review — 把 Code Review 做成 Agent 的一等公民

简介

AI review 的难点不是再多一个模式，而是范围是否完整、reviewer 是否独立、问题是否有证据，以及修复后何时停止。@piex-dev/review 把人类入口收敛为一个 /review：用紧凑菜单选择默认分支 PR 范围、working tree、staged、指定 base/commit/file 或自定义关注点，再在隔离的 Pi SDK session 中评审，并按风险自动选择一个 reviewer 或 lead + specialist。

技术原理

Review = 冻结范围 + 独立判断 + 证据裁决。核心洞见：更多 reviewer 不等于更可靠。普通改动单审以控制成本和噪声；只有安全、数据、并发、跨仓契约或大 diff 才增加一个专项 reviewer，最后仍由 lead 合并裁决。

/review → 选择范围并冻结 base/head/diff → 物理剔除噪声
→ 新建只读 reviewer session → 风险路由 1→2
→ 实时展示阶段、模型、thinking level 与工具活动
→ 按需打开安全 reviewer transcript
→ submit_review → 复核 diff，变化时自动刷新一次
→ evidence gate → PASS / NEEDS FIX
→ 持久化 finding 状态，供 re-review 使用

/review 打开一层范围菜单；review 工具不打开菜单，默认使用 auto，并为 agent 和脚本保留 diff、staged、branch、commit、file 参数。相同 diff 直接返回缓存；变化后优先验证旧 finding。

Re-review 持久化规范化后的开放 finding 集合。旧 finding 只有在带有非空理由的 resolved、invalid 或 superseded 状态下才会关闭；否则保持 still_open 并跨轮保留。重复 ID 或旧格式记录会规范化为一个候选，优先保留更高优先级， 优先级相同时再保留更高置信度；旧 P0/P1 不能仅靠改报 P2 绕过阻塞门槛。

使用说明

安装

pi install npm:@piex-dev/review

仓库源码：extensions/review

前提条件

当前目录是 git 仓库（或通过参数指定任意 git 仓库路径），本机有 git。

用法

/review
/review ../piex
/review "../piex" "../oh-my-pi"

支持 Pi 的 @path、autocomplete 引号和相对/绝对路径。多仓路径逐个校验并按 git 根去重；任一无效就汇总错误并中止。默认分支按 origin/HEAD、init.defaultBranch、main/master/trunk 解析，在本地计算 merge-base，不隐式 fetch。

仓库解析完成后会选择默认分支 PR 范围、working tree、staged、自定义 base，以及单仓可用的指定 commit/file；也可为默认 PR 范围附加自定义关注点。多仓菜单会隐藏 commit/file，选定的其它范围统一应用到所有仓库。取消菜单或后续输入会直接退出，不启动 reviewer。

高级工具的 commit 范围以目标提交的第一父提交为基线，因此 merge commit 只展示该次合并相对第一父提交引入的内容；根提交相对 Git 空树评审。

• NEEDS FIX：有证据充分的 P0/P1，修复后再次 /review
• PASS：没有阻塞 finding；P2 是 advisory，不要求无限循环
• cached：scope 与 diff 未变化，没有重复调用 reviewer

实时进度与 reviewer transcript

交互式 TUI 的 /review 只在编辑器上方显示实时面板，避免与状态栏重复；非 TUI UI 会回退为状态栏紧凑摘要：

Review · 00:31 · reviewing
● lead · openai-codex/gpt-5.6-sol · thinking xhigh · fast · reading src/reviewer.ts · 3 tools
● specialist/security · openai-codex/gpt-5.6-sol · thinking max · fast · reasoning about changes · 2 tools

面板会随 preparing、reviewing、adjudicating、validating、changes detected; restarting 等阶段，以及读取源码、搜索、检查冻结 diff 和提交报告等活动更新。并行运行时，先完成的 reviewer 会立即显示 ✓ … done，不会等待另一个 reviewer，也不会被尾随事件改回 running。通过 review 工具调用时，同一份结构化快照会经 onUpdate 返回；最终报告会保留实际 reviewer 模型、thinking level 和 Fast mode 状态。启用时，进度、transcript 与最终报告都会标记 fast。

reviewer 完成后会重新采集同一范围的 diff。若 hash 已变化，第一次结果会被丢弃，扩展自动切换到最新快照并重跑一次，同时更新进度和 transcript 的范围摘要，并只保留最新一轮 reviewer 状态；只有第二轮期间 diff 仍继续变化时才会失败并提示等待编辑完成。这样不会返回针对旧代码的报告，也不会因为一次并发保存或格式化就要求用户手动重新执行 /review。

在交互式 TUI 中，/review 会在后台执行并立即交还输入框。review 运行期间可直接输入 /review-log，也可按 Ctrl+Alt+R，两种方式都会打开铺满终端窗口、实时且可滚动的 transcript 浮层；完成后再次运行 /review-log 可回看最近一次记录。浮层复用主 Agent 当前 Pi 主题的语义配色：header、阶段、工具标题和 prompt 元数据分别使用 accent、muted、success/error、toolTitle 等 token，prompt 内嵌 diff 与 review_diff 使用增删/上下文色；工具参数和结果元数据只轻量区分 JSON 键、数字和标点，大段字符串使用主 Agent 的 toolOutput 正文色，不会整片显示为错误红色；read 按文件扩展名识别 TypeScript、Python、Rust 等源码语言，无法识别时保持普通代码色，不做不可靠的自动猜测。浮层支持用 Tab 切换 lead 与 specialist，方向键或 j/k 滚动，G 回到末尾并恢复自动跟随，q/Esc 关闭。

transcript 记录任务 prompt、assistant 可见文本、工具调用与结果摘要、阶段/重试状态和最终 submit_review，但不采集原始 thinking/reasoning。记录进入内存前会递归脱敏 secret/token/password 等字段与常见凭据格式，并限制单条文本、序列化值、集合深度、条目数和 UI 渲染行数。它不写入作者主 session，也不落盘，/reload 或进程退出后清除。

长工具结果会在 JSON 值内部截断并标记 [TRUNCATED]，保留合法 JSON，因此保留下来的源码和 diff 仍能按原始换行高亮。浮层按条目缓存高亮和自动换行结果，流式更新只处理变化部分；另一位 reviewer 的活动不会使当前页面缓存失效。窗口宽度变化只重新换行，主题刷新会清空缓存，淘汰的日志条目也会同步释放。

可选配置

默认使用当前模型。需要固定模型或开启 Fast mode 可写 ~/.pi/piex-dev/review/settings.json：

{
  "model": "openai-codex/gpt-5.6-sol",
  "thinkingLevel": "xhigh",
  "fastMode": true,
  "specialistModel": "openai-codex/gpt-5.6-sol",
  "specialistThinkingLevel": "max",
  "specialistFastMode": true,
  "maxReviewers": 2
}

thinkingLevel 与 specialistThinkingLevel 分别控制主 reviewer 与专项 reviewer，接受从 off 到 max 的 Pi 等级；专项等级未配置时继承主 reviewer。同一 scope 中，显式配置的 model / specialistModel始终优先；只有未配置对应模型时，re-review 才沿用首次记录的 reviewer 模型。maxReviewers 只接受 1 或 2。

fastMode 控制 lead，specialistFastMode 控制专项 reviewer；专项值缺省时继承 fastMode。设为 true 时，扩展向该独立 reviewer 的请求注入 service_tier: "priority"。该能力仅支持 openai-codex provider、openai-codex-responses API、ChatGPT OAuth，以及 gpt-5.4、gpt-5.5、gpt-5.6-sol、gpt-5.6-terra、gpt-5.6-luna、gpt-6-astra 模型；其他组合会在 reviewer 启动前报配置错误，而不是静默降级。reviewer 是独立 session，不会继承外层 /gpt-fast 状态，需要通过这两个字段显式配置。fast 标记表示扩展已启用请求注入，并非服务端确认；Pi 的本地成本遥测仍可能按标准 tier 估算，后端额度记录才是最终依据。

注意：ultra 不是 Pi thinking level。GPT-5.6 Sol 模型说明列出的最高 API reasoning.effort 是 max；Codex Ultra 使用 maximum reasoning，并可能额外运行 agent，见 OpenAI Model guidance。因此，max 是本扩展可传给单个 reviewer 的最高档，不等于完整的 Codex Ultra 模式；配置中的 ultra 会被忽略。

验证

pi -e ./extensions/review/src/review-v2.ts -p "what is 1+1" --no-session

实现方案

实现按 scope、diff、reviewer、finding gate、session state 与 render 分模块。噪声在 diff chunk 层物理剔除；范围冻结 base/head OID 与 changed ranges。reviewer 返回后会重新采集 diff 并比较 hash；一次变化会触发基于最新快照的有界自动重跑，若重跑期间仍变化则停止，避免返回过期结果或无限消耗模型调用。每个 reviewer 是新的内存 session，关闭 extensions/skills/templates/themes 与自动 system/context 注入；仓库约束改由只读工具显式读取，不能覆盖 reviewer 的系统角色。工具仅有 read/grep/find/ls、精确读取冻结 patch 的 review_diff 和强类型 submit_review。reviewer 被明确要求将其作为最终工具批次的唯一调用；成功提交会返回 terminate: true，让该批次直接结束，不再额外请求模型一轮。reviewer 不能写文件或运行命令。

主流程订阅每个独立 session 的生命周期、消息类型与工具执行事件，并归约成按 reviewer 角色隔离的进度快照。并行 lead/specialist 不会互相覆盖；完成状态不会被尾随 activity 改写，只有进入 adjudication 时的显式新一轮事件才能重新激活 lead。每秒 heartbeat 即使在长时间 reasoning 期间也会刷新耗时。路径在展示前会移除控制字符并截断，grep pattern、thinking delta 与 text delta 不进入紧凑进度输出。

同一事件流还会写入独立的有界内存 transcript store。只有 text_delta 的可见文本会按 reviewer 与阶段合并；thinking_delta 被显式丢弃，工具参数和结果先脱敏再截断。每轮记录带 run ID，迟到的旧轮事件不能污染新 review。TUI 浮层订阅 store 变化并实时刷新，滚动离开末尾时暂停自动跟随，回到底部后恢复。

交互式 /review 把长时评审放进受控后台任务，使 Pi 主输入循环立即恢复，因此运行中的 /review-log 能被即时分派。后台任务使用独立 AbortSignal；退出、/reload 或切换 session 时，session_shutdown 会先取消任务并等待 reviewer 清理。命令入口与工具入口仍共享执行门禁，不会同时写入同一份 transcript。

Diff 文件路径先按仓库相对路径精确匹配；只有精确匹配失败时，才把开头的 a/ 或 b/ 当作 Git 展示前缀，因此真实的顶层 a、b 目录不会被映射到错误文件。

Evidence gate 要求 finding 属于冻结仓库与文件、命中 changed hunk、由 patch 引入，且具备 trigger/impact/evidence；P0/P1 置信度至少 0.8，P2 至少 0.75，旧 blocking finding 按最终生效的优先级校验。候选按稳定 ID 与语义键规范化；PASS / NEEDS FIX 和摘要都从门禁后的当前 finding 与开放集合生成，不直接复用 reviewer 原始摘要。安全、数据、并发、跨仓或大 diff 才路由第二个 specialist；lead 与 specialist 并行，最终由 lead 合并裁决。

设计参考

核心取舍：简洁是外部 API，复杂度留在内部编排。/review 只暴露一层范围选择；并行 reviewer、模型与裁决细节仍由风险路由处理。

迭代记录

路线图

版本记录