oh-my-codex 双通道独立代码评审：code-review Skill 的合并就绪门控实战指南

oh-my-codex 双通道独立代码评审：code-review Skill 的合并就绪门控实战指南

【免费下载链接】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

导读

本文讲解 oh-my-codex（OMX）中code-reviewSkill 的完整运作机制：它以显式 opt-in 的方式，为合入前的变更提供双通道独立评审（code-reviewer与architect并行、互不替代），并通过确定性规则合成最终裁决（APPROVE / REQUEST CHANGES / COMMENT），把"评审不可用"与"拒绝合入"绑定为硬性门禁。读完本文，你将掌握如何用$code-review触发合并就绪评审、如何构造双通道 agent 调用、如何解读评审分类法与状态契约，以及如何对接 Autopilot / ultraqa / Ralph 等下游工作流。

核心入口文档为 skills/code-review/SKILL.md，配套的评审角色定义与运行态约束分别在 prompts/code-reviewer.md、prompts/architect.md 与 templates/AGENTS.md 中；仓库对这份契约有专门的测试守卫，见 src/hooks/tests/code-review-skill-contract.test.ts。

何时使用 code-review：一份明确的触发边界

code-review是一个显式 opt-in的任务卡（Task Card），不是默认流水线的一部分。其使用时机在 skills/code-review/SKILL.md 中写得很清楚：

• 应该用：用户明确要求代码评审、质量或安全评估；变更在合并前已就绪、需要一次独立评审；或一个大型功能需要独立于作者的第二双眼睛。
• 不要用：实现、广泛规划或自动清理类任务——这些场景有各自的 Skill（如$deep-interview、$plan、$team、$ultragoal）负责，不应被评审卡抢占。

这与仓库的关键词路由实现一致：src/hooks/keyword-registry.ts 将code review、$code-review、review code三个触发词以 priority 6 路由到code-reviewSkill；在 hook 上下文不可用时，AGENTS.md 规定以显式$code-review调用为准。

输入与作用域：先记录，再评审

发起评审前，卡片要求先锁定输入集：

• Scope：被请求评审的文件、commit、PR 或整个 diff。
• Requirements / specification：验收标准、相关的测试 / CI 证据。
• 已有评审产物与已知风险（如有）。
• continue语义：如果用户说continue，应在当前已验证的评审步骤上继续推进，而不是重启发现流程。

SKILL 建议用如下命令记录作用域基线：

git status --short git diff --stat git diff -- <scope>

作用域一经记录，"识别变更文件与评审边界，不要静默扩大范围"就成为评审的第一个执行约束——这保证了评审结论可以精确回溯到被审对象。

执行模型：双通道并行，禁绝自我评审

评审执行的核心是两个独立 lane 并行运行、互不替代：

1. 识别变更文件与评审边界。
2. 并行启动code-reviewer与architect两个 agent，两者都在干净上下文（clean context）中、携带显式 scope 与产物运行。如果任一 lane 无法启动或未返回证据，必须报告independent review unavailable，不得用当前/作者 lane 顶替，也不得批准或标记评审为合并就绪。
3. 尊重用户当前的模型与 reasoning/effort 选择，不要在评审 lane 调用中传递model或reasoning_effort覆盖参数。

SKILL 给出的原生调用模板如下（两段task(...)并行）：

task( agent_type="code-reviewer", prompt="CODE REVIEW TASK Review the supplied scope for spec compliance, security, quality, performance, and maintainability. Return files reviewed, severity-rated findings with file:line evidence and concrete fixes, and a recommendation: APPROVE / REQUEST CHANGES / COMMENT. Do not review architecture. Scope: [scope and artifacts]" ) task( agent_type="architect", prompt="ARCHITECTURE / DEVIL'S-ADVOCATE REVIEW TASK Review the same scope for boundaries, interfaces, hidden coupling, long-term tradeoffs, and the strongest counterargument against approval. Return file:line evidence, recommendations, and Architectural Status: CLEAR / WATCH / BLOCK. Scope: [scope and artifacts]" )

注意模板刻意不携带model=或reasoning_effort=：这正是 src/hooks/tests/code-review-skill-contract.test.ts 用doesNotMatch断言守卫的契约，防止评审 lane 悄悄覆盖用户的选择。

两个 lane 的角色定义

在 agent 目录中，两个角色都有显式定义（src/agents/definitions.ts 与 #L170-L179）：

prompts/code-reviewer.md 进一步定义了该 lane 的两阶段检查法：

• Stage 1 — Spec Compliance：确认每个需求都被覆盖、预期问题被解决、没有添加未经请求的行为。
• 根因守卫（root-cause guard）：拒绝那些吞掉失败、压制诊断、引入宽泛替代路径或绕过主契约的 fallback/workaround，要求最小根因修复、显式失败行为与回归证据。
• Stage 2 — Code Quality：检查正确性、安全、性能、可维护性与最佳实践，并在可行时对每个变更文件运行诊断；重点排查硬编码密钥、注入、XSS、不安全默认值、静默错误处理等模式。
• 每条发现必须给出 CRITICAL/HIGH/MEDIUM/LOW 定级与具体file:line，说明影响与根因，再给出可落地的修复建议；事实与建议必须区分。

prompts/architect.md 则约束该 lane：不评审没打开过的代码；重要论断必须引用文件与行号范围；先分离根因与症状、证据与不确定性；在双通道评审中必须显式输出CLEAR/WATCH/BLOCK架构状态；涉及共识评审时还要给出反题（antithesis）、权衡张力与综合（synthesis）。

评审分类法：统一的分级语言

两个 lane 的产出用同一套分级语言汇总：

• code-reviewer检查Security、Code Quality、Performance、Best Practices、Maintainability五个维度。
• 每条发现按CRITICAL（安全或数据丢失阻断项）、HIGH（bug/重大坏味道）、MEDIUM（重要改进）、LOW（风格/建议）定级。
• architect输出架构状态CLEAR（无问题）、WATCH（不阻断但有顾虑）、BLOCK（合并阻断项）。
• 每条发现必须包含file:line、问题描述、风险与具体修复方案，并区分事实与建议。

这套定级语言与 prompts/code-reviewer.md 的输出契约一一对应（CRITICAL: X (must fix)/HIGH: Y (should fix)/MEDIUM: Z (consider fixing)/LOW: W (optional)），保证多 lane 评审结果可以机械合并。

状态 / HUD 阶段契约：评审在哪运行

code-review对运行时状态有明确归属约束，避免与其它工作流互相污染：

• 独立运行$code-review：依赖 hook 持有的skill-active-state.json（skill:"code-review"、phase:"planning"），不要自建code-review-state.json——这与 AGENTS.md 的"hook 拥有正常 skill 激活与工作流状态持久化，skills 不得复制或改写 hook 持有的状态"一致。
• Autopilot 内运行：保持mode:"autopilot"激活，current_phase:"code-review"/ skill-activephase:"code-review"，不要激活对等的兄弟工作流。
• 评审通过：在进入ultraqa前，将产物持久化到 Autopilot 的handoff_artifacts.code_review；评审未通过：持久化发现结果，并按需走rework或ralplan。

Autopilot 阶段机把code-review与ultraqa列为合法的子阶段（src/autopilot/fsm.ts），且完成门控测试明确要求"从 implementation 到 code-review 的转换"以及"进入 ultraqa 前的 code-review 证据"（src/autopilot/tests/completion-gate-advisory.test.ts）。在附加 tmux 的 OMX CLI 运行时，可用以下命令写入状态：

omx state write --input '{"mode":"autopilot","active":true,"current_phase":"code-review"}' --json

omx state命令支持read|write|clear|list-active|get-status子命令，完整用法见 src/cli/state.ts。

最终综合与门禁：确定性的合并裁决

架构状态契约（Architectural Status Contract）

最终裁决必须同时合并两个独立 lane 的证据；任一 lane 缺失或委托失败都属于"阻断性不可用状态"，而不是批准的降级回退。合并规则是确定性的：

1. 若架构状态为BLOCK→ 最终建议REQUEST CHANGES。
2. 否则若code-reviewer建议为REQUEST CHANGES→ 最终建议REQUEST CHANGES。
3. 否则若架构状态为WATCH→ 最终建议COMMENT。
4. 否则最终建议跟随code-reviewerlane。

批准条件非常严格：APPROVE 仅在code-reviewer返回 APPROVE、架构状态为 CLEAR、且两个独立 lane 都返回了证据时才能给出；REQUEST CHANGES适用于出现阻断项、未解决的高/严重发现或 lane 不可用；COMMENT用于记录非阻断性发现。

这套映射在 src/hooks/tests/code-review-skill-contract.test.ts 中被逐条断言，包括"BLOCK → REQUEST CHANGES""WATCH → COMMENT"以及"APPROVE 的双 lane 证据前提"。

不可用即不可批：无自我评审回退

• 禁止自我评审回退：如果code-reviewer或architect路径缺失、不可用、被跳过或失败，必须阻止批准，直到存在独立 lane 证据。
• Ralph 例外：在显式 Ralph 路径上，发现结果可以触发自动修复跟进而无需再次征求权限；但普通code-review本身是只读的，不承诺自动修复。
• 最终报告必须让架构阻断项"不可能被漏看"。

证据 / 输出契约：可被下游消费的评审报告

评审结束必须返回一份紧凑的报告，SKILL 提供了可直接套用的模板：

CODE REVIEW REPORT Files Reviewed: <count> Total Issues: 0 Architectural Status: CLEAR | WATCH | BLOCK CRITICAL (0) | HIGH (0) | MEDIUM (0) | LOW (0) Findings: file:line -> issue, risk, concrete fix (or none) ARCHITECTURE WATCHLIST: concern, status, recommendation (or none) - code-reviewer recommendation: COMMENT - architect status: WATCH - final recommendation: COMMENT RECOMMENDATION: COMMENT

模板中的计数与裁决为示例值，需替换为真实观察结果；报告还应包含 scope、lane 证据/产物引用、未解决风险与验证缺口。示例中的"Total Issues: 0"与分级计数之和相等这一自洽性，同样被契约测试校验（src/hooks/tests/code-review-skill-contract.test.ts）。

退出条件：何时可以停

当 scoped diff 拥有了两个独立 lane 结果与确定性的最终建议时，评审结束：

• 只有在满足批准条件时才报告APPROVE；
• 否则留下有界的REQUEST CHANGES、COMMENT或"评审不可用"结果；
• 没有所需证据，绝不宣称合并就绪。

与周边工作流的衔接

• Autopilot：code-review是deep-interview → ralplan → ultragoal主链之外被显式挂载的评审阶段，通过omx state write与handoff_artifacts.code_review与ultraqa交接（见上文"状态 / HUD 阶段契约"）。
• Ralph：显式 Ralph 路径下，评审发现可触发自动修复跟进；普通code-review保持只读，不会悄悄改动代码。
• 团队模式：AGENTS.md 将代码评审列为适合显式团队编排的多 lane 工作之一（templates/AGENTS.md），但在code-review卡内，双 lane 委托必须走原生task(agent_type=...)，不携带model/reasoning_effort覆盖。

小结：把"评审"变成可验证的门禁

oh-my-codex 的code-reviewSkill 用一个简单而强约束的模型解决了 AI 评审最大的隐患——自我背书：两条独立 lane 必须都给出证据，缺失即不可批；裁决由确定性规则合成，不依赖主观判断；状态归属明确（hook 持有），不与兄弟工作流互踩；报告模板结构化，可被ultraqa、rework、ralplan等下游机械消费。对任何把"合并前独立评审"当作硬要求的团队，这套契约都值得直接借鉴。

参考路径速查

• skills/code-review/SKILL.md — 评审任务卡本体（本文主体）
• prompts/code-reviewer.md — code-reviewer lane 的完整角色指令
• prompts/architect.md — architect lane 的角色指令与输出契约
• src/agents/definitions.ts — architect 角色定义（xhigh 推理、只读）
• src/agents/definitions.ts — code-reviewer 角色定义（high 推理、只读）
• src/hooks/tests/code-review-skill-contract.test.ts — 评审契约的自动化守卫测试
• src/autopilot/fsm.ts — Autopilot 子阶段机中的code-review/ultraqa
• src/cli/state.ts —omx state命令用法
• templates/AGENTS.md — 状态与 hook 归属的 SSOT 规则

【免费下载链接】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