docs(35): 复盘结论 + 改进方案提案，未拍板

用户问"任务结果差是 agent 能力、架构、还是 graph workflow 问题"，这份文档是书面复盘：按发生顺序分四类——图/模板设计缺陷（31/33 号，已修）、招聘装配可靠性 bug（32 号已知问题的新样本）、一个复盘时新发现的架构缺口（missingBodyDefinition 完整性闸门只在招聘路径上调用，graph-engine.js 的执行核心路径 advanceOne 一次都没查，本体不完整时没有第二道防线，静默拿空提示词跑真实 LLM）、agent 能力（不是问题，两次订正过"没工具做不到"的误判，且有正面即兴发挥的例子）。结论：主要是架构问题 + 一个具体可靠性 bug，不是模型能力问题。提出两档改进方案供讨论：低成本（建议直接做）——把完整性闸门接进图执行前置检查（提案 A）、控制台展示验收证据可见性（提案 B，纯 UI 不改行为）大改动（建议先讨论优先级）——标准化视觉验收工具（提案 C）、引擎级证据闸门（提案 D） Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs(35): 复盘结论 + 改进方案提案，未拍板
用户问"任务结果差是 agent 能力、架构、还是 graph workflow 问题"，这份文档是书面复盘：按发生顺序分四类——图/模板设计缺陷（31/33 号，已修）、招聘装配可靠性 bug（32 号已知问题的新样本）、一个复盘时新发现的架构缺口（missingBodyDefinition 完整性闸门只在招聘路径上调用，graph-engine.js 的执行核心路径 advanceOne 一次都没查，本体不完整时没有第二道防线，静默拿空提示词跑真实 LLM）、agent 能力（不是问题，两次订正过"没工具做不到"的误判，且有正面即兴发挥的例子）。结论：主要是架构问题 + 一个具体可靠性 bug，不是模型能力问题。提出两档改进方案供讨论：低成本（建议直接做）——把完整性闸门接进图执行前置检查（提案 A）、控制台展示验收证据可见性（提案 B，纯 UI 不改行为）大改动（建议先讨论优先级）——标准化视觉验收工具（提案 C）、引擎级证据闸门（提案 D） Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
yibo
1 parent 364cc3dc
Showing 2 changed files with 169 additions and 0 deletions
docs/README.md
docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md
@@ -49,6 +49,7 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d
 | [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） |
 | [30-task-delegation-reliability-gaps.md](./todo/system-design/30-task-delegation-reliability-gaps.md) | **任务委派可靠性现状**— 📝 调研记录，非设计方案。DevLoop `runUnit`、Company 招聘装配、Graph 执行三条链路核对结论一致：都是「失败预算耗尽 → 停等人工」，没有「卡住了主动通知人」这一层；DevLoop 当前还默认走 mock，真实 CLI 成功率无实证数据 |
 | [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 次，零人工介入），修复确认生效 |
+| [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 能力问题。提出两档改进：低成本（把完整性闸门接进图执行前置检查、控制台展示验收证据可见性）建议直接做；大改动（标准化视觉验收工具、引擎级证据闸门）建议先讨论优先级 |
 | [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) 那类"装配没填充完"的真实样本，不是平台工具限制 |
 | [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 号文档的真实回归验证过程中，与兜底边问题无关 |
+# 35-validation-rigor-and-body-readiness-proposal. 复盘结论 + 改进方案（待讨论）
+
+> **日期**: 2026-08-22
+> **性质**: 复盘 + 改进方案提案，**未拍板，等讨论**。承接
+> [31](./31-work-graph-fail-fallback-coverage.md) /
+> [32](./32-hire-body-fill-reliability.md) /
+> [33](./33-needs-gate-role-filter-bug.md) /
+> [34](./34-validator-scored-without-real-deliverable.md) 四份文档的真实回归验证
+> 与调研——那几份记的是"发现了什么"，这份记的是"复盘下来该怎么办"。
+> **触发**：用户问"任务结果这么差，是 agent 能力问题、架构问题、还是 graph
+> workflow 缺陷"，本文档是那次复盘的书面结论 + 据此提出的改进方案。
+
+---
+
+## 一、复盘结论：四类原因，权重不均
+
+用一条真实回归任务（`T-mt2r6fz0-125b`，"做一个 apple.com 风格的 lemonboss 官网"）
+撞见的问题，按发生顺序分类：
+
+### 1.1 图/模板设计缺陷（已修复）—— 31、33 号文档
+
+- `org-planner-sdd` 没有兜底边，自判失败即卡死到人工重试（31 号）。
+- `test→validator` 边声明的 `produces:["log"]` 是一个 test 类节点永远写不出来的
+  kind，导致 `missing_required_input` 假阳性、永久熔断（33 号）。
+
+这两条是**真实的图/模板设计缺陷**，不是 agent 判断失误，也不是"能力"问题——
+图本身的结构不完整。**权重：中**（真实存在，但已经修好，且这类问题一旦发现，
+定位和修法都很直接）。
+
+### 1.2 招聘装配可靠性 bug（已知，这次是新样本）—— 32 号文档
+
+`unit-tester` 本体的 `agent.md` 全程是空白的 `_base` 骨架（带
+`LEMONBOSS_BASE_SKELETON` 哨兵标记），隔壁 `coder` 却正常填充过。32 号文档已经
+分析过这类异步装配的可靠性问题并实施了方案 B（`6a18379`），但这次撞见的样本
+发生在修复提交**之前** 1 小时，且没有专门验证过新机制是否已经完全堵住这个口子。
+**权重：这次具体检查偏弱的最直接原因**——`unit-tester` 在没有任何角色指导的
+情况下，只能靠自己对"该怎么测试网页"的通用理解去写检查脚本，写出来的东西天然
+比有明确方法论指导的 `org-coder`/`coder-validator` 弱。
+
+### 1.3 一个新发现的、更深的架构缺口：完整性闸门只在招聘时查，执行时不查
+
+复盘时确认过一件事（`server/services/graph-engine.js` 全文搜索）：
+`missingBodyDefinition()`（检测本体是否还带 `_base` 哨兵/空白）只在
+**招聘/建公司/dream 沉淀**这几条路径上被调用（`graph-service.js` /
+`graph-seed-service.js` / `company-service.js` / `dream-service.js`），
+**图执行的核心路径（`advanceOne`/`defaultAgentExecutor`）一次都没有调用它**。
+
+也就是说：即使 32 号文档的修复完全生效、招聘那一刻永远不会留下半成品——只要一个
+本体因为**任何其它原因**（手工改坏、迁移遗留、装配虽然完成了但内容本身依然是
+空骨架而系统判断不出来……）在 `system_agents` 目录里长期处于未填充状态，
+**图执行侧完全没有第二道防线**，会原样把这份空白提示词交给真实 Claude CLI 去跑，
+静默产出一份"看起来是回复、其实没有任何角色指导"的结果——这正是这次
+`unit-tester` 发生的事。**这是本次复盘里唯一一条原来没人查过、独立于 32 号文档
+既有分析的新架构缺口**。
+
+### 1.4 不是 agent 能力问题——两次订正过这一点
+
+- 最初以为"没有浏览器工具，物理上做不到视觉检查"，后来发现同一批工具权限下
+  隔壁一条任务真的跑出了 Playwright 测试（见 34 号文档 §5.3 的订正）——**能力
+  和权限都够**，缺的是指导。
+- `unit-tester` 在零指导的情况下，还是主动写出了一份能真实解析 CSS `clamp()`
+  算出字号比例、能识别锚点跳转反模式的静态断言脚本——这是**相当不错的即兴发挥**，
+  不是能力不足的表现。
+
+**结论：这次任务结果差，主要是架构 + 一个具体的可靠性 bug，不是模型能力问题。**
+按影响力排序：①执行侧没有完整性闸门（新发现，架构缺口）> ②招聘装配可靠性 bug
+（已知，这次撞上了修复前的窗口）> ③图模板设计缺陷（已修）> ④agent 能力（不是
+问题，甚至有正面例子）。
+
+---
+
+## 二、改进方案（分两档，供讨论）
+
+### 第一档：低成本、高置信度，建议直接做
+
+#### 提案 A：把 `missingBodyDefinition()` 接进图执行的派发前置检查
+
+**做什么**：`advanceOne`（或它调用 `defaultAgentExecutor` 之前的那一步）在真正
+派发一次 agent 调用前，对这个节点的 `systemAgentId` 跑一次
+`agentLocator.missingBodyDefinition(systemAgentId)`；非空就不派发真实调用，
+直接按新 fail_reason（复用已有语义相近的命名，比如 `body_not_ready`，与招聘时
+挡重复招聘的判词同名同义）让节点走 fail 流程——**跟 31 号文档修的兜底边机制是
+同一条已有的选边逻辑**，不需要发明新的路由方式，只需要在这一个检查点新增一次
+判断和一个新的 fail_reason 取值。
+
+**为什么现在做**：
+- 判据函数已经存在、已经测过、语义已经很清楚（`agent-locator.test.js` 覆盖过），
+  不是从零设计。
+- 改动面很小：一个检查点、一个新 fail_reason、复用现成的选边/兜底/熔断机制。
+  跟 31 号文档同一类"结构性、可验证、影响面可控"的修法。
+- 直接堵住了 §1.3 说的"唯一没有第二道防线"的洞——不管以后是招聘装配失败、
+  手工改坏、还是任何其它原因导致本体不完整，图执行到这一步都会被拦下来，
+  而不是静默拿一份空提示词去跑真实 LLM。
+- 有真实的失败样本（`unit-tester`）可以直接改写成回归测试，验证成本低。
+
+**代价 / 需要想清楚的点**：
+- fail_reason 走兜底边意味着这个节点会被打回上游重跑——但重跑到同一个
+  systemAgentId，body 还是没填，会不会陷入无意义的重试循环？需要确认
+  `body_not_ready` 这类 fail_reason 是否应该被排除在正常回退计数（backward_count）
+  之外，还是就该老实算一次退（让 §四.D.2.1 的熔断兜底），倾向于后者——不发明
+  第二套计数规则。
+- 需要决定：检查失败时是"这个节点 blocked 等人工重新触发装配"，还是"引擎自动
+  触发一次装配再重试"（后者更省心但复杂度更高，涉及跟 32 号文档的
+  `agent-body-filler.js` 打通）。**建议第一版先做前者（简单、可控），装配自愈
+  留给后续。**
+
+#### 提案 B：控制台展示"这份验收有没有证据支撑"（纯 UI，不改行为）
+
+**做什么**：在已有的 `TaskFilesPanel`/节点详情面板上，如果 validator 的
+`attempt-*.scores.json`（或对应产出）能关联上一份"真实检查证据"（比如同目录下
+有没有一份 `tests/*.mjs`/`*.check.js` 之类的脚本、或 `attempt-*.json` 里有没有
+`test_run.executed:true` 这类字段），标一个不起眼的小标签——不是要engine 判断
+"验证够不够严谨"（那是提案 D 的范畴，成本高很多），只是**把现在完全不可见的
+差异露出来**，让人在看"已完成"三个字时，能多看一眼"这条完成背后有没有真实证据"。
+
+**为什么可以现在做**：纯前端 + 读现成数据，不改变任何执行行为，风险几乎为零，
+且直接回应 34 号文档 §5.3 那条"三个任务验证严谨度天差地别、界面上完全看不出来"
+的具体抱怨。
+
+---
+
+### 第二档：更大的设计决策，建议先讨论优先级再动手
+
+#### 提案 C：给"视觉/UX 类"任务提供一套标准化、可复用的验收工具
+
+**问题**：`p-bkhylu` 那条任务能做到 Playwright 级验证，纯粹是因为那次的 agent
+会话自己想到了、自己写了 `verify.mjs`。换一次任务、换一次会话，不保证还会有人
+这么做——`unit-tester` 这次就没想到（或者说，没被指导要这么想）。
+
+**候选做法**：在仓库里放一份可复用的验收脚本模板/skill（比如
+`scripts/visual-acceptance-check.mjs`，封装"读 index.html/css/js → 用 Playwright
+量视口/对比度/字号"这类通用检查逻辑），并在 `coder`/`unit-tester`/
+`coder-validator` 这类角色的 `agent.md`（或它们的 `tools.md`）里显式点名："遇到
+`goal-benchmark.json` 里要求视口/对比度/首屏这类视觉维度时，用这份工具，不要
+自己发明"。
+
+**代价**：这不是"填一个空文件"那么简单——要设计这份工具的接口（读哪些文件、
+输出什么形态、怎么接进 `attempt-*.json`）、要决定哪些角色的 `agent.md` 需要
+更新、要不要影响现有已经在跑的任务。**这是一个需要先讨论范围的设计任务，
+不建议直接动手**。
+
+#### 提案 D：给"要求真实检查"的验收维度加引擎级证据闸门
+
+**问题**：`goal-benchmark.json` 的 `evidence_hint` 目前只是**写给 agent 看的
+文本提示**，agent 信不信、照不照做，引擎完全不管——验证严不严谨完全靠自觉。
+
+**候选做法**：给 `evidence_hint` 里出现"打开浏览器/截图/开发者工具"这类关键词
+的维度，要求打分时必须附带一个可核实的 `evidence_ref`（比如指向一份真实脚本的
+`stdout` 日志文件，或类似 `coder-validator` 已经在用的 `test_run.executed:true`
++ `output_excerpt` 那套惯例）——引擎收到一个没有 `evidence_ref` 的高分视觉维度时，
+可以选择"降级为 inconclusive"或至少"打一个显式的 ⚠️ 标记"，而不是原样采信。
+
+**代价**：这个提案影响 `goal-benchmark.json` 的 schema、`goal-contract.js` 的
+判定逻辑、以及所有会产出这类分数的 validator 角色的 `agent.md`——影响面明显
+比提案 A/B 大，且需要先定"哪些关键词触发这道闸门""没有证据时降级还是拦截"这类
+细节，**建议留到提案 A/B 落地、有更多真实样本之后再决定要不要做，不是这次的
+优先级**。
+
+---
+
+## 三、建议的推进顺序（供讨论，非最终决定）
+
+1. **提案 A**（执行侧完整性闸门）——最推荐现在就做，闭环 §1.3 那个新发现的架构
+   缺口，改动小、可测、影响明确。
+2. **提案 B**（控制台证据可见性）——可以跟 A 一起做，纯 UI，风险低。
+3. **提案 C / D**——不建议现在动手，先攒几个更多真实任务的样本（比如提案 A/B
+   落地后再跑几次真实回归），再决定要不要投入更大的设计成本，避免在样本量只有
+   "三个任务"的情况下就把标准定死。