Agent Zero 工程契约体系解析：以 AGENTS.md 为核心的分层 DOX 文档架构

Agent Zero 是一个面向"完整 Linux 计算机"的开放 Agent 框架，其仓库根目录的 AGENTS.md 并不只是一份写给 AI 助手的说明，而是一份项目级的工程契约（binding contract）与 DOX（Developer Operations eXchange）顶层索引。本文以该文件为主体，结合仓库源码，逐条拆解其 Purpose、Root Ownership、Project-Wide Contracts、Permissions、DOX Workflow 与 Child DOX Index，帮助你理解如何在 Agent Zero 这样的大型 Agent 框架中，用分层文档把架构决策、边界与验证方式固化下来，并能在自己的 Agent 项目中直接复用这套方法论。

一、什么是 DOX：AGENTS.md 文件体系的设计意图

根目录 AGENTS.md 开篇就明确了自身定位：

• Own project-wide engineering rules and the top-level DOX index.（负责项目级工程规则与顶层 DOX 索引。）
• Keep detailed contracts in the closest applicable child AGENTS.md.（把细粒度契约放到距离目标最近的子级 AGENTS.md 中。）

也就是说，根目录文件是"总纲"，只承载跨越整个仓库的规则；具体某个子目录的归属、工作流、输入输出与验证方式，则下沉到该目录自己的 AGENTS.md。仓库中几乎所有关键目录都遵循这一约定，例如 agents/AGENTS.md（Agent 配置文件与提示词）、api/AGENTS.md（HTTP API 与 WebSocket 入口）、plugins/AGENTS.md（内置插件与自定义插件架构契约）、helpers/AGENTS.md（共享后端工具）等。

这种"就近契约"（closest contract）原则的核心收益是：修改某个子目录时，只需阅读该目录的 AGENTS.md 与路径上的父级文件，就能掌握全部约束，而不必通读整个仓库。

二、项目技术栈与入口（Project）

AGENTS.md 用寥寥几行锁定了项目的关键技术事实，避免"假设一个端口、假设一种运行时"的常见误区：

• 技术栈：Python 3.12+ 框架、Python 3.13 Agent 执行运行时、Flask、Alpine.js、LiteLLM 与 Socket.IO。
• 启动 WebUI：python run_ui.py；不要假设固定端口，应从启动输出、Docker 端口映射或显式配置中发现其 URL。
• 运行测试：pytest 运行全部测试，或 pytest tests/test_name.py 运行单个文件。
• 面向人的文档：位于 README.md 与 docs/ 下。

这些约束与源码一一对应。例如 run_ui.py 中，主机名取自命令行参数 --host、环境变量 WEB_UI_HOST，最终回退到 localhost；端口则由 runtime.get_web_ui_port() 决定，这正解释了"不要假定端口"的契约来源。启动流程也印证了文件所述的技术栈：run_ui.py 通过 initialize.initialize_chats()、initialize_mcp()、initialize_job_loop()、initialize_preload() 完成组件初始化，最终由 run_uvicorn_with_retries 以 ws="wsproto" 启动 ASGI 服务，为 Socket.IO/WebSocket 通信提供底层支持。

三、根文件所有权划分（Root Ownership）

AGENTS.md 明确了哪些根级文件归谁管，这是代码审查与重构时判断"该不该动它"的第一依据：

文件/路径	所有权范围
agent.py	拥有 Agent、AgentContext 以及消息循环数据
initialize.py	拥有框架初始化逻辑
models.py	拥有模型提供方配置与 LiteLLM 集成
run_ui.py	WebUI 入口
DockerfileLocal	必须与 docker/ 下的契约保持兼容
usr/、tmp/	运行时/用户状态，默认不纳入 DOX 文档化范围

这条契约直接映射到代码结构：AgentContext 与 AgentContextType 定义在 agent.py，Agent 类定义在 agent.py；框架初始化函数（initialize_agent、initialize_chats、initialize_mcp、initialize_job_loop、initialize_preload、initialize_migration）全部集中在 initialize.py；LiteLLM 全局参数归一化（如 drop_params、字符串到布尔/整数的类型转换）则位于 models.py。

四、项目级契约详解（Project-Wide Contracts）

根 AGENTS.md 将"跨越整个仓库"的硬性规则集中在一节，它们是理解 Agent Zero 内部机制的关键：

1. 导入路径契约

Import AgentContext and AgentContextType from agent, not helpers.context.

AgentContext 是核心运行时类型，必须从 agent.py 导入，而不是从 helpers.context（那是上下文数据存储辅助模块）导入。这避免了同一类型的两套入口造成的循环依赖与语义分裂。

2. 安全与保密契约

• 永不提交 secrets、.env 文件、API key、token 或私有用户数据；
• 必须保留认证与 CSRF 防护。仓库中 tests/test_http_auth_csrf.py、tests/test_csrf_tunnel_origins.py 等测试即是对该契约的回归守护。

3. 消息循环的完成路径（break_loop 机制）

Message-loop completion flows through a response tool with break_loop; plain or malformed Chat Completions text enters repair, and native Responses output text is normalized through the same response-tool path.

这是 Agent Zero 消息循环的核心契约：循环的结束必须经由带 break_loop 标志的响应工具。break_loop 定义在 helpers/tool.py 的 Response 数据类中（message、break_loop、additional 三个字段）。落地实现是 tools/response.py：ResponseTool.execute 要求顶层 text 或 message 参数为非空字符串，否则抛出 RepairableException 进入修复流程；只有非空文本才会以 Response(message=message, break_loop=True) 结束循环。而 agent.py 的 monologue 内层 while True 循环正是依靠响应工具的 break_loop 才能正常退出——这也解释了为什么"裸文本或畸形 Chat Completions 文本会进入修复"：它们无法产生合法的 response-tool 调用。

4. 提示词中 JSON fence 的处理

Prompt Markdown may retain fenced JSON examples for readability; final system-prompt rendering removes only their JSON fence markers before model calls and preserves non-JSON fences.

即：提示词 Markdown 里可以保留 JSON 代码围栏（fenced block）以提升可读性；但最终渲染 system prompt 发给模型前，只移除 JSON 围栏标记本身，其他语言的代码围栏保留。这是一条非常实用的"人可读、模型也干净"的工程细节。

5. 插件代码的同步与放置位置

• 将线上核心插件的改动回写到跟踪源码 plugins/ 下；
• 新开发的自定义插件放在被忽略的 usr/plugins/ 下，随产品发布的捆绑插件才放 plugins/；
• 后端与插件钩子的验证应使用框架运行时，而不是独立的 agent 执行运行时。

五、权限边界（Permissions）

AGENTS.md 明确划分了"无需询问即可执行"与"必须事先询问"的操作：

允许（无需询问）：

• 读取仓库文件；
• 更新 usr/ 下的文件。

必须询问：

• 安装依赖；
• 删除 usr/ 或 tmp/ 之外的核心文件；
• 修改 agent.py 或 initialize.py；
• 创建 commit 或推送分支。

这条契约与 Root Ownership 一脉相承：agent.py、initialize.py 是框架的心脏，任何改动都需显式授权；而 usr/ 被设计为可安全写入的用户态区域。

六、DOX 工作流：如何正确维护这套契约

AGENTS.md 对"如何写 AGENTS.md"也给出了可操作的工作流：

1. AGENTS.md 是其子树的有约束力契约（binding contracts for their subtrees）。
2. 编辑前阅读：先读本文件与目标路径上的每一个 AGENTS.md；距离最近的契约在细节上优先，但不能削弱父级规则（"the closest contract controls local details without weakening parent rules"）。
3. 层级分工：项目级规则放根文件；具体归属、工作流、输入、输出、副作用与验证放子文档。
4. 何时新建子 AGENTS.md：仅在存在"具有独立所有权或工作流的持久边界"时才创建。
5. 子文档推荐结构：Purpose（目的）、Ownership（所有权）、Local Contracts（本地契约）、Work Guidance（工作指引）、Verification（验证）、Child DOX Index（子 DOX 索引）。
6. 每次有意义变更后：复查受影响的路径、更新最近的所有权文档与索引、删除过期指引、运行相关验证。
7. 不记录被忽略的 usr/、tmp/ 变更，除非被明确要求。
8. 保持 DOX 简洁、当前、可操作，避免日记式记录或重复父级指导。

以 agents/AGENTS.md 为例，可以看到这一模板的完整落地：它包含 Purpose（拥有捆绑 Agent 档案与档案本地提示词）、Ownership（每个档案目录拥有自己的 agent.yaml、可选 prompts/、tools/、extensions/）、Local Contracts（agent.yaml 必须是合法 YAML；档案提示词覆盖应窄且命名匹配核心提示词）、Work Guidance、Verification（运行 pytest 验证档案加载）以及 Child DOX Index（_example、agent0、default、developer、hacker、researcher、tiny-local 七个档案）。plugins/AGENTS.md 则展示了更庞大的子树契约，涵盖插件清单字段（name、title、description、version、settings_sections、per_project_config、per_agent_config、always_enabled）、插件路由约定（GET /plugins/<name>/<path>、POST /api/plugins/<name>/<handler>）、导入约定（捆绑插件用 plugins.<plugin_name>...，用户插件用 usr.plugins.<plugin_name>...）以及 26 个捆绑插件的索引。

七、Child DOX Index：全仓库的导航地图

根 AGENTS.md 末尾用两张表给出了全仓库的 DOX 导航。第一张是索引表，列出各子目录的 AGENTS.md 及其管辖范围：

子文档	管辖范围
.github/AGENTS.md	GitHub Actions 工作流与发布自动化脚本（存在于仓库中）
agents/AGENTS.md	捆绑 Agent 档案、档案本地提示词与工具
api/AGENTS.md	HTTP API 与 WebSocket 处理器入口
conf/AGENTS.md	随仓库发布的配置默认值与模板
docker/AGENTS.md	Docker 构建上下文、镜像、compose 文件与运行时布局
docs/AGENTS.md	面向人的文档与截图
extensions/AGENTS.md	后端与 WebUI 生命周期扩展
helpers/AGENTS.md	共享后端工具与运行时服务
knowledge/AGENTS.md	内置 Agent 自我知识
lib/AGENTS.md	WebUI 包之外的轻量浏览器侧辅助
plugins/AGENTS.md	捆绑系统插件与自定义插件架构
prompts/AGENTS.md	核心提示词模板
scripts/AGENTS.md	仓库维护脚本与自动化输入
skills/AGENTS.md	捆绑的 Agent Zero 技能
tests/AGENTS.md	Pytest 回归与契约测试
tools/AGENTS.md	核心 Agent 工具实现
webui/AGENTS.md	Alpine.js WebUI 外壳、组件、JavaScript、CSS 与资源

第二张是有意不索引的本地/生成根目录清单，并给出理由：

路径	不索引原因
.conda/、.venv/	本地 Python 环境
.pytest_cache/、__pycache__/	生成的测试与字节码缓存
.vscode/、.windsurf/	编辑器本地配置与助手元数据
tmp/	被忽略的运行时缓存、上传与生成产物
usr/	被忽略的本地用户数据、设置、插件、聊天记录与工作目录
python/	生成或遗留的运行时镜像；当前源码位于根模块与受跟踪源码目录

这种"显式排除"同样是 DOX 工程的关键纪律：明确标注哪些路径不在契约管辖内，可以避免文档漂移（doc drift）与对用户态数据的误操作。

八、这套契约体系的实战启示

回到根 AGENTS.md 本身，它展示了一个可迁移的"大型 Agent 框架文档治理"模式：

1. 根文件只放全局规则：技术栈、入口命令、所有权划分、全局契约、权限边界、DOX 工作流、子索引——每一节都短小精悍，可被 AI 助手快速解析。
2. 契约下沉到子树：任何具体细节（如 tools/AGENTS.md 中"返回 helpers.tool.Response(message=..., break_loop=...)"的工具约定、plugins/AGENTS.md 中的插件清单与路由契约）都存放在距离实现最近的子文档中。
3. 所有权与权限显式化：谁拥有 agent.py、谁可以动 initialize.py、usr/ 可以自由写——这些边界在代码协作与 AI 代工场景下能显著降低误改风险。
4. 验证闭环：每次变更后重新检查受影响路径、更新文档索引、运行 pytest（如 tests/test_ws_handlers.py、tests/test_skills_cli.py 等契约测试），确保文档与实现不脱节。

对于想要为自己的 Agent 项目建立工程纪律的开发者而言，根 AGENTS.md 是一份可直接参考的范本：以"Purpose → Ownership → Contracts → Permissions → Workflow → Index"为骨架，配合"就近契约优先、变更后即时验证"的工作流，即可把架构决策固化为机器可读、人类可维护的工程文档体系。