# 三视角评审团——Work Graph Fan-out 实现——需求文档

**日期**: 2026-08-05
**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应 `docs/todo/graph-engineering-open-items.md` 条目 F 的确认结果——"三视角评审团可以做，做成 Work Graph 的 fan-out 图来实现"。
**依赖**：本文档描述的 fan-out 验证节点若要真正获得"多视角同时判断"的时间收益，强依赖 `docs/work-graph-parallel-execution-requirements.md`（条目 G）的并行执行能力——没有 G，把 `judge_root_cause` 现有的顺序调用改成 Work Graph fan-out 反而更慢（多了 Work Node 调度开销，却没有并行收益）。建议 G 先进入实现或至少详细设计定型后，再排期本文档。
**状态**: 草案，待评审。

## 1. 背景

`src/root_cause_trace.py::judge_root_cause()` 已经实现了 14 步版"多视角差异化校验"模式的核心逻辑：

```python
def judge_root_cause(perspective_fns):
    """要求 >= 2/3 视角一致才定案 ... 否则 raise InconclusiveEscalateError"""
    judgments = [fn() for fn in perspective_fns]
    ...
```

三个视角（正确性/需求完整性/Skill 系统性缺陷）目前只用在 Validator 的 `test_failed` 根因溯源场景，且是**纯 Python 函数式实现**——`perspective_fns` 是一组闭包，`judge_root_cause` 一个一个顺序调用它们（`judgments = [fn() for fn in perspective_fns]` 是一个普通的列表推导，不是并发调用），每个 `fn()` 内部大概率是一次独立的 `claude -p` 调用（`real_validator_perspective` 函数名暗示了这一点）。

这次确认的方向：把这套机制从"Python 函数顺序调用三个闭包"升级为"Work Graph 里一张真正的菱形拓扑"——fan-out 出 N 个独立的验证 Work Node（每个节点携带自己的视角提示词，是一次独立的 Work Node 执行，而不是一个 Python 闭包），fan-in 节点做投票/汇总。这跟综述版对照笔记（`docs/reference/graph-engineering-vs-loop-engineering-overview.diff-with-graphlemon.md` §2）指出的"这正好对应文章第 08 章'评审团'式多视角交叉审"是同一个模式，只是要把它从函数调用升格为图结构。

## 2. 目标

1. 把三视角（或未来可能扩展到更多视角）评审团实现成一张真正的 Work Graph fan-out/fan-in 菱形：一个 split 节点（或直接由调用方给出待评审对象）→ N 个并行的独立验证 Work Node（各自视角、各自独立的 `claude -p` 调用、各自独立的持久化状态） → 一个 fan-in 节点汇总投票结果。
2. 这套 fan-out 评审团机制要能被**不同的验证场景复用**，不只是 Validator 的根因溯源——`run_graph()` 现有的 `verify_fn`（单一验证器 + 失败重试一次）应该能够选择性地升级为这套多视角 fan-out 验证，用于高风险节点（比如 SDD 审核、代码变更审核）。
3. 每个视角的验证节点获得**独立、干净的上下文**（呼应 5 步版对照笔记已确认的"Verifier 需要干净上下文"这条原则）——不是同一个对话里问三次不同角度的问题，而是三次完全独立的 Work Node 执行。

## 3. 非目标

1. **不要求所有验证点都升级成 fan-out 评审团**。这是一种"重打法"，只用于高风险节点，大多数验证场景继续用现有的单一 `verify_fn`（一个验证器 + 失败重试一次）就够了——具体"高风险"的判定标准留待设计阶段确定，但原则上默认走轻量路径，评审团是可选升级，不是新的默认行为。
2. **不要求第一版就废弃 `root_cause_trace.judge_root_cause` 的现有 Python 函数式实现**。是否完全替换、还是保留作为"不需要 worktree/轻量场景"的备选实现，留待设计阶段确定（见第 8 节开放问题）。
3. **不在本文档定案 fan-out 验证节点的并发触发机制细节**。具体怎么并行触发这几个验证节点，是条目 G 的职责范围，本文档只提出"这几个节点需要能并行执行"这个需求，不重复 G 已经在做的设计工作。

## 4. 功能需求

| # | 需求描述 | 优先级 |
|---|---|---|
| FR-1 | 设计一种可复用的 `graph_manifest` 模式（菱形拓扑：1 个输入节点或直接的调用方输入 → N 个独立视角验证节点 → 1 个汇总节点），可以被任何需要"多视角评审团"式验证的调用方复用，不是针对根因溯源场景写死的一次性结构。 | 必须 |
| FR-2 | N 个视角验证节点的具体视角内容（提示词）需要能按调用场景参数化——根因溯源场景用"正确性/需求完整性/Skill 缺陷"三视角，未来其他场景（比如代码审查）可能需要"正确性/安全/性能"这类不同的视角组合，机制本身要跟具体视角内容解耦。 | 必须 |
| FR-3 | 汇总节点需要保留现有 `judge_root_cause` 已经验证过的判定规则——`>= 2/3` 视角一致才定案，不足则升级（`InconclusiveEscalateError` 的等价行为），这条规则本身经过实战验证，不需要重新设计，只需要把它从"Python 函数内的逻辑"迁移成"fan-in 节点的判定逻辑"。 | 必须 |
| FR-4 | `run_graph()` 的 `verify_fn` 接口需要能够对接这种 fan-out 评审团实现——具体是扩展 `verify_fn` 的调用约定，还是提供一个新的 `verify_fn` 工厂函数（生成一个内部会触发 fan-out 评审团的 `verify_fn`），留待设计阶段确定，但调用方（比如 `e2e_pipeline.py::plan_documents` 的 `_prd_consistency_verify_fn`）不应该需要感知内部是单一验证器还是评审团。 | 应该 |
| FR-5 | Validator 现有的 `test_failed` 根因溯源场景要能迁移到这套新机制上，作为第一个真实落地场景，验证机制本身可用，而不是只停留在通用接口设计层面。 | 必须 |

## 5. 验收标准

1. 给定一个需要根因溯源的模拟场景，用新的 fan-out 评审团机制跑一遍，验证三个视角节点各自作为独立的 Work Node 执行（能在 `execution_event`/日志里看到三次独立的节点执行记录，而不是一次函数调用内部的三次闭包调用）。
2. 验证判定规则等价性：构造"2/3 一致""不足 2/3"两种场景，确认新机制的判定结果跟现有 `judge_root_cause` 单测覆盖的场景给出相同的结论。
3. 验证视角节点确实使用独立、干净的上下文——每个视角节点的 `input_payload` 只包含它需要判断的内容，不包含其他视角节点的推理过程。
4. 在 G（并行执行）就绪后补充验证：三个视角节点的执行时间有重叠（不是排队执行）。

## 6. 约束与假设

- 复用现有的 Work Node 执行机制（`work_node_run.run_work_node`/`work_graph_execute.execute_work_graph`），每个视角节点是一次独立的单节点 workflow 脚本调用，跟现有其他 Work Node 没有本质区别。
- 复用现有的 `graph_manifest`/`run_graph()` 执行入口，不新建专门的"评审团执行器"——评审团只是 `graph_manifest` 的一种特定拓扑形状（菱形），不需要新的执行引擎能力（依赖 G 提供的并行触发能力，但执行入口本身还是 `run_graph()`）。
- `root_cause_trace.judge_root_cause` 现有的单测（如果存在）应该被保留或迁移，作为判定规则本身正确性的回归保障，不因为改成图结构就失去测试覆盖。

## 7. 风险

- **强依赖 G，排期上不能先于 G**：如果 G 推迟，这条也要跟着推迟，或者先落地"fan-out 但暂时串行执行"的过渡版本（功能正确但没有时间收益），需要跟用户确认是否接受这种过渡状态，还是宁可等 G 一起上。
- **每个视角节点变成独立 Work Node 后，token 成本会上升**：现有 Python 函数式实现里，"三次独立调用"这件事本身没有变化，但包装成 Work Node 后每个节点会多一层 schema 校验往返、多一次单节点 workflow 脚本渲染的开销——这个开销预计很小，但需要在设计阶段实测确认，不是纯粹的免费升级。
- **"高风险"判定标准如果定得太宽，会导致大量场景都触发评审团**，造成不必要的成本增长——需要在设计阶段给出明确、克制的判定标准，而不是默认"能用评审团就用评审团"。

## 8. 开放问题（留给详细设计阶段回答）

- [ ] `root_cause_trace.judge_root_cause` 的 Python 函数式实现要不要保留作为轻量级备选（比如单元测试场景、不需要真实 `claude` 子进程调用的场景），还是完全被 Work Graph 版本取代？
- [ ] FR-4 的具体接口设计——`verify_fn` 扩展方式。
- [ ] 除了 Validator 根因溯源，哪些验证点要升级成评审团（SDD 审核？代码变更审核？）——"高风险"判定标准怎么定，是节点类型固定标注还是运行时动态判断？
- [ ] 视角数量 N 是否需要可配置（不同场景可能需要 2 个视角或 5 个视角，不一定总是 3 个）？