mkdocs-for-agent main agent-workflow.md

AI Agent 工作流

这页说明 AI Agent 在 mkdocs-net 文档项目里应该如何阅读现有内容、生成新页面、补导航以及在交付前做自检。目标是让多次生成的结果保持同一套结构和标准。

写作要求

AI Agent 生成文档时应遵守以下要求：

  1. 先确认目标页面属于哪个目录，再写文件路径。
  2. 每页必须有明确的 H1，不要生成无标题碎片。
  3. 优先写用户能执行的步骤，不要先堆大量抽象背景。
  4. 标题尽量用“部署”“配置”“验证”这类任务导向文案。
  5. 链接、图片、文件名、命令都要与仓库结构一致。
  6. 不要写“待补充”“TODO”“以后再说”这类占位内容。
  7. 不要伪造页面、配置项、菜单路径和功能描述。
  8. 页面较长时，用 ##、### 切开逻辑块，让 TOC 可读。
  9. 生成 markdown project page 时，必须遵守三栏内容页规则： 无顶部、无底部、左导航固定、右 TOC 固定、只有中间正文滚动。

阅读顺序

AI Agent 阅读一套 mkdocs-net 文档时，建议按下面顺序理解：

  1. 先看入口页，例如 README.md。
  2. 再看 navmenu.md，理解站点的信息架构。
  3. 按标题层级阅读正文，识别章节语义边界。
  4. 沿着相对链接梳理跨页关系。
  5. 最后读取代码块、表格、配置片段，提取可执行信息。

阅读时要特别注意：

  • navmenu.md 代表导航意图，不一定等于内容详略。
  • 正文页代表具体说明，不一定覆盖全部入口。
  • 当导航与正文不完全一致时，应优先把导航理解为结构，再用正文补细节。

生成新文档的建议流程

  1. 确认这页是否真的需要新增，而不是补到现有页面。
  2. 确认它应该放在哪个目录。
  3. 判断它是否需要加入 navmenu.md。
  4. 先写 H1 和摘要，再写二级结构。
  5. 补至少一个上游入口页和一个相关页面链接。
  6. 检查相对路径、命令示例、配置片段是否真实可用。

给自己做的最终自检

  • 是否有明确页面目标。
  • 是否有清晰标题和摘要。
  • 是否使用了稳定的标题层级。
  • 是否使用相对链接表达站内关系。
  • 是否避免虚构路径和占位内容。
  • 是否让下一位 AI Agent 能直接继续维护这页。
  • 如果新增了页面，是否同步考虑 navmenu.md。
  • 是否没有把内容页写成带 header/footer 的官网式页面。

适合交给 AI Agent 的任务类型

  • 拆分过长页面。
  • 新增专题页并补站内链接。
  • 为现有页面补摘要、步骤和示例。
  • 为文档站新增导航文件。
  • 检查链接、标题层级和模板一致性。

不适合直接跳过检查的情况

  • 大量新增页面但没有导航方案。
  • 复制旧文档后没有核对路径。
  • 把列表树误当作 navmenu.md 层级结构。
  • 示例命令与当前仓库结构不一致。

相关页面