AI 原生开放教材

外观

大模型应用开发 -上下文工程与运行空间实践指南工程手册·中文原文 ↗原件 ↓仓库 ↗

贡献指南 ​

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

📋 目录 ​

项目结构 ​

本项目是一个基于 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
  1. 安装依赖：
bash
pnpm install
  1. 本地预览：
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）的注册与调度
  - [工具管理](/lib/10-context-memory/practical-guide-context-engineering/docs-工具管理模块-工具管理) ✅
  - [你的文章标题](./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 模板

8.3 提交并等待审核 ​

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

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

文章编写规范 ​

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

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

VitePress 配置说明 ​

配置文件位置 ​

docs/.vitepress/config.js

提交规范 ​

我们遵循 Conventional Commits 规范：

提交类型 ​

  • 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

Closes #

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

## 截图（可选）

注意事项 ​

内容质量 ​

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

文件管理 ​

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

协作礼仪 ​

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

行为准则 ​

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

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

版权声明 ​

贡献内容将遵循项目的 CC BY-NC-SA 4.0 许可协议。

感谢你的贡献！ 🎉

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