# 贡献指南

感谢你对「上下文工程实践指南」项目的关注！我们欢迎所有形式的贡献，无论是修复错误、完善内容、还是分享你的实践经验。

## 📋 目录

- [项目结构](#项目结构)
- [贡献类型](#贡献类型)
- [开始之前](#开始之前)
- [贡献流程](#贡献流程)
- [文章编写规范](#文章编写规范)
- [VitePress 配置说明](#vitepress-配置说明)
- [提交规范](#提交规范)
- [注意事项](#注意事项)

## 项目结构

本项目是一个基于 VitePress 构建的文档项目，采用三层目录结构：

### 目录层级说明

#### 第一层：部分（Part）
项目分为六大部分：
- 前言
- 第一部分：上下文工程基础技术
- 第二部分：上下文组成工程实践
- 第三部分：上下文管理
- 第四部分：Agent架构设计
- 第五部分：Agent评估
- 第六部分：上下文工程实践项目

#### 第二层：章节（Chapter）
每个部分下包含若干章节，例如：
- 第一章 数据持久化
- 第二章 向量存储和嵌入模型
- 第六章 工具管理模块

#### 第三层：文章/主题（Article/Topic）
根据内容复杂度决定：
- **章节即文章**：内容聚焦单一主题时，章节本身就是一篇文章（如：搜索代理）
- **章节包含多篇文章**：内容复杂且包含多个子主题时，章节下会包含多篇文章（如：工具管理模块）

### 文件组织结构

```
docs/
├── 搜索代理/
│   └── 搜索代理.md                    # 单一文章型章节
├── 工具管理模块/
│   ├── 工具管理.md                    # 多文章型章节
│   ├── ClaudeCode逆向工程（Kode）的工具定义和管理 -TS版本.md
│   ├── 模型调用工具能力评估.md
│   ├── MCP与MCP的安全.md
│   └── image/                         # 图片资源文件夹
│       ├── diagram-1.png
│       └── screenshot-2.png
└── ...
```

## 贡献类型

我们欢迎以下类型的贡献：

### 1. 内容贡献
- ✍️ **撰写新文章**：在现有章节下添加新的文章
- 📝 **完善现有内容**：改进文章质量、修正错误、补充案例
- 🖼️ **添加图表**：提供更好的可视化说明

### 2. 问题反馈
- 🐛 **报告错误**：发现内容错误、代码问题或格式问题
- 💡 **提出建议**：对项目结构、内容组织的改进建议

### 3. 技术改进
- ⚙️ **优化配置**：改进 VitePress 配置
- 🎨 **改善样式**：提升阅读体验

## 开始之前

### 环境准备

1. **Fork 本仓库**到你的 GitHub 账号
2. **Clone 到本地**：
```bash
git clone https://github.com/你的用户名/Practical-Guide-to-Context-Engineering.git
cd Practical-Guide-to-Context-Engineering
```

3. **安装依赖**：
```bash
pnpm install
```

4. **本地预览**：
```bash
pnpm run docs:dev
```

### 分支管理

- 主分支：`main`
- 创建功能分支：`git checkout -b feature/your-feature-name`
- 创建修复分支：`git checkout -b fix/your-fix-name`

## 贡献流程

### 步骤 1：选择或创建目录

根据你要贡献的内容，确定所属的章节：

- **现有章节**：直接在对应文件夹下添加文章
- **新建章节**：请先提 Issue 讨论，确认后再创建

### 步骤 2：添加文章

在相应的章节文件夹下创建 Markdown 文件：

```bash
# 示例：在工具管理模块下添加新文章
touch docs/工具管理模块/你的文章标题.md
```

**命名规范**：
- 使用中文文件名，语义清晰
- 避免特殊字符，可使用中文、英文、数字、连字符
- 示例：`工具调用的最佳实践.md`、`MCP协议详解.md`

### 步骤 3：添加图片资源

如果文章包含图片：

1. 在章节文件夹下创建 `image` 文件夹（如果不存在）
2. 将图片放入该文件夹
3. 在 Markdown 中使用相对路径引用

```bash
# 创建 image 文件夹
mkdir docs/工具管理模块/image

# 在 Markdown 中引用
![描述文字](./image/your-image.png)
```

**图片规范**：
- 格式：推荐使用 PNG、JPG、WebP
- 大小：单张图片不超过 2MB，过大的话可以使用 TinyPng：https://tinypng.com/进行压缩
- 命名：使用语义化命名，如 `tool-architecture.png`

### 步骤 4：更新 README.md

在 `README.md` 的对应章节下添加文章链接：

```markdown
- [第六章 工具管理模块](./docs/工具管理模块/)：工具（API、函数、MCP）的注册与调度
  - [工具管理](./docs/工具管理模块/工具管理.md) ✅
  - [你的文章标题](./docs/工具管理模块/你的文章标题.md) ✅
```

### 步骤 5：更新 VitePress 配置

编辑 `docs/.vitepress/config.js`，在 `sidebar` 中添加对应的导航项：

```javascript
{
  text: '第六章 工具管理模块',
  items: [
    { text: '工具管理', link: '/工具管理模块/工具管理' },
    { text: '你的文章标题', link: '/工具管理模块/你的文章标题' }  // 新增
  ]
}
```

**注意**：
- `link` 路径不需要 `.md` 后缀
- `link` 路径以 `/` 开头，基于 `docs` 目录
- 保持缩进格式一致

### 步骤 6：本地测试

在提交前，请务必在本地测试：

```bash
# 启动开发服务器
pnpm run docs:dev

# 构建测试
pnpm run docs:build
```

检查项：
- ✅ 文章能正常显示
- ✅ 导航链接正确
- ✅ 图片正常加载
- ✅ 没有构建错误

### 步骤 7：提交更改

```bash
# 添加更改
git add .

# 提交（遵循提交规范）
git commit -m "feat: 添加工具管理模块的最佳实践文章"

# 推送到你的 Fork
git push origin feature/your-feature-name
```

### 步骤 8：创建 Pull Request

#### 8.1 在 GitHub 上创建 PR

1. 在 GitHub 上打开**你 Fork 的仓库**
2. 点击 "Compare & pull request" 或 "New Pull Request" 按钮
3. 确认分支选择：
   - **Base repository**: `WakeUp-Jin/Practical-Guide-to-Context-Engineering`
   - **Base branch**: `main`
   - **Head repository**: `你的用户名/Practical-Guide-to-Context-Engineering`
   - **Compare branch**: `feature/your-feature-name`

#### 8.2 填写 PR 描述

在 PR 描述中详细说明您的贡献内容，包括：
- 改动类型（新增文章/修复错误/完善内容等）
- 具体改动说明
- 相关的 Issue 编号（如有）
- 检查清单确认

参考下方的 [Pull Request 模板](#pull-request-模板)

#### 8.3 提交并等待审核

1. 点击 "Create pull request" 提交 PR
2. 等待项目维护者审核
3. 根据 Review 意见进行修改（如需要）
4. 待审核通过后，维护者会合并您的 PR

**审核时间**：通常在 1-3 个工作日内会有反馈

## 文章编写规范

文章使用 **Markdown 格式**（.md 文件）编写即可，内容结构、写作风格不做强制约束。

欢迎发挥你的创意，用你习惯的方式分享知识和经验！

## VitePress 配置说明

### 配置文件位置

`docs/.vitepress/config.js`

## 提交规范

我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

### 提交类型

- `feat`: 新增功能/文章
- `fix`: 修复错误
- `docs`: 仅文档更新
- `style`: 格式调整（不影响代码逻辑）
- `refactor`: 重构
- `chore`: 构建/配置更新

### 提交格式

```
<类型>: <简短描述>

<详细描述（可选）>

<关联 Issue（可选）>
```

### 示例

```bash
# 添加新文章
git commit -m "feat: 添加工具管理最佳实践文章"

# 修复内容错误
git commit -m "fix: 修正 RAG 策略文章中的代码示例"

# 更新配置
git commit -m "chore: 更新 VitePress 侧边栏配置"

# 多行提交信息
git commit -m "feat: 添加 MCP 安全性分析文章

- 详细介绍 MCP 协议的安全机制
- 提供实际的安全配置示例
- 添加相关架构图

Closes #42"
```

## Pull Request 模板

创建 PR 时，请参考以下模板：

```markdown
## 改动类型
- [ ] 新增文章
- [ ] 完善现有内容
- [ ] 修复错误
- [ ] 配置/构建更新

## 改动说明
<!-- 简要描述你的改动 -->

## 改动内容
- 在 XX 章节下添加了 YY 文章
- 修正了 ZZ 文章中的错误
- 更新了相关配置文件

## 相关 Issue
<!-- 如果有关联 Issue，请注明 -->
Closes #

## 检查清单
- [ ] 已在本地测试，文章显示正常
- [ ] 已更新 README.md
- [ ] 已更新 VitePress 配置
- [ ] 图片已正确放置在 image 文件夹
- [ ] 遵循了提交规范
- [ ] 没有破坏现有内容

## 截图（可选）
<!-- 如果有界面变化，请提供截图 -->
```

## 注意事项

### 内容质量

- ✅ 确保内容准确、无误
- ✅ 引用来源时注明出处
- ✅ 避免抄袭，尊重版权

### 文件管理

- ✅ 图片统一放在对应章节的 `image` 文件夹
- ✅ 避免上传大文件（>2MB 的图片、视频等）
- ✅ 不要提交 `node_modules`、`.DS_Store` 等临时文件

### 协作礼仪

- ✅ 及时响应 Review 意见
- ✅ 保持友好、建设性的沟通
- ✅ 接受合理的修改建议
- ✅ 感谢其他贡献者的工作

## 获取帮助

如果在贡献过程中遇到问题：

1. **查看文档**：先查阅本贡献指南和 README
2. **搜索 Issue**：看是否有人遇到过类似问题
3. **提出 Issue**：描述你的问题，我们会尽快回复
4. **发起讨论**：可以向维护者邮箱发起讨论 2385472291@qq.com

## 行为准则

我们致力于为社区中的每个人创造一个友好、包容的环境。参与本项目即表示你同意遵守以下原则：

- 尊重不同的观点和经验
- 接受建设性的批评
- 专注于对社区最有利的事情
- 对其他社区成员表现出同理心

## 版权声明

贡献内容将遵循项目的 [CC BY-NC-SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/) 许可协议。

---

**感谢你的贡献！** 🎉

每一份贡献都让这个项目变得更好。如果你有任何疑问，欢迎随时联系我们。

- 项目维护者：[@WakeUp-Jin](https://github.com/WakeUp-Jin)
- 项目地址：[Practical-Guide-to-Context-Engineering](https://github.com/WakeUp-Jin/Practical-Guide-to-Context-Engineering)