# 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 落地 **状态**：✅ 已实现（2026-08-06）→ 需求文档 `docs/todo/validator-loop-until-dry-skill-requirements.md` + 设计文档 `docs/todo/validator-loop-until-dry-skill-design.md` **来源**：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 底层。 **待办**：✅ 已实现（2026-08-06）。关键设计澄清：loop-until-dry 不需要图内回路——收敛循环发生在**单个 Work Node 一次 `claude -p` 会话内部**（多轮工具调用），`graph_manifest` 本身仍是无环的，不需要碰 `topological_order`。实现内容：新 Skill `skills/unknown-scope-defect-sweep/SKILL.md`（K=2 连续无新发现停止、20 轮硬上限、去重键必须是结构性标识而非自然语言描述、去重集合是"全部见过的"而非"已确认的"——14 步版点名的常见坑），接入 `agent_profile.py::FRONTMATTER["validator"]["skills"]`；`agents/validator/AGENTS.md`"必须加载"一节新增触发指引（任务描述说不清验收对象确切数量/边界时加载）。FR-3 的判定框架接线选择了复用 `qa-task-validation` 已有的 PASS/FAIL/INCONCLUSIVE 判断，**没有**接 F 的 `root_cause_trace`/三视角评审团——两者是流水线上不同阶段（验证本身 vs 验证失败后的根因归属），不应该混用，设计文档第 2 节记录了这个取舍。本轮唯一有确定性代码行为、可测试的部分是 FR-4（Skill 接入 `agent_profile.py` 渲染进部署产物），新增 `test_agent_profile.py::test_validator_references_unknown_scope_defect_sweep_skill`；验收标准 1-3（真的能找全、真的能正确去重、真的能在硬上限停止）依赖真实 `claude -p` 多轮工具调用行为，只能用 `RUN_REAL_AGENT_E2E=1` 验证，不在本轮 mock 测试范围内，如实记录（跟 F 设计文档"视角节点并发时间收益的实测"是同一类限制）。`python3 -m unittest discover -s src`（587 tests）全绿，零回归。 --- ## 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 设计能力 **状态**：✅ 已实现（2026-08-06）→ 需求文档 `docs/todo/dynamic-work-graph-design-skill-requirements.md` + 设计文档 `docs/todo/dynamic-work-graph-design-skill-design.md` **来源**：综述版对照 §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 的设计"。 **待办**：✅ 已实现（2026-08-06）。G 已经回答了 FR-2（并行分组字段格式）：不需要新字段，`topological_layers()` 完全靠 `depends_on`/`edges` 结构本身推导独立性——设计文档第 1 节记录了这个结论。实现内容：新 Skill `skills/design-dynamic-work-graph/SKILL.md`（跨 Org Agent 通用方法论，接入 `agent_profile.py::FRONTMATTER["coder"]["skills"]`/`["validator"]["skills"]`）；`work_graph_plan.py` 新增 `_GENERIC_PROMPT_TEMPLATE`（`org_node != "planner"` 时使用，每节点自带 `task_prompt`，Planner 原有固定链路 `_PROMPT_TEMPLATE` 完全不动，零回归）+ `generic_node_prompt_builder()`。按需求文档非目标 #1（"不要求第一版就覆盖 Coder/Validator 全部真实工作场景，只需要证明机制走得通"）收窄范围：**没有**改动 `e2e_pipeline.py::implement_code()` 的现有单节点生产路径——新增测试证明"给 Coder 一个可拆成 3 个独立模块补测试的场景 → 生成正确的 `graph_manifest` → `topological_layers()` 确认三个节点落在同一层 → `run_graph()` 端到端跑完"这条链路本身成立（`src/test_work_graph_plan.py`：`GenericPlanningPromptTest`/`CoderThreeIndependentModulesScenarioTest`/`GenericNodePromptBuilderTest`/`GenericPathEndToEndViaRunGraphTest`），不是接入真实生产路径。`python3 -m unittest discover -s src`（580 tests）全绿，零回归。 --- ## F. 三视角评审团机制要不要推广到其他验证点 **状态**：✅ 已实现（2026-08-06）→ 需求文档 `docs/todo/verifier-fan-out-jury-requirements.md` + 设计文档 `docs/todo/verifier-fan-out-jury-design.md` **来源**：综述版对照 §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 图来实现吧"。 **待办**：✅ 已实现（2026-08-06）。汇总节点没有做成第四个 Work Node——投票是纯 `zero_token` 聚合（跟 E 里 `edge_type` 的区分直接对应），不需要 Agent 推理，做成普通 Python 函数在 `run_graph()` 返回后直接对 `outputs` 计数，不产生额外 `claude -p` 调用/token 成本，设计文档第 1 节记录了这个取舍。实现内容：`root_cause_trace.py` 新增 `_tally_perspectives()`（>=2/3 判定规则从 `judge_root_cause` 抽出来，闭包版和 Work Graph 版共用同一份规则，不是两份容易失配的实现）+ `judge_root_cause_via_work_graph()`（N 个视角节点用真实 schema 约束的结构化输出，不再像 `real_validator_perspective` 那样手工解析"CATEGORY:/DETAIL:"文本行）。闭包版 `judge_root_cause`/`real_validator_perspective` **保留**，不废弃（轻量备选，见设计文档第 4 节）。`org_level_loop.run_fix_loop`（唯一真实生产调用方）已迁移到 Work Graph 版本，fixer/verify 两次调用保持不变的 flat `trigger_org_node` 调用。**顺带修了一个真实的潜在 bug**：`judge_root_cause_via_work_graph` 是第一个真正触发 `run_graph()` 多节点并发层的生产代码路径（之前所有真实 `graph_manifest` 要么单节点要么严格串行链，G 的并发调度从未在生产里真正跑过），暴露出 `scheduler.py::run_goal_to_completion`/`task_execution.py::start_task_execution_in_background` 的 `schema.connect(db_path)` 都没传 `check_same_thread=False`——已一并修复。测试改造范围（设计文档第 5 节标注的最高风险点）：`test_org_level_loop.py`/`test_scheduler.py` 的 3 个测试把 mock 边界从 `org_node_trigger.trigger_org_node`（拦截"CATEGORY:"提示词）改成 `work_graph_execute.write_workflow_script`/`execute_work_graph`。新增测试证明验收标准 1-3（三次真实独立 Work Node 执行、判定规则与闭包版等价、每个视角节点的 `input_payload` 不含其他视角内容）+ 一个直接验证并发重叠的测试（`ConcurrentPerspectiveExecutionTest`）。`python3 -m unittest discover -s src`（586 tests）+ `discover -s supervisor`（125 tests）全绿，零回归。FR-4（`verify_fn` 通用对接其他验证点）本轮不实现，标注"应该"优先级，留待后续。 --- ## G. Work Graph 节点并行执行（Python 线程池方案） **状态**：✅ 已实现（2026-08-06）→ 需求文档见 `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 已经写的内容一致，不需要改需求文档的功能需求本身，只需要在文档里把这句话作为明确的验收口径固化下来。 **待办**：✅ 已实现（2026-08-06），按设计文档第 11 节的分步实施顺序落地——`src/work_graph_orchestrate.py`：`topological_layers()`（层内并发、层间屏障，`topological_order()` 改为薄封装）、`_LockedConn`/`_FetchedRows`（线程安全 conn 代理，**注意**：实现比设计文档原稿更严格——锁必须覆盖 `execute()` 到 `fetchone()`/`fetchall()` 的整个周期，不能只锁 `execute()` 本身；这个差异是 `RunGraphRealSqliteConcurrencyTest` 真实跑出 `database is locked`/空 `file_path` 类错误后修的，不是理论推导）、`run_graph()` 改层级调度 + `_run_one_node()` + `WorkGraphLayerError`；`src/work_node_run.py`：`create_worktree()` 加 `_worktree_creation_lock`。新增测试：`src/test_work_graph_orchestrate.py`（`TopologicalLayersTest`、`RunGraphConcurrencyTest` 同层并发+层间屏障、`RunGraphLayerErrorTest` 失败不取消同层兄弟节点、`RunGraphConcurrentResumeTest`、`RunGraphQuotaCoexistsWithNormalCompletionTest`、`RunGraphRealSqliteConcurrencyTest` 真实 sqlite 多轮并发）、`src/test_work_node_run.py`（`ConcurrentCreateWorktreeTest` 真实 git worktree 并发创建）。已知遗留限制（设计文档已诚实记录，本轮未解决）：单节点配额等待可长达数小时，会拖住整层其他已完成节点的返回——需要更细粒度的可中断调度才能解决，超出本次范围。`python3 -m unittest discover -s src`（575 tests）+ `discover -s supervisor -p "test_*.py"`（125 tests）全绿，零回归。 --- ## H. 统一 Role Package 抽象层 **状态**：✅ 已确认（需求评审通过，2026-08-06）→ 需求文档 `docs/todo/role-package-abstraction-requirements.md`（注：文档正文里自己写的路径少了 `todo/` 一段，实际文件在这个路径下） **来源**：不属于三份 Graph Engineering 对照笔记，是用户对照 Agentic Enterprise 产品目标（"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"）单独提出的差距检查，2026-08-06。 **背景**：逐维度核对代码发现，七个维度里六个都有对应实现（applications 是真空白），但没有被收敛成一个统一的"role package"格式——理解"Validator 这个角色完整定义是什么"现在得同时读 `agent_profile.py` + `skills/qa-task-validation/SKILL.md` + `.claude/agent-memory/validator/` + `docs/sdd/06-验收与测试锚点.md` 四个地方拼出来。更根本的问题：`role` 本身不是数据驱动的——`ORG_NODES = ("planner", "coder", "validator")` 硬编码元组，`schema.py` 四张表的 `CHECK (org_node IN ('planner','coder','validator'))` 约束——新增角色需要改代码和 schema，不是"包一个新角色进来"。 **需求评审结果（2026-08-06）**：方向确认，目标/非目标/FR-1~6 按原文通过，进入设计阶段。逐条核实过文档里对代码现状的描述后，发现两处需要修正/补充： 1. **风险第 1 条的依赖清单不准确，且遗漏了真正的大头**。文档写"`ORG_NODES`/`FRONTMATTER` 被 `deploy_agent_definitions`、`org_node_trigger`、`work_graph_orchestrate` 等多处代码直接依赖"——实测 `work_graph_orchestrate.py` 根本不 `import agent_profile`，这条是误判；真正 `from src.agent_profile import ORG_NODES`/`from src import agent_profile` 的只有 `org_node_trigger.py`（校验 `org_node` 合法性）和 `project_scaffold.py`（调 `deploy_agent_definitions()` 这一个单一入口）——这部分实际依赖面比文档描述的**更小**，是个好消息。但文档完全没提到两处真正硬编码了三元组的地方：`src/work_graph_run_query.py::_VALID_ORG_NODES`，以及**分量最大的**——`frontend/app.js` 里四处独立硬编码（`ORG_NODE_DETAIL_RE` 路由正则、`ORG_NODE_ORDER` 排序数组、任务创建表单的 `