From 89f4c9892db7ca32145a83de3e691c10e1c53d8b Mon Sep 17 00:00:00 2001 From: yibo Date: Sat, 15 Aug 2026 17:20:30 +0800 Subject: [PATCH] docs(graph-agent): 新增 27-REQ 原始需求页，保存用户原话作为设计源头 --- docs/todo/system-design/27-e2e-task-execution-flow.md | 1 + docs/todo/system-design/27-example-dev-company-walkthrough.md | 2 ++ docs/todo/system-design/27-graph-agent-architecture.md | 1 + docs/todo/system-design/27-requirement.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 173 insertions(+), 0 deletions(-) create mode 100644 docs/todo/system-design/27-requirement.md 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 4c0e33b..b7f166f 100644 --- a/docs/todo/system-design/27-e2e-task-execution-flow.md +++ b/docs/todo/system-design/27-e2e-task-execution-flow.md @@ -4,6 +4,7 @@ > **版本**: 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-REQ 原始需求](./27-requirement.md) —— 本文档是对那些原话的结构化转述，原文以那份为准。 > **配套**: [27-EXAMPLE 参考场景走查](./27-example-dev-company-walkthrough.md) —— 本文档讲机制，那份文档把机制在一家具体公司上跑一遍数。两份对照着读。 --- 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 20d4c68..c185a15 100644 --- a/docs/todo/system-design/27-example-dev-company-walkthrough.md +++ b/docs/todo/system-design/27-example-dev-company-walkthrough.md @@ -8,6 +8,8 @@ > 2. **验收场景**——P2/P3/P4 全部落地后，跑通这一个场景就等于端到端验证。 > 3. **沟通基准**——讨论"这里应该怎么设计"时，有一个共同的具体例子可指。 > +> ⚠️ **本文档的「配图工厂」是为走查虚构的场景，不是用户提出的原始需求**。原始需求原话见 [27-REQ](./27-requirement.md)。 +> > **注意**：文中所有数据是**设计意图的示例**，不是从运行中的系统里导出的真实记录。标 🔴 的地方是当前尚未实现、走查到此会断的环节。 --- diff --git a/docs/todo/system-design/27-graph-agent-architecture.md b/docs/todo/system-design/27-graph-agent-architecture.md index 61d3b91..45a2ba8 100644 --- a/docs/todo/system-design/27-graph-agent-architecture.md +++ b/docs/todo/system-design/27-graph-agent-architecture.md @@ -253,6 +253,7 @@ P0 阶段的处理方式是**迁移脚本层面的临时保护**：`system_agent ### 关联文档 +- **[27-REQ 原始需求](./27-requirement.md)** — **需求源头**：用户原话照搬 + 需求→设计落点速查。其余文档都是对它的转述，出现"当初到底怎么说的"争议时以这份为准。 - **[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 / 图 / 成本估算 / 断点清单）。实现时的靶子与端到端验收场景。 diff --git a/docs/todo/system-design/27-requirement.md b/docs/todo/system-design/27-requirement.md new file mode 100644 index 0000000..dfe001d --- /dev/null +++ b/docs/todo/system-design/27-requirement.md @@ -0,0 +1,169 @@ +# 27-REQ · 原始需求 + +> **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的需求源头文档。 +> **版本**: v0.1 +> **日期**: 2026-08-15 +> **定位**: **用户提出的需求原话照搬，再做结构化解析。本页是 27 系列所有设计决策的「源头」。** +> 格式与定位对齐仓库既有惯例 `docs/prd/newfunction/_spec/requirement.md`（DevLoop 的原始需求页）。 + +--- + +## 为什么需要这一页 + +27 系列其余文档（E2E / P2 / P3-P4 / EXAMPLE / NAMING）**全部是对下面这些原话的转述与结构化解读**，包括 `27-example-dev-company-walkthrough.md` 里那个「配图工厂」场景——那是为了走查而虚构的例子，不是用户给的。 + +转述会漂移。当出现「当初到底是怎么说的」这类争议、或者需要判断某个设计决策是不是过度解读时，**以本页为准**。 + +**照搬原则**：原文一字不改，含笔误（`validtor` / `syste agent` / `intergration` / `fin in` / `object-key result` 等）与不完整的句子，一律保留。笔误本身有时是理解意图的线索。 + +--- + +## R-1 · 起点：P2 对 P1 的依赖排查 + +> 你看一下todo 的 需求文档，p2 的部分有多少依赖于 p1 的实现 + +**落点**：无独立文档，结论并入 [27-P2](./27-p2-org-graph.md) §九。 + +--- + +## R-2 · 要一份 P2 详细设计 + +> 那你现在写一个新的 p2 的需求设计文档，来对 p2 的需求进行详细设计，任务划分 + +**落点**：[27-P2](./27-p2-org-graph.md)（初版 v0.1，后经 R-3 / R-10 两次重写） + +--- + +## R-3 · Org Graph 由第一个 agent 动态生成 + +> org graph 生成，应该由 company 的第一个 agent： org graph creator agent 来实现，根据这个公司的目标，描述，类型，来生成，比如要生成开发，还是运营，还是内容生成，会有多个不同的 org graph的模板，然后根据需求+agent list 动态来生成 org graph + +**落点**：[27-P2](./27-p2-org-graph.md) §4.1（`orggraph-planning` agent）、§4.6（`system/org-graph-templates/`） +**后续变更**：其中 `org graph creator` 这个名字在 R-12 的命名统一中改为 `orggraph-planning`。 + +--- + +## R-4 · 要一个执行控制台页面 + +> 我们需要一个新的页面，展示公司的 org graph 和每一个 org node 运行的 work graph，这个需求也需要设计一下，这个界面还需要设计一下 MVCP，数据库设计，界面设计，有启动，下一步，暂停，停止，重试这样的操作按钮，还需要展示每一个节点的运行日志，边的输入输出，loop 的划线，这些展示，还有主流程如何处理，异常流程如何处理，下钻的 sub agent 的流程如何处理和展示。 + +**落点**：[27-P3/P4](./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（最小可行范围）。 + +--- + +## R-5 · 手动 / 自动两种执行模式 + +> 对，而且运行有自动化和手动化两个选择，如果是手动，则 org graph，work graph 的执行是需要在界面上点击下一步下一步来完成，如果是自动则是授权自动从头到尾自动执行，一个节点完成则自动跳转到下一个节点执行 + +**落点**：[27-P3/P4](./27-p3-p4-work-graph-console.md) §四.C（`execution_mode ∈ {manual, auto}`，两者共用同一个 `advanceOne()` 原语，区别只在谁触发下一次调用） + +--- + +## R-6 · 完整的七阶段流程（核心需求） + +> 我说一下我理解的 process， 1， 用户新建一个 company 写入 company 的目标和描述2. company 默认有一个 org graph creator，根据用户描述，生成基础的 org graph，每一个 org graph node 可以从 system agent 中引用实现，也可以新建一个 system agent 来实现，比如开发 company，需要有 planner，code，validator 三个基础的 org graph 3. 用户输入一个具体的开发task， 4. org planner agent 作为执行 orggraph 的第一个节点，首先调用 planning work graph subagent，来规划执行 planning work graph 的这个任务，生成针对 planner agent 这个节点的 work graph，比如 brd->prd->sdd->benchmark->testdata->planner validtor->judge-loop-jump 来完成开发的第一个阶段需求planner的工作，这里面的每一个 work graph 节点都是一个 system agent 的引用，并且完成第一个 loop 闭环的跳转，如果成功则完成，如果有 bug 则跳转到对应的节点，让其只针对某一个部分开始修改。5 完成当前 org graph 节点工作，进入下一个 code graph node agent 的工作 6 code agent 也需要先调用 planning-work graph subagent 来设计 code work graph，可能是可以 fan out 并行多个 phase 的 code subagent->unit test 的开发，如果 unittest 有问题则loop 到 code subagent 来持续修改，全部并行完成后 fin in 节点到一个整合，->intergration test 来完成测试，如果有 bug 则判断是重新 planning 一个新的 work graph ，还是跳转到原有某个 work graph 节点来完成 7 codeagent 完成则进入全局的 validetor agent 来进行整体的判断，测试，审计，benchmark 的测试，test data 的测试等等，成功后完成，不成功则需要判断为什么会报错，是不是需要迭代某一个 syste agent 的 skill memory data llm 才能完成，先迭代 system agent ，再 loop 某个 work graph workflow ，再跑到 validator 验证，直至最后满足这个任务的 benchmark 或者 test data。 这个流程你整理成为一个文档，并且跟我们的 p2 设计比较，更新文档。 还有哪些没有考虑到的地方，这个流程是否是这样实现的？ + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) 全文（§三 七阶段逐段还原、§四 与既有设计的差异、§七 未考虑到的地方） + +**由此产生的三条核心结论**（[27-E2E](./27-e2e-task-execution-flow.md) §二）： +1. 这套流程 70-80% 已在 `docs/prd/newfunction/_spec/` 被完整设计过（DevLoop 的 L1/L2/L3） +2. DevLoop 是这套架构的一个硬编码实例 +3. 第七步「迭代 system agent」是真正全新的一层（后定名 L4） + +--- + +## R-7 · 更正：benchmark / test data 是 work graph 的节点，不是基础设施 + +> 我描述的 benchmark 和 test data 是 workgraph 的两个 subagent 节点，例如在code planner agent，他的 work graph里包含了要规划当前 goal task 的 benchmark 或者 test data 或者 test script 来完成最终对这个 goal 的验收，所以 work graph 里 就需要调用 code-planner-benchmark code-planner-test-data code-planner-test-script 这三个 system agent ，动态选择是否需要在 work graph 中加入这三个节点，还是只需要其中某一个，来完成 code planner。 + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) §十一（验收产出节点设计） + +**这条更正推翻了什么**：此前我把 benchmark / test data 理解成系统级基础设施，因而去核实 `benchmark-runner.js` 并判定「是假的、test data 不存在」。该判断与本需求无关——本流程根本不使用 `benchmark-runner.js`。 + +**后续变更**：文中的 `code-planner-benchmark` / `code-planner-test-data` / `code-planner-test-script` 三个名字，在 R-12 的命名统一中改为 `task-benchmark` / `task-test-data` / `task-test-script`（作用域从"父节点"改为"任务"）。 + +--- + +## R-8 · 是否需要独立的 example 文档 + +> 是否将我的描述的这个用户流程，更新迭代在文档里，并且作为一个 example 文档？ + +**落点**：[27-EXAMPLE](./27-example-dev-company-walkthrough.md) +⚠️ **注意**：该文档用的是虚构的「配图工厂」场景，**不是**本页 R-6 的原文。R-6 的原文只在本页。 + +--- + +## R-9 · 四个关键决策（回答确认问题） + +以下四条是针对具体设计分叉的定案回答，逐条照搬。 + +### R-9.1 · Org Graph 的定位（最大的架构分叉） + +> org graph 是由 company 级别生成的 workflow ，work graph 是由 org graph node 级别生成的 workflow 我不知道这个解释清楚了么？ + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) §五定案、[27-P2 v0.4](./27-p2-org-graph.md) §一、[27 号总纲 v0.3](./27-graph-agent-architecture.md) §二术语表 + §3.3 + +**推翻了什么**：P2 v0.1-v0.3 把 Org Graph 建模为静态汇报结构（边是 `reports_to` / `collaborates_with`），以及我提出的 A/B/C 三个折中方案，全部作废。新模型下两层图同构，共用一套 schema、引擎与 UI。 + +### R-9.2 · 元 Agent 继承 + +> 我们所有的org graph work graph 的 subagent 的 node agent，都是由一个元 agent 架构来继承生成的，统一有全局通用+公司/角色记忆分区 + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) §八bis + +**关联发现**：元 agent 在仓库里已有实物 —— `system/templates/base/`（"标准基座员工 Base Agent"），已强制 `RESEARCH → PLAN → EXECUTE → VERIFY` 四段式 + 阶段间 context flush + 换装元技能 + 失败写 `_lessons.md` 打回上一阶段。**它本身就是一个最小 work graph。** + +### R-9.3 · 验收产物由谁生成、由谁执行 + +> 验收产物在 org graph 中是由 planner 生成，由 validator 执行，每一个 node agent 的 benchmark 是由自身的 work graph 的 validator/test script/test benchmark/test script /节点来运行, + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) §11.3 + +**要点**：验收是**逐层递归**的——不是最外层一次总检，每一层图收尾都跑自己那层的验收；且执行由 agent 节点承担，不由引擎硬编码。 + +### R-9.4 · L4 拆成 company / general 两条通道 + +> 迭代 system agent 本体，也是分为 company 还是 general 的部分，company 的部分在运行过程中就需要自动迭代，general 的部分需要 system agent 的管理者 master agent 或者人工来驱动执行，比如每日定时或者手工执行agent dream流程来自我更新，根据今天所有的 company 执行的成功 失败 经验，来更新 general 的本体部分 + +**落点**：[27-E2E](./27-e2e-task-execution-flow.md) §八（L4-company / L4-general 对照表）、§8.1（agent dream 流程） + +**解决了什么**：此前我提出的「为修一个任务而改坏十家公司共用 agent」这一跨公司污染风险（原 §7.2），以及我给的三个缓解方案（fork 副本 / 只改私有 / 人工确认），因这条分层而全部不再需要——在线自动迭代永远只碰 company 分区，general 本体的更新被移出任务循环。 + +--- + +## R-10 · P2 重写 + 统一命名前缀 + +> 把 p2 文档按新的执行流边模型重写，仓库里的 benchmark 是 单 agent-benchmark 或者是 skill-benchmark ，给他们改个名字 ，我们这次聊的是goal-benchmark 或者 task-benchmark，我们在前面都统一加上前缀，包括 planner validator 也要加上 code-planner code-validator ，planning 是 workgraph-planning brd-planning，prd-planning orggraph-planning 这样起名，你可以统一排查一下 + +**落点**：[27-P2 v0.4](./27-p2-org-graph.md) 全文重写、[27-NAMING](./27-naming-conventions.md) 全文 + +**一处需要留意的取舍**：原话给了 `goal-benchmark` 或 `task-benchmark` 两个选项，最终选 `task-`。当时的理由是"`goal` 已被 OKR 体系占用"，但 R-11 决定把 OKR 从 `goal` 改名后，这个理由已不成立；保留 `task-` 的理由改为"验收标准的生命周期跟着一次 task 执行走，而 OKR 的 Key Result 是跨多个 task 的长周期度量"。**`goal-` 目前是空闲的，若要改回，全局换一个词即可。** + +--- + +## R-11 · OKR 正名 + +> okr 树应该叫做 object-key result ，可以修改一下，不要叫做 goal 了 + +**落点**：[27-NAMING](./27-naming-conventions.md) §六 + +**要点**：体系整体从 `goal` 改为 `okr`；且当前第 1 层节点也叫 "Goal" 是一处自我遮蔽，建议正名为 `Objective`（`O-001`），成为标准的 Objective → Key Result → Sub-Task 三层。代码层是真实数据迁移（9 条 API 路径 + `data/companies/{cid}/goals/` 磁盘目录 + `G-` ID 前缀写在已有 JSON 里），已给影响面清单，未执行。 + +--- + +## 附 · 需求 → 设计落点 速查 + +| 需求 | 一句话 | 主要落点 | +|---|---|---| +| R-3 | org graph 由第一个 agent 按公司描述动态生成 | P2 §4.1 / §4.6 | +| R-4 | 执行控制台页面（MVCP + 五个控制按钮 + 日志 + loop 划线 + 下钻） | P3/P4 全文 | +| R-5 | 手动 / 自动两种执行模式 | P3/P4 §四.C | +| R-6 | 七阶段端到端流程 | E2E §三 | +| R-7 | 验收产物是 work graph 的动态可选节点 | E2E §十一 | +| R-9.1 | **org graph = company 级 workflow；work graph = org node 级 workflow** | E2E §五 / P2 §一 / 总纲 §3.3 | +| R-9.2 | 所有 node agent 由元 agent 继承生成 | E2E §八bis | +| R-9.3 | 验收逐层递归，planner 生成、validator 执行 | E2E §11.3 | +| R-9.4 | L4 拆 company（自动）/ general（dream，人工或 master 驱动） | E2E §八 / §8.1 | +| R-10 | 统一命名前缀 | NAMING 全文 | +| R-11 | OKR 正名，不叫 goal | NAMING §六 | -- libgit2 0.21.4