Commit ced0268b29d021888ed1a57cd58f09970ef811c2
1 parent
853d2f0b
docs: 已完成的 5 份 todo 文档挪进 done/，修复索引与交叉引用
29-dream-design / 33-needs-gate-role-filter-bug / 35-validation-rigor-and-body-readiness-proposal / 39-boss-agent-task-supervision / 40-agent-chat-streaming-interrupt 逐份核实状态确认已完成 （后两份状态行本身滞后于代码，已在上一提交订正），按维护说明从 docs/todo/system-design/ 挪到 docs/done/system-design/，docs/README.md 的 todo/done 两张表同步更新。 顺带修复 4 处指向这 5 份文档的相对路径引用（28-followups / 31-work-graph-fail-fallback-coverage / 34-validator-scored-without-real-deliverable / 41-graph-vs-fde-reliability-discussion）， 文件搬家后原来的同目录相对链接会失效，改成 ../../done/system-design/ 的正确相对路径。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Showing
10 changed files
with
17 additions
and
10 deletions
docs/README.md
| ... | ... | @@ -31,6 +31,11 @@ |
| 31 | 31 | | [system-design/27-p3c-batch3-handover.md](./done/system-design/27-p3c-batch3-handover.md) | 批 3 交接 —— ✅ 已收口（2026-08-20）。**事故记录归档**：一份未经复核的代码被第三方会话提交进 main。留着是因为 §六 那几条多会话协作规则是真踩出来的 | |
| 32 | 32 | | [system-design/38-auth-multi-tenant-isolation.md](./done/system-design/38-auth-multi-tenant-isolation.md) | 登录鉴权 + 公司级多租户隔离 —— ✅ Phase 0/1/2/3 全部完成（2026-08-25）。种子账号 `admin`/`hex1234` + 登录页；全站挂 `requireAuth`（`agent-chat.js` 用 `requireAuthOrInternal` 放行三处服务端自环调用）；`company.json` 加 `ownerId`，`canAccessCompany` 是全仓库唯一归属判据，`company.js`/`graph-run.js`/`devloop.js` 分别接入（`graph-run.js` 双挂载点参数形状不同，设计阶段描述不准确，实现时才发现）；`okr.js` 因是零导航入口的孤儿页面改挂 `requireAdmin` 而非归属校验。**Phase 3 验证阶段真查出一个漏洞**：`agent-chat.js` 靠 `:agentId` 的 `"companyId:role"` 前缀区分会话归属却从没做过归属校验，任意登录用户可跨租户读别家公司会话，已修复。全量 `vitest` 1433 passed | |
| 33 | 33 | | [system-design/01-26](./done/system-design/) | 系统设计正文 01～26 章（14、25-harness-engineering-improvements 例外，见 todo/future/；27 例外，见 todo/），各章节状态见文内「状态」标记 | |
| 34 | +| [system-design/29-dream-design.md](./done/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） | | |
| 35 | +| [system-design/33-needs-gate-role-filter-bug.md](./done/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 号文档的真实回归验证过程中，与兜底边问题无关 | | |
| 36 | +| [system-design/35-validation-rigor-and-body-readiness-proposal.md](./done/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：控制台「验收证据」小节展示每个维度有没有证据支撑 | | |
| 37 | +| [system-design/39-boss-agent-task-supervision.md](./done/system-design/39-boss-agent-task-supervision.md) | ✅ **P1-P5 已实现**（2026-08-30，commit `a00590a` P1/P3/P4 后端、`5108d67` P2 前端、`d967ac0` P5）。boss agent 监督 goal/task 看板 + 独立任务看板页 + 心跳调度 + org/work graph 产出回写看板 + 公司级目标代码目录。本文档不再更新，仅存档决策过程，**已知未覆盖的后续工作见文内「六、已知遗留」** | | |
| 38 | +| [system-design/40-agent-chat-streaming-interrupt.md](./done/system-design/40-agent-chat-streaming-interrupt.md) | ✅ **已实现**（commit `4d23f50`，2026-08-30）。回应"前端刷新不及时/没有打字机效果，要不要把 SSE 换成 WebSocket"——排查后结论是传输层不是瓶颈（对照 hermes-webui/hermes-agent/deepseek-harness 三个参考实现，全部走 SSE，不用 WebSocket）。三个独立缺口全部补上：① 打字机不流畅→后端按字符数切片 + 前端 `createTypewriterQueue` 匀速吐出；② 执行中无法打断并接上新消息→`stop` 端点改轮询确认锁真正释放，前端据此直接发送/强制发送兜底，顺带修了服务端对同 convId 并发缺闸门这个真实 bug；③ 串台加固→`handleEvent` 抽成纯函数并补齐 `9b1c3f1` 那条不变式的回归测试。已用真实 Claude CLI 会话在浏览器验证 | | |
| 34 | 39 | |
| 35 | 40 | ## todo/（当前主线） |
| 36 | 41 | |
| ... | ... | @@ -48,17 +53,12 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d |
| 48 | 53 | | [27-goal-contract-format.md](./todo/system-design/27-goal-contract-format.md) | 验收契约格式（`goal-benchmark` / `goal-test-data` / `goal-test-script` 的产物形态与跨节点传递） | |
| 49 | 54 | | [27-p4-parallel-and-artifacts.md](./todo/system-design/27-p4-parallel-and-artifacts.md) | **P4（回收编号）并行执行与产物索引** — 📝 设计中，未实现。fan-out 真并发 + 同 agent 多实例隔离 + `files.json` 产物索引。三个 Phase，C 可插队 | |
| 50 | 55 | | [28-followups.md](./todo/system-design/28-followups.md) | 28 号（Agent 注册表统一）的遗留清单 — 主文档已在 `done/`，这份装没做完的：dream 机制（设计见 29 号，已实现，见下）、`source_kind`（✅已删）/`legacy_path`（不能删）删列、三项「已实施未验证」。任务态清理（✅已实现，见下）。§五 是**已立起来的守卫清单**（别重复造，也别删） | |
| 51 | -| [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） | | |
| 52 | 56 | | [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` 原地重跑没有熔断线，真撞上过一次确定性死循环（节点把诊断结论误判成自己的执行结果，反复重跑却从不路由到诊断建议的目标节点）；已加 `infra_flake_count` 列 + 硬顶 3 次熔断，连续判 infra_flake 超过硬顶就改判 blocked 交给人工 | |
| 53 | 57 | | [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 次，零人工介入），修复确认生效 | |
| 54 | -| [39-boss-agent-task-supervision.md](./todo/system-design/39-boss-agent-task-supervision.md) | 📝 **设计评估中，未实现**。评估用户提出的五阶段方案（雇 boss agent 监督 goal/task 看板、独立任务看板页、心跳挨个调度、org/work graph 产出的 bug/新任务回写看板、公司级目标代码目录）。结论：P2 看板已实现、P1/P3 心跳与 `ceo` 本体基础设施已有大半、P5 的 `linked-existing` 模式已在 `path-resolver.js` 完整实现只差公司级默认值，**真正从零开始的是 P4（回写闭环）**——当前没有任何 agent 工具能读写 goal/task 板。建议顺序倒过来先建 P4 地基 | | |
| 55 | 58 | | [41-graph-vs-fde-reliability-discussion.md](./todo/system-design/41-graph-vs-fde-reliability-discussion.md) | 📝 **讨论记录 + 落地实测，非设计方案**。org/work graph 与 master-Innovator-FDE 两套工作流的稳定性对比：根因是"拓扑运行时生成 vs 写死"。问题 7 是真实执行记录——新建 `org-hunt/digest/evolve`（graph 原生协议，方法论抄 innovator-hunt/digest/evolver）跑 Hunt→Digest→Evolve，11 轮真跑中挖出并修复 5 个独立缺陷（建公司自动规划竞态、work-graph 模板库缺内容型交付物骨架、验收节点任务描述越权、两个规划 agent 的路径口径写错、R-19 产出索引 `indexNodeOutputs()` 不覆盖项目根——最后一条改了 `graph-engine.js` 核心逻辑，加 `contract.json` 的 `produces` 显式声明机制，全局生效，补了 2 条守卫测试）。最终产出与原生 FDE（`prd-methodology-trial`）对比：内容骨架可迁移、质量不打折，但过程严谨度不如原生 FDE，可靠性差距悬殊（原生一次跑通，graph 版 11 轮才稳定）。`routeFailure` 的 `infra_flake` 分支绕过跨层寻址（`target_node`）仍是唯一确认还没补的口子 | |
| 56 | 59 | | [37-org-graph-department-scoping.md](./todo/system-design/37-org-graph-department-scoping.md) | 📝 **设计讨论，调用点扫描已完成，尚未立项实现**。现状 org graph 按 `company_id` 单例（`27-P2` 标题原文即"公司级"），塞不下 HR/财务/市场这类跟"交付流水线"无关的公司常设职能——`system/agents/hr/`（"招·留·管·退"）本体已存在却从没被装进任何图，全靠 fire-and-forget chat 招聘、无图执行审计轨迹。提议把 org graph 作用域从 `company_id` 升级为 `(company_id, department_id)`，一家公司可装配多张部门图，每张仍保持人工固定/慢变/可审计。全仓库调用点扫描结论：改造面是最初估算的 4 倍——真正的单点真相在 `work-graph-db.js:readDefGraph` 的裸 SQL 不变式（不在服务层），还牵涉两个易混淆服务文件间必须字节级一致的重复唯一索引、独立的 `graph-seed-service.js` 对账子系统、`company-hire-org-layer.test.js` 专属测试、`orggraph-planning`/`task-planning` 两份 agent 人设文档的自我认知改写 | |
| 57 | 60 | | [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:<reason>` 写进本体 `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（训练产物 → 雇佣本体转换）尚未开工 | |
| 58 | -| [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：控制台「验收证据」小节展示每个维度有没有证据支撑 | | |
| 59 | 61 | | [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) 那类"装配没填充完"的真实样本，不是平台工具限制 | |
| 60 | -| [40-agent-chat-streaming-interrupt.md](./todo/system-design/40-agent-chat-streaming-interrupt.md) | 📝 **需求文档，讨论中，未实现**。回应"前端刷新不及时/没有打字机效果，要不要把 SSE 换成 WebSocket"——排查后结论是传输层不是瓶颈（对照 hermes-webui/hermes-agent/deepseek-harness 三个参考实现，全部走 SSE，不用 WebSocket）。真正的三个独立缺口：① 打字机不流畅（ACP chunk 粒度太粗，方案是前后端都做匀速切片/渲染缓冲）；② 执行中无法打断并接上新消息（现状"先 Stop 再发"两步，方案是深度 1 的打断-排队，顺带发现服务端对同 convId 并发缺闸门这个现存 bug）；③ 串台已在 `9b1c3f1` 修复但没有回归测试兜底 | | |
| 61 | -| [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 号文档的真实回归验证过程中，与兜底边问题无关 | | |
| 62 | 62 | |
| 63 | 63 | ## todo/future/（暂缓，非当前重心） |
| 64 | 64 | ... | ... |
docs/todo/system-design/29-dream-design.md renamed to docs/done/system-design/29-dream-design.md
docs/todo/system-design/33-needs-gate-role-filter-bug.md renamed to docs/done/system-design/33-needs-gate-role-filter-bug.md
docs/todo/system-design/35-validation-rigor-and-body-readiness-proposal.md renamed to docs/done/system-design/35-validation-rigor-and-body-readiness-proposal.md
docs/todo/system-design/39-boss-agent-task-supervision.md renamed to docs/done/system-design/39-boss-agent-task-supervision.md
docs/todo/system-design/40-agent-chat-streaming-interrupt.md renamed to docs/done/system-design/40-agent-chat-streaming-interrupt.md
| 1 | 1 | # 40-agent-chat-streaming-interrupt. Agent Chat 打字机平滑 + 打断-排队 + 串台加固 |
| 2 | 2 | |
| 3 | 3 | > **日期**: 2026-08-30 |
| 4 | -> **状态**: 📝 需求文档，讨论中，尚未实现 | |
| 4 | +> **状态**: ✅ 已实现（commit `4d23f50`，2026-08-30）。三个方案全部落地：后端按字符数切片 + | |
| 5 | +> 前端 `createTypewriterQueue` 匀速吐出（打字机平滑）；`stop` 端点改轮询确认 | |
| 6 | +> `agentChatLocks` 真正释放后返回 `cleaned`，前端据此直接发送或走强制发送兜底，执行中解锁 | |
| 7 | +> 输入框（打断-排队）；`handleEvent` 分发逻辑抽成不依赖组件实例的纯函数 | |
| 8 | +> （`agentChatEvents.js`），补上 `9b1c3f1` 那条不变式的回归测试（串台加固）。已用真实 | |
| 9 | +> Claude CLI 会话（非 mock）在浏览器里验证打字机效果与打断并发送。实现过程中顺手修了一个 | |
| 10 | +> 真实并发漏洞：同一 `agentId` + 同一 `convId` 的并发请求此前完全没有闸门。本文档不再更新， | |
| 11 | +> 仅存档设计过程，实现细节以代码为准。 | |
| 5 | 12 | > **触发**: 用户反馈"前端刷新不及时、没有打字机效果"，怀疑要不要把传输层从 HTTP 换成 WebSocket |
| 6 | 13 | > 来解决打字机效果、多 Agent/多聊天切换、执行中无法打断这几个问题。经排查现状代码 + |
| 7 | 14 | > 对照 [hermes-webui](file:///Users/yibo/Documents/lemonAI/hermes-webui)、 | ... | ... |
docs/todo/system-design/28-followups.md
| ... | ... | @@ -21,7 +21,7 @@ |
| 21 | 21 | ### 1.1 dream 机制 |
| 22 | 22 | |
| 23 | 23 | **状态（2026-08-20 更新）**：设计已成文并已实现，见 |
| 24 | -[29-dream-design.md](./29-dream-design.md)。四条取舍（去敏判据 / 沉淀落点 / 触发时机 / | |
| 24 | +[29-dream-design.md](../../done/system-design/29-dream-design.md)。四条取舍（去敏判据 / 沉淀落点 / 触发时机 / | |
| 25 | 25 | 质量评估）均已拍板，五步推进顺序 + 定时挂载 + 定义文件写入均已落地， |
| 26 | 26 | `innovator-evolver` 上真 CLI 跑通一次（40 条原料 → 4 条抽象经验，8 条引用全部核对回原文）。 |
| 27 | 27 | ... | ... |
docs/todo/system-design/31-work-graph-fail-fallback-coverage.md
| ... | ... | @@ -15,7 +15,7 @@ |
| 15 | 15 | > （零 `retryNode` 调用），最终 planner 子图收敛到 `completed`。**修复确认生效，有真实证据**。 |
| 16 | 16 | > 同一次验证顺带在 `org-coder` 子图撞见一个**独立的新 bug**（`inboundContracts` 未按 `role` |
| 17 | 17 | > 过滤，把 `produces` 声明误当 `needs`，导致 `missing_required_input` 假阳性），与本文档无关， |
| 18 | -> 已记录在 [33-needs-gate-role-filter-bug.md](./33-needs-gate-role-filter-bug.md)。 | |
| 18 | +> 已记录在 [33-needs-gate-role-filter-bug.md](../../done/system-design/33-needs-gate-role-filter-bug.md)。 | |
| 19 | 19 | |
| 20 | 20 | --- |
| 21 | 21 | ... | ... |
docs/todo/system-design/34-validator-scored-without-real-deliverable.md
| ... | ... | @@ -17,7 +17,7 @@ |
| 17 | 17 | > 前置闸门统一验证严谨度，留给下次设计。 |
| 18 | 18 | > **触发**: `e2e-demo` 公司真实回归任务 `T-mt2r6fz0-125b`（goal `G-mt2r62ia-73af`， |
| 19 | 19 | > root run `run_0e9074815130`）——[31 号文档](./31-work-graph-fail-fallback-coverage.md) |
| 20 | -> 兜底边修复 + [33 号文档](./33-needs-gate-role-filter-bug.md) 契约修复之后，把这条任务 | |
| 20 | +> 兜底边修复 + [33 号文档](../../done/system-design/33-needs-gate-role-filter-bug.md) 契约修复之后，把这条任务 | |
| 21 | 21 | > 真正推到 `completed`，回头查"最终产出在哪"时发现的 |
| 22 | 22 | |
| 23 | 23 | --- | ... | ... |
docs/todo/system-design/41-graph-vs-fde-reliability-discussion.md
| ... | ... | @@ -348,7 +348,7 @@ FDE 无关，纯粹为了让 org-hunt 做真调研）反复 `rerun` 同一个 ta |
| 348 | 348 | requireAuthOrInternal`，本次合并已带入）。核实过 `server/routes/company.js:18` 现在是 |
| 349 | 349 | `router.use(requireAuthOrInternal)`，不再是 `requireAuth`。 |
| 350 | 350 | - [x] ~~boss agent（暂定挂在 CEO 身份下）：主动巡检 goal/task/work 状态~~ —— |
| 351 | - **已被另一并行会话实现**，见 [39-boss-agent-task-supervision.md](./39-boss-agent-task-supervision.md) | |
| 351 | + **已被另一并行会话实现**，见 [39-boss-agent-task-supervision.md](../../done/system-design/39-boss-agent-task-supervision.md) | |
| 352 | 352 | （P1-P5，commit `a00590a`/`5108d67`/`d967ac0`），本文档这条 TODO 作废，后续跟进请去那份 |
| 353 | 353 | 文档的「六、已知遗留」一节。 |
| 354 | 354 | - [ ] `routeFailure` 的 `infra_flake` 分支补上 `target_node` 路由（30 号文档遗留的"刻意没做②"）。 | ... | ... |