From 601ed9abbaba3b33a4476c6ac094f7caabea2336 Mon Sep 17 00:00:00 2001 From: yibo Date: Wed, 9 Sep 2026 17:10:13 +0800 Subject: [PATCH] docs(27-p3-p4): 同步全部交叉引用（前一提交只带了改名，本次补上内容） --- docs/README.md | 7 ++++--- docs/done/system-design/27-p2-org-graph.md | 10 +++++----- docs/done/system-design/27-p3c-goal-task-model.md | 4 ++-- docs/todo/system-design/27-e2e-task-execution-flow.md | 16 ++++++++-------- docs/todo/system-design/27-example-dev-company-walkthrough.md | 4 ++-- docs/todo/system-design/27-goal-contract-format.md | 8 ++++---- docs/todo/system-design/27-graph-agent-architecture.md | 10 +++++----- docs/todo/system-design/27-naming-conventions.md | 6 +++--- docs/todo/system-design/27-requirement.md | 42 +++++++++++++++++++++--------------------- server/routes/graph-run.js | 2 +- server/services/graph-engine.js | 2 +- server/services/graph-run-sse.js | 2 +- server/services/work-graph-db.js | 2 +- server/tests/unit/graph-engine.test.js | 2 +- server/tests/unit/graph-real-chain-smoke.test.js | 2 +- system/agents/_registry.json | 10 +++++----- system/agents/benchmark-validator/agent.md | 2 +- system/agents/brd-planning/tools.md | 2 +- system/agents/coder-validator/agent.md | 2 +- system/agents/org-validator/agent.md | 2 +- system/agents/planner-validator/agent.md | 2 +- system/agents/prd-planning/tools.md | 2 +- system/agents/testdata-validator/agent.md | 2 +- system/agents/validator-triager/agent.md | 2 +- system/agents/validator-triager/tools.md | 2 +- system/work-graph-templates/README.md | 2 +- 26 files changed, 75 insertions(+), 74 deletions(-) diff --git a/docs/README.md b/docs/README.md index ad75ee9..98110a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ 判断依据：文档正文的显式「状态」标记（✅ 已完成 / 已实现 vs 📝 设计中 / 未实现）、未勾选的 checklist，以及与代码库实际实现的交叉核对（见各条目备注）。 > **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。 -> 该系列已完成的阶段文档（P1 / P2 / **P3 收尾 P3C**）移入 `done/`，其余非主线待办在 `todo/future/`。 +> 该系列已完成的阶段文档（P1 / P2 / **P3+P4 执行控制台** / **P3 收尾 P3C** / P3B / P4）移入 `done/`，其余非主线待办在 `todo/future/`。 > **当前未完成的是**：28-followups。P3B 九条验收已于 2026-09-08 全部验完；P4 已于 2026-09-08 收口；P3/P4「真实路径 smoke 进 CI」的欠账已基本还清，只剩真 LLM（本质限制）与按需 hire 未覆盖。 ## done/ @@ -27,6 +27,7 @@ | [user-guides/08-base-agent-4-phase-guide.md](./done/user-guides/08-base-agent-4-phase-guide.md) | Base Agent 四阶段使用指南 | | [system-design/27-p1-virtual-reference.md](./done/system-design/27-p1-virtual-reference.md) | P1 虚拟引用寻址 — ✅ 已实现（commit `226489d`，`server/services/graph-service.js`）：`agent.md` 不再逐公司拷贝，改为 `config.json.systemAgentRef` 引用 + `company-context.md` 承载公司语境 | | [system-design/27-p2-org-graph.md](./done/system-design/27-p2-org-graph.md) | P2 Org Graph — ✅ 已实现（`70a4727` + `f20d0d8`）：org graph 定位为 company 级 workflow（执行流边），`orggraph-planning` agent 建公司时自动规划并招聘。真实建公司端到端验证通过 | +| [system-design/27-p3-p4-work-graph-console.md](./done/system-design/27-p3-p4-work-graph-console.md) | P3+P4（原 P4 回退+Loop-Validator 已并入）图执行引擎与执行控制台 — ✅ **2026-09-09 已彻底收口**，移入 `done/`（`c3abf4a` 起七轮实现）。§十「四条硬规矩」第 2 条欠账已还清：`graph-real-chain-smoke.test.js`（零注入、只换掉真 CLI 子进程）进 CI，覆盖 `agent_call`/`subgraph` 两支 + 多节点/回退边/双层熔断三种形状；按需 hire（`resolvePlanningAgentName`）用隔离 worktree + 真 Claude CLI 探针跑通，`workgraph-planning` 真的被按需雇进了一家没预雇过它的真实公司。唯一剩下的是真 LLM 本身进不了 CI 这条本质限制（要额度、分钟级、输出不确定），不算欠账，只能靠隔一段时间人工真跑核实 | | [system-design/27-p3c-goal-task-model.md](./done/system-design/27-p3c-goal-task-model.md) | **P3 收尾** goal / task 两级模型 + 控制台任务列表 — ✅ 已完成（2026-08-20）：五批实施 + §十七 清尾。含队列 / 并行槽位、`task-planning`、两套任务体系统一、墙钟预算改「只算活跃时长」。**§17.5 是真跑验收** —— 返工闭环第一次由真 agent（不是注入的假 executor）走通 | | [system-design/27-p3c-batch3-handover.md](./done/system-design/27-p3c-batch3-handover.md) | 批 3 交接 —— ✅ 已收口（2026-08-20）。**事故记录归档**：一份未经复核的代码被第三方会话提交进 main。留着是因为 §六 那几条多会话协作规则是真踩出来的 | | [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 | @@ -51,7 +52,7 @@ ## todo/（当前主线） -Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `done/`**（P1、P2），下面是仍在推进或长期有效的部分。 +Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `done/`**（P1、P2、P3+P4、P3C、P3B、P4），下面是仍在推进或长期有效的部分。 | 文件 | 说明 | |------|------| @@ -60,7 +61,6 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d | [27-naming-conventions.md](./todo/system-design/27-naming-conventions.md) | **命名规范**。`{作用域}-{职能}`；图节点按层级轴命名；节点名 ≠ 本体名；三种 benchmark 消歧；OKR 正名。新增 agent id / 表名 / 字段名前必读 | | [27-e2e-task-execution-flow.md](./todo/system-design/27-e2e-task-execution-flow.md) | 端到端流程总览：建公司 → 下达任务 → org graph 逐节点执行 → work graph 规划与循环 → 验收收敛。含与 DevLoop 既有实现的对应关系分析 | | [27-example-dev-company-walkthrough.md](./todo/system-design/27-example-dev-company-walkthrough.md) | 参考场景走查（虚构的「配图工厂」），把架构跑一遍具体的数：各阶段 JSON 形态、成本估算、断点清单 | -| [27-p3-p4-work-graph-console.md](./todo/system-design/27-p3-p4-work-graph-console.md) | P3+P4（原 P4 回退+Loop-Validator 已并入）图执行引擎与执行控制台 — ✅ 已实现（`c3abf4a`）。**仍留 todo 的原因**：§十 末「四条硬规矩」第 2 条那笔欠账**已基本还清**（2026-09-08）——`graph-real-chain-smoke.test.js`（零注入、只换掉真 CLI 子进程）已进 CI，覆盖 `agent_call`/`subgraph` 两支 + 多节点/回退边/双层熔断三种形状；按需 hire（`resolvePlanningAgentName`）2026-09-09 用隔离 worktree + 真 Claude CLI 探针跑通，`workgraph-planning` 真的被按需雇进了一家没预雇过它的真实公司。剩下的只有真 LLM 本身进不了 CI 这一条本质限制（要额度、分钟级、输出不确定，只能靠隔一段时间人工真跑核实，不会有"还清"的一天） | | [27-goal-contract-format.md](./todo/system-design/27-goal-contract-format.md) | 验收契约格式（`goal-benchmark` / `goal-test-data` / `goal-test-script` 的产物形态与跨节点传递） | | [28-followups.md](./todo/system-design/28-followups.md) | 28 号（Agent 注册表统一）的遗留清单 — 主文档已在 `done/`，这份装没做完的：dream 机制（设计见 29 号，已实现，见下）、`source_kind`（✅已删）/`legacy_path`（不能删）删列、三项「已实施未验证」。任务态清理（✅已实现，见下）。§五 是**已立起来的守卫清单**（别重复造，也别删） | | [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 交给人工 | @@ -69,6 +69,7 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d | [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（训练产物 → 雇佣本体转换）尚未开工 | | [49-antigravity-inspired-parallel-verification-proposal.md](./todo/system-design/49-antigravity-inspired-parallel-verification-proposal.md) | 📝 **设计讨论，不代表已拍板**（2026-09-04）。对照 Google Antigravity「Teamwork」多智能体框架博客文章，给 27 号 P4「真并行」与 34/35 号「验证严谨度不稳定」两个议题出的方案草稿。**先纠正一个前提**：重读 27-P4 全文后发现阶段 A/B/C 早已全部实现（又一次「文档落后于代码」），当时判断真并行只剩 T2/role 列/`advanceTree` 兄弟子 run 并发三件小事——2026-09-08 收口时又发现这个判断本身有两处误判（role 列其实早就落库、T1 的✅遗漏了 scope 参数的生产接线），三件小事（连同两处误判一起）已全部核实/补齐，见 [27-P4](./done/system-design/27-p4-parallel-and-artifacts.md)。**新提案 A**：借鉴长证明模式的「竞争候选+对抗批评+综合」，区别于现有 `executor-fanout.json` 的分解型 fan-out——需要先有真实场景验证价值，不建议凭空立项，详细设计见 [50 号文档](./todo/system-design/50-competing-candidates-critic-synthesis-design.md)。**新提案 B**：把 35 号提案 D「浏览器关键词命中才要证据」泛化成 benchmark 段全维度默认要求执行级证据（**唯一建议现在推进的部分**）；实地核实过把验收路径引导到 `test_script` 段的工作量后**结论是不做**——撞上 `test_script.path` 解析根不含 `org-coder` 实际写代码的项目根这个结构性冲突，改造面远超预期；新增「陷阱注册表」，把 validator 判卷失败的结构化原因喂回 Dream 机制，落点已定案为独立文件 `known_pitfalls.md`（不复用 `memory.md`，避免语义混淆）。建议推进顺序：陷阱注册表最低成本先做，证据泛化次之，竞争候选需要真实场景才立项 | | [50-competing-candidates-critic-synthesis-design.md](./todo/system-design/50-competing-candidates-critic-synthesis-design.md) | 📝 **设计草稿，不代表已拍板**（2026-09-04）。49 号文档提案 A 的展开：竞争候选骨架 JSON 形状草稿（`candidate-council.json`，未定案）、命名（按 27-NAMING 节点带前缀/本体不带前缀两轴）、`workgraph-planning` 选型判据方向。**关键设计约束**：critic（评判）与 synthesis（择优/融合）必须拆成两个节点，依据是仓库真实事故——`qa-judge` 早期"评判+终态判决合一"设计导致过一次无限循环（20 次调用/31 分钟才熔断，记录在 `deliverable.json` 的反模式说明里），新骨架延续 `validator-triager`/`benchmark-validator` 已验证的"归因/打分/判定三者分离"范式。**预算风险量化**：N 路候选并行消耗 N 倍预算，且 `checkBudget` 只在批量拾取前查一次，实际可能超支到 `maxConcurrency-1`（默认最多多花 4 次调用）才被拦下，候选数 N 目前代码层没有硬顶 | +| [51-ceo-autonomous-goal-refill-design.md](./todo/system-design/51-ceo-autonomous-goal-refill-design.md) | 📝 **设计草稿，不代表已拍板**（2026-09-09）。回应"公司能否 7×24 自转"的提问——核实执行层（存活扫描/僵尸 goal 收口/CEO 阻塞任务兜底心跳）已经扎实，真正缺口在决策层：`ceo/heartbeat.md` 与 `tools.md` 的"该提新任务"判断全部要求先有一个 goal/task 存在，没有一条覆盖"公司没有任何 active/draft/planning goal"这种完全空转场景；且 CEO 目前**没有创建 goal 的工具**（`tools.md` 对 `/goals` 只有 GET 示例），`POST /:companyId/goals` 端点存在于路由层但从未暴露给它。设计方案：心跳查询为空时进入"立项模式"，先查公司使命（`company-context.md`，默认"待定义"时拒绝立项、转人工）作为立项锚点，用 `created_by:'ceo'` + `split:false`（避免草稿阶段就烧 task-planning token）建草稿 goal，去重后停在 `draft` 等人工 `/dispatch`——分两阶段放权，阶段 B（CEO 自动 enqueue + guardrail）本文档只给方向不实现 | ## todo/future/（暂缓，非当前重心） diff --git a/docs/done/system-design/27-p2-org-graph.md b/docs/done/system-design/27-p2-org-graph.md index 5f31120..c334614 100644 --- a/docs/done/system-design/27-p2-org-graph.md +++ b/docs/done/system-design/27-p2-org-graph.md @@ -25,7 +25,7 @@ v0.1-v0.3 把 Org Graph 建模为**静态汇报结构**：节点是角色引用 | 生成时机 | 建公司时，一次 | 每个 org node 接到任务时 | | 节点指向 | org node agent（`org-planner` 等） | system agent 引用 | | 边的语义 | **执行流**：`condition ∈ {success, fail}` | **执行流**：同左 | -| 执行引擎 | [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) 的同一套 | 同左 | +| 执行引擎 | [27-P3/P4](./27-p3-p4-work-graph-console.md) 的同一套 | 同左 | **由此带来的四处结构性改动**（这也是本次重写的主要内容）： @@ -47,7 +47,7 @@ v0.1-v0.3 把 Org Graph 建模为**静态汇报结构**：节点是角色引用 ### 非目标 -- **不做**图的执行 —— 执行引擎、启动/暂停/单步/重试、SSE 全部属于 [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md)。P2 只负责"把图建出来、存好、能读能画"。 +- **不做**图的执行 —— 执行引擎、启动/暂停/单步/重试、SSE 全部属于 [27-P3/P4](./27-p3-p4-work-graph-console.md)。P2 只负责"把图建出来、存好、能读能画"。 - **不做** `company.json.agents[]` 的废弃 —— 它仍是"这家公司雇了谁"的真相源；org graph 回答的是"任务怎么流过这些人"，两者并存。 - **不做**存量公司的补图 —— 见 §六。 - **不做** `workgraph-planning` agent 本身的设计 —— 属于 P3。 @@ -95,7 +95,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active ### 3.3 图的合法性约束（写入前校验） -与 work graph 的执行前校验同一套规则（[27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §四.A）： +与 work graph 的执行前校验同一套规则（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A）： 1. **无环**（仅针对 `edge_kind='forward'`）—— 三色 DFS，复用 DevLoop `doc-store.js:167` 的 `hasCycle()` 实现。 2. **单一入口**（✅ 已定案，见 [27-REQ](../../todo/system-design/27-requirement.md) R-13）—— 必须恰好有一个入度为 0 的 forward 节点，任务从这里进入。多入口会让"任务从哪开始"无法确定，且需要任务入口多带一个参数。 @@ -183,7 +183,7 @@ if (bootstrap.status === 'hired_from_template') { ### 4.5 前端 -**不自己写渲染逻辑** —— org graph 与 work graph 同构，直接复用 [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) T3 的画布组件（其本身又是扩展自既有的 `web/src/components/devloop/UnitsDAG.vue`，已实现 SVG + Kahn 分波布局 + 状态着色 + 点击下钻）。 +**不自己写渲染逻辑** —— org graph 与 work graph 同构，直接复用 [27-P3/P4](./27-p3-p4-work-graph-console.md) T3 的画布组件（其本身又是扩展自既有的 `web/src/components/devloop/UnitsDAG.vue`，已实现 SVG + Kahn 分波布局 + 状态着色 + 点击下钻）。 这也意味着 **P2 的前端工作依赖 P3 的画布组件先做出来**。若想让 P2 独立上线，可以先在 Company Dashboard 用一个纯文本的拓扑序列表占位（`org-planner → org-coder → org-validator`），等 P3 画布就绪再替换。 @@ -211,7 +211,7 @@ if (bootstrap.status === 'hired_from_template') { 同理提供 `content.json`（`org-planner → org-writer → org-validator`）、`ops.json`。三张图**首尾节点同名**， 只有中段执行节点不同——命名轴是节点所在图的层级，不是业务领域（[27-NAMING](../../todo/system-design/27-naming-conventions.md) §3.1）。 -`dev.json` 那两条 `fail` 边是 P3 的 `fail_reason` 细分路由（[27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2）： +`dev.json` 那两条 `fail` 边是 P3 的 `fail_reason` 细分路由（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2）： 带 `failReason` 的边按归因结果精确匹配，不带 `failReason` 的那条是**兜底边**， 任何有 `fail` 出边的节点都必须留一条，否则归因产出图上没有的取值时会落到死路。 `content.json` / `ops.json` 目前只有兜底边。 diff --git a/docs/done/system-design/27-p3c-goal-task-model.md b/docs/done/system-design/27-p3c-goal-task-model.md index 4235427..80e60fd 100644 --- a/docs/done/system-design/27-p3c-goal-task-model.md +++ b/docs/done/system-design/27-p3c-goal-task-model.md @@ -1,6 +1,6 @@ # 27-P3C. 公司目标与任务 —— goal / task 两级模型 + 控制台任务列表 -> **所属**: [27 Graph Agent 架构](../../todo/system-design/27-graph-agent-architecture.md) 的 **P3 收尾**（P3C），直接续 [27-P3/P4 执行控制台](../../todo/system-design/27-p3-p4-work-graph-console.md) §四.B 与 [27-P3B 真跑跑道](./27-p3b-real-run-runway.md)。 +> **所属**: [27 Graph Agent 架构](../../todo/system-design/27-graph-agent-architecture.md) 的 **P3 收尾**（P3C），直接续 [27-P3/P4 执行控制台](./27-p3-p4-work-graph-console.md) §四.B 与 [27-P3B 真跑跑道](./27-p3b-real-run-runway.md)。 > **日期**: 2026-08-18 > **状态**: ✅ **已完成并归档**（2026-08-20）。五批全部实施（§十三 ～ §十六），§15.5 / §16.8 的后续项也已全部收掉（§十七）。 > 138 文件 / 1292 测试全绿，`web:build` 通过。**真跑验收见 §17.5** —— 返工闭环第一次由真 agent（不是注入的假 executor）走通。 @@ -845,7 +845,7 @@ parent_task_id TEXT REFERENCES tasks(id), -- B 的任务链；A 的 depends_ ## 十三、批 1 实施记录（2026-08-18，commit `7f24ef0`） -> 体例照 [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §十：**设计正文不改写，只在这里与实现对账**。 +> 体例照 [27-P3/P4](./27-p3-p4-work-graph-console.md) §十：**设计正文不改写，只在这里与实现对账**。 > 凡本节与前文冲突，**以本节为准** —— 前文是设计时的判断，本节是跑出来的事实。 ### 13.1 落地了什么 diff --git a/docs/todo/system-design/27-e2e-task-execution-flow.md b/docs/todo/system-design/27-e2e-task-execution-flow.md index 5e10b2c..b2fa95f 100644 --- a/docs/todo/system-design/27-e2e-task-execution-flow.md +++ b/docs/todo/system-design/27-e2e-task-execution-flow.md @@ -3,7 +3,7 @@ > **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的跨阶段总览文档，串起 P2（Org Graph）、P3/P4（Work Graph 执行）、P5（自我进化）。 > **版本**: v0.1 > **日期**: 2026-08-15 -> **前置**: [27-P2 Org Graph 落地](../../done/system-design/27-p2-org-graph.md)、[27-P3/P4 Work Graph 执行控制台](./27-p3-p4-work-graph-console.md)、**以及本文档最重要的参考源** `docs/prd/newfunction/_spec/`（DevLoop 的完整 MVCP 规格，尤其 `loops-overview.md` / `loops-l1.md` / `loops-l2.md` / `loops-l3.md` / `sdd-process.md` / `plan-cost-concurrency.md`）。 +> **前置**: [27-P2 Org Graph 落地](../../done/system-design/27-p2-org-graph.md)、[27-P3/P4 Work Graph 执行控制台](../../done/system-design/27-p3-p4-work-graph-console.md)、**以及本文档最重要的参考源** `docs/prd/newfunction/_spec/`（DevLoop 的完整 MVCP 规格，尤其 `loops-overview.md` / `loops-l1.md` / `loops-l2.md` / `loops-l3.md` / `sdd-process.md` / `plan-cost-concurrency.md`）。 > **需求源头**: [27-REQ 原始需求](./27-requirement.md) —— 本文档是对那些原话的结构化转述，原文以那份为准。 > **配套**: [27-EXAMPLE 参考场景走查](./27-example-dev-company-walkthrough.md) —— 本文档讲机制，那份文档把机制在一家具体公司上跑一遍数。两份对照着读。 @@ -31,7 +31,7 @@ - **成本与并发预算的数字版**（`plan-cost-concurrency.md`）：每个 agent 每次调用的 token 估算、典型项目总成本（中项目 ≈ 410K token ≈ $4.8）、三层并发上限、墙钟估算、6 个监控指标及告警阈值。 - **前端组件全集**（`sdd-view.md` V-1..V-11），且**代码已经存在**：`web/src/components/devloop/` 下 8 个组件，含 `UnitsDAG.vue`（SVG + Kahn 分波布局的 DAG 渲染器）、`LiveAgentStream.vue`（带 Last-Event-ID 断线重连的 SSE 消费）、`UnitDrawer.vue`（节点详情抽屉）。 -**这直接影响你的问题「这个流程是否是这样实现的」——答案是：在"一家写代码的公司"这个具体场景下，是的，而且已经实现了大半。** `loop-controller.js` 的 `runProject()` 已完整实现（不是我在 [27-P3/P4](./27-p3-p4-work-graph-console.md) 文档里写的 501，那条陈述已过期，见 §九），包含 Kahn 拓扑分波、L2 闸门、Integrator、Triager 四分支调度、预算熔断、SSE 埋点。 +**这直接影响你的问题「这个流程是否是这样实现的」——答案是：在"一家写代码的公司"这个具体场景下，是的，而且已经实现了大半。** `loop-controller.js` 的 `runProject()` 已完整实现（不是我在 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 文档里写的 501，那条陈述已过期，见 §九），包含 Kahn 拓扑分波、L2 闸门、Integrator、Triager 四分支调度、预算熔断、SSE 埋点。 ### 结论 2：DevLoop 就是你这套架构的一个「硬编码实例」 @@ -90,7 +90,7 @@ P2 已经设计了：`system/org-graph-templates/{dev,content,ops}.json` 模板 ### 阶段 4 · 第一个 org node（planner）调 planning-work-graph subagent 规划自己的 work graph -**状态**：📐 概念已在 27 号文档 §3.4 定义，执行引擎见 [27-P3/P4](./27-p3-p4-work-graph-console.md)，**但 planning agent 本身未设计** +**状态**：📐 概念已在 27 号文档 §3.4 定义，执行引擎见 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md)，**但 planning agent 本身未设计** 你举的例子 `brd-planning → prd-planning → sdd-planning → benchmark → testdata → planner-validator → loop-validator`，与 DevLoop 的实际链路高度重合： @@ -212,7 +212,7 @@ edge_kind TEXT NOT NULL DEFAULT 'forward' CHECK (edge_kind IN ('forward','back 汇报关系若仍需要，降级为 `org_graph_nodes` 上的一个可空属性（`reports_to_node_id`），不再是图的主干语义。 -2. **两层图的递归关系**（复用 [27-P3/P4](./27-p3-p4-work-graph-console.md) 已有的 `parent_node_id`）： +2. **两层图的递归关系**（复用 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 已有的 `parent_node_id`）： ``` Org Graph（company 级 workflow，orggraph-planning 建公司时生成） @@ -376,10 +376,10 @@ RESEARCH → PLAN → EXECUTE → VERIFY | # | 文档 | 原错误陈述 | 事实 | 修订结果 | |---|---|---|---|---| -| 1 | [27-P2](../../done/system-design/27-p2-org-graph.md) §九、[27-P3/P4](./27-p3-p4-work-graph-console.md) §九 | "P1 目前仍是设计稿，未实现，`graph-service.js` 尚不存在" | **P1 已实现并提交**（commit `226489d`），`server/services/graph-service.js` 已存在，配套测试 `graph-service.test.js` / `agent-manager-p1.test.js` 均在 | **✅ 已改**。27-P2 文件头「前置」已写明「P1 虚拟引用寻址已实现（commit `226489d`）」；27-P3/P4 §九「与 P1」条写明「无直接依赖，已实现（commit `226489d`）」 | -| 2 | [27-P3/P4](./27-p3-p4-work-graph-console.md) §三.1 | "`runProject` 目前直接 501" | **已完整实现**（`loop-controller.js:576`），含 Kahn 分波、L2 闸门、Triager 四分支、预算熔断 | **✅ 已改**。27-P3/P4 §三.1 现为「`runProject()`（行 576，**已完整实现**…）」，并追加了「波内实际是串行」的补充观察 | +| 1 | [27-P2](../../done/system-design/27-p2-org-graph.md) §九、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §九 | "P1 目前仍是设计稿，未实现，`graph-service.js` 尚不存在" | **P1 已实现并提交**（commit `226489d`），`server/services/graph-service.js` 已存在，配套测试 `graph-service.test.js` / `agent-manager-p1.test.js` 均在 | **✅ 已改**。27-P2 文件头「前置」已写明「P1 虚拟引用寻址已实现（commit `226489d`）」；27-P3/P4 §九「与 P1」条写明「无直接依赖，已实现（commit `226489d`）」 | +| 2 | [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §三.1 | "`runProject` 目前直接 501" | **已完整实现**（`loop-controller.js:576`），含 Kahn 分波、L2 闸门、Triager 四分支、预算熔断 | **✅ 已改**。27-P3/P4 §三.1 现为「`runProject()`（行 576，**已完整实现**…）」，并追加了「波内实际是串行」的补充观察 | | 3 | [27-P2](../../done/system-design/27-p2-org-graph.md) §4.1 | 提议建部分唯一索引 `idx_org_graph_nodes_company_role_active`（带 `WHERE status='active'`），但没说要先 DROP 旧索引 | **`graph-service.js` 已经建了全量唯一索引 `idx_org_graph_nodes_company_role`**（无 WHERE），必须先 DROP | **✅ 已改且已落地代码**。27-P2 §4.1 的 SQL 现以 `DROP INDEX IF EXISTS idx_org_graph_nodes_company_role;` 开头；`graph-db.js:59-60` 已实现这条 DROP + 重建 | -| 4 | [27-P3/P4](./27-p3-p4-work-graph-console.md) §四.B.2、§五 T3 | 把"手写分层布局算法，不引入图形库"当作**新**工作量 | `web/src/components/devloop/UnitsDAG.vue` **已实现** SVG + Kahn 分波布局 | **✅ 已改**。27-P3/P4 §三.5 新增「前端 DAG 已实现，扩展而非重写」一节；§四.B.2 与 §五 T3 均改为「**扩展 `UnitsDAG.vue`**」，并把新增工作量收窄到「subgraph 角标 + backward 曲线路由 + 循环徽标」三块 | +| 4 | [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.B.2、§五 T3 | 把"手写分层布局算法，不引入图形库"当作**新**工作量 | `web/src/components/devloop/UnitsDAG.vue` **已实现** SVG + Kahn 分波布局 | **✅ 已改**。27-P3/P4 §三.5 新增「前端 DAG 已实现，扩展而非重写」一节；§四.B.2 与 §五 T3 均改为「**扩展 `UnitsDAG.vue`**」，并把新增工作量收窄到「subgraph 角标 + backward 曲线路由 + 循环徽标」三块 | ### 此外建议（复核结论） @@ -396,7 +396,7 @@ RESEARCH → PLAN → EXECUTE → VERIFY | 原建议 | 为什么作废 | 被什么取代 | |---|---|---| -| **27-P3/P4：补 `node_kind='org_node'`** —— 即在节点表上开一个专门表示「这是个 org 节点」的枚举值 | 它的前提是「org graph 和 work graph 是两种不同的东西，引擎要靠节点上的一个标记去分辨」。**[27-REQ](./27-requirement.md) R-15.4 推翻了这个前提**：两层图是同一种东西在不同层级的递归，引擎泛化后**不为它们各写一套**，也就不需要在节点粒度上区分层级 | **`graph_runs.graph_kind IN ('org','work')`**（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A.2）。层级信息挂在**运行时的 run 上**，不挂在定义层的节点上；`graph_run_nodes.def_node_id` 按所属 run 的 `graph_kind` 解释到 `org_graph_nodes` 还是 `work_graph_nodes`。
节点粒度上真正存在的枚举是**另一个东西**——`node_kind IN ('agent_call','subgraph')`（§四.D.0），它区分的是**执行语义**（调一次 agent / 起一张子图并等它收敛），**不是**图的层级。org graph 的节点恰好全都是 `subgraph`，但这是推论，不是定义 | +| **27-P3/P4：补 `node_kind='org_node'`** —— 即在节点表上开一个专门表示「这是个 org 节点」的枚举值 | 它的前提是「org graph 和 work graph 是两种不同的东西，引擎要靠节点上的一个标记去分辨」。**[27-REQ](./27-requirement.md) R-15.4 推翻了这个前提**：两层图是同一种东西在不同层级的递归，引擎泛化后**不为它们各写一套**，也就不需要在节点粒度上区分层级 | **`graph_runs.graph_kind IN ('org','work')`**（[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.A.2）。层级信息挂在**运行时的 run 上**，不挂在定义层的节点上；`graph_run_nodes.def_node_id` 按所属 run 的 `graph_kind` 解释到 `org_graph_nodes` 还是 `work_graph_nodes`。
节点粒度上真正存在的枚举是**另一个东西**——`node_kind IN ('agent_call','subgraph')`（§四.D.0），它区分的是**执行语义**（调一次 agent / 起一张子图并等它收敛），**不是**图的层级。org graph 的节点恰好全都是 `subgraph`，但这是推论，不是定义 | > ⚠️ **不要照这条作废建议去加字段**。设计里不存在 `node_kind='org_node'` 这个取值，加了会与 `graph_kind` 形成两套互相矛盾的层级标记，且 `node_kind` 的 CHECK 约束（`IN ('agent_call','subgraph')`）会直接拒绝它。 diff --git a/docs/todo/system-design/27-example-dev-company-walkthrough.md b/docs/todo/system-design/27-example-dev-company-walkthrough.md index c7c743d..1fa6e1f 100644 --- a/docs/todo/system-design/27-example-dev-company-walkthrough.md +++ b/docs/todo/system-design/27-example-dev-company-walkthrough.md @@ -70,7 +70,7 @@ 边是 `success` / `fail` 执行流边，与 work graph 的边完全同构——**同一套 schema、同一个执行引擎、同一个控制台 UI 在两层复用**。 > 上面是 **P2 形态**（fail 只有一条兜底边）。P3 给边加了可空的 `fail_reason` -> （[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2），`system/org-graph-templates/dev.json` 的骨架因此 +> （[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2），`system/org-graph-templates/dev.json` 的骨架因此 > 多一条 `org-validator --fail[input_underspecified]--> org-planner`：归因判定是"规划给的约束不够"时退回重新规划， > 其余一切情况仍走这里画的这条无 `fail_reason` 的兜底边退回 `org-coder`。本文后续流程只用到兜底边，不受影响。 @@ -178,7 +178,7 @@ brd-planning → prd-planning → sdd-planning ─┬→ goal-test-data ── ``` - **fan-out**：三个 unit 无依赖，并行（DevLoop 的 `_groupUnitsByWave()` Kahn 分波已实现，🔴 但波内目前是串行的，`loop-controller.js:609` 注释 `// 串行跑`） -- **fan-in**：`integrate` 节点等三条支线全绿才能进入 `ready`（多入边 = 汇合点，全部满足才推进，[27-P3/P4](./27-p3-p4-work-graph-console.md) §D.1） +- **fan-in**：`integrate` 节点等三条支线全绿才能进入 `ready`（多入边 = 汇合点，全部满足才推进，[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §D.1） - 每个 `unittest` 失败 → 打回对应的 unit 重写 = **L1 循环**，`retry_budget=5` **假设 `integration-test` 失败了**：`html-render` 拿到的分段结构和 `md-parser` 产出的不一致。 diff --git a/docs/todo/system-design/27-goal-contract-format.md b/docs/todo/system-design/27-goal-contract-format.md index e8c96f7..a2e08a2 100644 --- a/docs/todo/system-design/27-goal-contract-format.md +++ b/docs/todo/system-design/27-goal-contract-format.md @@ -1,6 +1,6 @@ # 27-T0. 验收契约格式 —— `acceptance.json` 与执行器 -> **所属**: [27-P3/P4](./27-p3-p4-work-graph-console.md) §五 **阶段 0**（T0），需求源头 [27-REQ](./27-requirement.md) R-15.6 +> **所属**: [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §五 **阶段 0**（T0），需求源头 [27-REQ](./27-requirement.md) R-15.6 > **实现**: `server/services/goal-contract.js` > **配套**: [27-E2E](./27-e2e-task-execution-flow.md) §十一（三个验收产出节点）、`docs/prd/newfunction/_spec/sdd-model.md` M-6/M-7/M-8（形态来源） > **日期**: 2026-08-16（2026-08-17 R19-B：契约落点归并到 `tasks/{taskId}/` 并进产物索引，见 §一 / §八） @@ -9,7 +9,7 @@ ## 〇、这份文档定死什么、放开什么 -[27-P3/P4](./27-p3-p4-work-graph-console.md) §八.9 给的边界很明确——阶段 0 的契约格式一旦定错，阶段 A 的 schema 要返工，所以 +[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §八.9 给的边界很明确——阶段 0 的契约格式一旦定错，阶段 A 的 schema 要返工，所以 > 先把**存储位置**和**与 `output_ref` / `artifacts/` 的关联方式**定死，格式内部细节允许后续演进。 @@ -30,7 +30,7 @@ ## 一、存储位置（稳定面） -沿用 [27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A.5 已定的产物布局，本文档补上 `verdicts/` 这一格；契约本体按 [27-P4](../../done/system-design/27-p4-parallel-and-artifacts.md) §4.6 的目录约定归并到 `tasks/{taskId}/`（**R19-B**）： +沿用 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.A.5 已定的产物布局，本文档补上 `verdicts/` 这一格；契约本体按 [27-P4](../../done/system-design/27-p4-parallel-and-artifacts.md) §4.6 的目录约定归并到 `tasks/{taskId}/`（**R19-B**）： ``` data/companies/{cid}/ @@ -98,7 +98,7 @@ tasks/{taskId}/acceptance.json ─readContract┼──▶ executeContract ─ ## 二bis、接进生产路径：为什么是 agent 工具层，不是引擎钩子（R5-F3） -T0 交付后有四轮时间里，全仓库唯一提到 `goal-contract.js` 的是 `graph-engine.js:331` 的一句注释——实现完整、零调用方、零单测，[27-P3/P4](./27-p3-p4-work-graph-console.md) §六 验收 1 从未被执行过。接线时有两个位置可选，选了后者： +T0 交付后有四轮时间里，全仓库唯一提到 `goal-contract.js` 的是 `graph-engine.js:331` 的一句注释——实现完整、零调用方、零单测，[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §六 验收 1 从未被执行过。接线时有两个位置可选，选了后者： | | ① 引擎在节点收尾时自动跑 | ② **validator agent 通过工具（CLI）调用** ← 选这个 | |---|---|---| diff --git a/docs/todo/system-design/27-graph-agent-architecture.md b/docs/todo/system-design/27-graph-agent-architecture.md index 5e9f5a2..4b1828f 100644 --- a/docs/todo/system-design/27-graph-agent-architecture.md +++ b/docs/todo/system-design/27-graph-agent-architecture.md @@ -2,7 +2,7 @@ > **版本**: v0.3（P0/P1 已实现；Org Graph 建模在 v0.3 修正为 company 级 workflow） > **日期**: 2026-08-15 -> **状态**（2026-09-08 校准）: P0 ✅ 已实现（`graph-db.js` + `graph-seed-service.js`，见第七节）；P1 ✅ 已实现（commit `226489d`，`graph-service.js`）；**P2 ✅ 已实现**（设计已归档 [27-P2](../../done/system-design/27-p2-org-graph.md)）；**P3 主体 ✅ 已实现**（`c3abf4a` 起七轮，见 [27-P3/P4](./27-p3-p4-work-graph-console.md) §十 实现记录）；**P3 收尾 ✅ 已完成并归档**（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md) 五批 + §十七 清尾，2026-08-20 真跑走通返工闭环）；**P3B 真跑跑道 ✅ 九条验收全部验完**（[27-P3B](../../done/system-design/27-p3b-real-run-runway.md) §六quater，2026-09-08 隔离 worktree 真跑验掉最后一条验收 9：org 层回退边真的指向了 subgraph 节点）；**P4 ✅ 已彻底收口**（2026-09-08，[27-P4](../../done/system-design/27-p4-parallel-and-artifacts.md) 阶段 A/B/C 全部完成，仅 T5 账户欠费门因外部计费接口未接而悬置） +> **状态**（2026-09-08 校准）: P0 ✅ 已实现（`graph-db.js` + `graph-seed-service.js`，见第七节）；P1 ✅ 已实现（commit `226489d`，`graph-service.js`）；**P2 ✅ 已实现**（设计已归档 [27-P2](../../done/system-design/27-p2-org-graph.md)）；**P3 主体 ✅ 已实现**（`c3abf4a` 起七轮，见 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §十 实现记录）；**P3 收尾 ✅ 已完成并归档**（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md) 五批 + §十七 清尾，2026-08-20 真跑走通返工闭环）；**P3B 真跑跑道 ✅ 九条验收全部验完**（[27-P3B](../../done/system-design/27-p3b-real-run-runway.md) §六quater，2026-09-08 隔离 worktree 真跑验掉最后一条验收 9：org 层回退边真的指向了 subgraph 节点）；**P4 ✅ 已彻底收口**（2026-09-08，[27-P4](../../done/system-design/27-p4-parallel-and-artifacts.md) 阶段 A/B/C 全部完成，仅 T5 账户欠费门因外部计费接口未接而悬置） > > ⚠️ 这一行是别人判断「哪些文档能从 `docs/todo/` 搬去 `docs/done/`」的依据 —— 它过期会连累后面每一次迁移判断，改阶段状态时请顺手更新它。 > **命名**: 新增 agent id / 表名 / 字段名前先读 [27-NAMING 命名规范](./27-naming-conventions.md) @@ -119,7 +119,7 @@ system/agents/{agentId}/ 4. **回退边必须显式经过 loop-validator 节点**——即"节点A --fail--> loop-validator --> 节点B"，而不是"节点A --fail(隐藏回退属性)--> 节点B"。这是画图时的**结构要求**，不是引擎运行时才附加的隐藏逻辑。 5. **执行前结构校验**：图规划完成后、进入执行前，引擎做一次静态校验——任何边如果目标节点在图中已存在其他指向它的边（即会构成"回到历史节点"），但没有经过 loop-validator 节点，直接拒绝这张图，不进入执行。类比现有 `npm run spec:check` 的"结构先校验，再允许跑"模式。这是对"planning agent 应该自觉画上 validator"这条规则的**引擎级兜底**，防止规划疏漏导致死循环绕过审计。 -> ⚠️ **上面第 4、5 点已被 [27-P3/P4](./27-p3-p4-work-graph-console.md) v0.3 §四.D.2.1 改写**：`loop_validator` 节点由「回退边必须经过」的**强制结构要求**降级为**可选增强**（理由：org graph 是 `orggraph-planning` 生成的「这家公司有哪些角色」，往里塞基础设施节点会污染这个语义，而引擎泛化后两层用同一套校验）。熔断改由**引擎无条件的整数计数**承担，落地的写入前校验是**五项**：`acyclic` / `single-entry` / `reachable` / `backward-labeled` / `fail-fallback-edge`——**没有一项要求经过 loop-validator**。本节保留原文作为设计演进记录，实现以 27-P3/P4 为准。 +> ⚠️ **上面第 4、5 点已被 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) v0.3 §四.D.2.1 改写**：`loop_validator` 节点由「回退边必须经过」的**强制结构要求**降级为**可选增强**（理由：org graph 是 `orggraph-planning` 生成的「这家公司有哪些角色」，往里塞基础设施节点会污染这个语义，而引擎泛化后两层用同一套校验）。熔断改由**引擎无条件的整数计数**承担，落地的写入前校验是**五项**：`acyclic` / `single-entry` / `reachable` / `backward-labeled` / `fail-fallback-edge`——**没有一项要求经过 loop-validator**。本节保留原文作为设计演进记录，实现以 27-P3/P4 为准。 ### 3.5 Loop-Validator：死循环兜底 @@ -229,8 +229,8 @@ CREATE TABLE work_graph_edges ( | **P0 地基** ✅ | 建表 + 现有数据迁移，不改变任何现有执行路径 | `system_agents`/`org_graph_*` 表；把现有 `system/agents/` + `system/templates/` 目录扫描导入为种子数据（`system_agents` 行，`scope` 按当前所属推断） | 迁移脚本跑完，`system_agents` 表行数与现有 agent+模板目录数一致（**实际行数与本文档最初估计不同，见第七节**）；现有 `company-service.js` 行为不变（并行只读验证，已确认零改动） | | **P1 虚拟引用** | 停止文件拷贝，改为引用 | 改造 `AgentManager.getAgentConfig()` + `PromptBuilder.build()` 支持 `(agentId, companyId)` 寻址；`company-service.hire()` 改为创建 org_graph 引用节点而非 `_copyTemplate()`。细化需求与设计见 [27-P1 虚拟引用寻址](../../done/system-design/27-p1-virtual-reference.md) | 新雇佣的 agent 不再产生文件拷贝，调用时能正确拼装公共+私有上下文；旧公司（仍是拷贝模式）继续可跑，不强制迁移存量数据 | | **P2 Org Graph** | `company.json.agents[]` 迁移为图结构 | `org_graph_nodes`/`edges` 落地；HR/CEO 招聘走新表。细化需求与设计见 [27-P2 Org Graph 落地](../../done/system-design/27-p2-org-graph.md) | 现有 Company Dashboard 前端能正确读出 org graph 并渲染（哪怕暂时按列表展示） | -| **P3+P4 图执行引擎与执行控制台**（**两个 Phase 已合并**） | **一套引擎同时驱动 org graph 与 work graph**（R-15.4 引擎泛化），带回退与熔断 | 定义层 `work_graphs`/`work_graph_nodes`/`work_graph_edges` + **两层共用的运行时层** `graph_runs`/`graph_run_nodes`/`graph_run_loop_records`（共五张新表）；`graph-engine.js` 的 `advanceOne(runId)` 幂等推进原语 + 两种 node executor（`agent_call` / `subgraph`）；五个控制操作（启动 / 下一步 / 暂停 / 停止 / 重试）× 手动·自动两种模式；`GraphConsole.vue` 执行控制台页面；`workgraph-planning` agent + 用户→公司任务入口。细化需求与设计见 [27-P3/P4 Work Graph 执行控制台](./27-p3-p4-work-graph-console.md) **v0.3**，落地切成**五个可独立验收的阶段**（0 验收契约 / A 引擎地基 / B 回退熔断 / C 控制台 / D 规划闭环） | 见该文档 §六 的 17 条。**核心验收点是第 6 条**：一张 `graph_kind='org'` 的图与一张 work graph 用**同一套端点、同一条代码路径**跑通「手动逐步 / 自动跑完 / 暂停恢复 / 停止」；外加第 8 条「总是失败的节点第 4 次 `force_terminated` 收敛到 `blocked`」、第 17 条「一句自然语言任务两层跑到 `completed`」 | -| ~~**P4 回退 + Loop-Validator**~~ | **已并入上一行**，不再单列 | 合并理由见 [27-P3/P4](./27-p3-p4-work-graph-console.md) §二：执行引擎一旦要支持「暂停/单步/停止/重试」这种可被外部随时打断的控制语义，「先做单向、再加回退」会让第一版状态机设计得过窄，P4 加回退时必然回来重改数据模型和主循环。**两处定案变更**：① 熔断改为**引擎无条件做的整数计数**（单边 `loop_count > 3` + run 级 `backward_count > 5` 双层硬顶），不依赖 LLM，`loop_validator` 节点由「强制」降级为**可选增强**；② 结构校验从四项扩到**五项**，新增 `fail-fallback-edge`（有 `fail` 出边的节点必须留一条 `fail_reason IS NULL` 兜底边），org / work 两层都加 | 同上 | +| ~~**P3+P4 图执行引擎与执行控制台**~~ ✅（**两个 Phase 已合并**，2026-09-09 移入 `done/`） | **一套引擎同时驱动 org graph 与 work graph**（R-15.4 引擎泛化），带回退与熔断 | 定义层 `work_graphs`/`work_graph_nodes`/`work_graph_edges` + **两层共用的运行时层** `graph_runs`/`graph_run_nodes`/`graph_run_loop_records`（共五张新表）；`graph-engine.js` 的 `advanceOne(runId)` 幂等推进原语 + 两种 node executor（`agent_call` / `subgraph`）；五个控制操作（启动 / 下一步 / 暂停 / 停止 / 重试）× 手动·自动两种模式；`GraphConsole.vue` 执行控制台页面；`workgraph-planning` agent + 用户→公司任务入口。细化需求与设计见 [27-P3/P4 Work Graph 执行控制台](../../done/system-design/27-p3-p4-work-graph-console.md) **v0.3**，落地切成**五个可独立验收的阶段**（0 验收契约 / A 引擎地基 / B 回退熔断 / C 控制台 / D 规划闭环） | 见该文档 §六 的 17 条。**核心验收点是第 6 条**：一张 `graph_kind='org'` 的图与一张 work graph 用**同一套端点、同一条代码路径**跑通「手动逐步 / 自动跑完 / 暂停恢复 / 停止」；外加第 8 条「总是失败的节点第 4 次 `force_terminated` 收敛到 `blocked`」、第 17 条「一句自然语言任务两层跑到 `completed`」 | +| ~~**P4 回退 + Loop-Validator**~~ | **已并入上一行**，不再单列 | 合并理由见 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §二：执行引擎一旦要支持「暂停/单步/停止/重试」这种可被外部随时打断的控制语义，「先做单向、再加回退」会让第一版状态机设计得过窄，P4 加回退时必然回来重改数据模型和主循环。**两处定案变更**：① 熔断改为**引擎无条件做的整数计数**（单边 `loop_count > 3` + run 级 `backward_count > 5` 双层硬顶），不依赖 LLM，`loop_validator` 节点由「强制」降级为**可选增强**；② 结构校验从四项扩到**五项**，新增 `fail-fallback-edge`（有 `fail` 出边的节点必须留一条 `fail_reason IS NULL` 兜底边），org / work 两层都加 | 同上 | | ~~**P4 并行执行与产物索引**~~ ✅（**回收编号**） | fan-out 真并发 + 产物统一索引 —— **2026-09-08 全部完成** | `advanceBatch` 批量拾取（手动模式退化为 `maxConcurrency=1`，行为与 P3 一致）；同 agent 多实例隔离（`SessionPool.getKey` 的 `scope` 参数已实际接线：`graph-engine.js` 传 `gr:{nodeRunId}`）；`advanceTree` 兄弟子 run 真并发；解除「一家公司一个 active root run」；`data/companies/{cid}/tasks/{taskId}/` 产物目录 + `graph_files` 表检索索引。细化设计见 [27-P4 并行执行与产物索引](../../done/system-design/27-p4-parallel-and-artifacts.md) | 3 个并行分支同时 running 且总墙钟明显短于串行；部分失败时 fan-in 停等且可视化「在等谁」；产物索引可从节点行 rebuild | | **P5 自我进化** | 公共记忆蒸馏机制 | 公共 `memory.md` 写入走自省校验 + git 版本化；company-scoped → public 的升级门槛复用现有 benchmark ≥95 链路 | 同一 public agent 被两家公司调用后，`memory.md` 有可观察的增量更新，且能 git revert 到升级前版本 | | **P6（~~可选~~ **应前置**）DevLoop 收编** | 统一循环逻辑 | 把 `loop-controller.js`/`unit-registry.js` 重构为 Work Graph 引擎上的一个具体图模板。⚠️ **定位修正**：端到端流程梳理后发现 DevLoop 不是"将来可选整合的边缘子系统"，而是**本架构唯一一个已经跑通的参考实现**——它的 L1/L2/L3 三层循环、四分类失败归因、分级预算熔断、`contract_hash` 闸门、DAG 分波、SSE 埋点、前端 DAG 组件都已实现或已有完整规格（`docs/prd/newfunction/_spec/`）。通用 Work Graph 引擎应当**从它抽象而来**，而不是平行发明后再回头合并。详见 [27-E2E](./27-e2e-task-execution-flow.md) §二结论 2 | DevLoop 现有测试套件（`server/tests/devloop/**`）在新引擎上全部通过，无需单独维护两套循环代码 | @@ -267,5 +267,5 @@ P0 阶段的处理方式是**迁移脚本层面的临时保护**：`system_agent - **[27-EXAMPLE 参考场景走查](./27-example-dev-company-walkthrough.md)** — 把上面那套架构在一家具体公司上跑一遍数（含各阶段真实形态的 JSON / 图 / 成本估算 / 断点清单）。实现时的靶子与端到端验收场景。 - [27-P1 虚拟引用寻址](../../done/system-design/27-p1-virtual-reference.md) — 已实现（commit `226489d`） - [27-P2 Org Graph 落地](../../done/system-design/27-p2-org-graph.md) — 设计稿 -- [27-P3/P4 Work Graph 执行控制台](./27-p3-p4-work-graph-console.md) — 已实现（commit `c3abf4a`） +- [27-P3/P4 Work Graph 执行控制台](../../done/system-design/27-p3-p4-work-graph-console.md) — ✅ 已实现（commit `c3abf4a`），已彻底收口（2026-09-09） - [27-P4 并行执行与产物索引](../../done/system-design/27-p4-parallel-and-artifacts.md) — ✅ 已彻底收口（2026-09-08） diff --git a/docs/todo/system-design/27-naming-conventions.md b/docs/todo/system-design/27-naming-conventions.md index c94f104..f01fa26 100644 --- a/docs/todo/system-design/27-naming-conventions.md +++ b/docs/todo/system-design/27-naming-conventions.md @@ -77,7 +77,7 @@ ops.json org-planner → org-monitor → org-validator | **org graph 节点** | `org-planner` / `org-coder` / `org-validator` | ✅ 带 `org-` | | **work graph 节点** | `org-coder-validator` / `org-planner-validator` | ✅ 带父节点全名 | -落到 schema 上就是两个字段（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A）：`node_name` 存节点名（图内唯一），`system_agent_id` 存本体名（跨图复用）。 +落到 schema 上就是两个字段（[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.A）：`node_name` 存节点名（图内唯一），`system_agent_id` 存本体名（跨图复用）。 **为什么本体不带前缀**：禁止裸用 `validator` 的理由是「一家公司内两个节点不能重名」——该理由针对**节点**，不针对**本体**。本体若被迫带领域前缀，`coder-validator` 会复制成 `org-coder-validator` / `content-coder-validator` 多份，与 [27-P1](../../done/system-design/27-p1-virtual-reference.md)「同一份本体、多处引用、各自私有语境」直接冲突。 @@ -126,7 +126,7 @@ ops.json org-planner → org-monitor → org-validator R-16 把「失败该怪谁」从 validator 手里拆出来，交给一个专职的**归因节点**：`org-validator` 自己的 work graph 里 第一个节点就是它，产出 `fail_reason` + `remediation_note`，透传回 org 层作为选边依据 -（见 [27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2 / §四.D.3）。 +（见 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2 / §四.D.3）。 按本节的命名轴，它是**work graph 层的节点**——它活在 `org-validator` 这个 org node 的 work graph 里， 不是 org graph 上的节点，因此不带 `org-` 前缀，而是随父节点得名。 @@ -148,7 +148,7 @@ R-16 把「失败该怪谁」从 validator 手里拆出来，交给一个专职 > 🔁 **改名的影响面**（R-17.2 落地范围）：`system/templates/validator-triager/`（目录 + 内容自称）、 > `system/templates/_registry.json` 条目、`system/templates/org-validator/` 的节点名引用、 > `system/work-graph-templates/validator.json` 的 `nodeName` / `systemAgentId` / 边端点、 -> 本文档本节、[27-P3/P4](./27-p3-p4-work-graph-console.md) 全文，以及 `graph-engine.js` 的 +> 本文档本节、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 全文，以及 `graph-engine.js` 的 > `ATTRIBUTION_NODE_NAME` 常量与 `node.reflection` timeline 事件名（引擎侧另行改）。 > **这七处必须同时改**——节点名与 `systemAgentId` 与引擎常量三者只要有一处不同步， > 归因产出就会静默落不到透传路径上（27-P3/P4 §十 的「四环漏一环」缺陷模式）。 diff --git a/docs/todo/system-design/27-requirement.md b/docs/todo/system-design/27-requirement.md index 89fcf9c..f33f04a 100644 --- a/docs/todo/system-design/27-requirement.md +++ b/docs/todo/system-design/27-requirement.md @@ -47,7 +47,7 @@ > 我们需要一个新的页面，展示公司的 org graph 和每一个 org node 运行的 work graph，这个需求也需要设计一下，这个界面还需要设计一下 MVCP，数据库设计，界面设计，有启动，下一步，暂停，停止，重试这样的操作按钮，还需要展示每一个节点的运行日志，边的输入输出，loop 的划线，这些展示，还有主流程如何处理，异常流程如何处理，下钻的 sub agent 的流程如何处理和展示。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) 全文（§四 按 MVCP 四象限组织） +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 全文（§四 按 MVCP 四象限组织） **关键澄清**：此处的 "MVCP" 经确认是 **Model-View-Control-Process**，即仓库既有 SDD 的四象限文档格式（`docs/prd/newfunction/_spec/sdd-{model,view,control,process}.md`），不是 MVP（最小可行范围）。 --- @@ -56,7 +56,7 @@ > 对，而且运行有自动化和手动化两个选择，如果是手动，则 org graph，work graph 的执行是需要在界面上点击下一步下一步来完成，如果是自动则是授权自动从头到尾自动执行，一个节点完成则自动跳转到下一个节点执行 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.C（`execution_mode ∈ {manual, auto}`，两者共用同一个 `advanceOne()` 原语，区别只在谁触发下一次调用） +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.C（`execution_mode ∈ {manual, auto}`，两者共用同一个 `advanceOne()` 原语，区别只在谁触发下一次调用） --- @@ -242,7 +242,7 @@ 本条确认讨论的是**后者**。下文 R-15.2 起全部属于 27 系列。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) 全文。 +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 全文。 ### R-15.2 · `workgraph-planning` 是全局通用 agent @@ -250,7 +250,7 @@ **澄清了什么**：每个 org node 接到任务时不是各自带一份规划能力，而是**都调同一个全局 `workgraph-planning` 本体**，靠记忆分区区分它在不同 org node / 不同公司下的语境。与 R-9.2 元 agent 继承、[27-P1](../../done/system-design/27-p1-virtual-reference.md) 虚拟引用寻址一致——agent 池不随 org node 数量膨胀。 -**落点**：[27-NAMING](./27-naming-conventions.md) §二（该条目已在表内）、[27-P3/P4](./27-p3-p4-work-graph-console.md) 阶段 D。 +**落点**：[27-NAMING](./27-naming-conventions.md) §二（该条目已在表内）、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 阶段 D。 ### R-15.3 · validator 分两个层级，各有全局本体 @@ -277,31 +277,31 @@ **`org-validator` 调 sub agent 不需要新机制**：`org-validator` 本身是一个 org node，按定义有自己的 work graph，`benchmark-validator` / `testdata-validator` 就是这张 work graph 的节点，落在已有的递归模型里，引擎不加分支。 -**连带影响**：R-9.3「planner 生成、validator 执行」的两个角色现在分属**两个不同的 org node**——`goal-benchmark` / `goal-test-data` / `goal-test-script` 在 `org-planner` 的 work graph 里产出，由 `org-validator` 这个 org node 消费。因此需要**跨 org node 的产物传递机制**，[27-P3/P4](./27-p3-p4-work-graph-console.md) 现有的 `output_ref`（节点内产物指针）不够。 +**连带影响**：R-9.3「planner 生成、validator 执行」的两个角色现在分属**两个不同的 org node**——`goal-benchmark` / `goal-test-data` / `goal-test-script` 在 `org-planner` 的 work graph 里产出，由 `org-validator` 这个 org node 消费。因此需要**跨 org node 的产物传递机制**，[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 现有的 `output_ref`（节点内产物指针）不够。 -**落点**：[27-NAMING](./27-naming-conventions.md) §三 + 新增 validator 命名轴、[27-P2](../../done/system-design/27-p2-org-graph.md) §4.6 三个模板、[27-P3/P4](./27-p3-p4-work-graph-console.md)。 +**落点**：[27-NAMING](./27-naming-conventions.md) §三 + 新增 validator 命名轴、[27-P2](../../done/system-design/27-p2-org-graph.md) §4.6 三个模板、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md)。 ### R-15.4 · 引擎泛化，定义层与运行时层分离 **选项确认**，非原话。给出的三个选项是：引擎泛化接受表名参数（选中）/ org graph 执行时物化成 work_graph 实例 / 先只做 work graph 把 org graph 执行推到 P5。 -**推翻了什么**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A 的注释专门为「不拆定义表和实例表」辩护，理由是 work graph「规划完即执行、执行完即归档」，定义即实例。**该前提在 org graph 也要被执行之后失效**——org graph 是建公司时生成一次、活整个公司生命周期的长期定义，一份定义要被跑很多次（每来一个任务跑一遍）。 +**推翻了什么**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.A 的注释专门为「不拆定义表和实例表」辩护，理由是 work graph「规划完即执行、执行完即归档」，定义即实例。**该前提在 org graph 也要被执行之后失效**——org graph 是建公司时生成一次、活整个公司生命周期的长期定义，一份定义要被跑很多次（每来一个任务跑一遍）。 **定案**：定义层保留两套（`org_graph_*` 长期 / `work_graph_*` 一次性），运行时层统一为一套 `graph_runs` + `graph_run_nodes`，引擎只操作运行时层，定义从哪来由 `graph_runs.graph_kind` 决定。三层下钻改用 `parent_run_id` 一条链（取代 `parent_node_id`）；任务级总预算（[27-E2E](./27-e2e-task-execution-flow.md) §7.1）挂 root run，子 run 上溯扣同一个池；暂停/停止沿同一条链向下级联（§7.5）。 **连带定案**：org node 与 work node 的执行语义不同——前者是「起一张子图并等它收敛」（子 run `completed` → success，`blocked` → fail），后者是「一次 agent 调用」。引擎需要 `agent_call` / `subgraph` 两种 node executor。org 层回退**不**强制插 `loop_validator` 节点（会污染「这家公司有哪些角色」的语义），改由引擎对 `edge_kind='backward'` 的边统一计数 + 硬顶熔断。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A / §四.D。 +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.A / §四.D。 ### R-15.5 · P3 范围含 `workgraph-planning` + 任务入口 **选项确认**，非原话。 -**推翻了什么**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §一非目标把 `workgraph-planning` 排除在外，代价是该文档 §八.5 自己承认「只能用手写测试数据构造图，不能端到端验证从一句自然语言目标到一张可执行的图这条链路」。且 [27 总纲](./27-graph-agent-architecture.md) §六本来就把 `workgraph-planning` 列为 P3 交付物。任务入口（用户 → 公司）是 [27-E2E](./27-e2e-task-execution-flow.md) §四 #7 标注的「完全空白」，没有它图没有来源。 +**推翻了什么**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §一非目标把 `workgraph-planning` 排除在外，代价是该文档 §八.5 自己承认「只能用手写测试数据构造图，不能端到端验证从一句自然语言目标到一张可执行的图这条链路」。且 [27 总纲](./27-graph-agent-architecture.md) §六本来就把 `workgraph-planning` 列为 P3 交付物。任务入口（用户 → 公司）是 [27-E2E](./27-e2e-task-execution-flow.md) §四 #7 标注的「完全空白」，没有它图没有来源。 **定案**：两者都收进 P3，作为最后一个阶段（前面的阶段全部不起 LLM、可独立验收，与 [27-P2](../../done/system-design/27-p2-org-graph.md) §五「三个可独立验收的阶段」同一套切法）。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §一非目标（两条作废）、§五任务划分。 +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §一非目标（两条作废）、§五任务划分。 ### R-15.6 · 验收契约提到最前面 @@ -311,7 +311,7 @@ **定案**：P3 新增一个前置阶段，先定 `goal-benchmark` / `goal-test-data` / `goal-test-script` 三种产物的统一契约格式并建执行器，再动引擎。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §五任务划分、[27-E2E](./27-e2e-task-execution-flow.md) §十一。 +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §五任务划分、[27-E2E](./27-e2e-task-execution-flow.md) §十一。 --- @@ -319,9 +319,9 @@ > org-validator 判定任务未达成时，退回 code-coder（实现有问题）还是 code-planner（规划有问题）? 这个org-validator 会有自己的 work graph 里的 subagent 决定，它首先需要有一个 validator-reflection subagent 来判断当前的 bug 的源头是哪个 agent 的哪个 skill 的问题，还是哪个 agent 的输入约束不够的问题，还是哪个 agent 的执行问题，判断完原因，才知道是先改 skill，还是直接让某个 agent 直接+bug context 描述直接重做。 所以回退的边是多个的，不是一个的，在回放的时候才知道用哪个边实现回退。你觉得如何？ -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2（选边）、§四.D.0（子 run 回写透传）、§四.D.2.1（熔断） +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2（选边）、§四.D.0（子 run 回写透传）、§四.D.2.1（熔断） -**这条回答了什么**：[27-P3/P4](./27-p3-p4-work-graph-console.md) v0.3 §八.1 把「一个节点有多条 fail 边时走哪条」列为本版最需要确认的 open question，本条关闭它。 +**这条回答了什么**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) v0.3 §八.1 把「一个节点有多条 fail 边时走哪条」列为本版最需要确认的 open question，本条关闭它。 **关键结构**：归因**不是**失败节点自己顺手吐一个 reason，而是 `org-validator` 自己 work graph 里排第一位的一个专职节点 `validator-reflection`。这与 DevLoop 的既有分工同构——Integrator 判定集成失败、BugTriager 单独归因，是两个不同 agent，理由是同一个 agent 既当裁判又当法医容易把「我判失败」和「我认为该怪谁」混成一次输出。 @@ -336,7 +336,7 @@ ⚠️ **「skill 问题」这一支落在 P3 的非目标里**（L4 是三级恢复中最贵、爆炸半径最大的一级，[27-E2E](./27-e2e-task-execution-flow.md) §十 建议最后做）。**建议**：v1 保留 `skill_defect` 这个归因取值让 reflection 照常判定（数据先攒着，归因体系一次成型），但动作降级为「挂起等人工」，不自动触发 L4。`infra_flake` 建议补上——纯引擎逻辑、近乎零成本，不补则超时会被误判成执行问题、白烧一轮预算。 -**对 schema 的要求**：子 run 收敛时不能只回写 success/fail，**还要把 `fail_reason` 和 `remediation_note` 一起透传回父节点**——因为决定走哪条边的是子图里的 reflection 节点，不是失败节点本身。[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.0 原表只写了「子 run completed → success；blocked/failed → fail」，缺这条透传。 +**对 schema 的要求**：子 run 收敛时不能只回写 success/fail，**还要把 `fail_reason` 和 `remediation_note` 一起透传回父节点**——因为决定走哪条边的是子图里的 reflection 节点，不是失败节点本身。[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.D.0 原表只写了「子 run completed → success；blocked/failed → fail」，缺这条透传。 **本条带出的一个熔断漏洞**：v0.3 §四.D.2.1 按 `(run_id, edge_id)` 计数、硬顶 3，前提是一个节点只有一条回退边。多条回退边各自计数后，**硬顶实际变成 3×N**——reflection 只要每次归因到不同 agent、走不同的边，就永远撞不到任何一个计数器的顶。这是 [27-E2E](./27-e2e-task-execution-flow.md) §7.1「每级都重置下一级计数器则没有终止条件」的同型变体。**修法：双层计数**，单边计数（防同一路径死循环）+ `graph_runs.backward_count` 的 run 级总回退计数（防「换个借口继续退」），任一撞顶即 `force_terminated`。这与任务级总预算是两回事——预算管花了多少钱，这个管绕了多少圈，两者都要。 @@ -354,18 +354,18 @@ R-16 结尾留了两处待确认，本条给出定案。**两条都推翻了我 **代价是明知的**（R-16 里已列为该方案的坏处，本条接受）：破坏层级封装；控制台「暂停 / 单步」作用于哪一层的语义会变含糊，需要在 UI 上显式表达。 -**对已有实现的影响**：[27-P3/P4](./27-p3-p4-work-graph-console.md) v0.3 与首批实现（commit `c3abf4a`）都是按 org node 粒度做的，**本条要求返工**： +**对已有实现的影响**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) v0.3 与首批实现（commit `c3abf4a`）都是按 org node 粒度做的，**本条要求返工**： | 面 | 现状（org node 粒度） | 定案后（work graph node 粒度） | |---|---|---| | 回退目标 | org 边上的 `to_node_id`，指向一个 org node | 需要一个**跨层节点地址**（org node + 其 work graph 内的具体 node） | | 重跑范围 | 该 org node **整张 work graph 重跑**（起新子 run） | 复用既有 work graph 定义，只重置被点名的 node | -| 下游处理 | 整张图重来，无所谓 | 按 `contract_hash` 的 added/changed/removed/**unchanged** 四分类决定级联——已有机制，正好复用（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.C 末段） | +| 下游处理 | 整张图重来，无所谓 | 按 `contract_hash` 的 added/changed/removed/**unchanged** 四分类决定级联——已有机制，正好复用（[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.C 末段） | | 子 run | 每次回退新建一张 | 复用旧子 run，节点 `attempt+1` | ⚠️ **与已修缺陷的交互，返工时必须复核**：第二轮修掉的「subgraph 重跑不起新子 run 导致永久死锁」，修法正是「每次回退都新建子 run 并清空 `child_run_id`」。改成复用旧子 run 之后，那个死锁的原始成因（幂等守卫读到上一轮终态子 run 而直接返回 pending）会以另一种形式回来。返工时要重新设计幂等判据，并保证 `graph-engine.test.js` 里那条「回退后 subgraph 节点重跑」的用例仍然成立（可能需要按新语义重写该用例的期望——**这是唯一允许改测试期望的情形，因为语义本身变了**，且必须在提交信息里写明）。 -**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2 / §四.D.3 / §四.A.2（跨层地址的存储形态）/ §四.B（控制台层级语义）、§八 第 1 条（关闭）。 +**落点**：[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2 / §四.D.3 / §四.A.2（跨层地址的存储形态）/ §四.B（控制台层级语义）、§八 第 1 条（关闭）。 ### R-17.2 · `validator-reflection` 改名 `validator-triager` @@ -373,16 +373,16 @@ R-16 结尾留了两处待确认，本条给出定案。**两条都推翻了我 **理由**：它做的是**归因**不是**判定**，`triager` 与 DevLoop 已经跑通的 BugTriager 对齐，语义更准。 -**影响面**（纯改名，但铺得较开）：`system/templates/validator-reflection/` 目录、`system/templates/_registry.json` 条目、`org-validator` work graph 骨架里的节点名、`graph-engine.js` 里读归因产出的相关标识与注释（如 `resolveReflectionFile` / `readNodeProduct` 的 `node.reflection` timeline 事件名）、[27-NAMING](./27-naming-conventions.md) 的 validator 命名轴说明、[27-P3/P4](./27-p3-p4-work-graph-console.md) 全文、本文档 R-16。 +**影响面**（纯改名，但铺得较开）：`system/templates/validator-reflection/` 目录、`system/templates/_registry.json` 条目、`org-validator` work graph 骨架里的节点名、`graph-engine.js` 里读归因产出的相关标识与注释（如 `resolveReflectionFile` / `readNodeProduct` 的 `node.reflection` timeline 事件名）、[27-NAMING](./27-naming-conventions.md) 的 validator 命名轴说明、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 全文、本文档 R-16。 R-16 正文中的原话引用**保留 `validator-reflection` 的用词不改**（照搬原则），本条作为后续变更记录。 上方 R-16 与本节以外的地方读到 `validator-reflection`，一律按本条理解为 `validator-triager` 的历史名。 -**落点**：[27-NAMING](./27-naming-conventions.md)、[27-P3/P4](./27-p3-p4-work-graph-console.md)、`system/templates/`。 +**落点**：[27-NAMING](./27-naming-conventions.md)、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md)、`system/templates/`。 -**落地记录（第五轮）**：引擎外的改名已完成——`system/templates/validator-triager/`（目录 + 内容自称）、`_registry.json` 条目、`system/templates/org-validator/` 的节点名引用、`system/work-graph-templates/validator.json` 的 `nodeName`/`systemAgentId`/边端点、[27-NAMING](./27-naming-conventions.md) §3.5（该节标题与「两处待定案」表也一并更新，只剩前缀那一处未定案）、[27-P3/P4](./27-p3-p4-work-graph-console.md) 全文（含 §八.2 关闭）。引擎内的 `ATTRIBUTION_NODE_NAME` 常量与 `node.reflection` timeline 事件名另行改。 +**落地记录（第五轮）**：引擎外的改名已完成——`system/templates/validator-triager/`（目录 + 内容自称）、`_registry.json` 条目、`system/templates/org-validator/` 的节点名引用、`system/work-graph-templates/validator.json` 的 `nodeName`/`systemAgentId`/边端点、[27-NAMING](./27-naming-conventions.md) §3.5（该节标题与「两处待定案」表也一并更新，只剩前缀那一处未定案）、[27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) 全文（含 §八.2 关闭）。引擎内的 `ATTRIBUTION_NODE_NAME` 常量与 `node.reflection` timeline 事件名另行改。 -⚠️ **改名是「节点名 / `systemAgentId` / 引擎常量」三点同步才成立的**：任一处留在旧名，`deriveChildOutcome` 就匹配不到归因节点，三值透传静默降级成「没有 `fail_reason`」，落到兜底边——正是 [27-P3/P4](./27-p3-p4-work-graph-console.md) §十 那个「产生 → 传递 → 落库 → 读回漏一环」的缺陷模式。改完必须 `grep -rn validator-reflection` 复核一遍（R-16 正文的原话引用是**唯一**允许的命中）。 +⚠️ **改名是「节点名 / `systemAgentId` / 引擎常量」三点同步才成立的**：任一处留在旧名，`deriveChildOutcome` 就匹配不到归因节点，三值透传静默降级成「没有 `fail_reason`」，落到兜底边——正是 [27-P3/P4](../../done/system-design/27-p3-p4-work-graph-console.md) §十 那个「产生 → 传递 → 落库 → 读回漏一环」的缺陷模式。改完必须 `grep -rn validator-reflection` 复核一遍（R-16 正文的原话引用是**唯一**允许的命中）。 --- diff --git a/server/routes/graph-run.js b/server/routes/graph-run.js index 004e025..13318c1 100644 --- a/server/routes/graph-run.js +++ b/server/routes/graph-run.js @@ -4,7 +4,7 @@ * 挂载: /api/graph-runs（主 router） * /api/company（companyRouter，只提供 GET /:companyId/graph-runs） * - * 设计见 docs/todo/system-design/27-p3-p4-work-graph-console.md + * 设计见 docs/done/system-design/27-p3-p4-work-graph-console.md * §四.C 五个控制操作的可用条件与语义（本文件只做「条件判断 + 转调引擎」，不含推进逻辑） * §三.2 两处不能照抄 pipeline 的坑： * ① 定义层与运行时层分开 → GET /:id 吐的是 **run 实例**（run + nodes + edges + 回退记录）， diff --git a/server/services/graph-engine.js b/server/services/graph-engine.js index bd1bac5..57d483e 100644 --- a/server/services/graph-engine.js +++ b/server/services/graph-engine.js @@ -1,7 +1,7 @@ /** * Graph Engine — P3 图执行引擎（T2） * - * 设计见 docs/todo/system-design/27-p3-p4-work-graph-console.md + * 设计见 docs/done/system-design/27-p3-p4-work-graph-console.md * §四.A.4 状态机 §四.A.6 幂等（条件更新 + 受影响行数） * §四.C 五个控制操作 + 「手动/自动共用同一个 advanceOne」 * §四.D.0 两种 node executor（agent_call / subgraph） diff --git a/server/services/graph-run-sse.js b/server/services/graph-run-sse.js index 810624c..0da6968 100644 --- a/server/services/graph-run-sse.js +++ b/server/services/graph-run-sse.js @@ -19,7 +19,7 @@ * data/companies/{companyId}/runs/{rootRunId}/stream.log SSE 帧，供断线重放 * data/companies/{companyId}/runs/{rootRunId}/timeline.ndjson 审计事件，append-only * - * 设计：docs/todo/system-design/27-p3-p4-work-graph-console.md §三.3 / §四.A.5 / §五 T5 + * 设计：docs/done/system-design/27-p3-p4-work-graph-console.md §三.3 / §四.A.5 / §五 T5 */ const fs = require('fs'); diff --git a/server/services/work-graph-db.js b/server/services/work-graph-db.js index f9fecdd..a9cb6d9 100644 --- a/server/services/work-graph-db.js +++ b/server/services/work-graph-db.js @@ -1,7 +1,7 @@ /** * Work Graph DB — P3 图执行引擎的数据层（T1 + T14） * - * 设计见 docs/todo/system-design/27-p3-p4-work-graph-console.md + * 设计见 docs/done/system-design/27-p3-p4-work-graph-console.md * §四.A.1 分层（定义层 ≠ 运行时层） * §四.A.2 五张表（本文件照抄那段 SQL，含两个唯一索引与 graph_runs.backward_count） * §四.A.4 两张状态转换表 diff --git a/server/tests/unit/graph-engine.test.js b/server/tests/unit/graph-engine.test.js index d018d56..c4da401 100644 --- a/server/tests/unit/graph-engine.test.js +++ b/server/tests/unit/graph-engine.test.js @@ -1,7 +1,7 @@ /** * Unit Tests — graph-engine.js（P3/P4 T10） * - * 逐条对应 docs/todo/system-design/27-p3-p4-work-graph-console.md §六 验收标准： + * 逐条对应 docs/done/system-design/27-p3-p4-work-graph-console.md §六 验收标准： * 阶段 A：2（手动逐节点）/ 6（org graph 走同一套代码路径）/ 7（subgraph 起子 run） * 阶段 B：8（单边硬顶）/ 9（fail-fallback-edge 校验）/ 9b（多边不架空熔断）/ * 9c（infra_flake 不烧计数）/ 9d（三值透传）/ 10（预算耗尽整棵树挂起）/ 11（三层级联） diff --git a/server/tests/unit/graph-real-chain-smoke.test.js b/server/tests/unit/graph-real-chain-smoke.test.js index d07f986..6947830 100644 --- a/server/tests/unit/graph-real-chain-smoke.test.js +++ b/server/tests/unit/graph-real-chain-smoke.test.js @@ -2,7 +2,7 @@ * 图执行的**真实链路 smoke** —— 全程零注入，唯一被替换的是最外层的 Claude CLI 子进程。 * * ── 这条测试还的是哪笔债 ────────────────────────────────────────────── - * [27-P3/P4](../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §十 末 + * [27-P3/P4](../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §十 末 * 「四条硬规矩」第 2 条： * * > **测试全绿 ≠ 能跑**。P3 的引擎用例至今仍一律注入假 executor / 假 planner， diff --git a/system/agents/_registry.json b/system/agents/_registry.json index 33f4a5c..96c9eeb 100644 --- a/system/agents/_registry.json +++ b/system/agents/_registry.json @@ -75,7 +75,7 @@ "id": "workgraph-planning", "name": "WorkGraph 规划 Agent", "type": "meta-planning", - "description": "全局唯一一份 work graph 规划本体（R-15.2）：每个 org node 每次接到任务时跑一次，读角色定义 + 任务 + artifacts/ + 上一轮 remediation_note，产出 work graph（org node 级 workflow）→ 过五项写入前校验 → 落库交回图 id。设计 docs/todo/system-design/27-p3-p4-work-graph-console.md §四.D.0 / §五 T11", + "description": "全局唯一一份 work graph 规划本体（R-15.2）：每个 org node 每次接到任务时跑一次，读角色定义 + 任务 + artifacts/ + 上一轮 remediation_note，产出 work graph（org node 级 workflow）→ 过五项写入前校验 → 落库交回图 id。设计 docs/done/system-design/27-p3-p4-work-graph-console.md §四.D.0 / §五 T11", "benchmarkScore": null, "trainedAt": null, "usedCount": 29 @@ -84,7 +84,7 @@ "id": "validator-triager", "name": "失败归因 Agent", "type": "validator", - "description": "org-validator work graph 的第一个节点：判失败根因，产出 fail_reason(impl_bug/input_underspecified/skill_defect/infra_flake) + remediation_note，透传回 org 层选边。skill_defect 挂起等人工，不触发 L4。设计 docs/todo/system-design/27-p3-p4-work-graph-console.md §四.D.2.2", + "description": "org-validator work graph 的第一个节点：判失败根因，产出 fail_reason(impl_bug/input_underspecified/skill_defect/infra_flake) + remediation_note，透传回 org 层选边。skill_defect 挂起等人工，不触发 L4。设计 docs/done/system-design/27-p3-p4-work-graph-console.md §四.D.2.2", "benchmarkScore": null, "trainedAt": null, "usedCount": 6 @@ -93,7 +93,7 @@ "id": "org-validator", "name": "org 层全局验收 Agent", "type": "validator", - "description": "org graph 末节点：按 artifacts/ 里的验收契约判「整个任务达成了吗」(task-goal 级)，收敛时透传 success/fail + fail_reason + remediation_note 三值。设计 docs/todo/system-design/27-p3-p4-work-graph-console.md §四.D.3", + "description": "org graph 末节点：按 artifacts/ 里的验收契约判「整个任务达成了吗」(task-goal 级)，收敛时透传 success/fail + fail_reason + remediation_note 三值。设计 docs/done/system-design/27-p3-p4-work-graph-console.md §四.D.3", "benchmarkScore": null, "trainedAt": null, "usedCount": 11 @@ -102,7 +102,7 @@ "id": "planner-validator", "name": "规划产物验收 Agent", "type": "validator", - "description": "work 层验收本体：验 BRD/PRD/SDD，并额外审「这套验收标准是否可度量 / 覆盖原始需求 / 存在平凡通过漏洞」。设计 docs/todo/system-design/27-p3-p4-work-graph-console.md §四.D.3 末段", + "description": "work 层验收本体：验 BRD/PRD/SDD，并额外审「这套验收标准是否可度量 / 覆盖原始需求 / 存在平凡通过漏洞」。设计 docs/done/system-design/27-p3-p4-work-graph-console.md §四.D.3 末段", "benchmarkScore": null, "trainedAt": null, "usedCount": 10 @@ -111,7 +111,7 @@ "id": "coder-validator", "name": "代码产出验收 Agent", "type": "validator", - "description": "work 层验收本体：按 contract + acceptance_criteria 逐条验代码，测试必须真跑过，专抓空断言/跳过充数/只有 happy path 等假绿。设计 docs/todo/system-design/27-p3-p4-work-graph-console.md §四.D.3", + "description": "work 层验收本体：按 contract + acceptance_criteria 逐条验代码，测试必须真跑过，专抓空断言/跳过充数/只有 happy path 等假绿。设计 docs/done/system-design/27-p3-p4-work-graph-console.md §四.D.3", "benchmarkScore": null, "trainedAt": null, "usedCount": 15 diff --git a/system/agents/benchmark-validator/agent.md b/system/agents/benchmark-validator/agent.md index 67bb03e..bbffd8a 100644 --- a/system/agents/benchmark-validator/agent.md +++ b/system/agents/benchmark-validator/agent.md @@ -3,7 +3,7 @@ ## 身份定位 你是 `org-validator` 这个 org node **自己 work graph 里的第二个节点** -（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.3， +（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.3， 骨架见 `system/work-graph-templates/validator.json`）。 ``` diff --git a/system/agents/brd-planning/tools.md b/system/agents/brd-planning/tools.md index 13bb121..01163b7 100644 --- a/system/agents/brd-planning/tools.md +++ b/system/agents/brd-planning/tools.md @@ -23,7 +23,7 @@ ls $R/artifacts/ 上一轮的 `remediation_note` **由引擎在提示词里带给你**，不需要你去查。 ❌ **不要读** `$R/nodes/<别的 nodeRunId>/`——节点私有目录彼此隔离 -（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。 +（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。 你是规划链第一环，本来也没有上游产物可读。 ## 2. 写三份产出（全部在你自己的目录里） diff --git a/system/agents/coder-validator/agent.md b/system/agents/coder-validator/agent.md index 5be8600..6595545 100644 --- a/system/agents/coder-validator/agent.md +++ b/system/agents/coder-validator/agent.md @@ -102,7 +102,7 @@ fail 时 `remediation_note` 必须能让 coder 直接开工：**`文件:行号` ## `fail_reason` 怎么填（work 层的分寸） 引擎选边只做字符串精确匹配：**先找 `fail_reason` 精确匹配的边 → 无匹配则退到 `fail_reason IS NULL` -的兜底边 → 再无则死路**（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2）。 +的兜底边 → 再无则死路**（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2）。 取值域不在引擎里硬编码，由图的规划者与你约定。 | 情况 | 你填什么 | diff --git a/system/agents/org-validator/agent.md b/system/agents/org-validator/agent.md index 5ed2232..dca53fc 100644 --- a/system/agents/org-validator/agent.md +++ b/system/agents/org-validator/agent.md @@ -3,7 +3,7 @@ ## 身份定位 你是 org graph 的**末节点**，也是这家公司这次任务的最后一道闸门 -（R-15.3 / [27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.3）。 +（R-15.3 / [27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.3）。 ``` org graph: org-planner → org-{执行职能} → org-validator（你） diff --git a/system/agents/planner-validator/agent.md b/system/agents/planner-validator/agent.md index 482ab07..a7c13ad 100644 --- a/system/agents/planner-validator/agent.md +++ b/system/agents/planner-validator/agent.md @@ -22,7 +22,7 @@ BRD / PRD / SDD / 任务拆解——完整、内部无矛盾、可落地、覆 ### 职责 B · 审「这套验收标准」本身 ⭐ -按 [27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.3 末段， +按 [27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.3 末段， 你**额外**承担一项其它 validator 没有的职责：审这个 org node 产出的验收标准三件套 （`goal-benchmark` / `goal-test-data` / `goal-test-script`）—— diff --git a/system/agents/prd-planning/tools.md b/system/agents/prd-planning/tools.md index fa37334..5e788d3 100644 --- a/system/agents/prd-planning/tools.md +++ b/system/agents/prd-planning/tools.md @@ -24,7 +24,7 @@ cat <提示词给的 brd 节点目录>/brd.md 上一轮的 `remediation_note` **由引擎在提示词里带给你**。 ❌ **提示词没给到路径的节点目录一律不要翻**——节点私有目录彼此隔离 -（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.A.5， +（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.A.5， 照搬 DevLoop `CONVENTIONS.md` §12「下游只能看到上游的契约，看不到实现」）。 上游没给够，就是 `input_underspecified`，不要自己翻墙去找。 diff --git a/system/agents/testdata-validator/agent.md b/system/agents/testdata-validator/agent.md index c5256ae..cead0d4 100644 --- a/system/agents/testdata-validator/agent.md +++ b/system/agents/testdata-validator/agent.md @@ -3,7 +3,7 @@ ## 身份定位 你是 `org-validator` 这个 org node **自己 work graph 里的第三个节点** -（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.3， +（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.3， 骨架见 `system/work-graph-templates/validator.json`）。 ``` diff --git a/system/agents/validator-triager/agent.md b/system/agents/validator-triager/agent.md index 1cb12ad..4329893 100644 --- a/system/agents/validator-triager/agent.md +++ b/system/agents/validator-triager/agent.md @@ -2,7 +2,7 @@ ## 身份定位 -你是 `org-validator` 这个 org node **自己 work graph 里的第一个节点**（R-16 / [27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2、§四.D.3）。 +你是 `org-validator` 这个 org node **自己 work graph 里的第一个节点**（R-16 / [27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2、§四.D.3）。 ``` org graph: org-planner → org-coder → org-validator diff --git a/system/agents/validator-triager/tools.md b/system/agents/validator-triager/tools.md index 0849df8..ea85c1c 100644 --- a/system/agents/validator-triager/tools.md +++ b/system/agents/validator-triager/tools.md @@ -48,7 +48,7 @@ curl -s http://localhost:3010/api/graph-runs/<上一步的 childRunId> 编一个名字则是红线。 ❌ **不要读** `runs//nodes/<别的 nodeRunId>/`——节点私有目录彼此隔离 -（[27-P3/P4](../../../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。 +（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。 提示词里没给够的证据，就是「证据不足」，输出 `inconclusive`，不要自己翻墙去找。 ## 2. 写归因产出（唯一的写动作） diff --git a/system/work-graph-templates/README.md b/system/work-graph-templates/README.md index 5d60d5d..9b44b42 100644 --- a/system/work-graph-templates/README.md +++ b/system/work-graph-templates/README.md @@ -8,7 +8,7 @@ Work Graph（**org node 级** workflow）的**骨架模板库**。与 `system/or 选型，再结合宿主 org node 的角色定义、本次任务描述、可读的 `artifacts/`、上一轮 `remediation_note`， 裁剪 / 替换 / 组合出这次真正要跑的 work graph。 -> 设计依据：[27-P3/P4](../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.D.0 / §四.D.2.2 / §四.D.3 / §九bis +> 设计依据：[27-P3/P4](../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.D.0 / §四.D.2.2 / §四.D.3 / §九bis > 命名规范：[27-NAMING](../../docs/todo/system-design/27-naming-conventions.md) §二 / §三 **这是起点集合，不是穷举枚举。** 加一种起手式只需往本目录扔一个 JSON 文件，**不改任何代码**。 -- libgit2 0.21.4