三视角评审团——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 步版"多视角差异化校验"模式的核心逻辑：

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 个）？