# 27-P3/P4. 图执行引擎与执行控制台 — 需求与设计文档 > **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 Phase **P3(最小闭环)+ P4(回退 + 熔断)**,外加 27 号文档原始路线图里没有单独立项的两块新增交付物——**一个执行控制台页面**,以及 **`workgraph-planning` agent + 用户→公司的任务入口**。 > **版本**: v0.3(**按 [27-REQ](./27-requirement.md) R-15 六条定案重写**;v0.1 正文与 v0.2 修正块已合并入正文,不再单列) > **日期**: 2026-08-15 > **前置**: [27-P2 Org Graph 落地](./27-p2-org-graph.md) 阶段 A/B。P0/P1 均已实现并提交(P1 = commit `226489d`)。 > **命名**: 全文遵循 [27-NAMING](./27-naming-conventions.md),含本文档 §五 T-P2 要求新增的 validator 命名轴。 > **配套**: [27-E2E 端到端流程](./27-e2e-task-execution-flow.md)、[27-EXAMPLE 参考场景](./27-example-dev-company-walkthrough.md) > **设计方法论**: 核心设计(§四)用 **Model / View / Control / Process(MVCP)** 四段组织。 --- ## 〇、v0.3 重写说明 v0.1/v0.2 的正文有三处**结构性**问题,不是补丁能修的: | # | v0.1/v0.2 的写法 | 为什么不成立 | 本版怎么改 | |---|---|---|---| | 1 | 四张 `work_graph_*` 表,「定义即实例」不拆表 | 该辩护的前提是 work graph「规划完即执行、执行完即归档」。**org graph 也要被同一套引擎执行**(R-15.4),而它是活整个公司生命周期的长期定义,一份定义要被跑很多次 | 定义层与运行时层分离,五张表,§四.A | | 2 | `advanceOne()` 只有一种节点执行语义(调 `AgentManager`) | org node 的「执行」是起一张子图并等它收敛,不是一次 agent 调用 | 两种 node executor,§四.D.0 | | 3 | §一非目标排除 `workgraph-planning` 与任务入口 | 代价是 v0.1 §八.5 自己承认「只能手写测试数据构造图,不能端到端验证」 | 两条非目标作废(R-15.5),收进阶段 D | 另有四处 v0.2 已在头部修正、本版直接写进正文的过期陈述:`runProject` 已实现(不是 501)、`UnitsDAG.vue` 已实现分波布局(不用从零写)、回退/预算应从 `_spec/loops-*.md` 抽象而来(不是平行发明)、P1 已实现。 以及两个已被关掉的 open question:v0.1 §八.3「重试要不要级联下游」由 `loops-l3.md` 的 `contract_hash` unchanged 四分类判据关闭;v0.1 §八.4「子图不继承父图暂停」被 [27-E2E](./27-e2e-task-execution-flow.md) §7.5 推翻,改为向下级联。 --- ## 一、目标与非目标 ### 目标 1. **一套图执行引擎**,同时驱动 org graph(company 级 workflow)和 work graph(org node 级 workflow)—— 两者是同一种东西在不同层级的递归(R-9.1),引擎不为它们各写一套。 2. **执行控制**:启动、下一步、暂停、停止、重试五个操作,同时支持**手动**(点一次推进一个节点)和**自动**(一键授权跑到底)两种模式,且在**每一层语义完全一致**。 3. **回退与熔断**:`edge_kind='backward'` 的回退边带循环计数与硬顶,两层通用;跨所有层级共享一个**任务级总预算**。 4. **一个执行控制台页面**:左栏 org graph,中间选中 org node 的 work graph 画布,右栏节点详情;回退边可视化带 `N/3` 徽标;主流程 / 异常流程视觉区分;逐层下钻(agent 对话记录 + 嵌套子图)。 5. **验收契约**:先定义 `goal-benchmark` / `goal-test-data` / `goal-test-script` 三种产物的统一格式并建执行器,再动引擎(R-15.6)。 6. **规划闭环**:`workgraph-planning` agent + 用户→公司的任务入口,让「一句自然语言 → 一张可执行的图 → 跑完」端到端成立(R-15.5)。 ### 非目标(本阶段明确不做) - **不做 fan-out 并行**。它卡在两个既有不变量上:`CONVENTIONS.md` §12「同 `(pid, agent)` 只允许 1 个 `status=running`」和 SessionPool 的 key 复用([27-E2E](./27-e2e-task-execution-flow.md) §7.4)。必须先做同一 system agent 的多实例隔离,是独立工作量。**v1 直接约束「一家公司同时只有一个 active root run」**,新任务排队——注意这条约束在 org 层就需要,不是等到 work 层 fan-out 才需要。 - **不做 L4**(system agent 自我迭代)。见 [27-E2E](./27-e2e-task-execution-flow.md) §八,且它是三级恢复叠加里最贵、爆炸半径最大的一级。 - **不做**对 DevLoop 现有 `loop-controller.js` / `unit-registry.js` 的收编。它是本架构的参考实现([27-E2E](./27-e2e-task-execution-flow.md) §二结论 2),本引擎从它**抽象**,但不改它一行;收编是 P6。 - **不做**多人协同编辑同一张图的协作特性(评论、@提醒)。并发**冲突控制**要做(§四.A.4 幂等),「协作」停留在「不冲突」。 - **不做**节点执行中途的断点续传。重试语义是「整个节点重新执行一次」。 - **不做**跨公司的全局大屏。页面粒度是「一家公司」。 --- ## 二、背景 27 号总纲 §六把 P3 定义为「Work Graph 最小闭环:单向执行,先不做回退」,P4 才引入回退和 Loop-Validator。本文档不切两份,原因:**执行引擎的状态机一旦要支持「暂停/单步/停止/重试」这种可被外部随时打断和摆布的控制语义,「先做单向、再加回退」会让第一版状态机设计得过窄,P4 加回退时必须回来重改数据模型和主循环**。所以一次性把两个 phase 的数据模型和引擎设计完,落地仍分阶段交付(§五)。 v0.3 在此之上还合并了两块 27 号路线图里没单独立项的东西——控制台页面(R-4)和规划闭环(R-15.5)——理由是没有它们,P3 验收只能靠手写测试数据,验不到「这套东西真的能跑起来」。 --- ## 三、现状代码走查(决定设计边界的关键证据) ### 3.1 DevLoop `runUnit()` / `runProject()`:状态机可抄,驱动方式不可抄 `loop-controller.js:345` 的 `runUnit()` 本质是一个同步的 `while (attempt < retry_budget)` 循环:一次函数调用里 Coder → Tester → 失败则 `_buildRetryContext()` 拼上次失败摘要 → 重跑。`runProject()`(行 576,**已完整实现**,含 `_groupUnitsByWave()` Kahn 分波、L2 闸门、Integrator、BugTriager 四分支、预算熔断)同样是一次调用跑到底。`server/routes/devloop.js` 直接 `await loopController.runUnit(...)` 再吐响应——**整个 retry 循环最多 10 次 agent 调用全部塞在一次 HTTP 请求-响应周期里,外部在它跑完前完全没有插手机会**。 > 补充观察:`runProject` 的波内**实际是串行**的(行 609 注释「串行跑(mock 同步快,不需并行)」),分波结构在、并行没做。这也印证了 §一非目标里「fan-out 并行是独立工作量」。 配套的 `unit-registry.js` 状态机(`TRANSITIONS`,行 30-37)设计得很干净:显式转换表 + 非法转换报错 + 每次合法转换 emit 事件。**这部分直接借鉴**。 **结论**:状态机照抄 `unit-registry.js` 的模式,主循环**绝不能**照抄「一次函数调用跑到底」。 ### 3.2 Pipeline Service:正确的参照模型 `pipeline-service.js` 的 `startRun()`(144-181 行)只做状态机初始化,**不同步执行任何 agent**。推进靠外部显式调用 `advanceStep(runId, stepIndex, {output, status})`。`rejectStep()` 是现成的「退回重做」语义。 **这正是本文档需要的执行模型**:状态是持久化数据,「推进一步」是一次显式、幂等、外部可随时调用的动作,不是占着调用栈不放的循环。手动模式下「下一步」= 用户点一次调一次;自动模式下 = 引擎自己在上一次返回后立刻再调一次。**手动和自动共用同一个原语,区别只在谁触发下一次调用**。 **两处不能照抄的坑**: 1. `CompanyDashboard.vue:1019` 的 `loadPipelineDetail()` 请求的是流水线**定义**,但模板里 `:class="{'step-current': selectedPipeline.currentStep === idx}"`(行 258)引用的 `currentStep` 只存在于 run 实例上——这个高亮效果**从未生效过**。→ 本设计的定义层与运行时层必须是两个各自完整、明确分开的对象(§四.A)。 2. `retryPipelineRun()`(行 1034)调 `POST .../advance` 但没传 `stepIndex`,而路由端有 `if (stepIndex === undefined) return 400`——这个「重试」按钮点了必定 400。→ 「重试」必须是独立、参数自解释的端点(§四.C)。 ### 3.3 SSE 基础设施:可直接复用 `server/services/devloop/sse-broker.js`:每项目一个广播通道,`subscribe(pid, res, {replayFromOffset})` 支持 `Last-Event-ID` 断线重放,`emit()` 同时落盘 + 广播,25s 心跳。按 `run_id` 复用同一套实现。 **既有缺口不要重复**:DevLoop 里 `timeline-logger.js` 的审计事件和 `sse-broker.js` 的实时推送是两条独立的轨,没有自动桥接。本引擎要求**状态转换、timeline 写入、SSE 广播三者在同一次原子操作里一起发生**。 ### 3.4 子流程展示:`AgentChat.vue` 的双轨折叠卡片,直接复用 第四列 "ACP Events" 面板已实现:`subAgents`(以 `callId` 为 key 的响应式 map)承载**进行中**的子调用,靠流式事件持续追加;`subLogList` 是**已完成**的历史日志卡片列表,外观一致但无 `LIVE` 徽标。这套「live map + history list」双轨模型正是节点运行日志需要的东西。 ### 3.5 前端 DAG:`UnitsDAG.vue` 已实现,扩展而非重写 `web/src/components/devloop/UnitsDAG.vue`(107 行)已实现 SVG + `` 箭头 + **Kahn 分波拓扑布局**(`waves` computed,带 safety 上限防死循环)+ 按 status 着色 + 点击 emit 下钻。同目录 `LiveAgentStream.vue`(带 Last-Event-ID 重连的 SSE 消费)、`UnitDrawer.vue`(节点详情抽屉)同样可复用。**真正的新增工作量只剩回退边的曲线路由**。 ### 3.6 进程级取消:机制存在,调用链需实现前二次确认 `server/src/engine/process-guard.js` 的 `ProcessGuard.cancel()`(82-93 行)对底层 Claude CLI 子进程先 `SIGTERM`、超时后 `SIGKILL`。`run-registry.js` 的 `RunRegistry` 按 `runId` 登记每次调用,但其公开方法(`add/get/markState/touchOutput/listActive/listByBackend/listByAgent/list/remove/stats/clear`)里**没有 `cancel`**——取消动作大概率是调用方自己持有 `ProcessGuard` 引用后直接调,`RunRegistry` 只做登记和查询。列入 §五 T9 的实现前置核实项,不在设计阶段假设死。 ### 3.7 P2 已落地的图校验,直接复用 `server/services/org-graph-service.js`(469 行)已实现四项写入前校验:`acyclic`(三色 DFS,仅针对 forward 边)、`single-entry`(forward 意义下入度为 0 的节点恰好一个)、`reachable`(孤立节点拒绝)、`backward-labeled`(构成回路的边必须标 `backward`,且不构成回路的边不许标 `backward`——**双向复核,不信任标注**)。 **work graph 的写入校验直接复用这一套**,不另写。这意味着 work graph 也**强制单入口**(R-13.4 原本只对 org graph 定案,本文档统一到两层)。 **需新增第五项 `fail-fallback-edge`**(R-16,见 §四.D.2.2):任何有 `fail` 出边的节点,必须至少留一条 `fail_reason IS NULL` 的兜底边。这一项 P2 现有实现里没有,两层都要加。 --- ## 四、设计方案(Model / View / Control / Process) ### A. Model(数据模型) #### A.1 分层:定义层 ≠ 运行时层 这是 v0.3 相对 v0.1 最大的改动,直接来自 R-15.4。 | | org graph | work graph | |---|---|---| | 生成者 | `orggraph-planning` | `workgraph-planning` | | 生成时机 | 建公司时,一次 | 每个 org node 接到任务时 | | 生命周期 | **长期**,活整个公司生命周期 | **一次性**,规划完即执行 | | 一份定义被跑几次 | **多次**(每来一个任务跑一遍) | 一次 | 因为 org graph 是「一份定义、多次执行」,运行时状态**不能**存在定义表上(否则一家公司永远只能跑一个任务)。所以: ``` 定义层(两套,各自保留,形态同构) org_graph_nodes / org_graph_edges ← P2 已落地,本文档只读不改(除 T-P3 加一列) work_graph_nodes / work_graph_edges ← 本文档新增 运行时层(一套,两层共用,引擎只认这个) graph_runs ← 一次执行实例 graph_run_nodes ← 该次执行里每个节点的状态 graph_run_loop_records ← 回退边的循环计数与判词 ``` `work_graphs` 表在 v0.1 里混装了图的定义元数据和运行时状态(`run_status` / `pause_requested` / `execution_mode`),本版把运行时那半拆去 `graph_runs`。 #### A.2 表结构(追加在 P0/P2 的 `graph.sqlite` 上,复用同一 DB 文件) ```sql -- ── 定义层:work graph(org graph 的两张表 P2 已建) ────────────── CREATE TABLE IF NOT EXISTS work_graphs ( id TEXT PRIMARY KEY, -- wg_ company_id TEXT NOT NULL, owner_org_node_id INTEGER REFERENCES org_graph_nodes(id), -- 这张图属于哪个 org node planned_by TEXT NOT NULL DEFAULT 'workgraph-planning', goal_id TEXT, -- 一次人类需求描述(唯一,验收边界) task_id TEXT, -- 执行单元,一个 goal 多个 okr_node_id TEXT, -- 形如 O-001.1.1,长周期度量归属 created_at TEXT NOT NULL ); -- goal_id / task_id / okr_node_id 三者基数不同、不可混用,见 27-NAMING §四。 -- v0.1 的单字段 goal_task_id 不够用,已拆开。 CREATE TABLE IF NOT EXISTS work_graph_nodes ( id TEXT PRIMARY KEY, -- wgn_ work_graph_id TEXT NOT NULL REFERENCES work_graphs(id), node_name TEXT NOT NULL, -- 图内唯一,如 org-coder-validator system_agent_id TEXT NOT NULL REFERENCES system_agents(id), -- 引用的本体,如 coder-validator node_kind TEXT NOT NULL DEFAULT 'agent_call' CHECK (node_kind IN ('agent_call','subgraph')), created_at TEXT NOT NULL ); -- node_name ≠ system_agent_id:节点名带领域前缀、本体名不带(R-15.3)。 -- 同一本体可被多个节点、多家公司引用,与 P1 虚拟引用寻址一致。 CREATE TABLE IF NOT EXISTS work_graph_edges ( id TEXT PRIMARY KEY, work_graph_id TEXT NOT NULL REFERENCES work_graphs(id), from_node_id TEXT NOT NULL REFERENCES work_graph_nodes(id), to_node_id TEXT NOT NULL REFERENCES work_graph_nodes(id), condition TEXT NOT NULL CHECK (condition IN ('success','fail')), fail_reason TEXT, -- 可空;condition='fail' 时的细分路由键,见 §四.D.2.2 edge_kind TEXT NOT NULL DEFAULT 'forward' CHECK (edge_kind IN ('forward','backward')), created_at TEXT NOT NULL ); -- ── 运行时层:两层共用 ────────────────────────────────────────── CREATE TABLE IF NOT EXISTS graph_runs ( id TEXT PRIMARY KEY, -- run_ graph_kind TEXT NOT NULL CHECK (graph_kind IN ('org','work')), graph_id TEXT NOT NULL, -- kind='org' → company_id;kind='work' → work_graphs.id company_id TEXT NOT NULL, root_run_id TEXT NOT NULL, -- 自身为 root 时 = 自己的 id;冗余存储,避免每次上溯 parent_run_id TEXT REFERENCES graph_runs(id), parent_node_run_id TEXT REFERENCES graph_run_nodes(id), -- 是哪个节点下钻出来的 goal_id TEXT, task_id TEXT, okr_node_id TEXT, execution_mode TEXT NOT NULL DEFAULT 'manual' CHECK (execution_mode IN ('manual','auto')), run_status TEXT NOT NULL DEFAULT 'planning', -- planning | ready | running | paused | blocked | completed | failed | stopped pause_requested INTEGER NOT NULL DEFAULT 0, -- 软信号,下一个节点边界生效 stop_requested INTEGER NOT NULL DEFAULT 0, backward_count INTEGER NOT NULL DEFAULT 0, -- run 级总回退次数,双层熔断的外层,见 §四.D.2.1 budget_json TEXT, -- 仅 root run 非空,见 §四.A.3 created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); -- v1 约束:同一 company_id 至多一个 run_status ∈ {ready,running,paused} 的 root run(§一非目标) CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_runs_one_active_root ON graph_runs(company_id) WHERE parent_run_id IS NULL AND run_status IN ('ready','running','paused'); CREATE TABLE IF NOT EXISTS graph_run_nodes ( id TEXT PRIMARY KEY, -- rn_ run_id TEXT NOT NULL REFERENCES graph_runs(id), def_node_id TEXT NOT NULL, -- 按所属 run 的 graph_kind 解释: -- 'org' → org_graph_nodes.id(整数转字符串) -- 'work' → work_graph_nodes.id status TEXT NOT NULL DEFAULT 'pending', -- pending | ready | running | success | fail | blocked | skipped attempt INTEGER NOT NULL DEFAULT 0, agent_run_id TEXT, -- node_kind='agent_call' 时的 RunRegistry runId child_run_id TEXT REFERENCES graph_runs(id), -- node_kind='subgraph' 时本次 attempt 起的子 run output_ref TEXT, -- 产出物相对路径,见 §四.A.5 fail_reason TEXT, -- 本次失败的细分原因,供边路由,见 §四.D.2.2 started_at TEXT, completed_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_run_nodes_unique ON graph_run_nodes(run_id, def_node_id); CREATE TABLE IF NOT EXISTS graph_run_loop_records ( id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES graph_runs(id), edge_id TEXT NOT NULL, -- 触发回退的那条 backward 边(org/work 边表按 kind 解释) from_node_run_id TEXT NOT NULL REFERENCES graph_run_nodes(id), to_node_run_id TEXT NOT NULL REFERENCES graph_run_nodes(id), loop_count INTEGER NOT NULL, -- 这是第几次沿这条边回退(1-based) verdict TEXT NOT NULL CHECK (verdict IN ('registered','fixed','not_fixed','force_terminated')), remediation_note TEXT, -- 「应该如何修复」,供下一轮读取 created_at TEXT NOT NULL ); ``` > ⚠️ **一处已知的类型不整齐**:`org_graph_nodes.id` 是 `INTEGER AUTOINCREMENT`(P0 建表时定的),`work_graph_nodes.id` 是 `TEXT`。`graph_run_nodes.def_node_id` 统一取 `TEXT`,org 侧存整数的字符串形式。代价是这一列不能建外键约束,得靠服务层保证引用完整性。备选是把 `org_graph_nodes` 的主键改成 TEXT——那要动 P2 已落地并已有数据的表,不值得。**上限**:`def_node_id` 无 FK 保护,删除定义节点时需服务层显式级联;升级路径是等 org 侧有独立迁移窗口时统一成 TEXT 主键。 #### A.3 任务级总预算:挂 root run [27-E2E](./27-e2e-task-execution-flow.md) §7.1 指出的最严重问题:三级恢复(跳回节点 → 重新 planning → 迭代 agent)如果每级都重置下一级的计数器,整个循环没有终止条件。分层预算(`retry_budget` / `l2_budget`)只是**局部快速失败**信号,不是兜底。 有了 run 层,兜底的挂载点很自然——**`budget_json` 只在 root run 上非空,所有子 run 通过 `root_run_id` 扣同一个池**: ```jsonc { "total_agent_calls": 100, // 所有层级所有 agent 调用的总次数 "total_tokens": 5000000, "wallclock_ms": 7200000, // 2h "spent": { "agent_calls": 0, "tokens": 0, "started_at": "..." } } ``` **只增不减**。任何一层发起 agent 调用前先按 `root_run_id` 检查余额;扣完不是失败,是**整棵 run 树挂起等人工**(root run → `blocked`,向下级联 `pause_requested=1`)。 按 `plan-cost-concurrency.md` 的实测,DevLoop 一个中等项目 ≈ 39 次 agent 调用 / 410K token / $4.8 / 墙钟 20 分钟;本架构还要叠加两层图的规划,粗估中等任务 **60-100 次调用、$10-20、1-2 小时**([27-E2E](./27-e2e-task-execution-flow.md) §7.6)。这个量级下自动模式**启动前必须把预估成本告诉用户**(§四.C)。 #### A.4 状态机 ``` graph_run_nodes.status: pending → ready (上游全部满足 / 无上游依赖) ready → running (被 advanceOne 拾取) running → success | fail (agent 调用结束 / 子 run 收敛) fail → ready (命中一条 backward 边且未超硬顶;或人工「重试」) → blocked (无可走的 fail 边 / 回退硬顶耗尽) success → (终态,除非人工「重试」强制打回 ready) blocked → ready (人工「重试」,唯一走出 blocked 的路) * → skipped (run 被「停止」时,所有仍处 pending/ready 的节点) graph_runs.run_status: planning → ready (图规划完成 + 通过 §三.7 四项校验) ready → running (「启动」) running → paused (「暂停」软信号,下一个节点边界生效) paused → running (「启动」或「下一步」恢复) running → blocked (某节点 blocked 且无其他节点在 ready/running) blocked → running (对 blocked 节点「重试」后) running/paused/blocked → stopped (「停止」) running → completed (所有可达节点到达终态,且无 pending/ready 悬空) ``` 非法转换(如对 `success` 节点直接「下一步」)在服务层拒绝并返回明确错误,模式与 `unit-registry.js` 的 `InvalidTransitionError` 一致。 #### A.5 产物布局与跨节点传递 v0.1 只有 `output_ref`(节点内产物指针),**不足以支撑 R-15.3 推导出的跨 org node 传递**:`goal-benchmark` / `goal-test-data` / `goal-test-script` 在 `org-planner` 这个 org node 的 work graph 里产出,消费者却是 `org-validator` 这个**另一个 org node**。 ``` data/companies/{cid}/runs/{rootRunId}/ ├── artifacts/ # 任务级共享产物区(root run 级,跨 org node 可读) │ ├── goal-benchmark.json # 验收契约,见阶段 0 │ ├── goal-test-data/ │ └── goal-test-script/ └── nodes/{nodeRunId}/ # 节点私有产出,output_ref 指向这里 └── attempt-{n}.md ``` **读写规则(照搬 `CONVENTIONS.md` §12 的隔离思路)**: | | 读 | 写 | |---|---|---| | 自己的 `nodes/{自己}/` | ✅ | ✅ | | 别的节点的 `nodes/{其他}/` | ❌ 禁止 | ❌ | | `artifacts/`(按 `root_run_id` 上溯) | ✅ 任意层级只读 | ⚠️ 需节点在定义里显式声明产出权 | 「下游只能看到上游的契约,看不到实现」这条 DevLoop 已验证的原则原样继承。写 `artifacts/` 是特权动作——只有被 `workgraph-planning` 标记为验收契约产出者的节点才有,防止任意节点往共享区乱写。 节点私有产出的物理位置仍沿用 27 号文档 §四已定的 System Agent 目录约定,本文档不新造路径。 #### A.6 幂等与并发 `advanceOne` 必须幂等:同一节点被并发触发两次(自动驱动器和人工同时点),第二次检测到 `status` 已不是 `ready` 就返回当前状态而不报错。不引入分布式锁——SQLite 行级事务 + `UPDATE ... WHERE status='ready'` 条件更新(受影响行数 = 0 即「已被别人拿走」)就够。 --- ### B. View(界面设计) #### B.1 页面结构 新页面、新路由,不挂在 `CompanyDashboard.vue` 已有的 tab 体系下(信息密度和交互复杂度明显超过一个 tab 该承载的量,参照 `PipelineEditor.vue` 独立成页的先例): ``` ┌──────────────────────────────────────────────────────────────────┐ │ 组织与执行 预算 42/100 calls · $6.2 · 38min │ ├───────────────┬──────────────────────────────┬───────────────────┤ │ Org Graph │ Work Graph 画布 │ 节点详情面板 │ │ (同一个画布 │ (选中 org node 的 work │ (点某个 work │ │ 组件,只是 │ graph,见 B.2) │ graph node 后 │ │ graph_kind= │ │ 展开,见 B.3) │ │ 'org') │ 控制栏: ▶启动 ⏭下一步 │ │ │ │ ⏸暂停 ⏹停止 🔁重试 │ 状态/耗时/attempt │ │ org-planner │ │ [概览|输入输出| │ │ ↓ │ ●pending ●running ●success │ 运行日志|子图] │ │ org-coder │ ●fail ●blocked ●skipped │ │ │ ↓ │ ┄┄▶ 回退边 2/3 │ │ │ org-validator │ │ │ └───────────────┴──────────────────────────────┴───────────────────┘ 面包屑:公司 › org-coder › (子图) ``` 左栏和中栏是**同一个画布组件的两个实例**——因为两层图同构(R-9.1),这是 R-15.4 引擎泛化在前端的对应收益。左栏点击某个 org node → 中栏加载该节点的 work graph(一个 org node 生命周期里可能跑过多张,默认显示最新,下拉切换历史)。 #### B.2 画布 - **节点**:矩形卡片,标题是 `node_name`,右上角小圆点按 `status` 着色(沿用仓库既有色彩语义:绿=success、蓝=running、灰=pending/ready、红=fail、橙=blocked、浅灰斜纹=skipped)。`node_kind='subgraph'` 的节点右下角带一个「⊞」角标,提示可下钻。 - **边**:`forward` 是实线箭头;`backward` 是**虚线曲线箭头**,琥珀色,曲线中点渲染徽标,内容取自 `graph_run_loop_records` 里该 `edge_id` 最新一条记录的 `loop_count`,格式 `2/3`——不是随便画一条回退线,是带着「当前第几次、硬顶是几」上下文的线。 - **布局**:**扩展 `UnitsDAG.vue`**(§3.5),不从零写。新增工作量只有三块:`node_kind='subgraph'` 角标、`backward` 边的虚线曲线路由(避开其他节点,这块是真新的)、循环徽标。不引入图形库——既有实现已证明这个规模手写 SVG 足够。 - **主流程 vs 异常流程**:`success` 前进边和节点是画布主干;所有和 `fail` 相关的边、`blocked` 节点、回退边整体**降低视觉权重**(统一加一层浅色背景框),让人一眼分清「这张图正常该怎么走」和「这次因为哪里失败绕了远路」。 #### B.3 节点详情面板(四个 tab) 1. **概览**:`status`、`attempt`、`started_at`/`completed_at`/耗时、`fail_reason`;如果这个节点参与过回退,展示 `graph_run_loop_records` 里相关的完整记录(`loop_count` / `verdict` / `remediation_note`)。 2. **输入输出**:渲染 `output_ref` 指向的文件。**「原始产出」和「实际被下游消费时的形态」要能分别展示**——大多数正向边上两者相同,但经过回退、拼接了「上一轮 remediation_note」之后就不同了,不能假设总是相同。若该节点读过 `artifacts/`,一并列出读了哪些。 3. **运行日志**:复用 §3.4 的双轨折叠卡片——`running` 时走 live 面板流式追加,`success`/`fail` 后切换成历史视图。展示的是**这次 agent 调用内部**的对话/工具调用记录。 4. **子图**:仅当 `node_kind='subgraph'` 且 `child_run_id` 非空时出现,内容是**递归复用同一个画布组件**指向 `child_run_id`,上方面包屑支持逐层下钻和返回。 #### B.4 预算条 页头常驻显示 root run 的预算消耗(calls / tokens / 墙钟)。**自动模式点「启动」前弹一次预估成本确认**——按 §四.A.3 的量级,这不是可选的礼貌,是必要的。 #### B.5 空态 一个 org node 从未跑过 work graph:中栏显示空态提示,不报错、不留白页面。 --- ### C. Control(控制操作) | 操作 | 可用条件 | 引擎侧动作 | 对正在跑的节点的影响 | |---|---|---|---| | **启动** | `run_status ∈ {ready, paused, blocked}` | `→running`;`auto` 模式立即调一次 `advanceOne()` 并让它在每次成功后自我调度下一次;`manual` 模式只标 running,停在原地等「下一步」 | 无 | | **下一步** | `run_status='running'` 且(`manual` 或 `auto` 已 `paused`) | 拾取**一个** `status='ready'` 的节点执行,完成后评估出边把满足条件的下游置 `ready`,**不继续往下跑**。多个并行 ready 时 UI 必须明确标出「接下来要跑哪个」,避免用户以为点一下推进所有分支 | 会真正发起一次 agent 调用,不可中途取消 | | **暂停** | `run_status='running'` | 置 `pause_requested=1`,**并沿 `parent_run_id` 向下级联到所有 active 子 run**。不打断当前正在 `running` 的节点,在下一个节点的调度前检查标志位 | 软暂停,生效点是下一个节点边界 | | **停止** | `run_status ∈ {running, paused, blocked}` | 置 `stop_requested=1` 并**向下级联**;所有仍 `pending`/`ready` 的节点批量 `skipped`;`→stopped`。**正在 `running` 的节点不打断**(T9 已核实,硬取消调用链不存在,见下) | 打不断,等它自己跑完;run 已是 `stopped`,但该节点的结果仍会照常落库 | | **重试** | 节点 `status ∈ {fail, blocked}` | 该节点 `→ready`,`attempt+1`。**默认不级联重置下游** | 无 | **三层级联**(R-15.4 / [27-E2E](./27-e2e-task-execution-flow.md) §7.5):v0.1 §八.4 把「子图不继承父图暂停状态」列为刻意简化,现在层级从两层变三层(root → org node → 嵌套子图),「点了暂停但子图还在偷偷跑」会成为真实困惑点。**定案:暂停/停止向下级联;「下一步」只作用于当前查看的层级**(符合直觉——暂停是全局意图,单步是局部操作)。`root_run_id` 冗余列让级联是一次索引查询,不用递归遍历。 **「重试」不级联下游的判据**(v0.1 §八.3 的 open question,现已关闭):不由重试动作决定,由**产出契约是否真的变了**决定。采用 `loops-l3.md` 的增量算法——按 `contract_hash` 把下游分成 added / changed / removed / **unchanged** 四类,`unchanged`(id 在且 hash 不变)保持原状**无须重跑**,只有 hash 变了的才回退到 `pending`。`hashContract()` 的实现见 `doc-store.js:382`(对 `contract.exports` 做递归 key 排序的规范化序列化后 sha256 取前 16 位),直接复用。 **手动/自动的统一原语**:两种模式落到服务层都是同一个 `advanceOne(runId)`,区别只在**谁调用它、调用节奏由谁决定**。手动 = 收到用户点击的路由 handler,每次一下;自动 = 引擎自己的「节点完成回调」,只要 `pause_requested`/`stop_requested` 都是假就在上一次 resolve 后立刻发起下一次。**只有一套推进逻辑,自动模式只是一个不停调用它的循环,不是另一套实现**——这是避免两套并行执行逻辑互相踩的关键。 **「停止」是软停止,不是硬取消**(T9 已核实,结论定案)。§3.6 当时留的 open question 现已关闭,**结论是「做不到」**——不是权衡后的取舍,而是硬取消所需的调用链在当前代码里根本不存在: - `ProcessGuard` **在生产代码里从未被实例化**。全仓库 `new ProcessGuard` 只出现在 `server/src/tests/unit/process-guard.test.js`;`server/src/engine/index.js:22` 只是把它 re-export 出去,没有任何调用方。所以「SIGTERM → 2s → SIGKILL」这段能力(`process-guard.js:96-117` 的 `_kill()`)目前是**死代码**。 - `RunRegistry` 被实例化并层层透传(`standalone-entry.js:19` → `Orchestrator` → `AgentManager`),但**没有任何生产代码调用过它的 `add()`**,注册表恒为空。因此「按 runId 找到某次调用」这个前提本身不成立,`RunRegistry` 里没有、也无从持有 `ProcessGuard` 引用。 - 真正持有子进程的是 `ClaudeCliProtocol._child`(`ClaudeCliProtocol.js:120` 的 `spawn`),杀它的唯一现存路径是 `disconnect()`(同文件 `530-538`,`stdin.end()` + `SIGTERM`,无 SIGKILL 兜底),由 `SessionPool.killActive()`(`session-pool.js:184`)经 `AgentManager.killCurrentProcess()`(`agent-manager.js:242`)暴露。**这条链现在也没有任何调用方**,且它只能杀「当前 active 会话」,粒度是会话不是 runId。 - 即便接上这条链,`graph-engine.js` 的 `defaultAgentExecutor` 每次调用都 `new AgentManager()` 一个**局部临时实例**(`graph-engine.js:149`),调用返回即不可达,`stopRun` 拿不到它。 **因此本文档定案:「停止」的语义就是「不再调度后续节点」,正在跑的节点等它自己跑完。** 用户点停止后 run 立刻变 `stopped`、`pending`/`ready` 节点立刻 `skipped`,但**已经发出的那一次 agent 调用会继续跑到结束**,其结果照常落库(不因 run 已 stopped 而丢弃——丢弃会浪费已花费的预算,且让产物与 timeline 对不上)。UI 必须把这点说清楚,不能让用户以为点了停止子进程就没了。 要把它升级成真硬取消,是一次**跨 4 个文件的新增接线工作**(让 protocol 暴露 runId 级句柄 → `SessionPool`/`AgentManager` 按 runId 登记进 `RunRegistry` → 引擎持有长生命周期 manager → `stopRun` 按 runId 取消),**不属于 T9 的「只读核实」范围**,需要时另立任务。 --- ### D. Process(执行过程) #### D.0 两种 node executor v0.1 只设计了一种执行语义。org graph 加入后必须分派(R-15.4): | | `agent_call` | `subgraph` | |---|---|---| | 执行 = | 调 `AgentManager` 跑 `system_agent_id`,写 `agent_run_id` | 起一张子图并等它收敛 | | success/fail 来源 | agent 调用结果 | 子 run `completed` → success;`blocked`/`failed` → fail | | 耗时量级 | 秒~分钟 | 分钟~小时 | | 谁用 | work graph 节点(默认) | **org graph 节点(全部)**;work graph 里 agent 自行判断需要拆子图的节点 | `subgraph` 节点的完整动作: ``` 节点 → running → 调 workgraph-planning(全局通用本体,R-15.2),输入 = 该 org node 的角色定义 + 任务描述 + 可读的 artifacts/ + 上一轮 remediation_note(若有) → 产出图 → 过 §三.7 四项校验 → 写 work_graphs / work_graph_nodes / work_graph_edges → 建子 graph_run(parent_run_id / parent_node_run_id / root_run_id 三者填好, execution_mode 默认继承父 run)→ 回填 child_run_id → 递归执行子 run(同一个 advanceOne) → 子 run 收敛 → 回写本节点 success/fail + fail_reason + remediation_note ``` 父节点在子 run 跑完之前一直停在 `running`。这也让 §四.B.3 的「子图」tab 有了明确的数据来源。 **⚠️ 收敛时必须透传三个值,不只是 success/fail**(R-16)。原因是决定「失败后走哪条边」的**不是失败节点自己,而是它子图里的归因节点**(§四.D.2.2):`org-validator` 这个 org node 判定任务未达成时,是它 work graph 里的 `validator-reflection` 节点算出了根因,这个结论必须能穿透子 run 边界回到 org 层,否则 org 层选边时无据可依。 | 回写字段 | 来源 | 用途 | |---|---|---| | `success` / `fail` | 子 run 的 `run_status` | 父节点状态转换 | | `fail_reason` | 子图归因节点的产出 | 父层 §四.D.2.2 选边 | | `remediation_note` | 同上 | 随回退传给目标节点,成为它下一次 `workgraph-planning` 的输入 | #### D.1 主流程 ``` 节点进入 ready → advanceOne 拾取 → running → 按 node_kind 分派执行(D.0) → 产出写入 output_ref(特权节点可另写 artifacts/) → success:遍历出边中 condition='success' 的边,目标节点若**所有**入边条件都满足则置 ready (多入边 = 汇合点,采用「全部满足」语义,与 27 号文档 §3.4 的图规划约定一致) → 所有节点到达终态且无 ready/pending 悬空 → run_status = completed → 若本 run 有 parent_node_run_id,回写父节点 success ``` #### D.2 异常流程 ``` 节点 running → fail(附带 fail_reason) → 遍历出边中 condition='fail' 的边,按 D.2.2 选一条 ├─ 选中边 edge_kind='forward' → 普通失败分支(如「失败转人工审核节点」) │ → 按主流程把 to_node 置 ready ├─ 选中边 edge_kind='backward' → 回退,进 D.2.1 熔断流程 └─ 无可走的 fail 边(死路)→ 该节点 blocked → 若无其他节点在 ready/running,run_status 同步 blocked → 这是「需要人工介入」的终止态,区别于「停止」(人工主动终止) ``` **D.2.1 回退熔断(两层通用,取代 v0.1 的 `loop_validator` 强制节点)** 引擎准备沿一条 `backward` 边推进时,无条件执行: 1. **备案**:按 `(run_id, edge_id)` 查 `graph_run_loop_records` 已有记录数 n,`loop_count = n + 1`,插入一条 `verdict='registered'`;同时 `graph_runs.backward_count += 1`。 2. **双层硬顶检查**:`loop_count > 3`(单边)**或** `backward_count > 5`(run 级总数)→ 不再调用任何 LLM,直接改 `verdict='force_terminated'`,源节点 `blocked`,链路收敛,等人工介入。**这一条是纯整数比较,不依赖 agent 调用**——保证熔断不会被 LLM 的自由发挥绕过。 3. **回退**:两个计数都未撞顶时把 `to_node` 置 `ready`、`attempt+1`,把上一轮的 `remediation_note` 作为上下文补充带给它。 > **为什么单边计数不够**(R-16):v0.1/v0.2 只按 `(run_id, edge_id)` 计数,前提是一个节点只有一条回退边。D.2.2 引入多条回退边之后,每条边各自计数,**硬顶实际变成 3×N**——归因节点只要每次归因到不同的 agent、走不同的边,就永远撞不到任何一个计数器的顶。这是 [27-E2E](./27-e2e-task-execution-flow.md) §7.1「每一级都重置下一级的计数器则整个循环没有终止条件」的同型变体:不是重置计数器,但效果一样。 > > 所以**两个计数都要**:单边计数防同一条路径上的死循环,run 级 `backward_count` 防「换个借口继续退」。它与 §四.A.3 的任务级总预算也是两回事——**预算管花了多少钱,`backward_count` 管绕了多少圈**,两者互不替代。 **`infra_flake` 不烧任何计数**:进程超时 / 被杀这类基础设施抖动,归因为 `infra_flake` 后直接原地重跑,**既不写 `graph_run_loop_records`,也不加 `backward_count`,也不扣 `retry` 预算**——沿用 DevLoop 的差异化预算消耗(`_spec/sdd-process.md` P-7)。不设这一类的话,超时会被误判成执行问题白烧一轮。 > **为什么不强制插 `loop_validator` 节点**:27 号总纲 §3.4 第 4 点要求 work graph 的回退边必须经过 `loop_validator`。但 org graph 是 `orggraph-planning` 生成的「这家公司有哪些角色」,往里塞一个基础设施节点会污染这个语义。**定案:熔断计数由引擎无条件做(两层都有),`loop_validator` 节点降级为可选增强**——`workgraph-planning` 可以在 work graph 里插它,由它做 27 号 §3.5 的「审计 + 修复方案传递校验」(判断上一轮到底修好没有、产出 `remediation_note`,写回 `verdict ∈ {fixed, not_fixed}`),那是 LLM 的活;「数到 3 就停」是代码的活。两者分工清楚,不互相依赖。 **D.2.2 一个节点有多条 fail 边时走哪条(R-16 定案)** 这是 org 层引入后冒出来的新问题。`org-validator` 判定任务未达成时,退回 `org-coder`(实现有问题)还是 `org-planner`(规划有问题)?两条都是从同一节点出去的 `fail` 边,`condition` 单靠 `success`/`fail` 二值区分不了。 **定案:归因是一次显式的 agent 调用,由专职节点做,不是失败节点顺手吐一个值。** `org-validator` 自己的 work graph 里,**第一个节点是 `validator-reflection`**,它的唯一职责是判断这次失败的根因:是哪个 agent 的哪个 skill 有问题、是哪个 agent 拿到的输入约束不够、还是哪个 agent 的执行出了问题。归因完成才知道该先改 skill、还是直接让某个 agent 带 bug context 重做。 这与 DevLoop 的既有分工同构——Integrator 判定集成失败、BugTriager 单独归因,是**两个不同的 agent**。理由是同一个 agent 既当裁判又当法医,容易把「我判失败」和「我认为该怪谁」混成一次输出。拆开的额外好处:归因有独立的落盘产物、可审计、可在控制台单独下钻。 **归因取值域与 DevLoop 四分类的对照**: | `fail_reason` | DevLoop 对应 | 回退动作 | 烧计数? | |---|---|---|---| | `impl_bug` | `impl_bug` | 该 agent 带 bug context 重做 | 烧单边 + `backward_count` | | `input_underspecified` | `contract_mismatch` / `spec_ambiguous` | 退回上游产出约束的那个节点 | 同上 | | `skill_defect` | **无对应** | 见下方 ⚠️ | 同上 | | `infra_flake` | `infra_flake` | 原地重跑 | **不烧任何计数**(D.2.1) | ⚠️ **`skill_defect` 这一支即 L4-company,而 L4 在 §一是非目标**。**v1 处理方式:保留这个归因取值让 `validator-reflection` 照常判定**(数据先攒着,归因体系一次成型,不用等 L4 做完再回来改分类),**但动作降级为「挂起等人工」,不自动触发 L4**。理由见 [27-E2E](./27-e2e-task-execution-flow.md) §八——L4 是三级恢复里最贵、爆炸半径最大的一级,§十 建议最后做。 **引擎侧的选边规则**(引擎本身不理解上述语义,只做匹配): - 边上有可空的 `fail_reason` 列;节点失败时把 `fail_reason` 写进 `graph_run_nodes`(子图节点的这个值由 §四.D.0 从子 run 透传上来); - **先找 `fail_reason` 精确匹配的边 → 无匹配则退到 `fail_reason IS NULL` 的兜底边 → 再无则视为死路**; - 取值域**不在引擎里硬编码**,由图的规划者(`orggraph-planning` / `workgraph-planning`)与对应 validator 约定。上表是推荐取值,不是引擎约束。 **因此写入前校验要加第五项**:任何有 `fail` 出边的节点,**必须至少留一条 `fail_reason IS NULL` 的兜底边**。否则归因产出一个图上没有对应边的取值时会直接落到死路,表现为「莫名其妙 blocked」。这一项要加进 §三.7 复用的那套校验里。 这对 P2 已落地的 `org_graph_edges` 是**加一列**(T-P3),不动现有唯一索引——两条 fail 边指向不同 `to_node_id`,本来就不冲突。 #### D.3 两级验收的引擎语义(R-15.3) | | work 层 `{orgNode}-validator` | org 层 `org-validator` | |---|---|---| | 在图上是 | work graph 里一个普通 `agent_call` 节点 | org graph 的末节点(`subgraph` 节点,它自己也有 work graph) | | 验什么 | 这个 org node 自己的产出合格吗 | 整个任务达成了吗 | | 引用本体 | `planner-validator` / `coder-validator` | `org-validator` | | fail 触发 | 本张 work graph 内的 backward 边 | **org graph 的** backward 边 → 退回某个 org node → 该 org node 整张 work graph 重跑(起新子 run,`attempt+1`) | `org-validator` 内部调 `validator-reflection` / `benchmark-validator` / `testdata-validator` 等 sub agent **不需要新机制**——它是一个 org node,按定义有自己的 work graph,这些 sub agent 就是那张图的节点: ``` org graph: org-planner → org-coder → org-validator ↓(它自己的 work graph) validator-reflection → benchmark-validator → testdata-validator → … ↑ 排第一位:先归因,再决定后面怎么验 / 怎么退 ``` `validator-reflection` 的产出(`fail_reason` + `remediation_note`)通过 §四.D.0 的三值透传回到 org 层,成为 §四.D.2.2 选边的依据。 两级验收的失败都从**同一个 root run 预算池**扣(§四.A.3),这正是 [27-E2E](./27-e2e-task-execution-flow.md) §7.1「三级恢复叠加会让熔断失效」的解法。 **谁验收「验收标准」本身**:按 R-9.3「planner 生成、validator 执行」,产出者和被验收者天然分离,不存在「自己给自己出考题」。但「标准写错了」这一层仍未解决,两条缓解都要:① `planner-validator` 明确承担一项职责——审「这套验收标准是否可度量、是否覆盖原始需求、是否存在平凡通过的漏洞」,不只审 PRD/SDD 本身;② 保留人工 sign-off 作为最终关卡,v1 阶段不做全自动闭环。 --- ## 五、任务划分 ### 五个阶段(每个可独立验收、独立上线) 切法与 [27-P2](./27-p2-org-graph.md) §五「三个可独立验收的阶段」一致:**不起 LLM 的先做完、能单独验收的先上线**。 | 阶段 | 含 | 交付什么 | 怎么验收 | 起 LLM | |---|---|---|---|---| | **0 · 验收契约** | T0 | 三种验收产物的统一契约格式 + 执行器 | 手写一份契约 + 一个被测产物 → 执行器跑出通过/不通过,判决可持久化 | ❌ | | **A · 引擎地基** | T1→T2→T5、T6、T9、T10 | 五张表、`advanceOne` 幂等原语、两种 node executor、SSE 三者原子化、五个控制端点 | 手写图 JSON → 手动模式逐节点推进到 `completed`;切自动模式一键跑完;暂停后能手动单步、能恢复自动 | ❌ mock | | **B · 回退熔断** | T7、T8 | backward 边计数 + 硬顶、`fail_reason` 路由、任务级预算、三层级联 | 总是失败的节点第 4 次 `force_terminated` 收敛到 `blocked`;预算扣完整棵 run 树挂起;暂停 root 后子 run 也停 | ❌ | | **C · 控制台** | T3、T4 | 扩展 `UnitsDAG.vue`、四 tab 详情、`parent_run_id` 面包屑下钻、预算条 | 回退边虚线 + `N/3` 徽标随流程递增;运行日志 live↔history 切换不丢内容;子图 tab 能逐层进出 | ❌ | | **D · 规划闭环** | T11、T12 | `workgraph-planning` agent + 用户→公司任务入口 | 一句自然语言任务 → org graph 自动逐节点起 work graph → 两层跑完 | ✅ | | **P · P2 连带** | T-P1、T-P2、T-P3 | R-15.3 的改名 + `fail_reason` 加列 | 三个模板末节点为 `org-validator`;NAMING 补 validator 命名轴;`org_graph_edges` 多一列且旧数据不受影响 | ❌ | **阶段间可以停**:只做完 0+A,系统就有了一个「能手工建图、能校验、能按五个操作跑」的通用图引擎;B 让它在失败时不失控;C 让人看得见;D 才让它自己规划。**最快看到端到端效果是 0→A→B→D,C 可后延**。 ### 任务表 > **状态列说明**(2026-08-16 实测复核,逐个文件读 + `npx vitest run server/tests/unit/graph-engine.test.js` 实跑): > **✅ 已实现** = 代码在、能 require、要求的能力都在;**⚠️ 部分** = 主体在但有明确未完成的子项,缺口写在括号里;**❌ 未做** = 没有对应代码。 > 状态列描述的是**落地进度**,不是设计内容——设计以本文档正文为准,状态过期时以代码为准重新核。 | # | 任务 | 涉及文件 | 依赖 | 阶段 | 状态(2026-08-16 实测) | |---|---|---|---|---|---| | **T0** | 验收契约格式(`goal-benchmark` / `goal-test-data` / `goal-test-script` 三种产物的统一 schema)+ 执行器 + 判决持久化 | `server/services/goal-contract.js`(新增)、契约 schema 文档 | 无 | 0 | **✅ 已实现** — `goal-contract.js`(672 行)三段 schema 校验 + `executeContract`(`spawn` 真实起 `node` 子进程,`RUNNERS` 白名单)+ `persistVerdict`/`listVerdicts`/`readVerdict`;schema 文档 `27-goal-contract-format.md` 已在。**缺**:无独立单测 | | **T1** | schema:五张表 + 状态转换表实现(照抄 `unit-registry.js` 模式)+ work graph 写入校验(复用 `org-graph-service.js` 四项) | `server/services/work-graph-db.js`(新增) | 无 | A | **✅ 已实现** — `work-graph-db.js`(827 行)五张表 + 两个唯一索引齐全;`canTransition` + `InvalidTransitionError` 按 `unit-registry.js` 模式;`validateWorkGraph` 真的 `require` 了 `org-graph-service.validateGraph` 做名字映射后复用,没另写一套 | | **T2** | `graph-engine.js`:`advanceOne(runId)` 核心原语、两种 node executor、幂等条件更新、run 树级联工具函数 | `server/services/graph-engine.js`(新增) | T1 | A | **✅ 已实现** — `graph-engine.js`(1191 行)`advanceOne` / `settleNode` / `settleRun` / `executeSubgraph` / `defaultAgentExecutor` / `descendantRuns` 全在;幂等靠 `UPDATE ... WHERE status=?` 条件更新 | | **T3** | 画布组件:**扩展 `UnitsDAG.vue`**,加 `subgraph` 角标、backward 虚线曲线路由、循环徽标;org/work 两层共用同一实例 | `web/src/components/WorkGraphCanvas.vue`(从 `UnitsDAG.vue` 抽取)、`web/src/views/GraphConsole.vue`(新增) | T6 | C | **✅ 已实现** — `WorkGraphCanvas.vue`(308 行)三块新增工作量都在:`⊞` 角标、backward 虚线曲线 + 分道避让、`N/3` 徽标(取同 `edge_id` 最新一条 `loop_count`);异常流程降权样式也在。路由已注册 | | **T4** | 节点详情四 tab + 面包屑下钻 + 预算条;运行日志复用 `AgentChat.vue` 双轨模式 | 同上 + 会话记录查询接口确认 | T2, T6 | C | **⚠️ 部分** — 四 tab(概览/输入输出/运行日志/子图)、面包屑逐层下钻、页头预算条、空态都已实现。**缺**:「运行日志」tab 的数据源是 `GraphRunPane` 的 SSE 缓冲,而引擎侧未接线(见 T5),**当前这个 tab 恒为空** | | **T5** | SSE:按 `run_id` 复用 `sse-broker.js` 模式;**状态转换 + timeline 写入 + SSE 广播三者原子化**(不重复 DevLoop 的两轨缺口) | `server/services/graph-run-sse.js`(新增,参照 `devloop/sse-broker.js`) | T2 | A | **⚠️ 部分** — `graph-run-sse.js`(364 行)已实现 `subscribe`/`emit`/`replayTo`/心跳,连原子包装 `transitionNode`/`transitionRun` 都写好了;`GET /:id/stream` 端点已挂。**缺(本任务的核心要求)**:`graph-engine.js` **全文没有 `require('./graph-run-sse')`**,走的是 `work-graph-db` 的裸 `updateNodeStatus`/`updateRunStatus`——「三者原子化」没落地,流上不会产生任何事件 | | **T6** | REST:`POST /api/graph-runs/:id/{start,next,pause,stop}`、`POST /api/graph-runs/:id/nodes/:nodeId/retry`、`GET /api/graph-runs/:id`(含 nodes/edges 全量状态)、`GET /api/graph-runs/:id/stream`、`GET /api/company/:cid/graph-runs` | `server/routes/graph-run.js`(新增) | T2 | A | **✅ 已实现** — 七个端点全在(`start`/`next`/`pause`/`stop`/`nodes/:nodeId/retry`/`GET :id`/`GET :id/stream`)+ `companyRouter`;`index.js:98-99` 与 `agent-server.js:71-72` 两个入口都已挂载 | | **T7** | 回退熔断:D.2.1 三步 + **双层硬顶**(单边 `loop_count` + run 级 `backward_count`)+ `graph_run_loop_records` 读写;`infra_flake` 不烧计数;D.2.2 的 `fail_reason` 选边 + 子 run 三值透传 | `graph-engine.js` 扩展 | T2, T-P3 | B | **✅ 已实现** — `handleBackwardEdge` 备案→双层硬顶→回退三步齐;`LOOP_HARD_CAP_EDGE=3` / `LOOP_HARD_CAP_RUN=5` 是纯整数比较;`INFRA_FLAKE_REASON` 走原地重跑不烧计数;`selectFailEdge` 精确匹配→兜底边;`deriveChildOutcome` 从 `ATTRIBUTION_NODE_NAME='validator-reflection'` 取三值透传 | | **T8** | 任务级总预算(root run 扣减 + 熔断)+ 三层暂停/停止级联 + 「重试」的 `contract_hash` unchanged 判据 | `graph-engine.js` 扩展 | T2 | B | **✅ 已实现** — `checkBudget`/`spendBudget`/`suspendRunTree` 按 `root_run_id` 扣同一池;`descendantRuns` 靠 `root_run_id` 一次查询做级联,`pauseRun`/`stopRun` 都向下级联;`diffContracts`/`applyRetryCascade` 直接 `require` 了 `devloop/doc-store` 的 `hashContract`,没平行发明 | | **T9** | §3.6 取消能力的**实现前核实** + 落地:确认 `RunRegistry`/`ProcessGuard` 调用链,「停止」接入硬取消;或确认做不到、落地降级并回改本文档 §四.C | `server/src/engine/`(只读研究为主,必要时补一个查询接口) | 无,可最早独立开工 | A | **⚠️ 部分** — §四.C 写明的**降级路径已落地**(`stopRun` 置 `stop_requested` + `pending`/`ready` 批量 `skipped`,不再调度后续节点)。**缺(本任务的实质)**:`RunRegistry`/`ProcessGuard` 调用链**没有核实**,硬取消没接;代码里两处注释仍写着「由 T9 核实/补齐」,本文档 §四.C 也未按核实结果回改 | | **T10** | 测试:状态机非法转换、幂等 `advanceOne`、回退硬顶、预算熔断、级联;一条端到端脚本(建两层图 → 启动 → 若干次 advance → 触发回退 → 硬顶终止 → 查最终状态) | `server/tests/unit/graph-engine.test.js`(新增) | T2, T7, T8 | A/B | **⚠️ 部分** — `graph-engine.test.js`(816 行)17 个用例,覆盖面对得上验收清单。**但实跑 2 条失败(15 passed / 2 failed)**:① 「回退后 subgraph 节点重跑应起一张新的子 run」(§四.D.3 要求整张 work graph 重跑);② 「org 层同一条校验也要有」(即 T14 的 org 侧缺口)。另 `goal-contract.js` / `work-graph-db.js` 无独立测试 | | **T11** | `workgraph-planning` agent 本体(全局通用,R-15.2):读 org node 角色定义 + 任务 + `artifacts/` + 上一轮 `remediation_note` → 产出图 → 过校验 → 落库。生成的图**不得在节点内部再套四段式流转**(§九bis) | `system/templates/workgraph-planning/`(新增) | T1, T6 | D | **✅ 已实现** — `system/templates/workgraph-planning/`(agent.md / config.json / identity.md / soul.md / tools.md)已建并注册进 `_registry.json`;配套 `system/work-graph-templates/`(planner / executor / executor-fanout / validator 四个骨架 + README)已在 | | **T12** | 用户→公司的任务入口:`POST /api/company/:cid/tasks`,建 root run 并起 org graph 执行;复用既有 `task/dispatch` + `task/report` 回调链路 | `server/routes/company.js` 或新 `routes/task-entry.js` | T2, T11 | D | **✅ 已实现** — `company.js:1307` `POST /:companyId/tasks`:建 `graph_kind='org'` 的 root run → 写 task-goal artifact → `markRunReady` + `startRun` → **同步返回不等图跑完**;v1 单 active root run 约束做了预检查 + 唯一索引兜底两道;auto 模式挂 driver 并在收敛后 `reportRunOutcome` | | **T-P1** | 三个 org graph 模板末节点改 `org-validator`;`dev.json` 的回退边目标按 D.2.2 重画(`fail_reason` 区分退 coder 还是退 planner) | `system/org-graph-templates/{dev,content,ops}.json` | T-P3 | P | **✅ 已实现**(模板侧) — `dev`/`content`/`ops` 三张图节点均为 `org-planner` + 中段职能 + `org-validator`;`dev.json` 两条 fail 回退边已按 D.2.2 重画(`failReason: "input_underspecified"` → `org-planner`,兜底边 → `org-coder`)。**注意**:这个 `failReason` 目前**写不进库**,被落库路径丢弃,见 T-P3 | | **T-P2** | NAMING §三 删掉 `org-validator` 行;**新增 validator 命名轴一节**(节点名带领域前缀、本体名不带,R-15.3 的表) | `docs/todo/system-design/27-naming-conventions.md` | 无 | P | **✅ 已实现** — §三 已按「所在图的层级」重写:§3.1 两层节点名规则、§3.2「节点名 ≠ 本体名」新命名轴表、§3.3「三个 validator 是三个独立本体」、§3.4 存量归位映射表(`code-*` → `org-*` 作为作废记录保留) | | **T-P3** | `org_graph_edges` 加可空 `fail_reason` 列(D.2.2);`graph_runs` 加 `backward_count`;新建三个 validator 本体的 agent 模板 | `server/services/graph-db.js`、`system/templates/{planner-validator,coder-validator,org-validator}/` | 无 | P | **⚠️ 部分** — 列加了(`graph-db.js:72-73` 的 `ALTER TABLE org_graph_edges ADD COLUMN fail_reason`)、`graph_runs.backward_count` 在(`work-graph-db.js:102`)、三个 validator 模板已建并注册。**缺**:`org-graph-service.js` 的 `normalizeEdges`(行 45)和 `insertEdge`(行 235)**都不读也不写 `fail_reason`**——列建了但永远是 NULL,org 层的 D.2.2 细分路由目前无数据可用 | | **T13** | `validator-reflection` agent 本体(R-16):归因产出 `fail_reason` + `remediation_note`;`org-validator` 的 work graph 骨架把它排在第一位 | `system/templates/validator-reflection/`(新增) | T-P3 | B | **✅ 已实现** — `system/templates/validator-reflection/` 已建并注册(`_registry.json` 的 description 写明四类归因取值 + `skill_defect` 挂起等人工不触发 L4);引擎侧 `ATTRIBUTION_NODE_NAME = 'validator-reflection'` 常量已用于三值透传 | | **T14** | 写入前校验新增第五项 `fail-fallback-edge`(§三.7):有 `fail` 出边的节点必须留一条 `fail_reason IS NULL` 兜底边;org / work 两层都加 | `server/services/org-graph-service.js`、`work-graph-db.js` | T1 | B | **⚠️ 部分** — **work 层已加**(`work-graph-db.validateFailFallback`,接在复用的四项之后)。**org 层未加**:`org-graph-service.validateGraph` 仍是四项,`fail-fallback-edge` 这条规则不存在,对应测试用例「org 层同一条校验也要有」**正在失败**。本任务要求的是「两层都加」,只做了一层 | > ⚠️ **T-P1 / T-P2 / T-P3 是 P2 侧文件的连带修改,但归 P3 执行**。P2 正由另一条线推进中,这批改动写在本文档而非直接改 P2 的文档/模板,是为了避免两边同时写同一批文件产生冲突。P2 那条线**不要动**这三项。 **顺序建议**:T0 和 T9 可最早独立开工,互不阻塞。T-P3 要在 T7 之前(`fail_reason` 是 D.2.2 的地基)。T1→T2 是硬串行地基。T5/T6 依赖 T2,可并行。T3 建议先用 T1 的 schema 手写几行数据跑通画布,再接 T6 的真实端点。 --- ## 六、验收标准 **阶段 0** 1. 手写一份 `goal-benchmark` + `goal-test-data` + `goal-test-script`,执行器能对一个被测产物跑出明确的通过/不通过判决,判决落库可查。 **阶段 A** 2. 一张只有正向边、3-4 节点的图:手动模式连续点「下一步」逐节点推进到 `completed`,**每次点击只推进一个节点**(不因为下游 ready 了就自动继续)。 3. 同一张图切自动模式点「启动」:不再需要任何人工点击,自动跑到 `completed`。 4. 自动模式运行中点「暂停」:当前 `running` 节点跑完后 `run_status → paused`,不再自动调度;此时点「下一步」能手动单步;点「启动」能恢复自动。 5. 点「停止」:所有 `pending`/`ready` 节点变 `skipped`,`run_status → stopped`。若 T9 确认取消可用,正在 `running` 的节点被中断且状态可区分于正常 `fail`。 6. 一张 org graph(`graph_kind='org'`)用**同一套端点**跑通上述 2-5,代码路径与 work graph 完全一致——这是 R-15.4 引擎泛化的核心验收点。 7. 一个 `subgraph` 节点执行时正确起子 run、`child_run_id` 回填、子 run 收敛后父节点拿到正确的 success/fail。 **阶段 B** 8. 构造一个总是失败的节点,其 `fail` 边是指回上游的 `backward` 边:第 1-3 次回退正常触发(`graph_run_loop_records` 各一行),**第 4 次不再调用任何 agent、直接 `force_terminated`**,图收敛到 `blocked`。 9. 一个节点有两条 `fail` 边(`fail_reason` 分别为 A / 空):节点带 `fail_reason=A` 失败时走第一条,带其他值失败时走兜底边。写入一张有 `fail` 出边却无兜底边的图 → 被 `fail-fallback-edge` 校验拒绝,返回 400。 9b. **多边不架空熔断**:构造一个有 3 条回退边的节点,让归因每次归到不同的边——单边计数各自都没到 3,但 run 级 `backward_count` 到 5 时仍 `force_terminated`。 9c. `validator-reflection` 归因为 `infra_flake` 时原地重跑,`graph_run_loop_records` 不增行、`backward_count` 不递增。 9d. 一个 `subgraph` 节点的子 run 因内部归因失败而收敛:父节点同时拿到 `fail`、`fail_reason`、`remediation_note` 三个值,并据此在父层正确选边。 10. root run 预算扣完:整棵 run 树挂起,不是某一层单独失败。 11. 对 root run 点「暂停」:正在跑的子 run、孙 run 全部在下一个节点边界停下。 12. 对一个 `blocked` 节点点「重试」:节点回 `ready` 并能继续推进,不需要重建整张图;下游 `contract_hash` 未变的节点保持原状不重跑。 **阶段 C** 13. 画布:回退边渲染为虚线曲线且显示 `N/3` 徽标,随 D.2.1 推进数字正确递增。 14. 「运行日志」tab:`running` 时实时追加,`success`/`fail` 后切历史视图,内容不丢。 15. `subgraph` 节点的「子图」tab 点进去是完整可交互(能点「下一步」)的嵌套画布,面包屑能逐层返回。 16. 左栏点一个从未跑过 work graph 的 org node:中栏空态提示,不报错。 **阶段 D** 17. 对一家 org graph 已就绪的公司下达一句自然语言任务:自动建 root run → 第一个 org node 起 work graph → 两层跑到 `completed`,全程无需手工构造任何图数据。 --- ## 七、影响面 / Blast Radius | 文件 | 改动类型 | |---|---| | `server/services/work-graph-db.js` | 新增:五张表 + 状态转换表 + work graph 写入校验 | | `server/services/graph-engine.js` | 新增:`advanceOne` + 两种 executor + 回退熔断 + 预算 + 级联 | | `server/services/graph-run-sse.js` | 新增:参照 `sse-broker.js` | | `server/services/goal-contract.js` | 新增:验收契约 schema + 执行器 | | `server/routes/graph-run.js` | 新增:控制类 + 只读查询类端点 | | `server/routes/company.js` | 追加:任务入口端点(T12) | | `web/src/views/GraphConsole.vue` | 新增:主页面 | | `web/src/components/WorkGraphCanvas.vue` | 新增:从 `UnitsDAG.vue` 抽取,org/work 两层共用 | | `system/templates/workgraph-planning/` 等四个 | 新增:规划 agent + 三个 validator 本体 | | `server/services/graph-db.js` | 追加:`org_graph_edges` 加 `fail_reason` 列(T-P3) | | `system/org-graph-templates/*.json` | 修改:末节点改名 + 回退边重画(T-P1) | | `docs/todo/system-design/27-naming-conventions.md` | 修改:§三 删行 + 新增 validator 命名轴(T-P2) | | `server/src/engine/run-registry.js` | 只读研究为主,T9 视核实结果决定是否补一个查询接口 | **明确不改**:DevLoop 全部现有代码(`loop-controller.js` / `unit-registry.js` / `doc-store.js` 只被**读取和借鉴**,收编是 P6)、P2 的 `org-graph-service.js` 四项校验(只复用)、`CompanyDashboard.vue`(新页面独立存在,只从 Dashboard 加一个跳转入口)。 --- ## 八、风险 / Open Questions 1. **归因能精确到哪一层,尚未定案**(R-16 遗留)。原话说「直接让某个 agent 直接 +bug context 描述直接重做」,但若 `validator-reflection` 判定问题出在某个 org node **内部 work graph 的具体节点**,org 层的边只能退到 **org node 粒度**。两条路: - **(倾向)保持层级封装**:org 层只退到 org node,`remediation_note` 跟着传下去,由该 org node 自己的 `workgraph-planning` 决定是重新规划一张图、还是复用旧图只重跑某个节点。好处是 [27-E2E](./27-e2e-task-execution-flow.md) §四 #4 的「重新 planning vs 跳回节点」这个判断留在 org node 内部做,不上升到 org 层;坏处是多一跳。 - **允许跨层直接寻址目标节点**:更快,但破坏封装,且控制台上「暂停 / 单步」作用于哪一层会变得含糊。 2. **`validator-reflection` 的命名尚未定案**(R-16 遗留)。按 [27-NAMING](./27-naming-conventions.md) §三 现行规则(work graph 节点 = `{父 org 节点职能}-{职能}`),它作为 `org-validator` 的 work graph 节点应为 `validator-reflection`,与原话一致。但它做的是**归因**不是**判定**,是否改叫 `validator-triager`(对齐 DevLoop 的 BugTriager)待定。 3. **`fail_reason` 的取值域不由引擎约束**(§四.D.2.2)——引擎只做字符串匹配,取值由图的规划者和 validator 自行约定。好处是不把 DevLoop 的四分类硬编码进通用层;风险是归因产出一个图上没有对应边的取值。**缓解已定案**:写入前校验新增第五项 `fail-fallback-edge`(§三.7),强制每个有 `fail` 出边的节点留一条兜底边。 4. **`org_graph_nodes.id` 是整数、`work_graph_nodes.id` 是文本**,`graph_run_nodes.def_node_id` 只能取 TEXT 且无法建外键(§四.A.2 的注)。引用完整性靠服务层保证。 5. **回退边曲线路由是真实的手写前端工程量**(§四.B.2)。没引入图形库符合仓库一贯风格,但这块工时不能按「拿组件库拼一下」估。若实现中发现多条回退边交叉的边界情况成本远超预期,值得重新评估引入 dagre 的纯布局计算部分(不要它的渲染层)——本文档不预设结论。 6. ~~**`RunRegistry`/`ProcessGuard` 的取消调用链没有 100% 核实**(§3.6)~~ **【已关闭,2026-08-16 T9 逐行核实】结论:硬取消做不到,「停止」定案为软停止。** `ProcessGuard` 在生产代码里从未被实例化(只有测试 `new` 它),`RunRegistry.add()` 从未被调用(注册表恒为空),两者之间也不存在引用关系;唯一能杀子进程的 `ClaudeCliProtocol.disconnect()` → `SessionPool.killActive()` → `AgentManager.killCurrentProcess()` 这条链同样零调用方,且粒度是会话而非 runId。完整证据与 file:line 见 §四.C「『停止』是软停止,不是硬取消」。**残留风险已从「能不能取消」转为产品预期管理**:用户点停止后正在跑的节点仍会跑完(最长一个节点的时长),UI 必须明示,否则会被当成 bug 报上来。 7. **v1 的「一家公司同时只有一个 active root run」是一条真实的产品限制**,不只是技术妥协。它由 `CONVENTIONS.md` §12 的不变量和 SessionPool key 复用共同决定(§一非目标)。如果用户很快就要「一家公司并行接多个任务」,实例隔离要提前排期。 8. **`workgraph-planning` 的规划质量没有硬校验**。§三.7 只保证图**结构合法**,不保证它**适合这个任务**。缓解手段与 P2 同款:规划记录落盘供人工复核,发现不合理走增量修正。 9. **阶段 0 的契约格式一旦定错,阶段 A 的 schema 可能要返工**。这也正是 R-15.6 把它提到最前面的原因——但「提前」只降低概率,不消除风险。建议 T0 先把契约的**存储位置和与 `output_ref` / `artifacts/` 的关联方式**定死,格式内部细节可以后续演进。 --- ## 九、与其他阶段的关系 - **与 P2**:强依赖。P2 产出 org graph 定义,本文档执行它。**两者共用同一套 schema 形态、执行引擎、控制台画布**——这是 R-9.1 新模型最大的收益。本文档只读 `org_graph_nodes/edges`(唯一例外是 T-P3 加一列 `fail_reason`)。P2 侧的三项连带修改(T-P1/T-P2/T-P3)归本阶段执行,见 §五的警告框。 - **与 P1**:无直接依赖,已实现(commit `226489d`)。P1 改的是 prompt 从哪来,不改调用接口。但 R-15.3 的「本体名不带领域前缀」正是 P1「同一份本体、多处引用、各自私有语境」的直接推论。 - **与 P5(自我进化)/ L4**:本文档不含。任务级预算里预留了 `l4_iterations` 的位置但不实现。 - **与 P6(DevLoop 收编)**:本引擎从 DevLoop **抽象**而来(§三),但不改它一行。收编的验收标准是「DevLoop 现有测试套件在新引擎上全部通过」,属 P6。 - **与 base agent 的四段式**:见下方 §九bis——原表述「已强制一套四段式生命周期」不准确,实测有一半没落地。 - **与端到端流程**:本文档设计的是「一张图怎么被执行和控制」,完整的七阶段链路见 [27-E2E](./27-e2e-task-execution-flow.md) §三,跑一遍具体的数见 [27-EXAMPLE](./27-example-dev-company-walkthrough.md)。 --- ## 九bis、base agent 四段式的现状核实 [27-E2E](./27-e2e-task-execution-flow.md) §八bis 说 `system/templates/base/` 「已强制一套四段式生命周期」,并把它当作「每个 node agent 内部也是一张图」的现成雏形。**核实后这个说法只对一半**,本节记录实测结论——它直接决定了 P3 之后那项「统一两套状态机」的待办到底要做什么。 ### 设计意图(`system/templates/base/agent.md`,28 行) ``` RESEARCH ──→ PLAN ──→ EXECUTE ──→ VERIFY ↑ │ └───────── 失败写 _lessons.md 打回 ┘ ``` agent 默认**只挂载 `meta-research` 一个元技能**,必须主动呼叫 `node bin/lemon.js task transition --agentId --phase --artifact ` 才能换脑子换技能包;每次流转**清空上下文**(原文叫「斩断记忆 / Context Flush」)防长对话累积幻觉;EXECUTE 阶段才拿到「修改核心文件的破坏性权限」;VERIFY 通过才可 `report_task({status:"PASS"})`。 **这确实就是一张最小 work graph**:四个节点、线性前进、末端一条回退边,且已具备 P3 引擎需要的三样东西——显式的阶段状态、阶段间的产物传递(`--artifact`)、失败回退。 ### 实测:上下文隔离是真的,权限/技能隔离是假的 `POST /api/agent/:agentId/task/transition`(`server/routes/agent-chat.js:1832`)已实现,且比 prompt 里写的还多: | 机制 | 状态 | 位置 | |---|---|---| | Context Flush(断 ACP 进程 + `history.json` 清空 + artifact 注入新起步指令 + 重新唤醒) | ✅ 真的在跑 | `agent-chat.js:1916-1960` | | **P0 事前阻断阀**——P0 任务 `plan → execute` 拦截挂起、通知 Master 人工审批才放行 | ✅ 已实现(prompt 里没写这条) | `agent-chat.js:1854-1891` | | OKR 联动——顺带把节点状态更新为 `researching`/`planning`/`executing`/`verifying` | ✅ | `agent-chat.js:1894-1905` | | **Hot Swap 换技能包** | ❌ **静默失效** | `agent-chat.js:1908` | 失效原因:代码是 `const sourceSkill = .../system/skills/meta-${phase}/SKILL.md` 后跟 `if (fs.existsSync(sourceSkill))` 才拷贝,而 **`system/skills/` 这个目录在仓库里根本不存在**,四个 `meta-*` 技能一个都没有。所以每次流转的「动态换脑」是空转,那句 `🧠 动态技能树已切换` 的日志压根不会打印,**也没有任何报错**。 **后果**:「EXECUTE 阶段才拿到破坏性权限」这个设计意图目前**只靠 prompt 话术约束,没有任何机制保障**——agent 在 RESEARCH 阶段照样能写文件。 另两处顺带发现:`phase` 参数**没有任何校验**,既不校验流转顺序(可以 research 直接跳 verify、跳过中间两段),也不校验取值本身,而它被直接拼进文件路径。 ### 对 P3 的影响 原来那条待办(「保证两套状态机语义不冲突」)应当升级为一个更具体、收益也更明确的目标:**把四段式改写成引擎上的一张标准图模板**。这样做同时解决三件事: 1. 消除「引擎层的图」和「agent 内部的四段式」两套并行状态机; 2. `meta-*` 技能的挂载正好对应 work graph 节点的 `system_agent_id` 引用,**顺手把 `system/skills/` 缺失这个洞补上**——现在这批技能没有读取方,改造后引擎就是读取方; 3. 阶段顺序校验由引擎的边定义天然提供,不需要另写。 **仍列为 P3 之后的待办**,不进本阶段范围。但 §五 的 T11(`workgraph-planning`)在生成图时应当**避免与四段式语义打架**——具体是别让 work graph 节点内部再套一层四段式流转,否则同一次执行会有两层 Context Flush 互相清对方的上下文。