第 11 章

Review 与协作

让评审成为你的代码质量防线

从交互式 /review 到 GitHub 自动审查与 CI 集成

你敢直接合并吗

代码改完了，但你真的放心合入主分支吗

代码跑通了就合并

你的 PR 跑通了 CI、通过了单测，你点了 Merge。但 逻辑漏洞、边界条件、错误处理被忽略——这些问题不报警，只等线上爆炸。

等同事 Review

你发了 PR，但同事在忙、在开会、在休假。Review 队列排出三个人，一等就是两天。迭代节奏被打断，你开始做别的事，回头又忘了上下文。

Review 流于形式

你收到同事的 PR，扫了 5 分钟几百行 diff，最后写了 "LGTM"。你们都知道这只是走过场——没人有精力做真正的深度审查。

AI Review 不替代人，而是兜底：在人类 Review 之前，先把明显的坑填平；在 CI 无人值守时，充当第一道关卡。

开始之前

适合谁

写代码时需要"第二双眼睛"的 solo developer
团队没有专职 Reviewer，想提升代码审查覆盖率
想给 CI 加一层自动审查门禁的 DevOps 工程师

读完本章你会

用 /review 在 TUI 中一键审查代码改动
用 codex review CLI 子命令在脚本中自动化
配置 review_model 和 AGENTS.md 定制审查行为
与 Subagents 联动，实现多维度审查

先别急的事

Review 的模型能力上限与误判边界
如何把 Review 结果写回 GitHub PR 评论
企业私有化部署的合规与数据脱敏

前置知识：假设你已经读过第 7 章（Subagents）和第 4 章（Slash Commands）。

Review 是什么

让 AI 充当你的审查伙伴，在改动进入主干前把关

只读审查

Codex Review 不修改你的代码。它只读取 diff 并输出发现——这是纯粹的"第二双眼睛"，不是"自动修复器"。如果需要修复，要另行发指令。

外部视角

你写代码时用的是"创造者视角"——关注"能不能跑"。Review 用的是"审查者视角"——关注"哪里会出问题"。两种视角天然冲突，AI 帮你切换。

原则：Review 不替你做决策，但它确保你在做决策时看过所有相关信息。

官方文档： Review Pane · Slash Commands

Review 的三层目标

从低级错误到架构建议，层层递进

第一层：捕获低级错误

拼写错误、类型不匹配、逻辑矛盾、死代码。这些是最容易被发现但最容易被忽略的问题——因为你对自己的代码"太熟悉"了。

第二层：识别潜在问题

边界条件、安全漏洞、性能隐患、并发风险。这些不会让代码报错，但会在特定场景下引发故障。

第三层：提供改进建议

命名优化、结构重组、可测试性提升。这些不是 bug，但会让代码六个月后更容易维护。

现实检查：AI Review 在第一层表现最好，第二层需要好的指令引导，第三层仅供参考——它不了解你的业务上下文。

三种入口

TUI、CLI、GitHub——同一个引擎，不同姿势

/review（TUI 交互式）

在 Codex TUI 中输入 /review，弹出范围选择菜单。结果以 inline comments 形式显示在 review pane 中。

审查结果直接嵌入当前会话
可继续追问，让 Codex 解释或修复
适合：开发中途快速自查

codex review（CLI 子命令）

在终端直接运行，不进入 TUI。通过 --uncommitted / --base / --commit 指定范围。

codex review --base main
codex review --uncommitted
codex review --commit HEAD

@codex review（GitHub PR）

在 GitHub PR 评论中 @codex review，Codex 读取 diff 和仓库 AGENTS.md 规约，以标准 PR review 评论形式发布指摘。

聚焦 P0 / P1 高优先度问题
用 @codex fix 让 Codex 自动修复

选哪个入口

一个判断标准就够了

用 /review 当……

你正在 TUI 里写代码，想中途检查一下
你需要和 Codex 继续对话，追问审查发现
你想用 review pane 查看行内标注

用 codex review 当……

你在写 CI 脚本或 Shell 自动化
不进入 TUI，直接在终端拿结果
想精确控制审查范围（--base / --commit）

用 @codex review 当……

PR 已推到 GitHub
需要团队可见的 review 记录
想让 Codex 直接在 PR 行内评论

经验法则：本地开发用 /review，脚本/CI 用 codex review，GitHub 协作用 @codex review。

审查范围

三种 diff 范围覆盖所有场景

范围	CLI 参数	等价 git 命令	何时用
未提交改动	`--uncommitted`	`git diff`（含 staged + unstaged + untracked）	提交前自查
分支对比	`--base main`	`git diff main...HEAD`	PR 提交前
特定 commit	`--commit <sha>`	`git show <sha>`	回溯定位 bug

重要限制：codex review 的范围选项（--uncommitted / --base / --commit）与自定义审查指令互斥——不能同时指定 --base main 和自定义 prompt。如需自定义审查指令，用 codex exec + 自然语言 prompt。

实战 1：审查未提交改动

写完代码，先自查再提交

你刚改完 auth.ts，还没 git add。在 TUI 中输入：

> /review

Codex 弹出范围选择菜单：

选择审查范围：
  ❯ Uncommitted changes  (当前未提交的改动)
    All branch changes   (当前分支 vs base branch)
    Last turn changes    (最近一轮的改动)

选择 Uncommitted changes，Codex 开始分析。审查结果以 inline comments 形式出现在 review pane 的对应行上：

审查发现（auth.ts 未提交改动）：

🔴 严重：第 42 行 token 过期时间硬编码（3600s），
   应从配置读取，否则不同环境行为不一致。

🟡 建议：第 67 行缺少对 null 的显式检查，
   当 user 为 undefined 时会抛出 TypeError。

🟢 风格：第 88 行变量名 `tmp` 过于模糊，
   建议改为 `sanitizedEmail`。

效果：在 git commit 之前发现问题，比在 PR 里被发现便宜 10 倍。

实战 2：CLI 审查分支对比

PR 提交前的终极检查

你在 feature/login 分支，准备提 PR：

$ git checkout feature/login

# 用 CLI 审查分支差异
$ codex review --base main

Codex 读取 main...HEAD 的完整 diff，输出优先级排序的发现：

审查结果：feature/login → main（12 文件，340 行改动）

🔴 严重（2）：
  - src/auth.ts:112 — SQL 查询使用字符串拼接，存在注入风险
  - src/api.ts:78 — 错误响应包含完整 stack trace

🟡 建议（3）：
  - src/utils.ts:45 — refreshToken 存入 localStorage，建议改用 httpOnly cookie
  - src/handler.ts:23 — N+1 查询，可批量预加载
  - src/types.ts:8 — 缺少 User 类型的 JSDoc

✅ 正面：
  - 密码哈希使用了 bcrypt，符合最佳实践

技巧：输出是自然语言文本，按优先级（🔴 > 🟡 > 🟢 > ✅）排序。不是结构化 JSON。

实战 3：审查特定 commit

回溯历史，定位问题源头

线上有 bug，怀疑是某次提交引入：

$ git log --oneline -5
a3f8b2c feat: add user profile page
c7d1e4f fix: update auth middleware  ← 怀疑这个
e2a9b1c refactor: extract helpers

# 审查该 commit
$ codex review --commit c7d1e4f

审查结果：c7d1e4f (fix: update auth middleware)

🔴 严重：移除了 token 校验的 try-catch，
   导致校验失败时直接 500 而非 401。

🟡 建议：新增的 rate limiter 没有单元测试覆盖。

技巧：配合 git bisect 使用——先二分定位问题 commit，再用 codex review --commit 分析根因。

自定义审查指令

用 codex exec 聚焦特定维度

关键限制：codex review 子命令的 --base / --commit / --uncommitted 选项不能与自定义审查 prompt 同时使用。需要自定义审查指令时，用 codex exec。

# 用 codex exec 传入自定义审查指令 + diff 内容
$ codex exec "$(cat <<'EOF'
请对以下 git diff 进行安全审查，重点关注：
1. SQL 注入或 XSS 漏洞
2. token 存储是否安全
3. 错误信息是否泄露内部实现

$(git diff main...HEAD)
EOF
)"

Codex 会按你的指令聚焦输出：

安全审查结果：

🔴 SQL 注入：第 112 行使用字符串拼接构建查询，
   应改用参数化查询。

🟡 Token 存储：第 45 行将 refreshToken 存入 localStorage，
   建议改用 httpOnly cookie。

原则：审查指令越具体，输出越有用。"看安全问题"不如"看 SQL 注入、XSS、token 泄露"。

审查指令模板库

拿来即用的审查清单

安全审查模板

codex exec "对以下 diff 做安全审查：
- SQL 注入、XSS、CSRF
- 敏感数据明文存储或传输
- 认证/授权逻辑漏洞
- 错误信息泄露内部细节

$(git diff --staged)"

性能审查模板

codex exec "对以下 diff 做性能审查：
- N+1 查询问题
- 内存泄漏（未清理的监听器、定时器）
- 不必要的重复计算
- 大数据量操作的复杂度

$(git diff --staged)"

可维护性模板

codex exec "对以下 diff 做可维护性审查：
- 命名是否清晰表达意图
- 函数是否只做一件事
- 是否有对应的单元测试
- 文档注释是否完整

$(git diff --staged)"

建议：把这些模板存成 Shell 脚本或 AGENTS.md 片段，需要时直接调用。

配置审查模型

用 review_model 指定审查专用模型

默认情况下，/review 和 codex review 使用当前会话的模型。你可以在 config.toml 中为审查指定一个不同的模型：

# config.toml
# 审查专用模型（不指定则用当前会话模型）
review_model = "o3"

为什么要单独指定？

开发时用快速模型（如 gpt-4.1-mini）
审查时切换到深度推理模型（如 o3）
兼顾日常效率与审查质量

AGENTS.md 定制审查行为

在 AGENTS.md 的 Review guidelines 部分编写团队审查规约，Codex 审查时会遵循：

## Review Guidelines
- 所有公共 API 必须有 JSDoc
- 禁止直接操作 DOM，使用框架抽象
- 数据库查询必须参数化

GitHub PR 自动审查

@codex review —— 团队协作的 First Responder

在 GitHub PR 中评论 @codex review，Codex 会：

审查流程

读取 PR diff 和仓库 AGENTS.md 规约
添加 👚 reaction 表示正在处理
聚焦 P0（严重）和 P1（重要）问题
以标准 PR review 评论形式发布
指摘直接挂在对应代码行上

自动修复

评论 @codex fix 可让 Codex 在权限范围内自动修复指摘的问题。

# 触发审查
@codex review

# 审查后触发修复
@codex fix

官方文档： Use Codex in GitHub

实战 4：CI 自动化

把 Review 嵌入 GitHub Actions

注意：codex review 输出的是自然语言文本，不是结构化 JSON。CI 中需用 grep/文本匹配判断是否有严重问题。

name: AI Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 完整历史，确保 diff 正确

      - name: Install Codex
        run: npm install -g @openai/codex

      - name: Run Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          # 审查分支差异，输出保存到文件
          codex review --base origin/main > review-output.txt 2>&1 || true
          cat review-output.txt

      - name: Check for critical issues
        run: |
          # 检查输出中是否包含严重问题标记
          if grep -qiE '(🔴|critical|严重|P0)' review-output.txt; then
            echo "::error::发现严重问题，请修复后再合并"
            exit 1
          fi
          echo "未发现严重问题，审查通过"

效果：每次 PR 自动触发审查，严重问题直接阻断合并。

CI 输出消费

审查结果如何驱动后续流程

codex review 的输出是自然语言文本，格式类似：

审查结果：feature/auth → main

🔴 严重（1）：
  - src/auth.ts:42 — token 过期时间硬编码

🟡 建议（2）：
  - src/api.ts:67 — 缺少 null 检查
  - src/utils.ts:12 — 变量命名不清晰

✅ 正面：
  - 密码哈希使用 bcrypt

消费方式

grep 关键词：检查 🔴 / critical / P0
写入 PR 评论：用 gh pr comment 发布
推送通知：发到 Slack / 飞书
归档日志：保存审查记录供追踪

把结果发到 PR 评论

# 把审查结果作为 PR 评论发布
gh pr comment $PR_NUMBER \
  --body "$(cat review-output.txt)"

多维度审查

用自然语言让 Codex 从多个角度审查

单一 Review 有盲区。你可以用自然语言提示让 Codex 的主 agent 从多个维度分别审查：

> 请从以下三个维度分别审查当前改动：
1. 安全性（注入、认证、数据泄露）
2. 性能（N+1 查询、内存泄漏、算法复杂度）
3. 可维护性（命名、测试覆盖、文档完整性）

Codex 主 agent 会自行决定是否分派子代理（Subagents）并行处理，然后汇总输出：

多维度审查结果：

【安全性】发现 2 个严重问题
  - src/auth.ts:112 — SQL 注入风险
  - src/api.ts:78 — stack trace 泄露

【性能】发现 1 个警告
  - src/users.ts:45 — N+1 查询

【可维护性】发现 3 个建议
  - 命名改进 ×2，缺少测试 ×1

关键：不需要手动 spawn 子代理。主 agent 收到多维度审查请求后，会自动编排——决定是否并行、如何汇总。

审查委员会工作流

主 Agent 编排，自动分派与汇总

实现方式：用户只需用自然语言描述审查维度，主 agent 自动完成编排。无需手动调用 codex spawn（此命令不存在）或 SDK 的 spawnAgent（SDK 无此方法）。Subagents 的分派是主 agent 内部行为。

app-server RPC（进阶）

review/start —— 程序化触发审查

Codex app-server 暴露了 review/start JSON-RPC 方法，用于在宿主应用中程序化触发审查。

{
  "jsonrpc": "2.0",
  "id": "review-001",
  "method": "review/start",
  "params": {
    "target": {
      "type": "baseBranch"
    }
  }
}

target.type 可选值

uncommittedChanges — 未提交改动
baseBranch — 分支对比
commit — 特定 commit
custom — 自定义审查指令

审查结果

review 模式的 raw output 通过 thread item 读取。审查不改写代码树，只产出发现。

注意：review/start 是 app-server 层 RPC，不是 CLI 命令。具体字段名和参数以 app-server schema 为准。大多数用户无需直接调用此 RPC——用 /review 或 codex review 即可。

Review 流程

从触发到结果输出

关键节点：范围选择 → diff 提取 → 审查 prompt 组装 → 模型推理 → 结果格式化 → 输出（文本 / inline comments / PR 评论）。

常见错误（一）

这些坑踩过一次就够了

错误 1：审查范围过大

症状：一次 Review 扔进去 5000 行 diff，输出一堆泛泛而谈的"建议"。

修复：拆分成小 PR，每次 Review 控制在 300 行以内。用 --commit 逐次审查。

错误 2：把 review 当自动修复

症状：指望 /review 自动改代码，结果发现它只报告不改代码。

修复：Review 是只读审查。发现问题后，另行发指令让 Codex 修复（或在 GitHub 用 @codex fix）。

错误 3：把 Review 当测试

症状：指望 Review 发现所有逻辑 bug，跳过写测试。

修复：Review 是补充，不是替代。单测覆盖逻辑，Review 覆盖意图。

常见错误（二）

CLI 使用中的常见陷阱

错误 4：选项与 prompt 混用

症状：运行 codex review --base main "检查安全问题"，报错或被拒绝。

修复：--base 和自定义指令互斥。需要自定义指令时用 codex exec。

错误 5：CI 中期待 JSON 输出

症状：CI 脚本用 jq 解析 review 输出，全部失败。

修复：review 输出是自然语言文本。用 grep 匹配关键词（🔴 / 严重 / P0），不要用 jq。

错误 6：审查指令与改动不匹配

症状：用"安全审查"指令审查纯 CSS 改动，AI 硬找问题。

修复：审查指令要与改动类型匹配。CSS 关注兼容性和响应式；API 关注参数校验和错误码。

经验法则：Review 的输出是"信号"，不是"命令"。最终决策权始终在你手里。

最佳实践

让 Review 真正有效的几个习惯

小步快跑

每次改动控制在 200-300 行以内，Review 效果最好。大 PR 拆成小 PR，每个小 PR 独立审查。

指令先行

在写代码之前，先想好"这次改动需要审查什么"。把审查指令写进 AGENTS.md Review guidelines 段。

人机协作

AI Review 先过一遍，解决明显问题；再交给人做深度审查，关注业务逻辑和设计决策。

持续迭代

记录每次 Review 的误报和漏报，调整审查指令。好的指令是用出来的，不是想出来的。

命令速查表

完整参考

场景	命令	说明
TUI 审查	`/review`	交互式选择范围，inline comments 输出
CLI 未提交	`codex review --uncommitted`	审查 staged + unstaged + untracked
CLI 分支对比	`codex review --base main`	等价 git diff main...HEAD
CLI 特定 commit	`codex review --commit <sha>`	审查指定 commit 引入的改动
自定义审查	`codex exec "审查指令..."`	用自然语言 + diff 做自定义审查
GitHub PR 审查	`@codex review`	PR 评论触发，P0/P1 指摘
GitHub PR 修复	`@codex fix`	自动修复审查指摘
查看 diff	`/diff`	TUI 中查看 Git diff

记住：codex review 的范围选项与自定义 prompt 互斥。需要自定义指令时用 codex exec。

总结

Review 不是终点，是协作的起点

本章要点

三种入口：/review（TUI）、codex review（CLI）、@codex review（GitHub）
三种范围：--uncommitted / --base / --commit
自定义审查指令用 codex exec（与 review 选项互斥）
Review 是只读审查，不改代码
输出是自然语言文本，不是 JSON
多维度审查用自然语言提示，主 agent 自动编排
用 review_model + AGENTS.md 定制审查行为

下一步去哪

第 12 章：CLI 与脚本化——把 Review 嵌入 pre-commit hook
第 7 章：深入 Subagents——理解主 agent 的编排机制
实践：在你的下一个 PR 中试试 @codex review

记住：AI Review 的价值不在于"发现问题"，而在于让你在合并之前多想三秒。这三秒，可能省去你三天的 debug。