Agent Zero DOX 工作流全解析：从 Source Anchors 到收尾验证的文档契约维护指南

导读

在 Agent Zero 中，AGENTS.md 不是普通的说明文件，而是一套与目录树绑定的“文档契约（DOX）”。本文以 dox-workflow.md 为骨架，完整拆解 Agent Zero 的 DOX 编辑流程：如何沿 AGENTS.md 链定位局部契约、何时必须更新文档、api/、tools/、helpers/ 目录的文件级 *.py.dox.md 要求，以及每次变更后的 Closeout 收尾与验证清单。读完本文，你将掌握在 Agent Zero 仓库中安全修改代码并同步维护文档契约的完整方法，以及如何用 git diff --check、定向 pytest、Shell 覆盖检查等手段验证 DOX 的完整性。

一、DOX 是什么：Agent Zero 的文档契约体系

DOX（Documentation eXchange，文档契约）是 Agent Zero 内部对“源码变更与文档维护必须同步”这一工程规则的总称。其核心思想是：每个目录树节点都由最近的 AGENTS.md 文件声明所有权、责任、局部契约和验证方式，改动代码时必须同步更新这些契约文档，否则变更视为不完整。

从仓库根目录的 AGENTS.md 可以看到这套体系的顶层设计：

• 根 AGENTS.md 拥有项目级工程规则和顶层 DOX 索引（Child DOX Index），其中以表格形式登记了 .github/、agents/、api/、conf/、docker/、docs/、extensions/、helpers/、knowledge/、lib/、plugins/、prompts/、scripts/、skills/、tests/、tools/、webui/ 等 17 个直接子目录契约的职责范围；
• 详细契约“下放”到距离代码最近的子 AGENTS.md，根文档只保留跨树规则；
• usr/、tmp/、.venv/、.pytest_cache/ 等本地或生成目录被明确标记为“不纳入 DOX 索引”，避免把个人运行状态混入仓库契约。

这套层级结构在源码中同样可验证：api/、tools/、helpers/ 三个目录的 AGENTS.md 都声明自己是 file-documented DOX profile（文件级文档契约目录），要求目录内每个直接 *.py 文件都必须有同名 .dox.md 陪伴文件。

二、Source Anchors：DOX 契约的锚点地图

在动手修改任何代码之前，dox-workflow.md 要求先建立“锚点地图”，即确认当前改动涉及哪些 DOX 契约文件。以 a0-development 技能为例，其完整的锚点链为：

层级	锚点文件	作用
根 DOX 契约	AGENTS.md	项目级工程规则与顶层索引
技能父契约	skills/AGENTS.md	Bundled Skills 的加载与维护规则
本地技能契约	skills/a0-development/AGENTS.md	开发技能自身的职责与参考文件地图
参考文件契约	skills/a0-development/references/AGENTS.md	按需加载的源码锚定参考文件所有权
文件级 DOX 示例	api/health.py.dox.md、tools/notify_user.py.dox.md、helpers/api.py.dox.md	文件级契约的实际书写范例

以 tools/notify_user.py.dox.md 为例，一份合格的文件级 DOX 必须包含六个部分：Purpose（模块职责）、Ownership（实现与文档的所有权划分，以及公开类清单，如 NotifyUserTool 及其 async execute(**kwargs) 方法）、Runtime Contracts（运行时契约，如“工具模块必须继承 helpers.tool.Tool 并从 execute(...) 返回 helpers.tool.Response”）、Key Concepts（源码中观察到的关键依赖，如 AgentContext.get_notification_manager、Response、NotificationType）、Work Guidance（维护提示）和 Verification（关联测试）。

三、Before Editing：编辑前的契约行走规则

dox-workflow.md 给出了编辑前的 7 步强制流程，核心原则是“不依赖记忆，重新读取当前文件”：

1. 先读根 AGENTS.md，掌握项目级规则；
2. 列出所有预期会触碰的路径；
3. 从仓库根目录向每个目标路径逐层“行走”；
4. 读取路径上遇到的每一个 AGENTS.md；
5. 若某个父级 AGENTS.md 的子索引中列出其职责覆盖当前路径的子契约，则继续读取该子契约；
6. 以最近的 AGENTS.md 作为局部契约，父级文档仍然适用；
7. 若文档相互冲突，距离更近的文档控制局部细节，但任何子文档都不得削弱 DOX 本身。

这条规则在根 AGENTS.md 的 DOX Workflow 一节中得到印证：“The closest contract controls local details without weakening parent rules”（最近的契约控制局部细节，但不得削弱父级规则）。从源码结构看，这种设计的目的在于：当变更涉及 helpers/ 或 api/ 这类跨模块共享代码时，单一契约无法覆盖全部影响面，必须沿路径链确认每个层级的所有者都有机会同步其文档。

四、When To Update DOX：什么变更必须更新文档

并非每次代码修改都要改文档。dox-workflow.md 明确规定，当变更有意义地影响以下任一维度时，必须更新最近的拥有者 AGENTS.md：

• 目的、所有权、责任或职责范围发生变化；
• 持久化结构：目录、文件契约或子索引发生变化；
• 运行时行为：必需的输入/输出、副作用或验证规则发生变化；
• 用户或 Agent 的工作流规则发生变化；
• 创建、删除、重命名或移动某个 AGENTS.md 文件本身。

同时还有两条明确的边界规则：

• 不影响契约的小型实现级修改可以不改 DOX，但仍须执行 Closeout 检查，并在收尾报告中说明文档为何保持不变；
• 禁止在受忽略的 usr/ 或 tmp/ 下创建或更新 DOX，除非被显式要求（这与根 AGENTS.md 中“运行时或用户状态故意不纳入跟踪 DOX”的约定一致）。

五、File-Level DOX：三个目录的文件级契约硬性要求

Agent Zero 对特定目录实施“文件级 DOX 覆盖”，dox-workflow.md 用表格明确了强制范围：

目录	强制要求
api/	每个直接 *.py 端点或 ws_*.py 模块必须有同名 *.py.dox.md
tools/	每个直接 *.py 工具模块必须有同名 *.py.dox.md
helpers/	大量辅助模块使用文件级 DOX，修改辅助行为前先读 helpers/AGENTS.md

命名约定：文件级 DOX 的文件名 = 完整 Python 文件名 + .dox.md 后缀。例如 api/health.py 的契约文件是 api/health.py.dox.md，tools/notify_user.py 对应 tools/notify_user.py.dox.md。

当你新增、删除、重命名或行为性修改上述目录中的任一文件时，必须在同一次变更中更新其陪伴 DOX。 这条契约在 tools/AGENTS.md 和 helpers/AGENTS.md 中有完整的展开：

• 工具 DOX 拥有“工具目的、工具参数/概念、输出与 break_loop 行为、副作用、重要辅助依赖、提示词契约备注和验证指引”；
• 辅助模块 DOX 拥有“辅助目的、公开类/函数、跨模块契约、持久化或副作用、路径/安全假设、重要依赖和验证指引”；
• 删除或重命名文件后不得遗留过期 DOX。

以 api/health.py.dox.md 为实例，可以看到文件级 DOX 如何记录真实契约：HealthCheck 继承 helpers.api.ApiHandler，实现 requires_auth、requires_csrf、get_methods 与 async process(...)；其 Runtime Contracts 明确要求“HTTP 处理器必须派生自 helpers.api.ApiHandler，WebSocket 处理器必须派生自 helpers.ws.WsHandler”，并注明请求负载、认证/CSRF 要求、响应形状、路由副作用等变化都必须同步更新本文件。

六、Closeout：每次变更后的收尾清单

dox-workflow.md 定义了 6 步 Closeout（收尾）流程，确保任何改动都不会留下“代码与文档脱节”的债务：

1. 重新核对变更路径与 DOX 链是否仍然匹配；
2. 更新最近的拥有者文档以及受影响的父级或子级文档；
3. 刷新受影响的 Child DOX Index 表格（根 AGENTS.md 的 17 行子索引表、skills/AGENTS.md 的技能索引表都是这类表格的实例）；
4. 删除过期或矛盾的文本，而不是用大段文字解释旧历史；
5. 运行最近 DOX 指定的相关验证；
6. 报告有意保持不变的文档及其原因。

其中“刷新索引表”是一个容易被忽略的细节：每当新增/删除一个子目录契约或参考文件，父级 AGENTS.md 中的 Child DOX Index 表格必须同步增删行。例如 skills/a0-development/AGENTS.md 的索引表登记了 references/AGENTS.md，而 skills/a0-development/references/AGENTS.md 进一步登记了 architecture-runtime.md、dox-workflow.md、tools.md、extensions.md、api-webui.md、agents-prompts-skills-projects.md、plugins-workflow.md 七个参考文件的各自所有权——这套逐层索引正是“最近的契约控制局部细节”的落地载体。

七、Practical Verification：可执行的验证手段

dox-workflow.md 给出了四类实操验证手段，覆盖从静态检查到运行时验证的完整层次：

1. git diff --check：检查空白字符（尾随空格、缺行尾换行符等）问题，属于最快速的静态防线；
2. 定向测试：运行相关 DOX 文件点名的测试文件。以 tools/notify_user.py.dox.md 为例，其 Verification 节点名的关联测试是 tests/test_tool_action_contracts.py；tests/AGENTS.md 也明确了运行方式：大范围改动用 pytest，窄范围改动用 pytest tests/test_name.py 并在收尾时说明更广的测试缺口；
3. 手动通读：针对技能/参考文件链接的变更，手动检查相对引用是否失效（这与 skills/AGENTS.md 中“手动阅读变更的 SKILL.md 以检查损坏的相对引用”的验证规则一致）；
4. Shell 覆盖检查：当触碰 api/ 或 tools/ 时，用脚本/循环验证每个 *.py 都存在同名 *.py.dox.md。这一点在 tools/AGENTS.md 和 helpers/AGENTS.md 中被明确表述为“用脚本或 Shell 循环检查文件级文档覆盖”，例如：

   # 以 tools/ 为例的覆盖检查思路
   for f in tools/*.py; do
     test -f "$f.dox.md" || echo "MISSING DOX: $f.dox.md"
   done
   

5. 运行时或容器验证：当用户询问正在运行的 Dockerized 系统时，应对该确切运行环境做运行时/活容器验证，而不是假设固定的 localhost 端口——这与根 AGENTS.md 中“显式命名目标时验证精确运行时”的项目级契约一致。

八、DOX 变更的完整落地流程（综合示例）

将上述规则串起来，一次符合规范的 DOX 变更流程如下：

1. 阅读 AGENTS.md，确认变更属于哪些根所有权范围（如 agent.py 归 Agent、models.py 归模型提供方配置）；
2. 沿路径链读取所有相关 AGENTS.md（例如改动 api/ 下文件时读 api/AGENTS.md，改动 tools/ 下文件时读 tools/AGENTS.md）；
3. 判断变更是否触及“目的/所有权、持久化结构、运行时行为、工作流规则、AGENTS.md 文件本身”五类触发条件；
4. 若属于 api/、tools/、helpers/ 的直接文件，在同一次变更中同步更新同名 *.py.dox.md；
5. 更新最近拥有者的契约文档，并刷新各级 Child DOX Index 表格；
6. 执行 Closeout 六步检查，运行 git diff --check、定向 pytest、Shell 覆盖检查等验证；
7. 在变更说明中报告有意保持不变的文档及原因。

总结

Agent Zero 的 DOX 工作流本质上是一套**“以最近契约为准、逐层索引、变更必同步、收尾必验证”**的工程纪律。它通过根级索引、子目录契约、文件级 *.py.dox.md 三层结构，把“文档跟随代码”从口号变成可检查、可验证的强制规则。对任何在 Agent Zero 仓库中做扩展开发的开发者而言，掌握 dox-workflow.md 中的 Source Anchors 定位、Before Editing 行走规则、Closeout 收尾清单与 Practical Verification 手段，就能在保持代码库文档一致性的同时，安全地推进自己的改动。