27-P3/P4. 图执行引擎与执行控制台 — 需求与设计文档
所属: 27 Graph Agent 架构 的 Phase P3(最小闭环)+ P4(回退 + 熔断),外加 27 号文档原始路线图里没有单独立项的两块新增交付物——一个执行控制台页面,以及
workgraph-planningagent + 用户→公司的任务入口。 版本: v0.3(按 27-REQ R-15 六条定案重写;v0.1 正文与 v0.2 修正块已合并入正文,不再单列) 日期: 2026-08-15 前置: 27-P2 Org Graph 落地 阶段 A/B。P0/P1 均已实现并提交(P1 = commit226489d)。 命名: 全文遵循 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 推翻,改为向下级联。
一、目标与非目标
目标
- 一套图执行引擎,同时驱动 org graph(company 级 workflow)和 work graph(org node 级 workflow)—— 两者是同一种东西在不同层级的递归(R-9.1),引擎不为它们各写一套。
- 执行控制:启动、下一步、暂停、停止、重试五个操作,同时支持手动(点一次推进一个节点)和自动(一键授权跑到底)两种模式,且在每一层语义完全一致。
- 回退与熔断:
edge_kind='backward'的回退边带循环计数与硬顶,两层通用;跨所有层级共享一个任务级总预算。 - 一个执行控制台页面:左栏 org graph,中间选中 org node 的 work graph 画布,右栏节点详情;回退边可视化带
N/3徽标;主流程 / 异常流程视觉区分;逐层下钻(agent 对话记录 + 嵌套子图)。 - 验收契约:先定义
goal-benchmark/goal-test-data/goal-test-script三种产物的统一格式并建执行器,再动引擎(R-15.6)。 - 规划闭环:
workgraph-planningagent + 用户→公司的任务入口,让「一句自然语言 → 一张可执行的图 → 跑完」端到端成立(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() 是现成的「退回重做」语义。
这正是本文档需要的执行模型:状态是持久化数据,「推进一步」是一次显式、幂等、外部可随时调用的动作,不是占着调用栈不放的循环。手动模式下「下一步」= 用户点一次调一次;自动模式下 = 引擎自己在上一次返回后立刻再调一次。手动和自动共用同一个原语,区别只在谁触发下一次调用。
两处不能照抄的坑:
CompanyDashboard.vue:1019的loadPipelineDetail()请求的是流水线定义,但模板里:class="{'step-current': selectedPipeline.currentStep === idx}"(行 258)引用的currentStep只存在于 run 实例上——这个高亮效果从未生效过。→ 本设计的定义层与运行时层必须是两个各自完整、明确分开的对象(§四.A)。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)
- 概览:
status、attempt、started_at/completed_at/耗时、fail_reason;如果这个节点参与过回退,展示graph_run_loop_records里相关的完整记录(loop_count/verdict/remediation_note)。 - 输入输出:渲染
output_ref指向的文件。「原始产出」和「实际被下游消费时的形态」要能分别展示——大多数正向边上两者相同,但经过回退、拼接了「上一轮 remediation_note」之后就不同了,不能假设总是相同。若该节点读过artifacts/,一并列出读了哪些。 - 运行日志:复用 §3.4 的双轨折叠卡片——
running时走 live 面板流式追加,success/fail后切换成历史视图。展示的是这次 agent 调用内部的对话/工具调用记录。 - 子图:仅当
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 边推进时,无条件执行:
- 备案:按
(run_id, edge_id)查graph_run_loop_records已有记录数 n,loop_count = n + 1,插入一条verdict='registered';同时graph_runs.backward_count += 1。 - 双层硬顶检查:
loop_count > 3(单边)或backward_count > 5(run 级总数)→ 不再调用任何 LLM,直接改verdict='force_terminated',源节点blocked,链路收敛,等人工介入。这一条是纯整数比较,不依赖 agent 调用——保证熔断不会被 LLM 的自由发挥绕过。 - 回退:两个计数都未撞顶时把
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
- 手写一份
goal-benchmark+goal-test-data+goal-test-script,执行器能对一个被测产物跑出明确的通过/不通过判决,判决落库可查。
阶段 A
- 一张只有正向边、3-4 节点的图:手动模式连续点「下一步」逐节点推进到
completed,每次点击只推进一个节点(不因为下游 ready 了就自动继续)。 - 同一张图切自动模式点「启动」:不再需要任何人工点击,自动跑到
completed。 - 自动模式运行中点「暂停」:当前
running节点跑完后run_status → paused,不再自动调度;此时点「下一步」能手动单步;点「启动」能恢复自动。 - 点「停止」:所有
pending/ready节点变skipped,run_status → stopped。若 T9 确认取消可用,正在running的节点被中断且状态可区分于正常fail。 - 一张 org graph(
graph_kind='org')用同一套端点跑通上述 2-5,代码路径与 work graph 完全一致——这是 R-15.4 引擎泛化的核心验收点。 - 一个
subgraph节点执行时正确起子 run、child_run_id回填、子 run 收敛后父节点拿到正确的 success/fail。
阶段 B
- 构造一个总是失败的节点,其
fail边是指回上游的backward边:第 1-3 次回退正常触发(graph_run_loop_records各一行),第 4 次不再调用任何 agent、直接force_terminated,图收敛到blocked。 - 一个节点有两条
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三个值,并据此在父层正确选边。 - root run 预算扣完:整棵 run 树挂起,不是某一层单独失败。
- 对 root run 点「暂停」:正在跑的子 run、孙 run 全部在下一个节点边界停下。
- 对一个
blocked节点点「重试」:节点回ready并能继续推进,不需要重建整张图;下游contract_hash未变的节点保持原状不重跑。
阶段 C
- 画布:回退边渲染为虚线曲线且显示
N/3徽标,随 D.2.1 推进数字正确递增。 - 「运行日志」tab:
running时实时追加,success/fail后切历史视图,内容不丢。 subgraph节点的「子图」tab 点进去是完整可交互(能点「下一步」)的嵌套画布,面包屑能逐层返回。- 左栏点一个从未跑过 work graph 的 org node:中栏空态提示,不报错。
阶段 D
- 对一家 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
- 归因能精确到哪一层,尚未定案(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 层;坏处是多一跳。 - 允许跨层直接寻址目标节点:更快,但破坏封装,且控制台上「暂停 / 单步」作用于哪一层会变得含糊。
- (倾向)保持层级封装:org 层只退到 org node,
validator-reflection的命名尚未定案(R-16 遗留)。按 27-NAMING §三 现行规则(work graph 节点 ={父 org 节点职能}-{职能}),它作为org-validator的 work graph 节点应为validator-reflection,与原话一致。但它做的是归因不是判定,是否改叫validator-triager(对齐 DevLoop 的 BugTriager)待定。fail_reason的取值域不由引擎约束(§四.D.2.2)——引擎只做字符串匹配,取值由图的规划者和 validator 自行约定。好处是不把 DevLoop 的四分类硬编码进通用层;风险是归因产出一个图上没有对应边的取值。缓解已定案:写入前校验新增第五项fail-fallback-edge(§三.7),强制每个有fail出边的节点留一条兜底边。org_graph_nodes.id是整数、work_graph_nodes.id是文本,graph_run_nodes.def_node_id只能取 TEXT 且无法建外键(§四.A.2 的注)。引用完整性靠服务层保证。- 回退边曲线路由是真实的手写前端工程量(§四.B.2)。没引入图形库符合仓库一贯风格,但这块工时不能按「拿组件库拼一下」估。若实现中发现多条回退边交叉的边界情况成本远超预期,值得重新评估引入 dagre 的纯布局计算部分(不要它的渲染层)——本文档不预设结论。
【已关闭,2026-08-16 T9 逐行核实】结论:硬取消做不到,「停止」定案为软停止。RunRegistry/ProcessGuard的取消调用链没有 100% 核实(§3.6)ProcessGuard在生产代码里从未被实例化(只有测试new它),RunRegistry.add()从未被调用(注册表恒为空),两者之间也不存在引用关系;唯一能杀子进程的ClaudeCliProtocol.disconnect()→SessionPool.killActive()→AgentManager.killCurrentProcess()这条链同样零调用方,且粒度是会话而非 runId。完整证据与 file:line 见 §四.C「『停止』是软停止,不是硬取消」。残留风险已从「能不能取消」转为产品预期管理:用户点停止后正在跑的节点仍会跑完(最长一个节点的时长),UI 必须明示,否则会被当成 bug 报上来。- v1 的「一家公司同时只有一个 active root run」是一条真实的产品限制,不只是技术妥协。它由
CONVENTIONS.md§12 的不变量和 SessionPool key 复用共同决定(§一非目标)。如果用户很快就要「一家公司并行接多个任务」,实例隔离要提前排期。 workgraph-planning的规划质量没有硬校验。§三.7 只保证图结构合法,不保证它适合这个任务。缓解手段与 P2 同款:规划记录落盘供人工复核,发现不合理走增量修正。- 阶段 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 的影响
原来那条待办(「保证两套状态机语义不冲突」)应当升级为一个更具体、收益也更明确的目标:把四段式改写成引擎上的一张标准图模板。这样做同时解决三件事:
- 消除「引擎层的图」和「agent 内部的四段式」两套并行状态机;
meta-*技能的挂载正好对应 work graph 节点的system_agent_id引用,顺手把system/skills/缺失这个洞补上——现在这批技能没有读取方,改造后引擎就是读取方;- 阶段顺序校验由引擎的边定义天然提供,不需要另写。
仍列为 P3 之后的待办,不进本阶段范围。但 §五 的 T11(workgraph-planning)在生成图时应当避免与四段式语义打架——具体是别让 work graph 节点内部再套一层四段式流转,否则同一次执行会有两层 Context Flush 互相清对方的上下文。