diff --git a/docs/README.md b/docs/README.md index 348b887..4affa6e 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) | 📝 **复盘 + 改进方案,提案 A 已实施**。承接 31/32/33/34 号的复盘结论:任务结果差主要是架构问题(完整性闸门 `missingBodyDefinition` 只在招聘时查、图执行侧完全没有第二道防线——新发现)+ 一个具体的招聘装配可靠性 bug,不是 agent 能力问题。提案 A(把完整性闸门接进图执行前置检查)已落地——本体不完整时判 `fail_reason=body_not_ready`,不扣预算;提案 B(控制台展示验收证据可见性)待做;提案 C/D(标准化视觉验收工具、引擎级证据闸门)待讨论优先级 | +| [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 能力问题。提案 A:本体不完整时图执行前置判 `fail_reason=body_not_ready`,不扣预算。提案 D:`goal-contract.js` 的 `evidence_hint` 命中浏览器类关键词的维度必须有证据支撑,否则判不过。提案 C:新增 `scripts/visual-acceptance-check.mjs` 复用检查工具。提案 B:控制台「验收证据」小节展示每个维度有没有证据支撑 | | [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 76e2b54..bf4cf8e 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 @@ -9,8 +9,9 @@ > 与调研——那几份记的是"发现了什么",这份记的是"复盘下来该怎么办"。 > **触发**:用户问"任务结果这么差,是 agent 能力问题、架构问题、还是 graph > workflow 缺陷",本文档是那次复盘的书面结论 + 据此提出的改进方案。 -> **状态**:§二提案 A **已实施**(commit `bab675c`,全量单测 1004/1004 通过, -> 细节见 §三实现记录);提案 B/C/D 仍是提案,未动手。 +> **状态**:**四条提案全部已实施**。提案 A(commit `bab675c`);提案 B/C/D +> 一起做完(commit `fadb6fa`,全量单测 1012/1012 通过)。细节见各提案小节下方 +> 的"实现记录"。 --- @@ -141,6 +142,16 @@ 且直接回应 34 号文档 §5.3 那条"三个任务验证严谨度天差地别、界面上完全看不出来" 的具体抱怨。 +**实现记录(2026-08-22,commit `fadb6fa`)**:没有另做一套"有没有测试脚本"的 +启发式判断——直接读提案 D 已经算好的结论(`goal-contract.js` 判决里的 +`dimensions[].evidence_required`/`.ok`),比自己猜一遍"这份产出看起来严不严谨" +更准。`GET /api/graph-runs/:id` 新增 `benchmarkVerdicts`(只读 +`listVerdicts`/`readVerdict` 落盘的判决,不重新计算,读失败就跳过那一条,不拖垮 +整个响应);`NodeDetailPanel.vue` 概览 tab 新增"验收证据"小节,逐维度显示分数 + +是否有证据支撑,缺证据的标 ⚠️。只在这个节点真的有 benchmark 判决时才出现(同「输入 +输出」tab 的"不猜、不留空标题"口径)。已用 Chrome 实测过:点开 +`org-coder-validator` 节点,六个维度分数与 ⚠️ 标记正确渲染。 + --- ### 第二档:更大的设计决策,建议先讨论优先级再动手 @@ -163,6 +174,16 @@ 更新、要不要影响现有已经在跑的任务。**这是一个需要先讨论范围的设计任务, 不建议直接动手**。 +**实现记录(2026-08-22,commit `fadb6fa`)**:接口定成了四个独立子命令 +(`overflow`/`style`/`console`/`contrast`),各自吐一行 JSON 到 stdout,不做成 +"一次跑全部维度"的大而全脚本——`goal-benchmark.json` 的维度因任务而异,硬编码 +成一份不可复用。只更新了 `benchmark-validator/agent.md`(真正逐维度打分、写 +`evidence` 的那个角色),没有动 `coder`/`unit-tester`(当初以为的目标,后来发现 +写分数和证据的其实是另一个角色,见 §五.2 的角色梳理)。没有影响任何现有已经在跑 +的任务——纯新增文件 + 一段引用说明,agent.md 里其余内容一字未改。配一份不进 +`vitest` 快速循环的独立冒烟脚本(`visual-acceptance-check.smoke.mjs`,起真实 +Chromium 断言四个子命令,几秒量级)。 + #### 提案 D:给"要求真实检查"的验收维度加引擎级证据闸门 **问题**:`goal-benchmark.json` 的 `evidence_hint` 目前只是**写给 agent 看的 @@ -180,13 +201,33 @@ 细节,**建议留到提案 A/B 落地、有更多真实样本之后再决定要不要做,不是这次的 优先级**。 +**实现记录(2026-08-22,commit `fadb6fa`)**:关键词用了固定正则 +(`浏览器|viewport|视口|开发者工具|devtools|console|network|截图|screenshot`, +不分大小写);没有证据时选的是**拦截**(该维度直接判不过),不是"降级为 +inconclusive 但仍算过"——因为整个 §一复盘的教训就是"光有分数不该被当真", +选降级等于还是采信了那个分数,只是换了个说法。 + +**中途发现的一处设计对齐**:`goal-benchmark.json` 的 schema 完全不用改——`evidence` +不是新字段,`benchmark-validator/agent.md` 早就在教 agent 把 `dimensions[].evidence` +写进判词文件(`attempt-.json`),只是这份数据从来没被 `goal-contract.js run` +读过(它只读 `--target` 指向的 `attempt-.scores.json`,只有分数)。所以没有 +发明新格式,而是让 `runBenchmark` 多看一眼同目录的姊妹判词文件—— +`readSiblingEvidence()`:`attempt-.scores.json` → 同目录 `attempt-.json` → +取 `dimensions[].evidence`。`--target` 文件里如果也显式给了 `evidence.`, +优先用那份。6 条新单测覆盖:命中关键词但无证据判不过 / 给了证据后正常通过 / +普通维度不受约束 / 空字符串按没给处理 / 姊妹文件里的证据能读到 / 姊妹文件缺失 +不拖垮打分。 + --- -## 三、建议的推进顺序(供讨论,非最终决定) +## 三、推进顺序(原提案,已按此顺序全部做完) 1. **提案 A**(执行侧完整性闸门)——最推荐现在就做,闭环 §1.3 那个新发现的架构 - 缺口,改动小、可测、影响明确。 -2. **提案 B**(控制台证据可见性)——可以跟 A 一起做,纯 UI,风险低。 -3. **提案 C / D**——不建议现在动手,先攒几个更多真实任务的样本(比如提案 A/B - 落地后再跑几次真实回归),再决定要不要投入更大的设计成本,避免在样本量只有 - "三个任务"的情况下就把标准定死。 + 缺口,改动小、可测、影响明确。✅ 已实施(commit `bab675c`) +2. **提案 B**(控制台证据可见性)——可以跟 A 一起做,纯 UI,风险低。✅ 已实施 +3. **提案 C / D**——原计划"先攒几个更多真实任务的样本再决定要不要做",用户直接 + 要求一起做完,所以没有等到攒够样本——两条都已实施(commit `fadb6fa`), + 实现记录见各自小节。样本量不足这条风险仍然存在:目前只有一次真实回归验证过 + 这套证据闸门,`evidence_hint` 关键词表是不是覆盖了所有该拦的场景、拦下来的 + 维度会不会引发新一轮无意义回退,都还没有大量真实任务的数据支撑,留意后续 + 真实使用中的反馈。