graph-engineering-open-items.md 13.3 KB

Edit Raw Blame History


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/done/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 已经写的内容一致，不需要改需求文档的功能需求本身，只需要在文档里把这句话作为明确的验收口径固化下来。

待办：✅ 详细设计已产出 → docs/work-graph-parallel-execution-design.md。核心设计：新增 topological_layers()（层内并发、层间屏障），_LockedConn 线程安全代理复用 backend_server.py 的锁模式，create_worktree() 加防御性锁，WorkGraphLayerError 聚合层内多个失败。已知遗留限制（诚实记录，非本轮解决）：单节点配额等待可长达数小时，会拖住整层其他已完成节点的返回——需要更细粒度的可中断调度才能解决，超出本次范围。下一步：实施（见设计文档第 11 节的分步实施建议），或先评审设计。


确认结果汇总（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 层面）？还是先把六份需求文档过一遍评审，确认没有需要调整的地方，再决定设计阶段的排期？