parallel-review — 三引擎并行代码审
这个 skill 解决什么
一个模型审代码有盲区。Codex(OpenAI)强在跨函数追数据流的语义正确性(值在哪加载 vs 在哪用、NaN/None 击穿判定、数据源错配);内置 code-review(Claude 7-angle)强在逐行广度 + 复用/简化/设计深度。两者抓到的 bug 往往几乎不重叠——这就是并行的理由,不是冗余。本 skill 把三条腿真正并行跑,再做收敛分析:多边点名的发现可信度最高,只有一边抓到的是其他引擎的盲区补丁。
第三腿 DeepSeek(claude -p 裸配置 + DeepSeek 芯,即「双模型异源」——模型血统独立于前两家,harness 与 Claude 同源)成本几乎为零(flash $0.03/任务量级),三方收敛把最高置信信号再抬一档;其独有发现按「独有打折」处理(见第 5 步),对冲它假阳性偏高的短板。
价值不在「跑两次」,而在收敛分析——所以最后那一步不能省。
工作流
第 0 步 — 定范围(先扫,必要时才问)
先看 diff 多大、跨不跨线:
git diff --stat "<base>...HEAD" 2>/dev/null | tail -1
<base> 解析顺序:当前分支的上游 PR/MR 目标分支 → repo 默认分支 → git symbolic-ref refs/remotes/origin/HEAD → main / master。
判定: 如果 diff 干净小(≲ 800 行 且 ≲ 15 文件 且 看起来是单一主题),直接进第 1 步审全 diff。如果跨多条不相关的线、或超阈值,用 AskUserQuestion 让用户选范围——别盲目审全 diff。理由:实战里 base...HEAD 经常累积多条线(一条分支同时挂着 A 功能 + B 重构 + C 实验),全审会让三个引擎都被无关代码稀释,真正想审的「刚写完那批」反而被淹没。
问范围时给具体选项:最近 N 个 commit 的主线、某子目录、工作区未提交改动、或全 base...HEAD。把范围确定为一个 <base> + 一组文件路径(可空),后面三条腿都用这同一个范围,保证可比。
第 1 步 — 检查 Codex 可用
command -v codex && \
( [ -n "$CODEX_API_KEY" ] || [ -n "$OPENAI_API_KEY" ] || [ -f "${CODEX_HOME:-$HOME/.codex}/auth.json" ] && echo AUTH_OK || echo NO_AUTH ) && \
codex --version
没装或没 auth:告诉用户怎么修(codex login / npm i -g @openai/codex),Codex 腿缺席(不阻塞其他腿,降级组合见「边界与默认」)。版本 0.120.0/.1/.2 有 stdin deadlock,若命中提醒升级(非阻塞)。
同时检查 DeepSeek 腿可用:
[ -f ~/.deepseek-personal.env ] && grep -q '^DEEPSEEK_API_KEY=..' ~/.deepseek-personal.env && echo DS_OK || echo DS_MISSING
DS_MISSING → DeepSeek 腿缺席,明说并继续(不阻塞)。⚠️ 数据出境红线:diff 含真实健康分数 / 用户数据 → DeepSeek 腿直接跳过(数据会发 DeepSeek API),标「DS SKIP(出境红线)」。
第 2 步 — 三条腿真正并行启动
同一个回复里发起,让它们并发跑:
腿 A(Codex,异源) — 后台 bash 调 bundled 脚本:
bash ~/.claude/skills/parallel-review/scripts/run_codex_review.sh \
/tmp/parallel_review_codex.txt "<base>" <file1> <file2> ...
用 run_in_background: true。脚本已封装:直连 codex CLI 跳过 gstack onboarding、构造限定范围的 diff、加 filesystem boundary、high effort、read-only。结果写 /tmp/parallel_review_codex.txt,stderr + 退出码写 .err。不要手写 codex 命令——脚本是单一真值源。
腿 B(内置 code-review 编排,同源) — invoke 内置 code-review,把范围当参数传:
Skill(code-review) with args: "<base>..HEAD <file1> <file2> ..."
invoke code-review 会把它的 7-angle 编排指令(3 correctness + 3 cleanup + 1 altitude → verify)注入给你(主 agent)——finder 由你自己 spawn 执行,不是某个内置 agent 在后台自跑。当前 harness 下「invoke 内置 code-review」与「内联 spawn finder」是同一条路,不分主/备:按 references/inline-finders.md 的编排跑——3 个 finder 覆盖 7 angle → verify → JSON findings。关键坑:finder 子代理必须用 general-purpose,不要用 bug-analyzer——实测 bug-analyzer 的第一个 Bash 常被权限系统拒、0 产出。
腿 C(DeepSeek,双模型异源) — 同一回复里第三个后台 bash:
bash ~/.claude/skills/parallel-review/scripts/run_deepseek_review.sh \
/tmp/parallel_review_deepseek.txt "<base>" <file1> <file2> ...
同样 run_in_background: true。脚本已封装:claude -p --bare 裸配置(无 hooks/plugins/注入,零副作用已实测)+ DeepSeek 端点 env 覆写 + 只读工具白名单 + per-file 分片并行(每个文件一个独立会话,900s/100 轮,墙钟 ≈ 最大文件的耗时);模型名活口径读 ~/.deepseek-personal.env 的 DEEPSEEK_REVIEW_MODEL(缺省 deepseek-v4-flash)。
为什么分片:实测 flash 审单文件 303 行需 332s 且质量好(抓到另两腿都漏的缺陷),但 6 文件 1.4k 行一次性必烧穿(两轮 420s/80+120 轮全撞墙、零产出)——它 agentic 强会逐个 Read 文件、verbose、且无视「别读周边文件」这类负向约束(实测两次)。分片只收窄「审查目标」,它在单文件模式下照样跨文件追数据流。输出里 SHARDS_OK=n/m 是本轮实际覆盖率,未覆盖的文件必须在报告里点名(SHARD_FAILED 的文件本轮等于没审)。不要手写命令——脚本是单一真值源;其 prompt 与腿 A 完全镜像(多样性由血统提供,不由任务书提供),改任一边 prompt 必须两边同步。
三条腿都跑同一个 <base> + 文件范围,结果才可比。
第 3 步 — 收集三方输出
Codex 后台完成后会有任务通知。读结果(注意 flush 延迟,0 行时稍等再读):
cat /tmp/parallel_review_codex.txt # [P1]/[P2] findings
tail -3 /tmp/parallel_review_codex.txt.err # 确认 CODEX_EXIT=0
cat /tmp/parallel_review_deepseek.txt # 首行 MODEL_USED=<实际用芯>、SHARDS=m、末行 SHARDS_OK=n/m,中间按文件分段
tail -3 /tmp/parallel_review_deepseek.txt.err # 确认 DS_EXIT=0 与 DS_SHARDS_OK
内置 code-review 的 JSON findings 直接在它的返回里。
第 4 步 — verify(关键发现亲自核实)
行号可信度不一:Codex 与 DeepSeek 腿的 file:line 通常准(都读了真实文件);finder 子代理的行号常漂(描述时偏移,见过 117 行的文件被标 1278 行)。所以以代码为准,别照抄 finder 行号。
对每个独有的、且标 P1/严重的发现,亲自 Read 相关代码段确认它 constructible from code(能从代码构造出失败场景),再下结论 CONFIRMED / PLAUSIBLE / REFUTED。三方收敛与 Codex+Claude 两方收敛已互证,可略过深 verify;含 DeepSeek 的两方收敛仍按独有打折的 verify 判据走——DS 假阳性偏高,与 finder 的假阳性碰巧相撞并非不可能。recall 偏向:realistic 的 race / 罕见路径 nil / falsy-zero / 边界 off-by-one 默认 PLAUSIBLE,不要因为「依赖运行时状态」就 refute。
第 5 步 — cross-model 收敛分析(核心产出,不可省)
这是 skill 的灵魂。进「最终裁决」区前确认「仅 DeepSeek 抓到」的发现都过了独有打折 verify(判据见下方收敛分析条目)。按以下结构呈现:
## 这次并行审核:执行了什么
(实际引擎组合 + 各腿 MODEL_USED、各跑了什么范围、各出多少 P1/P2、GATE 结果、降级与否)
## Codex 原文(verbatim)
(Codex 的 [P1]/[P2] 逐条原文——内置 code-review skill 协议要求 codex 输出 verbatim 呈现,不改写不截断)
## Cross-model 收敛分析
- **三方都抓到(最高置信)**:逐条列,标「Codex [Px] + Claude(angle) + DS [Px] 收敛」
- **两方收敛(次高)**:逐条列,标注哪两方
- **只有 Codex 抓到(全异源价值)**:通常是跨函数数据流型 bug,附 verify 结论
- **只有内置 code-review 抓到(广度/设计)**:通常是逐行 + cleanup/simplify/altitude
- **只有 DeepSeek 抓到(独有打折)**:独有 ≠ 收敛。🔴 STOP——默认降一档([P1] 按 [P2] 呈现),未经主 agent 亲自 Read 代码 verify,**不得进入最终裁决区**。verify 判据 = 能从代码写出「什么输入/状态 → 走到哪段代码 → 产生什么错误结果」的完整链条(recall 偏向同第 4 步:realistic race / 罕见路径 nil / falsy-zero / off-by-one 默认 PLAUSIBLE,不因依赖运行时状态就 refute);verify 通过才可保级,不过进附录
- 一句话定调:各方盲区差异说明并行的价值在哪
## 最终裁决(按 置信度 × 严重度 排序)
(🔴 三方收敛 P1 → 🔴 两方收敛 P1 → 🔴 独有已 verify P1 → 🟠 中等 → 🟡 cleanup/altitude)
每条带证据:file:line + 具体失败场景。
呈现纪律:高密度、每论断带 file:line + 具体场景、结论一句话定调、不堆术语不打类比(贴合本项目工程汇报风格)。这是审查发现的呈现,不是替用户改代码——除非用户明说要 --fix。
失败模式(if-then,跑前过一遍)
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| codex 未装 / NO_AUTH / CODEX_EXIT∈{2,3,4}(2=非 repo,3=未装,4=auth) | 按 .err 首行诊断(codex login / 装 CLI) |
腿 A 缺席 →「双引擎(Claude + DeepSeek)」 |
| CODEX_EXIT=124(600s 超时,codex 最常见失败态) | 手动窄化重跑一次(缩文件范围) | 仍 124 → 腿 A 缺席标 SKIP(超时) |
| DS env 缺失 / key 空(DS_EXIT=3)/ 出境红线命中 | 补 ~/.deepseek-personal.env(红线命中则直接 SKIP) |
腿 C 缺席 →「双引擎(Codex + Claude)」 |
部分分片 124 超时(SHARDS_OK=n/m,n<m) |
不影响其他分片;报告里点名未覆盖的文件 | 该文件本轮等于没审,需要就单独重跑它 |
| 全部分片失败(DS_EXIT=1,SHARDS_OK=0/m) | 检查 key 与网络;高峰段错峰重跑 | 腿 C 缺席 →「双引擎(Codex + Claude)」 |
| DS exit 0 但某分片只有段标题无内容 | 按该文件空产出处理 | 该文件标缺席,不算「无发现」 |
| 腿 B finder 返回空 / 非 JSON | 重派一次(仍用 general-purpose) |
仍空 → 腿 B 缺席显式标注 |
| 三腿全挂 | 中止收敛分析 | 如实报告零引擎完成,绝不出「审过了」 |
| 北京 14-18 点高峰段 | DS 超时概率实测偏高,预期它可能缺席 | 错峰重跑或接受双引擎降级 |
边界与默认
- 只读审查:默认不动代码。要修等用户明确说。
- 范围一致:三条腿必须同范围,否则收敛分析不可比。
- 降级透明:任一腿缺席都明说,报告头写实际组合——Codex 缺席 →「双引擎(Claude + DeepSeek)」;DeepSeek 缺席 →「双引擎(Codex + Claude)」;只剩 Claude →「单引擎」。绝不假装满编。
- 不写过程痕迹进对外材料:跟 four-source-review 一样,审到的结论照常用,但「跑了并行审」这个动作本身不写进 summary / 简报 / 飞书对外稿(用户的 QA 过程习惯,不对外)。
- 跟 four-source-review 分工:代码 diff → 本 skill;spec / 设计文档定稿 → four-source-review。
不要做(反例黑名单)
- ❌ 手写腿 A / 腿 C 命令绕过脚本——auth / timeout / MODEL_USED 回显全在脚本里,绕过即裸奔。
- ❌ 只改一边的 review prompt——腿 A / 腿 C prompt 镜像,改动必须两边同步。
- ❌ 任一腿缺席还按满编组合出报告——报告头必须写实际引擎组合与 MODEL_USED。