diff --git a/docs/README.md b/docs/README.md index 093b5db..c7cc476 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ 判断依据：文档正文的显式「状态」标记（✅ 已完成 / 已实现 vs 📝 设计中 / 未实现）、未勾选的 checklist，以及与代码库实际实现的交叉核对（见各条目备注）。 -> **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。`todo/` 下只保留这一份，其余待办已移入 `todo/future/`，避免和主线抢注意力。 +> **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。该系列已完成的阶段文档（P1/P2）移入 `done/`，其余非主线待办在 `todo/future/`。 ## done/ @@ -21,14 +21,24 @@ | [qa_judge_req.md](./done/qa_judge_req.md) | QA Judge Agent 需求文档 — 已在 `system/templates/qa-judge/` 落地 | | [task_timeline_design.md](./done/task_timeline_design.md) | Task Timeline View 设计文档 — 已实现（`server/routes/tasks.js`、`server/services/task-service.js`、`web/src/views/TaskTimeline.vue`） | | [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/01-26](./done/system-design/) | 系统设计正文 01～26 章（14、25-harness-engineering-improvements 例外，见 todo/future/；27 例外，见 todo/），各章节状态见文内「状态」标记 | ## todo/（当前主线） +Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `done/`**（P1、P2），下面是仍在推进或长期有效的部分。 + | 文件 | 说明 | |------|------| -| [system-design/27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md) | Graph Agent 架构，状态：📝 设计中，未实现。P0-P6 分阶段路线图，当前唯一在推进的重构 | -| [system-design/27-p1-virtual-reference.md](./todo/system-design/27-p1-virtual-reference.md) | P1（虚拟引用）细化需求与设计文档：`getAgentConfig()`/`PromptBuilder.build()`/`hire()` 的具体改法、验收标准、blast radius、未决问题 | +| [27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md) | **总纲**。P0-P6 分阶段路线图与整体架构。P0-P3+P4 已实现，P4（新）/P5/P6 待做 | +| [27-requirement.md](./todo/system-design/27-requirement.md) | **需求源头**。用户原话照搬（R-1..R-16）+ 需求→设计落点速查。其余文档都是对它的转述，出现分歧以此为准 | +| [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`），文档仍在补充中 | +| [27-goal-contract-format.md](./todo/system-design/27-goal-contract-format.md) | 验收契约格式（`goal-benchmark` / `goal-test-data` / `goal-test-script` 的产物形态与跨节点传递） | +| [27-p4-parallel-and-artifacts.md](./todo/system-design/27-p4-parallel-and-artifacts.md) | **P4（回收编号）并行执行与产物索引** — 📝 设计中。fan-out 真并发 + 同 agent 多实例隔离 + `files.json` 产物索引。三个 Phase，C 可插队 | ## todo/future/（暂缓，非当前重心） diff --git a/docs/todo/system-design/27-p1-virtual-reference.md b/docs/done/system-design/27-p1-virtual-reference.md index ba70675..98e755c 100644 --- a/docs/todo/system-design/27-p1-virtual-reference.md +++ b/docs/done/system-design/27-p1-virtual-reference.md @@ -1,9 +1,9 @@ # 27-P1. 虚拟引用寻址 — 需求与设计文档 -> **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 Phase P1（"虚拟引用"） +> **所属**: [27 Graph Agent 架构](../../todo/system-design/27-graph-agent-architecture.md) 的 Phase P1（"虚拟引用"） > **版本**: v0.2（设计阶段，未实现；因 P0 完工同步更新） > **日期**: 2026-08-15 -> **前置**: P0 地基已**全部完工**并提交（commit `8421f55`）——`seedGlobalAgents()`/`seedTemplates()`/`seedCompanyAgents()`/`verifyCounts()` 四步全部实现，`system_agents.legacy_path` 可用，`org_graph_nodes` 已经把**现有全部公司雇佣关系**回填完毕（不再是空表）。P0 实施过程中发现一个直接影响 P1 设计的问题：**`system/agents/` 与 `system/templates/` 存在 6 个同名但内容可能不同步的 id**，详见 [27 号文档 §7](./27-graph-agent-architecture.md#七p0-实施发现2026-08-15) 与下文 §4.6——本版本已针对这个问题修正了查表逻辑。 +> **前置**: P0 地基已**全部完工**并提交（commit `8421f55`）——`seedGlobalAgents()`/`seedTemplates()`/`seedCompanyAgents()`/`verifyCounts()` 四步全部实现，`system_agents.legacy_path` 可用，`org_graph_nodes` 已经把**现有全部公司雇佣关系**回填完毕（不再是空表）。P0 实施过程中发现一个直接影响 P1 设计的问题：**`system/agents/` 与 `system/templates/` 存在 6 个同名但内容可能不同步的 id**，详见 [27 号文档 §7](../../todo/system-design/27-graph-agent-architecture.md#七p0-实施发现2026-08-15) 与下文 §4.6——本版本已针对这个问题修正了查表逻辑。 --- diff --git a/docs/todo/system-design/27-p2-org-graph.md b/docs/done/system-design/27-p2-org-graph.md index 86825c9..5f31120 100644 --- a/docs/todo/system-design/27-p2-org-graph.md +++ b/docs/done/system-design/27-p2-org-graph.md @@ -1,11 +1,11 @@ # 27-P2. Org Graph — 公司级 Workflow 的生成与落地 -> **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 Phase P2 +> **所属**: [27 Graph Agent 架构](../../todo/system-design/27-graph-agent-architecture.md) 的 Phase P2 > **版本**: v0.4（**按执行流边模型重写**；v0.1-v0.3 把 Org Graph 建模为静态汇报结构，该模型已作废，见 §一） > **日期**: 2026-08-15 > **前置**: P0 地基已完工（commit `8421f55`）、**P1 虚拟引用寻址已实现**（commit `226489d`，`server/services/graph-service.js`） -> **命名**: 全文遵循 [27-NAMING 命名规范](./27-naming-conventions.md)。v0.3 的 `org-graph-creator` 在本版本统一改名为 **`orggraph-planning`**。 -> **配套**: [27-E2E 端到端流程](./27-e2e-task-execution-flow.md)（本文档在整条链路里的位置）、[27-EXAMPLE 参考场景](./27-example-dev-company-walkthrough.md)（跑一遍具体的数） +> **命名**: 全文遵循 [27-NAMING 命名规范](../../todo/system-design/27-naming-conventions.md)。v0.3 的 `org-graph-creator` 在本版本统一改名为 **`orggraph-planning`**。 +> **配套**: [27-E2E 端到端流程](../../todo/system-design/27-e2e-task-execution-flow.md)（本文档在整条链路里的位置）、[27-EXAMPLE 参考场景](../../todo/system-design/27-example-dev-company-walkthrough.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](./27-p3-p4-work-graph-console.md) 的同一套 | 同左 | +| 执行引擎 | [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) 的同一套 | 同左 | **由此带来的四处结构性改动**（这也是本次重写的主要内容）： @@ -47,7 +47,7 @@ v0.1-v0.3 把 Org Graph 建模为**静态汇报结构**：节点是角色引用 ### 非目标 -- **不做**图的执行 —— 执行引擎、启动/暂停/单步/重试、SSE 全部属于 [27-P3/P4](./27-p3-p4-work-graph-console.md)。P2 只负责"把图建出来、存好、能读能画"。 +- **不做**图的执行 —— 执行引擎、启动/暂停/单步/重试、SSE 全部属于 [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md)。P2 只负责"把图建出来、存好、能读能画"。 - **不做** `company.json.agents[]` 的废弃 —— 它仍是"这家公司雇了谁"的真相源；org graph 回答的是"任务怎么流过这些人"，两者并存。 - **不做**存量公司的补图 —— 见 §六。 - **不做** `workgraph-planning` agent 本身的设计 —— 属于 P3。 @@ -95,10 +95,10 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active ### 3.3 图的合法性约束（写入前校验） -与 work graph 的执行前校验同一套规则（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.A）： +与 work graph 的执行前校验同一套规则（[27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §四.A）： 1. **无环**（仅针对 `edge_kind='forward'`）—— 三色 DFS，复用 DevLoop `doc-store.js:167` 的 `hasCycle()` 实现。 -2. **单一入口**（✅ 已定案，见 [27-REQ](./27-requirement.md) R-13）—— 必须恰好有一个入度为 0 的 forward 节点，任务从这里进入。多入口会让"任务从哪开始"无法确定，且需要任务入口多带一个参数。 +2. **单一入口**（✅ 已定案，见 [27-REQ](../../todo/system-design/27-requirement.md) R-13）—— 必须恰好有一个入度为 0 的 forward 节点，任务从这里进入。多入口会让"任务从哪开始"无法确定，且需要任务入口多带一个参数。 3. **可达性** —— 每个节点都必须从入口可达，孤立节点直接拒绝。 4. **回退边必须显式标注** —— 任何指向"拓扑序更早节点"的边，`edge_kind` 必须是 `backward`；引擎独立复核，不信任标注（27 号文档 §3.4 第 5 点的同款兜底）。 @@ -111,7 +111,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active 新增 system agent 模板 `system/templates/orggraph-planning/`（`config.json.type` 取 `meta-bootstrap`，与业务角色区分）。工作流： 1. **读输入**：公司 `id` / `name` / **`goal`（company-goal）** / `description`（由 §4.4 的首轮消息带入）。 - `company-goal` 是「这家公司要达成什么」，`description` 是「这家公司是干什么的」——前者是规划流水线的主依据，后者是背景。见 [27-NAMING](./27-naming-conventions.md) §四。 + `company-goal` 是「这家公司要达成什么」，`description` 是「这家公司是干什么的」——前者是规划流水线的主依据，后者是背景。见 [27-NAMING](../../todo/system-design/27-naming-conventions.md) §四。 2. **读候选骨架**：`ls system/org-graph-templates/`，逐个读取，理解各自的 `whenToUse`。 3. **读可招角色**：`node bin/lemon.js company templates`（复用现成 CLI，`listTemplates()` 返回 id/name/type/description）。 4. **规划**：综合三者，产出一张 workflow —— 节点列表 + 执行流边。允许裁剪、替换、组合多个模板，也允许判断需要一个模板库里没有的新角色。 @@ -119,7 +119,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active 6. **提交图**：调用 §4.3 的整体写入 API，图通过 §3.3 校验后落库。 7. **执行招聘**：按拓扑序对每个节点调 `hire()`。 - **模板已存在** → 走 P1 虚拟引用寻址，不拷贝 `agent.md`。 - - **模板不存在** → **从 `system/templates/base/` 元 agent 继承出骨架**（自动带上 base 的 `RESEARCH → PLAN → EXECUTE → VERIFY` 四段式生命周期），再由 `agent-creator` 填充该角色特有的定义。这是 [27-E2E](./27-e2e-task-execution-flow.md) §八bis「所有 node agent 由元 agent 继承生成」在 P2 的落地点——**不是**直接走现有的 `needs_training` 全量培养分支。 + - **模板不存在** → **从 `system/templates/base/` 元 agent 继承出骨架**（自动带上 base 的 `RESEARCH → PLAN → EXECUTE → VERIFY` 四段式生命周期），再由 `agent-creator` 填充该角色特有的定义。这是 [27-E2E](../../todo/system-design/27-e2e-task-execution-flow.md) §八bis「所有 node agent 由元 agent 继承生成」在 P2 的落地点——**不是**直接走现有的 `needs_training` 全量培养分支。 - **新建 agent 的 `scope`**：一律默认 `scope='company'`、`owner_company_id` 为本公司（27 号文档 §3.2）。升级为 `public` 走既有的 benchmark ≥95 门槛，不在 P2 范围内。 - **训练是可选的后置步骤**：建成后可手动触发 `innovator` 培养，也可按公司需求配置为自动触发。P2 只保证「角色能被建出来且带四段式骨架」，不强制等训练完成。 8. **收尾**：关闭自己的心跳转入休眠。后续增量调整归 HR。 @@ -183,7 +183,7 @@ if (bootstrap.status === 'hired_from_template') { ### 4.5 前端 -**不自己写渲染逻辑** —— org graph 与 work graph 同构，直接复用 [27-P3/P4](./27-p3-p4-work-graph-console.md) T3 的画布组件（其本身又是扩展自既有的 `web/src/components/devloop/UnitsDAG.vue`，已实现 SVG + Kahn 分波布局 + 状态着色 + 点击下钻）。 +**不自己写渲染逻辑** —— 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 分波布局 + 状态着色 + 点击下钻）。 这也意味着 **P2 的前端工作依赖 P3 的画布组件先做出来**。若想让 P2 独立上线，可以先在 Company Dashboard 用一个纯文本的拓扑序列表占位（`org-planner → org-coder → org-validator`），等 P3 画布就绪再替换。 @@ -209,9 +209,9 @@ if (bootstrap.status === 'hired_from_template') { ``` 同理提供 `content.json`（`org-planner → org-writer → org-validator`）、`ops.json`。三张图**首尾节点同名**， -只有中段执行节点不同——命名轴是节点所在图的层级，不是业务领域（[27-NAMING](./27-naming-conventions.md) §3.1）。 +只有中段执行节点不同——命名轴是节点所在图的层级，不是业务领域（[27-NAMING](../../todo/system-design/27-naming-conventions.md) §3.1）。 -`dev.json` 那两条 `fail` 边是 P3 的 `fail_reason` 细分路由（[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.D.2.2）： +`dev.json` 那两条 `fail` 边是 P3 的 `fail_reason` 细分路由（[27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §四.D.2.2）： 带 `failReason` 的边按归因结果精确匹配，不带 `failReason` 的那条是**兜底边**， 任何有 `fail` 出边的节点都必须留一条，否则归因产出图上没有的取值时会落到死路。 `content.json` / `ops.json` 目前只有兜底边。 @@ -220,7 +220,7 @@ if (bootstrap.status === 'hired_from_template') { - **是起点集合，不是穷举枚举** —— 加一种公司类型只需加一个 JSON 文件，不改任何代码。`orggraph-planning` 读全部模板后自行选型/裁剪/组合，不是代码里的 `switch(type)`。 - **`nodes` 里的角色名是建议**，`orggraph-planning` 必须对照 `company templates` 核实是否真有可招模板；没有则走 `needs_training` 培养分支。 -- **模板里的角色名必须遵循 [27-NAMING](./27-naming-conventions.md) §3.1 的 `org-{职能}` 规则**，不允许裸用 `planner` / `validator`，也不再按业务领域起 `code-` / `content-` 这类前缀（v0.2 的写法，已作废）。 +- **模板里的角色名必须遵循 [27-NAMING](../../todo/system-design/27-naming-conventions.md) §3.1 的 `org-{职能}` 规则**，不允许裸用 `planner` / `validator`，也不再按业务领域起 `code-` / `content-` 这类前缀（v0.2 的写法，已作废）。 - ⚠️ **避开命名冲突 id**：`agent-creator` / `digester` / `evolver` / `evolver-youtube-crawler` / `hunter` / `innovator` 这 6 个 id 在 `system/agents/` 与 `system/templates/` 下同时存在且内容可能不同步（27 号文档 §七），模板里不要引用它们。 --- @@ -292,7 +292,7 @@ P0 的 `seedCompanyAgents()` 已把所有存量公司的角色回填成 `org_gra ## 八、风险 / Open Questions -1. ~~**单一入口约束是否过严**~~ ✅ **已定案**（[27-REQ](./27-requirement.md) R-13.4）：强制单入口。保留原始论证：如果将来出现"两类任务从不同节点进入同一家公司"的需求（如 bugfix 直接从 coder 进入），需放宽为"允许多入口 + 任务携带指定入口"，届时任务入口要多带一个参数。 +1. ~~**单一入口约束是否过严**~~ ✅ **已定案**（[27-REQ](../../todo/system-design/27-requirement.md) R-13.4）：强制单入口。保留原始论证：如果将来出现"两类任务从不同节点进入同一家公司"的需求（如 bugfix 直接从 coder 进入），需放宽为"允许多入口 + 任务携带指定入口"，届时任务入口要多带一个参数。 2. **`orggraph-planning` 的规划质量没有硬校验**：§3.3 只保证图**结构合法**，不保证它**适合这家公司**。缓解：`workspace/orggraph-plan.md` 留下决策记录供人工复核；发现不合理时走 §4.3 的 PATCH 增量修正。 3. **一次建公司多一轮 LLM 对话**：✅ 实测约 30 秒（`p2-verify` 验证公司，4 节点 5 边 + 4 个角色招聘）。`POST /create` 保持同步返回（fire-and-forget）。⚠️ 前端空态文案已提及"存量公司或规划仍在进行中"，但**没有真正区分这两种状态**——要区分需要轮询 `/org-graph` 或给公司加一个 `orgGraphStatus` 字段。当前是刻意的简化。 4. **6 个命名冲突 id**（27 号文档 §七）：本文档 §4.6 已要求模板避开它们，但如果 `orggraph-planning` 自主判断需要其中某个角色，仍会撞上"该读哪份 `agent.md`"的歧义。建议在 P2 上线前把这个产品决策做掉。 @@ -304,4 +304,4 @@ P0 的 `seedCompanyAgents()` 已把所有存量公司的角色回填成 `org_gra - **P0/P1**：均已实现。P2 唯一需要动 P1 代码的地方是 DROP 它建的全量唯一索引（T1）。 - **P3/P4**：P2 产出图，P3/P4 执行图。**两者共用同一套 schema 形态、执行引擎和画布组件** —— 这是 v0.4 新模型最大的收益。P2 不含任何执行逻辑。 -- **端到端**：本文档在整条链路里的位置见 [27-E2E](./27-e2e-task-execution-flow.md) §三 阶段 2，具体跑一遍的样子见 [27-EXAMPLE](./27-example-dev-company-walkthrough.md) 阶段 2。 +- **端到端**：本文档在整条链路里的位置见 [27-E2E](../../todo/system-design/27-e2e-task-execution-flow.md) §三 阶段 2，具体跑一遍的样子见 [27-EXAMPLE](../../todo/system-design/27-example-dev-company-walkthrough.md) 阶段 2。 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 4612c63..5e10b2c 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 落地](./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 执行控制台](./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) —— 本文档讲机制，那份文档把机制在一家具体公司上跑一遍数。两份对照着读。 @@ -67,7 +67,7 @@ ### 阶段 2 · orggraph-planning 根据描述生成基础 org graph -**状态**：📐 已设计未实现（[27-P2](./27-p2-org-graph.md) §4.8/§4.9/§4.10） +**状态**：📐 已设计未实现（[27-P2](../../done/system-design/27-p2-org-graph.md) §4.8/§4.9/§4.10） P2 已经设计了：`system/org-graph-templates/{dev,content,ops}.json` 模板库 + `orggraph-planning` agent + 创建时自动招聘并 fire-and-forget 触发首轮对话。 @@ -177,7 +177,7 @@ P2 已经设计了：`system/org-graph-templates/{dev,content,ops}.json` 模板 > | **Org Graph** | orggraph-planning | 建公司时，一次 | org node agent | 执行流（success/fail 条件） | > | **Work Graph** | workgraph-planning agent | 每个 org node 接到任务时 | system agent 引用 | 执行流（success/fail 条件） | > -> **这意味着 [27-P2](./27-p2-org-graph.md) 现在的 org graph 模型需要改**：它把边定义成 `reports_to` / `collaborates_with`（静态汇报结构），而实际需要的是**带 success/fail 条件的执行流边**，与 work graph 的边同构。汇报关系如果还需要，应降级为节点上的元数据属性，而不是 org graph 的主干语义。 +> **这意味着 [27-P2](../../done/system-design/27-p2-org-graph.md) 现在的 org graph 模型需要改**：它把边定义成 `reports_to` / `collaborates_with`（静态汇报结构），而实际需要的是**带 success/fail 条件的执行流边**，与 work graph 的边同构。汇报关系如果还需要，应降级为节点上的元数据属性，而不是 org graph 的主干语义。 > > **好处**：一套 schema、一套执行引擎、一套控制台 UI，在两个层级上原样复用；三层下钻（org graph → work graph → 并行子图）天然递归；"启动/下一步/暂停/停止/重试"五个操作在每一层语义完全一致。 > @@ -356,7 +356,7 @@ DevLoop 就这个问题做过显式决策（`loops-l2.md` 方案 A/B/C），选 **所有 org graph / work graph 的 node agent，都由一个元 agent 架构继承生成，统一是「全局通用本体 + 公司/角色记忆分区」的结构。** -这条定案取代了 v0.1 §四 里"三个验收 agent 要不要按父节点特化"这个问题——答案是**不特化**：不存在 `goal-benchmark` / `test-planner-benchmark` 各自独立的 agent，只有通用的 benchmark 设计能力，靠记忆分区区分它在不同 org node / 不同公司下的经验积累。agent 池不随 org node 数量膨胀，也与 [27-P1](./27-p1-virtual-reference.md) 虚拟引用寻址的初衷一致（同一份本体，多处引用，各自私有语境）。 +这条定案取代了 v0.1 §四 里"三个验收 agent 要不要按父节点特化"这个问题——答案是**不特化**：不存在 `goal-benchmark` / `test-planner-benchmark` 各自独立的 agent，只有通用的 benchmark 设计能力，靠记忆分区区分它在不同 org node / 不同公司下的经验积累。agent 池不随 org node 数量膨胀，也与 [27-P1](../../done/system-design/27-p1-virtual-reference.md) 虚拟引用寻址的初衷一致（同一份本体，多处引用，各自私有语境）。 ✅ **元 agent 在仓库里已经存在**：`system/templates/base/`（"标准基座员工 Base Agent"）。它已经强制了一套四段式生命周期： @@ -376,9 +376,9 @@ RESEARCH → PLAN → EXECUTE → VERIFY | # | 文档 | 原错误陈述 | 事实 | 修订结果 | |---|---|---|---|---| -| 1 | [27-P2](./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`）」 | +| 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，**已完整实现**…）」，并追加了「波内实际是串行」的补充观察 | -| 3 | [27-P2](./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 + 重建 | +| 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 曲线路由 + 循环徽标」三块 | ### 此外建议（复核结论） 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 49a6c26..c7c743d 100644 --- a/docs/todo/system-design/27-example-dev-company-walkthrough.md +++ b/docs/todo/system-design/27-example-dev-company-walkthrough.md @@ -33,7 +33,7 @@ } ``` -**系统动作**（[27-P2](./27-p2-org-graph.md) §4.10）： +**系统动作**（[27-P2](../../done/system-design/27-p2-org-graph.md) §4.10）： 1. `companyService.create()` 建目录 + `company.json`（`agents: []`） 2. 🔴 自动 `hire(id, 'orggraph-planning', {})` @@ -48,7 +48,7 @@ **它读三样东西**： 1. 公司 description（上面那段） -2. `system/org-graph-templates/*.json`（候选骨架，[27-P2](./27-p2-org-graph.md) §4.8） +2. `system/org-graph-templates/*.json`（候选骨架，[27-P2](../../done/system-design/27-p2-org-graph.md) §4.8） 3. `node bin/lemon.js company templates`（现实里能招到的角色，`listTemplates()` 返回 id/name/type/description） **它的判断**：description 里有"做一个工具""跑在本地""CLI 版本"→ 匹配 `dev.json`。 @@ -76,7 +76,7 @@ `ceo` / `hr` 这类不参与任务执行的角色仍然可以被招聘进公司（存在于 `company.json.agents[]`），但**不出现在 org graph 这张 workflow 里**——org graph 只画"任务怎么流过这家公司"。 -**它提交图 + 执行招聘**（两步，[27-P2](./27-p2-org-graph.md) §4.1 第 6-7 步）： +**它提交图 + 执行招聘**（两步，[27-P2](../../done/system-design/27-p2-org-graph.md) §4.1 第 6-7 步）： ```bash # 1. 整体提交图定义，过四项校验（无环 / 单一入口 / 可达性 / 回退边标注）后事务性落库 @@ -255,10 +255,10 @@ brd-planning → prd-planning → sdd-planning ─┬→ goal-test-data ── | 1 | `qa-judge` 没有程序化调用入口（判决无法驱动任何自动动作） | 5, 6, 7 | [27-E2E](./27-e2e-task-execution-flow.md) §11.3 | | 2 | org-validator 节点的验收执行能力（跑 test_script / 喂 test_data）未实现 | 5, 7 | §11.3 | | 3 | 「用户 → 公司」任务入口不存在 | 3 | §三 阶段 3 | -| 4 | **P2 的 org graph 边模型需从 `reports_to` 改为 `success`/`fail` 执行流边** | 2, 4 | §五定案 + [27-P2](./27-p2-org-graph.md) v0.4 修正 | +| 4 | **P2 的 org graph 边模型需从 `reports_to` 改为 `success`/`fail` 执行流边** | 2, 4 | §五定案 + [27-P2](../../done/system-design/27-p2-org-graph.md) v0.4 修正 | | 5 | fan-out 并行撞 CONVENTIONS §12 不变量 + SessionPool key 复用 | 5, 6 | §7.4 | | 6 | 任务级总预算不存在 | 7 | §7.1 | | 7 | L4-general 的 agent dream 流程不存在（跨公司批量蒸馏层缺失，单点接口已齐） | 7 之后（离线） | §8.1 | -| 8 | orggraph-planning / workgraph-planning agent 均未实现 | 2, 5, 6 | [27-P2](./27-p2-org-graph.md) §4.9 | +| 8 | orggraph-planning / workgraph-planning agent 均未实现 | 2, 5, 6 | [27-P2](../../done/system-design/27-p2-org-graph.md) §4.9 | 第 4 项是**架构前提**，必须先改；改完之后做 1-3 项，这个场景就能在"串行、无 L4"的模式下端到端跑通一遍。 diff --git a/docs/todo/system-design/27-graph-agent-architecture.md b/docs/todo/system-design/27-graph-agent-architecture.md index e3afd09..ded6ccc 100644 --- a/docs/todo/system-design/27-graph-agent-architecture.md +++ b/docs/todo/system-design/27-graph-agent-architecture.md @@ -35,7 +35,7 @@ |------|------| | **System Agent** | 全局唯一的可执行 Agent 实体。自带 prompt 定义、公共记忆（`memory.md`）、按公司分区的私有历史。是 24 号文档里"System Agent"与"Agent Template"两个概念的合并——不再区分"模板"和"实例"，只有"这个 agent，被谁调用过"。 | | **scope** | System Agent 的可见性：`public`（跨公司共享，记忆公共累积）或 `company`（私有，只属于 `owner_company_id` 指定的一家公司）。 | -| **Org Graph** | **company 级别生成的 workflow**。由 `orggraph-planning` agent 在建公司时根据公司目标/描述生成一次。节点 = 对某个 org node agent 的引用；边 = **执行流**（`condition ∈ {success, fail}` + `edge_kind ∈ {forward, backward}`）。⚠️ v0.3 修正：本文档 v0.2 曾把它定义为"静态汇报结构、边是汇报/协作关系"，该建模已作废，详见 [27-P2 v0.4](./27-p2-org-graph.md) §一。 | +| **Org Graph** | **company 级别生成的 workflow**。由 `orggraph-planning` agent 在建公司时根据公司目标/描述生成一次。节点 = 对某个 org node agent 的引用；边 = **执行流**（`condition ∈ {success, fail}` + `edge_kind ∈ {forward, backward}`）。⚠️ v0.3 修正：本文档 v0.2 曾把它定义为"静态汇报结构、边是汇报/协作关系"，该建模已作废，详见 [27-P2 v0.4](../../done/system-design/27-p2-org-graph.md) §一。 | | **Work Graph** | **org graph node 级别生成的 workflow**。某个 org node 收到任务后，现场调用 `workgraph-planning` agent 针对这一具体任务规划出。节点 = 对某个 system agent 的一次调用；边的语义与 Org Graph **完全同构**。执行完归档，不复用到下一个任务。 | | **两者关系** | Org Graph 与 Work Graph 是**同一种东西在不同层级上的递归**——同一套 schema 形态、同一个执行引擎、同一套控制台 UI，区别只在生成者、生成时机、节点指向。 | | **Loop-Validator** | 一个专职的 system agent，内置带硬编码熔断逻辑的 skill。所有"回退到历史节点"的边必须先经过它：备案 → 审计上次修复是否生效 → 判断修复方案是否被正确传递 → 循环数 > 3 强制终止。 | @@ -101,7 +101,7 @@ system/agents/{agentId}/ ### 3.3 Org Graph：company 级 workflow -> ⚠️ **v0.3 修正**：本节 v0.2 的内容（"公司静态结构、边是汇报/协作关系、招聘时由 CEO 或 HR 维护"）已作废。完整设计见 [27-P2 v0.4](./27-p2-org-graph.md)。 +> ⚠️ **v0.3 修正**：本节 v0.2 的内容（"公司静态结构、边是汇报/协作关系、招聘时由 CEO 或 HR 维护"）已作废。完整设计见 [27-P2 v0.4](../../done/system-design/27-p2-org-graph.md)。 - **节点**：对某个 org node agent 的引用（`org_graph_nodes`）。 - **边**：**执行流**（`org_graph_edges`：`condition ∈ {success, fail}`、`edge_kind ∈ {forward, backward}`），与 `work_graph_edges` 同构。 @@ -225,8 +225,8 @@ CREATE TABLE work_graph_edges ( | Phase | 目标 | 交付物 | 验收标准 | |-------|------|--------|----------| | **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 虚拟引用寻址](./27-p1-virtual-reference.md) | 新雇佣的 agent 不再产生文件拷贝，调用时能正确拼装公共+私有上下文；旧公司（仍是拷贝模式）继续可跑，不强制迁移存量数据 | -| **P2 Org Graph** | `company.json.agents[]` 迁移为图结构 | `org_graph_nodes`/`edges` 落地；HR/CEO 招聘走新表。细化需求与设计见 [27-P2 Org Graph 落地](./27-p2-org-graph.md) | 现有 Company Dashboard 前端能正确读出 org graph 并渲染（哪怕暂时按列表展示） | +| **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 两层都加 | 同上 | | **P4 并行执行与产物索引**（**回收编号**） | fan-out 真并发 + 产物统一索引 | `advanceBatch` 批量拾取（手动模式退化为 `maxConcurrency=1`，行为与 P3 一致）；同 agent 多实例隔离（启用 `SessionPool.getKey` 已预留但从未使用的 `scope` 参数）；解除「一家公司一个 active root run」；`data/companies/{cid}/tasks/{taskId}/` 产物目录 + `files.json` 检索索引。细化设计见 [27-P4 并行执行与产物索引](./27-p4-parallel-and-artifacts.md) | 3 个并行分支同时 running 且总墙钟明显短于串行；部分失败时 fan-in 停等且可视化「在等谁」；`files.json` 可从节点行 rebuild | @@ -263,7 +263,7 @@ P0 阶段的处理方式是**迁移脚本层面的临时保护**：`system_agent - **[27-E2E 端到端任务执行流程](./27-e2e-task-execution-flow.md)** — 跨阶段总览：从建公司 → 下达任务 → org graph 逐节点执行 → work graph 规划与循环 → 验收收敛。**建议先读这一份**，它指出了本文档体系与已有 DevLoop 实现之间的对应关系、三处语义冲突和若干空白。 - **[27-NAMING 命名规范](./27-naming-conventions.md)** — 跨文档命名约定（`{作用域}-{职能}`）。新增 agent id / 表名 / 字段名前必读，避免与既有的 `benchmark` / `goal` 等命名撞车。 - **[27-EXAMPLE 参考场景走查](./27-example-dev-company-walkthrough.md)** — 把上面那套架构在一家具体公司上跑一遍数（含各阶段真实形态的 JSON / 图 / 成本估算 / 断点清单）。实现时的靶子与端到端验收场景。 -- [27-P1 虚拟引用寻址](./27-p1-virtual-reference.md) — 已实现（commit `226489d`） -- [27-P2 Org Graph 落地](./27-p2-org-graph.md) — 设计稿 +- [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-P4 并行执行与产物索引](./27-p4-parallel-and-artifacts.md) — 设计稿