# 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 ≡ 角色图**。 **待办**：✅ 已完成（2026-08-05）。`docs/graphlemon_architecture.md` §2 术语表的 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 底层。 **待办**：✅ 需求文档已产出 → `docs/validator-loop-until-dry-skill-requirements.md`。关键设计澄清：loop-until-dry 不需要图内回路——收敛循环发生在**单个 Work Node 一次 `claude -p` 会话内部**（多轮工具调用），`graph_manifest` 本身仍是无环的，不需要碰 `topological_order`。 --- ## 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）**：立项。 **待办**：✅ 需求文档已产出 → `docs/work-graph-time-travel-debugging-requirements.md`。已明确跟 Deploy Supervisor 自动回滚（`docs/supervisor-auto-rollback-design.md`）的命名消歧。最大的数据模型影响点：`work_graph_run` 表现有的 `ux_work_graph_run_active` 唯一约束（同一 `task_id`+`org_node` 同时只能有一个非终态 run）会挡住分叉分支，需要在设计阶段决定怎么扩展。 --- ## 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 的设计"。 **待办**：✅ 需求文档已产出 → `docs/dynamic-work-graph-design-skill-requirements.md`。深挖代码后发现真实缺口比原开放问题更大：`work_graph_plan.py::plan_work_graph()` 的提示词目前**硬编码**成永远只生成 brd/prd/sdd/benchmark 四个节点，且只有 Planner（`e2e_pipeline.py::plan_documents`）真正调用它——**Coder 和 Validator 现在根本没有走"先规划图再执行"这条路径**，走的是更简化的单次 `org_node_trigger.trigger_org_node()` 调用。所以 E 不只是"强化提示词"，而是要先把动态 Work Graph 规划能力从 Planner 专属扩展成三个 Org Agent 通用。 **依赖关系**：这条和「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 图来实现吧"。 **待办**：✅ 需求文档已产出 → `docs/verifier-fan-out-jury-requirements.md`。明确标注**强依赖 G**——没有并行执行能力，把 `judge_root_cause` 改成 Work Graph fan-out 反而更慢（多了 Work Node 调度开销，没有并行收益），建议排在 G 之后。 --- ## 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 | ✅ 已完成 | 无需求文档，直接改了 `docs/graphlemon_architecture.md` §2 术语表 | | B | ✅ 已确认，需求文档已产出 | `docs/validator-loop-until-dry-skill-requirements.md` | | C | ⛔ 暂不做 | 无 | | D | ✅ 已确认，需求文档已产出 | `docs/work-graph-time-travel-debugging-requirements.md` | | E | ✅ 已确认，需求文档已产出（范围比原开放问题更大） | `docs/dynamic-work-graph-design-skill-requirements.md` | | F | ✅ 已确认，需求文档已产出 | `docs/verifier-fan-out-jury-requirements.md` | | G | ✅ 已确认，核心优先级，需求文档已产出 | `docs/work-graph-parallel-execution-requirements.md` | **当前状态**：A 已落地；B/C/D/E/F/G 六项全部完成需求文档（BRD/PRD 层面），均未进入详细设计（SDD 层面）。 **推进顺序建议**：G 是 E、F 的前置依赖（E 的并行分组字段格式、F 的 fan-out 时间收益都需要 G 先定型），建议优先把 G 推进到详细设计。B、D 相对独立，可以随时单独推进详细设计。E、F 的详细设计需要等 G 的数据结构定下来。 下一步要我先把哪一份需求文档推进到详细设计（SDD 层面）？还是先把六份需求文档过一遍评审，确认没有需要调整的地方，再决定设计阶段的排期？