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 下逐环验过),但两件事一直没解决:
- 验证一直建立在 mock 之上。
ClaudeCliProtocol._sendMockPrompt完全不读提示词,只按 agent 名回放 fixture。所以前六轮报的「端到端生产成立」,验的是引擎编排,不是 agent 链路。第七轮换真 CLI 后,链路在第一个 work 节点就断。 - agent 供给链没有执行者。 work graph 节点引用的本体,没有任何流程会把它雇进公司。
本文档收敛这两件事,目标是:能在控制台上点一下,让真实 Claude CLI 跑完一个最小任务,且不写坏宿主仓库、验收不假放行。
二、目标与非目标
目标
workgraph-planning规划完图后自己雇齐引用到的本体(R-18.2 方案 a)。- 真实 Claude CLI 能跑完一个单 org node 的最小任务,产出落在分配好的项目根内。
- 验收链路不会「假放行」。
- 界面上有入口触发
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 的最小图(省约三分之二)。第一批的验收就按这个规模定。
六、验收标准
第一批
- 服务启动后
system_agents与system/templates/一致,无悬空company_hired行;新加一个模板目录、重启服务,它自动出现在表里。 - 起一个真 CLI 的 run,节点产出全部落在
data/companies/{cid}/projects/{pid}/内;git status在宿主仓库无任何新增/修改。 - 故意让节点往产物目录外写,被守卫拒绝并在 timeline 留痕。
- 造一份非法契约跑
benchmark-validator:判决为失败且引擎按失败处理(不是 success)。
第二批
- 新建公司 → 界面点「重新规划组织」→
orggraph-planning真跑 → org graph 出现,且它雇的三个 org 节点都在。 - 下达任务 →
workgraph-planning真跑 → 它引用的本体被自己雇进公司 → 图提交成功(不再外键挂)。 - 上条跑完后,控制台左栏 org graph 仍然只有 org 节点,没有混进
prd-planning这类 work 层本体。
第三批
validator-triager的提示词里能看到「哪个节点失败、第几 attempt、失败摘要」。- 一次真实的跨层回退:
target_org_node+target_node两半齐全,只有被点名的节点被重置。
七、风险
- 成本不可控:真 CLI 下一次跑错方向就是几美元 + 半小时。缓解:调试期强制单 org node;任务级预算的
total_agent_calls压到 15 以内先跑通。 - W7 的语义决定要谨慎:
hire()写org_graph_nodes是 P2 §4.2 定的(「hire 成功后写一行,幂等」),当时的前提是只有 org 节点会被雇。方案 a 打破了这个前提。改动要确认不破 P2 已有的 24 条测试。 - 真 CLI 会暴露一批模板质量问题:前七轮所有 agent 模板都只在 mock 下「跑过」,而 mock 不读提示词——这些提示词实际上从未被任何模型读过。第一次真跑大概率会集中暴露表述矛盾(W4 就是一例,
benchmark-validator的 Step 表与自己的产出格式表就互相打架)。 - 不要在没有 W2/W3 的情况下跑真 CLI:已经发生过一次 agent 写入宿主仓库。