diff --git a/docs/README.md b/docs/README.md index 94ad63e..348b887 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,7 +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 能力问题。提出两档改进:低成本(把完整性闸门接进图执行前置检查、控制台展示验收证据可见性)建议直接做;大改动(标准化视觉验收工具、引擎级证据闸门)建议先讨论优先级 | +| [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(标准化视觉验收工具、引擎级证据闸门)待讨论优先级 | | [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 号文档的真实回归验证过程中,与兜底边问题无关 | diff --git a/docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md b/docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md index caa5127..76e2b54 100644 --- a/docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md +++ b/docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md @@ -1,7 +1,7 @@ -# 35-validation-rigor-and-body-readiness-proposal. 复盘结论 + 改进方案(待讨论) +# 35-validation-rigor-and-body-readiness-proposal. 复盘结论 + 改进方案 -> **日期**: 2026-08-22 -> **性质**: 复盘 + 改进方案提案,**未拍板,等讨论**。承接 +> **日期**: 2026-08-22(复盘)/ 2026-08-22(提案 A 当天拍板并实施) +> **性质**: 复盘 + 改进方案提案。承接 > [31](./31-work-graph-fail-fallback-coverage.md) / > [32](./32-hire-body-fill-reliability.md) / > [33](./33-needs-gate-role-filter-bug.md) / @@ -9,6 +9,8 @@ > 与调研——那几份记的是"发现了什么",这份记的是"复盘下来该怎么办"。 > **触发**:用户问"任务结果这么差,是 agent 能力问题、架构问题、还是 graph > workflow 缺陷",本文档是那次复盘的书面结论 + 据此提出的改进方案。 +> **状态**:§二提案 A **已实施**(commit `bab675c`,全量单测 1004/1004 通过, +> 细节见 §三实现记录);提案 B/C/D 仍是提案,未动手。 --- @@ -104,6 +106,28 @@ `agent-body-filler.js` 打通)。**建议第一版先做前者(简单、可控),装配自愈 留给后续。** +**实现记录(2026-08-22,commit `bab675c`)**:按"第一版先做前者"落地—— +`runClaimedNode` 派发前查 `agentLocator.missingBodyDefinition(systemAgentId)`, +非空就直接判 `fail`(`ENGINE_FAIL_REASONS.BODY_NOT_READY = 'body_not_ready'`), +走正常的选边/兜底/熔断(不豁免 backward_count,理由同上——重试到同一个空骨架 +本体不会自愈,就该老实退熔断等人工,不发明第二套计数规则);不扣预算、不起 +边界守卫(没有调用真的发生)。 + +**中途踩的一个坑,记录一下**:第一版没加"只在真实执行器下生效"这条判据, +直接把检查焊死在派发前——结果全仓库几百个用假 `systemAgentId`(`w-prd`/`impl` +这类夹具名,不对应 `system/agents/` 下任何真实目录)+ 注入假 `executor` 的单测 +一次性全部判成 `body_not_ready`,`npx vitest run` 从 1004 掉到 75 个用例失败、 +16 个文件。根因是 `missingBodyDefinition` 查的是**真实文件系统**,而这些用例 +的本体压根不存在于真实仓库里——按真实文件系统的判据去判一个不存在的虚构本体, +"缺失"永远成立,等于把闸门焊死在开着的状态。**改法**:借用已有的 +`boundaryGuardApplicable` 判据(`agentExecutor === defaultAgentExecutor` +时才生效,测试注入假 executor 时天然跳过),不是发明一条新判据——两处判的是 +同一件事:"这次会不会真的起一个 Claude CLI 子进程",答案会不会真起决定了 +两道闸门(边界守卫 / 本体完整性)该不该查。收窄之后单测回到 1004/1004, +新增 `graph-engine-body-not-ready.test.js`(4 例,覆盖闸门生效/预算不扣/ +注入假 executor 时不生效/subgraph 节点不受约束)+ 更新 +`graph-engine-fail-reason.test.js` 的取值域断言。 + #### 提案 B:控制台展示"这份验收有没有证据支撑"(纯 UI,不改行为) **做什么**:在已有的 `TaskFilesPanel`/节点详情面板上,如果 validator 的