27-p3b-real-run-runway.md 9.06 KB

27-P3B. 真实运行前置 —— 从 mock 走到真 Claude CLI

所属: 27 Graph Agent 架构 的 P3 收尾。P3 主体见 27-P3/P4。 版本: v0.1 日期: 2026-08-16 起因: 27-REQ R-18(招聘归 workgraph-planning;停用 mock 改真 CLI) 前置: P3 主体已实现并提交(c3abf4a 起七轮),测试 719/719 全绿


一、为什么需要这份文档

P3 主体七轮做下来,引擎编排层是扎实的(状态机、双层熔断、三层级联、跨层回退,都在脚本 executor 下逐环验过),但两件事一直没解决:

  1. 验证一直建立在 mock 之上。 ClaudeCliProtocol._sendMockPrompt 完全不读提示词,只按 agent 名回放 fixture。所以前六轮报的「端到端生产成立」,验的是引擎编排,不是 agent 链路。第七轮换真 CLI 后,链路在第一个 work 节点就断。
  2. agent 供给链没有执行者。 work graph 节点引用的本体,没有任何流程会把它雇进公司。

本文档收敛这两件事,目标是:能在控制台上点一下,让真实 Claude CLI 跑完一个最小任务,且不写坏宿主仓库、验收不假放行。


二、目标与非目标

目标

  1. workgraph-planning 规划完图后自己雇齐引用到的本体(R-18.2 方案 a)。
  2. 真实 Claude CLI 能跑完一个单 org node 的最小任务,产出落在分配好的项目根内。
  3. 验收链路不会「假放行」。
  4. 界面上有入口触发 orggraph-planning 真跑(R-18.1),不再靠脚本代劳。

非目标

  • 不做 fan-out 并行(沿用 P3 §一:卡在实例隔离)。
  • 不做 L4。
  • 不追求一次跑通复杂任务:第一批的验收标准是「单 org node 的最小图能真跑完」,不是「开发型公司三节点全流程」。前七轮的教训是没跑起来之前的判断经常是错的,先拿到真实结果再排后面。

三、现状核实(决定工作量的证据)

# 事实 证据
1 seedTemplates() 没有任何运行时调用方 只有测试与手动的 scripts/graph-seed.js 引用它
2 因此 system/templates/ 新增的本体进不了 system_agents 表 而 work_graph_nodes.system_agent_id 是指向该表的外键
3 库里有 10 条悬空 company_hired 行,legacy_path 指向已删目录 含 validator-triager / prd-planning / sdd-planning / brd-planning / benchmark-validator / testdata-validator / workgraph-planning / org-validator
4 seedTemplates 遇到 id 已被别的 source_kind 占用会 skip 所以第 3 条那些永远变不回 template
5 后果链:lookupSharedAgentMd 恒 null → hire 静默退回全量拷贝 模板改动对已雇公司不生效
6 resolveAgentName 只查目录存不存在,不做按需 hire 同文件的 resolvePlanningAgentName 对 workgraph-planning 倒是做了
7 path-resolver.allocateProjectRoot 已实现,sandbox 模式给 data/companies/{cid}/projects/{pid},另有 isSensitivePath 黑名单 图执行侧没有调用它
8 图执行侧的 agent_call 节点没有产出位置也没有沙箱 真 CLI 实测已往宿主仓库写入 server/routes/echo.js 等三处(已复原)
9 FAILING_VERDICTS = {attributed, inconclusive},不含 "fail" 而 benchmark-validator / testdata-validator 的 Step 表教 agent 写 verdict: "fail"
10 system/skills/ 目录不存在 base agent 的 Hot Swap 是 existsSync 守卫下的静默空转

四、工作项

第一批 · 真跑的最小前提

做完这四件就能真跑,且不会写坏仓库、验收不会假放行。

# 内容 文件 量
W1 清 10 条悬空 company_hired 行;把 seedTemplates() 接进服务启动流程(或让 hire 顺手 upsert system_agents)。这是 W5/W6 的前置——不修,agent 雇完人提交图照样外键挂 server/services/graph-seed-service.js、server/index.js 小
W2 每个 run 分配项目根,写进节点提示词。复用 path-resolver.allocateProjectRoot(sandbox 模式),不新造 server/services/graph-engine.js 小
W3 产出目录边界守卫:节点写入限制在自己的产物目录 + 项目根内,越界拒绝并留痕。可复用 isSensitivePath server/services/graph-engine.js 小
W4 修 fail-open 的验收 bug:benchmark-validator / testdata-validator 的 Step 表与引擎 FAILING_VERDICTS 对齐。planner-validator/agent.md 已有一段红字警告这一点,另两份 Step 表恰恰在教 agent 犯它 system/templates/{benchmark,testdata}-validator/agent.md 小改动,性质严重

W4 的失效方向是放行不是拦截:契约非法的产物会被当合格通过。真跑之前不修,验收形同虚设。

第二批 · 招聘走方案 a

# 内容 文件 量
W5 workgraph-planning 模板改语义:撤掉「你不招人也不辞人」,加招聘步骤,tools.md 给 company hire 用法 system/templates/workgraph-planning/** 小
W6 写死顺序:先雇、再提交图(反了必外键挂);雇失败的重试与降级 同上 小
W7 work 层招聘不得污染 org graph:hire() 现在会把任何被雇 agent upsert 成一行 org_graph_nodes。方案 a 下每次任务规划都雇人,org graph 会被越塞越满(界面走查已实际撞到)。让这类招聘不写 org 节点,或写了打标区分 server/services/company-service.js、server/services/graph-service.js 中
W8 控制台加「重新规划组织」按钮,调 POST /:companyId/org-graph/replan(R-18.1)。该端点已实现,全仓库无前端调用方 web/src/views/GraphConsole.vue 或 CompanyDashboard.vue 小

第三批 · 让结果可信

# 内容 量
W9 失败上下文进提示词:validator-triager 的 agent.md 承诺「给你哪个节点失败、第几 attempt、失败摘要」,全仓库没有代码提供 中
W10 跨层地址要 target_org_node + target_node 两半都写才合法;模板要写清(只写一半会静默退化成整张图重跑) 小
W11 system/skills/meta-* 缺失导致 base agent 的 Hot Swap 静默空转,「EXECUTE 阶段才拿破坏性权限」只剩话术。补技能包,或如实降级并改文档 中

五、成本预估

一次 3 个 org node 的任务:3 次规划调用 + 每张 work graph 3-4 个节点,不含回退约 15 次调用,带一两次回退到 20-25 次。按 plan-cost-concurrency.md 的实测量级推算,单次 $3-8、墙钟 15-40 分钟。

调试期一律用单 org node 的最小图(省约三分之二)。第一批的验收就按这个规模定。


六、验收标准

第一批

  1. 服务启动后 system_agents 与 system/templates/ 一致,无悬空 company_hired 行;新加一个模板目录、重启服务,它自动出现在表里。
  2. 起一个真 CLI 的 run,节点产出全部落在 data/companies/{cid}/projects/{pid}/ 内;git status 在宿主仓库无任何新增/修改。
  3. 故意让节点往产物目录外写,被守卫拒绝并在 timeline 留痕。
  4. 造一份非法契约跑 benchmark-validator:判决为失败且引擎按失败处理(不是 success)。

第二批

  1. 新建公司 → 界面点「重新规划组织」→ orggraph-planning 真跑 → org graph 出现,且它雇的三个 org 节点都在。
  2. 下达任务 → workgraph-planning 真跑 → 它引用的本体被自己雇进公司 → 图提交成功(不再外键挂)。
  3. 上条跑完后,控制台左栏 org graph 仍然只有 org 节点,没有混进 prd-planning 这类 work 层本体。

第三批

  1. validator-triager 的提示词里能看到「哪个节点失败、第几 attempt、失败摘要」。
  2. 一次真实的跨层回退:target_org_node + target_node 两半齐全,只有被点名的节点被重置。

七、风险

  1. 成本不可控:真 CLI 下一次跑错方向就是几美元 + 半小时。缓解:调试期强制单 org node;任务级预算的 total_agent_calls 压到 15 以内先跑通。
  2. W7 的语义决定要谨慎:hire() 写 org_graph_nodes 是 P2 §4.2 定的(「hire 成功后写一行,幂等」),当时的前提是只有 org 节点会被雇。方案 a 打破了这个前提。改动要确认不破 P2 已有的 24 条测试。
  3. 真 CLI 会暴露一批模板质量问题:前七轮所有 agent 模板都只在 mock 下「跑过」,而 mock 不读提示词——这些提示词实际上从未被任何模型读过。第一次真跑大概率会集中暴露表述矛盾(W4 就是一例,benchmark-validator 的 Step 表与自己的产出格式表就互相打架)。
  4. 不要在没有 W2/W3 的情况下跑真 CLI:已经发生过一次 agent 写入宿主仓库。