并行深读流水线（Step 5.5 操作手册）

目的：让 whole-project 审查达到全库覆盖 ≥85% 且高风险 ≥95%（双目标 gate="both"，文件数口径）且每个深读文件通过三件套质量门禁（单元完整性 / 行覆盖 / 防伪抽验）。核心：主上下文不逐文件深读，改用并行 explore 子代理分组深读，每个子代理返回「深读确认清单 + semantic_units + read_ranges + findings（带 file:line 证据）」，结果落盘给聚合脚本校验。

〇、三件套质量门禁（V2.1，每个深读文件必须通过）

#	门禁	定义	阈值	角色	防伪性
①	单元完整性	`semantic_units` 与图谱单元节点差集 = 空	100%（硬）	防漏读（跳过后半段）	引擎/脚本自动核验
②	行覆盖	`union(read_ranges)` / 真实行数	≥95%	防"每单元只读一行"	低（自报粒度）
③	防伪抽验	主代理回读抽样单元	每组 2 文件 × 2-3 单元/文件，每波 ≤40 次	防假读（抄清单不读）	唯一防假读手段

判定规则：

① 单元被覆盖 = 图谱单元 [ls,le] 与上报 semantic_units 中某 range 精确匹配（优先）或重叠 ≥80%（兜底），且该单元 ≥80% 行落在 union(read_ranges) 内；一个上报 range 只能匹配一个单元（one-to-one），宽 range 无法覆盖多个单元。
巨型文件豁免 ①：单元数<3 或 最大单元行占比>80%（如 migrations.rs run_migrations 6200/6331=98%）→ 该文件仅按 ② 行覆盖校验，引擎/脚本返回 unit_exempt_files。
② 分母 = 真实文件行数（读取源文件，非图节点 line_end——已验证 ±1 偏差），行数缓存。
③ 预算：每波 ≤40 次 read（每波 4-6 组 × 2 文件 × 3 单元 ≈ 24-36，留余量）；每组抽 2 文件、每文件抽 2-3 单元回读比对 note；抽到假读 → 该组重读并升级抽验率。结果必须落盘 spot_check_<batch>.json 并在 Step 8 聚合注入 review_data.spot_check（顶层字段），否则报告渲染"防伪抽验：未执行 🔴"且 verify-spot-check.ps1 exit 1。

诚实声明：引擎无法防假读。① 防漏单元、② 防读不全、③（抽样）才是唯一防假读的手段，且为预算化而非全量。verify-spot-check.ps1 只能验证抽验声明完整性（抽了、单元数>0、range 落在 read_ranges 内），无法验证主代理是否真读了文件。

一、分组规则

以 AuraSpace 实测分组表为基准（约 508 源文件 → 14-16 组，每组 ≤40 文件）：

#	组（目录）	约文件数	子代理职责
1	`server/src/api`（1/2）	30	后端 API 层前半
2	`server/src/api`（2/2）	31	后端 API 层后半
3	`server/src/services`（1/2）	33	核心业务服务前半
4	`server/src/services`（2/2）	33	核心业务服务后半
5	`server/src/domain`	43	领域模型/DTO
6	`server/src/deepwiki` + `infrastructure`	25	DeepWiki + 基础设施
7	`server/tests` + `bin` + `models`	14	测试与工具二进制
8	`web/src/views`（1/2）	34	前端视图前半
9	`web/src/views`（2/2）	33	前端视图后半
10	`web/src/components`（1/3）	38	前端组件（issues/evm/ci）
11	`web/src/components`（2/3）	38	前端组件（docs/wiki/time-log/settings）
12	`web/src/components`（3/3）	37	前端组件（ppt/agent/opencode/common/ui）
13	`web/src/store` + `utils` + `api`	31	状态管理/工具函数/API 客户端
14	`web/src/hooks` + `services` + `generated` + `web/tests`	大	前端其余（可分 2 组）

实际以 deep_read_plan_tool(gate="overall", target_coverage=85, include_prior=True) 返回的 groups 为准（引擎按风险权重贪心 + 目录分组，数量随仓库变化）。每次并行派发 4-6 个子代理，其余排队分批，避免 MCP 并发压力与上下文风暴。

二、子代理 Prompt 模板（V2.1，含三件套协议）

对每个组派发如下 prompt（替换 <GROUP> / <FILE_LIST> / <输出目录> / <临时输出文件>）：

你是一个代码审查深读子代理。请深读以下 <GROUP> 组的全部文件：

<FILE_LIST（每行一个相对路径）>

要求：
1. 逐文件用 read 读取完整内容（文件大则分段读），**不要跳过任何文件**。
2. 对每个文件，从八个类别审视：interface / business / data / utility /
   error handling / security / performance / observability，并叠加
   CRITICAL 子轮：SQL 与数据安全、竞态条件、LLM 输出信任边界、Shell 注入、枚举完备性。
3. 只报告**真实问题**（严重度 blocker/major/minor，置信度 1-10）。
   每条 finding 必须含 file:line 证据（实际读取到的行），没有证据视为未深读。
4. 良好实践、无问题的文件，在 deep_read 确认清单中标注，不产出 finding。
5. **每个文件必须填写质量字段**（这是硬性要求，缺失视为未深读）：
   - total_lines: 文件真实总行数（从 read 输出得知）
   - read_ranges: 实际读取的行区间数组 [[s,e],...]（分段读即天然区间），
     闭区间，并集应覆盖你读过的每一行
   - semantic_units: 你实际读过的每个语义单元（函数/类/接口）摘要，
     {"range":[s,e],"kind":"Function|Class|Test","name":"<符号名>","note":"<≤60字摘要>"}
     **严格模式（强制）**：必须**逐一列出该文件图谱中的全部语义单元**，
     包括：
     - 所有 Function（含私有/辅助小函数）
     - 所有 Class / interface / Type（含 Props 接口、仅数行的小接口——如
       `MermaidBlockProps`（3 行）、`NavEntry`（5 行）也必须单独列出）
     - 不得把 Props interface / 小接口并入父组件或跳过
     - 一个语义单元 = 一个 semantic_units 条目，range 取该符号的实际
       [line_start, line_end]
     跳过任一图谱单元 = 漏读，会被单元完整性差集校验检出（unit_gap）→ 该文件须补报重读

输出（结构化，仅此格式），写入 <临时输出文件>（JSON 文件，不要回传大文本）：
{
  "group": "<GROUP>",
  "outputs": [
    {
      "path": "相对路径",
      "total_lines": <int>,
      "read_ranges": [[s,e], ...],
      "semantic_units": [{"range":[s,e],"kind":"...","name":"...","note":"..."}],
      "findings": [
        {"path": "...", "line": <int>, "severity": "blocker|major|minor",
         "category": "security|business|data|...", "confidence": <1-10>,
         "message": "问题描述（含具体行内容证据）", "fix": "修复建议"}
      ]
    }
  ],
  "summary": "本组一句话结论（主要风险点）"
}

深读确认 = 该组文件全部出现在 outputs 中，且每个都有 total_lines/read_ranges/semantic_units。

禁止退化格式：不得把子代理输出简化为 DEEPREAD_CONFIRM: <路径|总行数|已读范围|单元数> 单行文本。那会使主代理拿不到分段 read_ranges 与逐单元 semantic_units，导致 coverage_tool 三件套门禁无法执行、报告"无行覆盖"。子代理 prompt 必须使用本节模板原样复制。

三、输出 Schema（子代理 → 落盘 → 主代理）

落盘机制（强制）：子代理把上述 JSON 写入主代理指定的临时目录（如 C:\Users\ADMINI~1\AppData\Local\Temp\opencode\review\batchN.json）。 不要把 1-2MB JSON 回传主上下文——主代理只读聚合结果摘要。
每波子代理完成后，主代理运行聚合脚本：
```
python skills/project-review/scripts/aggregate_deep_read.py <repo_root> <输出目录>
```
返回 verified_files / line_gap_files / unit_gap_files / unit_exempt_files / summary。

四、主代理收尾流程

1. 每波子代理完成后（不等全部结束）：
   aggregate_deep_read.py <repo_root> <落盘目录>
2. 汇总三件套判定：
   - line_gap_files ∪ unit_gap_files → 补读队列（下波派发，禁止跳过）
   - unit_exempt_files → 仅按行覆盖校验（已由脚本处理）
   - verified_files → 计入本轮 deep_read_files
3. 防伪抽验（**强制，每波必做**）：对每组抽 **2 文件**、每文件抽 2-3 个语义单元，
   回读源文件对应行比对 semantic_units.note。每波 ≤40 次 read。抽到假读 → 该组重读并升级抽验率。
   结果落盘 `spot_check_<batch>.json`（schema：groups_sampled / files_sampled / units_sampled /
   fake_read_found / groups_rereread / samples[{group,file,unit,range,note_match,in_read_ranges}]）。
4. 全部达标后，三件套数据传入引擎 coverage_tool（B 阶段引擎原生支持）：
   coverage_tool(deep_read_files=<verified_files>, gate="both+line",
                 file_read_ranges=<{rel:[[s,e]..]}>, file_semantic_units=<{rel:[...]}>)
   → 引擎返回 line_coverage_pct / unit_coverage_pct / line_gap_files / unit_gap_files / unit_exempt_files
   ⚠️ 禁止降级：unit_gap_files 或 line_gap_files 非空时，**不得**改回 gate="both" 静默跳过；
     必须补轮重读至空，或在报告中显式标注"三件套未达标 🔴"并列出缺口文件。
5. 未达标（文件数 <85%/<95% 或行覆盖 <95% 或单元有缺口）→
   按 priority_deep_read_files / line_gap_files / unit_gap_files 补一轮（可再派 1-3 个子代理）。
6. G2：对 silent_files 随机抽 15% 深读（本轮未覆盖的静默文件）。
7. 报告生成前：聚合全部 `spot_check_*.json` → 注入 `review_data.spot_check`（顶层字段）。
8. G3：三件套 + 文件数双口径达标 → 报告生成（覆盖度区块须含行/单元覆盖 + 防伪抽验）→
   跑 verify-spot-check.ps1（Step 8.8）→ save_coverage_index_tool(deep_read_files=<verified_files>, file_read_ranges=<ranges>) 写 v2 索引。

五、质量控制与防伪

风险	对策
子代理"声称读了"但没真读	强制 `total_lines`/`read_ranges`/`semantic_units` 三字段 + findings 带行号；聚合脚本按①差集+②行并集双校验；主代理③抽样回读
子代理漏读文件	outputs 与分组清单 diff，漏读计入覆盖率缺口，触发补轮
子代理宽 range 冒充全读	① one-to-one 匹配：一个上报 range 只能覆盖一个单元，无法用整文件 range 覆盖所有单元
子代理漏报小单元（Props interface / Type / 小函数）	严格模式：semantic_units 必须逐一列出图谱全部单元（含 3-5 行的小接口）；unit_gap 非空 → 该文件补报重读，不得视为已深读
子代理各自为政口径不一	统一八类 + CRITICAL 子轮 + severity/confidence 标准（见上模板）
增量掩盖新代码	`include_prior=True` 按 per-file SHA 判定；变更文件自动失效重读
并发压力	每批 4-6 个并行，其余排队；batch_size 40 控制单组体量
主上下文被大 JSON 撑爆	落盘机制：子代理写临时文件，主代理只读聚合摘要

六、跨轮增量（多轮累积）

每轮报告后 save_coverage_index_tool 写 .code-review-graph/coverage-index.json （相对路径 → per-file SHA）。
下一轮 deep_read_plan_tool(include_prior=True) / coverage_tool(include_prior=True) 自动复用 SHA 未变文件 → 增量任务 = 新增文件 + 变更文件。
多轮后增量归零即实现全库全覆盖，避免每轮从 2-5% 起步。
引擎 B 阶段（compute_coverage 支持 file_read_ranges/file_semantic_units，gate="both+line"）已落地。主代理优先用 coverage_tool(deep_read_files=..., gate="both+line", file_read_ranges=..., file_semantic_units=...) 做三件套门禁（引擎返回 line_coverage_pct/unit_coverage_pct/line_gap_files/unit_gap_files/unit_exempt_files）。 A 阶段聚合脚本 scripts/aggregate_deep_read.py 保留作独立校验兜底（引擎不可用时的替代），两者判定逻辑一致。

12 KiB Raw Permalink Blame History Unescape Escape