# Graph Engineering 系列对照笔记——待确认事项清单

**日期**: 2026-08-04（2026-08-05 更新：A/B/D/E/F/G 已确认方向，C 已确认暂不做）
**性质**: 从三份对照笔记里提取出的全部"待讨论的开放问题"，去重合并后按主题整理，供逐条确认方案。每条确认后会展开成独立的需求文档（参考 `docs/work-graph-parallel-execution-requirements.md` 的产出方式），本文件本身只做索引和现状追踪，不写详细方案。
**来源文档**：
- `docs/reference/graph-engineering-1000-agents-5-steps.diff-with-graphlemon.md`（简称"5 步版对照"）
- `docs/reference/graph-engineering-vs-loop-engineering-overview.diff-with-graphlemon.md`（简称"综述版对照"）
- `docs/reference/Graph Engineering with Claude_ 14-Step roadmap from 0 to graph architect (Full Course).diff-with-graphlemon.md`（简称"14 步版对照"）

三份笔记里有几条开放问题实质上是同一件事的不同角度，已在下面合并并标注了原始出处。

---

## 状态图例

- 🔲 待确认：还没讨论方案
- 🟡 讨论中/已产出需求文档，待评审
- ✅ 已确认，进入设计/实现
- ⛔ 已确认不做（附理由）

---

## A. 架构文档要不要正式采用"工作图 / 角色图"命名

**状态**：✅ 已确认——两组术语等价，不是新概念

**来源**：5 步版对照 §4 开放问题 3 + 综述版对照 §8 开放问题 1（同一件事，两份笔记从不同角度各自提出）

**背景**：综述版文章提出一条治理红线——"工作图"（任务怎么拆怎么合，可以快变）vs "角色图"（谁有权改什么，必须慢变可审计）。这条边界跟 graphlemon 现有的 Org Graph（人工固定设计，架构变更需人工评审）/ Work Graph（每次任务动态生成）边界几乎是同一件事的两种命名。5 步版对照笔记是从"什么时候不该用 Graph"的角度独立推出同一条边界的。

**确认结果（2026-08-05）**：`工作图` 是 `Work Graph` 的字面翻译，graphlemon 本来就这么叫；`角色图` 不是 `Org Graph` 的字面翻译，但语义完全对得上——Org Graph 本来就是"角色（Planner/Coder/Validator）之间固定的组织关系图"，`角色图` 是更准确的中文释义，不是新造的概念。两组术语直接画等号：**Work Graph ≡ 工作图，Org Graph ≡ 角色图**。

**待办**：在 `docs/graphlemon_architecture.md` §2 术语表或 §3 整体架构处补一句显式对应说明（"Org Graph 即角色图、Work Graph 即工作图"），引用综述版文章的治理红线原文作为设计依据。纯文档改动，不涉及代码，可以随手做掉。

---

## B. loop-until-dry 要不要在 Validator 落地

**状态**：✅ 已确认方向——做成 Validator 的一个 Skill

**来源**：5 步版对照 §4 开放问题 1

**背景**：Org-level Loop 目前固定 3 轮上限（`docs/sdd/04-P-流程与状态流转.md` 已标注这是"未来优化候选"）。14 步版对照进一步发现：这不只是优先级问题——`work_graph_orchestrate.py::topological_order` 对有环的 `graph_manifest` 直接报错，Work Graph 被设计成严格 DAG，图内根本不支持回路，要支持 loop-until-dry 需要动执行模型本身，不是加一个判断逻辑那么简单。

**确认结果（2026-08-05）**：不改 Work Graph 执行模型本身（不引入图内回路）。做成一个独立的 Skill（例如 `validate-until-dry` 之类），把"连续 K 轮无新发现才停止、去重比对全部见过的而非仅已确认的"这套收敛逻辑封装成 Validator 可调用的方法论/工具，并且要求 `.claude/agents/validator.md` 在跑到"未知规模缺陷扫描"这类场景时记得调用它——落地方式是 Skill + Agent 定义引用，不是改 Graph Engine 底层。

**待办**：写需求文档，明确这个 Skill 的触发场景（哪些任务算"未知规模扫描"）、K 值默认多少、和现有 `root_cause_trace`/Org-level Loop 3 轮上限的关系（互不冲突：3 轮上限管的是 Org Graph 层 Validator→Planner 回退次数，这个 Skill 管的是 Validator 自己 Work Graph 内部一次验证过程要扫多少轮）。

---

## C. 按节点分层选模型——策略归属

**状态**：⛔ 已确认暂不做

**来源**：5 步版对照 §4 开放问题 2 + 14 步版对照 §1 表格第 12 行 / §3 开放问题 3

**背景**：`agent_profile.py` 里 Planner/Coder/Validator 三个 Org Agent 目前全部固定 `claude-sonnet-5`。14 步版对照进一步发现：Work Graph 层的管线其实已经打通了一半——`_render_node_script` 支持往生成的单节点脚本里塞 `model` 参数，`run_fn(cwd, model=None)` 也留了口子，但没有任何调用方真正传入非 None 的值，`graph_manifest` 的节点结构里也没有 `model` 字段。基础设施就位，缺的是"谁来决定每个节点该用哪个模型"这层策略。

**确认结果（2026-08-05）**：暂时不做。`_render_node_script` 的 `model` 参数保留现状（存在但不接线），Org Graph 三节点继续统一用 `claude-sonnet-5`。如果后续 G（并行执行）上线后节点数变多、成本变成真实痛点，再重新评估。

---

## D. Time-travel 调试要不要立项

**状态**：✅ 已确认立项

**来源**：综述版对照 §6

**背景**：LangGraph 的 checkpointer 支持回到任意历史检查点重放/分叉。graphlemon 目前的容错（部分节点失败保留已成功节点输出）、人在回路（Start/Pause/Stop）、记忆（`.claude/agent-memory/`）都已具备，唯独"回到某个历史节点重新分叉执行"没有，现状是"用 git 历史 + 手动重跑"。

**确认结果（2026-08-05）**：立项。

**待办**：写需求文档。需要先定义清楚几个问题再展开：
- "分叉重放"具体指什么粒度——回到某个 `work_node_execution` 之前，用新的输入/prompt 重新执行该节点及其下游，产出一条平行的执行分支？
- 分叉出来的新分支和原分支在数据模型上怎么共存（`work_graph_run`/`work_node_execution` 现有 schema 需不需要扩展"parent_run_id"之类的字段）？
- 和 G（并行执行）、控制台的关系——分叉调试大概率需要在控制台里可视化操作，属于第 13 节人机交互控制台的能力扩展，需要跟现有 v_task_detail 等页面的设计对齐。

---

## E. Planning Skill 提示词强化——识别可并行节点 + 通用 Work Graph 设计能力

**状态**：✅ 已确认，且范围比原开放问题更大

**来源**：综述版对照 §7 开放问题 3 + 14 步版对照 §3 开放问题 2（同一主题：让 Planning 阶段更早识别并行机会）

**背景**：`work_graph_plan.py` 里 Planning Skill 的 prompt（约在 `work_graph_plan.py:67` 附近）目前只要求"一个 artifact_type 一个节点"，没有引导 Claude 识别哪些节点互不依赖。目前观察到的真实 `graph_manifest`（如 BRD→PRD→SDD→Benchmark）是纯串行链，架构文档 §6.1 设想的并行候选点从未真正被生成过。

**确认结果（2026-08-05）**：提示词强化肯定要做——把"对每个箭头问是否真的有数据流动"的提问方式、以及"并行可分解 / 单一上下文装不下 / 收益覆盖成本"这三条尺子写进 Planning 相关 prompt。**但范围比原开放问题更大**：不能只强化 Planner 自己写 BRD/PRD/SDD/Benchmark 那条链的 prompt——架构文档 §5 本来就说"每个 Org Agent 拥有一个 Planning Skill"（Coder 和 Validator 各自也要规划自己的 Work Graph），"如何识别 fan-out/fan-in、设计一张动态 Work Graph"这套方法论应该是**跨 Org Agent 通用**的能力，而不是分别在 Planner/Coder/Validator 三份 Planning Skill 里各写一遍。用户原话："planner agent 里面要有多个 skill，不仅仅是 brd prd sdd benchmark 还有给其他 org graph 的 node 节点的 agent 做各种动态 work graph 的设计"。

**待办**：写需求文档，需要明确：
- 这套"动态 Work Graph 设计方法论"要不要抽成一个独立的、三个 Org Agent 共用的 Skill（类似现在 `skills/` 目录下已有的 `write-brd`/`write-prd` 等，新增一个例如 `design-dynamic-work-graph`），还是分别内嵌进各自的 Planning 环节？
- Planner 除了 BRD/PRD/SDD/Benchmark 这条主链的 skill 外，还需要哪些新 skill——用户提到"给其他 org graph 的 node 节点的 agent 做各种动态 work graph 的设计"，这暗示 Planner 可能要承担"帮 Coder/Validator 设计他们各自 Work Graph 结构"的角色，这跟架构文档 §5"每个 Org Agent 自己的 Planning Skill 各自生成自己的 Work Graph"的原有设计是否冲突，需要先对齐。
- 和 F（三视角评审团做成 fan-out 图）、G（并行执行）的衔接——这个 Skill 生成的 graph_manifest 里，fan-out 的节点组要用什么标记方式，让 G 的执行引擎能识别出"这些节点可以并发"。

**依赖关系**：这条和「G. Work Graph 节点并行执行」是互补的——G 解决"执行层能不能并发跑"，E 解决"规划层会不会生成值得并发的图"。两条需要一起排期,建议先看 G 的需求文档,E 的需求文档要在 G 确认的数据结构（`graph_manifest` 里怎么表达"这组节点可并行"）基础上写,避免两边字段对不上。

---

## F. 三视角评审团机制要不要推广到其他验证点

**状态**：✅ 已确认，且明确了实现方式

**来源**：综述版对照 §7 开放问题 4 + 14 步版对照 §3 开放问题 4（同一主题）

**背景**：`root_cause_trace.judge_root_cause`（正确性/需求完整性/Skill 缺陷三视角，≥2/3 一致才定案，否则升级人工）目前只服务于 Validator 的 `test_failed` 根因溯源场景。`run_graph()` 自身的 `verify_fn` 是单一验证器 + 失败重试一次，没有多视角/对抗式/评审团这类"重打法"。综述版文章把这类重仓验证归为"高风险场景才用"，暗示应该按风险分级选验证强度，而不是所有节点统一同一套。

**确认结果（2026-08-05）**：要做，而且明确了实现方式——**不是**继续用现在 `root_cause_trace.judge_root_cause` 那种 Python 层直接顺序调用三个 `perspective_fn` 的写法，而是把三视角评审团**做成一张真正的 Work Graph fan-out/fan-in 菱形拓扑**：fan-out 出 N 个独立的验证节点（每个节点是一次独立的 `claude -p` 调用，带自己的视角提示词），fan-in 节点做投票/汇总。用户原话："三视角评审团可以做，做成 work graph 的 fan out 图来实现吧"。

**待办**：写需求文档。这条**强依赖 G（并行执行）**——评审团的 fan-out 节点如果还是串行跑，就丢失了"多视角同时判断"的时间收益（现在 `judge_root_cause` 本来就是纯函数式顺序调用，改成 Work Graph fan-out 如果不配合并行执行，反而更慢）。需要确认：
- 现有 `root_cause_trace.judge_root_cause` 要不要保留作为"轻量级/无需 worktree/纯 Python 场景"的备选实现，还是完全被 Work Graph fan-out 版本取代？
- 哪些验证点要升级成这种 fan-out 评审团（SDD 审核？代码变更审核？）——"高风险"判定标准怎么定。

---

## G. Work Graph 节点并行执行（Python 线程池方案）

**状态**：✅ 已确认，标记为核心优先级 → 需求文档见 `docs/work-graph-parallel-execution-requirements.md`

**来源**：14 步版对照 §3 开放问题 1

**背景**：`run_graph()` 目前严格串行执行所有节点，即使 `graph_manifest` 里的节点互不依赖。已经讨论过按拓扑层分批 + 线程池并发的方案，核心风险（SQLite 并发写入、worktree 创建竞态、配额错误处理）都已识别，且发现 `backend_server.py` 里已有可复用的"共享连接 + `threading.Lock()`"先例。已产出完整需求文档（目标/非目标/功能需求/验收标准/风险/开放问题）。

**确认结果（2026-08-05）**：确认要做，用户强调"这个很核心"。触发规则明确为：**只要 Work Graph 规划了 fan-out/fan-in 的并行节点，节点触发时就应该并行执行**——这跟需求文档 FR-1/FR-2 已经写的内容一致，不需要改需求文档的功能需求本身，只需要在文档里把这句话作为明确的验收口径固化下来。

**待办**：进入详细设计阶段（`topological_layers()` 的具体实现、线程池调度器接口、锁的粒度），需求文档里第 8 节列的开放问题需要在设计阶段逐一敲定。这是 E、F 两条的前置依赖，建议优先推进。

---

## 确认结果汇总（2026-08-05）

| 项 | 结果 | 后续动作 |
|---|---|---|
| A | ✅ 确认，两组术语等价 | 待办：架构文档补一句对应说明（可直接做，无需求文档） |
| B | ✅ 确认，做成 Validator 的 Skill | 待办：写需求文档 |
| C | ⛔ 暂不做 | 无 |
| D | ✅ 确认立项 | 待办：写需求文档 |
| E | ✅ 确认，范围扩大为跨 Org Agent 的通用 Work Graph 设计能力 | 待办：写需求文档（依赖 G 的数据结构先定） |
| F | ✅ 确认，用 Work Graph fan-out/fan-in 实现 | 待办：写需求文档（强依赖 G） |
| G | ✅ 确认，核心优先级 | 需求文档已就绪，进入详细设计阶段，是 E/F 的前置依赖 |

**建议的推进顺序**：G 先进入详细设计（E、F 都依赖它的并行执行能力和数据结构），A 可以随手做掉（纯文档改动，不占用设计精力）。B、D 相对独立，可以在 G 设计的同时并行写需求文档。E、F 的需求文档建议等 G 的详细设计里"`graph_manifest` 怎么表达可并行节点组"这个数据结构定下来之后再写，避免字段对不上要返工。

下一步要我先做哪一件——是把 G 推进到详细设计，还是先把 B/D 的需求文档写掉，或者先去把 A 的架构文档措辞补上？