oh-my-codex AGENTS.md 全解读Codex 多 Agent 编排的顶层操作契约与运行时不变式【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codexAGENTS.md 是 oh-my-codexOMX工作区的最高操作契约它定义了 Codex CLI 之上的智能多 Agent 编排层的自主性边界、委派规则、技能路由、团队协作协议与持久化状态所有权。本文将逐节拆解这份契约的每一项条款并对照仓库中的 guidance schema、关键字注册表、团队状态机与状态存储实现说明每条规则在源码层面如何落地帮助你理解并正确配置自己的 OMX 工作区。一、AGENTS.md 的定位顶层操作契约oh-my-codex 是 Codex CLI 的协调层coordination layer仓库中的 templates/AGENTS.md 是这份协调层的顶层操作契约模板在安装后可作为工作区根目录的 AGENTS.mdtracked copy使用。它与普通提示词的区别在于prompts/*.md是更窄的执行面只负责某个角色的具体执行步骤它们必须遵循 AGENTS.md而不是覆盖它。OMX 安装后Agent 应从~/.codex/prompts、~/.codex/skills、~/.codex/agents或项目级启用的./.codex/...等价目录加载安装好的 prompt、skill 与 agent 表面。文件顶部是AUTONOMY DIRECTIVE自主性指令你是自主编码 Agent应当把任务执行到底不反复询问是否可以继续受阻时尝试替代方案仅在真正歧义或破坏性操作时才提问允许使用 Codex 原生 subagent 处理独立并行子任务这与 OMX Team 模式互补。这份文件在结构上遵循统一的 Guidance Schema见 docs/guidance-schema.md其六大必备区块角色与意图、操作原则、执行协议、约束与安全、验证与完成、恢复与生命周期在 AGENTS.md 中以标记块如operating_principles、verification、delegation_rules的形式呈现。二、运行时标记契约与 Guidance Schemaguidance_schema_contract标记块声明本模板的 canonical guidance schema 定义在 docs/guidance-schema.md当叠加运行时覆盖层overlay时必须保持以下标记契约稳定且非破坏性!-- OMX:RUNTIME:START -- ... !-- OMX:RUNTIME:END -- !-- OMX:TEAM:WORKER:START -- ... !-- OMX:TEAM:WORKER:END --这两个标记是运行时覆盖层runtime overlay与团队 Worker 覆盖层的边界。Schema 文档强调这套标准是增量且迁移安全的不改变任务状态 API、标记契约或文件路径所有权契约。Schema 的映射矩阵Mapping Matrix还明确了各表面的职责划分表面角色与意图执行协议约束与安全验证与完成恢复与生命周期工作区根 AGENTS.md标题 开场介绍模式选择 委派/模型路由/技能/团队 leader/worker 划分紧凑的 hook 支撑的关键字/取消/状态契约verification 续接清单 输出契约取消 恢复/状态指引 运行时/团队标记templates/AGENTS.md同上与根 AGENTS.md 相同的 canonical 编排节相同安全约束相同验证节运行时/团队覆盖层通过标记后加入prompts/*.md角色本地身份与职责该专家的任务执行步骤角色边界/工具规则/上报限制角色本地完成声明前的证据场景处理 最终清单运行时 AGENTS 覆盖层会话上下文身份压缩协议指令标记边界与大小/锁门控压缩前的检查点证据apply/strip 生命周期Team Worker 覆盖层Worker 身份 团队范围ACK → 读任务 → claim → 执行 → complete → idle文件所有权 阻塞状态规则写任务结果 状态更新邮箱轮询 关停处理skills/worker/SKILL.md worker inboxWorker 角色框架Worker 协议原则claim-first 路径/id 安全规则完成写回要求邮箱/关停循环此外Schema 定义了Worker 任务/邮箱文件契约任务文件路径格式.omx/state/team/team/tasks/task-id.json例如task-3.jsonState/MCP API 的 id 格式task_id: id例如3绝不能是task-3邮箱路径.omx/state/team/team/mailbox/worker.json这些路径与 src/team/state.ts 中的实现一一对应taskClaimLockDir位于claims/task-id.lockmailboxPath生成mailbox/worker.json且所有路径都经过assertPathWithinDir防目录穿越校验并要求 worker 名匹配/^[a-z0-9][a-z0-9-]{0,63}$/、任务 id 匹配/^\d{1,20}$/。三、操作原则Operating Principles与自主-询问边界operating_principles块包含两条层次的规则通用原则能安全且高质量地直接解决任务时就直接做仅在能实质提升质量、速度或正确性时才委派进度汇报保持简短、具体、有用优先证据而非假设宣称完成前必须验证使用陌生 SDK/框架/API 前先查官方文档在一个 Codex 会话或团队 pane 内对独立有界子任务使用 Codex 原生 subagent 提升吞吐。OMX:GUIDANCE:OPERATING标记块内的运行级指导!-- OMX:GUIDANCE:OPERATING:START -- ... !-- OMX:GUIDANCE:OPERATING:END --默认 outcome-first先识别用户的目标结果、成功标准、约束、可用证据、预期输出和停止条件再补充过程细节。AUTO-CONTINUE 与 ASK 的分界对清晰、低风险、可逆的本地编辑-测试-验证工作自动继续不请求权限交接只有破坏性、不可逆、凭据门控、外部生产环境或实质改变范围的操作才需要 ASK。绝对化语言的边界只用绝对化语言描述真正的恒真不变量——安全、安全边界、必需输出字段、工作流状态转移、产品契约。新证据优先当用户在同一线程内提供更新的证据日志、堆栈、测试输出时以新证据为当前事实源重新评估旧假设不锚定旧证据。节制工具升级更多投入不等于反射性地升级网络/工具调用先重新评估低/中档努力水平与最小的有效工具循环。四、工作协议Working Agreements对清理/重构/去冗deslop类工作先写清理计划并用回归测试锁定行为再动手编辑当测试覆盖缺失时。优先删除、复用既有工具与既有模式而非新建抽象只有明确要求时才新增依赖。保持 diff 小而可审查、可逆。改动后用 lint、typecheck、测试与静态分析验证最终报告包含改动文件、简化项与剩余风险。这与execution_protocols中的 Anti-slop 工作流呼应清理工作走understand - execute - verify - report轻量流程可使用$ai-slop-cleaner见 skills/ai-slop-cleaner/SKILL.md作为有界助手写代码前先写清理计划用回归测试锁定行为一次只做一轮气味修复坚持删除优于新增、复用加边界修复优于新层无明确要求不新增依赖。五、委派规则Delegation Rules与工作流选道delegation_rules规定了默认直做的姿势和六条执行车道默认姿态直接工作普通工作流是understand - execute - verify - report。$autopilot显式的无人值守编排其定义性的默认链是$deep-interview - $ralplan - $ultragoal这些受监督的阶段不能被空洞化为可选提示。$deep-interview当需求、意图、非目标或决策边界实质模糊时使用它是规划前独立的 Ouroboros 式苏格拉底深访谈阶段不等于$plan --interview。$plan无需深访谈时的轻量规划。$team已批准的计划需要跨多车道协调并行执行时使用。$ultragoal带检查点/恢复语义的持久多目标运行。单独执行任务已被界定且单个 Agent 能直接完成并验证时。角色边界同样重要在活跃的team/swarm模式之外用executorprompts/executor.md承担有界的实现或审查切片worker不是通用子角色仅限活跃team/swarm会话中由团队运行时分配 worker 车道时使用。关于 Conductor 工作流在 Conductor 工作流活跃期间原生子 Agent 仅限验证/建议——只能做正向分类的读取子到领导的汇报还需要独立的主机认证调用方、父与目标三重证明当活跃原生表面无法提供该证明时协作汇报与源/产品变更被拒绝。实现应路由到 Team且仅在 Team 的主机权威检查通过后进行Team 不可用或被拒绝时返回有界的只读结果或 blocker而不是把本地状态、任务文本、会话字段、跟踪器或子代来源当作权威。六、子 Agent 协议Child Agent Protocolchild_agent_protocol定义了 Leader/Worker 的职责契约Leader 职责选择模式、委派有界可验证子任务、集成结果、承担最终验证。Worker 职责执行分配的切片、严格留在范围内、向上汇报 blocker、共享文件冲突、范围扩张或推荐交接子提示应向上推荐交接而不是递归编排。升级方向worker 就 blocker、共享文件冲突、范围扩张、缺失权限或模式错配向 leader 升级。硬性上限最多6 个并发子 Agent子提示始终处于 AGENTS.md 权威之下除非任务有具体的模型理由否则继承模型默认值worker是团队运行时表面而非通用子角色。这一协议在团队状态机层面有完整实现任务状态枚举定义在 src/team/contracts.ts即pending | blocked | in_progress | completed | failed且只有in_progress状态可以转移到completed/failed终态集合completed/failed不可再转移。同时 dispatch 请求也有独立状态机pending - notified - delivered/failed。Leader 与 Worker 之间通过omx team api ... --json与.omx/state/team/team/下的任务、邮箱、事件events.ndjson文件交换状态见 src/team/state.ts 的teamEventLogPath与各类锁实现。七、调用约定、模型路由与专家路由调用约定Invocation Conventions$name—— 调用一个工作流技能例如$deep-interview、$team。/skills—— 浏览可用技能。确定性工作流路由优先使用显式技能调用。模型路由Model Routing按任务形态匹配角色任务形态路由角色仓库查找explore官方文档/参考收集researcherSDK/包决策dependency-expert实现executor根因分析debugger高复杂度审查architect/criticCodex 原生子 Agent 继承当前仓库/模型默认值除非调用方有具体理由覆盖。专家路由Specialist Routing!-- OMX:GUIDANCE:SPECIALIST-ROUTING:START --标记块内给出了更细的分流契约explore仓库内文件/符号/模式/关系查找、当前实现发现、仓库当前如何用某依赖。explore只掌握本仓库事实不负责外部文档或依赖建议。researcher官方文档、外部 API 行为、版本感知的框架指导、release-note 历史、带引用的资料收集。技术已选定回答这个选定的事物如何工作不是默认的依赖对比角色。dependency-expert包/SDK 选型或对比决策——是否采用、升级、替换或迁移候选对比维护、许可、安全、风险评估。混合路由要刻意为之explore - researcher本地现状 官方文档确认、explore - dependency-expert当前依赖使用 升级/替换/迁移评估、researcher - explore文档清晰但仓库影响面需确认、dependency-expert - explore决策清晰但本地迁移面需测绘。专家应将边界跨越上报而非默默吸收相邻工作当外部证据实质影响答案时先路由到相关专家再回到规划或执行。角色目录Agent Catalog关键角色explore、researcher、dependency-expert、planner、architect、debugger、executor、test-engineer、verifier、critic。完整描述以安装的角色目录为准对应提示词可参考 prompts/ 目录下的文件如 planner.md、verifier.md、test-engineer.md。八、关键字检测与 Hook 路由keyword_detection块说明关键字路由主要由原生UserPromptSubmithooks和生成的关键字注册表实现。关键规则当 hook 注入的路由上下文可用时以当前轮次的注入上下文为权威然后按指示加载对应的SKILL.md或 prompt 文件。hook 上下文不可用时的回退行为显式$name调用从左到右执行并覆盖隐式关键字。裸技能名本身不会激活技能技能名激活需要显式$skill调用。自然语言路由短语仍可能映射到某个工作流例如analyze/investigate→$analyze只读深度分析带排序综合、显式置信度与具体文件引用。详细关键字列表维护在 src/hooks/keyword-registry.ts不要在该文件中重复。源码层面keyword-registry.ts定义了KeywordTriggerDefinition接口keyword/skill/priority/guidance内置了从$autopilot、$deep-interview、$plan、$ralplan、$team、$cancel、$wiki到code review、build me、gather requirements等数十条触发定义并为其赋予不同优先级如$ralplan为 11、autopilot为 10、$team为 8、$cancel为 5。compareKeywordMatches先按优先级降序、再按关键字长度降序排序确保匹配确定性显式$token经EXPLICIT_SKILL_LOOKUP规范化后参与路由。另一个关键约束autopilot、ultraqa、team、ultragoal等运行时工作流需要 OMX CLI 运行时支持。在 Codex App、tmux 之外或没有 OMX tmux 运行时的普通 Codex 会话中应说明这些工作流在那里不可直接使用并继续使用最近的 App 安全表面——除非用户明确要求先从 shell 启动 OMX CLI。对于 deep-interview在附加 tmux 的 OMX CLI/运行时中激活时应通过omx question进行每轮提问在后台终端启动omx question后等待该终端结束并读取 JSON 答案再继续通过 Bash/工具路径调用时用OMX_QUESTION_RETURN_PANE$TMUX_PANE保留 leader pane。tmux 之外或无法渲染omx question的原生表面应使用原生结构化提问路径否则只问一个简洁的纯文本问题并等待答案。最后已移除/弃用的落日存根$ralph、$ultrawork、$pipeline、ecomode、swarm属于已移除或弃用的 sunset stubs不应将用户路由到那里。九、技能与团队模式技能Skillsskills块技能是工作流命令。始终先加载相关已安装的SKILL.md再遵循技能专属流程除非已安装目录仍将该技能标记为活跃否则删除或忽略已弃用的技能描述。仓库中 skills/ 目录下有 30 个技能如 autopilot/SKILL.md、deep-interview/SKILL.md、ralplan/SKILL.md、ultragoal/SKILL.md、cancel/SKILL.md、team/SKILL.md。团队组成与流水线team_compositions对于功能开发、缺陷调查、代码审查、UX 审计等多车道工作当协调价值超过开销时使用显式团队编排。team_pipeline团队模式是结构化多 Agent 表面当持久的阶段性协调值得开销时使用否则保持直接模式。终态complete、failed、cancelled。这对应 src/team/state.ts 中TeamConfig的lifecycle_profile: default以及TeamManifestV2的完整状态清单。团队模型解析Team Model ResolutionTeam/Swarm Worker 模型优先级显式OMX_TEAM_WORKER_LAUNCH_ARGS继承的 leader--model低复杂度默认值OMX_DEFAULT_SPARK_MODEL旧别名OMX_SPARK_MODEL要求将模型标志归一化为唯一 canonical 的--model value条目并使用OMX_DEFAULT_FRONTIER_MODEL/OMX_DEFAULT_SPARK_MODEL而非猜测默认值。团队运行时还支持通过OMX_TEAM_DISPLAY_MODE/OMX_TEAM_MODEauto/split_pane与OMX_TEAM_WORKER_LAUNCH_MODEinteractive/prompt环境变量调整策略见 src/team/state.ts 的resolveDisplayModeFromEnv与resolveWorkerLaunchModeFromEnv。十、验证与执行协议验证循环Verificationverification块含OMX:GUIDANCE:VERIFYSEQ标记定义主张与成功标准 → 运行能证明它的最小验证 → 读取输出 → 附证据汇报失败则迭代无法运行验证则解释原因并用次优检查。补充细则依赖任务顺序执行先验证前置条件再启动下游。任务更新只改当前分支时就地应用并继续不重新解释无关的常设指令。编码工作优先对变更行为做定向测试再视情况做 typecheck/lint/build/smoke 检查没有新鲜证据或显式验证缺口时不得宣称完成。当正确性依赖检索/诊断/测试时只持续到任务被扎根并验证为止避免只为措辞或非必要证据而增加循环。执行协议Execution Protocols模式选择$autopilot显式请求监督链$deep-interview - $ralplan - $ultragoal、$deep-interview独立需求歧义、$ralplan独立架构/共识规划、$team已批准的多车道并行、$ultragoal独立持久多目标。否则直接单独执行只有证据显示当前车道错配或被阻塞时才切换模式。命令路由简单只读仓库查找默认用常规 Codex 仓库检查工具/subagentomx sparkshell仅用于显式的 shell 原生只读证据或有界验证omx sparkshell --tmux-pane是显式 opt-in 的运维辅助不替代原始证据捕获。OMX CLI 入口为 src/cli/omx.ts它要求先npm run build生成dist/再运行编译后的入口。Supervisor tmux 交接安全防止把草稿文本粘贴进 pane绝不自 tmux 的隐式/当前 buffer 粘贴用tmux set-buffer -b name -- $message或临时文件支撑的tmux load-buffer -b name file把交接文本载入全新命名 buffer绝不用tmux load-buffer -- message。粘贴前必须用tmux show-buffer -b name验证命名 buffer加载失败或 buffer 不匹配是 blocker不得执行paste-buffer或提交按键。粘贴前用tmux send-keys -t pane C-u清空 pane 编辑器再用括号粘贴tmux paste-buffer -t pane -b name -p -d并有意提交。粘贴/回车后重新捕获 pane验证预期的回合被接受而非残留草稿文本。Leader vs Workerleader 选择模式、委派有界工作、集成并承担验证worker 执行切片并向 leader 升级 blocker、范围扩张、共享所有权冲突或模式错配。停止/升级任务验证完成、用户说停止/取消、或没有有意义的恢复路径时停止仅对不可逆、破坏性、实质分叉决策或缺失权限向用户升级。输出契约默认更新/最终形态为当前模式 动作/结果 证据或 blocker/下一步理由只陈述一次不每轮重述完整计划仅在风险、交接或明确请求时展开。续接结束前确认没有遗留工作、功能正常、测试通过或缺口已显式化、验证证据已收集否则继续。十一、取消与状态管理取消Cancellationcancellation块工作完成并验证、用户说停止、或硬 blocker 阻止有意义进展时使用cancel技能skills/cancel/SKILL.md结束活跃执行模式。还有可恢复工作时不要取消。状态管理State Managementstate_management块OMX 运行时状态位于.omx/下。omx state命令见 src/cli/state.ts提供对模式状态的读写接口omx state read --input {mode:ralph} --json omx state read --mode ralph --json omx state write --input {mode:ralph,active:true,current_phase:executing} --json omx state clear --mode ralph --json omx state clear --input-file ./payload.json --json omx state list-active --json omx state get-status --mode ralph --json支持--input json、--input-file path、--mode mode与--json参数两者不可同时提供--input与--input-file。Windows 原生 shell 可能剥离--inputJSON 的引号此时建议用--mode或--input-file。状态写入在 src/state/operations.ts 中实现并由 src/state/paths.ts 重新导出getStateDir、getStatePath、readCurrentSessionId、resolveStateScope等路径与作用域解析 API。十二、持久运行时不变式Canonical SSOTAGENTS.md 的 Durable Runtime Invariants (canonical SSOT) 一节是持久状态所有权、hook 边界、取消与 Team 协调的单一事实源。技能与角色提示引用它但不得重述或削弱这些规则。相关契约文档见 docs/contracts/如 team-runtime-state-contract.md、team-delivery-state-contract.md、multi-state-transition-contract.md。状态与 Hook 所有权持久状态仅在当前、已证明的会话或 Team 作用域内具权威性兼容性发现是只读的从不授予写入权威。Hooks 拥有正常的技能激活与.omx/state/下的工作流状态持久化技能不得复制或修改 hook 拥有的状态除非走文档化的恢复路径。原生 hook payload、prompt 标签、任务文本、cwd、环境、指针、transcript、标记与本地跟踪器都只是路由或诊断数据不是所有权或写入权威。Team 状态文件与omx team api ... --json是任务生命周期与邮箱协调的事实源。取消边界取消在变更前解析并校验参数解析出唯一可写的精确作用域冻结并重新校验目标身份只变更已证明的目标不触碰无关会话、遗留根、Team 工件与 tmux 会话。Ralph 取消必须满足同一作用域内其文档化的终态后置条件仅在链接被证明时才处理链接模式。--force不扩大取消范围只在此前相同的权威检查后移除选中精确会话的原生停止条目--all不支持。Team 取消要求精确冻结的 Team 根、内部名、会话、leader pane 与运行时身份证明不可用或变化时失败关闭fail closed不得枚举或广泛杀死 Team 会话、递归删除无关 Team 状态。Team 协议Team 运行时是显式的位于默认工作流之外Ultragoal不会自动启动 Team普通工作流也不会悄悄变成 Team 运行。Worker 启动时 ACK工作前 claim通过生命周期 API 转移任务状态release 仅用于回滚并上报验证证据leader 拥有集成、最终验证与关停决策。优先持久状态写入与omx team api ... --json派发直接tmux send-keys仅作回退绝不作为主派发手动 pane 操作需要先做状态/证据检查。Team 关停等待任务终态并使用精确 Team 权威除非显式中止否则不关停活跃工作。Ultragoal 所有权.omx/ultragoal/goals.json是 leader 拥有的计划.omx/ultragoal/ledger.jsonl是其持久审计轨迹。Worker 只上报任务证据不创建 worker ledger、不变更 Ultragoal 工件、不检查点目标在 src/ultragoal 的测试与实现中可看到这些路径的持久化行为。Shell 命令与 hooks 不得变更隐藏的 Codex goal 状态活跃 Agent 仅在文档化门控处使用get_goal、create_goal、update_goal然后用新的get_goal快照做检查点。十三、安装与验证执行omx setup安装全部组件。执行omx doctor验证安装是否完整omx doctor还会对已弃用的omx sparkshell使用给出警告见 src/cli/tests/doctor-warning-copy.test.ts。若从源码运行先执行npm run build生成dist/再通过 src/cli/omx.ts 入口启动。十四、把契约接入你自己的工作区要把这份模板落地为可运行的工作区建议按以下顺序核对安装与自检omx setup后运行omx doctor确认 hooks、skills、agents 均就位。确认 schema 对齐以 docs/guidance-schema.md 为准核对根 AGENTS.md 与各SKILL.md是否保留六大区块与两个运行时标记。选择执行车道默认直做需求模糊走$deep-interview需要共识规划走$ralplan多车道并行走$team持久多目标走$ultragoal。遵守状态所有权状态只写.omx/下由 hooks/团队运行时拥有的路径Worker 只上报证据不越权修改计划与账本。验证再宣称完成遵循验证循环——定义主张、跑最小验证、读输出、附证据汇报。这份 AGENTS.md 的核心价值在于它把自主但守纪律的 Agent 行为、可预测的多 Agent 委派、以及不可动摇的运行时所有权边界压缩成一份可被 Agent 与团队运行时共同读取、共同遵守的机器可读契约。理解它就等于理解了 oh-my-codex 如何在 Codex CLI 之上构建出安全、可审计、可恢复的多 Agent 协作体系。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考