LobeHub deep-review：reuse-architecture 重复实现发现的验证规则与爆炸半径决策

本文解析 LobeHub 仓库中 deep-review 代码评审技能针对 reuse-architecture（重复实现）类发现的验证附录：独立验证子代理如何基于“行为等价”三要素对重复代码候选发现做出 confirmed / false_positive / need_more_context 三分裁决，以及为何这类发现默认禁止自动修复、又在何种条件下可以例外。读完后你能复现从维度规则文件、验证子代理提示词到 zod 数据契约的完整执行链条，并理解该技能“反幻觉、反自我审批”的设计逻辑。

一、定位：deep-review 流水线中的“维度专属验证规则”

deep-review 是 LobeHub 仓库内置的多维度代码评审技能，入口定义在 SKILL.md。其两条核心原则直接决定了本文附录的存在方式：

1. 反幻觉：只看 diff 片段的评审代理会凭空捏造 bug，因此候选发现必须由一个阅读完整上下文的独立 verify 子代理逐条证伪，并返回三向裁决（confirmed / false_positive / need_more_context）——三向裁决优于置信度百分比，因为“听起来经过校准的分数作为硬性过滤器并不可靠”（见 SKILL.md）。
2. 反自我审批：刚写完代码的代理给自己的作业打分必然通过，所以评审与验证绝不能共用同一个代理（见 verify-prompt.md）。

验证子代理的提示词模板（verify-prompt.md）中有一个 {verification_addenda} 占位符，其实例化路由规则如下：当载荷中包含 release-risk 发现时注入 verification/release-risk.md；当载荷中包含 reuse-architecture 发现时注入 verification/reuse-architecture.md；两者都有则都注入，否则为 None（见 verify-prompt.md#L10-L13）。

也就是说，本文主题文件是一份按需动态拼入验证子代理提示词的“维度专属裁决规则”。它全文虽短，但每一行都是规范性条款：第一行划定适用范围，中间定义三向裁决的充分条件，最后两行定义 can_auto_fix 的默认值与唯一例外。

二、适用范围：只处理 reuse-architecture 去重发现

原文第一句即明确：“Apply only to reuse-architecture dedup findings.”（仅适用于 reuse-architecture 去重发现。）

这个“去重发现”由哪个环节产生？由 reuse 维度负责。dimensions/reuse-architecture.md 的 frontmatter 声明 id_prefix: reuse、verify: true，它是唯一要求全仓库搜索的维度——“绝不要只凭 diff 下判断”。其 Outward（查重）通道对发现有硬性要求：

• 对每个引入的行为单元，用“动作 + 上下文关键词”组合在仓库中 rg 搜索（如 window.open + popup、setInterval + poll、JSON.parse + storage）；
• 打开每一个命中结果，比较行为等价性；
• 只有当 existing_implementations 字段被填满（file:line 或 file:line-range，至少 1 条）时才允许上报（见 dimensions/reuse-architecture.md#L53-L56）。

这条“必须给出既有实现坐标”的规则不止写在提示词里，还被 zod 数据契约硬执行：validate-output.ts 的 superRefine 校验中，dimension === 'reuse-architecture' 且缺少 existing_implementations 的发现会直接校验失败。评审子代理的返回格式同样把该字段列为 reuse 去重发现的必备条件（review-prompt.md#L80）。

这正是验证附录的第一条规则之所以写“Open every entry”的原因：existing_implementations 是一个列表，可能包含多个候选既有实现，验证者必须逐一打开，而不是只看第一条就下结论。

三、核心验证流程：基于“行为等价”的三向裁决

原文给出的完整裁决标准如下：

Open every entry in existing_implementations with enough surrounding context to compare behavior:

• At least one implementation has equivalent input, output, and side effects → confirmed.
• All implementations are merely syntactically similar → false_positive, naming the semantic difference.
• Required context is unavailable → need_more_context.

三条规则对应三种裁决，各自的判定条件与产出要求：

裁决	触发条件	产出要求
confirmed	列表中至少一个实现与 diff 引入的实现在输入、输出、副作用三方面都等价	evidence 必须是文件 + 行号证据
false_positive	所有候选实现都仅是“语法上相似”	reason 必须点名具体的语义差异
need_more_context	所需上下文无法获取（如被引用的既有实现文件不存在、无法读取）	missing 字段说明缺什么

三个要点值得展开：

1. “行为等价”的操作性定义来自维度文件本身。 维度文件 Outward 通道第 4 步给出了等价性的判定口径：“same input → same output/side effect. Name/parameter differences still count as equivalent; syntactic similarity with different semantics does not.”（输入相同则输出/副作用相同即为等价；命名或参数不同仍然算等价；只有语法相似而语义不同的不算）（dimensions/reuse-architecture.md#L55）。这解释了为什么附录裁决的是 confirmed 而非 maybe：只要列表中任何一条命中即确认，重复成立。

2. false_positive 必须“点名语义差异”，禁止模糊否认。 这与验证子代理提示词的通用条款一致：confirmed 裁决要求文件与行号证据，“不确定性是 need_more_context，永远不是猜测式的确认”（verify-prompt.md#L58-L59）。对应的数据结构也强制了这一点：validate-output.ts 中 VerificationOutputSchema 用 z.discriminatedUnion('verdict', ...) 定义三种裁决，false_positive 必须携带非空 reason，need_more_context 必须携带非空 missing——字段互斥且不可省略。

3. 与 release-risk 附录的对照凸显本维度的特殊性。 verification/release-risk.md 的验证对象是具体技术事实（读实际 SQL、确认行为差异、复现调用点数量等），而 reuse 附录的验证对象是跨文件等价性判断——它的第一动作不是读 diff，而是“打开每一个 existing_implementations 条目并补足周边上下文”。这正呼应了技能总则中“反幻觉”原则：等价性无法从 diff 片段推断，只能从完整上下文确认。

四、can_auto_fix 判定：爆炸半径是核心论据

原文最后两句定义了本维度的自动修复策略：

Reuse-architecture findings default to can_auto_fix: false because caller migration changes the blast radius. A constant or single-import swap with no signature change may be auto-fixable when the evidence says why.

要理解这两句，先看验证提示词中 can_auto_fix: true 的通用四条件（verify-prompt.md#L61-L71）：

1. fix_cost 为 low；
2. 存在唯一一个显然的修法；
3. 不需要外部资源或产品决策；
4. 改动触碰少于 3 个文件，且不涉及架构层、数据库 schema、外部契约、用户可见行为、路由、热键、文案或权限边界。

reuse 发现为何默认不满足： 去重发现的修复动作不是“改一处”，而是“删掉 diff 新引入的重复实现 + 把所有调用方迁移到既有实现”。即使重复本体只在一个文件里，调用方迁移会把变更半径扩散到每个调用点——caller migration changes the blast radius 说的就是这件事：局部 diff 很小，但修复的实际影响面超出 diff 本身，因此默认违反第 4 条。

唯一的例外窗口： 当修复退化为“常量替换”或“单次导入替换”，且没有签名变化时——例如把 diff 手写的新字符串/数值换成仓库已有的常量，或把一处直接导入换成共享工具函数的导入——调用方不受影响、变更半径被限制在单点内，此时允许 can_auto_fix: true，前提是 the evidence says why：证据链必须说明清楚为什么这个替换不波及任何调用方。

这个“why”在数据契约中有明确落点：validate-output.ts#L104-L111 规定所有 can_auto_fix: false 的 confirmed 裁决必须携带 auto_fix_reason 字段，缺失即校验失败。也就是说，无论走默认路径还是例外路径，验证者都被强制写明推理。

与 release-risk 附录的对比能进一步标定 reuse 在技能体系中的位置：verification/release-risk.md 的最后一句是“Release-risk findings always use can_auto_fix: false”——无条件禁止；而 reuse 附录是唯一给出条件例外的验证附录，是全部发现类型中最接近“可自动修复”的一类，但仍然被爆炸半径论证严格约束。

渲染侧与之对应：只有 can_auto_fix 为真的发现才能进入报告的 Safe to fix now 区块，该区块的说明是“Single obvious fix, low risk, no product decisions”，且只接纳本变更引入（introduced）的发现、绝不包含遗留代码（report-template.md#L168-L172）。

五、数据契约：zod 如何强制这些规则被执行

deep-review 的产物不是自由文本而是结构化 JSON，validate-output.ts 提供 CLI 校验（Usage: validate-output.ts <review|verify|consolidate> [input-file]，见 validate-output.ts#L202）。与本附录直接相关的契约条款：

• 发现侧：ReviewIssueSchema 中 existing_implementations 字段本身是 optional，但 superRefine 在 dimension 为 reuse-architecture 时强制其存在（validate-output.ts#L54-L59）——保证验证者拿到的一定是一个非空的、可逐条打开的既有实现清单。
• 验证侧：VerificationOutputSchema 以 verdict 为判别键的三选一联合，恰好与附录的三向裁决一一对应（validate-output.ts#L113-L142）；confirmed 分支强制 evidence、can_auto_fix、blocks_release 字段，且 can_auto_fix: false 时强制 auto_fix_reason。
• 去重侧：全局整合通道（consolidate-prompt.md）声明“Two findings share a root only when one concrete fix resolves both”（只有一条具体修复能同时消解两条发现时才算同根）——这与附录的爆炸半径口径相互印证：影响面不同的修复不能被合并计数。

六、报告渲染：这些字段最终去向

report-template.md 规定了 verified 发现进入最终报告时的呈现方式，其中与 reuse 验证直接相关的条款：

• Existing implementations 行只为 reuse-architecture 去重发现渲染，并列出全部条目（report-template.md#L17 及 模板示例）——即验证者打开过的每一个 existing_implementations 条目都会出现在报告里，供读者复核等价性判断；
• 每条 confirmed 发现必须渲染 Blocks release 与 Likelihood 两行，这两值来自验证侧的 blocks_release 与 likelihood_override；
• can_auto_fix 为真的发现进入 Safe to fix now（report-template.md#L168-L172），为假的则只出现在对应严重级别桶中，由人决定修复时机。

七、验证者自检清单

处理一条 reuse-architecture 去重发现时，可以按以下条目逐条自查——即附录全部规则的展开：

1. 是否打开了 existing_implementations 的每一条（而非仅第一条）？
2. 是否对每个候选都从输入、输出、副作用三个维度做了等价比较？
3. 判 false_positive 时，reason 是否点名了具体的语义差异（而不是笼统的“看起来不一样”）？
4. 上下文缺失时，是否降级为 need_more_context 并在 missing 中说明缺口，而不是猜测式确认？
5. can_auto_fix 是否默认取 false，且 auto_fix_reason 已写明理由（缺失会过不了 zod 校验）？
6. 只有当修复是“常量/单次导入替换且无签名变化”时，才考虑 can_auto_fix: true，并在 evidence 中说明为什么调用方迁移的爆炸半径为零。

这套规则把“发现重复代码”这件看似机械的事拆成了可审计的三段：证据采集（评审侧必须给出既有实现坐标）→ 行为等价裁决（验证侧三向分类）→ 修复半径评估（can_auto_fix 与 auto_fix_reason）。每一段都有对应的 zod 契约兜底，使 deep-review 在 reuse 维度上的结论可复核、可追溯，而非模型的主观印象。