已有原始安全发现需要去重合并时：按代码路径+标题+签名聚类…

在研究阶段产出原始安全发现之后、进入评审之前，把完全相同或高度重叠的发现聚类合并为单条记录，同时避免误删回归缺陷与同一文件不同行的不同缺陷。

适用场景

解决思路

1. 确定角色：如果本阶段从不读取目标源码（report/calibrate/reflect 类），视为 FINDINGS-ONLY 阶段——跳过定位解析的第 2-6 步，但仍从 state 读取 active_snapshot 用于溯源/标注，且绝不因为 code root 未设置就中止。
2. 按优先级确定 CODE_ROOT：(a) 本次调用传了 --target_root 就用它（权威，覆盖 SNAPSHOT_ROOT 与 state 回退，用于调用方交来的已准备树，例如打过补丁的影子副本）；(b) 否则若传了 --snapshot_root（或 SNAPSHOT_ROOT）就用它；(c) 否则读 state_root/workspace/.mantis_state.json 的 active_snapshot.root/.snapshot_id/.snapshot_pinned（state_root 来自 --state_root，否则为当前目录下的 ./workspace）；(d) 否则 CODE_ROOT = 当前目录，snapshot_pinned = false（MODE-OFF），不要中止。
3. 哨兵检查：仅当 snapshot_pinned 为 true 且未走 (a) 路径时，校验 CODE_ROOT/.mantis_snapshot_id 存在且等于 SNAPSHOT_ID，否则 STOP snapshot sentinel mismatch（--target_root 提供的树豁免此检查）。
4. 区分路径字段：SNAPSHOT-RELATIVE（在 CODE_ROOT 下读）包括 code_paths 条目与 plan 中作为文件路径的 target_files，只剥离尾部 :<digits>；含 :// 的 code_paths 是 URL/端点而非文件读取；非 <existing-path>:<integer> 形式的是符号/偏移/端点这类非源码 LOCATOR，只校验构件/符号存在，跳过所有行号区间与行存在性逻辑。
5. STATE-RELATIVE（只在 state_root/workspace 下读写，绝不加 CODE_ROOT 前缀）：kb_references、repro_file_path、reattack_file_path、helper 脚本、报告文件以及所有 state/findings JSON。
6. snapshot_pinned 为 true 时绝不写 CODE_ROOT；任何编译、生成或写产物的命令都必须在私有影子副本中运行（用 mktemp -d 从 CODE_ROOT 复制），绝不能以 cwd=CODE_ROOT 运行；只读检查可以 cd 进 CODE_ROOT。
7. VCS 元数据例外：历史日志提取与任何 VCS diff/blame 命令都在仍保有 .git/.hg/.repo 的 LIVE 仓库根运行，而不是 CODE_ROOT（快照副本已剥离 VCS 元数据）；不要因为 CODE_ROOT 缺少 .git/.hg/.repo 就中止。
8. 每条 shell 命令都使用绝对路径，并在该次调用中自行设置工作目录，不要假设工作目录在调用之间保持。
9. 当前 pass 校验：若存在 active_snapshot 且 active_snapshot.pass != state.pass_number，视为该 pass 的 STALE 快照，STOP stale active_snapshot: pass mismatch 或降级为 HALT（snapshot_pinned 实际为 false：无权威判定、Block B 走 NOT_MATCHED、reproduce 记 not_attempted）。
10. 加载原始发现：列出目录并读取 workspace/findings/ 下的文件；若目录为空或不存在，通知用户并退出。
11. 列目录/处理发现时忽略隐藏文件与目录（例如 .trash/ 子目录）。
12. 加载历次 loop pass 的归档发现 JSON：workspace/archive/findings_pass_*/*.json 与 workspace/archive/loop*_findings/*.json，它们代表上一轮已完整评估、分诊甚至已修补的漏洞。
13. 不要读取或对比 workspace/historical_learnings.jsonl（VCS 历史）来去重——目的是发现旧漏洞被重新引入的回归。
14. 循环去重（快照门控）：先用 .mantis_state.json 中的 active_snapshot.snapshot_id 给所有缺 discovery_commit 的当期发现打上该字段（未 pin 时跳过）。
15. 签名只用于把一对发现升级为候选对，其本身绝不能被当作硬 DUPLICATE/trash 依据：只有同时满足 ①按当期 code_paths + title 相似度、且 code_paths 按行包含（带尾部 :line）比对匹配，②当双方都有 signature 时两个 signature 相等，才算候选对；仅有 signature 相等而无 code_paths+title 一致时最多写软标记 possible_duplicate_of 并保持 ACTIVE；任一方缺 signature 则沿用 code_paths + title 相似度匹配。
16. 成对快照匹配检查（决定 MATCHED 还是 NOT_MATCHED）：比较当期发现的 discovery_commit 与归档发现的 discovery_commit（不是与全局 SNAPSHOT_ID 比）。
17. 成对检查第一步：若 snapshot_pinned 为 false 且 state 中没有 active_snapshot（MODE-OFF）→ NOT_MATCHED 并停止；HALT 模式（有 active_snapshot 但 snapshot_pinned=false）不要在此短路，继续走到成对比较逻辑（因当期是 live: id，必然 NOT_MATCHED）。
18. 成对检查第二步：任一 discovery_commit 缺失、为空或字面量 MIXED → NOT_MATCHED；两者不是逐字节相等 → NOT_MATCHED；两者逐字节相等（都存在且非 MIXED）→ MATCHED；不存在其他通往 MATCHED 的路径，绝不做模糊比较，缺字段即 NOT_MATCHED。
19. MATCHED 处理：把当期发现软删除为 loop 重复——设 status 为 DUPLICATE、duplicate_of 为 <archived_uuid>，清除 possible_duplicate_of，确保 mkdir -p workspace/findings/.trash/，移入其中，并在 workspace/.tx_log.jsonl 记一条 loop_filter 事务；若当期缺 lineage_id 而归档有，则先继承归档的 lineage_id 再移动。
20. NOT_MATCHED 处理：不要设 DUPLICATE、不要移入 trash；保持 ACTIVE 并设 possible_duplicate_of 为 <archived_uuid>（非终态提示）；若当期缺 lineage_id 而归档有，则继承其 lineage_id。
21. 遵守状态/重复不变量：同一目标 UUID 不得同时出现在 duplicate_of 与 possible_duplicate_of；status 为 DUPLICATE 不得与指向同一 UUID 的 possible_duplicate_of 共存；NOT_MATCHED（MODE-OFF 回退例外之外）下 status 必须保持 active（VALID/PROVISIONALLY_VALID/NEEDS_RESEARCH 之类），不得设 duplicate_of，不得移入 .trash/。
22. POSSIBLE REGRESSION：若归档命中项的已解决状态（patch_status ∈ {VERIFIED_SECURE, MITIGATION_PROPOSED} 或 status==FALSE_POSITIVE 或 production_viability==NON_VIABLE）且该对为 NOT_MATCHED，则保持当期发现 ACTIVE，追加 history 注记 POSSIBLE REGRESSION vs <archived_uuid>，不做过泸。
23. EXACT-UUID 重试例外：若当期发现与归档发现 UUID 完全相同，说明是被有意拷回重试，不要过泸，保持原样。
24. 永久未 pin 例外（仅 MODE-OFF，即无 active_snapshot）：回退到旧式去重——有 signature 用 signature，否则用 stable_key = normalized_title + 第一条 code_paths 条目（含尾部 :line，按行包含）；只有当 stable_key 的按行包含匹配也一致时才偏好 signature，绝不单凭 signature；存在 active_snapshot 但未 pin（HALT）时该例外不生效；POSSIBLE REGRESSION 优先于该回退。
25. 三级去重阶梯 Tier 1（快路径精确启发式锚点，<1ms、0 token）：① 精确内容身份签名匹配 hashlib.sha256(canonical_fp | canonical_cwe | target_symbol)（对行位移、反引号、标题改写不敏感）；② 精确 canonical_filepath + 归一化 CWE + target_symbol 匹配；③ target symbol 为空时在同一 canonical filepath 上的严格行邻近窗口（≤3 行）；命中即直接继承祖先 lineage_id，不调用 LLM 或 embedding。
26. Tier 2（RCA 归一化）：Tier 1 未产生精确锚点时，合成标准化 5 行根因分析摘要——Component（归一化 canonical filepath 与 symbol）、Vulnerability Class（规范 CWE 标识与名称）、Root Cause Mechanism（底层编程/逻辑缺陷）、Failure Condition（具体输入、状态或边界条件）、Taint Dataflow（source 到 sink 的数据流轨迹）。
27. Tier 3（向量嵌入与余弦相似度扫描）：用配置的 multi-provider embedding engine（默认 vertex_ai/gemini-embedding-001）把 RCA 摘要投影为稠密向量；对数据库中的历史 lineage_vectors 做有界余弦相似度最近邻扫描；执行 CWE Family & Class Structural Guard——对双方显式 CWE 做归一化，若属于不同且不兼容的 CWE ID 则直接跳过候选向量比较；正阈值 ≥0.90（可由 EMBEDDING_SIMILARITY_THRESHOLD 配置）时并入同一祖先 lineage_id；负阈值 <0.70 时 fail closed 并生成全新唯一 lineage_id。
28. 当前批次内去重：仅当两条发现共享同一条 code_paths 条目（按行包含，带尾部 :line）且 title 相同或高度相似时才判为重复并合并；同一文件不同行是不同缺陷，绝不合并。
29. 规模化的 Map/Reduce 分块：发现文件较多（如 >20 个）时，先按目标文件或组件分组，再检查重叠，以避免上下文窗口限制。
30. 省 token 的合并：不要在回复里手写或输出合并后的 JSON，先在内部把哪些发现映射到哪个 primary。
31. 写可复用确定性脚本 workspace/helpers/merge_findings.py，其第一行必须恰好是 # MANTIS_HELPER_VERSION = 2；复用已有 helper 前先 grep 其前几行确认该标记，标记缺失或整数不同（旧版本残留）就重新生成。
32. 脚本确定性合并规则——Title：取最全面、最具描述性的标题；ID：保留被保留 primary 发现的唯一 id；Severity：取合并项中最高的严重级别。
33. 脚本规则继续：Privileges Required 继承最严重者（NONE > LOW > HIGH）；Attacker Position 继承最关键者（EXTERNAL > INTERNAL_NETWORK > IN_CLUSTER > LOCAL > HOST_SYSTEM > SUPPLY_CHAIN > PHYSICAL_TEMPORARY > PHYSICAL_LONG_TERM）；User Interaction 继承最严重者（NONE > REQUIRED）。
34. 脚本规则继续：Code Paths 收集并去重所有文件路径与行号成单一唯一数组；Description、Mitigation、Impact 干净拼接。
35. 脚本规则继续：History 拼接并保留所有被合并发现的 history 条目，并追加一条符合 schema 的合并记录（含 stage 为 dedupe、action 为 merge、details 为 Merged duplicate findings: [comma-separated-ids]、pass_number 为当前 pass 号、timestamp 为当前 ISO8601 时间戳）。
36. 未知键与溯源（强制）：脚本必须把 primary 上每个未显式处理的键原样拷到合并对象（含 discovery_commit、repro_snapshot_id、patch_base_snapshot、possible_duplicate_of、signature、lineage_id、cwe），绝不丢字段；若两条发现的 discovery_commit 不同必须拒绝合并（它们描述不同代码版本），保持分离并记录拒绝；所有发现共享同一 discovery_commit 时原样保留。
37. 执行脚本，更新磁盘上的 primary 发现文件 workspace/findings/<primary_id>.json。
38. 事务化暂存清理：不要永久删除冗余文件；确保 mkdir -p workspace/findings/.trash/；移动前脚本先把重复文件设为 status 为 DUPLICATE、duplicate_of 为 <primary_uuid>，再把被合并的重复 .json 移入 workspace/findings/.trash/。
39. 每个被移动的文件都往 workspace/.tx_log.jsonl 追加一条事务记录，每行是自包含 JSON：{timestamp: ISO8601, action: loop_filter | dedupe_merge, primary_uuid: UUID（loop_filter 时为 null）, moved_uuid: UUID}，以便下游阶段使用并保留回滚能力。
40. 完成后通知用户。:
41. 完成后通知用户。
42. 完成后通知用户。

适用边界 · 注意事项

• 不用于初始代码审计或补丁生成；也不应用于读取 VCS 历史学习记录来挖掘缺陷（历史学习记录不参与去重，以便发现回归）。
• workspace/findings/ 不存在或为空时应通知用户并退出，不能继续去重。
• 当前 pass 与 active_snapshot.pass 不一致（快照 STALE）或哨兵不匹配时应停下，而不是继续合并。