From 54ee14eb497a8b2a9acf8a8f854db3373650f58a Mon Sep 17 00:00:00 2001 From: yibo Date: Thu, 20 Aug 2026 17:10:50 +0800 Subject: [PATCH] docs(27): P3C 收口归档 + §十七 清尾记录 + 各文档状态校准 --- docs/README.md | 12 +++++++++--- docs/done/system-design/27-p3c-batch3-handover.md | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/27-p3c-goal-task-model.md | 1311 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/system-design/27-graph-agent-architecture.md | 2 +- docs/todo/system-design/27-p3b-real-run-runway.md | 9 +++++++-- docs/todo/system-design/27-p3c-batch3-handover.md | 184 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/todo/system-design/27-p3c-goal-task-model.md | 1201 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/todo/system-design/27-requirement.md | 2 +- docs/todo/system-design/28-followups.md | 50 ++++++++++++++++++++++++++++++++++++++------------ 9 files changed, 1560 insertions(+), 1404 deletions(-) create mode 100644 docs/done/system-design/27-p3c-batch3-handover.md create mode 100644 docs/done/system-design/27-p3c-goal-task-model.md delete mode 100644 docs/todo/system-design/27-p3c-batch3-handover.md delete mode 100644 docs/todo/system-design/27-p3c-goal-task-model.md diff --git a/docs/README.md b/docs/README.md index 790f602..e8e9190 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,9 @@ 判断依据：文档正文的显式「状态」标记（✅ 已完成 / 已实现 vs 📝 设计中 / 未实现）、未勾选的 checklist，以及与代码库实际实现的交叉核对（见各条目备注）。 -> **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。该系列已完成的阶段文档（P1/P2）移入 `done/`，其余非主线待办在 `todo/future/`。 +> **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。 +> 该系列已完成的阶段文档（P1 / P2 / **P3 收尾 P3C**）移入 `done/`，其余非主线待办在 `todo/future/`。 +> **当前未完成的是**：P3B 真跑跑道的几条验收、P3/P4 那笔「真实路径 smoke 进 CI」的欠账、P4（未实现）、28-followups。 ## done/ @@ -24,6 +26,8 @@ | [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-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/01-26](./done/system-design/) | 系统设计正文 01～26 章（14、25-harness-engineering-improvements 例外，见 todo/future/；27 例外，见 todo/），各章节状态见文内「状态」标记 | ## todo/（当前主线） @@ -37,9 +41,11 @@ 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`），文档仍在补充中 | +| [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 条那笔欠账未还 —— 引擎用例一律注入假 executor / 假 planner，**没有一条真实路径的 smoke 进 CI** | +| [27-p3b-real-run-runway.md](./todo/system-design/27-p3b-real-run-runway.md) | P3 收尾之真跑跑道（从 mock 走到真 Claude CLI）— 📝 **仍在推进**。验收 7 ⛔ 真跑不成立（`readme-writer` 混进 org graph，未修）；2/4/8/9 未在干净环境验。缺陷② 的根因（边界守卫误判并行会话）已于 2026-08-20 修掉，但**根因修了不等于验收点验了** | | [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 可插队 | +| [27-p4-parallel-and-artifacts.md](./todo/system-design/27-p4-parallel-and-artifacts.md) | **P4（回收编号）并行执行与产物索引** — 📝 设计中，未实现。fan-out 真并发 + 同 agent 多实例隔离 + `files.json` 产物索引。三个 Phase，C 可插队 | +| [28-followups.md](./todo/system-design/28-followups.md) | 28 号（Agent 注册表统一）的遗留清单 — 主文档已在 `done/`，这份装没做完的：dream 机制（只有口述、无设计）、任务态清理（源码树无限增长）、`source_kind`/`legacy_path` 删列、三项「已实施未验证」。§五 是**已立起来的守卫清单**（别重复造，也别删） | ## todo/future/（暂缓，非当前重心） diff --git a/docs/done/system-design/27-p3c-batch3-handover.md b/docs/done/system-design/27-p3c-batch3-handover.md new file mode 100644 index 0000000..3fd50ba --- /dev/null +++ b/docs/done/system-design/27-p3c-batch3-handover.md @@ -0,0 +1,193 @@ +# 27-P3C 批 3 交接 —— main 上有一份待修复的代码 + +> 记录时间：2026-08-19 17:1x +> 记录人：Claude 会话 `lemonboss-8x`（本文档的作者，也是下面 87b776c / b0b2b62 两笔提交的执行者） +> 状态：✅ **已收口**（2026-08-20）。四条复核结论全部修完（记在 +> [27-P3C §15.3](./27-p3c-goal-task-model.md)），§五 那条卡住的 run 也已解开并真跑推进 +> （§17.4 / §17.5）。本文档从待办转为**事故记录归档**，留着是因为 §六 那几条协作规则 +> 是真踩出来的，不是纸上谈兵。 + +## 一句话 + +`87b776c` 把 lemonboss-78 还在等对抗复核的批 3 提进了 main，复核结论随后给出 4 条问题； +main 现在躺着一份**已知有缺陷**的代码，而那笔提交的说明里写着「1201 用例全绿」。 + +--- + +## 一、时间线（事实） + +| 时间 | 事件 | +|---|---| +| 会话启动 | 本会话拿到的 git status 快照里已有批 3 的全部在途文件（9 个未跟踪 + 一批 M） | +| 16:53 | 本会话完成三处控制台可见性修复（见 §三） | +| 16:54 | `npm run test:unit` → 126 文件 / 1201 用例全绿 | +| **16:56:24** | **`87b776c`** feat(27-P3C): 批 3 —— 队列 / 恢复路径 / 控制台三处修复 | +| **16:56:39** | **`b0b2b62`** fix(session-pool): SessionPool 空闲 TTL | +| 16:56:44 | `bash start.sh` 重启后端 + 前端（用户要求） | +| 17:05 | lemonboss-89 提交 `2092a2e`（精确提交，只含自己的文件） | +| 17:00 左右 | 批 3 的对抗复核结论出来：**1 条半修 + 3 条新引入** | +| 17:1x | lemonboss-89 跨会话核对，本会话确认两笔提交都是自己做的 | + +--- + +## 二、main 上现在有什么 + +### `87b776c` —— 批 3（作者：lemonboss-78，提交者：本会话，**未经作者同意**） + +内容：公司级任务队列（`task-scheduler.js`）、恢复路径补洞、控制台三处可见性修复。 +25 files changed, 5691 insertions(+), 305 deletions(-)。 + +**已知缺陷（来自 17:00 的对抗复核）：4 条 —— 1 条半修 + 3 条新引入。** + +> **2026-08-19 由 lemonboss-78（批 3 作者）补齐**：以下 4 条是 17:00 那次对抗复核的原文结论， +> 每条都有独立探针实跑证据。本文档作者原先只确知第 1 条、其余刻意留空——那个做法是对的。 + +**N1 🔴「取消排队」会留下一个还在烧 token 的孤儿子 run**（优先级最高，唯一有直接金钱成本的一条） +`company.js:1768` 的注释说「对一条还没开跑、没有子 run 的排队 run，`stopRun` 是多余的一圈」。 +**这个前提被批 3 自己的 `requeueBlockedRootRun` 改没了** —— `run_status='queued'` 的 run 现在可以是 +跑过一半的（有 success 节点、有 ready 节点、有活着的子 run）。探针实跑：取消后 root=stopped / +task=cancelled，而节点残留 `aa2:ready, aa1:success`（没批量 skipped），子 run 残留 +`paused / stop_requested=0`（没走 `suspendRunTree`）。 +失败路径：预算撞顶时子 run 可能仍是 `running`（引擎只把 root 置 blocked，子 run 要到节点边界才落 paused）→ +人点「启动」→ 退回队列 → 改主意点「取消排队」→ **那条 running 子 run 既没收到停止信号也没被结算，继续调 agent**。 +前端 `goal-task-model.js:171` 的按钮 title 还在说「它还没开跑，所以不会有半截产物」。 +命中入口三个：`/tasks/:id/cancel` 的 queued 分支、blocked 分支①、`DELETE /tasks/:taskId`。 + +**L1 ⚠️ 半修 · 恢复路径对 manual 任务不成立** +批 3 的修法是「恢复撞坑满 → 退回队列」，对 **auto 真的成立**（探针：T2 收敛后 T1 无人干预自动跑起来）。 +但 `tickInner` 第 4 步 `filter(t => t.execution_mode === 'auto')` 故意不碰 manual（§五.2bis「manual 不堵队」）， +于是 manual 任务：人点「启动」→ 退回队列 → 坑空了 → **没人来接**，任务躺着、sweep 每 60s 空转。 +而 `graph-engine.js:2345` 的注释白纸黑字写着「**「T1 永远回不来」这个后果因此消失**」——**对 manual 不成立**。 + +**N2 🟠「退回队列」这件事对用户完全不可见** +`startRunSync` 早返回 `{ok:true, runStatus:'queued', requeued:true}` 走 **200**。 +`GraphRunPane.act()` 只在 `!r.ok` 时写 `err` → 界面零提示；`can('start')` 因 `queued ∉ ALLOW.start` 把按钮全部置灰； +task 翻 queued 后 `hasStartedRun()` 返回 false → `GraphConsole.vue:248` 把 run 面板换成 org graph **定义视图**， +提示语「节点状态一律 pending」**是假的**（这条 run 有 success 节点、有活着的子 run）。 +`requeued` 这个字段**全前端零处读取**（`grep -rn requeued web/src` 无命中）。 +用户点了「启动」，得到的是：什么都没说、按钮全灰、图不见了。 + +**N3 🟠 `isSlotRaceError` 第三条判据的注释被探针证伪，且它吞真错误还不打日志** +`work-graph-db.js:110` 声称 `InvalidTransitionError` = 「这条 run 已被别人从 queued 推走了」。 +实跑证伪：被抢走后再 CAS **返回 0，不抛异常**；真正抛 `InvalidTransitionError` 的是**调用方声明了非法转换** +（`expected = from` 是调用方声明值，`canTransitionRun` 判的是 `expected → to` 而不是 `cur.run_status → to`）。 +所以这条判据把「调用方写错了转换」当成竞态吞掉，且不留日志。 + +> 这 4 条里有 3 条是同一个模式：**注释承诺的前提被本轮自己的改动改没了，注释还留着**。 +> 27-P3C §十三.3 / §十四.4 已经就这个模式立过两次案，这是第三次。 + +> 提交说明里的「126 文件 / 1201 用例全绿」**需要更正**：这句话准确描述了 16:54 那次测试运行， +> 但它压在一份尚未通过复核的代码上，读起来像质量背书，替 lemonboss-78 说了它没说过的话。 + +### `b0b2b62` —— SessionPool 空闲 TTL（作者：lemonboss-89，提交者：本会话） + +给图执行侧的常驻会话上空闲 TTL，堵住「一节点一进程、永不释放」的泄漏（实测 23h 漏 7 个进程）。 +自带 3 个测试，全过。**lemonboss-89 已确认认这笔**，内容无争议，提交信息是替它写的。 + +### `2092a2e` —— agent-chat 会话回收补漏（作者/提交者：lemonboss-89） + +精确提交，未波及他人在途文件。无争议。 + +--- + +## 三、本会话自己写的三处控制台可见性修复 + +这三处是本会话的原创工作，混在 `87b776c` 里（`GraphConsole.vue` 同文件内与批 3 的改动交织， +无法干净拆分）。**内容与批 3 的 4 条缺陷无关**，处理批 3 时不必连带回退。 + +| # | 症状 | 改在哪 | 验证 | +|---|---|---|---| +| 1 | 顶栏墙钟恒 `now - started_at`，没有终点：一条昨晚就 blocked 的 run 第二天还在涨到「16h 58min」，而那是页面上唯一的时间信号 ——「已停等人处置」被显示成了「还在跑再等等」 | `web/src/views/GraphConsole.vue`：终点取 `run.updated_at`，run 不在 `running/planning` 就冻结并标「已停」 | ✅ 浏览器实测：`16h 58min` → `31min 已停`（31min 是真实耗时） | +| 2 | 越界日志只报「留下 N 处改动」，文件清单只在 `timeline.ndjson` 里，界面翻不到。而判罚就是按这份清单下的 | `web/src/components/graph-console/node-signals.js`：`describeEvent` 拼进 `entries` | ✅ 浏览器实测：显示出 `?? server/tests/unit/task-scheduler.test.js` | +| 3 | run 收敛成 blocked 时只写 task 状态不写原因，任务列表那行只剩一个橙色「挂起」，必须逐层点进 org 图 → work 图 → 节点详情才知道发生了什么 | `server/services/task-settle.js`：新增 `describeRunBlock`，把「哪个节点 + fail_reason + 判词摘要」写进 `tasks.blocked_reason` | ⚠️ 仅单测（`server/tests/unit/task-blocked-reason.test.js`，5 例；注释掉修复后红 4 例）。界面上看不出效果 —— `blocked_reason` 是 run 收敛那一刻写的，存量 run 补不上 | + +第 3 条顺带把一条口头约束变成了会红的测试：原因串**绝不能**以 `UPSTREAM_BLOCK_PREFIX` +（`upstream_failed:`）开头，否则会被调度器当成「依赖推导出的 blocked」自动推回 queued， +而这类 blocked 本来就等着人处置。原先这只是 `noteTaskBlockedReason` 上的一句注释。 + +--- + +## 四、待决策：`87b776c` 怎么处理 + +**不由本会话决定。** 本会话的判断，供参考： + +- ❌ **revert 恐怕是最差的选项**。截至 17:1x，lemonboss-78 已经在 `87b776c` 之上叠改动了 + （`task-scheduler.js` / `work-graph-db.js` + 4 个测试文件正在改）。revert 会把这些在途工作的地基抽掉。 +- ✅ **倾向修复前推**：把复核的 4 条作为后续提交解决，孤儿子 run 那条优先。 +- 📝 无论走哪条路，`87b776c` 说明里的「1201 用例全绿」都该有一条更正记录（本文档即是）。 + +--- + +## 五、还没解决的原始问题：一条卡住的 run + +这才是本会话最初被叫来看的东西，**至今没动**。 + +- 目标 `G-msyu6u9a-90cf` / 任务 `T-msyu6u9b-939c`（公司 `e2e-demo`，做 lemonai 官网） +- root run `run_9168bd24f46c` → work run `run_ee90c4e35f9f`，2026-08-18T16:19:36Z 收敛为 `blocked` +- 死在 `org-planner-sdd`，`fail_reason = boundary_escape` +- **这次判罚是误伤**：守卫抓到的 3 处改动（`M server/services/graph-run-sse.js`、 + `?? server/services/task-scheduler.js`、`?? server/tests/unit/task-scheduler.test.js`） + 正是当时并行会话在写批 3 的文件，不是 agent 写的 +- 预算远未耗尽：7/100 次调用、69,961/5,000,000 tokens + +### 界面上怎么重跑（不需要命令行） + +两个 🔁重试 按钮，各作用于自己那一层，**选中一个 `fail`/`blocked` 节点才亮**： + +- **左栏点 `org-planner` 重试** → 子图里没有待跑节点 → `resetRunNodes`：整张 work graph 作废重跑（brd/prd 也重来） +- **中栏点 `org-planner-sdd` 重试** → 只把这一个节点打回 ready。**自足**：子图跑完后 + `reviveParentFromChild` 会自动把父节点和父 run 从 blocked 拉回来 +- **顺序有影响**：先中栏单点重试、再左栏点 org-planner，那时子图里有 ready 节点 → + 左栏那一下变成「定点重置」而不是整张图重跑 + +### ⚠️ 重跑的前提 + +**工作区必须是干净的。** 边界守卫比对的是 agent 调用前后的整仓 `git status` 差集， +只要还有人在写这个 worktree，跑起来的节点就会再被误判一次 —— 白烧一轮预算。 +截至 17:1x 工作区仍有 13 个文件在改动中。 + +> 顺带：这条误伤暴露了守卫的一个结构性上限 —— 整仓 git status 的差集里**没有「谁写的」这一维**。 +> 多会话共用 worktree 时它必然误判。`splitUnattributable` 已经为 `system/agents/` 开了「保留证据、 +> 放弃判罚」的口子，同样的思路能不能推广到「调用窗口内有其他写入者」，值得单开一条 followup。 + +--- + +## 六、协作规则（这次踩实的） + +多个 Claude 会话共用 `/Users/yibo/Documents/lemonAI/lemonboss` 同一个工作目录、同一个 git HEAD。 + +1. **会话启动时系统给的 git status 快照，不是「用户自己的在途工作」的证据。** + 它只是「此刻工作区长这样」，里面大概率有别的会话正在写的东西。 + 本次事故的根因就是把快照当成了归属证明。 +2. **「用户让我提交工作区」≠「工作区里的东西都归用户」。** 逐文件确认归属。 +3. `git commit -- <自己的文件>` 精确提交。注意：**`git add <显式列表>` 一样会中招** —— + 出事的是列表内容，不是有没有用 `-A`。 +4. 判断某文件是不是别人的：看 mtime / `find . -newermt '-20 minutes'`。 + **对话进行中才变的文件 = 有人正在写**，一律先 SendMessage 问。 +5. commit message 里的「N 个测试全绿」只描述那一次测试运行。 + 压在别人还没复核完的代码上时，它会替对方说出没说过的话。 +6. 任何 `checkout` / `restore` / `stash` / `reset` 前先问，不论范围多小。 + +--- + +## 七、下一步 —— 全部完成（2026-08-20 回填） + +- [x] ~~lemonboss-78 补齐 §二 里缺的 3 条复核结论~~ —— 已补齐并提交（`5a31d00`），4 条均带独立探针实跑证据 +- [x] 定 `87b776c` 的处理方式 —— **修复前推**，4 条作为后续提交解决 +- [x] **N1** 孤儿子 run —— 改为无条件走 `engine.stopRun`（[27-P3C §15.3](./27-p3c-goal-task-model.md)） +- [x] **L1** manual 的恢复出路 —— 判据用 `attempt > 0` 而**不是** `started_at`（后者看着更贴切，但 `requeueBlockedRootRun` 退回队列时会把它清成 NULL，恰好在需要它的那一刻是空的，实测踩过） +- [x] **N2** 「退回队列」透出到界面 —— 加 `notice` 一行明说「已退回队列排队，坑一空会自动接着跑」 +- [x] **N3** `isSlotRaceError` —— 探针证伪后**删掉该分支**（被推走时条件更新返回 0、不抛；真正抛它的只有「调用方声明了非法转换」，那一支把调用方的 bug 当竞态吞掉且不留日志） +- [x] 重跑 `T-msyu6u9b-939c`（见 §五）—— ✅ **2026-08-20 已解开并推进**，见 [27-P3C §17.4 / §17.5](./27-p3c-goal-task-model.md) +- [x] 给边界守卫加「多写入者 → 放弃判罚」的口子（§五 末尾）—— ✅ 已加，见 [27-P3C §17.2](./27-p3c-goal-task-model.md) + +> **§五 那条 run 的结局值得单独记一句**：本文档判断「它卡住是因为边界守卫误伤」， +> 这一半是对的 —— 但守卫修完之后**它仍然跑不动**。第二道锁在墙钟预算上 +> （`blocked` 挂起等人的时间被算进「已用」，过夜的 run 永远醒不过来）， +> 那把锁只有真去点一次重试才露出来。 +> **「修完 A 就能跑」是个假设，不是结论 —— 卡住的东西可以有不止一把锁。** + +> §二 那条「注释承诺的前提被本轮自己的改动改没了，注释还留着」已经是第三次立案 +> （§十三.3 / §十四.4 / 本次）。第三次就不该再只当个案记 —— 值得考虑一条机器可查的守卫： +> 注释里出现「因此消失 / 不再可能 / 已经不会」这类**断言性承诺**时，要求同处留下可执行的判据引用。 +> 这条只是提议，归 lemonboss-78 判断要不要立。 diff --git a/docs/done/system-design/27-p3c-goal-task-model.md b/docs/done/system-design/27-p3c-goal-task-model.md new file mode 100644 index 0000000..6eef668 --- /dev/null +++ b/docs/done/system-design/27-p3c-goal-task-model.md @@ -0,0 +1,1311 @@ +# 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 真跑跑道](../../todo/system-design/27-p3b-real-run-runway.md)。 +> **日期**: 2026-08-18 +> **状态**: ✅ **已完成并归档**（2026-08-20）。五批全部实施（§十三 ～ §十六），§15.5 / §16.8 的后续项也已全部收掉（§十七）。 +> 138 文件 / 1292 测试全绿，`web:build` 通过。**真跑验收见 §17.5** —— 返工闭环第一次由真 agent（不是注入的假 executor）走通。 +> **⚠️ 批次与 phase 的对应不是一一对齐的**，判断「这份能不能搬进 done」时按批看，别按文档名看： +> · **批 1-3 = 真正的 P3 收尾**（goal/task 两级模型 + `task-planning` + 排队），本文档的主体； +> · **批 4（并行）归 [27-P4](../../todo/system-design/27-p4-parallel-and-artifacts.md) §一.3**，那边是设计权威，本文档只服从（见 §五.2 的警示块）； +> · **批 5（两套任务体系统一）不属于任何既有 phase** —— 是跨阶段的技术债清理，风险面也与前四批完全不同（坏了是所有 agent 互相派不了活），见 §十二.6。 +> **交付物**: ① `goals` / `tasks` 两张表，把「人类下达的需求」与「lemonboss 执行的单元」拆成两级；② 基于这两张表的**排队与并行**；③ 执行控制台（`/:id/graph-console`）最左侧新增**目标·任务两级列表栏**。 +> **命名**: 全文遵循 [27-NAMING](../../todo/system-design/27-naming-conventions.md)，本文档**落地**的正是它 §四 定义但代码里一直没有载体的 `goal 1 : task N` 基数关系。 +> **代码引用体例**: 沿用 27-P3/P4 头部约定 —— 只写 `文件名` + 函数名 / 常量名，**不写行号**。 +> +> **第二轮（2026-08-18，逐条对着代码复核初稿）**：抓到 7 处「照初稿实现就会出 bug」和 6 处补漏，正文已改，关键的错误结论**留档不删**（§三 的 ⚠️ 块、§五.1、§九.1 开头），因为它们是最容易再犯一次的那类。 +> ① **`createRun` 在建行的事务里就把 `graph_run_nodes` 按定义全插好了** —— 初稿三处基于「queued run 没有节点行」的论证全部作废（§三 / §四.3 / §九.1）； +> ② 由 ① 派生出一个**既存但被排队放大成必然事件**的缺陷：节点行在入队时快照、定义却是读时取最新，**排队期间 replan 会让 run 出队即卡死**（§四.3 末，新增 `syncRunNodesToDef`）； +> ③ 出队原语写错了 —— `markRunReady` 把 `from` 写死成 `planning`，复用不了；正解是 `updateRunStatus(runId,'queued','ready')`（§五.1）； +> ④ 唯一索引冲突是 **throw** 不是 `changes = 0`，初稿的错误处理只覆盖了一半（§五.1）； +> ⑤ **触发点枚举本身是漏的**：`stopRun` 与「预算耗尽 → blocked」两条最常见的释放路径都**不走 `settleRun`**，改为挂在唯一漏斗 `transitionRun` 上（§五.1.1）； +> ⑥ `report_to` 只活在请求闭包里，排队后**回调链路静默断掉**；`okr_node_id` 逐 task 下发会**反复覆写同一个 OKR 节点**（§四.7 两条禁令）； +> ⑦ **manual 任务会永久堵住队头**（占着 `running` 等人点「下一步」），改为不参与自动出队（§五.2bis）。 +> 补漏：存量回填脚本（§四.8，不做的话批 1 反而让历史任务更看不见）、任务级 `rerun` 与节点级 `retry` 的命名撞车（§六.3）、`queuePosition` 排序口径必须与调度器同源、砍掉没有消费方的 `goals.budget_json`（§十一.6）。 +> +> **第三轮（2026-08-18，四条口径由用户定案 → 27-REQ R-20.5）**：① **`task-planning` agent 提进 v1**（原计划 v2），新增 §四.9，批 2 范围与工作量随之变化；② 并行仍按批 4 单独排期，v1 只做排队（`max_parallel_tasks = 1`，唯一索引不动）；③ manual 任务不参与自动出队（§五.2bis）；④ 上游失败 → 下游自动推导为 `blocked` 并标红（§五.1.2）。 +> 定案 ① 连带牵出一处新缺陷：**`task-planning` 跑在 goal 层、任何 run 存在之前，它烧的 token 没有预算池可扣** —— 正是 `defaultPlanWorkGraph` 注释里点名的「隐形的一半花费」的新实例。上一轮刚以「零消费方」为由砍掉的 goal 级预算字段，因此以记账字段 `planning_tokens` 的形式回来（§四.1）。 +> +> **第四轮（2026-08-18，五条口径由用户定案 → 27-REQ R-20.6）**：① 退役 `/goals` 两个 OKR 别名**确认执行**；② **goal 级验收仍用 `org-validator`**，在 goal 层再调一次（新增 §四.10，goal 状态机加 `failed`）；③ **预算先不考虑**，不做 goal 级闸门，但保留 `planning_tokens` / `validation_tokens` 两个记账字段；④ **`queued` 开放改 `depends_on`**（§六.3）；⑤ **两套任务体系统一到 `tasks` 表，删掉会话反推那套**（新增 §十二 = 批 5）。 +> 定案 ⑤ 核实后有个反直觉的前提必须先说清：**两套不是并列的，A 的回调链路长在 B 身上** —— `reportRunOutcome` 收敛后调的正是 `/api/agent/task/report`。所以「删掉另一套」= 删**存储与会话反推**，**不能**删入口与回调（`/task/dispatch` 的 URL 与请求体写在 `tools-base.md` 里，改它等于同时改所有 agent 的提示词）。开放问题 2 / 4 / 6 / 7 全部就此关闭。 + +--- + +## 一、问题 + +用户的原话是「一个 company 在控制台下达任务只能有一个」。拆开是**三件事**： + +| # | 现象 | 真实成因 | 本次 | +|---|---|---|---| +| A | 历史任务**看不见、切不了、管不了** | 纯界面缺失。`GraphConsole.loadRuns()` 拿到了全部 root run，却只取 `roots.find(active) \|\| roots[0]`，其余全丢 | ✅ §七 | +| B | 一家公司**同时**只能跑一个，下第二个吃 409 | v1 硬约束：`work-graph-db` 的 `idx_graph_runs_one_active_root` 唯一索引 + `company.js` 的预检查。当时选「拒绝」而不是「排队」的理由写在代码注释里 —— **仓库里没有任何出队 worker，排进去的任务不会被消费，那是一条会静默丢任务的路** | ✅ §五 补上调度器，约束从「拒绝」改成「排队」 | +| C | 「人类提的需求」和「机器执行的单元」是**同一个东西** | `POST /api/company/:cid/tasks` 一次调用同时创造了需求、执行单元和执行实例三层语义，压在一条 root run 上。于是需求无法分解，也就无从并行 | ✅ §三 / §四 | + +C 是根因，A 和 B 是它的两个表征。**先拆两级模型，A/B 才有干净的解法。** + +--- + +## 二、与既有命名的对齐（先读这一节） + +### 2.1 这不是新概念，是给一个已存在的悬空外键补上它的表 + +[27-NAMING §四](../../todo/system-design/27-naming-conventions.md) 早已定义好基数： + +| 概念 | 基数 | 定义（原文） | +|---|---|---| +| **goal** | 一个人类需求描述 = **1 个** | 验收的边界。回答「这次交付到底算不算满足了人提的要求」 | +| **task** | 一个 goal 分解出 **N 个** | 图中的执行单元。**可并行**、可下钻 sub agent | +| **okr** | 跨多个 goal 的长周期度量树 | Objective / Key Result | + +而 `graph_runs` 里： + +```sql +goal_id TEXT, -- 全仓库**没有任何写入方**，只有 body.goal_id 透传 +task_id TEXT, -- 由 POST /:cid/tasks 现生成，无表、无唯一性保证 +``` + +`company.js` 那条注释写得明明白白：`goal_id?, okr_node_id?, 三者基数不同不可混用（goal 1 : task N : okr 跨 goal 度量树）`。**字段在、语义在、表不在。** 本文档做的就是把这两张缺席的表补上，不是发明新词。 + +### 2.2 「goal」一词的六个用法消歧（实现前必须分清） + +| 写法 | 指什么 | 载体 | 本次是否新增 | +|---|---|---|---| +| `company-goal` | 建公司时那句定性目标 | `company.json.goal` | 否 | +| **`goal`（本文档）** | **人类下达的一个需求 = 验收边界** | **新 `goals` 表，`G-xxx`** | ✅ 新增 | +| `task-goal` | **一个 task** 的验收边界（= 该 task 的描述） | `runs/{runId}/artifacts/task-goal.json` | 否，位置不变 | +| `subtask-goal` | work graph 内分支的验收边界 | `workgraph-planning` 拆分时产生 | 否 | +| OKR `Objective` | 长周期度量树，`O-xxx` | `data/companies/{cid}/okr/` | 否 | +| `goal-benchmark` / `goal-test-data` / `goal-test-script` | 三种**验收产物**（agent / 节点名） | work graph 节点 | 否 | + +> **注意 `task-goal` 的归属没变**：它是「一次 task 执行的验收边界」，artifact 本来就落在 `runs/{runId}/` 下 —— 也就是**每个 task 一份**。引入 goal 表后它的位置和语义都不用动，goal 的描述是它的**上级**，不是它的替代。 + +### 2.3 `G-` 前缀可以用，`/api/company/:cid/goals` 可以要回来 + +两处历史包袱都已经清干净，实地核实过： + +1. **`G-` 前缀已被 OKR 释放**。27-NAMING §六 的迁移把 OKR 第 1 层 `G-001` 正名为 `O-001`（`npm run okr:migrate` 已执行，且当时存量数据「几乎为空」）。所以新 `goals` 表用 `G-` 不与任何活数据冲突。 +2. **`/api/goals` 与 `/api/company/:cid/goals` 目前是 OKR 的向后兼容别名，但全仓库零调用方**。grep 的结果只有三行，全是别名注册语句本身（`index.js` / `agent-server.js` / `okr.js` 的注释）。**本次连带退役这两个别名**，把路径要回来给新概念 —— 一个词在同一套 API 里指两件事，是比破坏兼容更贵的债。 + +--- + +## 三、模型：goal → task → run 三级 + +``` +goals (G-xxx) 人类下达。一条 = 一个需求 = 一条验收边界 + │ 描述一经下达不可改（§四.4） + └─ tasks (T-xxx) N 条。lemonboss 的执行单元，可排队、可并行、可有依赖 + │ 描述一经下达不可改（§四.4） + └─ graph_runs root run，M 条。一次**执行实例**（重试会产生第 2 条） + └─ 子 run 每个 org node 现规划出的 work graph，及更深的子图 +``` + +三级各自回答一个问题，不重叠： + +| 层 | 回答的问题 | 谁改它 | 状态机 | +|---|---|---|---| +| goal | 人想要什么？做到了没有？ | 人 + **goal 级 `org-validator`**（§四.10）| `draft → planning → active → done / failed / cancelled / archived` | +| task | 这个需求拆成哪几件事？谁先谁后？ | **`task-planning` agent 拆、人可改**（§四.9）| `draft → queued → running → completed / failed / blocked / cancelled` | +| run | 这一次跑成什么样？ | 引擎 | 既有 `RUN_TRANSITIONS` + 新增 `queued`（§四.3） | + +**为什么 task 与 run 必须分开**（「不能直接把 task 当 root run」的三条硬理由）： + +1. **重跑是 task 1 : run N**。今天「重跑一遍这个任务」只能新建一条毫不相干的 run，两次执行在数据上没有任何关联；有了 task 表，run 挂在 task 下，「这个任务试了 3 次、第 2 次卡在哪」才说得出来。 +2. **依赖与并行是 task 之间的关系**，不是 run 之间的。`depends_on` 只有落在稳定的 task id 上才有意义 —— run id 每次重跑都变。 +3. **run 是「某一版图的执行快照」，task 是「人要做这件事」的意图**。`createRun` 在建行那一刻就按当时的 org graph 把 `graph_run_nodes` 全部插好（§四.3 核实），一条 run 因此天然绑死一个图版本；而意图必须跨图版本存活 —— 排队期间 org graph 被重新规划，正是这个区分的用武之地（§四.3 末）。 + +> ⚠️ **初稿在这里的第一条理由是错的**，留档以免再犯：初稿写「排队态没有 run，硬塞一条 run 行进去 `graph_run_nodes` 是空的」。核实 `createRun` 后 —— 它的事务里就按 `readDefGraph` 把节点行全插好了，**queued run 有一整套 `pending` 节点**，与 ready run 的唯一差别就是 `run_status`。结论（两级必须分开）不变，理由换成上面三条。 + +--- + +## 四、数据模型 + +DB 文件复用 `data/graph.sqlite`（`graph-db.js` 的 `getDb()`，WAL + `foreign_keys=ON` 已设好），与 `graph_runs` 同库同连接。迁移写法照抄 `work-graph-db.js` 现有的「存量库迁移」块（`hasColumn` 判断 + `ALTER TABLE ADD COLUMN`）。 + +### 4.1 `goals` 表（新） + +```sql +CREATE TABLE IF NOT EXISTS goals ( + id TEXT PRIMARY KEY, -- G-{base36}-{4hex}，见 §四.5 + company_id TEXT NOT NULL, + title TEXT NOT NULL, -- 短标题，列表显示用；可改 + description TEXT NOT NULL, -- 人类需求原文 = 验收边界；下达后不可改 + status TEXT NOT NULL DEFAULT 'draft', + -- draft | planning | active | done | failed | cancelled | archived + -- planning = task-planning 正在拆分（§四.9），是个真会持续几十秒的状态 + -- failed = goal 级验收没过，或有 task 未能 completed（§四.10）；可回 active 补 task 重下 + priority TEXT NOT NULL DEFAULT 'P1', + okr_node_id TEXT, -- 可选，挂到 OKR 度量树的哪个节点（O-001.1.1） + created_by TEXT, -- 'human' | agent id（Master/CEO 代下单） + report_to TEXT, -- 收敛后要唤醒的上级 agent，见 §四.7 + planning_tokens INTEGER NOT NULL DEFAULT 0, -- task-planning 拆分烧掉的 token（§四.9） + validation_tokens INTEGER NOT NULL DEFAULT 0, -- goal 级 org-validator 烧掉的 token（§四.10） + verdict TEXT, -- goal 级验收判词（org-validator 的原话），§四.10 + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + dispatched_at TEXT, -- 首次下达时间；非空 = 描述已冻结 + archived_at TEXT +); +CREATE INDEX IF NOT EXISTS idx_goals_company ON goals(company_id, status); +``` + +**没有 `budget_json`，但有 `planning_tokens`**：预算**闸门**是按 root run 算的（`DEFAULT_TASK_BUDGET` 只挂 root run，子 run 一律上溯 `root_run_id` 扣同一个池），goal 级预算没有任何执行机制，加一个没人消费的额度字段就是这个仓库反复被咬的「实现在、零调用方」。 + +但 `task-planning` 定案进 v1 之后，**goal 层出现了一笔真实、且没有池子可扣的花费**：它跑在任何 run 存在之前。`defaultPlanWorkGraph` 的注释已经把这个病点过名 ——「规划调用也是真花钱的一次 agent 调用，token 必须计入同一个 root run 预算池，否则『一层规划 + 一层执行』里有一半的花费是隐形的」。goal 级拆分正是那个「隐形的一半」的新实例，所以**必须记账**（`planning_tokens`），哪怕暂时不设闸门。goal 级总额**控制**仍留到 §十一.6。 + +`okr_node_id` 放在 goal 上而不是 task 上：OKR 度量的是「人的需求达成了没有」，那正是 goal 的粒度 —— 具体的实现禁令见 §四.7，那不是一句设计倾向，是照现有代码顺手写就会踩的坑。 + +### 4.2 `tasks` 表（新） + +```sql +CREATE TABLE IF NOT EXISTS tasks ( + id TEXT PRIMARY KEY, -- T-{base36}-{4hex} + goal_id TEXT NOT NULL REFERENCES goals(id), + company_id TEXT NOT NULL, -- 冗余一份：调度器按公司选任务，避免每次 JOIN + seq INTEGER NOT NULL, -- goal 内序号，列表排序用（1,2,3…） + title TEXT NOT NULL, + description TEXT NOT NULL, -- 落进 task-goal.json 的那句；下达后不可改 + status TEXT NOT NULL DEFAULT 'draft', + -- draft | queued | running | completed | failed | blocked | cancelled + execution_mode TEXT NOT NULL DEFAULT 'manual' CHECK (execution_mode IN ('manual','auto')), + depends_on TEXT NOT NULL DEFAULT '[]', -- JSON 数组，同 goal 内的 task id + budget_json TEXT, + current_run_id TEXT, -- 最近一次 root run（逻辑外键，见 §四.6） + attempt INTEGER NOT NULL DEFAULT 0, -- 起过几次 run（任务级重跑，≠ 节点级 retry） + report_to TEXT, -- 从 goal 继承或调用方指定；见 §四.7 + created_by TEXT, -- 'task-planning' | 'human'：这一条是拆出来的还是人加的 + blocked_reason TEXT, -- status='blocked' 时的原因，如 upstream_failed:T-xxx + priority TEXT NOT NULL DEFAULT 'P1', + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + queued_at TEXT, -- 入队时间；非空 = 描述已冻结 + started_at TEXT, + finished_at TEXT, + archived_at TEXT +); +CREATE INDEX IF NOT EXISTS idx_tasks_goal ON tasks(goal_id, seq); +CREATE INDEX IF NOT EXISTS idx_tasks_queue ON tasks(company_id, status, priority, created_at); +``` + +**`depends_on` 一个字段同时表达串行与并行**，不另设 `parallel_group`： + +- `[]` → 无前置，可立即入队 → 同一 goal 下多个空依赖的 task **天然并行**（能不能真并行由 §五.2 的并发上限决定）。 +- `["T-a"]` → 等 `T-a` 到 `completed` 才可调度 → **串行**。 +- 多个元素 → 汇聚点（fan-in）。 + +也就是说 goal 内部就是一张 task DAG。校验：写入时查环（`depends_on` 只能引用同 goal 内已存在的 task），有环 `400`。 + +### 4.3 `graph_runs` 新增一个 run status：`queued` + +**这是本次唯一动到既有运行时表的地方。** `run_status` 列上没有 CHECK 约束（只有 `graph_kind` / `execution_mode` 有），所以加值不需要改表，只要给 `work-graph-db` 的 `RUN_TRANSITIONS` 加一行： + +```js +queued: ['ready', 'stopped'], // 出队 = queued → ready；取消 = queued → stopped +``` + +**为什么有了 tasks 表还需要它**（否则确实是冗余的第二套排队状态）—— 只有一个理由，但足够硬： + +> **它把「出队」这个并发临界区交给已有的唯一索引兜底。** +> +> 调度器出队时，如果先 `INSERT` 一条 `ready` 的 run，两个并发的 tick 会各插一条，超发。而 `idx_graph_runs_one_active_root` 的 `WHERE` 覆盖 `ready/running/paused`、**不覆盖 `queued`** —— 于是：入队时创建 run 行为 `queued`（不占坑，可以有任意多条），出队时做一次 `UPDATE ... SET run_status='ready' WHERE id=? AND run_status='queued'`，**超发的那一条会被唯一索引直接拒绝**，而不是靠应用层的「先查后插」（那中间永远有竞态窗口）。 + +顺带三个收益：入队即有稳定的 `run_id`（可分享的控制台链接）、`task-goal.json` 的落盘路径 `runs/{runId}/artifacts/` 在入队时就确定（描述冻结点与 artifact 落盘点重合，见 §四.4）、timeline 上能记下「何时入队」这条审计事实。 + +#### 代价：入队即建行 = 节点行在入队时就被快照，出队前必须重新对齐 + +`createRun` 的事务里会按 `readDefGraph(graphKind, graphId)` 把 `graph_run_nodes` **一次插全**（每个 def node 一行 `pending`）。而 `getRunState` 是**每次读都重新读当前定义**，org run 的 `graph_id` 就是 `company_id` —— 也就是说定义那一侧永远是「此刻最新的 org graph」。 + +于是排队期间有人点了「重新规划组织」（`ReplanOrgGraphButton`，一个一等的用户操作）： + +- 被删掉的节点 → 留下孤儿 run 行，`getRunState` 里 `defById.get()` 取到空对象，名字/类型全空； +- **新增的节点 → 根本没有 run 行 → 永远不会被拾取执行 → 这条 run 出队后必然卡死**。 + +> **这个洞今天就存在**（一条跑了一小时的 run 期间 replan，同样中招），只是今天 createRun 到 startRun 之间只隔几行代码，窗口是毫秒级。**排队把窗口放大到小时级，从理论缺陷变成必然事件。** + +定案两条，缺一不可： + +1. **出队时重新对齐节点行**：`queued → ready` 之前先按当前定义补齐缺失的 node 行、删掉孤儿行（都还是 `pending`，没有任何执行痕迹会丢）。这一步做成 `syncRunNodesToDef(runId)`，`stopped`/`completed` 的 run 一律不碰。 +2. **replan 时把该公司所有 `queued` run 标记为待对齐**（或直接就地跑一次上面的 sync）。理由是别让「出队时才发现图变了」成为唯一防线 —— 那时用户已经在等这条任务跑起来了。 + +> ponytail: 出队对齐是「定义变了就补行」的最小实现，它默认**新节点从 pending 开始**是安全的（queued run 本来一个节点都没跑过）。一旦将来允许对**跑到一半**的 run 做 replan，这个函数就不够用了，必须升级成带 `contract_hash` 判据的级联重置（`loops-l3.md` 已有那套四分类）。 + +状态机全貌： + +``` +task: draft ──提交──▶ queued ──调度器出队──▶ running ──┬─▶ completed + │ ├─▶ failed + cancelled ├─▶ blocked ──重试──▶ queued + └─▶ cancelled + +run: queued ──▶ ready ──▶ running ──┬─▶ completed / failed / blocked / stopped + │ └─▶ paused ──▶ running + stopped （既有转换全部不变） +``` + +### 4.4 描述冻结（用户要求 3） + +| 对象 | 可改字段 | 冻结点 | 冻结后改会怎样 | +|---|---|---|---| +| goal | `title` / `priority` / `okr_node_id` | `dispatched_at IS NOT NULL`（首个 task 入队）后 **`description` 冻结** | `409` | +| task | `title` / `priority`（`depends_on` 仅 draft） | `queued_at IS NOT NULL` 后 **`description` / `execution_mode` / `budget` 冻结** | `409` | + +**这不是保守，是数据一致性的硬要求**：task 的 description 在入队时就写进了 `runs/{runId}/artifacts/task-goal.json`，而 `describeTask` 等 agent 侧链路读的是 artifact。改库不改 artifact 会让两份记录对不上；两份都改则等于篡改已被 agent 消费过的审计输入。**要改就取消后新建**，错误响应里直接给这句 hint。 + +`title` 留着可改，因为它只是列表上的一个标签，不进任何 agent 的上下文。 + +### 4.5 ID 生成 —— 现有格式在本次会真的撞 + +现在两处都写 `` `T-${Date.now().toString(36)}` ``（`company.js` 与 `agent-chat.js`）。**同一毫秒内生成的两个 id 完全相同** —— 今天没炸是因为一次只建一个；本次「一个 goal 一次性建 N 个 task」是**循环建行**，同毫秒撞是必然事件，而 `tasks.id` 是主键，撞了就是 500。 + +改成仓库既有约定（`_spec/CONVENTIONS.md` §2：*时间戳部分不保证全局唯一 —— 靠后缀随机位避免碰撞*）： + +```js +const genId = (p) => `${p}-${Date.now().toString(36)}-${crypto.randomBytes(2).toString('hex')}`; +// G-mabc123-7f3a / T-mabc123-9e21 +``` + +`agent-chat.js` 那处 tasklog 的 `T-` 生成**本次不动**（那是另一套存储），但要在 §九 记一笔：两套 `T-` id 从此可能长得像但不同源，读的时候别混。 + +### 4.6 逻辑外键，不重建表 + +`graph_runs.goal_id` / `task_id` 保持现状不加 `REFERENCES`：SQLite 不支持给已有列追加外键，要加只能重建表 —— 而 `graph_runs` 上挂着 `graph_run_nodes` / `graph_run_loop_records` 的真外键，重建代价远大于收益。约束由服务层保证，文档里标注为**逻辑外键**。 + +`tasks.goal_id → goals(id)` 是新表，可以是真外键，直接写上。 + +### 4.7 收敛汇报的两条实现禁令（照现有代码顺手写就会踩） + +> ⚠️ **本节写于批 1 实施之前，`reportRunOutcome` 已在批 1 中删除**（见 §十三）。下面对它的描述保留为「当时的现状」，两条禁令的结论不变，只是落点从 `company.js:reportRunOutcome` 变成了 `task-settle.js:reportGoalOutcome`。 + +`reportRunOutcome`（`company.js`，**已删**）曾是 root run 收敛后的唯一出口，它做两件事：有 `report_to` 就 POST 给 `/api/agent/task/report` 唤醒上级 agent，没有就直接 `OkrService.updateNode(objectiveId, okrNodeId, {status})`。两件事在 goal/task 两级下都会坏： + +**禁令一：task 的 run 一律不带 `okr_node_id`。** +现在 `createRun({okrNodeId})` 把它写进 run，`reportRunOutcome` 读 `run.okr_node_id` 直接写 OKR 节点。一个 goal 挂一个 OKR 节点、下面 5 个 task 各带一份，就是**同一个 OKR 节点被写 5 次**，且没有合并逻辑 —— 最后一个收敛的 task 说了算，一个 failed 的尾巴能把已经 done 的节点翻成 failed。所以：**`okr_node_id` 只存在 `goals` 表上，不进 `graph_runs`**；OKR 由 goal 收敛（全部 task 终态）时写一次。 + +**禁令二：`report_to` 必须落库。** +今天 `report_to` / `reporterAgent` 只活在请求作用域的闭包里（`ctx`），随手挂给 auto 模式的 driver。**排队之后 driver 是调度器在几小时后创建的，那时请求体早已不存在** —— 结果是 Master / CEO 代下单的回调链路**静默断掉**：不报错、不重试，就是没人被唤醒。所以 `goals.report_to` / `tasks.report_to` 两列是必需的，调度器起 driver 时从 task 行读回。 + +> 这两条都属于「既有实现是对的，只是它假设了『下达即执行』」。排队打破了那个假设，而打破得非常安静。 + +### 4.8 存量回填（不做的话，批 1 会让历史任务更看不见） + +既有的 root run 在 `tasks` 表里没有任何行。左栏一旦改成读 `tasks`，**所有历史 run 会从界面上消失** —— 正好是本文档要修的 A 类问题的反向放大。 + +迁移脚本（一次性，幂等，`--dry-run` 预演，写法照 `scripts/migrate-goals-to-okr.js`）： + +对每条 `parent_run_id IS NULL` 的 `graph_runs`： +1. 建一条 `goals` 行：`description` 从 `data/companies/{cid}/runs/{runId}/artifacts/task-goal.json` 的 `task` 字段读回；读不到就用 `run.task_id` 占位并标 `title = '(历史任务)'`。`status` 按 run 终态映射（`completed → done`，其余 → `active` / `cancelled`）。 +2. 建一条 `tasks` 行：`seq=1`、`depends_on=[]`、`current_run_id = run.id`、`attempt=1`、`status` 按 run 状态映射，`queued_at = run.created_at`（描述立即冻结，历史任务本来也不该再改）。 +3. 回填 `graph_runs.goal_id` / `task_id` 指向新行。 + +> 实测当前 `data/graph.sqlite` 里只有 1 条 root run（且卡在 `running`），所以回填本身成本极低 —— 但**开发机与线上库的数据量不一样**，脚本必须写，不能靠「反正没几条」跳过。 + +### 4.9 `task-planning` —— 把 goal 拆成 task DAG（v1 就做，用户定案） + +命名依 27-NAMING §二「`{产出物}-planning`」：产出物是 task 列表，故 **`task-planning`**。它是继 `orggraph-planning` / `workgraph-planning` 之后的**第三个规划类 agent**，形态与后者对齐。 + +#### 链路照抄 `defaultPlanWorkGraph`，不另造 + +`graph-engine.defaultPlanWorkGraph` 已经把「调规划 agent → 校验产物 → 不过就把 `errors` 原样回给它再来一轮」这条链路跑通了（`PLAN_MAX_ROUNDS = 3`）。`task-planning` 用**同一个形状**： + +``` +AgentManager 调 task-planning（输入：goal.description + 公司 org graph 摘要 + 可用角色清单） + → 产出 JSON: [{ title, description, depends_on: [], seq }] + → 校验：字段齐全 / depends_on 只引用本次产出的 seq / 无环 / 条数 ≤ 上限 + → 不过 → errors 原样回喂，最多 3 轮 + → 过 → 落 tasks 表，全部 status='draft' +``` + +**产出的 task 一律是 `draft`，不自动入队。** 拆完在界面上是一份可编辑的清单（改描述、删、加、调依赖），人点「全部下达」才转 `queued`。理由：拆分是一次 LLM 猜测，直接把 5 条任务塞进队列跑起来，等于让一次猜错的拆分直接烧掉 5 份预算；而这一步的编辑成本几乎为零。 + +#### 三条必须写进实现的约束 + +1. **token 记账**：复用 `defaultPlanWorkGraph` 那个 `onAcpEvent` 累加 `usage` 的写法，结果写进 `goals.planning_tokens`（§四.1）。这是 goal 层唯一一笔花费，不记就是隐形的。 +2. **失败必须降级，不能把 goal 卡在 `planning`**：3 轮都没产出合法 DAG → **退化成 1 条同描述的 task**（`created_by='human'`、`seq=1`、`depends_on=[]`），goal 转 `active`，并在界面标注「自动拆分失败，已按单任务下达」。绝不能留一个永远转圈的 `planning` goal —— 那正是这次要消灭的那类静默状态。 +3. **本体落点是 `system/agents/task-planning/`**（`system/templates/` 已在 2026-08-18 的 agent 目录重构里**彻底取消**，50 个本体全部 `git mv` 进 `system/agents/`，`base` → `_base`）。形态照 `workgraph-planning`：`agent.md` / `config.json` / `identity.md` / `soul.md` / `tools.md`。**不要用 `_` 开头命名** —— `_` 是保留前缀，扫描时会被跳过。 + +4. **`agent.md` + `soul.md` 必须一次写完，不能先建骨架后填**。本体现在有**毕业闸门**：`agent.md` 与 `soul.md` 非空、且不带 `_base` 的骨架哨兵，才会从 `system_agents.status='draft'` 毕业；否则 `hire()` 拒绝并返回 `body_not_ready`。「从 `_base` 复制骨架 → 以后再填」的中间态**雇不进公司**。（`.claude/skills/main_skill/SKILL.md` 是可选的，57 个本体里 54 个没有。） + + 三个权威判据（真到建本体时以它们为准，别照文档复述）：`agent-locator.js` 的 **`missingBodyDefinition()`**（判什么算没填完）、`graph-service.js` 的 **`promoteDraftIfComplete()`**（转正动作）、以及 `hire()` 用的 **`isUngraduatedStatus()`**。 + + > ⚠️ **`isUngraduatedStatus()` 只挡 `draft` / `training` 两个状态，不是「≠ active 就挡」。** 这个坑已经被踩过一次：库里有 36 个本体的 status 是 `enabled` / `idle` / `ready` / `trained`，按「不等于 active」判会被全部误判成「没填完」。取值域的唯一持有者是 `graph-service`，**不要在别处复述它** —— 本文档 §六.3 已经因为 `canDispatch` 被前端复述过一次取值域而记过同类教训。 + +5. **`_registry.json` 登记是可选的，建目录才是关键动作** —— 这条与初稿写反了，留档纠正：`graph-seed-service.seedAgents()` 现在直接 `readdirSync(system/agents/)` 把**目录当真相**，`_registry.json`（已随重构挪到 `system/agents/_registry.json`，数组格式不变）只用于按 id 补 `benchmark_score`，registry 缺条目照样 seed。初稿写的「不登记会把 CI 跑红」引的是 27-P3/P4 §八.21 的前科，那条前科属于 `template-refs.test.js` 硬编码 `system/templates` 路径的时代，**该测试正随重构一起改**。仍建议顺手登记（`benchmark_score` 要用），但它不是闸门。 + +6. **本体正文里的路径有三条硬规矩，写错不报错、只静默降级**（agent 运行时 cwd 是 `system/agents/{aid}/{cid}/{taskId}/`，深度 3）： + - 引用本体自己的文件 → `../../`（如 `../../tools.md`）； + - 引用仓库根 → `../../../../../`； + - **交付物路径绝不能写裸相对**（`workspace/x.md` 会落进任务态目录，之后被清理）。必须用提示词开头「运行时坐标」里「你的交付物必须写到」那一行给的**绝对路径**，本体正文里统一记作 `$W`。 + + 照 `system/agents/orggraph-planning/agent.md`（重构后版本）抄写法。这三条错了全都**不报错**，只是产物落在没人看的地方 —— 与本文档反复点名的那类静默故障同源。 + +#### 跳过拆分 + +`POST /goals` 带 `split: false` 时不调 agent，直接建 1 条同描述的 task。存量调用方（`POST /:cid/tasks`）走的就是这条路 —— **它们不该因为这次改动突然多花一次 LLM 调用**。 + +### 4.10 goal 级验收 —— 仍然是 `org-validator`（用户定案） + +**不新造验收 agent**：goal 级用的还是 `org-validator` 这个本体，只是**在 goal 层再调一次**。 + +#### 为什么是「再调一次」而不是复用 task 级那次的结论 + +因为两次验的是**基数不同的东西**，这正是 27-NAMING §四 那张表的论证： + +| | 验什么 | 谁问的 | +|---|---|---| +| task 级（既有，org graph 末端节点）| 这**一个 task** 的 `task-goal` 达成了没有 | 引擎，每个 task 各一次 | +| **goal 级（本次新增）** | **N 个 task 合起来，人提的那个需求达成了没有** | goal 收敛时，一次 | + +5 个 task 全 `completed`，只说明每一件事都按各自的描述做完了 —— 不说明拼起来是人要的东西。这个缺口正是 goal 层存在的理由，用别的东西替代不了。 + +#### 触发与判定 + +``` +goal 下所有 task 到终态 + ├─ 有任何一条 ≠ completed → goal 直接 failed，不调 agent（省一次调用：显然没交付） + ├─ 全 completed 且只有 1 条 task → 跳过 goal 级验收，直接采用该 task 的验收结论 + │ （单 task 的 goal，两级验收是同一件事，再调一次纯浪费） + └─ 全 completed 且 ≥2 条 task → 调一次 org-validator + 输入：goal.description（= 验收边界）+ 该 goal 全部 task 的产物索引 + （`graph_files` 按 task_id 查，§P4 §4.6 的表已经能给出这份清单） + 产出：pass / fail + 判词 → goals.status = done / failed，判词落 goals.verdict +``` + +调用形态与 `task-planning` 相同：`AgentManager` 直调本体，不在任何 graph run 里，token 记 `goals.validation_tokens`。 + +#### 挂在哪 + +和调度器同一个位置：task 转终态时顺手判一次「这个 goal 的 task 是不是都到齐了」。**`settleGoal(goalId)` 必须幂等**（并行完成的多个 task 会同时触发它），用 `goals.status` 的条件更新做闸门 —— 与 §五.1 出队用的是同一招。 + +> goal 收敛之后才轮到 §四.7 的两件事：写 OKR 节点（一次，用 goal 的判定结果）、唤醒 `report_to`。**这两件事从 run 级上移到 goal 级**，禁令一说的「task 的 run 一律不带 `okr_node_id`」在这里闭环。 + +--- + +## 五、排队与并行 + +### 5.1 调度器 `server/services/task-scheduler.js`（新） + +一个函数就是全部： + +```js +tick(companyId) // 幂等，可重入，同步执行（better-sqlite3 是同步 API） +``` + +1. 读公司并发上限 `max`（§五.2）。 +2. 数当前活跃 root run 数 `n`（`run_status ∈ {ready,running,paused}`）。 +3. `n >= max` → 直接返回（队伍照排，不动）。 +4. 选候选：`status='queued'` 且 `depends_on` 里每个 id 都已 `completed`、且 `execution_mode='auto'`（manual 不自动出队，见 §五.3）的 task，按 `priority` → `seq` → `created_at` 排序，取前 `max - n` 条。 +5. 逐条出队，**整条包在 `try/catch` 里**： + ```js + syncRunNodesToDef(runId); // §四.3：定义可能已经变了 + const changed = updateRunStatus(runId, 'queued', 'ready'); // 原子出队，见下 + if (!changed) continue; // 被并发抢走，正常情况 + startRun(runId, { mode, task }); // manual 只点亮入口，auto 挂 driver + ``` + 捕获到 `UNIQUE constraint failed` 或 `InvalidTransitionError` 同样 `continue` —— 它们都是「这条没抢到」，不是错误。 + +**出队原语就是 `updateRunStatus(runId, 'queued', 'ready')` 这一条，不经过 `markRunReady`。** 核实结论： + +- `updateRunStatus` 本身就是条件更新（`WHERE id = @id AND run_status = @from`）并返回 `changes` —— 这正是要的 compare-and-swap； +- 它**先**跑 `canTransitionRun(from, to)`，非法转换直接 `throw InvalidTransitionError`； +- 撞唯一索引时 better-sqlite3 **抛 `SqliteError: UNIQUE constraint failed`，不是返回 `changes = 0`**。初稿只写了「受影响行数为 0 就跳过」，漏了这一半 —— 照初稿实现，一次正常的并发竞争会把整个 `tick` 抛出去； +- **`markRunReady` 不能复用**：它把 `transitionRun(runId, 'planning', 'ready')` 的 `from` **写死成 `planning`**，对一条 `queued` 的 run 是空转（`WHERE run_status='planning'` 匹配不到）。初稿写的「UPDATE 成 ready 之后再 markRunReady」既冗余又跑不通。 + +### 5.1.1 触发：挂在状态变更漏斗上，而不是枚举路径 + +初稿列了四个触发点（入队 / `settleRun` / 启动 / 60s 兜底）。**核实后发现这个枚举本身就是漏的**： + +| 路径 | 会不会释放 active 坑 | 走不走 `settleRun` | +|---|---|---| +| 正常收敛（manual `/next` / auto driver）| 会 | ✅ 走（`settleRun` 只在 `advanceOne` 里被调用） | +| **人工停止 `stopRun`** | 会（`stopped`）| ❌ **不走** —— 代码注释自己写着「子 run 被 stopRun 直接转 stopped，不经过 settleRun」 | +| **预算耗尽 → `blocked`** | 会（`blocked` 不在 active 取值域里）| ❌ 不走 | + +也就是说「用户停掉一个任务」和「任务烧完预算」这两条最常见的释放路径，队列都不会动，要干等 60s 兜底。**继续往表里加行不是解法 —— 枚举一次漏一次，而漏的症状是任务静默躺在队里、界面上跟「正在排队」一模一样，正是当初拒绝做排队的那条理由。** + +改成挂在**唯一的状态变更漏斗**上：`graph-run-sse.transitionRun` 是全仓库所有 run 状态转换的必经之路（引擎侧一律走它，因为它同时要落 timeline 和推 SSE）。 + +```js +// transitionRun 内，条件更新成功之后 +if (run.parent_run_id === null && !ACTIVE_ROOT_RUN_STATUS.has(to)) { + setImmediate(() => scheduler.tick(run.company_id)); // 出漏斗再调，避免重入 +} +``` + +一个钩子覆盖 settle / stop / blocked / failed / completed 全部路径，且**语义就是那句话本身**——「一个 root run 离开了活跃集，去看看队里有没有人能顶上」。 + +保留的另外三个触发点：**入队时**（队伍空时立即起跑）、**服务启动时**（挂在 `server/index.js` 现有的「中断任务恢复」旁边，补进程重启丢掉的唤醒）、**60s 兜底定时器**（前面全漏了也能自愈）。 + +两条必须写进实现的护栏： +- **重入保护**：`tick` 会起 run → 起 run 会转换状态 → 又触发 `tick`。用一个 per-company 的 in-flight 标志，或统一 `setImmediate` 出栈后再跑。 +- **`tick` 里不 throw**：它挂在状态转换的尾巴上，抛出去会把一次正常的 run 收敛也带崩。 + +> ponytail: `tick` 目前按公司算配额。将来要跨公司全局配额时，改成「按配额池」——钩子位置不用动。 + +### 5.1.2 上游失败 → 下游自动转 `blocked`（用户定案） + +`depends_on` 只认 `completed`，所以上游一旦 `failed` / `cancelled`，依赖它的下游**永远满足不了条件**。放着不管，那条 task 会静默躺在队里，界面上和「正在正常排队」长得一模一样 —— 又是这次要消灭的那类症状。 + +`tick` 开头加一步（在选候选之前）： + +```js +// 依赖已经不可能满足的 queued task，就地转 blocked，别让它假装在排队 +for (const t of queuedTasks) { + const dead = t.depends_on.find((id) => ['failed','cancelled'].includes(statusOf(id))); + if (dead) setTaskBlocked(t.id, `upstream_failed:${dead}`); +} +``` + +界面上 `blocked` 的行标红并显示 `blocked_reason`，`⋯` 菜单给两个出路：**重跑上游**（上游 `rerun` 成功后，下游自动回 `queued`）或 **强制放行**（清掉那条依赖，人为承担风险）。 + +> **级联要一次算到底**：A 失败 → B blocked → 依赖 B 的 C 也应该 blocked（`blocked` 同样不是 `completed`）。上面那段按「依赖里有任意一个处于非 completed 终态」判定即可自然级联，但要注意**别把 `blocked` 本身当成终态去反向传播**，否则 A 重跑成功后 C 解不开。解法：`blocked` 只由这一步**推导**得出，不落成不可逆状态 —— 每次 `tick` 重算一遍，上游恢复了就自己回 `queued`。 + +### 5.2bis manual 模式会永久堵住队头 + +`startRun(manual)` 只点亮入口节点就停下等 `/next`，而这时 run 已经是 `running` —— **占着 active 坑**。`max_parallel_tasks = 1` 时，一个没人点「下一步」的 manual 任务会把它后面所有任务**无限期堵死**，而队列界面上看不出任何异常。 + +定案：**manual 任务不参与自动出队**（§五.1 第 4 步的过滤条件）。它只能由人在控制台上显式点「开始」——那一步同样走 `queued → ready` 的原子出队，抢不到坑就提示「当前有任务在跑」。 + +理由：manual 的语义本来就是「人盯着一步步推」，让调度器在半夜自动把它拉起来、然后停在第一个节点上占着坑到天亮，是这个模式下最糟的行为。 + +### 5.2 并发上限与唯一索引 + +**定案（2026-08-18）：配置放 `company.json`，不建 `company_settings` 表。** `companyService.get` 已经在读这个文件，零新增读路径；建表要多一张表、一套读写、一次迁移，而目前公司级配置项只有这一个。公司级配置项涨到 3 个以上时再考虑建表（届时连 `company.json` 里已有的那些一起收）。 + +`company.json` 加一个字段： + +```jsonc +{ "max_parallel_tasks": 1 } // 缺省 1 = 与今天完全同行为 +``` + +- **`max = 1`（默认、批 2 上线时的形态）**：`idx_graph_runs_one_active_root` 保留不动，DB 层的守卫还在，行为与今天一致，只是「拒绝」变成了「排队」。 +- **`max > 1`（批 4）**：这个唯一索引必须 `DROP`，否则第二条并行任务在 `queued → ready` 时被索引拒掉。替代守卫是 §五.1 第 2-5 步**整体包在一个 `better-sqlite3` 事务里**（`db.transaction(...)`）—— SQLite 是单写者，写事务天然序列化，「count 完再 admit」在这里是真原子的，不是应用层的乐观检查。 + +**批 4 单独排期、单独验收**，理由：删掉一个唯一索引 = 删掉最后一道 DB 兜底，这个动作不该和「界面上能看到任务列表」混在一次上线里。 + +> ⚠️ **批 4 与 [27-P4](../../todo/system-design/27-p4-parallel-and-artifacts.md) §一.3 是同一件事，不要各做一遍。** 那份文档的目标 3 逐字写着「**解除「一家公司同时只有一个 active root run」约束** —— P3 v1 用一个唯一索引强制它（§三.3），并行能力具备后应放开」。也就是说：**放开约束的设计归 27-P4，本文档只负责在它之上定义「谁来排队、按什么序出队」**（§五.1）。真到实施时以 27-P4 的并行方案为准，本文档的 §五.2 服从它；两边都写一版会产生两套并发守卫。 + +--- + +## 六、API + +全部挂在 `server/routes/company.js`。错误响应沿用现有 `{ error, hint, ... }` 形态。 + +> **⚠️ 批 1 必须修两处路径缺陷 —— 一处就在本文档的核心链路上。** +> +> **缺陷 A（会分叉，在核心链路上）**：`task-goal.json` 的写入方与读取方用的不是同一套路径规则。 +> +> | | 位置 | 认不认 `GRAPH_RUNS_DIR` | +> |---|---|---| +> | **写** | `company.js` 的 `writeTaskGoalArtifact` → `path.resolve(__dirname,'../..','data','companies',cid,'runs',rid,'artifacts')` | ❌ **不认** | +> | **读** | `graph-engine.js` 的 `runRootDir`（`describeTask` 与 `goal-contract.deriveRunDir` 都走它）| ✅ 认 | +> +> `GRAPH_RUNS_DIR` 一旦被设上（目前只有测试在用），写进 A 处、从 B 处读 —— `describeTask` 拿到 null，**静默退回兜底文案「执行图节点任务」**，agent 从此拿不到真实任务描述，而**没有任何报错**。`goal-contract.test.js` 的注释佐证读取方那套形状才是约定：`{GRAPH_RUNS_DIR}/{rootRunId}/artifacts/task-goal.json`。 +> +> 生产环境两边恰好都退到同一个默认分支，所以今天不发作 —— 但**批 1 会把 artifact 的落盘点从「下达时」前移到「入队时」**（§四.3 / §四.4 的描述冻结点），正好要动这个函数。**修法是一行级：写侧改调读侧的 `runRootDir`。** +> +> > ⚠️ **本文档初稿在这里归因错了，留档纠正**：初稿写成「`runRootDir` / `companyRootDir` / 写入方三种拼法争权威，实施前得先定哪个权威」。**那是错的，而且会让实施者去做一个根本不存在的设计决策。** `runRootDir` 与 `companyRootDir` 是**两个不同的事实**，不是同一事实的两种拼法： +> > - `runRootDir` → **run 目录**，覆盖态是 `{RUNS_ROOT}/{rootRunId}`。扁平即可，因为 `rootRunId` 全局唯一； +> > - `companyRootDir` → **公司根**，覆盖态是 `{RUNS_ROOT}/_companies/{cid}`。多出来的 `_companies/` **是必须的** —— 公司 id 不是全局唯一坐标，扁平放会和 run 目录撞名。 +> > +> > `company-paths.js` 的注释本身就写着「理由与 `runRootDir` 那处 override 一致」，作者是有意区分的。**真正错的只有一处：写入方自己拼路径。** +> +> **缺陷 B（不会分叉，因为它根本没有调用方 —— 但更会骗人）**：`goal-contract.js:75` 声明了 +> +> ```js +> /** run 目录根的覆盖，与 graph-engine.RUNS_ROOT / graph-run-sse 是同一个变量（测试隔离在用） */ +> const RUNS_ROOT = process.env.GRAPH_RUNS_DIR || null; +> ``` +> +> **然后一次都没用过**（全文件只有注释 + 声明两行），同文件的 `resolveRunDir()` 照旧自己拼 `DATA_DIR/companies/…`。而且 `resolveRunDir` **全仓库零调用方**（只有定义、`module.exports` 和 `27-goal-contract-format.md` 里的一行文档）—— 又一个「实现在、零调用方」。 +> +> 所以它今天不会出错，危害是**注释在撒谎**：白纸黑字写着「与 graph-engine.RUNS_ROOT 是同一个变量、测试隔离在用」，读代码的人会据此认为这个文件认 `GRAPH_RUNS_DIR`。**一个声明了意图、代码却不兑现的常量，比没有这个常量更容易骗人** —— 第一个把 `resolveRunDir` 接上去的人会直接踩。 +> +> 批 1 一并处理：要么让它真的用 `RUNS_ROOT`，要么连函数带常量一起删（零调用方，删是更省的一侧）。 +> +> **`system/agents` 那一族已经不用管了** —— 2026-08-18 的 `e120645` 已把全仓库 13 处（跨 5 个文件，含 `company.js` 里 6 个 `TEMPLATES_DIR` + 3 个同义异名的 `DATA_DIR`）收敛到 `locator.AGENTS_ROOT`，并新增 `server/tests/unit/agents-root-single-holder.test.js` 锁住不变式。**批 1 新增的代码必须遵守它**：不许自己拼「以 `../` 开头、以 `system/agents` 结尾」的字面量，否则这条测试会红。 +> +> 这些全是**同一个病**的不同实例，本文档已经攒到第五个：`canDispatch` 的取值域被前端复述（§六.3）、`ACTIVE_ROOT_RUN_STATUS` 在两文件逐字重复（§九.1）、`isUngraduatedStatus()` 的取值域（§四.9）、`system/agents` 的 13 份路径、以及上面这三种 run 目录拼法。**同一个事实只能有一处持有者 —— 路径也是事实。** +> +> 方法论也记一条：我第一次只 grep 了 `TEMPLATES_DIR` 这个**名字**，因此漏掉了同一文件里语义相同但叫 `DATA_DIR` 的 3 处。**同义异名的副本按名字 grep 永远找不到，要按值 / 按路径字面量 grep。** +> +> （一条**刻意不做**的：`company-service.js` 的 `const TEMPLATES_DIR = locator.AGENTS_ROOT` 取值已正确、只是名字过期，读的人会以为它指 `system/templates`。改名要动 50 处、跨 6 个文件、零功能收益 —— 不值得。留着这条记录，是为了说明它**是已知的，不是没人看见**。） + +### 6.1 先做一件清理：退役 OKR 的 `/goals` 别名 + +`index.js` / `agent-server.js` 里 `app.use('/api/goals', require('./routes/okr'))` 与 `company.js` 的 `okrPath()` 里那条 `/:companyId/goals${suffix}` 一并删除。§二.3 已核实**零调用方**。删完 `/goals` 这个词在整套 API 里只剩一个含义。 + +### 6.2 goal + +| 方法 | 路径 | 说明 | +|---|---|---| +| `GET` | `/api/company/:cid/goals` | 列表。query: `status` / `includeArchived` / `withTasks=1`（带出每个 goal 的 task 摘要，列表页一次拉完不 N+1） | +| `POST` | `/api/company/:cid/goals` | 新建。body `{ title, description, priority?, okr_node_id?, report_to?, split?: bool, tasks?: [...] }`。**默认 `split: true` → 异步调 `task-planning`**：立即 `202 { goalId, status: 'planning' }` 返回，拆分产物几十秒后才出现（前端轮询或走 SSE）。`split: false` 或显式传 `tasks` 则同步建行、不调 agent。**产出一律是 `draft`，不自动入队** —— 入队走下面的 `dispatch` | +| `GET` | `/api/company/:cid/goals/:goalId` | 详情：goal + 全部 task + 每个 task 的最近一次 run 摘要 | +| `PATCH` | `/api/company/:cid/goals/:goalId` | 改 `title` / `priority` / `okr_node_id`；`dispatched_at` 非空时带 `description` 一律 `409`（§四.4） | +| `POST` | `/api/company/:cid/goals/:goalId/dispatch` | 把该 goal 下所有 `draft` task 入队，写 `dispatched_at` | +| `DELETE` | `/api/company/:cid/goals/:goalId` | 归档。有 task 正在跑 → `409` + hint「先停止 T-xxx」；否则连带归档其下 task | + +### 6.3 task + +| 方法 | 路径 | 说明 | +|---|---|---| +| `GET` | `/api/company/:cid/tasks` | **新端点**（核实过：今天这个路径下只有 `POST`，没有 `GET`，不存在兼容问题）。返回 task 表的行，含 `goalId` / `status` / `queuePosition` / `progress` / `runId` | +| `POST` | `/api/company/:cid/tasks` | **保留、行为兼容**：不带 `goal_id` 调用时，**自动建一个同描述的 goal**（`created_by` 记调用方）再挂一条 task —— 存量调用方（含 `DispatchTaskButton`、外部 agent 的 curl）一行不用改就还能用，响应体里多出 `goalId` 字段。带 `goal_id` 则挂到既有 goal 下 | +| `PATCH` | `/api/company/:cid/tasks/:taskId` | 改 `title` / `priority`；**`depends_on` 在 `draft` 与 `queued` 都可改**（用户定案，见下）；`queued_at` 非空时带 `description` / `mode` / `budget` 一律 `409` | +| `POST` | `/api/company/:cid/tasks/:taskId/enqueue` | 单条入队：建 `queued` 的 run 行 + 写 `task-goal.json` + `tick()` | +| `POST` | `/api/company/:cid/tasks/:taskId/cancel` | `queued` → 撤出队列（run `queued → stopped`）；`running` → 转调既有 `POST /api/graph-runs/:id/stop` | +| `POST` | `/api/company/:cid/tasks/:taskId/rerun` | 从 `failed` / `blocked` / `completed` 重新入队，`attempt + 1`，**新起一条 run**（旧 run 保留在历史里）。**刻意不叫 `retry`** —— 见下 | +| `DELETE` | `/api/company/:cid/tasks/:taskId` | 归档，同 goal 的规则 | + +**`rerun` ≠ `retry`，两者会撞车。** 既有的 `POST /api/graph-runs/:id/nodes/:nodeId/retry` 是**节点级重试**：同一条 run 内把某个节点打回 `ready` 重跑（`blocked` 的唯一出路，`NODE_TRANSITIONS` 里写死的）。新加的是**任务级重跑**：新起一条 run，整张图从头来。两个都叫 retry，实现时必然有人把新端点接到旧逻辑上（或反过来）。所以任务级一律叫 `rerun`，文档、API、界面按钮文案（「重跑这个任务」vs 节点详情里的「重试这一步」）三处同时区分。 + +**`queued` 状态开放改依赖**（用户定案）。真实场景是「B 已经排上了，才发现它得等 C」，此前只能取消重建、丢掉排队位次。三条细则： +- 环检测照跑（只能引用同 goal 内的 task），有环 `400`，库里不留半条脏数据； +- **位次不受影响**：`queuePosition` 只按 `priority → seq → created_at` 排，`depends_on` 决定的是「够不够格出队」，两者正交 —— 当初担心的「改完位次怎么算」不成立； +- 新加的依赖若已经 `failed` / `cancelled`，下一次 `tick` 会自然把它推导成 `blocked`（§五.1.2），不需要额外处理。 + +**`POST /:cid/tasks` 的 409 消失了**：并发冲突不再是错误，是排队。响应体改为 `201 { taskId, goalId, runId, status: 'queued', queuePosition: 2 }`。`queuePosition` 是这次改动里对用户最直观的那个字段 —— **它的排序口径必须与调度器第 4 步逐字一致**（`priority → seq → created_at`），两处各写一份的下场已经有先例：`canDispatch` 就是因为前端自己复述了一遍取值域、还多写了一个 `blocked`，导致公司失败一次后再也下不了任务。**口径只留调度器一处，端点调用它算位置。** + +### 6.4 不动的端点 + +`GET /api/company/:cid/graph-runs`（其它调用方在用）、全部 `/api/graph-runs/*` 控制端点、`/api/okr/*`。 + +--- + +## 七、前端 + +### 7.1 布局 + +``` +┌──────────────┬──────────────┬───────────────────────┬──────────────┐ +│ 目标 · 任务 │ Org Graph │ Work Graph │ 节点详情 │ +│ 280px │ 320px │ 1fr │ 360px │ +│ │ │ │ │ +│ [+ 新目标] │ ○─○─○ │ ○──○──○ │ 四个 tab │ +│ ▾ G 做个官网 │ │ │ │ │ │ │ +│ ● T1 首页 ◀│ ○──○ │ ○ │ │ +│ ◌ T2 后台 │ │ │ │ +│ ⋯ T3 排队#2│ │ │ │ +│ ▸ G 埋点改造 │ │ │ │ +└──────────────┴──────────────┴───────────────────────┴──────────────┘ +``` + +`GraphConsole.vue` 的 `.cols` 从 `320px 1fr 360px` 改为 `280px 320px minmax(0,1fr) 360px`。 +响应式：`≤1400px` 最左栏收成 44px 图标条 + 抽屉展开（org graph 那栏最不能压，它是全局导航）；`≤1100px` 沿用既有堆叠，目标栏排最上。 + +### 7.2 新组件 `web/src/components/graph-console/GoalTaskPane.vue` + +两级树，goal 可折叠，**选中态永远落在 task 上**（org / work graph 是 task 级的）： + +- **goal 行**：状态点 + 标题 + `3/5 任务完成` + `⋯` 菜单（编辑 / 下达全部 / 归档）。点标题展开收起；goal 行本身被选中时，中栏显示这个 goal 的任务概览（v1 就是一张简单的任务卡片列表，不画图）。 +- **task 行**：状态点 + 标题（2 行截断）+ 第二排 `queued#2 · auto · 3/7 · 12min`。`depends_on` 非空时标题前加 `⇢` 并 hover 出「等 T1 完成」。 +- 状态点配色**沿用画布节点的既有色板**，不新造：running 蓝 / completed 绿 / failed 红 / blocked 橙 / queued 灰蓝 / draft 空心圈 / cancelled 灰。 + +**「+ 新目标」表单是两步的**（承接现有 `DispatchTaskButton` 的内容，搬进这一栏内联展开）： + +**第一步 · 写需求**：标题 + 描述 + 执行模式 + auto 模式的成本预警（原样保留）+ 一个「自动拆分任务」开关（默认开 = `split: true`）。主按钮「下一步」。 + +**第二步 · 确认拆分**：开关关掉就跳过这一步直接下达。开着则显示 `task-planning` 的产出——一份**可编辑**的任务清单（改描述、删行、加行、调依赖前置），带一行 `本次拆分消耗 ~N tokens`。主按钮「全部下达」，次按钮「存草稿」。 + +拆分进行中（goal `status='planning'`）显示骨架屏 + 「正在拆分…」，**并给一个「跳过，按单任务下达」的逃生口** —— 几十秒的 LLM 等待必须能被绕过，否则一次 agent 卡死就等于这个表单不能用了。拆分失败时这一步直接展示降级结果（1 条同描述的 task）+ 一句「自动拆分失败，已按单任务下达」，**不弹错误对话框**。 + +`canDispatch === false` 时**主按钮不再禁用** —— 排队之后它永远可点，按钮下方改为提示「当前 1 个任务在跑，新任务将排在第 2 位」。这是 B 类问题在界面上的最终消解。 + +### 7.3 选中态与刷新 + +- 路由 `/:id/graph-console?goal=G-xxx&task=T-xxx`，刷新 / 分享可复原。无参数时默认选中最近一条 `running` 的 task，没有则最近创建的。 +- 切 task 时 `orgNode / selectedNode / stack` 全清（不同任务的 def node 不可复用，串了会画出一张不存在的图 —— 与 `onReplanned` 的处理同理）。 +- 选中 **draft / queued** task：org 栏画 org graph **定义**（现有 `hasOrgGraph && !rootRun` 分支已能画，全 pending），顶部一条「排队中，前面还有 1 个任务」或「草稿，尚未下达」+ 对应按钮。 +- 刷新：选中 task 的 run 有 SSE（`GraphRunPane` 的 `@state`）→ 只更新那一行；整树 20s 轮询兜底。 + > ponytail: 没有公司级 SSE 通道，所以未选中的行只能靠轮询。升级路径是 `graph-run-sse` 加一个 company topic，前端订一条就够。 + +--- + +## 八、验收 + +每条都要在浏览器 `/e2e-probe/graph-console` 上真点出来，不是只跑单测。 + +1. 建一个 goal 不拆分 → 自动生成 1 条 task 并入队，左栏出现两级树，org 栏画出该 task 的 run。 +2. 建一个 goal 拆 3 条 task，T2/T3 依赖 T1 → T1 跑时 T2/T3 显示 `queued`；**T1 收敛后 T2 自动起跑**（验证漏斗钩子覆盖正常收敛），全程无人工干预。 +3. `max_parallel_tasks=1` 下建两条无依赖 task → 第二条排队而**不是 409**，`queuePosition=2`。 +4. 存量调用方兼容：`curl POST /api/company/:cid/tasks -d '{"task":"…"}'`（不带 `goal_id`）仍返回 201，且自动生成了一个 goal。 +5. 改已下达 goal 的 `description` → `409` + hint；改 `title` → 200。task 同理。 +6. `depends_on` 写成环 → `400`，库里没有半条脏数据。 +7. 取消一个 `queued` task → run `queued → stopped`，队列后面的顶上来。 +8. `failed` 的 task 点重试 → `attempt=1`，新起一条 run，**旧 run 仍能在历史里点开**。 +9. 杀掉服务再起（模拟进程重启）→ 队列里的 task 被「服务启动」这个辅助触发捡起来，不需要人工干预。 +10. 列表端点在 20 goal × 3 task 的公司上**不 N+1**（`graph_run_nodes` 的进度用一次 `GROUP BY` 出）。 +11. `/api/goals` 与 `/api/company/:cid/goals` 的 OKR 别名退役后，`OkrDashboard` / `CompanyDashboard` / `bin/lemon.js` 全部功能正常（它们走的是 `/api/okr`）。 +12. **回填**：跑迁移脚本后，既存的每条 root run 在左栏都以 goal + task 的形式出现，描述从 `task-goal.json` 读回（§四.8）。**这条必须在批 1 就验** —— 不验就等于批 1 让历史任务更看不见了。 +12b. **路径缺陷 A 已修**：在 `GRAPH_RUNS_DIR` 指向临时目录的条件下走一遍「下达 → 入队 → 读回描述」，`describeTask` 拿到的是**真实任务描述**而不是兜底文案「执行图节点任务」。 +> ⚠️ 这条验收**必须先设 env 再 `require`**：`graph-engine.js:84` / `goal-contract.js:75` / `graph-run-sse.js:34` 三处都是**模块加载时快照** `GRAPH_RUNS_DIR`，而 `company-paths.js:14` 的文件头注释恰恰记着相反的教训（「每次调用时读，不在模块加载时快照 —— 镜像时代两个模块各自快照，加载顺序不同就会算出不同的根，测试先 require 再设 env 时尤其明显」）。既有测试已经在为此做变通（`graph-engine.test.js` 注释：「`graph-run-sse` 在模块顶部快照 `GRAPH_RUNS_DIR`，必须连它一起重新 require」）。**教训在一个模块里学会了，没传出去** —— 这是本清单的第六个实例，形态还不一样：不是事实被复述，是**「事实该怎么读取」的约定只传了一半**。 +12c. **路径缺陷 B 已处理**：`goal-contract.js` 里那个声明了却从未使用的 `RUNS_ROOT` 要么真的接上、要么连 `resolveRunDir` 一起删；不留「注释承诺了、代码不兑现」的常量。 +13. **停止即出队**：`max=1`，任务 A 跑着、B 排队，对 A 点「停止」→ **B 在几秒内自动起跑**（验证 §五.1.1 的漏斗钩子覆盖了 `stopRun` 这条不走 `settleRun` 的路径），不是等 60s 兜底。 +14. **预算耗尽即出队**：把 A 的预算调到极小让它烧成 `blocked` → B 同样自动起跑。 +15. **排队期间 replan**：B 排队时点「重新规划组织」改动 org graph → B 出队后**按新图跑**，没有孤儿节点、没有卡死（验证 `syncRunNodesToDef`）。 +16. **manual 不堵队**：下一个 `manual` 任务 + 一个 `auto` 任务 → manual 不被自动拉起，auto 正常起跑；在控制台上对 manual 点「开始」才占坑。 +17. **`report_to` 穿过队列**：带 `report_to` 下达一个会排队的任务，等它出队跑完 → 上级 agent 确实收到 `/api/agent/task/report`（验证 §四.7 禁令二）。 +18. **OKR 只写一次**：一个挂了 `okr_node_id` 的 goal 下放 3 个 task，其中一个 failed → OKR 节点**只被写一次**，且不是被最后那个 failed 覆盖的（验证禁令一）。 +19. **拆分正常**：下达一个「做个官网」这类 goal → `task-planning` 产出 ≥2 条带依赖的 task，**全部是 `draft`**，界面上可改可删可加；点「全部下达」后按依赖顺序依次跑。 +20. **拆分失败必须降级**：让 `task-planning` 连续 3 轮产出非法 JSON → goal 转 `active` + 1 条同描述 task + 界面标注「自动拆分失败」，**绝不能卡在 `planning`**。 +21. **拆分记账**：拆分后 `goals.planning_tokens > 0`，且界面上看得到这一笔（验证 goal 层花费不再隐形）。 +22. **不该花钱的路径不花钱**：`split: false` 与存量 `POST /:cid/tasks` 都**不触发任何 LLM 调用**（mock 层计数验）。 +23. **上游失败 → 下游标红**：A 失败后依赖它的 B 转 `blocked` 且带 `upstream_failed:T-A`；**A 重跑成功后 B 自动回 `queued`**（验证 blocked 是每次 tick 推导出来的，不是落死的状态）。 +24. 全量 `npx vitest run` 不掉，重点是 §九.1 那批回归 + 新本体的 `_registry.json` 登记（`template-refs.test.js`）。 + +--- + +## 九、风险与已知取舍 + +### 1. `queued` 混进 `run_status` 取值域 —— 本次最大的回归面 + +新增一个状态值，所有按 `run_status` 分支的地方都要逐个确认 `queued` 不被误当可执行。实现时必须挨个看过并补测试： + +**先纠正一个前提**：`queued` run **有一整套 `pending` 节点行**（`createRun` 建行时就按定义插全了），它和 `ready` run 在数据上唯一的差别就是 `run_status` 那一个字段。所以「靠没有节点行自然报错」这道想象中的防线**根本不存在** —— 唯一的闸门是各处对 `run_status` 的判断，必须逐个钉死。 + +| 位置 | 期望 | +|---|---| +| `graph-engine.advanceOne` | 已有 `if (run.run_status !== 'running') return result(..., 'run-not-running')` ✅ 天然挡住。**但要加断言测试钉死** —— 这是防止 `queued` run 被误推进的唯一一道闸 | +| `graph-engine.startRun` | 只接受 `ready`；对 `queued` 必须拒绝（出队顺序是先 `queued→ready` 再 `startRun`，不能反过来） | +| `TERMINAL_RUN_STATUS` / `settleRun` / `propagateToParent` | `queued` 既非终态也非活跃态，收敛判定不该碰到它；且它只可能是 root run，不涉及向上传播 | +| `ACTIVE_ROOT_RUN_STATUS`（`graph-run.js` + `company.js` 两处） | 不含 `queued` ✅ 天然正确，但要加断言测试钉死 —— **这条正是 §四.3 出队原子性的全部依赖** | +| `GraphConsole.loadRuns` 的 `roots.find(active) \|\| roots[0]` | 会把 `queued` run 当成「最近的 root run」画图 —— **必须改**，否则入队一条任务就把 org 栏画崩 | +| 服务启动的中断任务恢复（`server/index.js`）| `queued` 不该被当成「被中断的 run」拉起，它该走调度器 | +| `company-heartbeat-service` | 同上 | +| `GET /api/graph-runs/:id` / SSE | `queued` run 要能正常读（控制台要显示「排队中」），不能因为没有 `started_at` 之类的字段报错 | + +### 2. 「排队」这条路当初被明确否决过，现在要对它负责 + +`company.js` 的注释原话：*选拒绝的理由是，仓库里没有任何出队/唤醒的 worker，排进去的任务不会被自动消费，那是一条会静默丢任务的路*。**这条判断在今天仍然成立** —— 它只是被 §五.1.1 的调度触发解除。所以调度器（尤其是挂在 `transitionRun` 上的那个漏斗钩子）是本次的**功能主体**，不是收尾工作；验收 2 / 9 / 13 / 14 专门验它。**初稿用「枚举四个触发点」的写法本身就漏了两条最常见的释放路径**（`stopRun` 与预算耗尽），这正说明枚举法在这里靠不住——症状是任务静默躺在队里，而界面上它长得跟「正在排队」一模一样。 + +### 3. `description` 双写（DB + `task-goal.json`） + +两份都在入队那一刻写、之后都不可变（§四.4）——结构上不可能不一致。这正是「已下达不给改」的真正理由，而不是保守。 + +### 4. 归档只是隐藏 + +`data/companies/{cid}/runs/{runId}/` 仍在磁盘上。本次不做 GC；需要时另立清理任务（按 `archived_at` 早于 N 天）。 + +### 4bis. 三处「排队打破了『下达即执行』这个隐含假设」 + +本次复核抓到的三条同形缺陷，共性是**既有实现都没错，只是它们都默认了「请求进来 → 立刻执行」**，排队把那个假设拆了，而且拆得非常安静（都不报错）： + +| # | 缺陷 | 症状 | +|---|---|---| +| 1 | `report_to` 只活在请求闭包里（§四.7 禁令二）| 上级 agent 永远等不到回调，没有任何日志 | +| 2 | 节点行在 `createRun` 时快照，排队期间 replan 就分叉（§四.3 末）| 出队后 run 卡死在「有新节点但没有 run 行」 | +| 3 | `okr_node_id` 逐 task 写同一个 OKR 节点（§四.7 禁令一）| 最后一个收敛的 task 说了算，done 会被后来的 failed 覆盖 | + +**实现时的通用检查法**：凡是「从 HTTP 请求体里取出、直接交给 driver / 闭包」的东西，在排队模型下都要问一句「几小时后它还在吗」。 + +### 4ter. `task-planning` 引入的三个新风险 + +1. **多一次会失败的 LLM 调用挡在「下达任务」前面**。今天下达是一次同步 DB 写，现在中间插了一次几十秒、可能失败的 agent 调用。降级路径（§四.9 约束 2）和界面上的逃生口（§七.2）**不是可选项** —— 少了任何一个，一次 agent 卡死就等于整个下达入口不可用。 +2. **拆分质量决定预算消耗**。拆出 5 条 task 就是 5 份 `DEFAULT_TASK_BUDGET`（各 100 次调用 / 500 万 token）。这是「产出一律 `draft`、必须人确认」的根本理由 —— 那一步是唯一一道成本闸门。界面上要显式提示「N 个任务 ≈ N × 单任务成本」。 +3. **新本体的真正闸门是「毕业」，不是 registry 登记**（§四.9 约束 4/5 已纠正初稿的反向结论）。`agent.md` + `soul.md` 没写满就停在 `draft`，`hire()` 返回 `body_not_ready`；而 `_registry.json` 缺条目只是少个 `benchmark_score`。另外本体正文的相对路径写错**不报错只静默降级**（§四.9 约束 6）—— 这是本文档点名的静默故障家族里最新的一个成员。 + +### 4quater. 本文档有三处要求属于同一个惯犯模式：「实现在、零调用方」 + +§四.1 砍掉 `goals.budget_json`、§四.7 禁令二要求 `report_to` 落库、验收 12c 处理 `goal-contract.js` 那个声明了却零使用的 `RUNS_ROOT` —— 三条都是同一件事：**别留下「代码写了、但没有任何活的调用方/消费方」的东西。** + +这不是洁癖，仓库里有完整的证据链，而且证据本身就说明问题： + +| 出处 | 原话 | +|---|---| +| `graph-engine.js`（`indexNodeOutputs` 注释）| 「凡『靠 agent 自觉』的环节几乎全部落空过（**goal-contract 零调用**、`setPlanWorkGraph` 零调用、三值透传只接了读那一半）」| +| `graph-engine.js`（跨层判据处）| 「（『实现在、零调用方』的**第五次**）」| +| `graph-run-route-io.test.js` 文件头 | 「就是这一路踩了**十几次**的『实现在、零调用方』换个方向再来一次（这次是前端在、后端没喂）」| +| `graph-edge-contracts.test.js` 文件头 | 「`declareEdgeContract` **零调用方**」| +| `graph-run.js:243` | 「契约声明与产物索引都在库里，界面上却看不见，等于**又一次**『实现在、零调用方』」| +| `27-goal-contract-format.md:101` | 「T0 交付后有四轮时间里，全仓库唯一提到 `goal-contract.js` 的是一句注释 —— 实现完整、零调用方、零单测，§六 验收 1 **从未被执行过**」| +| 27-P3/P4 §八 已关闭项 6 | `ProcessGuard` 生产代码里从未被实例化、`RunRegistry.add()` 从未被调用、杀进程那条链同样零调用方 | + +**这些记录证明的不是「有这个问题」，而是「发现了也没人回来收」** —— 有人数到第五次，有人写「十几次」，然后它继续复发。所以本文档凡是写「必须落库 / 必须接上调用方 / 零调用方就删掉」的地方，都请当成硬要求，而不是可以留到下一轮的整洁度问题。 + +**批 1 的落点**：验收 12c 就是收其中一个（`resolveRunDir` + 那个死常量）。同时按并行会话的建议加一条不变式测试 —— 「凡是声明了 `GRAPH_RUNS_DIR` 覆盖的模块，该覆盖必须真的被用到」，形状照抄 `server/tests/unit/agents-root-single-holder.test.js`（**「样本非空」前置断言别省** —— 扫不到文件时会静默全绿，那正是这类测试自己变成「零调用方」的方式）。 + +### 5. 两套 `T-` id —— 由 §十二 的统一消解，但在那之前是真风险 + +`agent-chat.js` 的 `/task/dispatch` 也发 `T-` 开头的 id 并写 `system/tasklog/`。**批 1-4 期间两套并存**，长得像但不同源，读日志时别混（本文档的 id 一律带 `-{4hex}` 后缀，肉眼可分）。批 5（§十二）把存储统一到 `tasks` 表之后，这个风险随之消失 —— 那时 `T-` 只有一个来源。 + +### 6. 并行是最后一批，且要单独验 + +批 4 会 `DROP` `idx_graph_runs_one_active_root` —— 删掉最后一道 DB 兜底。守卫改成事务内 count + admit（SQLite 单写者天然序列化）。不与界面改动同批上线。 + +--- + +## 十、实施顺序 + +| 批 | 内容 | 验收 | +|---|---|---| +| **1 · 两级模型落库** | `goals` / `tasks` 建表 + **存量回填脚本（§四.8）** + ID 生成器修正 + `POST /:cid/tasks` 兼容改造（自动建 goal、`report_to` 落库）+ `GET` 列表端点 + 退役 `/goals` 别名 | 4 / 10 / 11 / **12** | +| **2 · 控制台左栏 + 拆分** | `GoalTaskPane` 两级树 + URL 选中态 + `loadRuns` 修正 + **`task-planning` 本体（含 `_registry.json` 登记）+ 拆分链路 + 失败降级**+ 两步表单 | 1 / 19 / 20 / 21 / 22 | +| **3 · 排队** | `run_status='queued'` + `RUN_TRANSITIONS` + `syncRunNodesToDef` + `task-scheduler`（漏斗钩子 + 三个辅助触发 + 重入保护 + 上游失败推导 blocked）+ `depends_on` 环检测 + 入队/取消/rerun 端点 + §四.7 两条禁令 + §九.1 全部回归点 | 2 / 3 / 5 / 6 / 7 / 8 / 9 / 13-18 / 23 | +| **4 · 并行**（单独排期）| `max_parallel_tasks` + `DROP` 唯一索引 + 事务内 admit。**与 [27-P4](../../todo/system-design/27-p4-parallel-and-artifacts.md) §一.3 同一件事**，实施以那份为准 | 另立验收 | +| **5 · 任务体系统一**（单独排期）| 见 §十二：`executor` / `assignee_agent_id` / `parent_task_id` 三字段 + `/task/dispatch` 换存储 + 删会话反推 + `tasklog` 回填 | 25-30 | + +> 批 3 的验收从 6 条涨到 12 条，是本次复核的直接结果 —— 13/14/15 三条各自对应一个「初稿会实现出来的静默故障」。 + +### 与并行进行中的「agent 目录结构重构」的关系（2026-08-18 核实） + +写本文档期间，另一条工作线正在做 **agent 目录结构重构**（`system/templates/` 并入 `system/agents/`，两份 `_registry.json` 合一），工作区约 900 个变更**尚未提交**。它与本文档有实质交集，逐条核实结果： + +| 交集点 | 结论 | +|---|---| +| 本文档逐字引用的全部函数 / 常量（`settleRun` / `markRunReady` / `stopRun` / `defaultPlanWorkGraph` / `PLAN_MAX_ROUNDS` / `writeTaskGoalArtifact` / `reportRunOutcome` / `ACTIVE_ROOT_RUN_STATUS` / `saveTaskMeta` / `getAggregatedTasks`）| **全部存活**。重构改了约 650 行、5 个文件，但没有动这些锚点 —— 27-P3/P4 那条「只写函数名不写行号」的体例在这里直接兑现了价值 | +| 本文档的五条**行为性**结论（`markRunReady` 写死 `planning`、`settleRun` 只在 `advanceOne` 内被调、`stopRun` 不走 `settleRun`、`reportRunOutcome` 读 `run.okr_node_id` 与闭包里的 `ctx.reportTo`）| **逐条复验仍然成立** | +| `work-graph-db.js`（`createRun` 建节点行、`updateRunStatus` 条件更新、`RUN_TRANSITIONS`、唯一索引）| **完全未被改动** —— 第二轮复核里最关键的那批发现不受影响 | +| 新建本体的做法（§四.9）| **初稿有一条写反了，已纠正**：`system/templates/` 彻底取消（本体落 `system/agents/`）；`_registry.json` 已不是数据源头（`seedAgents` 扫目录当真相），登记是可选的；真正的闸门是**毕业**（`agent.md` + `soul.md` 非空且无 `_base` 哨兵，否则 `hire()` 返回 `body_not_ready`）；本体正文的相对路径另有三条硬规矩，写错静默降级。详见 §四.9 约束 3-6 | +| `agent-chat.js`（+455 行）、`company.js`、`agent-manager.js` | 都是本文档批 1 / 批 5 要改的文件。**新端点是新增代码，不冲突**；但 §十二 的前提「`/task/dispatch` 的 URL 与请求体一个字都不能动」需要在批 5 开工前**基于重构后的版本重新核一遍**（`tools-base.md` 目前未被改动，是个好迹象） | + +**对排期的影响**：批 1 可照常开工（`work-graph-db.js` 无人触碰，建表 + 回填是纯新增）。**批 2 的 `task-planning` 本体应当等 agent 重构落地后再建** —— 否则本体目录与登记方式要按旧形态做一遍、再按新形态改一遍。批 5 在那之后重新核 `agent-chat.js`。 + +批 1+2 上线就已经解决用户提的核心痛点（历史任务看不见、需求无法分解）；批 3 才是「不再只能有一个」。 + +--- + +## 十一、开放问题 + +1. ~~谁把 goal 拆成 task？~~ **已定案（2026-08-18）：`task-planning` agent 进 v1**，产出 `draft` 任务清单由人确认后下达，详见 §四.9。 +2. ~~goal 级的验收谁做？~~ **已定案（2026-08-18）：仍然是 `org-validator`**，在 goal 层再调一次同一个本体，输入是该 goal 全部 task 的产物合集。详见 §四.10。 +3. ~~失败的 task 挡不挡住依赖它的下游？~~ **已定案（2026-08-18）：自动转 `blocked` 并在界面标红**，给「重跑上游」与「强制放行」两个出路；`blocked` 每次 `tick` 重算而不落死，上游恢复后下游自己回 `queued`。详见 §五.1.2。 +4. ~~跨公司任务总览 / 两套任务树并存~~ **已定案（2026-08-18）：统一到 `tasks` 表一套，删掉会话反推那套。** 详见 §十二（批 5）。 +5. ~~`max_parallel_tasks` 放 `company.json` 还是建 `company_settings` 表？~~ **已定案（2026-08-18）：放 `company.json`。** 详见 §五.2。 + +> **本文档的开放问题至此全部关闭。** 后续新增的疑问按惯例继续往这一节追加，不要在正文里留疑问句。 +6. ~~goal 级总预算怎么定口径？~~ **已定案（2026-08-18）：预算先不考虑，不做 goal 级闸门。** `goals.budget_json` 保持砍掉。**但 `planning_tokens` / `validation_tokens` 两个记账字段保留** —— 它们不是闸门，是让 goal 层那两次 agent 调用的花费**可见**；不记就是 `defaultPlanWorkGraph` 注释点名的「隐形的一半」，而且界面上「本次拆分消耗 ~N tokens」这个确认步骤要用它。 +7. ~~排队中的任务能不能改依赖？~~ **已定案（2026-08-18）：可以改。** `queued` 状态开放 `depends_on` 的 `PATCH`，见 §六.3。当初担心的「改完位次怎么算」不成立：`queuePosition` 只按 `priority → seq → created_at` 排，`depends_on` 决定的是**够不够格出队**，两者正交，改依赖不动位次。 + +--- + +## 十二、批 5 · 任务体系统一（用户定案：统一到一套，删掉另一套） + +### 12.1 现状：两套并存，而且**新体系已经依赖旧体系的一半** + +| | A · 本文档的体系 | B · 会话反推的体系 | +|---|---|---| +| 存储 | `goals` / `tasks` 表（SQLite） | `system/tasklog/{taskId}.json` 一任务一文件 | +| 入口 | `POST /api/company/:cid/goals`、`/tasks` | `POST /api/agent/task/dispatch`（**agent 之间派单**，`tools-base.md` 里写着让 agent curl 它）| +| 收敛 | `settleGoal` → OKR + `report_to` | `POST /api/agent/task/report`（更新 todo/plan → 更新 OKR → 推进 Pipeline → 唤醒上级）| +| 任务树 | `goal_id` / `depends_on` 显式存 | `TaskService.getAggregatedTasks()` **扫全部 agent 的 conversations 反推**父子关系（391 行）| +| 读接口 | `GET /:cid/goals`、`/tasks` | `GET /api/tasks`、`/api/tasks/:id/timeline`（59 行）| +| 前端 | `GoalTaskPane`（§七）| `TaskTimeline.vue`（736 行，唯一消费方）| +| id | `T-{base36}-{4hex}` | `T-{base36}`（同前缀不同源，§九.5）| + +**关键事实：A 的收敛出口调的正是 B 的 `/api/agent/task/report`。** 批 1 之前这个出口是 `company.js:reportRunOutcome`（run 级），批 1 把它删掉、换成了 `task-settle.js:reportGoalOutcome`（goal 级，挂在 `transitionRun` 漏斗上）——**函数换了，依赖关系没变**。两套不是并列关系，A 的回调链路仍然长在 B 身上。所以「删掉另一套」不能理解成整片删除 —— 要删的是**存储与反推**，不是入口与回调。 + +### 12.2 删什么、留什么 + +**删**： +- `system/tasklog/` 目录及其读写（`agent-chat.js` 的 `saveTaskMeta` / `loadTaskMeta`，`task-service.js` 的 `_loadTaskMetas`）； +- `TaskService.getAggregatedTasks()` —— **从会话记录反推任务树**这整套启发式。父子关系改为显式存字段，不再猜。 + +**留（改数据源）**： +- `POST /api/agent/task/dispatch` **URL 与请求体形态一个字都不能动** —— 它写在 `packages/agent-core/base/common/tools-base.md` 里，是所有 agent 的工具说明；改了等于同时改所有 agent 的提示词。只把它的存储从写 JSON 文件改成写 `tasks` 表。 +- `POST /api/agent/task/report` 同上（A 的回调依赖它）。 +- `TaskService.getTaskTimeline()` —— 它读的是 agent 的 `conversations/`，那是**真实的一手数据**，不是反推。留着，只把「有哪些 task、父子是谁」换成查表。 +- `TaskTimeline.vue` 保留，换数据源。 + +### 12.3 `tasks` 表要吸收 B，需要三个字段 + +B 的 task 与 A 的 task 有一处真实差异：**执行载体不同**。A 的 task 跑一张 org graph（走调度器），B 的 task 是直接派给某个 agent 起一次对话（`autoExecute`）。硬说成一回事会骗自己，所以显式建模： + +```sql +executor TEXT NOT NULL DEFAULT 'graph', -- 'graph'（跑 org graph，走 §五 调度器） + -- 'agent'（直接派给某个 agent 对话，不进队列） +assignee_agent_id TEXT, -- executor='agent' 时派给谁（B 的 `to`） +parent_task_id TEXT REFERENCES tasks(id), -- B 的任务链；A 的 depends_on 是同级依赖，两者不同 +``` + +**调度器只管 `executor='graph'`**（§五.1 的候选筛选加这一条），`executor='agent'` 的 task 由 `/task/dispatch` 自己起对话，进表只为了「可见、可查、可串成树」。 + +`goal_id NOT NULL` 怎么办：**agent 派单时自动建一个 goal**（`title = '来自 {from} 的派单'`、`created_by = from`），与 §六.3 已经为 `POST /:cid/tasks` 设计的兼容路径**同一条**。模型保持干净，不给 `goal_id` 开可空的口子。 + +### 12.4 顺带修好的两件事 + +1. **30 分钟去重从「扫全目录 JSON」变成一条 SQL**。现在 `/task/dispatch` 每次派单都 `readdirSync` + 逐个 `JSON.parse` 整个 `tasklog/` 来找相似任务 —— 任务一多就是 O(n) 次磁盘读，且相似度判断本身也没索引可用。改成 `WHERE company_id=? AND assignee_agent_id=? AND status='queued' AND created_at > ?` 一条查询。 +2. **两套 `T-` id 合一**（§九.5 那条风险就此消失）。id 生成统一走 §四.5 的 `T-{base36}-{4hex}`。 + +### 12.5 迁移 + +`system/tasklog/*.json` 回填进 `tasks` 表，与 §四.8 的 root run 回填**放在同一个脚本**（同一次数据形态变更，分两个脚本只会让「跑了哪个没跑哪个」变成新问题）。字段映射：`to → assignee_agent_id`、`parentTaskId → parent_task_id`、`objectiveId/goalId → 所属 goal 的 okr_node_id`、`status` 按 `dispatched/done/failed/blocked` 映射。**回填后目录改名为 `system/tasklog.bak-unify/` 而不是直接删**，跑顺一个版本再清。 + +### 12.6 排在批 5 的理由 + +它依赖 `tasks` 表存在（批 1）、依赖 `executor` 语义在调度器里被正确排除（批 3）。而且它**改的是 agent 的生产链路**（派单 / 汇报 / 唤醒），风险面与前四批完全不同 —— 前四批坏了是控制台不好用，这一批坏了是**所有 agent 互相派不了活**。必须单独一批、单独验收。 + +### 12.7 验收 + +25. `POST /api/agent/task/dispatch` 请求体不变，派单成功后 `tasks` 表出现 `executor='agent'` 的行，`system/tasklog/` 不再产生新文件。 +26. 派单的 task **不进调度队列**（`executor='agent'` 被 §五.1 排除），不占 `max_parallel_tasks` 的坑。 +27. 30 分钟去重仍然拦得住重复派单，且不再读目录（改成 SQL）。 +28. `POST /api/agent/task/report` 汇报链路四步（todo/plan → OKR → Pipeline → 唤醒上级）全部照常；**`task-settle.reportGoalOutcome` 那条依赖它的路也照常**（批 1 之前这条依赖挂在已删除的 `reportRunOutcome` 上）。 +29. `TaskTimeline.vue` 任务列表与时间线都正常，父子关系来自 `parent_task_id` 而非会话反推。 +30. 存量 `system/tasklog/*.json` 全部回填进表，目录改名保留。 + +--- + +## 十三、批 1 实施记录（2026-08-18，commit `7f24ef0`） + +> 体例照 [27-P3/P4](../../todo/system-design/27-p3-p4-work-graph-console.md) §十：**设计正文不改写，只在这里与实现对账**。 +> 凡本节与前文冲突，**以本节为准** —— 前文是设计时的判断，本节是跑出来的事实。 + +### 13.1 落地了什么 + +| 交付 | 落点 | +|---|---| +| `goals` / `tasks` 两张表 + CRUD + `depends_on` 环检测 | `work-graph-db.js` | +| ID 生成器 `G-/T-{base36}-{4hex}` + 主键碰撞重试 | 同上（`insertWithFreshId`：4hex 只有 65536 种取值，实测同毫秒建 2000 条会撞 5 次） | +| goal / task 全套端点 + `POST /:cid/tasks` 向后兼容 | `company.js` | +| 退役 `/api/goals` 与 `/:cid/goals` 两个 OKR 别名 | `index.js` / `agent-server.js` / `company.js` | +| **终态回写 + goal 收敛 + OKR 写一次** | `graph-run-sse.transitionRun` 钩子 → `task-settle.js`（新） | +| 三处「模块加载时快照 `GRAPH_RUNS_DIR`」改调用时读 | `graph-engine.js` / `graph-run-sse.js` / `goal-contract.js` | +| 存量回填脚本（幂等 + `--dry-run`） | `scripts/migrate-runs-to-goal-task.js` | +| 4 个测试文件，含不变式测试 | `server/tests/unit/` | + +全量：**116 文件 / 1057 测试全绿**。 + +### 13.2 与设计正文的四处偏离（**以本节为准**） + +**① `blocked` 在 task / goal 两层都不是终态。** +正文 §四.3 的状态机把 `blocked` 与 `completed`/`failed` 并列画成终态。实现时发现那是错的，而且**实跑复现出了后果**： + +``` +预算耗尽 → task=blocked, goal=failed, OKR=failed +人加预算恢复 → run=running +跑完 → run=completed, task=blocked, goal=failed, OKR=failed ← 永久对不上 +``` + +`RUN_TRANSITIONS` 里 `blocked: ['running','stopped']` —— 对 run 它是**可恢复态**，`reviveParentFromChild` 还会自动把它拉回 running。若 task 层把它当终态，恢复后跑完时 `settleTaskFromRun` 与 `settleGoalStatus` 两次条件更新**静默命中 0 行**，无日志无事件。 + +定案：`TASK_TERMINAL_STATUS` 只含 `completed / failed / cancelled`；**只要有一条 task 处于 `blocked`，goal 就不收敛**（不写 OKR、不唤醒上级）。`blocked` 的语义是「挂起等人介入」，与那三个不同类。run 转 blocked 时**仍然**把 task 写成 blocked（界面要看得见卡住），只是不触发收敛。 + +连带：归档守卫从「过严」翻到「过松」过一次 —— 恢复后 task 停在 `blocked`、run 却在 running，用户能归档掉一条**正在烧预算**的 run。现由 `taskHoldsRun()` 兜住（`ACTIVE_ROOT_RUN_STATUS` **派生**出 `RUN_HOLDING_STATUS`，不复述第二份字面量）。 + +**② goal 级是唯一汇报出口，`reportRunOutcome` 已删除。** +正文 §四.7 把它写成「root run 收敛后的唯一出口」。批 1 的唯一形态是 1 goal : 1 task，而 `createTask` 继承 `goal.report_to`，于是 run 级与 goal 级两条汇报会**就同一件事把上级 agent 唤醒两次**（其中一次带的是它从没见过的 `G-` id）。 + +grep 确认 `reportRunOutcome` 无其它调用方（连它自己那行 `module.exports` 都零人 require），整体删除。理由：run 级只在 auto 模式触发（manual 收敛不走 driver），本来就是半条链路；goal 级挂在唯一漏斗上，manual / auto / stopped / blocked 全覆盖。 + +同时 `from` 的口径修正为**实际交付者**：`terminalOrgAgent` 从 `company.js` 搬到 `org-graph-service.terminalAgentId()`（唯一持有者），不再用 `goal.created_by` —— 那是「谁下的单」，默认字面量 `'human'`，下游 `readStateFile('human','todo.md')` 会静默落空。 + +**③ dispatch 挑第一条「可跑的」draft，不是恒取 seq 最小那条。** +`validateDependsOn` 只拒环、不拒正向引用，所以「第 1 条依赖第 2 条」是合法输入；而恒取 `drafts[0]` 会让这种 goal **永远下达不了**（`blockers` 恒非空）。批 2 的 `task-planning` 产出契约正是「`depends_on` 只引用本次产出的 seq」，产出乱序完全在射程内。 + +连带：`PATCH /:cid/tasks/:taskId` 补上了改 `seq` 的入参翻译 —— 原先 409 的 hint 写着「改依赖或 seq」，而那个端点从不读 `body.seq`，**两条自救路径只有一条通**。 + +**④ `POST /:cid/goals` 批 1 只做同步路径。** `task-planning`（§四.9）与 goal 级 `org-validator` 验收（§四.10）属批 2，`verdict` / `validation_tokens` 两列目前只有定义、无写侧。 + +### 13.3 过程：三轮编排，19 条缺陷 + +| 轮次 | agent | 产出 | +|---|---|---| +| 1 · 实现 | 11 | 建表 + 端点 + 回填 + 测试；对抗复核报 **10 条缺陷** | +| 2 · 修复 | 6 | 修完 10 条；复核确认真修好，但报出 **4 条修复自己引入的新缺陷** | +| 3 · 再修 | 4 | 修完 4 条；全绿 | + +**最值得记的一条**是②那类：*第二轮的修复引入了第三轮才发现的缺陷*，而且是同一个形状——「界面撒谎」的镜像版本。这说明**对抗复核不能只做一轮**：修复本身和实现一样会出错，而且更隐蔽（它长得像在解决问题）。 + +判定为**非问题**的 5 条也记一笔（复核给了证据）：进度查询确实是一条 `GROUP BY` 不 N+1；`LIMIT` 的字符串插值前置了 `Number.isInteger` 守死；`tasks.goal_id` 的真外键在 `foreign_keys=ON` 下不与软删冲突；回填脚本的两条幂等判据覆盖了「脚本重跑」与「新链路建出来的 run」；`/goals` 别名确为零调用方（`OkrDashboard.vue` / `CompanyDashboard.vue` / `bin/lemon.js` 全走 `/okr`）。 + +### 13.4 一条对外可见的破坏性变更 + +`POST /api/company/:cid/tasks` 的 `goal_id`：旧代码原样存进 `graph_runs.goal_id` **不校验**，新代码要求它是 `goals` 表里本公司的真行，否则 **404**。仓库内无此调用方，但外部 agent 的 curl 若一直往这里传 OKR 节点 id 之类的值，会从 201 变 404。**404 是对的**（那种调用方本来就在制造悬空外键），但属于对外可见的行为收紧。 + +### 13.5 留给下一轮的两条 + +1. **run 转 `blocked` 时仍写 `finished_at`** —— 「挂起 ≠ 结束」，界面会显示一个随后被恢复覆盖掉的结束时间。改它要动 `settleTaskFromRun` 的签名。 +2. **run 从 `blocked` 恢复成 `running` 时不把 task 写回 `running`** —— task 行会在恢复期停在 `blocked`。归档守卫已经兜住了它的风险（§13.2 ①），要消掉需要在 `afterRunTransition` 上加「离开终态时反向回写」，与批 3 的调度器一起做更合适。 + +--- + +## 十四、批 2 实施记录（2026-08-18） + +> 体例同 §十三：**设计正文不改写，只在这里对账；冲突处以本节为准。** + +### 14.1 落地了什么 + +| 交付 | 落点 | +|---|---| +| `task-planning` 本体（毕业判据实测通过） | `system/agents/task-planning/` + `_registry.json` | +| 拆分链路（3 轮 errors 回喂 / 降级 / token 记账 / 注入缝 `setPlanTasks`） | `server/services/task-planning.js`（新） | +| goal 级 `org-validator` 验收（注入缝 `setValidateGoal`） | `server/services/goal-validation.js`（新）+ `task-settle.js` | +| 目标·任务两级栏 + 四栏布局 + 两步表单 | `GoalTaskPane.vue` / `NewGoalForm.vue` / `goal-task-model.js` / `GraphConsole.vue` | +| 中断恢复：启动时补跑验收与汇报 | `task-settle.resumePendingGoalValidations` + `server/index.js` | + +全量：**118 文件 / 1112 测试全绿**，`npm run web:build` 通过。 + +### 14.2 与设计正文的六处偏离（**以本节为准**） + +**① 拆分完成/降级后 goal 落 `draft`，不是 `active`。** +§四.9 约束 2 与 §八 验收 20 都写「降级后 goal 转 `active`」。实现落 `draft`，理由成立且已复核确认：`active` 的语义已被 `markGoalDispatched` 钉死为「**已下达**」（连带盖 `dispatched_at` = 描述冻结点），而 §四.9／§六.2 同时要求「产出一律 draft、不自动入队」。两者只能取一个 —— 拆分失败却标 `active` 且一条 task 都没起，界面上就是一个「进行中」却什么都没跑的 goal，正是本文档反复点名的「界面撒谎」。硬要求「绝不能卡在 planning」两种落点都满足。 + +**② `POST /:cid/goals` 默认异步（202 + `status:'planning'`）**，`split:false` 或显式 `tasks[]` 走同步 201。存量 `POST /:cid/tasks` 走同步路径，**不会因为这次改动多花一次 LLM 调用**。 + +**③ `mode` 是三级继承**：`tasks[i].mode` > goal 级 `mode` > `'manual'`，**goal 级对显式 `tasks[]` 同样生效**。这是对存量调用方的行为变化（原先显式 `tasks[]` 恒 manual），已写进端点 JSDoc + 用例钉住 —— 从「静默变化」变成「明写约定」。 + +**④ 占位判词不出 API。** 验收窗口里 `goals.verdict` 挂的是内部认领 token（含进程随机段与时间戳），`goalView` 对外只回 `(验收进行中)`。判定走 `task-settle.isPendingVerdict`，不在路由层比字符串。 + +**⑤ 认领带租约。** 见 §14.3 第 3 条。 + +**⑥ 新增两列**：`goals.planning_error`（降级原因，界面展示）、`goals.reported_at`（汇报可查性）。`reported_at` 的迁移**带回填** —— 不回填的话加完列第一次启动会把库里所有历史终态 goal 当成「汇报丢了」重报一遍。 + +### 14.3 三条跨进程竞态（全部用真探针实跑复现后才判定修好） + +**1 · `runGoalSplit` 无条件把 goal 写回 `draft`，抹掉并发发生的「已下达」。** +触发它的正是表单自己推荐的逃生口：用户点「跳过，按单任务下达」→ goal 变 `active` 且 run 在跑 → 拆分收工把它写回「草稿」，并多插 N 条 draft task → `settleGoalIfAllTasksDone` 看到 `[T1 completed, T2..TN draft]`，draft 不是终态 → **永不收敛**，OKR 不写、上级不唤醒。 +修法：条件更新 `WHERE status='planning' AND archived_at IS NULL`，没命中就一条 task 都不插（但**钱照记**）。 + +**2 · CAS 把最终态提前写进库，验收窗口内重启即丢，且查不出来。** +`verdict=NULL` 也正是「1 条 task 跳过验收」的合法形态，**没有任何查询能把「验收丢了」和「本来就没验」分开**。 +修法：占位判词 + 启动重推。三态可分：`NULL`（没验）/ 占位前缀（进行中或丢了）/ 真判词（已定案）。 + +**3 · 认领语句自己构成了它点名要避开的形态。** +第一版重推的认领是 `SET verdict=RESUMING WHERE verdict IN (PENDING, RESUMING)` —— **写进去的值就在 WHERE 里**，已被认领的行照样匹配，`changes` 恒为 1。而函数注释白纸黑字写着「认领写的是**另一个**占位值，别的扫描者就不会再选中它」。**注释是对的，代码没兑现。** +实测后果：`org-validator 调 2 次 / OKR 写 2 条 / token 双记`。 +修法：claim 值 = 前缀 + 进程随机段 + 进程内自增 + **时间戳**；认领的 WHERE 只认上一个态；回写改成 `WHERE verdict = @claim` 的条件更新决胜；**主路径也走同一套闸门**。 + +> 第三轮之后仍剩一条同款：`reported_at` 只有认领一道闸，且接受任意占位值当旧值 —— B 实例会把 A 实例**手上还活着**的汇报抢走，上级被叫醒两次。第四轮补上**租约**（`CLAIM_LEASE_MS`，默认 10 分钟）：活着的认领不许抢，过期的才准抢。**只认 `null` 不行** —— 那会把「可恢复的洞」换成「不可恢复的洞」。 + +### 14.4 过程：四轮，22 条缺陷，其中 6 条是修复自己引入的 + +| 轮次 | agent | 结果 | +|---|---|---| +| 1 · 实现 | 11 | 全绿；复核报 8 条 | +| 2 · 修复 | 5 | 修 6 条；复核报 1 条**新引入**的高危（认领竞态，实跑复现） | +| 3 · 再修 | 5 | 竞态真消灭（跨进程探针验证）；复核又报 4 条 | +| 4 · 收尾 | 人工 | 租约 / 归档不重报 / 输家记账 / 判词不出 API | + +**第四轮修完挂了 3 条测试，全都是测试在钉住缺陷本身**：断言「抢跑输家的 token 为 0」（= 钱静默蒸发）、断言「重推能抢走新鲜占位」（= 跨进程重复汇报）。其中一条的注释写着「这里模拟的是进程死后重启」，而它构造的占位值是**新鲜的** —— 注释描述 A 场景、代码构造 B 场景、断言按 A 场景写。按注释的语义把占位值做旧，测试就对了。 + +> **这是本文档第二次记录同一条规律**（§十三.3 是第一次）：修复与实现一样会出错，而且更隐蔽 —— 它长得像在解决问题。批 1 三轮、批 2 四轮，两次都不是一轮收敛的。 + +### 14.5 留给下一轮 + +1. **跨进程判活要租约 + 心跳**：现在靠固定租约窗口，抢跑者仍可能多烧一次 LLM（副作用一个都不会多做）。 +2. **汇报语义是 at-least-once**：exactly-once 要 `/api/agent/task/report` 认幂等键（goal id + 收敛时间），属接收侧改动。 +3. **拆分超时只在本进程存活期间成立**：进程中途被杀会留下 `status='planning'` 的 goal，需要启动时扫描重推（与批 3 的中断恢复一起做）。 +4. `io-model.check.js` 仍是零调用方（同款前科，批 2 已把 `goal-task-model.check.js` 转成真测试）。 + +--- + +## 十五、批 3 + 批 4 实施记录（2026-08-19） + +> 体例同 §十三 / §十四：**设计正文不改写，只在这里对账；冲突处以本节为准。** + +### 15.1 落地了什么 + +**批 3 · 排队**（commit `87b776c`，**该提交由第三方会话在对抗复核完成前误提，见 §15.4**） +`run_status='queued'` + `RUN_TRANSITIONS` + `syncRunNodesToDef` + `task-scheduler.js`（tick / sweep / +依赖推导）+ 入队/取消/rerun 端点 + 控制台队列显示与三处可见性修复。 + +**批 4 · 并行**（本次） +`idx_graph_runs_one_active_root` **已 DROP**；`max_parallel_tasks` 从 `company.json` **调用时读** +（缺省 1、非法回落 1 并留声、硬上限 20）；准入判据「从活跃集外进入活跃集」按额度计数。 + +全量：**128 文件 / 1240 测试全绿**，`npm run web:build` 通过。 + +### 15.2 批 4 的生死线：超发（真进程实跑，不是纸面论证） + +删掉唯一索引 = 删掉最后一道 DB 兜底，此后全靠 `updateRunStatus` 的准入事务。**用 8 个真 node 进程 +并发抢坑实测**（每进程最多重试 40 次），四组： + +| max | 抢到坑的进程 | 库里实际活跃 root run | 判定 | +|---|---|---|---| +| 1 | 1 | 1 | ✅ | +| 2 | 2 | 2 | ✅ | +| 3 | 3 | 3 | ✅ | +| 5 | 5 | 5 | ✅ | + +落选进程全部吃 `RunSlotBusyError`（各 40 次全被拒），零 `other` 错误。准入的四步缺一不可： +`BEGIN IMMEDIATE` → 事务内重读 → 事务内计数 → 同事务条件更新。 + +### 15.3 批 3 复核的 4 条遗留（本次修完） + +**N1 🔴 `cancelQueuedRun` 的前提被批 3 自己改没了** +它的注释说「对一条还没开跑、没有子 run 的排队 run，`stopRun` 是多余的一圈」—— +而 `requeueBlockedRootRun` 落地后，`queued` 的 run **可以是跑过一半的**（有 success 节点、 +有活着的子 run；预算撞顶时引擎只把 root 置 blocked，子 run 要到节点边界才落 paused）。 +探针实测：取消后节点残留 `ready`+`success`、子 run 残留 `paused / stop_requested=0` —— +**那条 running 的子 run 继续调 agent 烧 token**。改为无条件走 `engine.stopRun`。 + +**L1 ⚠️ 恢复路径对 manual 只兑现一半** +`graph-engine.js` 写着「『T1 永远回不来』这个后果因此消失」，但调度器 `filter(execution_mode === 'auto')` +故意不碰 manual → 人点「启动」→ 退回队列 → 坑空了 → **没人接**。 +定案：**「manual 不自动出队」约束的是首次起跑的授权**；一条已被人亲手起过、因坑满被退回队列的 +manual，授权早就给过了，让它自己接回来是**兑现人刚才那次点击**，不是新授权。 +判据用 **`attempt > 0`** 而不是 `started_at` —— 后者看着更贴切，但 `requeueBlockedRootRun` +退回队列时会把它清成 NULL，**恰好在需要它的那一刻是空的**（实测踩过）。 + +**N2 🟠「退回队列」对用户完全不可见** +`startRunSync` 早返回 200 + `{ok:true, requeued:true}`，而 `GraphRunPane.act()` 只在 `!r.ok` 时写 +`err` → 界面零提示；随后按钮全灰、run 面板换成定义视图、提示语说「节点状态一律 pending」（**假的**）。 +`requeued` 字段全前端零处读取。现加 `notice` 一行明说「已退回队列排队，坑一空会自动接着跑」。 + +**N3 🟠 `isSlotRaceError` 的判据被探针证伪** +注释称 `InvalidTransitionError` = 「已被别人从 queued 推走」。实测：被推走时条件更新 +**返回 0、不抛**；真正抛它的只有「**调用方声明了非法转换**」。那一支把调用方的 bug 当竞态吞掉 +且不留日志。已删除该分支（与批 4 删 UNIQUE 那支同一理由：让它吵起来）。 + +> **4 条里有 3 条是同一个模式：注释承诺的前提被本轮自己的改动改没了，注释还留着。** +> §十三.3 / §十四.4 已经就这个模式立过两次案，这是第三、四、五次。 + +### 15.4 一次流程事故：代码在复核完成前被第三方提交 + +`87b776c` 由另一个会话（`lemonboss-68`）在 16:56 提交，**而批 3 的对抗复核 17:00 才出结果** +（就是 §15.3 那 4 条）。提交说明里的「1201 用例全绿」准确描述了当时那次测试运行，但它压在一份 +尚未通过复核的代码上，读起来像质量背书。该会话已写交接文档 `27-p3c-batch3-handover.md` 并更正记录。 + +**教训**：多会话共用同一个 worktree 时，「工作区里的改动」不等于「可以提交的改动」—— +未提交本身可能就是一种状态声明（这里是「在等复核」）。提交前问一句的成本，远低于把一份 +已知有缺陷的代码写进 main 的成本。 + +### 15.5 留给下一轮 + +1. **边界守卫会误判并行会话的改动**：它比对整仓 `git status` 差集，那里面**没有「谁写的」这一维**， + 多会话共用 worktree 时必然把开发会话的改动算到当时在跑的图节点头上（实测已导致一条 run 被判 + `boundary_escape`）。批 3 修的是这条日志的**可见性**（列出文件清单），**误判本身没修**。 +2. **机器级闸门仍然不存在**：`SessionPool` 没有 `maxSessions`，`task-queue.js` 另有个 `MAX_CONCURRENT=3` + 抢同一台机器。批 4 只放开了公司级额度（硬上限 20），机器压不压得住没有任何守卫。 +3. 批 5（两套任务体系统一）未开工，预研方案已就绪。 + +--- + +## 十六、批 5 实施记录（2026-08-19/20，进行中） + +> 体例同 §十三～§十五。**本节随批 5 推进增量补写**，未做的步骤明确标出来。 + +### 16.1 进度 + +| 步 | 内容 | 状态 | +|---|---|---| +| 1 | `tasks` 表吸收 `executor` / `assignee_agent_id` / `parent_task_id` | ✅ `5cd91c3` | +| 2 | `system/tasklog/*.json` 回填进 `tasks` 表 | ✅ `514ec3d` | +| 3 | `/task/dispatch` 改写 `tasks` 表（**URL 与请求体一个字不动**） | ✅ `12880b8` | +| 4 | 30 分钟去重从「扫目录」改成一条 SQL | ✅ 同上 | +| 5 | `GET /api/tasks` 改读表；删 `TaskService.getAggregatedTasks()` 的会话反推 | ✅ `71cf45e` | +| 6 | 调度器只管 `executor='graph'` | ✅ 同上 | + +**批 5 完成，P3C 五批全部实施完毕。** 全量：**132 文件 / 1257 测试全绿**。 + +### 16.2 第 1 步踩到的：一个会让**所有存量库开不了**的顺序问题 + +第一版把 `CREATE INDEX ... ON tasks(assignee_agent_id)` 写进了建表块。**建表块整体先于迁移块执行**， +而存量库上 `CREATE TABLE IF NOT EXISTS tasks` 是 no-op —— 表还是批 4 的形态、没有那一列， +于是这句索引直接抛 `no such column`，`getDb()` 起不来。 + +**新建库完全正常**（单测默认走的就是这条路），所以只测新建库根本看不见这个洞。 +是专门去跑「批 4 形态的库重启一次」才撞出来的。索引已挪进迁移块、排在 ALTER 之后， +守卫见 `tasks-executor-migration.test.js`。 + +> 由此得到一条可复用的规矩：**凡是加列，必须同时测「存量库重启」这条路**。 +> 新建库的路径由每个单测天然覆盖，存量库那条没人走 —— 而生产上只有存量库。 + +已知不对称（写在代码注释里）：`ALTER TABLE ADD COLUMN` 加不了 CHECK 也加不了外键， +所以存量库上 `executor` 的取值域**只由应用层守**，与新建库的 CHECK 不同源。 + +### 16.3 第 2 步的关键判断：沿用原 `taskId` + +回填时**不新发 id**。理由是引用面：`conversations/task-{taskId}` 是目录名、汇报链路按 taskId +找回这条派单、summary 里互相引用。换 id 等于把这些引用全断掉，**而回填的目的恰恰是 +「别让历史消失」**。 + +`company_id` 落保留 id `_global`：tasklog 的行**没有 company 这一维**（`from`/`to` 都是本体 id）， +全局 agent 的会话本来就落在这个 id 下（28 §5.1）。刻意不去猜某条派单「其实属于哪家公司」—— +猜错会让它出现在错误的公司任务列表里，那比「都归 `_global`」更难发现。 + +实跑：4 条派单全部回填成功、零失败；再跑一次全部跳过、零新增。 + +### 16.4 第 3 步（下一步）的前提，动手前必须先核实 + +`POST /api/agent/task/dispatch` 与 `/task/report` 的 **URL 与请求体形态一个字都不能改** —— +它们印在 `packages/agent-core/base/common/tools-base.md` 里，是**所有 agent 的工具说明**， +改它等于同时改所有 agent 的提示词。 + +而 `server/routes/agent-chat.js` 在 2026-08-19 被另一个会话大改过（会话回收 / `IdleTimer` / +`CALL_KINDS` / 进程泄漏修复，见 `310a2b2` / `2092a2e` / `b0b2b62`）。**预研是在那之前写的**， +所以第 3 步动手前要重新读一遍现状，而不是照预研的描述改。 + +> 顺带记一处过期：`tools-base.md` 里印的是 `http://localhost:3000`，而实际端口是 **3010** +> （`server/config.js`）。已经真咬过人 —— 回填出来的派单正文里有人手写了「端口 3010，不是 3000」 +> 来纠正它。这一处该在第 3 步一起改（改的是端口不是契约形态）。 + +### 16.5 第 3 步（最危险的一步）怎么做到不碰契约 + +`/task/dispatch` 的副作用有九步，**只有第 ⑧ 步是「存储」**： + +``` +① 校验 from/to/task + 两个本体目录存在 +② 去重（30 分钟内同接收方 + 正文互相包含） +③ 推断 parentTaskId +④ 正文净化（\n →
，| → |） +⑤ 写目标 agent 的 todo.md +⑥ 写发送者的 plan.md +⑦ 更新 OKR 节点 → in_progress +⑧ saveTaskMeta(taskId, {...}) ← 只换这一步的内脏 +⑨ autoExecute → POST /api/agent/{to}/chat +``` + +**把 `saveTaskMeta` / `loadTaskMeta` 变成 tasks 表的适配器**，其余八步一行不动 —— +URL 与请求体形态天然不可能变。②③ 顺带从「扫目录」改成带索引的 SQL，**判据一个字没改**， +换的只是从哪儿把候选捞出来。 + +字段落点的三个判断： +- **`objectiveId` 不单独存**：它恒等于 okr node id 的首段（`OkrService.parseNodeId` 与 + `reportRunOutcome` 同一口径），且两处读取方都是 `if (objId && meta.nodeId)` —— 从不单独用。 +- **`sourceConvId` 删掉**：全仓零读取方。正是本文档 §九.4quater 立过案的「实现在、零调用方」， + 不往新表里再搬一份。 +- **`summary` / `execution_conv_id` 加列**（用户定案 A）：前者当前只写不读但语义清晰、界面迟早要它； + 后者有真读取方。**没有选「加一个 legacy meta 的 JSON blob 列」** —— §十二 引 R-19.2 明确否过 + 「建表而不是 JSON」，那会把一个已被否掉的形态重新引进来。 + +验证方式是**真起服务打一遍**，不是只看测试绿：照 `tools-base.md` 印的请求体原样 POST → 200 + +老形态响应；再打一次 → 409 且 `existingTaskId` 正确；`/task/report` 之后 `status→completed`、 +`summary` 与 `finished_at` 都在；`loadTaskMeta` 往返出来的形状与老 JSON 逐字一致。 + +### 16.6 第 5 步：删掉的是「猜」，不是「记录」 + +原 `getAggregatedTasks` 是 122 行的启发式：扫全部 agent 的 `conversations/`，按会话 id 里的 +`T-xxx` 归组，再用三条策略（meta 的 `parentTaskId` / from agent 的活跃会话时间包含 / +master conv 的标题相似）**猜**父子关系。猜出来的树没法验证对错，而且每次请求都要遍历所有 +agent 的会话目录 —— 路由那 10 秒缓存就是为它加的。 + +现在父子关系是 `tasks.parent_task_id`，派单时就显式写下来了。`task-service.js` **391 行 → 236 行**。 + +**`getTaskTimeline` 保留**，但来源拆清楚： +- 任务树（有哪些子任务）→ `tasks` 表，显式、可验证； +- 时间线正文 → agent 的 `conversations/`，那是**一手记录，没有替代品**。 + +两处口径变化（已写进代码注释）：`agents` 从「会话里出现过的 agent 集合」变成「谁派的 + 派给谁」； +`conversationCount` 从「扫出来的文件数」变成「有没有起过执行会话」（0/1）—— 为一个列表字段 +遍历所有 agent 的会话目录，正是这次要去掉的那笔开销。 + +### 16.7 两次「测试全绿 ≠ 没坏」 + +这一批里有两处只有**真跑**才会暴露的问题，测试一条都没红： + +1. **`routes/tasks.js` 漏改**：它自己还在算 `t.conversations.length`，而 `conversations` 是 + 会话反推那套的产物、已随之删除 → `GET /api/tasks` 直接 500。没有任何测试走那条路。 +2. **控制台 org graph 栏宽**（§十五 之外，`81629b7`）：320px 减去 padding 只剩 292px， + 而两个节点加一条边要 380px+ —— 节点名被从中间切断。构建、单测、探针全都不会报。 + +> 与之对照，§十六.2 那个「存量库一启动就炸」是**测试能覆盖但没人写**的类型。 +> 三者合起来是一条经验：**新建库的路径、纯逻辑的路径由单测天然覆盖； +> 「存量数据」「真实接口」「肉眼可见」这三类必须另外安排人去走一遍。** + +### 16.8 留给下一轮 + +1. `system/tasklog/` 目录**还在**（4 个历史文件，已回填进表）。按 §十二.5 应改名为 + `system/tasklog.bak-unify/` 而不是直接删，跑顺一个版本再清。本轮未做。 +2. `tools-base.md` 里印的端口仍是 `localhost:3000`，实际是 **3010**。已经真咬过人 —— + 回填出来的派单正文里有人手写「端口 3010，不是 3000」在纠正它。**改端口不改契约形态**， + 但它是所有 agent 的工具说明，值得单独一次改动 + 通告。 +3. `TaskTimeline.vue` 未动。它按字段名取值，本轮保住了全部 12 个字段，但 `agents` / + `conversationCount` 的语义变了（见 §16.6），界面上的措辞可能要跟着调。 + +--- + +## 十七、收尾之后（2026-08-20）—— §16.8 与 §15.5 全部收掉，外加真跑挖出来的三条 + +> 体例同 §十三～§十六。这一节记的是 P3C 五批之后的清尾，**以及一次真跑**： +> 它才是这批工作真正的验收，也是三条缺陷的出处。 + +### 17.1 §16.8 / §15.5 的欠账（commit `8f4c1b6`） + +| 来源 | 项 | 结果 | +|---|---|---| +| §16.8-1 | `system/tasklog/` 改名保留 | ✅ 改成 `system/tasklog.bak-unify/`；回填脚本**两处都认**（先原位置再备份位置，顺序不能反：万一有人从备份恢复出一份新的 tasklog，那份才是要回填的） | +| §16.8-2 | agent 提示词里的端口 3000 → 3010 | ✅ 守卫 `agent-docs-port.test.js`。第一版扫出 5 条误报，全是某 agent 目录下 Python venv 里 playwright 的 ThirdPartyNotices —— 第三方文件不是提示词，已跳过 `venv/site-packages/workspace/conversations/train` | +| §16.8-3 | `TaskTimeline.vue` 的措辞 | ✅ `conversationCount` 批 5 之后只会是 0/1，界面却写 `Convs: N` —— 读的人会以为这条任务只有一次对话。改成有/无的表达 | +| §15.5-1 | 边界守卫误判并行会话的改动 | ✅ 见 17.2 | +| §15.5-2 | 机器级闸门 | ✅ `SessionPool.maxSessions()` + `SessionPoolFullError` + `_evictForRoom()`，守卫 `session-pool-max.test.js` | +| §15.5-3 | 批 5 | ✅ §十六 | + +### 17.2 边界守卫：从「乱扣帽子」改成「留证据、不判罚」 + +守卫的前提是「窗口内新增的仓库改动 = 这个节点写的」。**多会话共用 worktree 时这个前提是假的** —— +`git status` 的差集里没有「谁写的」这一维。实测已发生：批 3 的开发改动把一条 run 判成 +`boundary_escape` 卡住（就是 §17.4 那条）。 + +可检测的信号：节点**开跑那一刻**仓库就已经有源码目录的未提交改动 → 有人正在这个 worktree 上开发 +→ 窗口内新增的源码改动无法归属 → **降级为只记证据、不判罚**（与既有的 `unattributable` 桶同一语义）， +而不是关掉守卫：证据照留，人一眼看得出「这次没判罚，因为当时仓库是脏的」。 + +`BOUNDARY_GUARD=strict` 强制判罚（CI / 干净环境），`=record` 一律只记。守卫 8 例，含关键对照： +**仓库脏时不判、干净时同样一处越界仍判 fail** —— 守卫没被削弱，只是不再乱扣帽子。 + +### 17.3 测试在往生产图库写（commit `20fed0a`） + +`agent-chat-tenant-isolation.test.js` 每跑一次往共享的 `data/graph.sqlite` 落 2 条 goal + 2 条 task。 +库里 31 条 goal 里 **22 条是它的残留**，而测试一直全绿。 + +根因是**批 5 的存储迁移留下的半截清理**：`/task/dispatch` 的元数据从 `system/tasklog/*.json` +换进了 `tasks` 表（§十六 第 3 步），而这个用例的 `afterAll` 只会清那个目录 —— +清理代码还在、清的东西已经不在那儿了。**这是这次迁移唯一没被任何测试照到的一面。** + +> **它是本仓库第四次踩「测试污染共享库」，但换了个方向进来。** +> 前三次（`BENCHMARK_DB_PATH` / `USERS_DB_PATH` / `SKILLS_DIR`，记在 `test-isolation-env.test.js` +> 文件头）都是「设了 env，生产代码不读」，那条守卫查的正是这个形态。 +> 这次是**一个字都没设** —— 没有可查的东西，守卫自然查不出来。 +> 静态扫源码也判不出「这个测试会不会开库」（要跨 require 链推导）。 + +修法两层：用例自己开一次性库；`graph-db.getDb()` 加**运行期闸门**（`VITEST` 为真且没设 +`GRAPH_DB_PATH` → 抛，报错里点名 env、点明「要在 require 之前设」，因为 `DB_PATH` 是模块级 const）。 +闸门放在 `getDb()` 不放模块顶层：只为取常量而 require 是合法用法，顶层抛会误伤。 +守卫 `graph-db-prod-guard.test.js` 4 例（含「没有 VITEST 时不生效」—— 防止把生产一起锁死）。 + +存量清理：删掉 `created_by LIKE 'zz-tenant-%'` 的 22 goal + 22 task，其余 9 条真实数据一条没动。 + +### 17.4 那条卡了两天的 run：真正卡住它的不是边界守卫，是墙钟预算 + +`run_9168bd24f46c`（`e2e-demo` 做 lemonai 官网）2026-08-18 16:19 判 `blocked` 之后再没能起来。 +17.2 修完误判之后它**仍然跑不动** —— 第二道锁在预算上： + +> 墙钟按 `now - spent.started_at` 算，而 `started_at` 是「第一次花钱的绝对时刻」。 +> 这与 `blocked` 的语义**直接对撞**：预算耗尽、节点判罚都会把 run 打到 `blocked`， +> 而 `blocked` 的定义就是**挂起等人工**。人隔夜来处置 → 等待那段被算成「已用」→ +> 一起跑就报 `wallclock_ms` 耗尽 → 再 `blocked` → 再等人。**过夜的 run 永远醒不过来。** + +而且报出来的原因具有误导性：写着 `wallclock_ms`（跑太久），实际是**等人等太久**。 +这条 run 只花了 7/100 次调用、69,961/5,000,000 tokens —— **预算用掉不到 2%**。 + +改法：`spent` 改记 `active_ms`（累计活跃时长），`started_at` 退化成「当前这一段的起点」， +不在 `running` 时为 null。起止结算挂在 `graph-run-sse.afterRunTransition` 这个**单一漏斗**上。 + +⚠️ 钩子必须放在那个 early return **之前**：进 `running` 既不是收敛、也不空坑，两个条件都不满足， +放后面就变成「只结算停下来、从不开始计时」，症状是 `active_ms` 恒 0、墙钟形同虚设，**而且照样全绿**。 + +**第一版的洞是真起服务、真点重试才撞出来的**（commit `9891c3b`）：预算行挂在 root， +我就只认 root 的转换；而人工重试一个 work 层节点动的是**子 run**（`blocked → running`）， +root 全程 `blocked` —— 子 run 跑整场、墙钟一次都没开始计。**单测当时全绿，因为它们只喂了 root。** + +存量重锚必须放在**开库路径**里：钩子只在「进 / 出 running」时触发，而升级那一刻正停在 +`running` 的 run 不会再进一次 `running`。⚠️ 第一版把这段迁移写进了 `graph-db.js` 的 `migrate()`， +而 `graph_runs` 是 `work-graph-db` 建的表、graph-db 的迁移块跑在它之前 —— 新库上直接 +`no such table: graph_runs`，`getDb()` 起不来。**和 §16.2 那次「加索引写进建表块」是同一类顺序问题，这是第二次。** + +### 17.5 真跑结果（2026-08-20） + +重启服务（迁移在真库上跑到）→ 重试 `org-planner-sdd` → 逐节点 `/next`： + +| 节点 | 结果 | +|---|---| +| `org-planner-sdd` | ✅ success（attempt 2） | +| `org-planner-benchmark` | ✅ success | +| `org-planner-validator` | ✅ success → 整张 work graph 五节点全 success，work run `completed` | +| （父节点自动拉回） | ✅ `reviveParentFromChild` 把 root 从 `blocked` 拉回 `running` | +| `org-coder` | → 起实现层子图 `run_91c4e38492dd` | +| `org-coder-impl` | ✅ success | +| `org-coder-validator` | 判 fail → **走回退边打回 `org-coder-impl`**（`loopCount: 1`），判词：项目根下只有一份计划文档，没有任何交付文件 | + +**返工闭环在真跑里成立了** —— 这是 P3 的核心机制第一次由真 agent（不是注入的假 executor）走通。 +预算 13/100 次调用、114,847/5,000,000 tokens。 + +### 17.6 这一轮的三条经验 + +1. **「修完 A 就能跑」是个假设，不是结论。** 17.2 修完误判之后那条 run 仍然跑不动， + 第二道锁（墙钟）只有真去点一次才露出来。**卡住的东西可以有不止一把锁。** +2. **单测喂什么形状，就只能守住什么形状。** 墙钟第一版的 8 条用例全绿， + 因为它们全都直接喂 root run —— 而生产里触发计时的是**子 run**。 + §16.7 说「存量数据 / 真实接口 / 肉眼可见三类要另外走一遍」，这里要补第四类： + **树形结构的机制，测试必须喂非根节点**。 +3. **同一类顺序问题第二次了**（迁移写错模块 vs §16.2 加索引写进建表块）。 + 判据可以固化成一句话：**凡是写迁移，先问「这张表是谁建的」，答案就是这段迁移该待的文件。** diff --git a/docs/todo/system-design/27-graph-agent-architecture.md b/docs/todo/system-design/27-graph-agent-architecture.md index 154c8f4..68835d9 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-08-18 校准，此前这一行落后两个阶段）: 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) §十 实现记录 + 第六轮终验回填；收尾见 [27-P3B](./27-p3b-real-run-runway.md)）；**P4 📝 设计中/未实现**（[27-P4](./27-p4-parallel-and-artifacts.md) 自述 v0.1 设计阶段） +> **状态**（2026-08-20 校准）: 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](./27-p3b-real-run-runway.md)，验收 7 真跑不成立、2/4/8/9 未验）；**P4 📝 设计中/未实现**（[27-P4](./27-p4-parallel-and-artifacts.md) 自述 v0.1 设计阶段） > > ⚠️ 这一行是别人判断「哪些文档能从 `docs/todo/` 搬去 `docs/done/`」的依据 —— 它过期会连累后面每一次迁移判断，改阶段状态时请顺手更新它。 > **命名**: 新增 agent id / 表名 / 字段名前先读 [27-NAMING 命名规范](./27-naming-conventions.md) diff --git a/docs/todo/system-design/27-p3b-real-run-runway.md b/docs/todo/system-design/27-p3b-real-run-runway.md index 8c22760..e17ec51 100644 --- a/docs/todo/system-design/27-p3b-real-run-runway.md +++ b/docs/todo/system-design/27-p3b-real-run-runway.md @@ -5,6 +5,11 @@ > **日期**: 2026-08-16 > **起因**: [27-REQ](./27-requirement.md) R-18（招聘归 `workgraph-planning`；停用 mock 改真 CLI） > **前置**: P3 主体已实现并提交（`c3abf4a` 起七轮），测试 719/719 全绿 +> **状态**（2026-08-20 校准）: 📝 **仍在推进**。第一批验收 1/3 已验、2 的后半与 4 未在干净环境重验； +> 第二批验收 7 ⛔ 真跑不成立（§六bis 缺陷③ `readme-writer` 混进 org graph，**未修**）； +> 第三批 8/9 真 CLI 未验。 +> §六bis 缺陷② 的**根因**（边界守卫误判并行会话的改动）已于 2026-08-20 修掉， +> 见 [27-P3C §17.2](../../done/system-design/27-p3c-goal-task-model.md) —— 但**根因修了不等于验收点验了**，那几条仍要重跑一遍。 --- @@ -760,8 +765,8 @@ agent 读的是 `agent.md`，那一侧不改，模型就会继续以为「前三 | # | 标准 | 状态 | |---|---|---| | 1 | 服务启动后 `system_agents` 与 `system/templates/` 一致，无悬空 `company_hired` 行；新加一个模板目录、重启服务，它自动出现在表里 | ✅ **已验**（生产库实查 + hermetic 用例）。一处**已知且合理**的偏差：`system/agents/` 与 `system/templates/` 同名的 6 个 id（`agent-creator` / `org-innovator` / `innovator-{digest,evolver,hunt}` / `evolver-youtube-crawler`）按设计 skip，仍是 `global_agent`。图用到的本体都不在这 6 个里 | -| 2 | 起一个真 CLI 的 run，节点产出全部落在 `data/companies/{cid}/projects/{pid}/` 内；`git status` 在宿主仓库无任何新增/修改 | 🟡 **前半已验、后半被并行 agent 打破**（2026-08-17，§六bis）：`workgraph-planning` 的产物真的落在 `data/companies/p3bfin/projects/p-24vxi8/workspace/` 内，`project-root.json` 四环闭合；宿主仓库出现的两处改动经查是**并行的 Master agent** 写的（缺陷②），已复原。被判罚的那个 work 节点自己一个字节都没往仓库写 | -| 3 | 故意让节点往产物目录外写，被守卫拒绝并在 timeline 留痕 | ✅ **真 CLI 已验**（2026-08-17，§六bis）：git 扫描确实扫到了宿主仓库里的那处改动，`node.boundary` 事件带完整 `entries`，结果被降级判 fail 且 `fail_reason='boundary_escape'` 落库。**但同一次也验出了误判**：那处改动是并行的 Master agent 写的，不是被判罚的节点写的（W3「拦不住」第 5 条，见 §六bis 缺陷②）。判罚逻辑侧另有 W12 补完那一轮加的三条分支用例 | +| 2 | 起一个真 CLI 的 run，节点产出全部落在 `data/companies/{cid}/projects/{pid}/` 内；`git status` 在宿主仓库无任何新增/修改 | 🟡 **前半已验、后半被并行 agent 打破**（2026-08-17，§六bis）。**2026-08-20 补记**：后半那个「被并行 agent 打破」本身已经不再导致误判 —— 守卫改成「节点开跑那一刻仓库就脏 → 只记证据、不判罚」，见 [27-P3C §17.2](../../done/system-design/27-p3c-goal-task-model.md)。**但这条验收标准本身仍未在干净环境下重验**。当时的原始记录：`workgraph-planning` 的产物真的落在 `data/companies/p3bfin/projects/p-24vxi8/workspace/` 内，`project-root.json` 四环闭合；宿主仓库出现的两处改动经查是**并行的 Master agent** 写的（缺陷②），已复原。被判罚的那个 work 节点自己一个字节都没往仓库写 | +| 3 | 故意让节点往产物目录外写，被守卫拒绝并在 timeline 留痕 | ✅ **真 CLI 已验**（2026-08-17，§六bis）：git 扫描确实扫到了宿主仓库里的那处改动，`node.boundary` 事件带完整 `entries`，结果被降级判 fail 且 `fail_reason='boundary_escape'` 落库。**但同一次也验出了误判**：那处改动是并行的 Master agent 写的，不是被判罚的节点写的（W3「拦不住」第 5 条，见 §六bis 缺陷②）。判罚逻辑侧另有 W12 补完那一轮加的三条分支用例。**2026-08-20 补记**：误判那一半已修（[27-P3C §17.2](../../done/system-design/27-p3c-goal-task-model.md)，`BOUNDARY_GUARD=strict|record` 两个开关 + 8 例守卫，含「仓库干净时同样一处越界仍判 fail」的对照） | | 4 | 造一份非法契约跑 `benchmark-validator`：判决为失败且引擎按失败处理（**不是** success） | 🟡 **静态成立，未真跑**。模板已改写 `verdict: "attributed"`，而 `FAILING_VERDICTS={attributed,inconclusive}` → `readNodeProduct` 置 `failingVerdict=true` → `callAgentNode` 判 `fail`（`graph-engine.js:473/385`），链路读通；防线测试三次反例变异全部变红 | > 2 与 3 都要真 CLI 才验得了，而真 CLI 现在会先死在 W5/W6 上。**这两条应挪到第二批之后一起验。** diff --git a/docs/todo/system-design/27-p3c-batch3-handover.md b/docs/todo/system-design/27-p3c-batch3-handover.md deleted file mode 100644 index 7fa94c4..0000000 --- a/docs/todo/system-design/27-p3c-batch3-handover.md +++ /dev/null @@ -1,184 +0,0 @@ -# 27-P3C 批 3 交接 —— main 上有一份待修复的代码 - -> 记录时间：2026-08-19 17:1x -> 记录人：Claude 会话 `lemonboss-8x`（本文档的作者，也是下面 87b776c / b0b2b62 两笔提交的执行者） -> 状态：**未收口**。等 lemonboss-78 的批 3 修复完成后一起处理。 - -## 一句话 - -`87b776c` 把 lemonboss-78 还在等对抗复核的批 3 提进了 main，复核结论随后给出 4 条问题； -main 现在躺着一份**已知有缺陷**的代码，而那笔提交的说明里写着「1201 用例全绿」。 - ---- - -## 一、时间线（事实） - -| 时间 | 事件 | -|---|---| -| 会话启动 | 本会话拿到的 git status 快照里已有批 3 的全部在途文件（9 个未跟踪 + 一批 M） | -| 16:53 | 本会话完成三处控制台可见性修复（见 §三） | -| 16:54 | `npm run test:unit` → 126 文件 / 1201 用例全绿 | -| **16:56:24** | **`87b776c`** feat(27-P3C): 批 3 —— 队列 / 恢复路径 / 控制台三处修复 | -| **16:56:39** | **`b0b2b62`** fix(session-pool): SessionPool 空闲 TTL | -| 16:56:44 | `bash start.sh` 重启后端 + 前端（用户要求） | -| 17:05 | lemonboss-89 提交 `2092a2e`（精确提交，只含自己的文件） | -| 17:00 左右 | 批 3 的对抗复核结论出来：**1 条半修 + 3 条新引入** | -| 17:1x | lemonboss-89 跨会话核对，本会话确认两笔提交都是自己做的 | - ---- - -## 二、main 上现在有什么 - -### `87b776c` —— 批 3（作者：lemonboss-78，提交者：本会话，**未经作者同意**） - -内容：公司级任务队列（`task-scheduler.js`）、恢复路径补洞、控制台三处可见性修复。 -25 files changed, 5691 insertions(+), 305 deletions(-)。 - -**已知缺陷（来自 17:00 的对抗复核）：4 条 —— 1 条半修 + 3 条新引入。** - -> **2026-08-19 由 lemonboss-78（批 3 作者）补齐**：以下 4 条是 17:00 那次对抗复核的原文结论， -> 每条都有独立探针实跑证据。本文档作者原先只确知第 1 条、其余刻意留空——那个做法是对的。 - -**N1 🔴「取消排队」会留下一个还在烧 token 的孤儿子 run**（优先级最高，唯一有直接金钱成本的一条） -`company.js:1768` 的注释说「对一条还没开跑、没有子 run 的排队 run，`stopRun` 是多余的一圈」。 -**这个前提被批 3 自己的 `requeueBlockedRootRun` 改没了** —— `run_status='queued'` 的 run 现在可以是 -跑过一半的（有 success 节点、有 ready 节点、有活着的子 run）。探针实跑：取消后 root=stopped / -task=cancelled，而节点残留 `aa2:ready, aa1:success`（没批量 skipped），子 run 残留 -`paused / stop_requested=0`（没走 `suspendRunTree`）。 -失败路径：预算撞顶时子 run 可能仍是 `running`（引擎只把 root 置 blocked，子 run 要到节点边界才落 paused）→ -人点「启动」→ 退回队列 → 改主意点「取消排队」→ **那条 running 子 run 既没收到停止信号也没被结算，继续调 agent**。 -前端 `goal-task-model.js:171` 的按钮 title 还在说「它还没开跑，所以不会有半截产物」。 -命中入口三个：`/tasks/:id/cancel` 的 queued 分支、blocked 分支①、`DELETE /tasks/:taskId`。 - -**L1 ⚠️ 半修 · 恢复路径对 manual 任务不成立** -批 3 的修法是「恢复撞坑满 → 退回队列」，对 **auto 真的成立**（探针：T2 收敛后 T1 无人干预自动跑起来）。 -但 `tickInner` 第 4 步 `filter(t => t.execution_mode === 'auto')` 故意不碰 manual（§五.2bis「manual 不堵队」）， -于是 manual 任务：人点「启动」→ 退回队列 → 坑空了 → **没人来接**，任务躺着、sweep 每 60s 空转。 -而 `graph-engine.js:2345` 的注释白纸黑字写着「**「T1 永远回不来」这个后果因此消失**」——**对 manual 不成立**。 - -**N2 🟠「退回队列」这件事对用户完全不可见** -`startRunSync` 早返回 `{ok:true, runStatus:'queued', requeued:true}` 走 **200**。 -`GraphRunPane.act()` 只在 `!r.ok` 时写 `err` → 界面零提示；`can('start')` 因 `queued ∉ ALLOW.start` 把按钮全部置灰； -task 翻 queued 后 `hasStartedRun()` 返回 false → `GraphConsole.vue:248` 把 run 面板换成 org graph **定义视图**， -提示语「节点状态一律 pending」**是假的**（这条 run 有 success 节点、有活着的子 run）。 -`requeued` 这个字段**全前端零处读取**（`grep -rn requeued web/src` 无命中）。 -用户点了「启动」，得到的是：什么都没说、按钮全灰、图不见了。 - -**N3 🟠 `isSlotRaceError` 第三条判据的注释被探针证伪，且它吞真错误还不打日志** -`work-graph-db.js:110` 声称 `InvalidTransitionError` = 「这条 run 已被别人从 queued 推走了」。 -实跑证伪：被抢走后再 CAS **返回 0，不抛异常**；真正抛 `InvalidTransitionError` 的是**调用方声明了非法转换** -（`expected = from` 是调用方声明值，`canTransitionRun` 判的是 `expected → to` 而不是 `cur.run_status → to`）。 -所以这条判据把「调用方写错了转换」当成竞态吞掉，且不留日志。 - -> 这 4 条里有 3 条是同一个模式：**注释承诺的前提被本轮自己的改动改没了，注释还留着**。 -> 27-P3C §十三.3 / §十四.4 已经就这个模式立过两次案，这是第三次。 - -> 提交说明里的「126 文件 / 1201 用例全绿」**需要更正**：这句话准确描述了 16:54 那次测试运行， -> 但它压在一份尚未通过复核的代码上，读起来像质量背书，替 lemonboss-78 说了它没说过的话。 - -### `b0b2b62` —— SessionPool 空闲 TTL（作者：lemonboss-89，提交者：本会话） - -给图执行侧的常驻会话上空闲 TTL，堵住「一节点一进程、永不释放」的泄漏（实测 23h 漏 7 个进程）。 -自带 3 个测试，全过。**lemonboss-89 已确认认这笔**，内容无争议，提交信息是替它写的。 - -### `2092a2e` —— agent-chat 会话回收补漏（作者/提交者：lemonboss-89） - -精确提交，未波及他人在途文件。无争议。 - ---- - -## 三、本会话自己写的三处控制台可见性修复 - -这三处是本会话的原创工作，混在 `87b776c` 里（`GraphConsole.vue` 同文件内与批 3 的改动交织， -无法干净拆分）。**内容与批 3 的 4 条缺陷无关**，处理批 3 时不必连带回退。 - -| # | 症状 | 改在哪 | 验证 | -|---|---|---|---| -| 1 | 顶栏墙钟恒 `now - started_at`，没有终点：一条昨晚就 blocked 的 run 第二天还在涨到「16h 58min」，而那是页面上唯一的时间信号 ——「已停等人处置」被显示成了「还在跑再等等」 | `web/src/views/GraphConsole.vue`：终点取 `run.updated_at`，run 不在 `running/planning` 就冻结并标「已停」 | ✅ 浏览器实测：`16h 58min` → `31min 已停`（31min 是真实耗时） | -| 2 | 越界日志只报「留下 N 处改动」，文件清单只在 `timeline.ndjson` 里，界面翻不到。而判罚就是按这份清单下的 | `web/src/components/graph-console/node-signals.js`：`describeEvent` 拼进 `entries` | ✅ 浏览器实测：显示出 `?? server/tests/unit/task-scheduler.test.js` | -| 3 | run 收敛成 blocked 时只写 task 状态不写原因，任务列表那行只剩一个橙色「挂起」，必须逐层点进 org 图 → work 图 → 节点详情才知道发生了什么 | `server/services/task-settle.js`：新增 `describeRunBlock`，把「哪个节点 + fail_reason + 判词摘要」写进 `tasks.blocked_reason` | ⚠️ 仅单测（`server/tests/unit/task-blocked-reason.test.js`，5 例；注释掉修复后红 4 例）。界面上看不出效果 —— `blocked_reason` 是 run 收敛那一刻写的，存量 run 补不上 | - -第 3 条顺带把一条口头约束变成了会红的测试：原因串**绝不能**以 `UPSTREAM_BLOCK_PREFIX` -（`upstream_failed:`）开头，否则会被调度器当成「依赖推导出的 blocked」自动推回 queued， -而这类 blocked 本来就等着人处置。原先这只是 `noteTaskBlockedReason` 上的一句注释。 - ---- - -## 四、待决策：`87b776c` 怎么处理 - -**不由本会话决定。** 本会话的判断，供参考： - -- ❌ **revert 恐怕是最差的选项**。截至 17:1x，lemonboss-78 已经在 `87b776c` 之上叠改动了 - （`task-scheduler.js` / `work-graph-db.js` + 4 个测试文件正在改）。revert 会把这些在途工作的地基抽掉。 -- ✅ **倾向修复前推**：把复核的 4 条作为后续提交解决，孤儿子 run 那条优先。 -- 📝 无论走哪条路，`87b776c` 说明里的「1201 用例全绿」都该有一条更正记录（本文档即是）。 - ---- - -## 五、还没解决的原始问题：一条卡住的 run - -这才是本会话最初被叫来看的东西，**至今没动**。 - -- 目标 `G-msyu6u9a-90cf` / 任务 `T-msyu6u9b-939c`（公司 `e2e-demo`，做 lemonai 官网） -- root run `run_9168bd24f46c` → work run `run_ee90c4e35f9f`，2026-08-18T16:19:36Z 收敛为 `blocked` -- 死在 `org-planner-sdd`，`fail_reason = boundary_escape` -- **这次判罚是误伤**：守卫抓到的 3 处改动（`M server/services/graph-run-sse.js`、 - `?? server/services/task-scheduler.js`、`?? server/tests/unit/task-scheduler.test.js`） - 正是当时并行会话在写批 3 的文件，不是 agent 写的 -- 预算远未耗尽：7/100 次调用、69,961/5,000,000 tokens - -### 界面上怎么重跑（不需要命令行） - -两个 🔁重试 按钮，各作用于自己那一层，**选中一个 `fail`/`blocked` 节点才亮**： - -- **左栏点 `org-planner` 重试** → 子图里没有待跑节点 → `resetRunNodes`：整张 work graph 作废重跑（brd/prd 也重来） -- **中栏点 `org-planner-sdd` 重试** → 只把这一个节点打回 ready。**自足**：子图跑完后 - `reviveParentFromChild` 会自动把父节点和父 run 从 blocked 拉回来 -- **顺序有影响**：先中栏单点重试、再左栏点 org-planner，那时子图里有 ready 节点 → - 左栏那一下变成「定点重置」而不是整张图重跑 - -### ⚠️ 重跑的前提 - -**工作区必须是干净的。** 边界守卫比对的是 agent 调用前后的整仓 `git status` 差集， -只要还有人在写这个 worktree，跑起来的节点就会再被误判一次 —— 白烧一轮预算。 -截至 17:1x 工作区仍有 13 个文件在改动中。 - -> 顺带：这条误伤暴露了守卫的一个结构性上限 —— 整仓 git status 的差集里**没有「谁写的」这一维**。 -> 多会话共用 worktree 时它必然误判。`splitUnattributable` 已经为 `system/agents/` 开了「保留证据、 -> 放弃判罚」的口子，同样的思路能不能推广到「调用窗口内有其他写入者」，值得单开一条 followup。 - ---- - -## 六、协作规则（这次踩实的） - -多个 Claude 会话共用 `/Users/yibo/Documents/lemonAI/lemonboss` 同一个工作目录、同一个 git HEAD。 - -1. **会话启动时系统给的 git status 快照，不是「用户自己的在途工作」的证据。** - 它只是「此刻工作区长这样」，里面大概率有别的会话正在写的东西。 - 本次事故的根因就是把快照当成了归属证明。 -2. **「用户让我提交工作区」≠「工作区里的东西都归用户」。** 逐文件确认归属。 -3. `git commit -- <自己的文件>` 精确提交。注意：**`git add <显式列表>` 一样会中招** —— - 出事的是列表内容，不是有没有用 `-A`。 -4. 判断某文件是不是别人的：看 mtime / `find . -newermt '-20 minutes'`。 - **对话进行中才变的文件 = 有人正在写**，一律先 SendMessage 问。 -5. commit message 里的「N 个测试全绿」只描述那一次测试运行。 - 压在别人还没复核完的代码上时，它会替对方说出没说过的话。 -6. 任何 `checkout` / `restore` / `stash` / `reset` 前先问，不论范围多小。 - ---- - -## 七、下一步 - -- [x] ~~lemonboss-78 补齐 §二 里缺的 3 条复核结论~~ —— 已补齐并提交（`5a31d00`），4 条均带独立探针实跑证据 -- [ ] 定 `87b776c` 的处理方式（建议修复前推） -- [ ] **N1** 修掉孤儿子 run（取消排队时还在烧 token）—— 唯一有直接金钱成本的一条，优先 -- [ ] **L1** 恢复路径对 manual 任务补一条出路（现在退回队列后没人接，sweep 空转） -- [ ] **N2** 「退回队列」透出到界面（`requeued` 字段全前端零读取；按钮全灰 + 图消失 + 假提示语） -- [ ] **N3** `isSlotRaceError` 第三条判据按探针结论改写，别再吞真错误 -- [ ] 工作区收敛干净后，重跑 `T-msyu6u9b-939c`（见 §五） -- [ ] 考虑给边界守卫加「多写入者 → 放弃判罚」的口子（§五 末尾） - -> §二 那条「注释承诺的前提被本轮自己的改动改没了，注释还留着」已经是第三次立案 -> （§十三.3 / §十四.4 / 本次）。第三次就不该再只当个案记 —— 值得考虑一条机器可查的守卫： -> 注释里出现「因此消失 / 不再可能 / 已经不会」这类**断言性承诺**时，要求同处留下可执行的判据引用。 -> 这条只是提议，归 lemonboss-78 判断要不要立。 diff --git a/docs/todo/system-design/27-p3c-goal-task-model.md b/docs/todo/system-design/27-p3c-goal-task-model.md deleted file mode 100644 index d1df014..0000000 --- a/docs/todo/system-design/27-p3c-goal-task-model.md +++ /dev/null @@ -1,1201 +0,0 @@ -# 27-P3C. 公司目标与任务 —— goal / task 两级模型 + 控制台任务列表 - -> **所属**: [27 Graph Agent 架构](./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 -> **状态**: **五批全部实施完毕并全绿**（§十三 ～ §十六）。132 文件 / 1257 测试，`web:build` 通过。开放问题已全部关闭；后续项见 §15.5 与 §16.8。 -> **⚠️ 批次与 phase 的对应不是一一对齐的**，判断「这份能不能搬进 done」时按批看，别按文档名看： -> · **批 1-3 = 真正的 P3 收尾**（goal/task 两级模型 + `task-planning` + 排队），本文档的主体； -> · **批 4（并行）归 [27-P4](./27-p4-parallel-and-artifacts.md) §一.3**，那边是设计权威，本文档只服从（见 §五.2 的警示块）； -> · **批 5（两套任务体系统一）不属于任何既有 phase** —— 是跨阶段的技术债清理，风险面也与前四批完全不同（坏了是所有 agent 互相派不了活），见 §十二.6。 -> **交付物**: ① `goals` / `tasks` 两张表，把「人类下达的需求」与「lemonboss 执行的单元」拆成两级；② 基于这两张表的**排队与并行**；③ 执行控制台（`/:id/graph-console`）最左侧新增**目标·任务两级列表栏**。 -> **命名**: 全文遵循 [27-NAMING](./27-naming-conventions.md)，本文档**落地**的正是它 §四 定义但代码里一直没有载体的 `goal 1 : task N` 基数关系。 -> **代码引用体例**: 沿用 27-P3/P4 头部约定 —— 只写 `文件名` + 函数名 / 常量名，**不写行号**。 -> -> **第二轮（2026-08-18，逐条对着代码复核初稿）**：抓到 7 处「照初稿实现就会出 bug」和 6 处补漏，正文已改，关键的错误结论**留档不删**（§三 的 ⚠️ 块、§五.1、§九.1 开头），因为它们是最容易再犯一次的那类。 -> ① **`createRun` 在建行的事务里就把 `graph_run_nodes` 按定义全插好了** —— 初稿三处基于「queued run 没有节点行」的论证全部作废（§三 / §四.3 / §九.1）； -> ② 由 ① 派生出一个**既存但被排队放大成必然事件**的缺陷：节点行在入队时快照、定义却是读时取最新，**排队期间 replan 会让 run 出队即卡死**（§四.3 末，新增 `syncRunNodesToDef`）； -> ③ 出队原语写错了 —— `markRunReady` 把 `from` 写死成 `planning`，复用不了；正解是 `updateRunStatus(runId,'queued','ready')`（§五.1）； -> ④ 唯一索引冲突是 **throw** 不是 `changes = 0`，初稿的错误处理只覆盖了一半（§五.1）； -> ⑤ **触发点枚举本身是漏的**：`stopRun` 与「预算耗尽 → blocked」两条最常见的释放路径都**不走 `settleRun`**，改为挂在唯一漏斗 `transitionRun` 上（§五.1.1）； -> ⑥ `report_to` 只活在请求闭包里，排队后**回调链路静默断掉**；`okr_node_id` 逐 task 下发会**反复覆写同一个 OKR 节点**（§四.7 两条禁令）； -> ⑦ **manual 任务会永久堵住队头**（占着 `running` 等人点「下一步」），改为不参与自动出队（§五.2bis）。 -> 补漏：存量回填脚本（§四.8，不做的话批 1 反而让历史任务更看不见）、任务级 `rerun` 与节点级 `retry` 的命名撞车（§六.3）、`queuePosition` 排序口径必须与调度器同源、砍掉没有消费方的 `goals.budget_json`（§十一.6）。 -> -> **第三轮（2026-08-18，四条口径由用户定案 → 27-REQ R-20.5）**：① **`task-planning` agent 提进 v1**（原计划 v2），新增 §四.9，批 2 范围与工作量随之变化；② 并行仍按批 4 单独排期，v1 只做排队（`max_parallel_tasks = 1`，唯一索引不动）；③ manual 任务不参与自动出队（§五.2bis）；④ 上游失败 → 下游自动推导为 `blocked` 并标红（§五.1.2）。 -> 定案 ① 连带牵出一处新缺陷：**`task-planning` 跑在 goal 层、任何 run 存在之前，它烧的 token 没有预算池可扣** —— 正是 `defaultPlanWorkGraph` 注释里点名的「隐形的一半花费」的新实例。上一轮刚以「零消费方」为由砍掉的 goal 级预算字段，因此以记账字段 `planning_tokens` 的形式回来（§四.1）。 -> -> **第四轮（2026-08-18，五条口径由用户定案 → 27-REQ R-20.6）**：① 退役 `/goals` 两个 OKR 别名**确认执行**；② **goal 级验收仍用 `org-validator`**，在 goal 层再调一次（新增 §四.10，goal 状态机加 `failed`）；③ **预算先不考虑**，不做 goal 级闸门，但保留 `planning_tokens` / `validation_tokens` 两个记账字段；④ **`queued` 开放改 `depends_on`**（§六.3）；⑤ **两套任务体系统一到 `tasks` 表，删掉会话反推那套**（新增 §十二 = 批 5）。 -> 定案 ⑤ 核实后有个反直觉的前提必须先说清：**两套不是并列的，A 的回调链路长在 B 身上** —— `reportRunOutcome` 收敛后调的正是 `/api/agent/task/report`。所以「删掉另一套」= 删**存储与会话反推**，**不能**删入口与回调（`/task/dispatch` 的 URL 与请求体写在 `tools-base.md` 里，改它等于同时改所有 agent 的提示词）。开放问题 2 / 4 / 6 / 7 全部就此关闭。 - ---- - -## 一、问题 - -用户的原话是「一个 company 在控制台下达任务只能有一个」。拆开是**三件事**： - -| # | 现象 | 真实成因 | 本次 | -|---|---|---|---| -| A | 历史任务**看不见、切不了、管不了** | 纯界面缺失。`GraphConsole.loadRuns()` 拿到了全部 root run，却只取 `roots.find(active) \|\| roots[0]`，其余全丢 | ✅ §七 | -| B | 一家公司**同时**只能跑一个，下第二个吃 409 | v1 硬约束：`work-graph-db` 的 `idx_graph_runs_one_active_root` 唯一索引 + `company.js` 的预检查。当时选「拒绝」而不是「排队」的理由写在代码注释里 —— **仓库里没有任何出队 worker，排进去的任务不会被消费，那是一条会静默丢任务的路** | ✅ §五 补上调度器，约束从「拒绝」改成「排队」 | -| C | 「人类提的需求」和「机器执行的单元」是**同一个东西** | `POST /api/company/:cid/tasks` 一次调用同时创造了需求、执行单元和执行实例三层语义，压在一条 root run 上。于是需求无法分解，也就无从并行 | ✅ §三 / §四 | - -C 是根因，A 和 B 是它的两个表征。**先拆两级模型，A/B 才有干净的解法。** - ---- - -## 二、与既有命名的对齐（先读这一节） - -### 2.1 这不是新概念，是给一个已存在的悬空外键补上它的表 - -[27-NAMING §四](./27-naming-conventions.md) 早已定义好基数： - -| 概念 | 基数 | 定义（原文） | -|---|---|---| -| **goal** | 一个人类需求描述 = **1 个** | 验收的边界。回答「这次交付到底算不算满足了人提的要求」 | -| **task** | 一个 goal 分解出 **N 个** | 图中的执行单元。**可并行**、可下钻 sub agent | -| **okr** | 跨多个 goal 的长周期度量树 | Objective / Key Result | - -而 `graph_runs` 里： - -```sql -goal_id TEXT, -- 全仓库**没有任何写入方**，只有 body.goal_id 透传 -task_id TEXT, -- 由 POST /:cid/tasks 现生成，无表、无唯一性保证 -``` - -`company.js` 那条注释写得明明白白：`goal_id?, okr_node_id?, 三者基数不同不可混用（goal 1 : task N : okr 跨 goal 度量树）`。**字段在、语义在、表不在。** 本文档做的就是把这两张缺席的表补上，不是发明新词。 - -### 2.2 「goal」一词的六个用法消歧（实现前必须分清） - -| 写法 | 指什么 | 载体 | 本次是否新增 | -|---|---|---|---| -| `company-goal` | 建公司时那句定性目标 | `company.json.goal` | 否 | -| **`goal`（本文档）** | **人类下达的一个需求 = 验收边界** | **新 `goals` 表，`G-xxx`** | ✅ 新增 | -| `task-goal` | **一个 task** 的验收边界（= 该 task 的描述） | `runs/{runId}/artifacts/task-goal.json` | 否，位置不变 | -| `subtask-goal` | work graph 内分支的验收边界 | `workgraph-planning` 拆分时产生 | 否 | -| OKR `Objective` | 长周期度量树，`O-xxx` | `data/companies/{cid}/okr/` | 否 | -| `goal-benchmark` / `goal-test-data` / `goal-test-script` | 三种**验收产物**（agent / 节点名） | work graph 节点 | 否 | - -> **注意 `task-goal` 的归属没变**：它是「一次 task 执行的验收边界」，artifact 本来就落在 `runs/{runId}/` 下 —— 也就是**每个 task 一份**。引入 goal 表后它的位置和语义都不用动，goal 的描述是它的**上级**，不是它的替代。 - -### 2.3 `G-` 前缀可以用，`/api/company/:cid/goals` 可以要回来 - -两处历史包袱都已经清干净，实地核实过： - -1. **`G-` 前缀已被 OKR 释放**。27-NAMING §六 的迁移把 OKR 第 1 层 `G-001` 正名为 `O-001`（`npm run okr:migrate` 已执行，且当时存量数据「几乎为空」）。所以新 `goals` 表用 `G-` 不与任何活数据冲突。 -2. **`/api/goals` 与 `/api/company/:cid/goals` 目前是 OKR 的向后兼容别名，但全仓库零调用方**。grep 的结果只有三行，全是别名注册语句本身（`index.js` / `agent-server.js` / `okr.js` 的注释）。**本次连带退役这两个别名**，把路径要回来给新概念 —— 一个词在同一套 API 里指两件事，是比破坏兼容更贵的债。 - ---- - -## 三、模型：goal → task → run 三级 - -``` -goals (G-xxx) 人类下达。一条 = 一个需求 = 一条验收边界 - │ 描述一经下达不可改（§四.4） - └─ tasks (T-xxx) N 条。lemonboss 的执行单元，可排队、可并行、可有依赖 - │ 描述一经下达不可改（§四.4） - └─ graph_runs root run，M 条。一次**执行实例**（重试会产生第 2 条） - └─ 子 run 每个 org node 现规划出的 work graph，及更深的子图 -``` - -三级各自回答一个问题，不重叠： - -| 层 | 回答的问题 | 谁改它 | 状态机 | -|---|---|---|---| -| goal | 人想要什么？做到了没有？ | 人 + **goal 级 `org-validator`**（§四.10）| `draft → planning → active → done / failed / cancelled / archived` | -| task | 这个需求拆成哪几件事？谁先谁后？ | **`task-planning` agent 拆、人可改**（§四.9）| `draft → queued → running → completed / failed / blocked / cancelled` | -| run | 这一次跑成什么样？ | 引擎 | 既有 `RUN_TRANSITIONS` + 新增 `queued`（§四.3） | - -**为什么 task 与 run 必须分开**（「不能直接把 task 当 root run」的三条硬理由）： - -1. **重跑是 task 1 : run N**。今天「重跑一遍这个任务」只能新建一条毫不相干的 run，两次执行在数据上没有任何关联；有了 task 表，run 挂在 task 下，「这个任务试了 3 次、第 2 次卡在哪」才说得出来。 -2. **依赖与并行是 task 之间的关系**，不是 run 之间的。`depends_on` 只有落在稳定的 task id 上才有意义 —— run id 每次重跑都变。 -3. **run 是「某一版图的执行快照」，task 是「人要做这件事」的意图**。`createRun` 在建行那一刻就按当时的 org graph 把 `graph_run_nodes` 全部插好（§四.3 核实），一条 run 因此天然绑死一个图版本；而意图必须跨图版本存活 —— 排队期间 org graph 被重新规划，正是这个区分的用武之地（§四.3 末）。 - -> ⚠️ **初稿在这里的第一条理由是错的**，留档以免再犯：初稿写「排队态没有 run，硬塞一条 run 行进去 `graph_run_nodes` 是空的」。核实 `createRun` 后 —— 它的事务里就按 `readDefGraph` 把节点行全插好了，**queued run 有一整套 `pending` 节点**，与 ready run 的唯一差别就是 `run_status`。结论（两级必须分开）不变，理由换成上面三条。 - ---- - -## 四、数据模型 - -DB 文件复用 `data/graph.sqlite`（`graph-db.js` 的 `getDb()`，WAL + `foreign_keys=ON` 已设好），与 `graph_runs` 同库同连接。迁移写法照抄 `work-graph-db.js` 现有的「存量库迁移」块（`hasColumn` 判断 + `ALTER TABLE ADD COLUMN`）。 - -### 4.1 `goals` 表（新） - -```sql -CREATE TABLE IF NOT EXISTS goals ( - id TEXT PRIMARY KEY, -- G-{base36}-{4hex}，见 §四.5 - company_id TEXT NOT NULL, - title TEXT NOT NULL, -- 短标题，列表显示用；可改 - description TEXT NOT NULL, -- 人类需求原文 = 验收边界；下达后不可改 - status TEXT NOT NULL DEFAULT 'draft', - -- draft | planning | active | done | failed | cancelled | archived - -- planning = task-planning 正在拆分（§四.9），是个真会持续几十秒的状态 - -- failed = goal 级验收没过，或有 task 未能 completed（§四.10）；可回 active 补 task 重下 - priority TEXT NOT NULL DEFAULT 'P1', - okr_node_id TEXT, -- 可选，挂到 OKR 度量树的哪个节点（O-001.1.1） - created_by TEXT, -- 'human' | agent id（Master/CEO 代下单） - report_to TEXT, -- 收敛后要唤醒的上级 agent，见 §四.7 - planning_tokens INTEGER NOT NULL DEFAULT 0, -- task-planning 拆分烧掉的 token（§四.9） - validation_tokens INTEGER NOT NULL DEFAULT 0, -- goal 级 org-validator 烧掉的 token（§四.10） - verdict TEXT, -- goal 级验收判词（org-validator 的原话），§四.10 - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL, - dispatched_at TEXT, -- 首次下达时间；非空 = 描述已冻结 - archived_at TEXT -); -CREATE INDEX IF NOT EXISTS idx_goals_company ON goals(company_id, status); -``` - -**没有 `budget_json`，但有 `planning_tokens`**：预算**闸门**是按 root run 算的（`DEFAULT_TASK_BUDGET` 只挂 root run，子 run 一律上溯 `root_run_id` 扣同一个池），goal 级预算没有任何执行机制，加一个没人消费的额度字段就是这个仓库反复被咬的「实现在、零调用方」。 - -但 `task-planning` 定案进 v1 之后，**goal 层出现了一笔真实、且没有池子可扣的花费**：它跑在任何 run 存在之前。`defaultPlanWorkGraph` 的注释已经把这个病点过名 ——「规划调用也是真花钱的一次 agent 调用，token 必须计入同一个 root run 预算池，否则『一层规划 + 一层执行』里有一半的花费是隐形的」。goal 级拆分正是那个「隐形的一半」的新实例，所以**必须记账**（`planning_tokens`），哪怕暂时不设闸门。goal 级总额**控制**仍留到 §十一.6。 - -`okr_node_id` 放在 goal 上而不是 task 上：OKR 度量的是「人的需求达成了没有」，那正是 goal 的粒度 —— 具体的实现禁令见 §四.7，那不是一句设计倾向，是照现有代码顺手写就会踩的坑。 - -### 4.2 `tasks` 表（新） - -```sql -CREATE TABLE IF NOT EXISTS tasks ( - id TEXT PRIMARY KEY, -- T-{base36}-{4hex} - goal_id TEXT NOT NULL REFERENCES goals(id), - company_id TEXT NOT NULL, -- 冗余一份：调度器按公司选任务，避免每次 JOIN - seq INTEGER NOT NULL, -- goal 内序号，列表排序用（1,2,3…） - title TEXT NOT NULL, - description TEXT NOT NULL, -- 落进 task-goal.json 的那句；下达后不可改 - status TEXT NOT NULL DEFAULT 'draft', - -- draft | queued | running | completed | failed | blocked | cancelled - execution_mode TEXT NOT NULL DEFAULT 'manual' CHECK (execution_mode IN ('manual','auto')), - depends_on TEXT NOT NULL DEFAULT '[]', -- JSON 数组，同 goal 内的 task id - budget_json TEXT, - current_run_id TEXT, -- 最近一次 root run（逻辑外键，见 §四.6） - attempt INTEGER NOT NULL DEFAULT 0, -- 起过几次 run（任务级重跑，≠ 节点级 retry） - report_to TEXT, -- 从 goal 继承或调用方指定；见 §四.7 - created_by TEXT, -- 'task-planning' | 'human'：这一条是拆出来的还是人加的 - blocked_reason TEXT, -- status='blocked' 时的原因，如 upstream_failed:T-xxx - priority TEXT NOT NULL DEFAULT 'P1', - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL, - queued_at TEXT, -- 入队时间；非空 = 描述已冻结 - started_at TEXT, - finished_at TEXT, - archived_at TEXT -); -CREATE INDEX IF NOT EXISTS idx_tasks_goal ON tasks(goal_id, seq); -CREATE INDEX IF NOT EXISTS idx_tasks_queue ON tasks(company_id, status, priority, created_at); -``` - -**`depends_on` 一个字段同时表达串行与并行**，不另设 `parallel_group`： - -- `[]` → 无前置，可立即入队 → 同一 goal 下多个空依赖的 task **天然并行**（能不能真并行由 §五.2 的并发上限决定）。 -- `["T-a"]` → 等 `T-a` 到 `completed` 才可调度 → **串行**。 -- 多个元素 → 汇聚点（fan-in）。 - -也就是说 goal 内部就是一张 task DAG。校验：写入时查环（`depends_on` 只能引用同 goal 内已存在的 task），有环 `400`。 - -### 4.3 `graph_runs` 新增一个 run status：`queued` - -**这是本次唯一动到既有运行时表的地方。** `run_status` 列上没有 CHECK 约束（只有 `graph_kind` / `execution_mode` 有），所以加值不需要改表，只要给 `work-graph-db` 的 `RUN_TRANSITIONS` 加一行： - -```js -queued: ['ready', 'stopped'], // 出队 = queued → ready；取消 = queued → stopped -``` - -**为什么有了 tasks 表还需要它**（否则确实是冗余的第二套排队状态）—— 只有一个理由，但足够硬： - -> **它把「出队」这个并发临界区交给已有的唯一索引兜底。** -> -> 调度器出队时，如果先 `INSERT` 一条 `ready` 的 run，两个并发的 tick 会各插一条，超发。而 `idx_graph_runs_one_active_root` 的 `WHERE` 覆盖 `ready/running/paused`、**不覆盖 `queued`** —— 于是：入队时创建 run 行为 `queued`（不占坑，可以有任意多条），出队时做一次 `UPDATE ... SET run_status='ready' WHERE id=? AND run_status='queued'`，**超发的那一条会被唯一索引直接拒绝**，而不是靠应用层的「先查后插」（那中间永远有竞态窗口）。 - -顺带三个收益：入队即有稳定的 `run_id`（可分享的控制台链接）、`task-goal.json` 的落盘路径 `runs/{runId}/artifacts/` 在入队时就确定（描述冻结点与 artifact 落盘点重合，见 §四.4）、timeline 上能记下「何时入队」这条审计事实。 - -#### 代价：入队即建行 = 节点行在入队时就被快照，出队前必须重新对齐 - -`createRun` 的事务里会按 `readDefGraph(graphKind, graphId)` 把 `graph_run_nodes` **一次插全**（每个 def node 一行 `pending`）。而 `getRunState` 是**每次读都重新读当前定义**，org run 的 `graph_id` 就是 `company_id` —— 也就是说定义那一侧永远是「此刻最新的 org graph」。 - -于是排队期间有人点了「重新规划组织」（`ReplanOrgGraphButton`，一个一等的用户操作）： - -- 被删掉的节点 → 留下孤儿 run 行，`getRunState` 里 `defById.get()` 取到空对象，名字/类型全空； -- **新增的节点 → 根本没有 run 行 → 永远不会被拾取执行 → 这条 run 出队后必然卡死**。 - -> **这个洞今天就存在**（一条跑了一小时的 run 期间 replan，同样中招），只是今天 createRun 到 startRun 之间只隔几行代码，窗口是毫秒级。**排队把窗口放大到小时级，从理论缺陷变成必然事件。** - -定案两条，缺一不可： - -1. **出队时重新对齐节点行**：`queued → ready` 之前先按当前定义补齐缺失的 node 行、删掉孤儿行（都还是 `pending`，没有任何执行痕迹会丢）。这一步做成 `syncRunNodesToDef(runId)`，`stopped`/`completed` 的 run 一律不碰。 -2. **replan 时把该公司所有 `queued` run 标记为待对齐**（或直接就地跑一次上面的 sync）。理由是别让「出队时才发现图变了」成为唯一防线 —— 那时用户已经在等这条任务跑起来了。 - -> ponytail: 出队对齐是「定义变了就补行」的最小实现，它默认**新节点从 pending 开始**是安全的（queued run 本来一个节点都没跑过）。一旦将来允许对**跑到一半**的 run 做 replan，这个函数就不够用了，必须升级成带 `contract_hash` 判据的级联重置（`loops-l3.md` 已有那套四分类）。 - -状态机全貌： - -``` -task: draft ──提交──▶ queued ──调度器出队──▶ running ──┬─▶ completed - │ ├─▶ failed - cancelled ├─▶ blocked ──重试──▶ queued - └─▶ cancelled - -run: queued ──▶ ready ──▶ running ──┬─▶ completed / failed / blocked / stopped - │ └─▶ paused ──▶ running - stopped （既有转换全部不变） -``` - -### 4.4 描述冻结（用户要求 3） - -| 对象 | 可改字段 | 冻结点 | 冻结后改会怎样 | -|---|---|---|---| -| goal | `title` / `priority` / `okr_node_id` | `dispatched_at IS NOT NULL`（首个 task 入队）后 **`description` 冻结** | `409` | -| task | `title` / `priority`（`depends_on` 仅 draft） | `queued_at IS NOT NULL` 后 **`description` / `execution_mode` / `budget` 冻结** | `409` | - -**这不是保守，是数据一致性的硬要求**：task 的 description 在入队时就写进了 `runs/{runId}/artifacts/task-goal.json`，而 `describeTask` 等 agent 侧链路读的是 artifact。改库不改 artifact 会让两份记录对不上；两份都改则等于篡改已被 agent 消费过的审计输入。**要改就取消后新建**，错误响应里直接给这句 hint。 - -`title` 留着可改，因为它只是列表上的一个标签，不进任何 agent 的上下文。 - -### 4.5 ID 生成 —— 现有格式在本次会真的撞 - -现在两处都写 `` `T-${Date.now().toString(36)}` ``（`company.js` 与 `agent-chat.js`）。**同一毫秒内生成的两个 id 完全相同** —— 今天没炸是因为一次只建一个；本次「一个 goal 一次性建 N 个 task」是**循环建行**，同毫秒撞是必然事件，而 `tasks.id` 是主键，撞了就是 500。 - -改成仓库既有约定（`_spec/CONVENTIONS.md` §2：*时间戳部分不保证全局唯一 —— 靠后缀随机位避免碰撞*）： - -```js -const genId = (p) => `${p}-${Date.now().toString(36)}-${crypto.randomBytes(2).toString('hex')}`; -// G-mabc123-7f3a / T-mabc123-9e21 -``` - -`agent-chat.js` 那处 tasklog 的 `T-` 生成**本次不动**（那是另一套存储），但要在 §九 记一笔：两套 `T-` id 从此可能长得像但不同源，读的时候别混。 - -### 4.6 逻辑外键，不重建表 - -`graph_runs.goal_id` / `task_id` 保持现状不加 `REFERENCES`：SQLite 不支持给已有列追加外键，要加只能重建表 —— 而 `graph_runs` 上挂着 `graph_run_nodes` / `graph_run_loop_records` 的真外键，重建代价远大于收益。约束由服务层保证，文档里标注为**逻辑外键**。 - -`tasks.goal_id → goals(id)` 是新表，可以是真外键，直接写上。 - -### 4.7 收敛汇报的两条实现禁令（照现有代码顺手写就会踩） - -> ⚠️ **本节写于批 1 实施之前，`reportRunOutcome` 已在批 1 中删除**（见 §十三）。下面对它的描述保留为「当时的现状」，两条禁令的结论不变，只是落点从 `company.js:reportRunOutcome` 变成了 `task-settle.js:reportGoalOutcome`。 - -`reportRunOutcome`（`company.js`，**已删**）曾是 root run 收敛后的唯一出口，它做两件事：有 `report_to` 就 POST 给 `/api/agent/task/report` 唤醒上级 agent，没有就直接 `OkrService.updateNode(objectiveId, okrNodeId, {status})`。两件事在 goal/task 两级下都会坏： - -**禁令一：task 的 run 一律不带 `okr_node_id`。** -现在 `createRun({okrNodeId})` 把它写进 run，`reportRunOutcome` 读 `run.okr_node_id` 直接写 OKR 节点。一个 goal 挂一个 OKR 节点、下面 5 个 task 各带一份，就是**同一个 OKR 节点被写 5 次**，且没有合并逻辑 —— 最后一个收敛的 task 说了算，一个 failed 的尾巴能把已经 done 的节点翻成 failed。所以：**`okr_node_id` 只存在 `goals` 表上，不进 `graph_runs`**；OKR 由 goal 收敛（全部 task 终态）时写一次。 - -**禁令二：`report_to` 必须落库。** -今天 `report_to` / `reporterAgent` 只活在请求作用域的闭包里（`ctx`），随手挂给 auto 模式的 driver。**排队之后 driver 是调度器在几小时后创建的，那时请求体早已不存在** —— 结果是 Master / CEO 代下单的回调链路**静默断掉**：不报错、不重试，就是没人被唤醒。所以 `goals.report_to` / `tasks.report_to` 两列是必需的，调度器起 driver 时从 task 行读回。 - -> 这两条都属于「既有实现是对的，只是它假设了『下达即执行』」。排队打破了那个假设，而打破得非常安静。 - -### 4.8 存量回填（不做的话，批 1 会让历史任务更看不见） - -既有的 root run 在 `tasks` 表里没有任何行。左栏一旦改成读 `tasks`，**所有历史 run 会从界面上消失** —— 正好是本文档要修的 A 类问题的反向放大。 - -迁移脚本（一次性，幂等，`--dry-run` 预演，写法照 `scripts/migrate-goals-to-okr.js`）： - -对每条 `parent_run_id IS NULL` 的 `graph_runs`： -1. 建一条 `goals` 行：`description` 从 `data/companies/{cid}/runs/{runId}/artifacts/task-goal.json` 的 `task` 字段读回；读不到就用 `run.task_id` 占位并标 `title = '(历史任务)'`。`status` 按 run 终态映射（`completed → done`，其余 → `active` / `cancelled`）。 -2. 建一条 `tasks` 行：`seq=1`、`depends_on=[]`、`current_run_id = run.id`、`attempt=1`、`status` 按 run 状态映射，`queued_at = run.created_at`（描述立即冻结，历史任务本来也不该再改）。 -3. 回填 `graph_runs.goal_id` / `task_id` 指向新行。 - -> 实测当前 `data/graph.sqlite` 里只有 1 条 root run（且卡在 `running`），所以回填本身成本极低 —— 但**开发机与线上库的数据量不一样**，脚本必须写，不能靠「反正没几条」跳过。 - -### 4.9 `task-planning` —— 把 goal 拆成 task DAG（v1 就做，用户定案） - -命名依 27-NAMING §二「`{产出物}-planning`」：产出物是 task 列表，故 **`task-planning`**。它是继 `orggraph-planning` / `workgraph-planning` 之后的**第三个规划类 agent**，形态与后者对齐。 - -#### 链路照抄 `defaultPlanWorkGraph`，不另造 - -`graph-engine.defaultPlanWorkGraph` 已经把「调规划 agent → 校验产物 → 不过就把 `errors` 原样回给它再来一轮」这条链路跑通了（`PLAN_MAX_ROUNDS = 3`）。`task-planning` 用**同一个形状**： - -``` -AgentManager 调 task-planning（输入：goal.description + 公司 org graph 摘要 + 可用角色清单） - → 产出 JSON: [{ title, description, depends_on: [], seq }] - → 校验：字段齐全 / depends_on 只引用本次产出的 seq / 无环 / 条数 ≤ 上限 - → 不过 → errors 原样回喂，最多 3 轮 - → 过 → 落 tasks 表，全部 status='draft' -``` - -**产出的 task 一律是 `draft`，不自动入队。** 拆完在界面上是一份可编辑的清单（改描述、删、加、调依赖），人点「全部下达」才转 `queued`。理由：拆分是一次 LLM 猜测，直接把 5 条任务塞进队列跑起来，等于让一次猜错的拆分直接烧掉 5 份预算；而这一步的编辑成本几乎为零。 - -#### 三条必须写进实现的约束 - -1. **token 记账**：复用 `defaultPlanWorkGraph` 那个 `onAcpEvent` 累加 `usage` 的写法，结果写进 `goals.planning_tokens`（§四.1）。这是 goal 层唯一一笔花费，不记就是隐形的。 -2. **失败必须降级，不能把 goal 卡在 `planning`**：3 轮都没产出合法 DAG → **退化成 1 条同描述的 task**（`created_by='human'`、`seq=1`、`depends_on=[]`），goal 转 `active`，并在界面标注「自动拆分失败，已按单任务下达」。绝不能留一个永远转圈的 `planning` goal —— 那正是这次要消灭的那类静默状态。 -3. **本体落点是 `system/agents/task-planning/`**（`system/templates/` 已在 2026-08-18 的 agent 目录重构里**彻底取消**，50 个本体全部 `git mv` 进 `system/agents/`，`base` → `_base`）。形态照 `workgraph-planning`：`agent.md` / `config.json` / `identity.md` / `soul.md` / `tools.md`。**不要用 `_` 开头命名** —— `_` 是保留前缀，扫描时会被跳过。 - -4. **`agent.md` + `soul.md` 必须一次写完，不能先建骨架后填**。本体现在有**毕业闸门**：`agent.md` 与 `soul.md` 非空、且不带 `_base` 的骨架哨兵，才会从 `system_agents.status='draft'` 毕业；否则 `hire()` 拒绝并返回 `body_not_ready`。「从 `_base` 复制骨架 → 以后再填」的中间态**雇不进公司**。（`.claude/skills/main_skill/SKILL.md` 是可选的，57 个本体里 54 个没有。） - - 三个权威判据（真到建本体时以它们为准，别照文档复述）：`agent-locator.js` 的 **`missingBodyDefinition()`**（判什么算没填完）、`graph-service.js` 的 **`promoteDraftIfComplete()`**（转正动作）、以及 `hire()` 用的 **`isUngraduatedStatus()`**。 - - > ⚠️ **`isUngraduatedStatus()` 只挡 `draft` / `training` 两个状态，不是「≠ active 就挡」。** 这个坑已经被踩过一次：库里有 36 个本体的 status 是 `enabled` / `idle` / `ready` / `trained`，按「不等于 active」判会被全部误判成「没填完」。取值域的唯一持有者是 `graph-service`，**不要在别处复述它** —— 本文档 §六.3 已经因为 `canDispatch` 被前端复述过一次取值域而记过同类教训。 - -5. **`_registry.json` 登记是可选的，建目录才是关键动作** —— 这条与初稿写反了，留档纠正：`graph-seed-service.seedAgents()` 现在直接 `readdirSync(system/agents/)` 把**目录当真相**，`_registry.json`（已随重构挪到 `system/agents/_registry.json`，数组格式不变）只用于按 id 补 `benchmark_score`，registry 缺条目照样 seed。初稿写的「不登记会把 CI 跑红」引的是 27-P3/P4 §八.21 的前科，那条前科属于 `template-refs.test.js` 硬编码 `system/templates` 路径的时代，**该测试正随重构一起改**。仍建议顺手登记（`benchmark_score` 要用），但它不是闸门。 - -6. **本体正文里的路径有三条硬规矩，写错不报错、只静默降级**（agent 运行时 cwd 是 `system/agents/{aid}/{cid}/{taskId}/`，深度 3）： - - 引用本体自己的文件 → `../../`（如 `../../tools.md`）； - - 引用仓库根 → `../../../../../`； - - **交付物路径绝不能写裸相对**（`workspace/x.md` 会落进任务态目录，之后被清理）。必须用提示词开头「运行时坐标」里「你的交付物必须写到」那一行给的**绝对路径**，本体正文里统一记作 `$W`。 - - 照 `system/agents/orggraph-planning/agent.md`（重构后版本）抄写法。这三条错了全都**不报错**，只是产物落在没人看的地方 —— 与本文档反复点名的那类静默故障同源。 - -#### 跳过拆分 - -`POST /goals` 带 `split: false` 时不调 agent，直接建 1 条同描述的 task。存量调用方（`POST /:cid/tasks`）走的就是这条路 —— **它们不该因为这次改动突然多花一次 LLM 调用**。 - -### 4.10 goal 级验收 —— 仍然是 `org-validator`（用户定案） - -**不新造验收 agent**：goal 级用的还是 `org-validator` 这个本体，只是**在 goal 层再调一次**。 - -#### 为什么是「再调一次」而不是复用 task 级那次的结论 - -因为两次验的是**基数不同的东西**，这正是 27-NAMING §四 那张表的论证： - -| | 验什么 | 谁问的 | -|---|---|---| -| task 级（既有，org graph 末端节点）| 这**一个 task** 的 `task-goal` 达成了没有 | 引擎，每个 task 各一次 | -| **goal 级（本次新增）** | **N 个 task 合起来，人提的那个需求达成了没有** | goal 收敛时，一次 | - -5 个 task 全 `completed`，只说明每一件事都按各自的描述做完了 —— 不说明拼起来是人要的东西。这个缺口正是 goal 层存在的理由，用别的东西替代不了。 - -#### 触发与判定 - -``` -goal 下所有 task 到终态 - ├─ 有任何一条 ≠ completed → goal 直接 failed，不调 agent（省一次调用：显然没交付） - ├─ 全 completed 且只有 1 条 task → 跳过 goal 级验收，直接采用该 task 的验收结论 - │ （单 task 的 goal，两级验收是同一件事，再调一次纯浪费） - └─ 全 completed 且 ≥2 条 task → 调一次 org-validator - 输入：goal.description（= 验收边界）+ 该 goal 全部 task 的产物索引 - （`graph_files` 按 task_id 查，§P4 §4.6 的表已经能给出这份清单） - 产出：pass / fail + 判词 → goals.status = done / failed，判词落 goals.verdict -``` - -调用形态与 `task-planning` 相同：`AgentManager` 直调本体，不在任何 graph run 里，token 记 `goals.validation_tokens`。 - -#### 挂在哪 - -和调度器同一个位置：task 转终态时顺手判一次「这个 goal 的 task 是不是都到齐了」。**`settleGoal(goalId)` 必须幂等**（并行完成的多个 task 会同时触发它），用 `goals.status` 的条件更新做闸门 —— 与 §五.1 出队用的是同一招。 - -> goal 收敛之后才轮到 §四.7 的两件事：写 OKR 节点（一次，用 goal 的判定结果）、唤醒 `report_to`。**这两件事从 run 级上移到 goal 级**，禁令一说的「task 的 run 一律不带 `okr_node_id`」在这里闭环。 - ---- - -## 五、排队与并行 - -### 5.1 调度器 `server/services/task-scheduler.js`（新） - -一个函数就是全部： - -```js -tick(companyId) // 幂等，可重入，同步执行（better-sqlite3 是同步 API） -``` - -1. 读公司并发上限 `max`（§五.2）。 -2. 数当前活跃 root run 数 `n`（`run_status ∈ {ready,running,paused}`）。 -3. `n >= max` → 直接返回（队伍照排，不动）。 -4. 选候选：`status='queued'` 且 `depends_on` 里每个 id 都已 `completed`、且 `execution_mode='auto'`（manual 不自动出队，见 §五.3）的 task，按 `priority` → `seq` → `created_at` 排序，取前 `max - n` 条。 -5. 逐条出队，**整条包在 `try/catch` 里**： - ```js - syncRunNodesToDef(runId); // §四.3：定义可能已经变了 - const changed = updateRunStatus(runId, 'queued', 'ready'); // 原子出队，见下 - if (!changed) continue; // 被并发抢走，正常情况 - startRun(runId, { mode, task }); // manual 只点亮入口，auto 挂 driver - ``` - 捕获到 `UNIQUE constraint failed` 或 `InvalidTransitionError` 同样 `continue` —— 它们都是「这条没抢到」，不是错误。 - -**出队原语就是 `updateRunStatus(runId, 'queued', 'ready')` 这一条，不经过 `markRunReady`。** 核实结论： - -- `updateRunStatus` 本身就是条件更新（`WHERE id = @id AND run_status = @from`）并返回 `changes` —— 这正是要的 compare-and-swap； -- 它**先**跑 `canTransitionRun(from, to)`，非法转换直接 `throw InvalidTransitionError`； -- 撞唯一索引时 better-sqlite3 **抛 `SqliteError: UNIQUE constraint failed`，不是返回 `changes = 0`**。初稿只写了「受影响行数为 0 就跳过」，漏了这一半 —— 照初稿实现，一次正常的并发竞争会把整个 `tick` 抛出去； -- **`markRunReady` 不能复用**：它把 `transitionRun(runId, 'planning', 'ready')` 的 `from` **写死成 `planning`**，对一条 `queued` 的 run 是空转（`WHERE run_status='planning'` 匹配不到）。初稿写的「UPDATE 成 ready 之后再 markRunReady」既冗余又跑不通。 - -### 5.1.1 触发：挂在状态变更漏斗上，而不是枚举路径 - -初稿列了四个触发点（入队 / `settleRun` / 启动 / 60s 兜底）。**核实后发现这个枚举本身就是漏的**： - -| 路径 | 会不会释放 active 坑 | 走不走 `settleRun` | -|---|---|---| -| 正常收敛（manual `/next` / auto driver）| 会 | ✅ 走（`settleRun` 只在 `advanceOne` 里被调用） | -| **人工停止 `stopRun`** | 会（`stopped`）| ❌ **不走** —— 代码注释自己写着「子 run 被 stopRun 直接转 stopped，不经过 settleRun」 | -| **预算耗尽 → `blocked`** | 会（`blocked` 不在 active 取值域里）| ❌ 不走 | - -也就是说「用户停掉一个任务」和「任务烧完预算」这两条最常见的释放路径，队列都不会动，要干等 60s 兜底。**继续往表里加行不是解法 —— 枚举一次漏一次，而漏的症状是任务静默躺在队里、界面上跟「正在排队」一模一样，正是当初拒绝做排队的那条理由。** - -改成挂在**唯一的状态变更漏斗**上：`graph-run-sse.transitionRun` 是全仓库所有 run 状态转换的必经之路（引擎侧一律走它，因为它同时要落 timeline 和推 SSE）。 - -```js -// transitionRun 内，条件更新成功之后 -if (run.parent_run_id === null && !ACTIVE_ROOT_RUN_STATUS.has(to)) { - setImmediate(() => scheduler.tick(run.company_id)); // 出漏斗再调，避免重入 -} -``` - -一个钩子覆盖 settle / stop / blocked / failed / completed 全部路径，且**语义就是那句话本身**——「一个 root run 离开了活跃集，去看看队里有没有人能顶上」。 - -保留的另外三个触发点：**入队时**（队伍空时立即起跑）、**服务启动时**（挂在 `server/index.js` 现有的「中断任务恢复」旁边，补进程重启丢掉的唤醒）、**60s 兜底定时器**（前面全漏了也能自愈）。 - -两条必须写进实现的护栏： -- **重入保护**：`tick` 会起 run → 起 run 会转换状态 → 又触发 `tick`。用一个 per-company 的 in-flight 标志，或统一 `setImmediate` 出栈后再跑。 -- **`tick` 里不 throw**：它挂在状态转换的尾巴上，抛出去会把一次正常的 run 收敛也带崩。 - -> ponytail: `tick` 目前按公司算配额。将来要跨公司全局配额时，改成「按配额池」——钩子位置不用动。 - -### 5.1.2 上游失败 → 下游自动转 `blocked`（用户定案） - -`depends_on` 只认 `completed`，所以上游一旦 `failed` / `cancelled`，依赖它的下游**永远满足不了条件**。放着不管，那条 task 会静默躺在队里，界面上和「正在正常排队」长得一模一样 —— 又是这次要消灭的那类症状。 - -`tick` 开头加一步（在选候选之前）： - -```js -// 依赖已经不可能满足的 queued task，就地转 blocked，别让它假装在排队 -for (const t of queuedTasks) { - const dead = t.depends_on.find((id) => ['failed','cancelled'].includes(statusOf(id))); - if (dead) setTaskBlocked(t.id, `upstream_failed:${dead}`); -} -``` - -界面上 `blocked` 的行标红并显示 `blocked_reason`，`⋯` 菜单给两个出路：**重跑上游**（上游 `rerun` 成功后，下游自动回 `queued`）或 **强制放行**（清掉那条依赖，人为承担风险）。 - -> **级联要一次算到底**：A 失败 → B blocked → 依赖 B 的 C 也应该 blocked（`blocked` 同样不是 `completed`）。上面那段按「依赖里有任意一个处于非 completed 终态」判定即可自然级联，但要注意**别把 `blocked` 本身当成终态去反向传播**，否则 A 重跑成功后 C 解不开。解法：`blocked` 只由这一步**推导**得出，不落成不可逆状态 —— 每次 `tick` 重算一遍，上游恢复了就自己回 `queued`。 - -### 5.2bis manual 模式会永久堵住队头 - -`startRun(manual)` 只点亮入口节点就停下等 `/next`，而这时 run 已经是 `running` —— **占着 active 坑**。`max_parallel_tasks = 1` 时，一个没人点「下一步」的 manual 任务会把它后面所有任务**无限期堵死**，而队列界面上看不出任何异常。 - -定案：**manual 任务不参与自动出队**（§五.1 第 4 步的过滤条件）。它只能由人在控制台上显式点「开始」——那一步同样走 `queued → ready` 的原子出队，抢不到坑就提示「当前有任务在跑」。 - -理由：manual 的语义本来就是「人盯着一步步推」，让调度器在半夜自动把它拉起来、然后停在第一个节点上占着坑到天亮，是这个模式下最糟的行为。 - -### 5.2 并发上限与唯一索引 - -**定案（2026-08-18）：配置放 `company.json`，不建 `company_settings` 表。** `companyService.get` 已经在读这个文件，零新增读路径；建表要多一张表、一套读写、一次迁移，而目前公司级配置项只有这一个。公司级配置项涨到 3 个以上时再考虑建表（届时连 `company.json` 里已有的那些一起收）。 - -`company.json` 加一个字段： - -```jsonc -{ "max_parallel_tasks": 1 } // 缺省 1 = 与今天完全同行为 -``` - -- **`max = 1`（默认、批 2 上线时的形态）**：`idx_graph_runs_one_active_root` 保留不动，DB 层的守卫还在，行为与今天一致，只是「拒绝」变成了「排队」。 -- **`max > 1`（批 4）**：这个唯一索引必须 `DROP`，否则第二条并行任务在 `queued → ready` 时被索引拒掉。替代守卫是 §五.1 第 2-5 步**整体包在一个 `better-sqlite3` 事务里**（`db.transaction(...)`）—— SQLite 是单写者，写事务天然序列化，「count 完再 admit」在这里是真原子的，不是应用层的乐观检查。 - -**批 4 单独排期、单独验收**，理由：删掉一个唯一索引 = 删掉最后一道 DB 兜底，这个动作不该和「界面上能看到任务列表」混在一次上线里。 - -> ⚠️ **批 4 与 [27-P4](./27-p4-parallel-and-artifacts.md) §一.3 是同一件事，不要各做一遍。** 那份文档的目标 3 逐字写着「**解除「一家公司同时只有一个 active root run」约束** —— P3 v1 用一个唯一索引强制它（§三.3），并行能力具备后应放开」。也就是说：**放开约束的设计归 27-P4，本文档只负责在它之上定义「谁来排队、按什么序出队」**（§五.1）。真到实施时以 27-P4 的并行方案为准，本文档的 §五.2 服从它；两边都写一版会产生两套并发守卫。 - ---- - -## 六、API - -全部挂在 `server/routes/company.js`。错误响应沿用现有 `{ error, hint, ... }` 形态。 - -> **⚠️ 批 1 必须修两处路径缺陷 —— 一处就在本文档的核心链路上。** -> -> **缺陷 A（会分叉，在核心链路上）**：`task-goal.json` 的写入方与读取方用的不是同一套路径规则。 -> -> | | 位置 | 认不认 `GRAPH_RUNS_DIR` | -> |---|---|---| -> | **写** | `company.js` 的 `writeTaskGoalArtifact` → `path.resolve(__dirname,'../..','data','companies',cid,'runs',rid,'artifacts')` | ❌ **不认** | -> | **读** | `graph-engine.js` 的 `runRootDir`（`describeTask` 与 `goal-contract.deriveRunDir` 都走它）| ✅ 认 | -> -> `GRAPH_RUNS_DIR` 一旦被设上（目前只有测试在用），写进 A 处、从 B 处读 —— `describeTask` 拿到 null，**静默退回兜底文案「执行图节点任务」**，agent 从此拿不到真实任务描述，而**没有任何报错**。`goal-contract.test.js` 的注释佐证读取方那套形状才是约定：`{GRAPH_RUNS_DIR}/{rootRunId}/artifacts/task-goal.json`。 -> -> 生产环境两边恰好都退到同一个默认分支，所以今天不发作 —— 但**批 1 会把 artifact 的落盘点从「下达时」前移到「入队时」**（§四.3 / §四.4 的描述冻结点），正好要动这个函数。**修法是一行级：写侧改调读侧的 `runRootDir`。** -> -> > ⚠️ **本文档初稿在这里归因错了，留档纠正**：初稿写成「`runRootDir` / `companyRootDir` / 写入方三种拼法争权威，实施前得先定哪个权威」。**那是错的，而且会让实施者去做一个根本不存在的设计决策。** `runRootDir` 与 `companyRootDir` 是**两个不同的事实**，不是同一事实的两种拼法： -> > - `runRootDir` → **run 目录**，覆盖态是 `{RUNS_ROOT}/{rootRunId}`。扁平即可，因为 `rootRunId` 全局唯一； -> > - `companyRootDir` → **公司根**，覆盖态是 `{RUNS_ROOT}/_companies/{cid}`。多出来的 `_companies/` **是必须的** —— 公司 id 不是全局唯一坐标，扁平放会和 run 目录撞名。 -> > -> > `company-paths.js` 的注释本身就写着「理由与 `runRootDir` 那处 override 一致」，作者是有意区分的。**真正错的只有一处：写入方自己拼路径。** -> -> **缺陷 B（不会分叉，因为它根本没有调用方 —— 但更会骗人）**：`goal-contract.js:75` 声明了 -> -> ```js -> /** run 目录根的覆盖，与 graph-engine.RUNS_ROOT / graph-run-sse 是同一个变量（测试隔离在用） */ -> const RUNS_ROOT = process.env.GRAPH_RUNS_DIR || null; -> ``` -> -> **然后一次都没用过**（全文件只有注释 + 声明两行），同文件的 `resolveRunDir()` 照旧自己拼 `DATA_DIR/companies/…`。而且 `resolveRunDir` **全仓库零调用方**（只有定义、`module.exports` 和 `27-goal-contract-format.md` 里的一行文档）—— 又一个「实现在、零调用方」。 -> -> 所以它今天不会出错，危害是**注释在撒谎**：白纸黑字写着「与 graph-engine.RUNS_ROOT 是同一个变量、测试隔离在用」，读代码的人会据此认为这个文件认 `GRAPH_RUNS_DIR`。**一个声明了意图、代码却不兑现的常量，比没有这个常量更容易骗人** —— 第一个把 `resolveRunDir` 接上去的人会直接踩。 -> -> 批 1 一并处理：要么让它真的用 `RUNS_ROOT`，要么连函数带常量一起删（零调用方，删是更省的一侧）。 -> -> **`system/agents` 那一族已经不用管了** —— 2026-08-18 的 `e120645` 已把全仓库 13 处（跨 5 个文件，含 `company.js` 里 6 个 `TEMPLATES_DIR` + 3 个同义异名的 `DATA_DIR`）收敛到 `locator.AGENTS_ROOT`，并新增 `server/tests/unit/agents-root-single-holder.test.js` 锁住不变式。**批 1 新增的代码必须遵守它**：不许自己拼「以 `../` 开头、以 `system/agents` 结尾」的字面量，否则这条测试会红。 -> -> 这些全是**同一个病**的不同实例，本文档已经攒到第五个：`canDispatch` 的取值域被前端复述（§六.3）、`ACTIVE_ROOT_RUN_STATUS` 在两文件逐字重复（§九.1）、`isUngraduatedStatus()` 的取值域（§四.9）、`system/agents` 的 13 份路径、以及上面这三种 run 目录拼法。**同一个事实只能有一处持有者 —— 路径也是事实。** -> -> 方法论也记一条：我第一次只 grep 了 `TEMPLATES_DIR` 这个**名字**，因此漏掉了同一文件里语义相同但叫 `DATA_DIR` 的 3 处。**同义异名的副本按名字 grep 永远找不到，要按值 / 按路径字面量 grep。** -> -> （一条**刻意不做**的：`company-service.js` 的 `const TEMPLATES_DIR = locator.AGENTS_ROOT` 取值已正确、只是名字过期，读的人会以为它指 `system/templates`。改名要动 50 处、跨 6 个文件、零功能收益 —— 不值得。留着这条记录，是为了说明它**是已知的，不是没人看见**。） - -### 6.1 先做一件清理：退役 OKR 的 `/goals` 别名 - -`index.js` / `agent-server.js` 里 `app.use('/api/goals', require('./routes/okr'))` 与 `company.js` 的 `okrPath()` 里那条 `/:companyId/goals${suffix}` 一并删除。§二.3 已核实**零调用方**。删完 `/goals` 这个词在整套 API 里只剩一个含义。 - -### 6.2 goal - -| 方法 | 路径 | 说明 | -|---|---|---| -| `GET` | `/api/company/:cid/goals` | 列表。query: `status` / `includeArchived` / `withTasks=1`（带出每个 goal 的 task 摘要，列表页一次拉完不 N+1） | -| `POST` | `/api/company/:cid/goals` | 新建。body `{ title, description, priority?, okr_node_id?, report_to?, split?: bool, tasks?: [...] }`。**默认 `split: true` → 异步调 `task-planning`**：立即 `202 { goalId, status: 'planning' }` 返回，拆分产物几十秒后才出现（前端轮询或走 SSE）。`split: false` 或显式传 `tasks` 则同步建行、不调 agent。**产出一律是 `draft`，不自动入队** —— 入队走下面的 `dispatch` | -| `GET` | `/api/company/:cid/goals/:goalId` | 详情：goal + 全部 task + 每个 task 的最近一次 run 摘要 | -| `PATCH` | `/api/company/:cid/goals/:goalId` | 改 `title` / `priority` / `okr_node_id`；`dispatched_at` 非空时带 `description` 一律 `409`（§四.4） | -| `POST` | `/api/company/:cid/goals/:goalId/dispatch` | 把该 goal 下所有 `draft` task 入队，写 `dispatched_at` | -| `DELETE` | `/api/company/:cid/goals/:goalId` | 归档。有 task 正在跑 → `409` + hint「先停止 T-xxx」；否则连带归档其下 task | - -### 6.3 task - -| 方法 | 路径 | 说明 | -|---|---|---| -| `GET` | `/api/company/:cid/tasks` | **新端点**（核实过：今天这个路径下只有 `POST`，没有 `GET`，不存在兼容问题）。返回 task 表的行，含 `goalId` / `status` / `queuePosition` / `progress` / `runId` | -| `POST` | `/api/company/:cid/tasks` | **保留、行为兼容**：不带 `goal_id` 调用时，**自动建一个同描述的 goal**（`created_by` 记调用方）再挂一条 task —— 存量调用方（含 `DispatchTaskButton`、外部 agent 的 curl）一行不用改就还能用，响应体里多出 `goalId` 字段。带 `goal_id` 则挂到既有 goal 下 | -| `PATCH` | `/api/company/:cid/tasks/:taskId` | 改 `title` / `priority`；**`depends_on` 在 `draft` 与 `queued` 都可改**（用户定案，见下）；`queued_at` 非空时带 `description` / `mode` / `budget` 一律 `409` | -| `POST` | `/api/company/:cid/tasks/:taskId/enqueue` | 单条入队：建 `queued` 的 run 行 + 写 `task-goal.json` + `tick()` | -| `POST` | `/api/company/:cid/tasks/:taskId/cancel` | `queued` → 撤出队列（run `queued → stopped`）；`running` → 转调既有 `POST /api/graph-runs/:id/stop` | -| `POST` | `/api/company/:cid/tasks/:taskId/rerun` | 从 `failed` / `blocked` / `completed` 重新入队，`attempt + 1`，**新起一条 run**（旧 run 保留在历史里）。**刻意不叫 `retry`** —— 见下 | -| `DELETE` | `/api/company/:cid/tasks/:taskId` | 归档，同 goal 的规则 | - -**`rerun` ≠ `retry`，两者会撞车。** 既有的 `POST /api/graph-runs/:id/nodes/:nodeId/retry` 是**节点级重试**：同一条 run 内把某个节点打回 `ready` 重跑（`blocked` 的唯一出路，`NODE_TRANSITIONS` 里写死的）。新加的是**任务级重跑**：新起一条 run，整张图从头来。两个都叫 retry，实现时必然有人把新端点接到旧逻辑上（或反过来）。所以任务级一律叫 `rerun`，文档、API、界面按钮文案（「重跑这个任务」vs 节点详情里的「重试这一步」）三处同时区分。 - -**`queued` 状态开放改依赖**（用户定案）。真实场景是「B 已经排上了，才发现它得等 C」，此前只能取消重建、丢掉排队位次。三条细则： -- 环检测照跑（只能引用同 goal 内的 task），有环 `400`，库里不留半条脏数据； -- **位次不受影响**：`queuePosition` 只按 `priority → seq → created_at` 排，`depends_on` 决定的是「够不够格出队」，两者正交 —— 当初担心的「改完位次怎么算」不成立； -- 新加的依赖若已经 `failed` / `cancelled`，下一次 `tick` 会自然把它推导成 `blocked`（§五.1.2），不需要额外处理。 - -**`POST /:cid/tasks` 的 409 消失了**：并发冲突不再是错误，是排队。响应体改为 `201 { taskId, goalId, runId, status: 'queued', queuePosition: 2 }`。`queuePosition` 是这次改动里对用户最直观的那个字段 —— **它的排序口径必须与调度器第 4 步逐字一致**（`priority → seq → created_at`），两处各写一份的下场已经有先例：`canDispatch` 就是因为前端自己复述了一遍取值域、还多写了一个 `blocked`，导致公司失败一次后再也下不了任务。**口径只留调度器一处，端点调用它算位置。** - -### 6.4 不动的端点 - -`GET /api/company/:cid/graph-runs`（其它调用方在用）、全部 `/api/graph-runs/*` 控制端点、`/api/okr/*`。 - ---- - -## 七、前端 - -### 7.1 布局 - -``` -┌──────────────┬──────────────┬───────────────────────┬──────────────┐ -│ 目标 · 任务 │ Org Graph │ Work Graph │ 节点详情 │ -│ 280px │ 320px │ 1fr │ 360px │ -│ │ │ │ │ -│ [+ 新目标] │ ○─○─○ │ ○──○──○ │ 四个 tab │ -│ ▾ G 做个官网 │ │ │ │ │ │ │ -│ ● T1 首页 ◀│ ○──○ │ ○ │ │ -│ ◌ T2 后台 │ │ │ │ -│ ⋯ T3 排队#2│ │ │ │ -│ ▸ G 埋点改造 │ │ │ │ -└──────────────┴──────────────┴───────────────────────┴──────────────┘ -``` - -`GraphConsole.vue` 的 `.cols` 从 `320px 1fr 360px` 改为 `280px 320px minmax(0,1fr) 360px`。 -响应式：`≤1400px` 最左栏收成 44px 图标条 + 抽屉展开（org graph 那栏最不能压，它是全局导航）；`≤1100px` 沿用既有堆叠，目标栏排最上。 - -### 7.2 新组件 `web/src/components/graph-console/GoalTaskPane.vue` - -两级树，goal 可折叠，**选中态永远落在 task 上**（org / work graph 是 task 级的）： - -- **goal 行**：状态点 + 标题 + `3/5 任务完成` + `⋯` 菜单（编辑 / 下达全部 / 归档）。点标题展开收起；goal 行本身被选中时，中栏显示这个 goal 的任务概览（v1 就是一张简单的任务卡片列表，不画图）。 -- **task 行**：状态点 + 标题（2 行截断）+ 第二排 `queued#2 · auto · 3/7 · 12min`。`depends_on` 非空时标题前加 `⇢` 并 hover 出「等 T1 完成」。 -- 状态点配色**沿用画布节点的既有色板**，不新造：running 蓝 / completed 绿 / failed 红 / blocked 橙 / queued 灰蓝 / draft 空心圈 / cancelled 灰。 - -**「+ 新目标」表单是两步的**（承接现有 `DispatchTaskButton` 的内容，搬进这一栏内联展开）： - -**第一步 · 写需求**：标题 + 描述 + 执行模式 + auto 模式的成本预警（原样保留）+ 一个「自动拆分任务」开关（默认开 = `split: true`）。主按钮「下一步」。 - -**第二步 · 确认拆分**：开关关掉就跳过这一步直接下达。开着则显示 `task-planning` 的产出——一份**可编辑**的任务清单（改描述、删行、加行、调依赖前置），带一行 `本次拆分消耗 ~N tokens`。主按钮「全部下达」，次按钮「存草稿」。 - -拆分进行中（goal `status='planning'`）显示骨架屏 + 「正在拆分…」，**并给一个「跳过，按单任务下达」的逃生口** —— 几十秒的 LLM 等待必须能被绕过，否则一次 agent 卡死就等于这个表单不能用了。拆分失败时这一步直接展示降级结果（1 条同描述的 task）+ 一句「自动拆分失败，已按单任务下达」，**不弹错误对话框**。 - -`canDispatch === false` 时**主按钮不再禁用** —— 排队之后它永远可点，按钮下方改为提示「当前 1 个任务在跑，新任务将排在第 2 位」。这是 B 类问题在界面上的最终消解。 - -### 7.3 选中态与刷新 - -- 路由 `/:id/graph-console?goal=G-xxx&task=T-xxx`，刷新 / 分享可复原。无参数时默认选中最近一条 `running` 的 task，没有则最近创建的。 -- 切 task 时 `orgNode / selectedNode / stack` 全清（不同任务的 def node 不可复用，串了会画出一张不存在的图 —— 与 `onReplanned` 的处理同理）。 -- 选中 **draft / queued** task：org 栏画 org graph **定义**（现有 `hasOrgGraph && !rootRun` 分支已能画，全 pending），顶部一条「排队中，前面还有 1 个任务」或「草稿，尚未下达」+ 对应按钮。 -- 刷新：选中 task 的 run 有 SSE（`GraphRunPane` 的 `@state`）→ 只更新那一行；整树 20s 轮询兜底。 - > ponytail: 没有公司级 SSE 通道，所以未选中的行只能靠轮询。升级路径是 `graph-run-sse` 加一个 company topic，前端订一条就够。 - ---- - -## 八、验收 - -每条都要在浏览器 `/e2e-probe/graph-console` 上真点出来，不是只跑单测。 - -1. 建一个 goal 不拆分 → 自动生成 1 条 task 并入队，左栏出现两级树，org 栏画出该 task 的 run。 -2. 建一个 goal 拆 3 条 task，T2/T3 依赖 T1 → T1 跑时 T2/T3 显示 `queued`；**T1 收敛后 T2 自动起跑**（验证漏斗钩子覆盖正常收敛），全程无人工干预。 -3. `max_parallel_tasks=1` 下建两条无依赖 task → 第二条排队而**不是 409**，`queuePosition=2`。 -4. 存量调用方兼容：`curl POST /api/company/:cid/tasks -d '{"task":"…"}'`（不带 `goal_id`）仍返回 201，且自动生成了一个 goal。 -5. 改已下达 goal 的 `description` → `409` + hint；改 `title` → 200。task 同理。 -6. `depends_on` 写成环 → `400`，库里没有半条脏数据。 -7. 取消一个 `queued` task → run `queued → stopped`，队列后面的顶上来。 -8. `failed` 的 task 点重试 → `attempt=1`，新起一条 run，**旧 run 仍能在历史里点开**。 -9. 杀掉服务再起（模拟进程重启）→ 队列里的 task 被「服务启动」这个辅助触发捡起来，不需要人工干预。 -10. 列表端点在 20 goal × 3 task 的公司上**不 N+1**（`graph_run_nodes` 的进度用一次 `GROUP BY` 出）。 -11. `/api/goals` 与 `/api/company/:cid/goals` 的 OKR 别名退役后，`OkrDashboard` / `CompanyDashboard` / `bin/lemon.js` 全部功能正常（它们走的是 `/api/okr`）。 -12. **回填**：跑迁移脚本后，既存的每条 root run 在左栏都以 goal + task 的形式出现，描述从 `task-goal.json` 读回（§四.8）。**这条必须在批 1 就验** —— 不验就等于批 1 让历史任务更看不见了。 -12b. **路径缺陷 A 已修**：在 `GRAPH_RUNS_DIR` 指向临时目录的条件下走一遍「下达 → 入队 → 读回描述」，`describeTask` 拿到的是**真实任务描述**而不是兜底文案「执行图节点任务」。 -> ⚠️ 这条验收**必须先设 env 再 `require`**：`graph-engine.js:84` / `goal-contract.js:75` / `graph-run-sse.js:34` 三处都是**模块加载时快照** `GRAPH_RUNS_DIR`，而 `company-paths.js:14` 的文件头注释恰恰记着相反的教训（「每次调用时读，不在模块加载时快照 —— 镜像时代两个模块各自快照，加载顺序不同就会算出不同的根，测试先 require 再设 env 时尤其明显」）。既有测试已经在为此做变通（`graph-engine.test.js` 注释：「`graph-run-sse` 在模块顶部快照 `GRAPH_RUNS_DIR`，必须连它一起重新 require」）。**教训在一个模块里学会了，没传出去** —— 这是本清单的第六个实例，形态还不一样：不是事实被复述，是**「事实该怎么读取」的约定只传了一半**。 -12c. **路径缺陷 B 已处理**：`goal-contract.js` 里那个声明了却从未使用的 `RUNS_ROOT` 要么真的接上、要么连 `resolveRunDir` 一起删；不留「注释承诺了、代码不兑现」的常量。 -13. **停止即出队**：`max=1`，任务 A 跑着、B 排队，对 A 点「停止」→ **B 在几秒内自动起跑**（验证 §五.1.1 的漏斗钩子覆盖了 `stopRun` 这条不走 `settleRun` 的路径），不是等 60s 兜底。 -14. **预算耗尽即出队**：把 A 的预算调到极小让它烧成 `blocked` → B 同样自动起跑。 -15. **排队期间 replan**：B 排队时点「重新规划组织」改动 org graph → B 出队后**按新图跑**，没有孤儿节点、没有卡死（验证 `syncRunNodesToDef`）。 -16. **manual 不堵队**：下一个 `manual` 任务 + 一个 `auto` 任务 → manual 不被自动拉起，auto 正常起跑；在控制台上对 manual 点「开始」才占坑。 -17. **`report_to` 穿过队列**：带 `report_to` 下达一个会排队的任务，等它出队跑完 → 上级 agent 确实收到 `/api/agent/task/report`（验证 §四.7 禁令二）。 -18. **OKR 只写一次**：一个挂了 `okr_node_id` 的 goal 下放 3 个 task，其中一个 failed → OKR 节点**只被写一次**，且不是被最后那个 failed 覆盖的（验证禁令一）。 -19. **拆分正常**：下达一个「做个官网」这类 goal → `task-planning` 产出 ≥2 条带依赖的 task，**全部是 `draft`**，界面上可改可删可加；点「全部下达」后按依赖顺序依次跑。 -20. **拆分失败必须降级**：让 `task-planning` 连续 3 轮产出非法 JSON → goal 转 `active` + 1 条同描述 task + 界面标注「自动拆分失败」，**绝不能卡在 `planning`**。 -21. **拆分记账**：拆分后 `goals.planning_tokens > 0`，且界面上看得到这一笔（验证 goal 层花费不再隐形）。 -22. **不该花钱的路径不花钱**：`split: false` 与存量 `POST /:cid/tasks` 都**不触发任何 LLM 调用**（mock 层计数验）。 -23. **上游失败 → 下游标红**：A 失败后依赖它的 B 转 `blocked` 且带 `upstream_failed:T-A`；**A 重跑成功后 B 自动回 `queued`**（验证 blocked 是每次 tick 推导出来的，不是落死的状态）。 -24. 全量 `npx vitest run` 不掉，重点是 §九.1 那批回归 + 新本体的 `_registry.json` 登记（`template-refs.test.js`）。 - ---- - -## 九、风险与已知取舍 - -### 1. `queued` 混进 `run_status` 取值域 —— 本次最大的回归面 - -新增一个状态值，所有按 `run_status` 分支的地方都要逐个确认 `queued` 不被误当可执行。实现时必须挨个看过并补测试： - -**先纠正一个前提**：`queued` run **有一整套 `pending` 节点行**（`createRun` 建行时就按定义插全了），它和 `ready` run 在数据上唯一的差别就是 `run_status` 那一个字段。所以「靠没有节点行自然报错」这道想象中的防线**根本不存在** —— 唯一的闸门是各处对 `run_status` 的判断，必须逐个钉死。 - -| 位置 | 期望 | -|---|---| -| `graph-engine.advanceOne` | 已有 `if (run.run_status !== 'running') return result(..., 'run-not-running')` ✅ 天然挡住。**但要加断言测试钉死** —— 这是防止 `queued` run 被误推进的唯一一道闸 | -| `graph-engine.startRun` | 只接受 `ready`；对 `queued` 必须拒绝（出队顺序是先 `queued→ready` 再 `startRun`，不能反过来） | -| `TERMINAL_RUN_STATUS` / `settleRun` / `propagateToParent` | `queued` 既非终态也非活跃态，收敛判定不该碰到它；且它只可能是 root run，不涉及向上传播 | -| `ACTIVE_ROOT_RUN_STATUS`（`graph-run.js` + `company.js` 两处） | 不含 `queued` ✅ 天然正确，但要加断言测试钉死 —— **这条正是 §四.3 出队原子性的全部依赖** | -| `GraphConsole.loadRuns` 的 `roots.find(active) \|\| roots[0]` | 会把 `queued` run 当成「最近的 root run」画图 —— **必须改**，否则入队一条任务就把 org 栏画崩 | -| 服务启动的中断任务恢复（`server/index.js`）| `queued` 不该被当成「被中断的 run」拉起，它该走调度器 | -| `company-heartbeat-service` | 同上 | -| `GET /api/graph-runs/:id` / SSE | `queued` run 要能正常读（控制台要显示「排队中」），不能因为没有 `started_at` 之类的字段报错 | - -### 2. 「排队」这条路当初被明确否决过，现在要对它负责 - -`company.js` 的注释原话：*选拒绝的理由是，仓库里没有任何出队/唤醒的 worker，排进去的任务不会被自动消费，那是一条会静默丢任务的路*。**这条判断在今天仍然成立** —— 它只是被 §五.1.1 的调度触发解除。所以调度器（尤其是挂在 `transitionRun` 上的那个漏斗钩子）是本次的**功能主体**，不是收尾工作；验收 2 / 9 / 13 / 14 专门验它。**初稿用「枚举四个触发点」的写法本身就漏了两条最常见的释放路径**（`stopRun` 与预算耗尽），这正说明枚举法在这里靠不住——症状是任务静默躺在队里，而界面上它长得跟「正在排队」一模一样。 - -### 3. `description` 双写（DB + `task-goal.json`） - -两份都在入队那一刻写、之后都不可变（§四.4）——结构上不可能不一致。这正是「已下达不给改」的真正理由，而不是保守。 - -### 4. 归档只是隐藏 - -`data/companies/{cid}/runs/{runId}/` 仍在磁盘上。本次不做 GC；需要时另立清理任务（按 `archived_at` 早于 N 天）。 - -### 4bis. 三处「排队打破了『下达即执行』这个隐含假设」 - -本次复核抓到的三条同形缺陷，共性是**既有实现都没错，只是它们都默认了「请求进来 → 立刻执行」**，排队把那个假设拆了，而且拆得非常安静（都不报错）： - -| # | 缺陷 | 症状 | -|---|---|---| -| 1 | `report_to` 只活在请求闭包里（§四.7 禁令二）| 上级 agent 永远等不到回调，没有任何日志 | -| 2 | 节点行在 `createRun` 时快照，排队期间 replan 就分叉（§四.3 末）| 出队后 run 卡死在「有新节点但没有 run 行」 | -| 3 | `okr_node_id` 逐 task 写同一个 OKR 节点（§四.7 禁令一）| 最后一个收敛的 task 说了算，done 会被后来的 failed 覆盖 | - -**实现时的通用检查法**：凡是「从 HTTP 请求体里取出、直接交给 driver / 闭包」的东西，在排队模型下都要问一句「几小时后它还在吗」。 - -### 4ter. `task-planning` 引入的三个新风险 - -1. **多一次会失败的 LLM 调用挡在「下达任务」前面**。今天下达是一次同步 DB 写，现在中间插了一次几十秒、可能失败的 agent 调用。降级路径（§四.9 约束 2）和界面上的逃生口（§七.2）**不是可选项** —— 少了任何一个，一次 agent 卡死就等于整个下达入口不可用。 -2. **拆分质量决定预算消耗**。拆出 5 条 task 就是 5 份 `DEFAULT_TASK_BUDGET`（各 100 次调用 / 500 万 token）。这是「产出一律 `draft`、必须人确认」的根本理由 —— 那一步是唯一一道成本闸门。界面上要显式提示「N 个任务 ≈ N × 单任务成本」。 -3. **新本体的真正闸门是「毕业」，不是 registry 登记**（§四.9 约束 4/5 已纠正初稿的反向结论）。`agent.md` + `soul.md` 没写满就停在 `draft`，`hire()` 返回 `body_not_ready`；而 `_registry.json` 缺条目只是少个 `benchmark_score`。另外本体正文的相对路径写错**不报错只静默降级**（§四.9 约束 6）—— 这是本文档点名的静默故障家族里最新的一个成员。 - -### 4quater. 本文档有三处要求属于同一个惯犯模式：「实现在、零调用方」 - -§四.1 砍掉 `goals.budget_json`、§四.7 禁令二要求 `report_to` 落库、验收 12c 处理 `goal-contract.js` 那个声明了却零使用的 `RUNS_ROOT` —— 三条都是同一件事：**别留下「代码写了、但没有任何活的调用方/消费方」的东西。** - -这不是洁癖，仓库里有完整的证据链，而且证据本身就说明问题： - -| 出处 | 原话 | -|---|---| -| `graph-engine.js`（`indexNodeOutputs` 注释）| 「凡『靠 agent 自觉』的环节几乎全部落空过（**goal-contract 零调用**、`setPlanWorkGraph` 零调用、三值透传只接了读那一半）」| -| `graph-engine.js`（跨层判据处）| 「（『实现在、零调用方』的**第五次**）」| -| `graph-run-route-io.test.js` 文件头 | 「就是这一路踩了**十几次**的『实现在、零调用方』换个方向再来一次（这次是前端在、后端没喂）」| -| `graph-edge-contracts.test.js` 文件头 | 「`declareEdgeContract` **零调用方**」| -| `graph-run.js:243` | 「契约声明与产物索引都在库里，界面上却看不见，等于**又一次**『实现在、零调用方』」| -| `27-goal-contract-format.md:101` | 「T0 交付后有四轮时间里，全仓库唯一提到 `goal-contract.js` 的是一句注释 —— 实现完整、零调用方、零单测，§六 验收 1 **从未被执行过**」| -| 27-P3/P4 §八 已关闭项 6 | `ProcessGuard` 生产代码里从未被实例化、`RunRegistry.add()` 从未被调用、杀进程那条链同样零调用方 | - -**这些记录证明的不是「有这个问题」，而是「发现了也没人回来收」** —— 有人数到第五次，有人写「十几次」，然后它继续复发。所以本文档凡是写「必须落库 / 必须接上调用方 / 零调用方就删掉」的地方，都请当成硬要求，而不是可以留到下一轮的整洁度问题。 - -**批 1 的落点**：验收 12c 就是收其中一个（`resolveRunDir` + 那个死常量）。同时按并行会话的建议加一条不变式测试 —— 「凡是声明了 `GRAPH_RUNS_DIR` 覆盖的模块，该覆盖必须真的被用到」，形状照抄 `server/tests/unit/agents-root-single-holder.test.js`（**「样本非空」前置断言别省** —— 扫不到文件时会静默全绿，那正是这类测试自己变成「零调用方」的方式）。 - -### 5. 两套 `T-` id —— 由 §十二 的统一消解，但在那之前是真风险 - -`agent-chat.js` 的 `/task/dispatch` 也发 `T-` 开头的 id 并写 `system/tasklog/`。**批 1-4 期间两套并存**，长得像但不同源，读日志时别混（本文档的 id 一律带 `-{4hex}` 后缀，肉眼可分）。批 5（§十二）把存储统一到 `tasks` 表之后，这个风险随之消失 —— 那时 `T-` 只有一个来源。 - -### 6. 并行是最后一批，且要单独验 - -批 4 会 `DROP` `idx_graph_runs_one_active_root` —— 删掉最后一道 DB 兜底。守卫改成事务内 count + admit（SQLite 单写者天然序列化）。不与界面改动同批上线。 - ---- - -## 十、实施顺序 - -| 批 | 内容 | 验收 | -|---|---|---| -| **1 · 两级模型落库** | `goals` / `tasks` 建表 + **存量回填脚本（§四.8）** + ID 生成器修正 + `POST /:cid/tasks` 兼容改造（自动建 goal、`report_to` 落库）+ `GET` 列表端点 + 退役 `/goals` 别名 | 4 / 10 / 11 / **12** | -| **2 · 控制台左栏 + 拆分** | `GoalTaskPane` 两级树 + URL 选中态 + `loadRuns` 修正 + **`task-planning` 本体（含 `_registry.json` 登记）+ 拆分链路 + 失败降级**+ 两步表单 | 1 / 19 / 20 / 21 / 22 | -| **3 · 排队** | `run_status='queued'` + `RUN_TRANSITIONS` + `syncRunNodesToDef` + `task-scheduler`（漏斗钩子 + 三个辅助触发 + 重入保护 + 上游失败推导 blocked）+ `depends_on` 环检测 + 入队/取消/rerun 端点 + §四.7 两条禁令 + §九.1 全部回归点 | 2 / 3 / 5 / 6 / 7 / 8 / 9 / 13-18 / 23 | -| **4 · 并行**（单独排期）| `max_parallel_tasks` + `DROP` 唯一索引 + 事务内 admit。**与 [27-P4](./27-p4-parallel-and-artifacts.md) §一.3 同一件事**，实施以那份为准 | 另立验收 | -| **5 · 任务体系统一**（单独排期）| 见 §十二：`executor` / `assignee_agent_id` / `parent_task_id` 三字段 + `/task/dispatch` 换存储 + 删会话反推 + `tasklog` 回填 | 25-30 | - -> 批 3 的验收从 6 条涨到 12 条，是本次复核的直接结果 —— 13/14/15 三条各自对应一个「初稿会实现出来的静默故障」。 - -### 与并行进行中的「agent 目录结构重构」的关系（2026-08-18 核实） - -写本文档期间，另一条工作线正在做 **agent 目录结构重构**（`system/templates/` 并入 `system/agents/`，两份 `_registry.json` 合一），工作区约 900 个变更**尚未提交**。它与本文档有实质交集，逐条核实结果： - -| 交集点 | 结论 | -|---|---| -| 本文档逐字引用的全部函数 / 常量（`settleRun` / `markRunReady` / `stopRun` / `defaultPlanWorkGraph` / `PLAN_MAX_ROUNDS` / `writeTaskGoalArtifact` / `reportRunOutcome` / `ACTIVE_ROOT_RUN_STATUS` / `saveTaskMeta` / `getAggregatedTasks`）| **全部存活**。重构改了约 650 行、5 个文件，但没有动这些锚点 —— 27-P3/P4 那条「只写函数名不写行号」的体例在这里直接兑现了价值 | -| 本文档的五条**行为性**结论（`markRunReady` 写死 `planning`、`settleRun` 只在 `advanceOne` 内被调、`stopRun` 不走 `settleRun`、`reportRunOutcome` 读 `run.okr_node_id` 与闭包里的 `ctx.reportTo`）| **逐条复验仍然成立** | -| `work-graph-db.js`（`createRun` 建节点行、`updateRunStatus` 条件更新、`RUN_TRANSITIONS`、唯一索引）| **完全未被改动** —— 第二轮复核里最关键的那批发现不受影响 | -| 新建本体的做法（§四.9）| **初稿有一条写反了，已纠正**：`system/templates/` 彻底取消（本体落 `system/agents/`）；`_registry.json` 已不是数据源头（`seedAgents` 扫目录当真相），登记是可选的；真正的闸门是**毕业**（`agent.md` + `soul.md` 非空且无 `_base` 哨兵，否则 `hire()` 返回 `body_not_ready`）；本体正文的相对路径另有三条硬规矩，写错静默降级。详见 §四.9 约束 3-6 | -| `agent-chat.js`（+455 行）、`company.js`、`agent-manager.js` | 都是本文档批 1 / 批 5 要改的文件。**新端点是新增代码，不冲突**；但 §十二 的前提「`/task/dispatch` 的 URL 与请求体一个字都不能动」需要在批 5 开工前**基于重构后的版本重新核一遍**（`tools-base.md` 目前未被改动，是个好迹象） | - -**对排期的影响**：批 1 可照常开工（`work-graph-db.js` 无人触碰，建表 + 回填是纯新增）。**批 2 的 `task-planning` 本体应当等 agent 重构落地后再建** —— 否则本体目录与登记方式要按旧形态做一遍、再按新形态改一遍。批 5 在那之后重新核 `agent-chat.js`。 - -批 1+2 上线就已经解决用户提的核心痛点（历史任务看不见、需求无法分解）；批 3 才是「不再只能有一个」。 - ---- - -## 十一、开放问题 - -1. ~~谁把 goal 拆成 task？~~ **已定案（2026-08-18）：`task-planning` agent 进 v1**，产出 `draft` 任务清单由人确认后下达，详见 §四.9。 -2. ~~goal 级的验收谁做？~~ **已定案（2026-08-18）：仍然是 `org-validator`**，在 goal 层再调一次同一个本体，输入是该 goal 全部 task 的产物合集。详见 §四.10。 -3. ~~失败的 task 挡不挡住依赖它的下游？~~ **已定案（2026-08-18）：自动转 `blocked` 并在界面标红**，给「重跑上游」与「强制放行」两个出路；`blocked` 每次 `tick` 重算而不落死，上游恢复后下游自己回 `queued`。详见 §五.1.2。 -4. ~~跨公司任务总览 / 两套任务树并存~~ **已定案（2026-08-18）：统一到 `tasks` 表一套，删掉会话反推那套。** 详见 §十二（批 5）。 -5. ~~`max_parallel_tasks` 放 `company.json` 还是建 `company_settings` 表？~~ **已定案（2026-08-18）：放 `company.json`。** 详见 §五.2。 - -> **本文档的开放问题至此全部关闭。** 后续新增的疑问按惯例继续往这一节追加，不要在正文里留疑问句。 -6. ~~goal 级总预算怎么定口径？~~ **已定案（2026-08-18）：预算先不考虑，不做 goal 级闸门。** `goals.budget_json` 保持砍掉。**但 `planning_tokens` / `validation_tokens` 两个记账字段保留** —— 它们不是闸门，是让 goal 层那两次 agent 调用的花费**可见**；不记就是 `defaultPlanWorkGraph` 注释点名的「隐形的一半」，而且界面上「本次拆分消耗 ~N tokens」这个确认步骤要用它。 -7. ~~排队中的任务能不能改依赖？~~ **已定案（2026-08-18）：可以改。** `queued` 状态开放 `depends_on` 的 `PATCH`，见 §六.3。当初担心的「改完位次怎么算」不成立：`queuePosition` 只按 `priority → seq → created_at` 排，`depends_on` 决定的是**够不够格出队**，两者正交，改依赖不动位次。 - ---- - -## 十二、批 5 · 任务体系统一（用户定案：统一到一套，删掉另一套） - -### 12.1 现状：两套并存，而且**新体系已经依赖旧体系的一半** - -| | A · 本文档的体系 | B · 会话反推的体系 | -|---|---|---| -| 存储 | `goals` / `tasks` 表（SQLite） | `system/tasklog/{taskId}.json` 一任务一文件 | -| 入口 | `POST /api/company/:cid/goals`、`/tasks` | `POST /api/agent/task/dispatch`（**agent 之间派单**，`tools-base.md` 里写着让 agent curl 它）| -| 收敛 | `settleGoal` → OKR + `report_to` | `POST /api/agent/task/report`（更新 todo/plan → 更新 OKR → 推进 Pipeline → 唤醒上级）| -| 任务树 | `goal_id` / `depends_on` 显式存 | `TaskService.getAggregatedTasks()` **扫全部 agent 的 conversations 反推**父子关系（391 行）| -| 读接口 | `GET /:cid/goals`、`/tasks` | `GET /api/tasks`、`/api/tasks/:id/timeline`（59 行）| -| 前端 | `GoalTaskPane`（§七）| `TaskTimeline.vue`（736 行，唯一消费方）| -| id | `T-{base36}-{4hex}` | `T-{base36}`（同前缀不同源，§九.5）| - -**关键事实：A 的收敛出口调的正是 B 的 `/api/agent/task/report`。** 批 1 之前这个出口是 `company.js:reportRunOutcome`（run 级），批 1 把它删掉、换成了 `task-settle.js:reportGoalOutcome`（goal 级，挂在 `transitionRun` 漏斗上）——**函数换了，依赖关系没变**。两套不是并列关系，A 的回调链路仍然长在 B 身上。所以「删掉另一套」不能理解成整片删除 —— 要删的是**存储与反推**，不是入口与回调。 - -### 12.2 删什么、留什么 - -**删**： -- `system/tasklog/` 目录及其读写（`agent-chat.js` 的 `saveTaskMeta` / `loadTaskMeta`，`task-service.js` 的 `_loadTaskMetas`）； -- `TaskService.getAggregatedTasks()` —— **从会话记录反推任务树**这整套启发式。父子关系改为显式存字段，不再猜。 - -**留（改数据源）**： -- `POST /api/agent/task/dispatch` **URL 与请求体形态一个字都不能动** —— 它写在 `packages/agent-core/base/common/tools-base.md` 里，是所有 agent 的工具说明；改了等于同时改所有 agent 的提示词。只把它的存储从写 JSON 文件改成写 `tasks` 表。 -- `POST /api/agent/task/report` 同上（A 的回调依赖它）。 -- `TaskService.getTaskTimeline()` —— 它读的是 agent 的 `conversations/`，那是**真实的一手数据**，不是反推。留着，只把「有哪些 task、父子是谁」换成查表。 -- `TaskTimeline.vue` 保留，换数据源。 - -### 12.3 `tasks` 表要吸收 B，需要三个字段 - -B 的 task 与 A 的 task 有一处真实差异：**执行载体不同**。A 的 task 跑一张 org graph（走调度器），B 的 task 是直接派给某个 agent 起一次对话（`autoExecute`）。硬说成一回事会骗自己，所以显式建模： - -```sql -executor TEXT NOT NULL DEFAULT 'graph', -- 'graph'（跑 org graph，走 §五 调度器） - -- 'agent'（直接派给某个 agent 对话，不进队列） -assignee_agent_id TEXT, -- executor='agent' 时派给谁（B 的 `to`） -parent_task_id TEXT REFERENCES tasks(id), -- B 的任务链；A 的 depends_on 是同级依赖，两者不同 -``` - -**调度器只管 `executor='graph'`**（§五.1 的候选筛选加这一条），`executor='agent'` 的 task 由 `/task/dispatch` 自己起对话，进表只为了「可见、可查、可串成树」。 - -`goal_id NOT NULL` 怎么办：**agent 派单时自动建一个 goal**（`title = '来自 {from} 的派单'`、`created_by = from`），与 §六.3 已经为 `POST /:cid/tasks` 设计的兼容路径**同一条**。模型保持干净，不给 `goal_id` 开可空的口子。 - -### 12.4 顺带修好的两件事 - -1. **30 分钟去重从「扫全目录 JSON」变成一条 SQL**。现在 `/task/dispatch` 每次派单都 `readdirSync` + 逐个 `JSON.parse` 整个 `tasklog/` 来找相似任务 —— 任务一多就是 O(n) 次磁盘读，且相似度判断本身也没索引可用。改成 `WHERE company_id=? AND assignee_agent_id=? AND status='queued' AND created_at > ?` 一条查询。 -2. **两套 `T-` id 合一**（§九.5 那条风险就此消失）。id 生成统一走 §四.5 的 `T-{base36}-{4hex}`。 - -### 12.5 迁移 - -`system/tasklog/*.json` 回填进 `tasks` 表，与 §四.8 的 root run 回填**放在同一个脚本**（同一次数据形态变更，分两个脚本只会让「跑了哪个没跑哪个」变成新问题）。字段映射：`to → assignee_agent_id`、`parentTaskId → parent_task_id`、`objectiveId/goalId → 所属 goal 的 okr_node_id`、`status` 按 `dispatched/done/failed/blocked` 映射。**回填后目录改名为 `system/tasklog.bak-unify/` 而不是直接删**，跑顺一个版本再清。 - -### 12.6 排在批 5 的理由 - -它依赖 `tasks` 表存在（批 1）、依赖 `executor` 语义在调度器里被正确排除（批 3）。而且它**改的是 agent 的生产链路**（派单 / 汇报 / 唤醒），风险面与前四批完全不同 —— 前四批坏了是控制台不好用，这一批坏了是**所有 agent 互相派不了活**。必须单独一批、单独验收。 - -### 12.7 验收 - -25. `POST /api/agent/task/dispatch` 请求体不变，派单成功后 `tasks` 表出现 `executor='agent'` 的行，`system/tasklog/` 不再产生新文件。 -26. 派单的 task **不进调度队列**（`executor='agent'` 被 §五.1 排除），不占 `max_parallel_tasks` 的坑。 -27. 30 分钟去重仍然拦得住重复派单，且不再读目录（改成 SQL）。 -28. `POST /api/agent/task/report` 汇报链路四步（todo/plan → OKR → Pipeline → 唤醒上级）全部照常；**`task-settle.reportGoalOutcome` 那条依赖它的路也照常**（批 1 之前这条依赖挂在已删除的 `reportRunOutcome` 上）。 -29. `TaskTimeline.vue` 任务列表与时间线都正常，父子关系来自 `parent_task_id` 而非会话反推。 -30. 存量 `system/tasklog/*.json` 全部回填进表，目录改名保留。 - ---- - -## 十三、批 1 实施记录（2026-08-18，commit `7f24ef0`） - -> 体例照 [27-P3/P4](./27-p3-p4-work-graph-console.md) §十：**设计正文不改写，只在这里与实现对账**。 -> 凡本节与前文冲突，**以本节为准** —— 前文是设计时的判断，本节是跑出来的事实。 - -### 13.1 落地了什么 - -| 交付 | 落点 | -|---|---| -| `goals` / `tasks` 两张表 + CRUD + `depends_on` 环检测 | `work-graph-db.js` | -| ID 生成器 `G-/T-{base36}-{4hex}` + 主键碰撞重试 | 同上（`insertWithFreshId`：4hex 只有 65536 种取值，实测同毫秒建 2000 条会撞 5 次） | -| goal / task 全套端点 + `POST /:cid/tasks` 向后兼容 | `company.js` | -| 退役 `/api/goals` 与 `/:cid/goals` 两个 OKR 别名 | `index.js` / `agent-server.js` / `company.js` | -| **终态回写 + goal 收敛 + OKR 写一次** | `graph-run-sse.transitionRun` 钩子 → `task-settle.js`（新） | -| 三处「模块加载时快照 `GRAPH_RUNS_DIR`」改调用时读 | `graph-engine.js` / `graph-run-sse.js` / `goal-contract.js` | -| 存量回填脚本（幂等 + `--dry-run`） | `scripts/migrate-runs-to-goal-task.js` | -| 4 个测试文件，含不变式测试 | `server/tests/unit/` | - -全量：**116 文件 / 1057 测试全绿**。 - -### 13.2 与设计正文的四处偏离（**以本节为准**） - -**① `blocked` 在 task / goal 两层都不是终态。** -正文 §四.3 的状态机把 `blocked` 与 `completed`/`failed` 并列画成终态。实现时发现那是错的，而且**实跑复现出了后果**： - -``` -预算耗尽 → task=blocked, goal=failed, OKR=failed -人加预算恢复 → run=running -跑完 → run=completed, task=blocked, goal=failed, OKR=failed ← 永久对不上 -``` - -`RUN_TRANSITIONS` 里 `blocked: ['running','stopped']` —— 对 run 它是**可恢复态**，`reviveParentFromChild` 还会自动把它拉回 running。若 task 层把它当终态，恢复后跑完时 `settleTaskFromRun` 与 `settleGoalStatus` 两次条件更新**静默命中 0 行**，无日志无事件。 - -定案：`TASK_TERMINAL_STATUS` 只含 `completed / failed / cancelled`；**只要有一条 task 处于 `blocked`，goal 就不收敛**（不写 OKR、不唤醒上级）。`blocked` 的语义是「挂起等人介入」，与那三个不同类。run 转 blocked 时**仍然**把 task 写成 blocked（界面要看得见卡住），只是不触发收敛。 - -连带：归档守卫从「过严」翻到「过松」过一次 —— 恢复后 task 停在 `blocked`、run 却在 running，用户能归档掉一条**正在烧预算**的 run。现由 `taskHoldsRun()` 兜住（`ACTIVE_ROOT_RUN_STATUS` **派生**出 `RUN_HOLDING_STATUS`，不复述第二份字面量）。 - -**② goal 级是唯一汇报出口，`reportRunOutcome` 已删除。** -正文 §四.7 把它写成「root run 收敛后的唯一出口」。批 1 的唯一形态是 1 goal : 1 task，而 `createTask` 继承 `goal.report_to`，于是 run 级与 goal 级两条汇报会**就同一件事把上级 agent 唤醒两次**（其中一次带的是它从没见过的 `G-` id）。 - -grep 确认 `reportRunOutcome` 无其它调用方（连它自己那行 `module.exports` 都零人 require），整体删除。理由：run 级只在 auto 模式触发（manual 收敛不走 driver），本来就是半条链路；goal 级挂在唯一漏斗上，manual / auto / stopped / blocked 全覆盖。 - -同时 `from` 的口径修正为**实际交付者**：`terminalOrgAgent` 从 `company.js` 搬到 `org-graph-service.terminalAgentId()`（唯一持有者），不再用 `goal.created_by` —— 那是「谁下的单」，默认字面量 `'human'`，下游 `readStateFile('human','todo.md')` 会静默落空。 - -**③ dispatch 挑第一条「可跑的」draft，不是恒取 seq 最小那条。** -`validateDependsOn` 只拒环、不拒正向引用，所以「第 1 条依赖第 2 条」是合法输入；而恒取 `drafts[0]` 会让这种 goal **永远下达不了**（`blockers` 恒非空）。批 2 的 `task-planning` 产出契约正是「`depends_on` 只引用本次产出的 seq」，产出乱序完全在射程内。 - -连带：`PATCH /:cid/tasks/:taskId` 补上了改 `seq` 的入参翻译 —— 原先 409 的 hint 写着「改依赖或 seq」，而那个端点从不读 `body.seq`，**两条自救路径只有一条通**。 - -**④ `POST /:cid/goals` 批 1 只做同步路径。** `task-planning`（§四.9）与 goal 级 `org-validator` 验收（§四.10）属批 2，`verdict` / `validation_tokens` 两列目前只有定义、无写侧。 - -### 13.3 过程：三轮编排，19 条缺陷 - -| 轮次 | agent | 产出 | -|---|---|---| -| 1 · 实现 | 11 | 建表 + 端点 + 回填 + 测试；对抗复核报 **10 条缺陷** | -| 2 · 修复 | 6 | 修完 10 条；复核确认真修好，但报出 **4 条修复自己引入的新缺陷** | -| 3 · 再修 | 4 | 修完 4 条；全绿 | - -**最值得记的一条**是②那类：*第二轮的修复引入了第三轮才发现的缺陷*，而且是同一个形状——「界面撒谎」的镜像版本。这说明**对抗复核不能只做一轮**：修复本身和实现一样会出错，而且更隐蔽（它长得像在解决问题）。 - -判定为**非问题**的 5 条也记一笔（复核给了证据）：进度查询确实是一条 `GROUP BY` 不 N+1；`LIMIT` 的字符串插值前置了 `Number.isInteger` 守死；`tasks.goal_id` 的真外键在 `foreign_keys=ON` 下不与软删冲突；回填脚本的两条幂等判据覆盖了「脚本重跑」与「新链路建出来的 run」；`/goals` 别名确为零调用方（`OkrDashboard.vue` / `CompanyDashboard.vue` / `bin/lemon.js` 全走 `/okr`）。 - -### 13.4 一条对外可见的破坏性变更 - -`POST /api/company/:cid/tasks` 的 `goal_id`：旧代码原样存进 `graph_runs.goal_id` **不校验**，新代码要求它是 `goals` 表里本公司的真行，否则 **404**。仓库内无此调用方，但外部 agent 的 curl 若一直往这里传 OKR 节点 id 之类的值，会从 201 变 404。**404 是对的**（那种调用方本来就在制造悬空外键），但属于对外可见的行为收紧。 - -### 13.5 留给下一轮的两条 - -1. **run 转 `blocked` 时仍写 `finished_at`** —— 「挂起 ≠ 结束」，界面会显示一个随后被恢复覆盖掉的结束时间。改它要动 `settleTaskFromRun` 的签名。 -2. **run 从 `blocked` 恢复成 `running` 时不把 task 写回 `running`** —— task 行会在恢复期停在 `blocked`。归档守卫已经兜住了它的风险（§13.2 ①），要消掉需要在 `afterRunTransition` 上加「离开终态时反向回写」，与批 3 的调度器一起做更合适。 - ---- - -## 十四、批 2 实施记录（2026-08-18） - -> 体例同 §十三：**设计正文不改写，只在这里对账；冲突处以本节为准。** - -### 14.1 落地了什么 - -| 交付 | 落点 | -|---|---| -| `task-planning` 本体（毕业判据实测通过） | `system/agents/task-planning/` + `_registry.json` | -| 拆分链路（3 轮 errors 回喂 / 降级 / token 记账 / 注入缝 `setPlanTasks`） | `server/services/task-planning.js`（新） | -| goal 级 `org-validator` 验收（注入缝 `setValidateGoal`） | `server/services/goal-validation.js`（新）+ `task-settle.js` | -| 目标·任务两级栏 + 四栏布局 + 两步表单 | `GoalTaskPane.vue` / `NewGoalForm.vue` / `goal-task-model.js` / `GraphConsole.vue` | -| 中断恢复：启动时补跑验收与汇报 | `task-settle.resumePendingGoalValidations` + `server/index.js` | - -全量：**118 文件 / 1112 测试全绿**，`npm run web:build` 通过。 - -### 14.2 与设计正文的六处偏离（**以本节为准**） - -**① 拆分完成/降级后 goal 落 `draft`，不是 `active`。** -§四.9 约束 2 与 §八 验收 20 都写「降级后 goal 转 `active`」。实现落 `draft`，理由成立且已复核确认：`active` 的语义已被 `markGoalDispatched` 钉死为「**已下达**」（连带盖 `dispatched_at` = 描述冻结点），而 §四.9／§六.2 同时要求「产出一律 draft、不自动入队」。两者只能取一个 —— 拆分失败却标 `active` 且一条 task 都没起，界面上就是一个「进行中」却什么都没跑的 goal，正是本文档反复点名的「界面撒谎」。硬要求「绝不能卡在 planning」两种落点都满足。 - -**② `POST /:cid/goals` 默认异步（202 + `status:'planning'`）**，`split:false` 或显式 `tasks[]` 走同步 201。存量 `POST /:cid/tasks` 走同步路径，**不会因为这次改动多花一次 LLM 调用**。 - -**③ `mode` 是三级继承**：`tasks[i].mode` > goal 级 `mode` > `'manual'`，**goal 级对显式 `tasks[]` 同样生效**。这是对存量调用方的行为变化（原先显式 `tasks[]` 恒 manual），已写进端点 JSDoc + 用例钉住 —— 从「静默变化」变成「明写约定」。 - -**④ 占位判词不出 API。** 验收窗口里 `goals.verdict` 挂的是内部认领 token（含进程随机段与时间戳），`goalView` 对外只回 `(验收进行中)`。判定走 `task-settle.isPendingVerdict`，不在路由层比字符串。 - -**⑤ 认领带租约。** 见 §14.3 第 3 条。 - -**⑥ 新增两列**：`goals.planning_error`（降级原因，界面展示）、`goals.reported_at`（汇报可查性）。`reported_at` 的迁移**带回填** —— 不回填的话加完列第一次启动会把库里所有历史终态 goal 当成「汇报丢了」重报一遍。 - -### 14.3 三条跨进程竞态（全部用真探针实跑复现后才判定修好） - -**1 · `runGoalSplit` 无条件把 goal 写回 `draft`，抹掉并发发生的「已下达」。** -触发它的正是表单自己推荐的逃生口：用户点「跳过，按单任务下达」→ goal 变 `active` 且 run 在跑 → 拆分收工把它写回「草稿」，并多插 N 条 draft task → `settleGoalIfAllTasksDone` 看到 `[T1 completed, T2..TN draft]`，draft 不是终态 → **永不收敛**，OKR 不写、上级不唤醒。 -修法：条件更新 `WHERE status='planning' AND archived_at IS NULL`，没命中就一条 task 都不插（但**钱照记**）。 - -**2 · CAS 把最终态提前写进库，验收窗口内重启即丢，且查不出来。** -`verdict=NULL` 也正是「1 条 task 跳过验收」的合法形态，**没有任何查询能把「验收丢了」和「本来就没验」分开**。 -修法：占位判词 + 启动重推。三态可分：`NULL`（没验）/ 占位前缀（进行中或丢了）/ 真判词（已定案）。 - -**3 · 认领语句自己构成了它点名要避开的形态。** -第一版重推的认领是 `SET verdict=RESUMING WHERE verdict IN (PENDING, RESUMING)` —— **写进去的值就在 WHERE 里**，已被认领的行照样匹配，`changes` 恒为 1。而函数注释白纸黑字写着「认领写的是**另一个**占位值，别的扫描者就不会再选中它」。**注释是对的，代码没兑现。** -实测后果：`org-validator 调 2 次 / OKR 写 2 条 / token 双记`。 -修法：claim 值 = 前缀 + 进程随机段 + 进程内自增 + **时间戳**；认领的 WHERE 只认上一个态；回写改成 `WHERE verdict = @claim` 的条件更新决胜；**主路径也走同一套闸门**。 - -> 第三轮之后仍剩一条同款：`reported_at` 只有认领一道闸，且接受任意占位值当旧值 —— B 实例会把 A 实例**手上还活着**的汇报抢走，上级被叫醒两次。第四轮补上**租约**（`CLAIM_LEASE_MS`，默认 10 分钟）：活着的认领不许抢，过期的才准抢。**只认 `null` 不行** —— 那会把「可恢复的洞」换成「不可恢复的洞」。 - -### 14.4 过程：四轮，22 条缺陷，其中 6 条是修复自己引入的 - -| 轮次 | agent | 结果 | -|---|---|---| -| 1 · 实现 | 11 | 全绿；复核报 8 条 | -| 2 · 修复 | 5 | 修 6 条；复核报 1 条**新引入**的高危（认领竞态，实跑复现） | -| 3 · 再修 | 5 | 竞态真消灭（跨进程探针验证）；复核又报 4 条 | -| 4 · 收尾 | 人工 | 租约 / 归档不重报 / 输家记账 / 判词不出 API | - -**第四轮修完挂了 3 条测试，全都是测试在钉住缺陷本身**：断言「抢跑输家的 token 为 0」（= 钱静默蒸发）、断言「重推能抢走新鲜占位」（= 跨进程重复汇报）。其中一条的注释写着「这里模拟的是进程死后重启」，而它构造的占位值是**新鲜的** —— 注释描述 A 场景、代码构造 B 场景、断言按 A 场景写。按注释的语义把占位值做旧，测试就对了。 - -> **这是本文档第二次记录同一条规律**（§十三.3 是第一次）：修复与实现一样会出错，而且更隐蔽 —— 它长得像在解决问题。批 1 三轮、批 2 四轮，两次都不是一轮收敛的。 - -### 14.5 留给下一轮 - -1. **跨进程判活要租约 + 心跳**：现在靠固定租约窗口，抢跑者仍可能多烧一次 LLM（副作用一个都不会多做）。 -2. **汇报语义是 at-least-once**：exactly-once 要 `/api/agent/task/report` 认幂等键（goal id + 收敛时间），属接收侧改动。 -3. **拆分超时只在本进程存活期间成立**：进程中途被杀会留下 `status='planning'` 的 goal，需要启动时扫描重推（与批 3 的中断恢复一起做）。 -4. `io-model.check.js` 仍是零调用方（同款前科，批 2 已把 `goal-task-model.check.js` 转成真测试）。 - ---- - -## 十五、批 3 + 批 4 实施记录（2026-08-19） - -> 体例同 §十三 / §十四：**设计正文不改写，只在这里对账；冲突处以本节为准。** - -### 15.1 落地了什么 - -**批 3 · 排队**（commit `87b776c`，**该提交由第三方会话在对抗复核完成前误提，见 §15.4**） -`run_status='queued'` + `RUN_TRANSITIONS` + `syncRunNodesToDef` + `task-scheduler.js`（tick / sweep / -依赖推导）+ 入队/取消/rerun 端点 + 控制台队列显示与三处可见性修复。 - -**批 4 · 并行**（本次） -`idx_graph_runs_one_active_root` **已 DROP**；`max_parallel_tasks` 从 `company.json` **调用时读** -（缺省 1、非法回落 1 并留声、硬上限 20）；准入判据「从活跃集外进入活跃集」按额度计数。 - -全量：**128 文件 / 1240 测试全绿**，`npm run web:build` 通过。 - -### 15.2 批 4 的生死线：超发（真进程实跑，不是纸面论证） - -删掉唯一索引 = 删掉最后一道 DB 兜底，此后全靠 `updateRunStatus` 的准入事务。**用 8 个真 node 进程 -并发抢坑实测**（每进程最多重试 40 次），四组： - -| max | 抢到坑的进程 | 库里实际活跃 root run | 判定 | -|---|---|---|---| -| 1 | 1 | 1 | ✅ | -| 2 | 2 | 2 | ✅ | -| 3 | 3 | 3 | ✅ | -| 5 | 5 | 5 | ✅ | - -落选进程全部吃 `RunSlotBusyError`（各 40 次全被拒），零 `other` 错误。准入的四步缺一不可： -`BEGIN IMMEDIATE` → 事务内重读 → 事务内计数 → 同事务条件更新。 - -### 15.3 批 3 复核的 4 条遗留（本次修完） - -**N1 🔴 `cancelQueuedRun` 的前提被批 3 自己改没了** -它的注释说「对一条还没开跑、没有子 run 的排队 run，`stopRun` 是多余的一圈」—— -而 `requeueBlockedRootRun` 落地后，`queued` 的 run **可以是跑过一半的**（有 success 节点、 -有活着的子 run；预算撞顶时引擎只把 root 置 blocked，子 run 要到节点边界才落 paused）。 -探针实测：取消后节点残留 `ready`+`success`、子 run 残留 `paused / stop_requested=0` —— -**那条 running 的子 run 继续调 agent 烧 token**。改为无条件走 `engine.stopRun`。 - -**L1 ⚠️ 恢复路径对 manual 只兑现一半** -`graph-engine.js` 写着「『T1 永远回不来』这个后果因此消失」，但调度器 `filter(execution_mode === 'auto')` -故意不碰 manual → 人点「启动」→ 退回队列 → 坑空了 → **没人接**。 -定案：**「manual 不自动出队」约束的是首次起跑的授权**；一条已被人亲手起过、因坑满被退回队列的 -manual，授权早就给过了，让它自己接回来是**兑现人刚才那次点击**，不是新授权。 -判据用 **`attempt > 0`** 而不是 `started_at` —— 后者看着更贴切，但 `requeueBlockedRootRun` -退回队列时会把它清成 NULL，**恰好在需要它的那一刻是空的**（实测踩过）。 - -**N2 🟠「退回队列」对用户完全不可见** -`startRunSync` 早返回 200 + `{ok:true, requeued:true}`，而 `GraphRunPane.act()` 只在 `!r.ok` 时写 -`err` → 界面零提示；随后按钮全灰、run 面板换成定义视图、提示语说「节点状态一律 pending」（**假的**）。 -`requeued` 字段全前端零处读取。现加 `notice` 一行明说「已退回队列排队，坑一空会自动接着跑」。 - -**N3 🟠 `isSlotRaceError` 的判据被探针证伪** -注释称 `InvalidTransitionError` = 「已被别人从 queued 推走」。实测：被推走时条件更新 -**返回 0、不抛**；真正抛它的只有「**调用方声明了非法转换**」。那一支把调用方的 bug 当竞态吞掉 -且不留日志。已删除该分支（与批 4 删 UNIQUE 那支同一理由：让它吵起来）。 - -> **4 条里有 3 条是同一个模式：注释承诺的前提被本轮自己的改动改没了，注释还留着。** -> §十三.3 / §十四.4 已经就这个模式立过两次案，这是第三、四、五次。 - -### 15.4 一次流程事故：代码在复核完成前被第三方提交 - -`87b776c` 由另一个会话（`lemonboss-68`）在 16:56 提交，**而批 3 的对抗复核 17:00 才出结果** -（就是 §15.3 那 4 条）。提交说明里的「1201 用例全绿」准确描述了当时那次测试运行，但它压在一份 -尚未通过复核的代码上，读起来像质量背书。该会话已写交接文档 `27-p3c-batch3-handover.md` 并更正记录。 - -**教训**：多会话共用同一个 worktree 时，「工作区里的改动」不等于「可以提交的改动」—— -未提交本身可能就是一种状态声明（这里是「在等复核」）。提交前问一句的成本，远低于把一份 -已知有缺陷的代码写进 main 的成本。 - -### 15.5 留给下一轮 - -1. **边界守卫会误判并行会话的改动**：它比对整仓 `git status` 差集，那里面**没有「谁写的」这一维**， - 多会话共用 worktree 时必然把开发会话的改动算到当时在跑的图节点头上（实测已导致一条 run 被判 - `boundary_escape`）。批 3 修的是这条日志的**可见性**（列出文件清单），**误判本身没修**。 -2. **机器级闸门仍然不存在**：`SessionPool` 没有 `maxSessions`，`task-queue.js` 另有个 `MAX_CONCURRENT=3` - 抢同一台机器。批 4 只放开了公司级额度（硬上限 20），机器压不压得住没有任何守卫。 -3. 批 5（两套任务体系统一）未开工，预研方案已就绪。 - ---- - -## 十六、批 5 实施记录（2026-08-19/20，进行中） - -> 体例同 §十三～§十五。**本节随批 5 推进增量补写**，未做的步骤明确标出来。 - -### 16.1 进度 - -| 步 | 内容 | 状态 | -|---|---|---| -| 1 | `tasks` 表吸收 `executor` / `assignee_agent_id` / `parent_task_id` | ✅ `5cd91c3` | -| 2 | `system/tasklog/*.json` 回填进 `tasks` 表 | ✅ `514ec3d` | -| 3 | `/task/dispatch` 改写 `tasks` 表（**URL 与请求体一个字不动**） | ✅ `12880b8` | -| 4 | 30 分钟去重从「扫目录」改成一条 SQL | ✅ 同上 | -| 5 | `GET /api/tasks` 改读表；删 `TaskService.getAggregatedTasks()` 的会话反推 | ✅ `71cf45e` | -| 6 | 调度器只管 `executor='graph'` | ✅ 同上 | - -**批 5 完成，P3C 五批全部实施完毕。** 全量：**132 文件 / 1257 测试全绿**。 - -### 16.2 第 1 步踩到的：一个会让**所有存量库开不了**的顺序问题 - -第一版把 `CREATE INDEX ... ON tasks(assignee_agent_id)` 写进了建表块。**建表块整体先于迁移块执行**， -而存量库上 `CREATE TABLE IF NOT EXISTS tasks` 是 no-op —— 表还是批 4 的形态、没有那一列， -于是这句索引直接抛 `no such column`，`getDb()` 起不来。 - -**新建库完全正常**（单测默认走的就是这条路），所以只测新建库根本看不见这个洞。 -是专门去跑「批 4 形态的库重启一次」才撞出来的。索引已挪进迁移块、排在 ALTER 之后， -守卫见 `tasks-executor-migration.test.js`。 - -> 由此得到一条可复用的规矩：**凡是加列，必须同时测「存量库重启」这条路**。 -> 新建库的路径由每个单测天然覆盖，存量库那条没人走 —— 而生产上只有存量库。 - -已知不对称（写在代码注释里）：`ALTER TABLE ADD COLUMN` 加不了 CHECK 也加不了外键， -所以存量库上 `executor` 的取值域**只由应用层守**，与新建库的 CHECK 不同源。 - -### 16.3 第 2 步的关键判断：沿用原 `taskId` - -回填时**不新发 id**。理由是引用面：`conversations/task-{taskId}` 是目录名、汇报链路按 taskId -找回这条派单、summary 里互相引用。换 id 等于把这些引用全断掉，**而回填的目的恰恰是 -「别让历史消失」**。 - -`company_id` 落保留 id `_global`：tasklog 的行**没有 company 这一维**（`from`/`to` 都是本体 id）， -全局 agent 的会话本来就落在这个 id 下（28 §5.1）。刻意不去猜某条派单「其实属于哪家公司」—— -猜错会让它出现在错误的公司任务列表里，那比「都归 `_global`」更难发现。 - -实跑：4 条派单全部回填成功、零失败；再跑一次全部跳过、零新增。 - -### 16.4 第 3 步（下一步）的前提，动手前必须先核实 - -`POST /api/agent/task/dispatch` 与 `/task/report` 的 **URL 与请求体形态一个字都不能改** —— -它们印在 `packages/agent-core/base/common/tools-base.md` 里，是**所有 agent 的工具说明**， -改它等于同时改所有 agent 的提示词。 - -而 `server/routes/agent-chat.js` 在 2026-08-19 被另一个会话大改过（会话回收 / `IdleTimer` / -`CALL_KINDS` / 进程泄漏修复，见 `310a2b2` / `2092a2e` / `b0b2b62`）。**预研是在那之前写的**， -所以第 3 步动手前要重新读一遍现状，而不是照预研的描述改。 - -> 顺带记一处过期：`tools-base.md` 里印的是 `http://localhost:3000`，而实际端口是 **3010** -> （`server/config.js`）。已经真咬过人 —— 回填出来的派单正文里有人手写了「端口 3010，不是 3000」 -> 来纠正它。这一处该在第 3 步一起改（改的是端口不是契约形态）。 - -### 16.5 第 3 步（最危险的一步）怎么做到不碰契约 - -`/task/dispatch` 的副作用有九步，**只有第 ⑧ 步是「存储」**： - -``` -① 校验 from/to/task + 两个本体目录存在 -② 去重（30 分钟内同接收方 + 正文互相包含） -③ 推断 parentTaskId -④ 正文净化（\n →
，| → |） -⑤ 写目标 agent 的 todo.md -⑥ 写发送者的 plan.md -⑦ 更新 OKR 节点 → in_progress -⑧ saveTaskMeta(taskId, {...}) ← 只换这一步的内脏 -⑨ autoExecute → POST /api/agent/{to}/chat -``` - -**把 `saveTaskMeta` / `loadTaskMeta` 变成 tasks 表的适配器**，其余八步一行不动 —— -URL 与请求体形态天然不可能变。②③ 顺带从「扫目录」改成带索引的 SQL，**判据一个字没改**， -换的只是从哪儿把候选捞出来。 - -字段落点的三个判断： -- **`objectiveId` 不单独存**：它恒等于 okr node id 的首段（`OkrService.parseNodeId` 与 - `reportRunOutcome` 同一口径），且两处读取方都是 `if (objId && meta.nodeId)` —— 从不单独用。 -- **`sourceConvId` 删掉**：全仓零读取方。正是本文档 §九.4quater 立过案的「实现在、零调用方」， - 不往新表里再搬一份。 -- **`summary` / `execution_conv_id` 加列**（用户定案 A）：前者当前只写不读但语义清晰、界面迟早要它； - 后者有真读取方。**没有选「加一个 legacy meta 的 JSON blob 列」** —— §十二 引 R-19.2 明确否过 - 「建表而不是 JSON」，那会把一个已被否掉的形态重新引进来。 - -验证方式是**真起服务打一遍**，不是只看测试绿：照 `tools-base.md` 印的请求体原样 POST → 200 + -老形态响应；再打一次 → 409 且 `existingTaskId` 正确；`/task/report` 之后 `status→completed`、 -`summary` 与 `finished_at` 都在；`loadTaskMeta` 往返出来的形状与老 JSON 逐字一致。 - -### 16.6 第 5 步：删掉的是「猜」，不是「记录」 - -原 `getAggregatedTasks` 是 122 行的启发式：扫全部 agent 的 `conversations/`，按会话 id 里的 -`T-xxx` 归组，再用三条策略（meta 的 `parentTaskId` / from agent 的活跃会话时间包含 / -master conv 的标题相似）**猜**父子关系。猜出来的树没法验证对错，而且每次请求都要遍历所有 -agent 的会话目录 —— 路由那 10 秒缓存就是为它加的。 - -现在父子关系是 `tasks.parent_task_id`，派单时就显式写下来了。`task-service.js` **391 行 → 236 行**。 - -**`getTaskTimeline` 保留**，但来源拆清楚： -- 任务树（有哪些子任务）→ `tasks` 表，显式、可验证； -- 时间线正文 → agent 的 `conversations/`，那是**一手记录，没有替代品**。 - -两处口径变化（已写进代码注释）：`agents` 从「会话里出现过的 agent 集合」变成「谁派的 + 派给谁」； -`conversationCount` 从「扫出来的文件数」变成「有没有起过执行会话」（0/1）—— 为一个列表字段 -遍历所有 agent 的会话目录，正是这次要去掉的那笔开销。 - -### 16.7 两次「测试全绿 ≠ 没坏」 - -这一批里有两处只有**真跑**才会暴露的问题，测试一条都没红： - -1. **`routes/tasks.js` 漏改**：它自己还在算 `t.conversations.length`，而 `conversations` 是 - 会话反推那套的产物、已随之删除 → `GET /api/tasks` 直接 500。没有任何测试走那条路。 -2. **控制台 org graph 栏宽**（§十五 之外，`81629b7`）：320px 减去 padding 只剩 292px， - 而两个节点加一条边要 380px+ —— 节点名被从中间切断。构建、单测、探针全都不会报。 - -> 与之对照，§十六.2 那个「存量库一启动就炸」是**测试能覆盖但没人写**的类型。 -> 三者合起来是一条经验：**新建库的路径、纯逻辑的路径由单测天然覆盖； -> 「存量数据」「真实接口」「肉眼可见」这三类必须另外安排人去走一遍。** - -### 16.8 留给下一轮 - -1. `system/tasklog/` 目录**还在**（4 个历史文件，已回填进表）。按 §十二.5 应改名为 - `system/tasklog.bak-unify/` 而不是直接删，跑顺一个版本再清。本轮未做。 -2. `tools-base.md` 里印的端口仍是 `localhost:3000`，实际是 **3010**。已经真咬过人 —— - 回填出来的派单正文里有人手写「端口 3010，不是 3000」在纠正它。**改端口不改契约形态**， - 但它是所有 agent 的工具说明，值得单独一次改动 + 通告。 -3. `TaskTimeline.vue` 未动。它按字段名取值，本轮保住了全部 12 个字段，但 `agents` / - `conversationCount` 的语义变了（见 §16.6），界面上的措辞可能要跟着调。 diff --git a/docs/todo/system-design/27-requirement.md b/docs/todo/system-design/27-requirement.md index 93b0004..d273a43 100644 --- a/docs/todo/system-design/27-requirement.md +++ b/docs/todo/system-design/27-requirement.md @@ -563,7 +563,7 @@ git diff，最后 W13 只能把计数挪去另一个被 ignore 的文件。`file 统一还顺带修好两件事：30 分钟派单去重从「`readdirSync` 整个 tasklog 目录 + 逐个 JSON.parse」变成一条 SQL；两套同前缀不同源的 `T-` id 合一。 -**落点**：[27-P3C goal / task 两级模型](./27-p3c-goal-task-model.md)（本条派生出的工作项文档）。 +**落点**：[27-P3C goal / task 两级模型](../../done/system-design/27-p3c-goal-task-model.md)（本条派生出的工作项文档）。 --- diff --git a/docs/todo/system-design/28-followups.md b/docs/todo/system-design/28-followups.md index 9a77ceb..f6015eb 100644 --- a/docs/todo/system-design/28-followups.md +++ b/docs/todo/system-design/28-followups.md @@ -63,17 +63,26 @@ 只有设计，没有实现。任务目录 `system/agents/{aid}/{cid}/{taskId}/` 在源码树里无限增长。 **实现前必须先读主文档 §5.6b** —— 公司态是 dream 的原料，不是缓存，只能清任务态。 -### 3.3 `agent-chat.js:1209` 是心跳落点 bug 的第二个入口 +### 3.3 ~~`agent-chat.js` 是心跳落点 bug 的第二个入口~~ ✅ 已修（2026-08-20，`edeff2e`） `PUT /api/agent/:agentId/heartbeat`（前端 Agent 详情页走的就是它）用 `locator.bodyDir(parseAddress(id).agentId)` 把公司段丢掉，然后整份重写本体 `config.json`。 +后果是**静默无效**：公司态文件一旦存在，读侧优先取公司态，界面收到 `{success:true}` +而实际在跑的还是旧值；`GET /info` 同理报的是本体缺省。症状是「界面写 30 分钟、 +调度器按 15 分钟在跑」，两边都不报错。 -心跳落点已在 `company.js` 侧修好（写 `system/agents/{aid}/{cid}/heartbeat.json`）， -**但这个入口没改**，且因此多了一个新问题：公司态文件一旦存在，读侧优先取公司态， -于是这个端点的写入对该 (agent, 公司) 变成**静默无效**。 +读写都已改走 `heartbeat-service` 的 `readHeartbeatConfig` / `writeHeartbeatConfig`， +与心跳挂载读的是同一个答案；入参校验归服务（`intervalMinutes` 直接进 `setInterval`， +NaN / 0 / 负数会让定时器退化成每 tick 触发一次，而每次 tick 真起一轮 LLM），端点翻成 400。 -修法（一行级）：那段读改写换成 -`require('../services/heartbeat-service').writeHeartbeatConfig(req.params.agentId, req.body)`， -`GET :1203` 的 `heartbeat: config?.heartbeat` 同理换成 `readHeartbeatConfig`。 +**顺带修的一处**：404 闸门原来也用 `getBodyDir(id)`。`cid:role` 里冒号后面是**角色名**， +未必等于本体 id（`company_agents` 的映射）—— 拿角色名当本体 id 判存在性，凡是角色名 ≠ 本体 id 的 +都会被判成「agent 不存在」，而写侧其实找得到。**判 404 和写入必须问同一个问题。** + +守卫：`heartbeat-company-scoped.test.js` 补 3 例（反向验过，退回旧写法立刻红）。 + +> ⚠️ **一处没修，别当成修过了**：`GET /info` 的 404 闸门仍是 `getBodyDir(id)`， +> 对 `cid:role` 会直接 404。那是 `/info` 整体寻址的既有缺口（它还要按同一个目录读 +> `identity` / `agent.md` / `cron`），不在心跳这一条的范围内。测试里用裸 agent id 绕开。 --- @@ -95,12 +104,16 @@ ## 五、已经立起来的守卫（别重复造，也别删） -这几条是沉淀下来的不变式测试（前三条出自 agent 目录重构那一轮，第四条出自 27-P3C 批 1，第五、六条出自 CLI 进程泄漏那一轮）。 -**前四条**守的都是「同一个事实只能有一处持有者」，而且**六条都带「样本非空」前置断言** —— 少了那一条，扫描路径一写错就会以 -「零违例」的形式全绿，一条永远通过的不变式测试和没有这条测试是一回事。 +这几条是沉淀下来的不变式测试（前三条出自 agent 目录重构那一轮，第四条出自 27-P3C 批 1，第五、六条出自 CLI 进程泄漏那一轮， +第七、八条出自 27-P3C 收尾之后那一轮）。 +**第 1-4 条 + 第 8 条**守的都是「同一个事实只能有一处持有者」，而且**凡是靠扫描的都带「样本非空」前置断言** —— +少了那一条，扫描路径一写错就会以「零违例」的形式全绿，一条永远通过的不变式测试和没有这条测试是一回事。 -后两条形状不同：第五条守的是**资源生命周期**（每一条创建路径都要有对应的回收路径），判据不靠扫源码，而是把回收行为当黑盒去探； -第六条守的是**指路牌的有效性**（文档 / 清单里指向的东西必须真实存在）。列在一起是因为「别重复造，也别删」这条规矩对它们同样适用。 +另外三条形状不同，判据都不靠扫源码： +第 5 条守的是**资源生命周期**（每一条创建路径都要有对应的回收路径），把回收行为当黑盒去探； +第 6 条守的是**指路牌的有效性**（文档 / 清单里指向的东西必须真实存在）； +第 7 条守的是**运行期闸门本身**（起真子进程去撞，看撞不撞得动 —— 静态扫源码判不出「这个测试会不会开库」）。 +列在一起是因为「别重复造，也别删」这条规矩对它们同样适用。 | 测试 | 守什么 | 违例时 | |------|--------|--------| @@ -110,6 +123,8 @@ | `runs-root-single-holder.test.js` | 凡是把 `process.env.GRAPH_RUNS_DIR` 绑到标识符上的模块，那个标识符必须在**代码里**（不是注释里）真正被用到 | 精确点名到文件行号 | | `agent-chat-session-reclaim.test.js` | agent-chat 的 `sessions` 池：一次性 convId 的调用跑完必须回收，可复用的（pipeline / 人类对话）必须留下并受 TTL 兜底；顺带锁 `CALL_KINDS` 的标注 | 探针 `/chat/:convId/stop` 报告会话还在 | | `no-dead-path-references.test.js` | CLAUDE.md 的仓库路径与 npm run、package.json 的 scripts/bin/main、docs/README.md 的相对链接，四类引用都必须指向真实存在的东西 | 列出死引用的出处与目标 | +| `graph-db-prod-guard.test.js` | 测试进程不许打开共享生产库 `data/graph.sqlite`（判据在 `graph-db.getDb()` 的运行期闸门上，这条测试是对闸门本身的黑盒验证） | 子进程撞库时抛，报错点名 env 与「要在 require 之前设」 | +| `heartbeat-company-scoped.test.js` | 心跳设置是公司级状态，两个入口（`/api/company/...` 与 `/api/agent/...`）都不许落到共享本体上，且写完要能从读侧读回 | 本体 `config.json` 的 mtime / 内容变了，或读侧读回的不是刚写的值 | > 第四条的来历值得记：`goal-contract.js` 里曾有一行 `const RUNS_ROOT = process.env.GRAPH_RUNS_DIR || null`， > 注释白纸黑字写着「与 graph-engine.RUNS_ROOT 是同一个变量（测试隔离在用）」，**全文件却零引用**。 @@ -137,6 +152,17 @@ > 上下文里的相对片段（`_base/`、`todo/future/`）、glob、`/…` 示意写法一律不判。 > 宽一档就会把这些一起判红，防线于是被人整条注释掉。 +> 第七条的来历是**第四次踩「测试污染共享库」**，而且换了个方向进来。前三次 +> （`BENCHMARK_DB_PATH` / `USERS_DB_PATH` / `SKILLS_DIR`）都是「设了 env、生产代码不读」—— +> `test-isolation-env.test.js` 查的正是这个形态。这次那个用例**一个字都没设**， +> 于是那条守卫没有可查的东西，`/task/dispatch` 每跑一次往生产库落 2 条 goal + 2 条 task， +> 攒到 22 条才被人翻库发现。 +> +> 静态扫源码判不出「这个测试会不会开库」（要跨 require 链推导），所以这一条改成 +> **运行期闸门 + 对闸门本身的黑盒验证**：起一个真子进程去撞，看撞不撞得动。 +> 判据里特意留了「没有 VITEST 时不生效」那一例 —— 少了它，闸门写成「永远不许开 +> `data/graph.sqlite`」也会全绿，而那会把生产一起锁死。 + **改动它们之前先想清楚**：这几条的价值全在于「红了才有用」。 放宽判据、加例外、或者把断言改成永远成立的形式，等于把守卫拆掉 —— 本仓库有过「隔离是表演」的测试污染前科。 -- libgit2 0.21.4