27-p3-p4-work-graph-console.md 72.6 KB

27-P3/P4. 图执行引擎与执行控制台 — 需求与设计文档

所属: 27 Graph Agent 架构 的 Phase P3(最小闭环)+ P4(回退 + 熔断),外加 27 号文档原始路线图里没有单独立项的两块新增交付物——一个执行控制台页面,以及 workgraph-planning agent + 用户→公司的任务入口。 版本: v0.3(按 27-REQ R-15 六条定案重写;v0.1 正文与 v0.2 修正块已合并入正文,不再单列) 日期: 2026-08-15 前置: 27-P2 Org Graph 落地 阶段 A/B。P0/P1 均已实现并提交(P1 = commit 226489d)。 命名: 全文遵循 27-NAMING,含本文档 §五 T-P2 要求新增的 validator 命名轴。 配套: 27-E2E 端到端流程、27-EXAMPLE 参考场景 设计方法论: 核心设计(§四)用 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 §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 §7.4)。必须先做同一 system agent 的多实例隔离,是独立工作量。v1 直接约束「一家公司同时只有一个 active root run」,新任务排队——注意这条约束在 org 层就需要,不是等到 work 层 fan-out 才需要。
  • 不做 L4(system agent 自我迭代)。见 27-E2E §八,且它是三级恢复叠加里最贵、爆炸半径最大的一级。
  • 不做对 DevLoop 现有 loop-controller.js / unit-registry.js 的收编。它是本架构的参考实现(27-E2E §二结论 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 + <marker> 箭头 + 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 文件)

-- ── 定义层:work graph(org graph 的两张表 P2 已建) ──────────────

CREATE TABLE IF NOT EXISTS work_graphs (
  id                TEXT PRIMARY KEY,        -- wg_<nanoid>
  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_<nanoid>
  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_<nanoid>
  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_<nanoid>
  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 §7.1 指出的最严重问题:三级恢复(跳回节点 → 重新 planning → 迭代 agent)如果每级都重置下一级的计数器,整个循环没有终止条件。分层预算(retry_budget / l2_budget)只是局部快速失败信号,不是兜底。

有了 run 层,兜底的挂载点很自然——budget_json 只在 root run 上非空,所有子 run 通过 root_run_id 扣同一个池:

{
  "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 §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 独立成页的先例):

┌──────────────────────────────────────────────────────────────────┐
│  <company name>  组织与执行        预算 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 §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 §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 §八——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 §7.1「三级恢复叠加会让熔断失效」的解法。

谁验收「验收标准」本身:按 R-9.3「planner 生成、validator 执行」,产出者和被验收者天然分离,不存在「自己给自己出考题」。但「标准写错了」这一层仍未解决,两条缓解都要:① planner-validator 明确承担一项职责——审「这套验收标准是否可度量、是否覆盖原始需求、是否存在平凡通过的漏洞」,不只审 PRD/SDD 本身;② 保留人工 sign-off 作为最终关卡,v1 阶段不做全自动闭环。


五、任务划分

五个阶段(每个可独立验收、独立上线)

切法与 27-P2 §五「三个可独立验收的阶段」一致:不起 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

  1. 一张只有正向边、3-4 节点的图:手动模式连续点「下一步」逐节点推进到 completed,每次点击只推进一个节点(不因为下游 ready 了就自动继续)。
  2. 同一张图切自动模式点「启动」:不再需要任何人工点击,自动跑到 completed。
  3. 自动模式运行中点「暂停」:当前 running 节点跑完后 run_status → paused,不再自动调度;此时点「下一步」能手动单步;点「启动」能恢复自动。
  4. 点「停止」:所有 pending/ready 节点变 skipped,run_status → stopped。若 T9 确认取消可用,正在 running 的节点被中断且状态可区分于正常 fail。
  5. 一张 org graph(graph_kind='org')用同一套端点跑通上述 2-5,代码路径与 work graph 完全一致——这是 R-15.4 引擎泛化的核心验收点。
  6. 一个 subgraph 节点执行时正确起子 run、child_run_id 回填、子 run 收敛后父节点拿到正确的 success/fail。

阶段 B

  1. 构造一个总是失败的节点,其 fail 边是指回上游的 backward 边:第 1-3 次回退正常触发(graph_run_loop_records 各一行),第 4 次不再调用任何 agent、直接 force_terminated,图收敛到 blocked。
  2. 一个节点有两条 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 三个值,并据此在父层正确选边。
  3. root run 预算扣完:整棵 run 树挂起,不是某一层单独失败。
  4. 对 root run 点「暂停」:正在跑的子 run、孙 run 全部在下一个节点边界停下。
  5. 对一个 blocked 节点点「重试」:节点回 ready 并能继续推进,不需要重建整张图;下游 contract_hash 未变的节点保持原状不重跑。

阶段 C

  1. 画布:回退边渲染为虚线曲线且显示 N/3 徽标,随 D.2.1 推进数字正确递增。
  2. 「运行日志」tab:running 时实时追加,success/fail 后切历史视图,内容不丢。
  3. subgraph 节点的「子图」tab 点进去是完整可交互(能点「下一步」)的嵌套画布,面包屑能逐层返回。
  4. 左栏点一个从未跑过 work graph 的 org node:中栏空态提示,不报错。

阶段 D

  1. 对一家 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 §四 #4 的「重新 planning vs 跳回节点」这个判断留在 org node 内部做,不上升到 org 层;坏处是多一跳。
    • 允许跨层直接寻址目标节点:更快,但破坏封装,且控制台上「暂停 / 单步」作用于哪一层会变得含糊。
  2. validator-reflection 的命名尚未定案(R-16 遗留)。按 27-NAMING §三 现行规则(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-EXAMPLE。

九bis、base agent 四段式的现状核实

27-E2E §八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 <id> --phase <next> --artifact <path> 才能换脑子换技能包;每次流转清空上下文(原文叫「斩断记忆 / 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 互相清对方的上下文。