# 27-P3B. 真实运行前置 —— 从 mock 走到真 Claude CLI > **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 P3 收尾。P3 主体见 [27-P3/P4](./27-p3-p4-work-graph-console.md)。 > **版本**: v0.1 > **日期**: 2026-08-16 > **起因**: [27-REQ](./27-requirement.md) 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)。 **第二批** 5. 新建公司 → 界面点「重新规划组织」→ `orggraph-planning` 真跑 → org graph 出现,且它雇的三个 org 节点都在。 6. 下达任务 → `workgraph-planning` 真跑 → 它引用的本体被自己雇进公司 → 图提交成功(不再外键挂)。 7. 上条跑完后,控制台左栏 org graph **仍然只有 org 节点**,没有混进 `prd-planning` 这类 work 层本体。 **第三批** 8. `validator-triager` 的提示词里能看到「哪个节点失败、第几 attempt、失败摘要」。 9. 一次真实的跨层回退:`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 写入宿主仓库。