diff --git a/docs/README.md b/docs/README.md index e5d8db5..382aec8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -47,7 +47,7 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d | [27-p4-parallel-and-artifacts.md](./todo/system-design/27-p4-parallel-and-artifacts.md) | **P4（回收编号）并行执行与产物索引** — 📝 设计中，未实现。fan-out 真并发 + 同 agent 多实例隔离 + `files.json` 产物索引。三个 Phase，C 可插队 | | [28-followups.md](./todo/system-design/28-followups.md) | 28 号（Agent 注册表统一）的遗留清单 — 主文档已在 `done/`，这份装没做完的：dream 机制（设计见 29 号，已实现，见下）、`source_kind`（✅已删）/`legacy_path`（不能删）删列、三项「已实施未验证」。任务态清理（✅已实现，见下）。§五 是**已立起来的守卫清单**（别重复造，也别删） | | [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 成功率无实证数据 | +| [30-task-delegation-reliability-gaps.md](./todo/system-design/30-task-delegation-reliability-gaps.md) | **任务委派可靠性现状**— 📝 调研记录，非设计方案。DevLoop `runUnit`、Company 招聘装配、Graph 执行三条链路核对结论一致：都是「失败预算耗尽 → 停等人工」，没有「卡住了主动通知人」这一层；DevLoop 当前还默认走 mock，真实 CLI 成功率无实证数据。2026-08-23 追加真实实例：`infra_flake` 原地重跑没有熔断线，真撞上过一次确定性死循环（节点把诊断结论误判成自己的执行结果，反复重跑却从不路由到诊断建议的目标节点），比本文档原先的模式更隐蔽——连"卡住"本身都不容易从节点状态看出来 | | [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 次，零人工介入），修复确认生效 | | [36-prd-agent-methodology-training-feasibility.md](./todo/system-design/36-prd-agent-methodology-training-feasibility.md) | 📝 **调研 + 阶段一/二均已完成**。回应"落地页太单薄是不是该用 Innovator 先训练专业 agent、再用 Dream 持续迭代"——认同方向。**阶段一**：`graph-engine.js` 结算节点后把 `success`/`fail:` 写进本体 `memory.md`（此前只有人类对话路径会写，Dream 天天空转）。**阶段二**：新建独立试验节点 `prd-methodology-trial` 走真实 Hunt→Digest→Evolve，2 轮收敛（96/97 分，真实基线 50 分），三个真实历史项目反推验证方法论有效；过程中连带修复同一个 2026-08-16 改名批次遗留的 5 处 `innovator`→`org-innovator` 死链（后端两处硬编码、前端"重新训练"按钮、`/api/agent/list` 展示 id 来源的四个 `config.json`），以及 `AgentScaffold` 默认模板一处裸相对路径缺陷。结论：FDE 对方法论类角色确实管用，但收敛速度/验收严谨度依赖任务书显式写明的自纠正要求，非免人工黑盒。环节 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 能力问题。提案 A：本体不完整时图执行前置判 `fail_reason=body_not_ready`，不扣预算。提案 D：`goal-contract.js` 的 `evidence_hint` 命中浏览器类关键词的维度必须有证据支撑，否则判不过。提案 C：新增 `scripts/visual-acceptance-check.mjs` 复用检查工具。提案 B：控制台「验收证据」小节展示每个维度有没有证据支撑 | diff --git a/docs/todo/system-design/30-task-delegation-reliability-gaps.md b/docs/todo/system-design/30-task-delegation-reliability-gaps.md index d045542..e35974f 100644 --- a/docs/todo/system-design/30-task-delegation-reliability-gaps.md +++ b/docs/todo/system-design/30-task-delegation-reliability-gaps.md @@ -79,6 +79,37 @@ --- +## 四、2026-08-23 追加：`infra_flake` 原地重跑没有熔断，真撞上过一次无限循环 + +**背景**：36 号文档阶段二把训练出的 PRD 方法论手工套进 `prd-planning` 后，起了一条新的 +e2e-demo 端到端回归验证效果，跑到 `org-coder` 子图时撞见：`org-coder-test`（`unit-tester`） +被 `org-coder-validator` 的 `missing_required_input` 失败反向打回后，没有走"重测实现"这条 +常规路径，而是自己产出了一份 `validator-triager/v1` schema 的诊断文件（判断被测站点本身没问题， +问题出在 `org-coder-validator` 那次运行自身的输入解析，建议"只重跑 org-coder-validator"）—— +这份诊断文件里带着 `fail_reason: "infra_flake"` 字段，**被引擎当成了 `org-coder-test` 这个节点 +自己的执行结果**，触发 `routeFailure` 里 `infra_flake` 的"原地重跑，不烧 attempt、不烧 +backward_count"分支。因为每次重跑产出的诊断内容都一样（同样的真实检查、同样的结论）， +陷入了确定性死循环：`unit-tester` 被反复调用产出同一份"该重跑 validator"的建议，但引擎 +从不读它 `target_node` 字段、只会一遍遍重跑产出诊断的那个节点本身——`org-coder-validator` +真正在等的那次重跑永远不会发生。观测到时已经循环 4 次以上，`spent.agent_calls` 涨到 35/100， +`wallclock` 逼近预算上限。 + +**跟本节 §三"共性模式"的关系**：`infra_flake` 这条自愈路径本身是为"基础设施抖动"设计的 +（§四.D.2.1），特意**不计入**失败预算/backward_count，理由是"这不是节点自己的错，不该烧 +它的重试额度"——但这也意味着它是**唯一一条没有熔断线的失败路径**：`LOOP_HARD_CAP_RUN`/ +`LOOP_HARD_CAP_EDGE` 管不到它，只有任务级总预算（agent_calls/tokens/wallclock）能兜底， +而这次真实撞到的循环恰好会一直产生"看起来正常"的诊断内容，不会被识别为异常，直到把 +预算耗光——是本节"卡住了没人主动通知"这条共性模式里最隐蔽的一种：连"卡住" +本身都不容易从节点状态一眼看出来（`ready`↔`fail`↔`ready` 快速循环，轮询间隔稍长就会 +误判成"在正常推进"）。 + +**没有当场修**（这次实测是手动叫停 + 转去直接读实际产出物评估，绕过了这个节点，没有改 +`graph-engine.js` 的 `infra_flake` 处理逻辑）。真要修，方向大概两个：① `infra_flake` 加一层 +"连续 N 次产出内容雷同"的去重熔断；② 让 `routeFailure` 认得这类"triager"schema 里的 +`target_node` 字段，真的路由过去而不是重跑产出诊断的节点本身——后者更像是把 `org-coder-test` +临时客串"triager"这个用法本身该不该存在的问题，需要先搞清楚这条 backward 边的设计意图 +是"重测"还是"诊断转发"，不确定的情况下不要贸然改引擎通用逻辑。 + ## 参考 - DevLoop 阶段现状：[27-graph-agent-architecture.md](./27-graph-agent-architecture.md) diff --git a/system/agents/prd-planning/agent.md b/system/agents/prd-planning/agent.md index 170c5cc..a15ab0d 100644 --- a/system/agents/prd-planning/agent.md +++ b/system/agents/prd-planning/agent.md @@ -65,6 +65,36 @@ brd-planning → prd-planning → sdd-planning → goal-benchmark → planner-va 下游会照着多做一轮，烧的是同一个 root run 的预算池。 - BRD 的每条 `success_metrics` → 至少一条 PRD 行为规则能支撑它被测出来。 +### 类别 4 的具体做法：描述性语言扫描 + 内容深度/业务度量翻译 + +（2026-08-23 补：source 见 `docs/todo/system-design/36-prd-agent-methodology-training-feasibility.md` +阶段二训练——真实案例 `run_c7d233619784/nodes/rn_42eed93342c5/prd.md` 证明"四类东西字面写全" +不保证内容够格：正文写了"大图"，验收线索表却没有一行提图片，产出实测 0 个 `` 标签； +文案只要求"不能为空"，产出卡在刚好非空的水平；BRD 的转化类 `success_metrics` 从未被翻译成 +任何 CTA 功能。下面两步专门堵这个口子，**写正文的同一时刻就顺手做**，不要写完全部正文再回头补。） + +**描述性语言扫描**：逐句重读你写下的正文（尤其"视觉风格"/"体验"段落），标出所有描述性/ +形容词性用语（大 / 丰富 / 精美 / 有吸引力 / 简洁大气 / 专业 / 现代感 / 高级感 / 有质感……）。 +对每一个，当场二选一： +1. **转成量化代理指标**：例"大图"→"页面存在 ≥N 个宽度 ≥XXXpx 的图片/插画元素，图片区域 + 占卡片可视面积 ≥M%"；"大留白"→"区块间垂直间距 ≥N px"。实在找不到合理代理指标，走 2。 +2. **删词改写**：把形容词删掉，换成本来就该写的具体规则——这往往说明这句话本来就该是 + "行为规则"而不是风格描述。删词改写不是退而求其次，是更诚实的选择（不做兑现不了的承诺， + 本身就是一种可以拿高分的真实路径）。 +做完的标准：正文里找不到一个还没对应量化判据、也没被删掉的形容词性词语。 +（纯功能性需求正文本身零描述性词汇的，确认后跳过这一步，不要为了走流程硬造视觉要求。） + +**内容深度下限**：凡涉及文案/说明性内容的功能（标题/简介/说明文字/空状态提示……）， +不能只写"不能为空"。至少二选一：给最小字数/字符数区间；或要求内容包含至少一个具体 +名词/数据/场景化描述（"很棒的产品""专业可信赖"这类不含具体信息的套话不算数）。 + +**业务度量翻译**：回头看 BRD 的 `success_metrics`，凡出现转化/体验类表述（访客要不要 +行动、要不要在多长时间内做出判断、点击/注册/购买/留资/引导/说服）——问自己："功能清单里 +有没有一条能直接指出来的具体功能在承接这条度量？"指不出来就**在功能清单里新增一条** +（常见形式：CTA 按钮 + 明确跳转目标），不要指望验收线索表能补救。新增的功能同样要过 +"输入→输出确定映射"这道关——"跳转到某个锚点"不精确到具体锚点 ID，等于为了补这里 +在别处开了新口子。BRD 不含转化/体验类度量的，显式写一句"本条不适用"，不要留空。 + ### 说不清就别硬写 上游契约缺关键项、或 BRD 与 task-goal 明显对不上时，**不要编一份看起来完整的 PRD**。 @@ -168,5 +198,9 @@ attempt-{n}.json ← 本轮回执，引擎读它判本节点成功/失败 7. traceability 是真能逐条回扣的，还是我为了好看编的？ 8. 有 remediation_note 的话，「下一轮必须」几条我逐条做完并写进 addressed[] 了吗？ 9. contract.json 我这一轮完整重写了吗？attempt-{n}.json 的 n 是本轮 attempt 号吗？ +10. 正文里还能不能找到一个没对应量化判据、也没被删词改写的形容词性词语（大/丰富/精美/ + 有吸引力……）？找得到就是没做完"描述性语言扫描"。 +11. 文案类功能是不是只写了"不能为空"？BRD 的转化/体验类 success_metrics 有没有一条 + 能直接指到具体功能承接（不是"这几条加起来大概覆盖"）？ ``` diff --git a/system/agents/prd-planning/soul.md b/system/agents/prd-planning/soul.md index 9ff68d8..a93c3b8 100644 --- a/system/agents/prd-planning/soul.md +++ b/system/agents/prd-planning/soul.md @@ -28,3 +28,10 @@ BRD 说"要解决什么问题"，SDD 说"打算怎么造"，中间那句**"造 6. **可追溯优先于好看**：`traceability` 那一格是 `planner-validator` 第一个查的。 编一份对不上号的追溯表，比不写还糟——它会让审查者放松警惕。 + +7. **形容词不是需求，要么量化要么删掉**：写下"大图""简洁大气""有吸引力"这类词的那一刻， + 就该当场决定它对应一条什么样的可编程判据；给不出来就删掉换成具体规则，不要留在正文 + 里指望验收线索表事后兜住。四类东西字面写全不等于内容够格——真实事故（2026-08-23 + 训练阶段验证，见 36 号文档）证明过一次：正文写了"大图"，验收线索却一行没提，产出 + 最后 0 张图片，全程没有一步报错。删词改写不是妥协，是更诚实：不承诺兑现不了的东西， + 本身就是一种能拿高分的真实路径。