Agent Orchestrator 的 AGENTS.md 操作契约全解：从仓库布局到硬性边界的智能体协作指南

Agent Orchestrator 的 AGENTS.md 操作契约全解从仓库布局到硬性边界的智能体协作指南【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址: https://gitcode.com/gh_mirrors/ag/agent-orchestratorAgent Orchestrator 是一个从规划到合并全程编排并监督多个编码智能体的项目——它同时支持 Claude Code、Codex 等 25 种 harness并提供桌面、Web、移动与云端的统一界面。当仓库里同时有人类贡献者和**编码智能体coding agents**协作时如何让两者对哪些目录归谁、哪些命令必须跑、哪些规则绝对不能违反达成一致就成了工程治理的关键问题。本指南以仓库根目录的 AGENTS.md 为主体结合 package.json、docs/architecture.md、docs/cli/README.md、后端 Go 源码与前端 Electron 主进程实现逐条拆解这份智能体操作契约读完你将掌握该仓库的目录职责、本地校验命令矩阵、桌面 UI 评审的隔离实验流程、分发路径规则、Go 编码约定以及回环监听、LAN 监听、状态推导和~/.ao数据边界等硬性规则背后的设计与实现。AGENTS.md 的定位机器可读的契约层在写任何代码之前需要先理解这份文档在整个文档体系中的位置。docs/documentation-map.md 将仓库文档明确分为两层分层受众示例如何保持正确面向人类的文档贡献者、用户README.md、CONTRIBUTING.md、docs/人工评审散文描述代码可能滞后机器可读契约层编码智能体、CI、代码生成器openapi.yaml、AGENTS.md、skills/、sqlcgen/由源码生成或被 CI 漂移门禁检查规则很简单当契约层与人写文档冲突时以契约层为准——因为它要么由代码生成、要么被 CI 门禁守护。而 AGENTS.md 就是这个契约层中智能体操作契约的载体它规定了编码智能体在本仓库中工作时的仓库布局认知、命令清单、代码入口、编码约定、硬性规则与 PR 卫生要求。它本身是手写的、不受机器门禁直接检查但其命名的硬规则由测试强制执行例如回环路由限制、状态推导逻辑详见 docs/documentation-map.md 的契约层表格。配套地CLAUDE.md 是给 Claude Code 的兼容性指针全文只有三件事指向 AGENTS.md、强调应用状态只落在~/.ao、以及 UI 设计系统克隆 agent-orchestrator 的视觉风格。也就是说无论你用哪个 Agent 工具进入这个仓库最终都会回到 AGENTS.md 这份契约上。仓库布局一眼分清 Go 重写、Electron 前端与文档AGENTS.md 首先给出五层目录地图这是智能体形成什么改动该落在哪的认知基础backend/—— Agent Orchestrator 的Go 重写CobraaoCLI、回环 HTTP 守护进程、service、SQLite 存储、生命周期/reaper、runtime/workspace/agent/tracker 适配器、终端 mux 与测试。frontend/——Electron React监督界面通过生成的类型化客户端与守护进程通信。它被明确定位为薄监督层/UI 表面不允许把守护进程逻辑搬进前端。docs/—— 当前架构与状态笔记。改动生命周期、CLI、agents、存储或守护进程行为前必须先读这里。test/—— 外部冒烟/e2e 资产包括 CLI 全新安装的容器检查。.github/workflows/—— CI 定义本地尽量镜像执行同样的命令。这一布局背后是守护进程边界的架构意图aoCLI 是薄客户端通过回环 HTTP 与 daemon 通信绝不直接开 SQLite、绝不直接拉起 runtime。docs/cli/README.md 进一步点明ao start或打开桌面 App 后ao agent ls、ao spawn等产品命令都会走回环 daemon若running.json指向的进程不存活会直接报 daemon is not running。从源码入口看backend/cmd/ao/main.go 仅做一件事调用cli.Execute()出错时打印到 stderr 并以cli.ExitCode(err)退出——这正是CLI 是薄客户端的极简体现。命令矩阵仓库级校验的完整清单AGENTS.md 的 Commands 一节是智能体提交前必须本地执行的最小验证集。结合根目录 package.json 的 scripts 字段可以还原每个命令的真实底层实现npm run lint # backend go test ./... golangci-lint v2.12.2 npm run frontend:typecheck # frontend TypeScript check npm run sqlc # 重新生成 backend/internal/storage/sqlite/gen npm run api # 重新生成 OpenAPI spec frontend TS 类型 npx redwoodjs/agent-ci run --all # 本地工作流验证需要 Docker socket这些命令在 package.json 中的实际定义如下npm run lint→cd backend go test ./... go run github.com/golangci/golangci-lint/v2/cmd/golangci-lintv2.12.2 run --path-modeabs先跑全量 Go 测试再用锁定版本 v2.12.2的 golangci-lint 静态检查保证本地与 CI 用同一个 linter。npm run sqlc→cd backend go run github.com/sqlc-dev/sqlc/cmd/sqlcv1.31.1 generate从backend/internal/storage/sqlite/queries/*与 migrations 生成gen/代码同样锁版本 v1.31.1。npm run api→ 依次执行api:speccd backend go generate ./internal/httpd/apispec/...与api:tsnpx openapi-typescript7.4.4 backend/internal/httpd/apispec/openapi.yaml -o frontend/src/api/schema.ts。后端专用检查cd backend go build ./... go test ./... go test -race ./... go vet ./... go run ./cmd/ao start前端专用检查cd frontend npm run typecheck # 即 tsc --noEmit见 frontend/package.json npm run build还有一个容易被忽略的验收习惯展示或演示前端改动时必须在会话内运行ao preview [url]让改动渲染到桌面浏览面板inspector 侧栏的 Browser 标签页而不是口头描述。这条规则在 CLAUDE.md 中也被重复强调说明它是仓库对UI 改动必须眼见为实的硬性预期。Desktop Lab在隔离工作树里跑真实 Electron 应用对于需要真实 App而非ao preview或dev:web的视觉验收AGENTS.md 给出了严格的隔离实验流程。它的核心约束是绝不污染正在使用的工作树可能含有无关的未提交改动绝不触碰用户真实的~/.ao数据git worktree add /tmp/ao-lab branch # 待评审的 PR 分支 cd /tmp/ao-lab/frontend npm ci # 严禁 symlink 其他 checkout 的 node_modules npm run build:daemon -- --dev AO_DATA_DIR/tmp/ao-lab-data ./node_modules/.bin/electron-forge start文档专门记录了四类踩坑点这些都是真实事故的浓缩经验必须真实执行npm ci。symlink 另一个 checkout 的node_modules会让 React 从两个物理路径解析、并共享 Vite 优化器缓存症状是黑窗口 控制台报Invalid hook call/useSyncExternalStore还会把.vite/deps输出写进别人的工作树。用AO_DATA_DIR隔离数据。Lab 以空面板启动在里面创建一次性会话即可走通列表/详情流程Electron 的userData目录本就默认指向 dev 路径而非生产路径。用ELECTRON_ENABLE_LOGGING1诊断。绝大多数黑窗口的根因是 renderer 控制台错误开启后错误会落到启动器的 stdout。杀掉 forge 包装进程是不够的。Electron 主进程的 cmdline 只是Electron .所以pkill -f electron-forge之后 App 仍在运行、下一次启动会静默失败。必须显式杀掉Electron.app/.../MacOS/Electron主进程再重启。另外懒加载模块例如首次使用时动态 import 的mermaid的缺依赖警告不会导致黑窗口按信息性提示对待即可。先看哪里文档索引与代码入口定位AGENTS.md 给出了智能体首次进入仓库时的阅读顺序README.md —— 当前运行/配置/测试快速入门。docs/README.md —— 文档索引。docs/documentation-map.md —— 机器可读契约层的总览哪些构件是契约、各自是何种事实来源、CI 如何防止漂移。docs/architecture.md —— 后端心智模型、包布局、生命周期/会话/服务边界与承重规则。docs/STATUS.md —— 当前main上已发布什么、还有哪些在途。docs/cli/README.md —— 预期中的 CLI 形态薄 Cobra 客户端永远走 daemon HTTP。CLAUDE.md —— Claude Code 兼容性指针引导回到 AGENTS.md。代码入口定位表每个目录都在仓库中存在并可继续深入关注点位置CLI 命令backend/internal/cli/HTTP 控制器与 DTObackend/internal/httpd/controllers/服务读写边界backend/internal/service/领域词汇backend/internal/domain/端口契约backend/internal/ports/SQLite 查询/迁移/存储backend/internal/storage/sqlite/生成的 sqlc 代码backend/internal/storage/sqlite/gen/架构层面docs/architecture.md 给出的是OBSERVE → UPDATE → DERIVE三段式心智模型展示状态永不落库读取时由 service 层从持久事实activity_state、is_terminated、PR/check/comment 事实等实时推导。分发路径桌面 App 为正统npm 已冻结AGENTS.md 的 Distribution 一节对用户到底该从哪装 AO给出了明确的当代结论桌面 AppGitHub Releases是正统的、自动更新的安装路径应优先引导用户走这里。npm 仍可用但不再推荐。0.10.0是发布到 npm 的最终版本aoagents/ao包已冻结、不再更新仅作为老用户 PATH 上已有ao的遗留入口此时ao start会拉取并打开桌面构建。不要新增把 npm 当作正式安装方式的特性、文档或流程。只有唯一一个发布者。只有指定的发布负责人可以在任何 channel 执行真实发布——多个发布者的分叉产物曾导致 7 月 28–29 日的 macOS 事故难以解读。测试构建请走 fork 开发循环。完整规则与理由见 frontend/docs/desktop-release.md 的 Hard rule: exactly one publisher。macOS 产物必须用 frontend/scripts/verify-mac-artifact.sh 验证绝不手工。脚本用ditto -x -k解包并执行codesign --verify --deep --strict、spctl -a -vv -t exec、xcrun stapler validate。普通unzip会破坏签名封印从而产生极具迷惑性的假失败spctl不带-vv时成功时什么都不输出。macOS 同时发布.zip与.dmgdmg 只用于首次安装.zip和latest-mac.yml必须永久持续发布因为 electron-updater 无法从 dmg 安装更新。macOS 差分更新被永久禁用只走全量下载见 issue #3151 与 #3267 的决策。编码约定从退出码到测试风格的 Go 工程规范AGENTS.md 的 Coding conventions 逐条约束智能体的代码行为这些约定大都能在源码中找到直接对应实现改动小而精准外科手术式修改、直接服务于任务不做顺手的清理、大范围改名、格式扰动、投机性抽象或架构重构除非任务明确要求。遵守 Go 包边界CLI 代码应通过共享的 CLI 客户端辅助函数调用 daemon HTTP 路由不得直接打开 SQLite、spawn runtime 或直连适配器。Cobra 命令就近放、按表驱动测试风格对齐 backend/internal/cli/ 下的*_test.go。CLI 镜像 DTO 而非 import 控制器包除非该包已建立了这种依赖。用法错误返回usageError退出码 2runtime/daemon 失败退出码 1。这条规则在 backend/internal/cli/root.go 有直接实现usageError类型包裹错误ExitCode用errors.As判定命中则返回 2、其余失败返回 1、成功返回 0executeWithDeps还会在退出码为 2 时额外发射 CLI 用法错误遥测。仓库内大量命令如agent command is required、invalid session id、--timeout must be between 1 and N milliseconds等都以usageError{...}形式返回。在将 daemon 错误抛给用户时保留 API 错误信封与 request ID。做 I/O 或阻塞工作的函数context.Context作为第一个参数。不为一次性用例添加抽象只有当辅助函数能消除真实调用点的重复时才添加。测试覆盖用户可见行为与所改边界happy path、校验/缺参、daemon 错误信封以及任何破坏性确认路径。硬性边界Hard rules网络、状态与数据的红线这一节是 AGENTS.md 中智能体必须绝对遵守的部分也是与其他模块强耦合最多的地方。每条硬规则几乎都能在源码里找到对应的强制实现或测试。1. 回环监听器保持127.0.0.1且无认证daemon 的主回环监听器必须始终绑定127.0.0.1、不认证。不允许修改绑定主机或给它加认证。OpenAPI 生成的 spec 中 daemon 地址固定为http://127.0.0.1:3001见 backend/internal/httpd/apispec/specgen/build.go 中的 Server 描述 Local daemon (loopback only)安全模型是操作系统保证箱外无法触达因此不需要认证。2. 可选的 LAN 监听器仅在显式启用时、仅在认证之后daemon可以运行第二个可选 LAN 监听器即 Connect Mobile 功能绑定0.0.0.0仅在显式启用期间仅在 bearer 密码authMiddleware之后只服务 App API永不服务回环门禁的控制路由/shutdown、telemetry、mobile control。在 backend/internal/httpd/lan_listener.go 中可以确认lanControlBlock作为最外层包装先于authMiddleware对路径或其嵌套子路径命中控制前缀的请求直接返回 404假装路由从未挂载避免用 403/401 泄漏路径存在性。被封锁的前缀包括/shutdown /internal/ /api/v1/mobile /api/v1/dev /api/v1/browser /api/v1/desktop /api/v1/system/install /api/v1/agents/codex/accounts /api/v1/agents/codex/account-switches此外POST /api/v1/agents/*/install也被拦截且/api/v1/sessions/{id}/preview/server同样不可经 LAN 触达。原因在代码注释里写得很清楚共享路由里的localControlRequest信任客户端提供的Host头而该头可被任意 LAN 客户端伪造LAN 监听器是调用者唯一无法伪造的物理 socket所以封锁只能加在 LAN 侧、与任何 header 无关。恰好一条路由豁免authMiddlewareGET /api/v1/identity。它返回不透明的、安装绑定的 host id 与移动端契约版本用于让手机在出示凭据前先确认应答的是哪台机器——私网地址不等于身份192.168.1.42在大多数家庭/办公网络上都存在且在不同网络上指向不同设备。豁免有精确约束且各有测试精确路径匹配不是前缀——/api/v1/identity之下不继承豁免仅GET——对同一路径的写操作仍需密码在锁定检查之前判定——手机并发探测多个端点时不能被锁定且无凭据的探测不会因密码错误触发锁定。实现见 backend/internal/httpd/controllers/identity.goMobileAPIVersion 1控制器只挂GET /identity返回{hostId: ..., apiVersion: 1}。host id 持久化在~/.ao/mobile/identity.json属于该 AO 数据目录硬件指纹只作为诊断元数据保留、永不轮换 id——扩展坞、OS 网卡变化、更换唯一网卡都不应静默解绑所有手机。显式重置身份的方式是AO 停止时删除该文件下次启动签发新 id。完整权衡见 docs/adr/0003-unauthenticated-identity-probe.md 与 docs/adr/0001-lan-listener-for-mobile.md。3. CLI 是薄客户端、状态是推导的、runtime 探测不是死亡证明CLI 是薄客户端不移植旧的进程内 TypeScript CLI 行为来绕过 daemon HTTP 路由。不存储派生/展示状态会话状态在 service 读取时由持久事实activity_state、is_terminated、PR/check/comment 事实推导。不把失败/未知的 runtime 探测当作会话死亡的证据。不强制删除脏的已注册工作树。4. SQLite 与迁移纪律不修改已合并的 SQLite 迁移改为新增迁移。不手工编辑backend/internal/storage/sqlite/gen/*改queries/*或迁移后运行npm run sqlc重新生成。SQLite 变更事件由 DB 触发器写入change_log不得在 store 方法中并行手工发射 CDC除非架构显式变更。5.~/.ao所有 AO 状态只能落在这里所有 AO 自有应用状态只能位于~/.ao之下。daemon 数据目录、running.json、工作树、Electron 监督进程的userDataChromium 缓存、cookies、local/session storage、crash dumps都必须解析到~/.ao可用AO_DATA_DIR/AO_RUN_FILE覆盖。绝不向~/Library/Application Support或任何 OS 默认应用数据位置写 AO 状态。唯一的读例外是显式、用户发起的浏览器 profile 导入只读经过校验的、已知来源的浏览器 profile 文件绝不写入源 profile源路径不得进入 renderer所有快照、staging 文件与导入结果都放到~/.ao下。这条规则在 frontend/src/main.ts 有直接实现Electron 的userData被 pin 到~/.ao/electron打包版或~/.ao/dev/electron开发版sessionData与crashDumps都从userData派生因此这一个覆盖点就把它们全部重新挂载了daemon 数据目录在 dev 下为~/.ao/dev/data、生产为~/.ao/datarunning.json在~/.ao/running.jsondev 为~/.ao/dev/running.json。注释明确指出 103 字节的sockaddr_un限制也是因此设计为~/.ao下的子目录。移除main.ts中的该覆盖或依赖 Electron 默认路径都是被禁止的。API 契约变更code-first改源再重新生成daemon API 是code-first的OpenAPI spec 与前端 TypeScript 类型都是生成产物——编辑源然后重新生成。这正对应前文机器可读契约层的设计。需要编辑的源文件backend/internal/httpd/controllers/dto.go —— 请求/响应形状backend/internal/httpd/apispec/specgen/build.go —— 操作注册表新增命名类型要加schemaNames条目。编辑后重新生成npm run api # 依次执行 api:spec 然后 api:ts等价于手动执行npm run api:spec # cd backend go generate ./internal/httpd/apispec/... npm run api:ts # npx openapi-typescript7.4.4 backend/internal/httpd/apispec/openapi.yaml -o frontend/src/api/schema.ts验证cd backend go test ./internal/httpd/... # spec 漂移 路由/spec 一致性测试不覆盖 schema.ts——由 api-drift CI 任务检查提交时必须把openapi.yaml与frontend/src/api/schema.ts和 Go 改动一起提交。CI 会重新生成这两个文件若已提交版本过期则失败。openapi.yaml生成结果位于 backend/internal/httpd/apispec/openapi.yaml。CLI 手工镜像的 DTObackend/internal/cli/是刻意的手工边界不由openapi.yaml生成线级兼容由测试覆盖而非生成器保证。PR 卫生从描述到验证的提交前清单最后AGENTS.md 定义了智能体提交 PR 前的行为规范创建或更新 PR 时遵循.agents/skills/pr-description/SKILL.md让 PR 描述以经过验证的分类变更计数开头。创建或交接 PR 前用 CI 工作流命令、固定版本 runtime 和 CI 环境本地跑完全部校验任务完整测试套件而非只跑聚焦测试修复失败后重跑受影响的全量套件再分享 PR。本地通过 ≠ 保证远程检查也要验证。若某任务无法本地跑如缺少原生 OS runner、Docker 或所需凭据必须明确报告缺口并在 CI 中验证绝不能标注为本地通过发布或生产部署不作为验证步骤执行。除非明确延续既有 PR否则从main切分支。一个 PR 对应一个问题被要求做独立工作时另开分支和 PR。使用 conventional commit 消息feat:、fix:、docs:、test:、chore:。在 PR body 中说明刻意省略的部分——尤其是当 TypeScript 原版比 Go 重写版当前领域支持的行为更多时。先跑最窄的相关测试再跑匹配所改区域的仓库/CI 命令。小结为什么这份契约值得被认真对待AGENTS.md 之所以能成为仓库的智能体操作契约是因为它把四类知识压缩进了一个文件目录地图改动归属、命令清单本地验证闭环、硬性边界网络监听、状态推导、数据落盘、迁移纪律与协作规范编码约定、API 变更流程、PR 卫生。每一类都能在仓库源码中找到可验证的实现证据——usageError的退出码 2、lanControlBlock的控制前缀封锁、~/.ao/electron的 userData pin、MobileAPIVersion的契约版本号、code-first 的npm run api生成链路。对于任何将要在这类人机共写仓库中工作的编码智能体把 AGENTS.md 当作第一手权威来源、把它的硬规则当作不可逾越的边界是避免破坏性事故、保证 CI 绿与评审顺畅的最低成本策略。继续深入可以从 docs/architecture.md后端心智模型与 docs/documentation-map.md契约层总览开始。【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址: https://gitcode.com/gh_mirrors/ag/agent-orchestrator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考