Agent Zero DOX 工作流全解析从 Source Anchors 到收尾验证的文档契约维护指南【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero导读在 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 的文档契约体系DOXDocumentation 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 AnchorsDOX 契约的锚点地图在动手修改任何代码之前dox-workflow.md要求先建立“锚点地图”即确认当前改动涉及哪些 DOX 契约文件。以 a0-development 技能为例其完整的锚点链为层级锚点文件作用根 DOX 契约AGENTS.md项目级工程规则与顶层索引技能父契约skills/AGENTS.mdBundled 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 步强制流程核心原则是“不依赖记忆重新读取当前文件”先读根AGENTS.md掌握项目级规则列出所有预期会触碰的路径从仓库根目录向每个目标路径逐层“行走”读取路径上遇到的每一个AGENTS.md若某个父级AGENTS.md的子索引中列出其职责覆盖当前路径的子契约则继续读取该子契约以最近的AGENTS.md作为局部契约父级文档仍然适用若文档相互冲突距离更近的文档控制局部细节但任何子文档都不得削弱 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.mdtools/每个直接*.py工具模块必须有同名*.py.dox.mdhelpers/大量辅助模块使用文件级 DOX修改辅助行为前先读 helpers/AGENTS.md命名约定文件级 DOX 的文件名 完整 Python 文件名 .dox.md后缀。例如api/health.py的契约文件是api/health.py.dox.mdtools/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.ApiHandlerWebSocket 处理器必须派生自helpers.ws.WsHandler”并注明请求负载、认证/CSRF 要求、响应形状、路由副作用等变化都必须同步更新本文件。六、Closeout每次变更后的收尾清单dox-workflow.md定义了 6 步 Closeout收尾流程确保任何改动都不会留下“代码与文档脱节”的债务重新核对变更路径与 DOX 链是否仍然匹配更新最近的拥有者文档以及受影响的父级或子级文档刷新受影响的 Child DOX Index 表格根 AGENTS.md 的 17 行子索引表、skills/AGENTS.md 的技能索引表都是这类表格的实例删除过期或矛盾的文本而不是用大段文字解释旧历史运行最近 DOX 指定的相关验证报告有意保持不变的文档及其原因。其中“刷新索引表”是一个容易被忽略的细节每当新增/删除一个子目录契约或参考文件父级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给出了四类实操验证手段覆盖从静态检查到运行时验证的完整层次git diff --check检查空白字符尾随空格、缺行尾换行符等问题属于最快速的静态防线定向测试运行相关 DOX 文件点名的测试文件。以 tools/notify_user.py.dox.md 为例其 Verification 节点名的关联测试是tests/test_tool_action_contracts.pytests/AGENTS.md 也明确了运行方式大范围改动用pytest窄范围改动用pytest tests/test_name.py并在收尾时说明更广的测试缺口手动通读针对技能/参考文件链接的变更手动检查相对引用是否失效这与 skills/AGENTS.md 中“手动阅读变更的SKILL.md以检查损坏的相对引用”的验证规则一致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运行时或容器验证当用户询问正在运行的 Dockerized 系统时应对该确切运行环境做运行时/活容器验证而不是假设固定的 localhost 端口——这与根 AGENTS.md 中“显式命名目标时验证精确运行时”的项目级契约一致。八、DOX 变更的完整落地流程综合示例将上述规则串起来一次符合规范的 DOX 变更流程如下阅读 AGENTS.md确认变更属于哪些根所有权范围如agent.py归Agent、models.py归模型提供方配置沿路径链读取所有相关AGENTS.md例如改动api/下文件时读 api/AGENTS.md改动tools/下文件时读 tools/AGENTS.md判断变更是否触及“目的/所有权、持久化结构、运行时行为、工作流规则、AGENTS.md 文件本身”五类触发条件若属于api/、tools/、helpers/的直接文件在同一次变更中同步更新同名*.py.dox.md更新最近拥有者的契约文档并刷新各级 Child DOX Index 表格执行 Closeout 六步检查运行git diff --check、定向 pytest、Shell 覆盖检查等验证在变更说明中报告有意保持不变的文档及原因。总结Agent Zero 的 DOX 工作流本质上是一套**“以最近契约为准、逐层索引、变更必同步、收尾必验证”**的工程纪律。它通过根级索引、子目录契约、文件级*.py.dox.md三层结构把“文档跟随代码”从口号变成可检查、可验证的强制规则。对任何在 Agent Zero 仓库中做扩展开发的开发者而言掌握 dox-workflow.md 中的 Source Anchors 定位、Before Editing 行走规则、Closeout 收尾清单与 Practical Verification 手段就能在保持代码库文档一致性的同时安全地推进自己的改动。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考