SuperAPI AI 工具集

codex-review

编程与开发

查看项目

更新于 10-24 00:42

技能介绍

用途

codex-review 通过 OpenAI Codex CLI 执行代码审查并返回发现。它的价值在于“使用不同的模型”:目的是捕捉 Claude 自身审查可能遗漏的问题,而不是替代或改进 Claude 的审查。使用范围非常明确:作为 /deep-review 的第二审查者使用,或在用户明确要求非 Claude 模型审查某个 diff 时使用。

不应用于一般代码审查、子代理自我审查,也不应作为任何位置的默认审查者。内置的 /code-review 更快、在自己的上下文中运行,且无需外部 CLI。

主要能力与行为约定

  • Codex 以只读方式运行,从不编辑文件;该技能本身也从不提交代码,只向调用方报告发现。
  • 当用户单独调用该技能且没有调用方可路由时,由执行者自行应用明确正确的修复并提交。
  • 并发保护:每次启动都被包裹在 bash $HOME/.claude/scripts/codex-guard.sh --wait <secs> -- <launch...> 中,这是机器级 flock 信号量,共 2 个槽位,防止并行代理同时审查造成机器过载。不得传入按调用方区分的 --slots,所有调用方共享默认值。
  • 守卫超时降级约定:如果在 --wait 时间内没有槽位释放,守卫以退出码 75 退出且不运行 codex,随后按其他非零退出码一样进入降级路径。管理器启动等待 300 秒,子代理等待 90 秒并采用更轻量的降级方式。

使用流程

步骤 0:限流预检。运行 node $HOME/.claude/scripts/codex-rate-limit.js check,非零表示被限流,跳过所有 codex 步骤直接进入步骤 4,且不得向用户报告限流。

步骤 1:解析基线与环境。若调用方传入目标(基线分支或 PR 编号),直接使用;PR 编号解析为该 PR 的基线。未传入时按常规方式解析:当前分支有 PR 则用 PR 基线,否则用仓库默认分支。同时准备日志目录、时间戳、Codex 插件路径与超时命令。若 $CODEX_COMPANION 不存在,报告“Codex 插件未安装 — 运行 /codex:setup”并进入步骤 4。

步骤 2:运行 codex,启动形式取决于上下文。

  • 交互式/主会话(管理器)上下文:使用后台 Bash 任务启动,预算 25 分钟(1500 秒),后台任务完成通知会到达此处。
  • 子代理/子代理上下文:绝不可后台运行,使用前台 Bash 单次调用,工具超时设为最大值 600000 毫秒。子代理预算固定为守卫等待 90 秒 + 运行 480 秒 + 终止宽限 15 秒 = 585 秒,小于 600 秒上限;不得提高运行上限。
  • 任何非零 CODEX_EXIT(超时的 124、守卫的 75、无超时跳过)都进入步骤 4,即使输出文件有部分内容。
  • 若不确定所处上下文,按子代理上下文处理。

步骤 3:收集,仅在 codex 实际完成后进行。管理器上下文中后台运行期间输出文件为空,需等待后台任务完成通知或轮询文件,然后再运行 codex-rate-limit.js check-output 检查输出。非零退出或运行结束后输出文件缺失/为空则进入步骤 4。否则读取发现,按优先级整理,连同日志路径返回给调用方。

步骤 4:降级,始终静默。Codex 不可用绝不能阻塞调用方或暴露配额错误,不向用户报告、不暂停、不询问。由 /deep-review 调用时,仅返回“codex unavailable — no findings”,不得用 /code-review 替代(/deep-review 已在步骤 1 并行运行过它,重复运行会制造虚假的跨模型共识信号)。管理器上下文单独调用时,改用 Skill(skill="code-review", args="<本次技能收到的关注度与目标,否则 medium>") 并返回其结果。子代理/子代理上下文:自行在前台审查 git diff "$BASE"...HEAD 并返回发现,不得派生子代理。

步骤 5:回收 broker,仅子代理上下文,所有退出路径均需执行。交互式会话的 SessionEnd 钩子会自行处理;子会话从不触发该钩子,其 broker 与 app-server 会孤儿化到 PPID 1 并耗尽 WSL2 的 fs.inotify.max_user_instances(表现为 Vite EMFILE)。报告前无条件运行 node $HOME/.claude/scripts/codex-sweep.js --workspace "<你的 worktree 绝对路径>",必须传入自己的工作树路径,不能使用 $PWD。

适用场景

  • 作为 /deep-review 的第二审查者,获得跨模型审查意见。
  • 用户明确要求非 Claude 模型审阅某个 diff 时。

限制

  • 不用于一般代码审查、子代理自我审查或默认审查。
  • Codex 只读,所有文件编辑由 Claude Code 完成。
  • 子代理上下文绝不可后台运行 codex,否则其轮次会因等待路由到管理器的通知而永久挂起。
  • 输出写入 $LOGDIR/${DATETIME}-codex-review*.md,带时间戳避免覆盖,之后可通过 /cclogs 访问。
  • 该技能的范围纪律是其存在的核心:以前它是默认审查者,现在不再是;到处运行 codex 会为无人请求的第二意见消耗配额。