AutoGPT 文档贡献指南：GitBook 同步机制、本地编辑与新增文档页面的完整流程

本文围绕 AutoGPT 仓库中 docs/content/contribute/index.md 的官方文档贡献说明展开，讲清楚 AutoGPT 文档「GitBook 托管 + GitHub 同步」的运作机制，覆盖本地克隆编辑、预览、新增页面并挂载到 SUMMARY.md 导航、以及提交 Pull Request 的完整实战流程。读完后，你可以独立完成一次 AutoGPT 文档的修改、新增页面并规范地提交 PR。

文档托管机制：GitBook 与 GitHub 双向同步

AutoGPT 的官方文档托管在 GitBook 上，并通过自动同步与 GitHub 仓库保持一致。根据 官方贡献文档，这套机制的三个关键事实是：

• 文档源码存放在仓库的 docs/ 目录中，位于 gitbook 分支上；
• GitBook 会自动从 GitHub 同步变更，无需手动发布操作；
• 修改入口有两种：直接在 GitHub 网页端编辑，或克隆到本地修改。

从仓库当前结构可以印证这一说法：docs/ 目录下除了 content/（对应 classic、forge、challenges 等历史文档内容）外，还包含 docs/home/README.md、docs/platform/ 与 docs/integrations/ 等子目录，各子目录均配有独立的 SUMMARY.md 导航文件，这正是 GitBook 以目录结构组织书籍（Book）的典型布局。

![AutoGPT 文档主页截图，展示 Platform、Integrations、Contribute 三大文档板块]

说明：仓库内并未附带文档站运行截图类资源，此处不插入图片；本文所有事实均以 docs/ 目录下的 Markdown 源文件为准。

本地编辑文档的完整步骤

官方文档给出的本地编辑流程分为四步，可完整复制执行：

1. 克隆仓库并切换到 gitbook 分支

git clone <AutoGPT 仓库地址>.git
cd AutoGPT
git checkout gitbook

注意 git checkout gitbook 这一步：文档源文件所在的不是默认分支，而是 gitbook 分支。如果直接在默认分支上修改 docs/，改动不会进入 GitBook 的同步链路。

2. 修改 docs/ 下的 Markdown 文件

对 docs/ 目录中任意 Markdown 文件进行修改即可。修改时建议遵循仓库内置的文档写作规范：

• docs/AGENTS.md 定义了「区块文档手册章节（Block Documentation Manual Sections）」的写法规范，适用于 docs/integrations/ 下带 <!-- MANUAL: ... --> 标记的区块文档：
  • How It Works 章节：用 1-2 段技术性描述说明区块处理逻辑，提及校验、错误处理与边界情况，必要时用反引号给出输入输出示例（如 [[1, 2], [3, 4]] 变为 [1, 2, 3, 4]）；
  • Use Case 章节：给出 3 个实用场景，格式为「加粗标题: 一句话描述」；
  • 风格要求：描述简洁、面向行动、聚焦真实场景、术语与其他区块保持一致、避免不必要的技术黑话。
• 根目录 CLAUDE.md 与 docs/CLAUDE.md 通过 @AGENTS.md 引用方式把上述规范接入 AI 辅助编辑链路，说明该规范在仓库内被当作正式约束使用。

3. 预览修改效果

官方文档提供两种预览方式：

• 推送分支并创建 PR——GitBook 会为 PR 生成预览版本；
• 本地使用任意 Markdown 预览工具查看。

4. 提交指向 gitbook 分支的 Pull Request

完成修改后，创建目标分支为 gitbook 的 Pull Request，维护者会审核后按需合并。

新增文档页面的三步操作

向文档站新增一个页面时，官方流程要求完成三个动作，缺一不可：

1. 在合适的 docs/ 子目录中创建新的 Markdown 文件；
2. 将新页面加入相应的 SUMMARY.md 文件，使其出现在导航中；
3. 向 gitbook 分支提交 Pull Request。

其中第 2 步是新手最容易遗漏的环节。GitBook 的书籍导航完全由 SUMMARY.md 驱动：一个 Markdown 文件即使存在于 docs/ 中，若没有出现在任何 SUMMARY.md 的目录树里，就不会在文档站的侧边导航中显示。仓库中现存三处导航文件可作为参考样例：

• docs/home/SUMMARY.md：最简形态，仅一行目录项，指向 docs/home/README.md（「Developer Platform」首页）；
• docs/platform/SUMMARY.md：Platform 文档板块的导航；
• docs/integrations/SUMMARY.md：集成（Integrations）文档板块的导航。

新增条目时，SUMMARY.md 中的链接是相对于该 SUMMARY.md 自身位置的局部相对路径（例如 docs/home/SUMMARY.md 中写的是 README.md）。编写新条目时保持同样的局部相对写法即可——这是 GitBook 源文件内部的规范，与对外发布文章时的根目录路径写法是两回事。

从 docs/home/README.md 的页面内容看，文档站首页以卡片形式组织了 AutoGPT Platform、Integrations、Contribute 三大入口，并附带 GitBook 专有的 frontmatter（cover、layout、pagination 等字段）与 {% columns %} 等 GitBook 宏语法。这说明文档源文件是「GitBook 风味」的 Markdown：普通 CommonMark 内容可以正常使用，但涉及页面布局时应遵循 GitBook 语法约定。

与代码贡献规范的衔接

文档贡献属于项目整体贡献流程的一部分，以下几点来自仓库根目录的配套文件，提交文档 PR 前值得了解：

• 总览：CONTRIBUTING.md 给出了项目贡献总原则——避免重复工作、大改动先开 Draft PR、提交前自测、不引入与个人偏好相关的无关改动等。需要特别留意的是其中的 CLA 说明：对 autogpt_platform 目录的贡献受 贡献者许可协议.md) 约束，其他目录（包括 docs/）的贡献则处于 MIT 许可之下。
• PR 模板：.github/PULL_REQUEST_TEMPLATE.md 要求所有 PR（文档 PR 同样适用）按「Why / What / How」结构说明背景、改动与实现方式，并附改动清单与测试计划清单。
• 代码属主：.github/CODEOWNERS 规定仓库默认由 @Significant-Gravitas/maintainers 团队审核，.github/workflows/ 归 devops 团队、classic/ 各子目录归各自维护团队——文档 PR 提交后会自动请求对应维护者审核。
• 配套写作规范：修改集成文档（如 docs/integrations/ 下的区块文档）时，务必对照 docs/AGENTS.md 的 MANUAL 章节格式，保持与自动生成/半自动维护内容的兼容性。

提交前自检清单

在发起指向 gitbook 分支的 PR 之前，建议按以下清单核对：

1. 改动发生在 gitbook 分支基线上，且只修改了 docs/ 下预期文件；
2. 新增页面已写入对应目录的 SUMMARY.md 导航，且链接为相对于该 SUMMARY.md 的局部路径、目标文件确实存在；
3. 图片等资源的引用路径与 GitBook 源文件位置匹配（仓库文档中资源引用形如 .gitbook/assets/xxx.png，需相对文档所在位置写对）；
4. 涉及 docs/integrations/ 区块文档时，MANUAL 章节格式符合 docs/AGENTS.md 规范；
5. PR 描述遵循 Why / What / How 模板 并列出全部改动文件。

满足以上条件后推送分支创建 PR，GitBook 即会基于 PR 生成预览，维护者审核通过后合并，文档变更随同步链路自动发布到线上文档站。