宜博 / lemonboss

Commit 1b6d4355692d4a045c87f8ef02b711acd79363a9

Authored by yibo
1 parent bab675cb

docs(35): 标记提案 A 已实施，记录实现细节与中途踩的坑 

补记 commit bab675c 的实现记录：按"第一版先做前者"落地（blocked 等人工，
装配自愈留后续），以及中途把测试套件炸穿 75 个用例又收窄回来的完整过程——
根因是 missingBodyDefinition 查真实文件系统，测试夹具的假 systemAgentId
天然"缺失"，改法是借用已有的 boundaryGuardApplicable 判据（只在真实执行器
下生效），不是发明新判据。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Inline Side-by-side
Showing 2 changed files with 28 additions and 4 deletions
docs/README.md
  View file @1b6d435
... ... @@ -49,7 +49,7 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d
49 49 | [29-dream-design.md](./todo/system-design/29-dream-design.md) | **dream（经验汇流）**— ✅ 已实现。定时整理所有 agent 在所有公司的记忆，提炼后跨公司沉淀（不泄漏公司信息）。四条取舍已拍板并实现：去敏独立判定、四落点分层写入（经验/`SKILL.md`/`soul.md`/`agent.md`，受管区块+三道闸门）、每日定时（串行+空转保护）、引用真伪自动查、REST+控制台入口（`/api/dream/*`、`/dream`）。`innovator-evolver` 真 CLI 跑通一次。**仍缺的**：「结论对不对」只能人抽查；「套进 org/work graph 来跑」评估后用户选了不做（作用域不匹配，见文内 §5.7） |
50 50 | [30-task-delegation-reliability-gaps.md](./todo/system-design/30-task-delegation-reliability-gaps.md) | **任务委派可靠性现状**— 📝 调研记录，非设计方案。DevLoop `runUnit`、Company 招聘装配、Graph 执行三条链路核对结论一致：都是「失败预算耗尽 → 停等人工」，没有「卡住了主动通知人」这一层；DevLoop 当前还默认走 mock，真实 CLI 成功率无实证数据 |
51 51 | [31-work-graph-fail-fallback-coverage.md](./todo/system-design/31-work-graph-fail-fallback-coverage.md) | work graph 兜底边覆盖不全 — ✅ 已完成（除入口节点外强制兜底边，`planner.json`/`executor-fanout.json` 补 6 条边），978/978 单测通过；2026-08-21 又用真实 LLM 起了一条新任务做端到端回归验证，`org-planner-sdd` 自判失败后自动打回 `org-planner-prd`（3 次，零人工介入），修复确认生效 |
52   -| [35-validation-rigor-and-body-readiness-proposal.md](./todo/system-design/35-validation-rigor-and-body-readiness-proposal.md) | 📝 **复盘 + 改进方案，未拍板**。承接 31/32/33/34 号的复盘结论：任务结果差主要是架构问题（完整性闸门 `missingBodyDefinition` 只在招聘时查、图执行侧完全没有第二道防线——新发现）+ 一个具体的招聘装配可靠性 bug，不是 agent 能力问题。提出两档改进：低成本（把完整性闸门接进图执行前置检查、控制台展示验收证据可见性）建议直接做；大改动（标准化视觉验收工具、引擎级证据闸门）建议先讨论优先级 |
  52 +| [35-validation-rigor-and-body-readiness-proposal.md](./todo/system-design/35-validation-rigor-and-body-readiness-proposal.md) | 📝 **复盘 + 改进方案，提案 A 已实施**。承接 31/32/33/34 号的复盘结论：任务结果差主要是架构问题（完整性闸门 `missingBodyDefinition` 只在招聘时查、图执行侧完全没有第二道防线——新发现）+ 一个具体的招聘装配可靠性 bug，不是 agent 能力问题。提案 A（把完整性闸门接进图执行前置检查）已落地——本体不完整时判 `fail_reason=body_not_ready`，不扣预算；提案 B（控制台展示验收证据可见性）待做；提案 C/D（标准化视觉验收工具、引擎级证据闸门）待讨论优先级 |
53 53 | [34-validator-scored-without-real-deliverable.md](./todo/system-design/34-validator-scored-without-real-deliverable.md) | 📝 **调研记录，checklist 已查完**。最初以为 `org-coder-impl` 从未产出任何 HTML/CSS，后来发现真实网站其实存在于 `graph_files` 索引不覆盖的「项目根」目录（已顺手修：控制台「产物」面板现在会展示项目根）。追加查清 validator 有没有真的做浏览器级检查——中途自我订正一次：不是"没工具做不到"（`bash` 能走到仓库自带的 Playwright，另一条对照任务证明可行），是**没人教它这么做**；抽查另外两个项目根后发现**验证严谨度完全不稳定**（同类任务有的做了真实 Playwright 级验证、有的只做静态正则、有的没验证就被取消），根因很可能是新招聘的 `unit-tester` 本体撞上了 [32 号文档](./todo/system-design/32-hire-body-fill-reliability.md) 那类"装配没填充完"的真实样本，不是平台工具限制 |
54 54 | [33-needs-gate-role-filter-bug.md](./todo/system-design/33-needs-gate-role-filter-bug.md) | ✅ **已修复**。`executor.json`/`executor-fanout.json` 里 `produces:["log"]` 声明了一个 test/integration 类节点永远不会被索引到的 kind，导致 `org-coder-validator` 被 `missing_required_input` 反复误判 blocked；改成 `required:false`（对齐 `validator.json` 既有写法）。文档记录了一条**走过的弯路**（按 role 过滤 `inboundContracts` 会削弱 T-mt25ecbd 的产出闸门，已撤回），发现于 31 号文档的真实回归验证过程中，与兜底边问题无关 |
55 55  
... ...
docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md
  View file @1b6d435
1   -# 35-validation-rigor-and-body-readiness-proposal. 复盘结论 + 改进方案（待讨论）
  1 +# 35-validation-rigor-and-body-readiness-proposal. 复盘结论 + 改进方案
2 2  
3   -> **日期**: 2026-08-22
4   -> **性质**: 复盘 + 改进方案提案，**未拍板，等讨论**。承接
  3 +> **日期**: 2026-08-22（复盘）/ 2026-08-22（提案 A 当天拍板并实施）
  4 +> **性质**: 复盘 + 改进方案提案。承接
5 5 > [31](./31-work-graph-fail-fallback-coverage.md) /
6 6 > [32](./32-hire-body-fill-reliability.md) /
7 7 > [33](./33-needs-gate-role-filter-bug.md) /
... ... @@ -9,6 +9,8 @@
9 9 > 与调研——那几份记的是"发现了什么"，这份记的是"复盘下来该怎么办"。
10 10 > **触发**：用户问"任务结果这么差，是 agent 能力问题、架构问题、还是 graph
11 11 > workflow 缺陷"，本文档是那次复盘的书面结论 + 据此提出的改进方案。
  12 +> **状态**：§二提案 A **已实施**（commit `bab675c`，全量单测 1004/1004 通过，
  13 +> 细节见 §三实现记录）；提案 B/C/D 仍是提案，未动手。
12 14  
13 15 ---
14 16  
... ... @@ -104,6 +106,28 @@
104 106 `agent-body-filler.js` 打通）。**建议第一版先做前者（简单、可控），装配自愈
105 107 留给后续。**
106 108  
  109 +**实现记录（2026-08-22，commit `bab675c`）**：按"第一版先做前者"落地——
  110 +`runClaimedNode` 派发前查 `agentLocator.missingBodyDefinition(systemAgentId)`，
  111 +非空就直接判 `fail`（`ENGINE_FAIL_REASONS.BODY_NOT_READY = 'body_not_ready'`），
  112 +走正常的选边/兜底/熔断（不豁免 backward_count，理由同上——重试到同一个空骨架
  113 +本体不会自愈，就该老实退熔断等人工，不发明第二套计数规则）；不扣预算、不起
  114 +边界守卫（没有调用真的发生）。
  115 +
  116 +**中途踩的一个坑，记录一下**：第一版没加"只在真实执行器下生效"这条判据，
  117 +直接把检查焊死在派发前——结果全仓库几百个用假 `systemAgentId`（`w-prd`/`impl`
  118 +这类夹具名，不对应 `system/agents/` 下任何真实目录）+ 注入假 `executor` 的单测
  119 +一次性全部判成 `body_not_ready`，`npx vitest run` 从 1004 掉到 75 个用例失败、
  120 +16 个文件。根因是 `missingBodyDefinition` 查的是**真实文件系统**，而这些用例
  121 +的本体压根不存在于真实仓库里——按真实文件系统的判据去判一个不存在的虚构本体，
  122 +"缺失"永远成立，等于把闸门焊死在开着的状态。**改法**：借用已有的
  123 +`boundaryGuardApplicable` 判据（`agentExecutor === defaultAgentExecutor`
  124 +时才生效，测试注入假 executor 时天然跳过），不是发明一条新判据——两处判的是
  125 +同一件事："这次会不会真的起一个 Claude CLI 子进程"，答案会不会真起决定了
  126 +两道闸门（边界守卫 / 本体完整性）该不该查。收窄之后单测回到 1004/1004，
  127 +新增 `graph-engine-body-not-ready.test.js`（4 例，覆盖闸门生效/预算不扣/
  128 +注入假 executor 时不生效/subgraph 节点不受约束）+ 更新
  129 +`graph-engine-fail-reason.test.js` 的取值域断言。
  130 +
107 131 #### 提案 B：控制台展示"这份验收有没有证据支撑"（纯 UI，不改行为）
108 132  
109 133 **做什么**：在已有的 `TaskFilesPanel`/节点详情面板上，如果 validator 的
... ...