From 7aa2d0dab96813a555638cbcd01507f656b7ea07 Mon Sep 17 00:00:00 2001 From: yibo Date: Mon, 31 Aug 2026 00:27:46 +0800 Subject: [PATCH] docs: 39/42 号文档移进 done/，索引同步（4 个 phase 全部完工） --- docs/README.md | 4 ++-- docs/done/system-design/39-boss-agent-task-supervision.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/42-org-work-graph-reliability-followups.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/system-design/39-boss-agent-task-supervision.md | 218 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/todo/system-design/42-org-work-graph-reliability-followups.md | 130 ---------------------------------------------------------------------------------------------------------------------------------- 5 files changed, 350 insertions(+), 350 deletions(-) create mode 100644 docs/done/system-design/39-boss-agent-task-supervision.md create mode 100644 docs/done/system-design/42-org-work-graph-reliability-followups.md delete mode 100644 docs/todo/system-design/39-boss-agent-task-supervision.md delete mode 100644 docs/todo/system-design/42-org-work-graph-reliability-followups.md diff --git a/docs/README.md b/docs/README.md index c0b3c25..4a0d8f5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,6 +35,8 @@ | [system-design/33-needs-gate-role-filter-bug.md](./done/system-design/33-needs-gate-role-filter-bug.md) | ✅ **已修复**。`executor.json`/`executor-fanout.json` 里 `produces:["log"]` 声明了一个 test/integration 类节点永远不会被索引到的 kind，导致 `org-coder-validator` 被 `missing_required_input` 反复误判 blocked；改成 `required:false`（对齐 `validator.json` 既有写法）。文档记录了一条**走过的弯路**（按 role 过滤 `inboundContracts` 会削弱 T-mt25ecbd 的产出闸门，已撤回），发现于 31 号文档的真实回归验证过程中，与兜底边问题无关 | | [system-design/35-validation-rigor-and-body-readiness-proposal.md](./done/system-design/35-validation-rigor-and-body-readiness-proposal.md) | 📝 **复盘 + 改进方案，四条提案全部已实施**。承接 31/32/33/34 号的复盘结论：任务结果差主要是架构问题（完整性闸门 `missingBodyDefinition` 只在招聘时查、图执行侧完全没有第二道防线——新发现）+ 一个具体的招聘装配可靠性 bug，不是 agent 能力问题。提案 A：本体不完整时图执行前置判 `fail_reason=body_not_ready`，不扣预算。提案 D：`goal-contract.js` 的 `evidence_hint` 命中浏览器类关键词的维度必须有证据支撑，否则判不过。提案 C：新增 `scripts/visual-acceptance-check.mjs` 复用检查工具。提案 B：控制台「验收证据」小节展示每个维度有没有证据支撑 | | [system-design/40-agent-chat-streaming-interrupt.md](./done/system-design/40-agent-chat-streaming-interrupt.md) | ✅ **已实现**（commit `4d23f50`，2026-08-30）。回应"前端刷新不及时/没有打字机效果，要不要把 SSE 换成 WebSocket"——排查后结论是传输层不是瓶颈（对照 hermes-webui/hermes-agent/deepseek-harness 三个参考实现，全部走 SSE，不用 WebSocket）。三个独立缺口全部补上：① 打字机不流畅→后端按字符数切片 + 前端 `createTypewriterQueue` 匀速吐出；② 执行中无法打断并接上新消息→`stop` 端点改轮询确认锁真正释放，前端据此直接发送/强制发送兜底，顺带修了服务端对同 convId 并发缺闸门这个真实 bug；③ 串台加固→`handleEvent` 抽成纯函数并补齐 `9b1c3f1` 那条不变式的回归测试。已用真实 Claude CLI 会话在浏览器验证 | +| [system-design/39-boss-agent-task-supervision.md](./done/system-design/39-boss-agent-task-supervision.md) | ✅ **P1-P5 全部已实现**（2026-08-30，`a00590a`/`5108d67`/`d967ac0`/`14cbaf5`）。boss agent（复用 `ceo`）监督 goal/task 看板闭环：draft task 回写、事件驱动+低频兜底唤醒、独立任务看板页、公司级 `target_dir`。**真实端到端测试**（建公司→下 goal→跑出一个 Playwright 5/5 验证通过的贪吃蛇游戏）撞出并记录了三个单测没覆盖的真问题，见文内「七、真跑复盘」；沉淀的待办已在 [42-org-work-graph-reliability-followups.md](./done/system-design/42-org-work-graph-reliability-followups.md) 全部收口 | +| [system-design/42-org-work-graph-reliability-followups.md](./done/system-design/42-org-work-graph-reliability-followups.md) | ✅ **Phase 1-4 全部已实现**（2026-08-30，`6ae1f76`/`2a60fe1`/`ae7650e`/`2a0ffb8`）。39 号文档真跑复盘沉淀的四 phase 可靠性收尾：① 卡住恢复闭环（服务器重启僵尸节点检测 + 强制判失败端点）② `ceo` 自建 task 的闸门穿透性回归测试 ③ `target_dir` 的 API/UI 配置入口（Phase 3 前端缺一次真实浏览器点击验证，见该节说明，是唯一已知缺口）④ `timeline.ndjson` 承接 planning/reflection 轨迹——`--artifact` 路径本身编码 `rootRunId`/`nodeRunId`，不用改任何 agent.md 或塞新环境变量 | ## todo/（当前主线） @@ -54,8 +56,6 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d | [28-followups.md](./todo/system-design/28-followups.md) | 28 号（Agent 注册表统一）的遗留清单 — 主文档已在 `done/`，这份装没做完的：dream 机制（设计见 29 号，已实现，见下）、`source_kind`（✅已删）/`legacy_path`（不能删）删列、三项「已实施未验证」。任务态清理（✅已实现，见下）。§五 是**已立起来的守卫清单**（别重复造，也别删） | | [30-task-delegation-reliability-gaps.md](./todo/system-design/30-task-delegation-reliability-gaps.md) | **任务委派可靠性现状**— 📝 调研记录，非设计方案。DevLoop `runUnit`、Company 招聘装配、Graph 执行三条链路核对结论一致：都是「失败预算耗尽 → 停等人工」，没有「卡住了主动通知人」这一层；DevLoop 当前还默认走 mock，真实 CLI 成功率无实证数据。2026-08-23 追加真实实例并已修：`infra_flake` 原地重跑没有熔断线，真撞上过一次确定性死循环（节点把诊断结论误判成自己的执行结果，反复重跑却从不路由到诊断建议的目标节点）；已加 `infra_flake_count` 列 + 硬顶 3 次熔断，连续判 infra_flake 超过硬顶就改判 blocked 交给人工 | | [31-work-graph-fail-fallback-coverage.md](./todo/system-design/31-work-graph-fail-fallback-coverage.md) | work graph 兜底边覆盖不全 — ✅ 已完成（除入口节点外强制兜底边，`planner.json`/`executor-fanout.json` 补 6 条边），978/978 单测通过；2026-08-21 又用真实 LLM 起了一条新任务做端到端回归验证，`org-planner-sdd` 自判失败后自动打回 `org-planner-prd`（3 次，零人工介入），修复确认生效 | -| [39-boss-agent-task-supervision.md](./todo/system-design/39-boss-agent-task-supervision.md) | ✅ **P1-P5 已实现**（2026-08-30，`a00590a`/`5108d67`/`d967ac0`/`14cbaf5`）。boss agent（复用 `ceo`）监督 goal/task 看板闭环：draft task 回写、事件驱动+低频兜底唤醒、独立任务看板页、公司级 `target_dir`。**真实端到端测试**（建公司→下 goal→跑出一个 Playwright 5/5 验证通过的贪吃蛇游戏）撞出并记录了三个单测没覆盖的真问题，见文内「七、真跑复盘」；沉淀的待办见 [42-org-work-graph-reliability-followups.md](./todo/system-design/42-org-work-graph-reliability-followups.md) | -| [42-org-work-graph-reliability-followups.md](./todo/system-design/42-org-work-graph-reliability-followups.md) | 📝 **Phase 1 已实现，Phase 2-4 待开工**（Phase 1：卡住恢复闭环——僵尸节点检测 + 强制判失败端点，`6ae1f76`）。39 号文档真跑复盘沉淀的四 phase 可靠性待办：卡住恢复闭环 → `ceo` 自建 task 的闸门穿透性回归测试 → `target_dir` 的 API/UI 配置入口 → `timeline.ndjson` 承接 planning/reflection 轨迹（结构性改动，排最后） | | [41-graph-vs-fde-reliability-discussion.md](./todo/system-design/41-graph-vs-fde-reliability-discussion.md) | 📝 **讨论记录 + 落地实测，非设计方案**。org/work graph 与 master-Innovator-FDE 两套工作流的稳定性对比：根因是"拓扑运行时生成 vs 写死"。问题 7 是真实执行记录——新建 `org-hunt/digest/evolve`（graph 原生协议，方法论抄 innovator-hunt/digest/evolver）跑 Hunt→Digest→Evolve，11 轮真跑中挖出并修复 5 个独立缺陷（建公司自动规划竞态、work-graph 模板库缺内容型交付物骨架、验收节点任务描述越权、两个规划 agent 的路径口径写错、R-19 产出索引 `indexNodeOutputs()` 不覆盖项目根——最后一条改了 `graph-engine.js` 核心逻辑，加 `contract.json` 的 `produces` 显式声明机制，全局生效，补了 2 条守卫测试）。最终产出与原生 FDE（`prd-methodology-trial`）对比：内容骨架可迁移、质量不打折，但过程严谨度不如原生 FDE，可靠性差距悬殊（原生一次跑通，graph 版 11 轮才稳定）。`routeFailure` 的 `infra_flake` 分支绕过跨层寻址（`target_node`）仍是唯一确认还没补的口子 | | [37-org-graph-department-scoping.md](./todo/system-design/37-org-graph-department-scoping.md) | 📝 **设计讨论，调用点扫描已完成，尚未立项实现**。现状 org graph 按 `company_id` 单例（`27-P2` 标题原文即"公司级"），塞不下 HR/财务/市场这类跟"交付流水线"无关的公司常设职能——`system/agents/hr/`（"招·留·管·退"）本体已存在却从没被装进任何图，全靠 fire-and-forget chat 招聘、无图执行审计轨迹。提议把 org graph 作用域从 `company_id` 升级为 `(company_id, department_id)`，一家公司可装配多张部门图，每张仍保持人工固定/慢变/可审计。全仓库调用点扫描结论：改造面是最初估算的 4 倍——真正的单点真相在 `work-graph-db.js:readDefGraph` 的裸 SQL 不变式（不在服务层），还牵涉两个易混淆服务文件间必须字节级一致的重复唯一索引、独立的 `graph-seed-service.js` 对账子系统、`company-hire-org-layer.test.js` 专属测试、`orggraph-planning`/`task-planning` 两份 agent 人设文档的自我认知改写 | | [36-prd-agent-methodology-training-feasibility.md](./todo/system-design/36-prd-agent-methodology-training-feasibility.md) | 📝 **调研 + 阶段一/二均已完成**。回应"落地页太单薄是不是该用 Innovator 先训练专业 agent、再用 Dream 持续迭代"——认同方向。**阶段一**：`graph-engine.js` 结算节点后把 `success`/`fail:` 写进本体 `memory.md`（此前只有人类对话路径会写，Dream 天天空转）。**阶段二**：新建独立试验节点 `prd-methodology-trial` 走真实 Hunt→Digest→Evolve，2 轮收敛（96/97 分，真实基线 50 分），三个真实历史项目反推验证方法论有效；过程中连带修复同一个 2026-08-16 改名批次遗留的 5 处 `innovator`→`org-innovator` 死链（后端两处硬编码、前端"重新训练"按钮、`/api/agent/list` 展示 id 来源的四个 `config.json`），以及 `AgentScaffold` 默认模板一处裸相对路径缺陷。结论：FDE 对方法论类角色确实管用，但收敛速度/验收严谨度依赖任务书显式写明的自纠正要求，非免人工黑盒。环节 3（训练产物 → 雇佣本体转换）尚未开工 | diff --git a/docs/done/system-design/39-boss-agent-task-supervision.md b/docs/done/system-design/39-boss-agent-task-supervision.md new file mode 100644 index 0000000..afbfae8 --- /dev/null +++ b/docs/done/system-design/39-boss-agent-task-supervision.md @@ -0,0 +1,218 @@ +# 39. Boss Agent 任务看板监督 + 公司目标代码目录 — 需求评估与设计草案 + +> **状态**：✅ P1-P5 已实现（2026-08-30，commit `a00590a` P1/P3/P4 后端、`5108d67` P2 前端、`d967ac0` P5、`14cbaf5` graph-run.js 鉴权补丁）。本文档是落地前的设计草案，实现细节以代码为准，仅存档决策过程。**已知未覆盖的后续工作见「六、已知遗留」，真实端到端跑测的复盘见「七、真跑复盘」，复盘沉淀的待办已拆成独立文档 [42-org-work-graph-reliability-followups.md](./42-org-work-graph-reliability-followups.md)（按 phase 排开工顺序）**。 +> **日期**：2026-08-30 +> **背景**：承接对话讨论——goal/task 两级模型（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md)）已落地，但推进它的是纯确定性代码（`task-scheduler.js` + `transitionRun` 钩子），没有任何 agent 在持续监督这块看板、处理异常、把执行中发现的新问题回写成新任务。用户提出五阶段方案补上这一层，并追加公司级目标代码目录需求。 +> **读者须知**：本文档大量引用现有代码路径核实"已有 vs 缺失"，结论以文内给出的具体函数/文件为准；这些引用会随代码演进过期，落地前请重新核实。 + +--- + +## 一、先说结论 + +用户的五阶段里，**P2（任务看板）本质已完成，P1/P3 的基础设施已有大半，P4 是真正的新增核心，P5 的机制已经实现了 70%，只是没有暴露到公司层面。** 真正从零开始的工作量比五个"phase"暗示的要小得多，但顺序建议大改：**P4（回写闭环）应该提到最前面**，因为它才是这次讨论最初的诉求（"自己发现问题、自己重新规划"），P1/P3 的 boss agent 只有在 P4 的工具/数据通路建好之后才有事可做。 + +| 用户的 phase | 名义工作量 | 实际现状 | 建议 | +|---|---|---|---| +| P1 雇佣通用 boss agent | 新建一个角色 + 训练 | 心跳基础设施、`ceo` 本体、Innovator 训练方法论**全部已有** | 复用 `ceo`，不新建角色；工作量收窄成"写 heartbeat.md + 工具" | +| P2 任务看板独立页面 | 一个新系统 | goal/task 两级看板**已实现**（`GoalTaskPane.vue`），只是嵌在控制台里 | 降级成 UI 改造，非必须，可排最后 | +| P3 心跳挨个决定下一个 task | 新的调度逻辑 | 挨个执行**已经是** `task-scheduler.js` 在做，且做得更好（事件驱动、零成本、已测试） | **不要重建调度**；心跳的职责收窄为"异常判断"，且应事件触发而非纯轮询 | +| P4 bug/新任务回写看板 | 一条新闭环 | **不存在**——没有任何 agent 可读写 goal/task 板的工具，四分类失败归因（30 号文档）目前只导向"重试或人工介入"，不导向"开新任务" | **真正的核心工作，优先做** | +| P5 公司目标代码目录 | 新能力 | DevLoop 的 `path-resolver.js` 已实现 `sandbox` / `linked-new` / `linked-existing` 三种模式，**`linked-existing`（接管已有目录）已经是完整实现**，只是没有公司级默认值，也没打通到 org/work graph（非 DevLoop）路径 | 补一个公司级默认配置 + 核实非 DevLoop 路径是否需要同样机制 | + +--- + +## 二、逐 phase 现状核实 + +### P1：每个公司雇佣 boss agent，system agent 层训练通用版本 + +**已有的基础设施**（全部实地核实过）： + +1. **通用心跳机制**：`server/services/heartbeat-service.js`。状态落在 `system/agents/{aid}/{cid}/heartbeat.json`（公司态目录，不是共享本体——这条边界是踩过坑之后加的，见文件头注释），本体 `config.json.heartbeat` 只是只读默认建议间隔。`_triggerHeartbeat()` 按 `setInterval` 定时给 agent 发一条 `[SYSTEM HEARTBEAT]` 系统消息（走正常的 `/api/agent/{agentId}/chat`），要求 agent "**根据你的身份和 heartbeat.md 规则**……如果一切正常，无事发生，请直接回复『心跳正常』"，带 30 分钟会话互斥防重叠。**这套机制现成可用，不用重建。** + - ✅ **修正一处之前的误判**：原以为 prompt 里"扫描全局 OKR 目标状态和节点"那句硬编码需要改代码才能适配新 goal/task 模型。查了 `system/agents/` 下已有 **35 个**本体带 `heartbeat.md`（如 `org-innovator/heartbeat.md`），内容五花八门、完全跟 OKR 无关，说明触发消息里那句"扫描 OKR"从来就只是**默认示例文案**，各 agent 早就按自己 `heartbeat.md` 里写的规则各干各的。**结论：`heartbeat-service.js` 大概率零改动**，只需要新建 `system/agents/ceo/heartbeat.md`，写清楚"去查 goal/task 板、按 §四.9 的规则判断"，agent 读到自己的 `heartbeat.md` 就会照着做，不需要动服务端代码。落地时找一个现有 `heartbeat.md` 生效的真实案例复核一次这个推断，再动手写 `ceo` 的那份。 +2. **本体已存在**：`system/agents/ceo/`（`type: "cxo"`，"Chief Executive Officer"，`heartbeat.enabled: false` 默认关）。同时存在 `system/agents/master/`（`type: "master"`，**全局唯一**，`/api/master/chat`，负责建公司/招聘等跨公司操作）。两者定位不同：`master` 是平台层面的单例助手，`ceo` 才是"每个公司一个"的角色。 +3. **训练方法论已验证**：`36-prd-agent-methodology-training-feasibility.md` 已经用 Innovator（Hunt→Digest→Evolve）训练出过一个方法论型 agent（`prd-methodology-trial`），2 轮收敛、96/97 分，方法论对这类"判断型"角色确实管用。可以照搬这条路径训练 `ceo` 的监督方法论，而不是手写一份 prompt 拍脑袋。 + +**结论**：不建议新建"boss"角色。**复用 `system/agents/ceo/`**——它的岗位定义（CEO）本来就该管"任务有没有卡住、要不要重新分解"，另起一个语义重叠的角色只会重犯这个仓库反复踩过的"名字歧义"坑（`27-naming-conventions.md` 通篇在防这个）。P1 的实际工作量是：① 给 `ceo` 补一份 `heartbeat.md`（监督规则）；② 给它挂上 P4 需要的工具（见下）；③ 默认 `heartbeat.enabled: true`（但见 P3 的成本讨论，建议先不无脑轮询）；④ 可选：用 Innovator 训练它的监督方法论。 + +**缺口 A**：目前**没有任何 agent 工具能读写 `goals`/`tasks` 表或操作 graph run**（搜了 `server/src/tools/` 全目录，零命中）。`ceo` 就算被唤醒也无事可做——这是 P1 能不能生效的真正前提，见 P4。 + +**缺口 B（新发现，之前漏了）：`ceo` 现在没有被雇进任何公司，`hire()` 也没有任何自动触发点会调它**。查了 `hire(companyId, roleName)`（`company-service.js:422`）——它只查本体目录 + `company_agents` 表，**不查 org graph**，机制上雇一个不在图里的角色完全没问题（数据模型层面，"雇了"和"进图"是两件独立的事）。但目前**没有任何代码路径会主动调 `hire(companyId, 'ceo')`**——它不在三份 org-graph-templates 里，也没有类似 `orggraph-planning` 那样的自动招聘钩子替它兜底。`37-org-graph-department-scoping.md` 里记录过一模一样的处境：`hr/` 本体"已经真实存在……只是从没被装进任何图……今天完全是编外人员"——`ceo` 现在是同款处境，**不是有先例可抄，是同一个坑还没人填**。P1 必须显式加一步：① 公司创建流程里（不管选哪个 org-graph-template）固定 `hire(companyId, 'ceo')` 一次；② 存量公司需要一次性回填脚本，遍历现有公司补雇。这条不做，前面说的"复用 ceo"就是一句空话——压根没有 `ceo` 实例在跑。 + +--- + +### P2：任务看板独立页面 + +**已实现**（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md)，✅ 2026-08-20）：`web/src/components/graph-console/GoalTaskPane.vue` + `goal-task-model.js`，挂在 `/:companyId/graph-console` 左栏。goal/task 两级状态、优先级排队位次、颜色语义全部已有，REST 是 `server/routes/company.js` 的 `GET/POST /api/company/:cid/goals` 系列。 + +**用户要的"独立页面"** 目前是控制台的一个侧栏，不是路由级独立页面。这是纯 UI 改造，**不涉及数据模型或后端**，随时可做，风险最低。 + +**"subtask" 层**：当前**没有独立的 subtask 表**，`task` 就是看板能管理的最细颗粒度。task 再往下是 `graph_runs`（work graph 节点，可能含嵌套子图），这层在中间的执行画布（`WorkGraphCanvas`）里看，不在左栏。 + +> ⚠️ **不建议新增一张 subtask 表**去对应 work graph 节点。这个仓库已经因为"两套任务体系不统一"吃过至少两次苦头（P3C §十二"批 5"整章在处理这个债，`27-p3c-batch3-handover.md` 也记过一次事故）。如果要在看板上展示"这个 task 内部具体在跑哪几步"，应该是**只读地把该 task 当前 `current_run_id` 对应的 `graph_run_nodes` 渲染成一份"子步骤列表"**，复用现有表和现有执行画布的数据源，不新建写路径。 + +#### P2 决定：与 OKR 页面的关系（已拍板，2026-08-30） + +排查发现现状比预期乱：**OKR 相关 UI 现在有两份几乎逐行相同的重复实现**——`web/src/views/OkrDashboard.vue`（路由 `/okr`，`requireAdmin`，零导航入口的孤儿页面）和 `CompanyDashboard.vue` 里挂着 "goals" 名字、实际渲染 "Goals (Full OKR Tree)" 的 tab——两者都是旧 OKR 树（`O-xxx`，owner + progress%），是"OKR 正名"（`27-naming-conventions.md` §六）前端没跟着改完的遗留物，前端两处都调 `/api/okr/*`，和 P3C 的新 goal/task 模型完全不是一回事。 + +**已拍板**：**不合并**，OKR 这套前端 UI**直接废弃**，新任务看板**另起一个独立页面**。具体动作： + +1. **新增路由**：仿照 `GraphConsole` 已经立好的先例（`/:id/graph-console` 是独立路由，不挤在 `CompanyDetail` 的 `:tab(...)` 白名单里），新增 `/:id/task-board`（命名待定）→ 新建 `web/src/views/TaskBoard.vue`。**不要塞进 `:tab(...)` 正则**，理由与 `graph-console` 当年的注释一致：任务看板信息密度高，值得一个整页。 +2. **复用现有逻辑，不重写数据层**：`GoalTaskPane.vue` + `goal-task-model.js` 现在已经封装了 goal/task 的状态映射、排序、颜色语义（且有专门的单测 `goal-task-model.test.js` 兜底）。新页面应该是把这个组件从 `GraphConsole` 的侧栏布局里"拔出来"放大铺满整页，**不是重新实现一遍**。`GraphConsole` 侧栏可以保留一份精简版（点某个 task 仍需跳转去看它的执行图），也可以改成跳转链接指向新页面——两种都行，实现时再定。 +3. **废弃 OKR 前端**：删 `/okr` 路由 + `OkrDashboard.vue`；删 `CompanyDashboard.vue` 里那个挂着 "goals" 名字实为 OKR 树的 tab；路由 `:tab(...)` 白名单里的 `goals`/`okr` 两个值一并摘掉，避免留死链接。 +4. **导航入口**：新页面必须挂真实导航入口（`AppNav` 或公司详情页的显眼位置），不能重蹈 `/okr` 那种"孤儿页面"的覆辙。 +5. **鉴权**：`okr.js` 当年挂 `requireAdmin` 是因为它是孤儿页面、没做归属校验的权宜之计（`38-auth-multi-tenant-isolation.md`），**不是"任务看板天生该管理员专属"**。新路由要按 `company.js` 等其他公司级路由的标准做法，走 `canAccessCompany` 归属校验，不能照抄 `requireAdmin`。 + +**范围之外、本次不动**（留作独立的后续决定，不在这次 P2 改造里顺手做）：`/api/okr/*` 后端路由、`okr` 相关 SQLite 表、`goals.okr_node_id` 这个可选外键字段——前端 UI 废弃不等于后端子系统也要一起拆，那是一次单独的、影响面更大的退役决定（牵涉数据迁移/存量数据处理），需要单独评估，这里先只处理前端。 + +--- + +### P3：心跳挨个决定下一个 task + +**这条按用户原话实现是在重建一个已经存在、已经测试、且更优的系统。** `task-scheduler.js` 的队列排序口径是 `priority → seq → created_at`（`ORDER BY priority, seq, created_at`），出队靠 `transitionRun` 这个唯一漏斗事件触发，不是轮询；v1 约束 `max_parallel_tasks`（`company.json`，缺省 1）决定"挨个"还是"并发几个"，`server/tests/unit/task-slots-parallel.test.js` 覆盖了 >1 的情况。这套机制零 LLM 成本、毫秒级触发、已经过多轮真实回归验证（`31-work-graph-fail-fallback-coverage.md` 的真实 LLM 端到端案例）。 + +**成本账**：`heartbeat-service.js` 现在的实现是**每一次 tick 都真的发一次 LLM 调用**，只是 prompt 要求"没事就回复 `[心跳正常]`"——省不了那次调用的 token/延迟。如果 N 家公司、每家每 5 分钟一次心跳，24 小时就是 N×288 次 LLM 调用，绝大多数只会换回一句"心跳正常"。 + +**修订建议**：boss agent 心跳**只负责调度器处理不了的判断题**，而且触发方式改成"事件优先、轮询兜底"，不是纯定时轮询： + +1. 判断题清单（调度器管不了、需要 LLM 判断的）： + - task 长时间 `blocked` 或 `failed`（预算耗尽/依赖死锁）——要不要重新分解、要不要升级给人类； + - 同一 goal 下多个 task 出现优先级冲突（业务变化导致原定顺序不再合理）——要不要调整 `priority`； + - `task-planning` 3 轮降级成单任务（P3C §四.9 的降级路径）——要不要人工介入重新审视这条 goal 的描述。 +2. **优先事件驱动**：在 `transitionRun`/`settleGoal` 这类既有钩子里，遇到上述判断题触发的状态变化（比如 task 转 `blocked`）时，**主动**唤醒 `ceo` 处理这一条，而不是让它等下一次心跳才发现。心跳退化成**低频兜底**（比如 30 分钟一次，只扫"有没有钩子漏掉的异常"），不是主决策路径——这与现有 `task-scheduler.js` 头部注释里"兜底扫描周期"的设计哲学完全一致，照抄这个模式即可。 + +--- + +### P4：org/work graph 产生的新 bug / 新 task 回写看板，形成闭环 + +**这是五个 phase 里唯一真正从零开始、也是这次讨论最初诉求（"自己发现问题、自己重新规划"）真正要落地的地方。** + +**现有的失败归因机制**（`30-task-delegation-reliability-gaps.md`）：`BugTriager`/`validator-triager` 类节点已经在做四分类——`contract_mismatch` / `impl_bug` / `spec_ambiguous` / `infra_flake`——但**四条路径的终点目前都是"原地重试"或"预算耗尽后 blocked 等人工"**，没有一条走向"生成一条新 task/goal"。 + +**需要新增的两个通路**： + +1. **确定性通路（不需要 agent 判断）**：把四分类里"显然该开新任务"的情形直接在 `routeFailure`（`graph-engine.js`）里接一条规则，而不是等 boss agent 心跳才处理——比如 `spec_ambiguous` 在 goal 级预算内重试超过阈值，直接生成一条 `status='draft'`、`created_by='system'`、挂在同一 `goal_id` 下的新 task，附上失败节点的诊断产物作为新 task 的 `description` 素材，人工/`ceo` 再审。这条不需要 LLM 判断"要不要开新任务"，只需要判断"开一条什么样的"——后者才是可选的 agent 介入点。 +2. **主观通路（需要 agent 判断，这是 P1 的 `ceo`/工具的用武之地）**：agent 在执行任务过程中发现的、**不在当前 task 描述范围内**的问题（比如 coder 顺手发现一个无关的历史 bug），需要一个**工具**让它"提一条新任务"而不是把不相关的修复硬塞进当前 task 的产物里。这是当前完全没有的能力。 + +**必须先建的地基**——查完代码，发现比"包一层工具"更底层的东西还没有，得先排清楚三件事，顺序不能反： + +#### 地基 0（阻塞项）：`ceo` 现在物理上调不通这套 REST API + +`server/src/tools/tool-registry.js` 开头写得明明白白——**这是"Master Agent 工具注册中心"**，`[TOOL_CALL: xxx]` 这套 JSON 文本协议是 Master 专属的自定义解析层，`server/src/tools/devloop/` 下另有一套 DevLoop 专属的 tool-registry。`ceo` 这类普通 org node agent（走标准 Claude CLI 子进程）**两套都不属于**——它能用的只有 Claude CLI 原生的 Bash/curl，具体调用哪个接口靠 `tools.md` 里的**大白话 + curl 示例**（`task-planning/tools.md` 就是这个写法的范本）。所以"task-board-tools.js" 这个提法本身**不成立**——不需要新写一个 JS 工具模块，需要写的是一份 `system/agents/ceo/tools.md`（现在是空文件）。 + +但更麻烦的是：`server/routes/company.js` 顶部 `router.use(requireAuth)`（14 行），**goals/tasks 全系列端点只认人类 JWT**，没有走 `agent-chat.js` 那样的 `requireAuthOrInternal`。也就是说，就算 `ceo` 的 `tools.md` 写得再clear，它发出的每一条 curl **现在都会静默 401**——这正是最近几个 commit（`d48425a` selfChat 自环漏带内部令牌、`9e58656` bin/lemon.js task report/dispatch 401）反复修的那一类坑，company.js 这次还没打这个补丁。**这是全部 P4 工作的前提阻塞项**，必须先给 goals/tasks 这组路由加上 `requireAuthOrInternal`（或者更收紧一点，只给这几条挂内部令牌白名单），agent 才有物理上调得通的可能。 + +#### 地基 1：`POST /:companyId/tasks` 没有"草稿"模式，agent 提的任务会立刻烧预算 + +现有 `POST /:companyId/tasks`（`company.js:2077`）建完 task 行**无条件紧接着调 `enqueueTaskRun` + `startNextIfSlotFree`**——语义是"下达即执行"，服务的是"人类/外部 agent 派工"这个存量场景（代码注释原话："存量调用方的心智是下达即执行"）。这条路径不适合 `ceo` 自主提的新任务：`task-planning` 拆出来的 task 尚且要先落 `draft`、人点"全部下达"才转 `queued`（P3C §四.9 的既定哲学——"一次 LLM 猜测直接烧 5 份预算"是要避免的事），`ceo` 一次判断失误直接把新任务怼进队列烧钱，风险比 task-planning 更高（task-planning 只在 goal 刚建时跑一次，`ceo` 是持续在线判断）。 + +**需要的改动很小**：给 `POST /:companyId/tasks` 加一个 `draft: true`（或 `status: 'draft'`）入参，为真时只调 `wdb.createTask()` 落库，跳过 `enqueueTaskRun`/`markGoalDispatched`/`startNextIfSlotFree` 三步，返回 `status: 'draft'`。已有的 `POST /:companyId/tasks/:taskId/enqueue`（`company.js:2275`，`draft → queued`）原样复用，不用新建。默认行为（不传这个参数）完全不变，纯加法，不影响存量调用方。 + +#### 地基 2：`ceo` 的 `tools.md` 写什么 + +在地基 0/1 落地后，照抄 `task-planning/tools.md` 的写法（先说"大概率不需要工具"、给出何时才用、给出 curl 示例、专辟一节"你不该用的工具"防止越权）给 `ceo` 写一份，覆盖： + +- **读**：`GET /:cid/goals?status=active`（扫哪些 goal 在跑）、`GET /:cid/tasks?status=blocked` / `?status=failed`（找卡住的）、`GET /:cid/goals/:goalId`（看某 goal 下全部 task + run 摘要） +- **写**：`PATCH /:cid/tasks/:taskId`（改 `priority`）、`POST /:cid/tasks`（带 `draft:true`，提新任务）、`POST /:cid/tasks/:taskId/enqueue`（把自己或别人提的草稿正式下达——这一步要不要也留给人类点，是个开放问题，见 §四） +- **明确不该用**：`org-graph/replan`、招聘类端点（这些是 HR/`orggraph-planning` 的事，`ceo` 判断"缺角色"之后应该是发通知/提 task，不是自己动手改组织结构） + +#### 确定性通路（routeFailure 里那条规则）不走这套 REST + +30 号文档四分类里"显然该开新任务"的情形（比如 `spec_ambiguous` 重试超阈值），是 `graph-engine.js` 服务端内部代码，**直接调 `wdb.createTask()`**（同进程函数调用），不必经过 HTTP、不必带内部令牌，落库同样是 `draft`。这条通路和 `ceo` 的 agent 通路是并行的两条腿，共享同一个"落 draft、不自动下达"的规则，但触发方式不同（一个是引擎钩子里的确定性规则，一个是 agent 主观判断）。 + +**先做地基 0（鉴权）→ 地基 1（draft 模式）→ 地基 2（`tools.md`），P1/P3 的 boss agent 才有事可干**——三步不做完，`ceo` 被心跳唤醒了也只能干瞪眼，或者干瞪眼都算好的，更可能是每次尝试都吃一个静默 401。 + +--- + +### P5：公司级目标代码目录（"接管已有工作目录"） + +**核实结论：这个能力在 DevLoop 层面已经完整实现，只是没有公司级默认值，也没有确认是否覆盖非 DevLoop 的执行路径。** + +`server/services/devloop/path-resolver.js` 的 `allocateProjectRoot()` 已支持三种模式（`server/routes/devloop.js` 建项目时传 `mode`/`target_path`）： + +| mode | 语义 | 现状 | +|---|---|---| +| `sandbox` | 自动分配到 `data/companies/{cid}/projects/{pid}/`（lemonboss 内部） | ✅ 已实现，默认值 | +| `linked-new` | 用户指定一个**空/新建**的绝对路径作为项目根，登记进 `~/.devloop/linked-projects.json` | ✅ 已实现 | +| `linked-existing` | 用户指定一个**已存在**的目录，接管为项目根 | ✅ **已实现，不是文件头注释说的"预留接口拒收"**——代码实测有完整校验：路径必须存在且是目录、不能已经是别的 DevLoop 项目（`project.json` 冲突检测）、若有 `.git` 必须 working tree 干净（防止 agent 的 `git add -A` 把用户脏改动卷进自动 commit）。文件头那句注释是过期文档，**建议顺手修正**。 | + +这正是用户要的"像 Claude Code 选工作目录一样接管一个已有目录"，**核心机制已经有**，且安全校验（黑名单敏感路径、git 干净树）已经比较完善。 + +**org/work graph（非 DevLoop）路径已核实**，结论比预期更好也更麻烦，分开说： + +**好消息：不是两套系统**。`graph-engine.js` 有自己的 `ensureProjectRoot(ctx)`（3476 行），文件头注释写明"位置的分配**复用 DevLoop 的 `path-resolver.allocateProjectRoot`（sandbox 模式）**，不新造一套"——`allocateRunProjectRoot()`（3458 行）内部真的就是调 `require('./devloop/path-resolver').allocateProjectRoot({ company_id, mode: 'sandbox' })`。org-coder 类节点的交付物落点、`graph_files` 索引、`34号文档` 提到的"项目根"，指的都是这同一套机制，不是 `locator.taskDir`（那是 agent 自己的运行 cwd，`_applyRuntimeScope` 分配的，两者不是一回事——agent 在 `locator.taskDir` 里跑，但写产物是写去 `ctx.projectRoot`，这个区分在 `graph-engine.js` 3736 行的"越界写入"检测里能看到：写到项目根之外会被判越界）。**结论：P5 只需要改一处入口（`allocateRunProjectRoot`），不需要在 org graph 侧另建一套。** + +**坏消息：现在的分配粒度是"每个 root run 一份全新 sandbox"，不是"每个公司一份持久目录"**。`allocateRunProjectRoot()` 硬编码 `mode: 'sandbox'`，且**没有任何"复用已有项目根"的入参**——`ensureProjectRoot()` 的幂等只在**同一个 root run 内**成立（先读 `project-root.json` 再决定要不要新分配），跨 run（也就是跨 task）**永远分配一个新 `pid`**，哪怕是同一个公司、同一个 goal 下的两个 task，也会落进两个互不相干的空目录。这比"没法接管外部目录"更根本——现在**同一家公司自己的两个任务都不共享代码**，遑论接管一个外部已有仓库。 + +**P5 真正要做的三件事**（比原先设想的"补个配置项"要深一层）： + +1. **公司级配置**：`company.json` 加 `target_dir`（绝对路径，可空）+ `target_mode`（`linked-new` / `linked-existing`，配了 `target_dir` 才有意义）。 +2. **改 `allocateRunProjectRoot(run)`**：读 `run.company_id` 对应的 `company.json.target_dir`。**配了就不再"每 run 分配新 pid"，而是所有该公司的 run 一律解析到同一个 `root_path`**（跳过 `path-resolver` 的 pid/registry 那一整套，直接返回固定路径，首次访问时按 `target_mode` 做一次 `linked-existing`/`linked-new` 的校验——现成的校验逻辑，`path-resolver.js` 261-310 行原样复用，只是只做一次，不是每个 run 各做一次）；没配 `target_dir` 就走现在的 `sandbox` 老路径，行为不变。 +3. **⚠️ 并发风险，必须在设计里显式处理**：一旦多个 task 共享同一个 `target_dir`，就与前面讨论过的"跨 task 并发"（`max_parallel_tasks > 1`）正面相撞——两个 coder agent 同时写同一个 git 仓库会冲突，`linked-existing` 现有的"进入时 working tree 必须干净"只是一次性校验，不是运行期互斥锁。**建议 v1 做法**：`company.json.target_dir` 非空时，该公司的 `max_parallel_tasks` 强制钉死为 1（在 `maxActiveRootRuns()` 里加一条：读到 `target_dir` 就忽略/覆盖用户配的 `max_parallel_tasks`），从根上排除并发写冲突，比引入 git worktree/分支合并那一整套复杂度便宜得多。`ponytail`: 这是刻意的简化，天花板是"一家公司同一时间只能有一个任务真正动代码"；真要多任务并发写同一个仓库，需要 git worktree + 完成时合并这一层，属于独立工作量，不在这次范围内。 + +**建议**：P5 独立于 P1-P4 推进（数据面完全不相关），优先级可以更高——但工作量比最初评估要大一档，不是"公司级配置 + 一次核实"就完，是"公司级配置 + 改分配粒度 + 并发约束联动"三件套。 + +--- + +## 三、修订后的建议顺序 + +用户原始顺序是 P1→P2→P3→P4，本文档建议倒过来做地基： + +``` +第一步：P4 地基 —— 建 task-board-tools（读写 goal/task 的 agent 工具） + + routeFailure 里接确定性的「四分类 → 自动开新 task」规则 +第二步：P1 收窄版 —— 给 ceo 配 heartbeat.md（监督规则，认新 goal/task 模型不是旧 OKR） + + 挂上第一步的工具 +第三步：P3 收窄版 —— 心跳只做异常判断，事件触发优先、轮询兜底、绝不重做调度 +第四步：P4 完整版 —— 把「主观判断要不要开新 task」的部分交给已经装好工具的 ceo +第五步：P2（UI） —— 独立任务看板页面，随时可插入，风险最低 +并行轨：P5 —— 公司级默认 target dir 配置 + 核实 org graph 交付物落点是否需要同样机制 +``` + +理由：P1/P3 的 boss agent 在 P4 地基建好之前没有可操作的对象；P2 是纯 UI，不卡任何人；P5 数据面独立，可以完全并行推进。 + +--- + +## 四、开放问题（已拍板，2026-08-30） + +1. ~~`ceo` 会不会和已有流水线角色冲突~~ **已核实排除**：`system/org-graph-templates/{dev,content,ops}.json` 三份模板全文搜索 `ceo`，零命中——`ceo` 现在没有出现在任何一张图里，是完全没被使用的孤儿本体。给它加监督职责没有冲突。 +2. **P4 确定性通路新开 task 的 `report_to`：继承原 goal 的 `report_to`**。`okr_node_id` 不用单独决定——它按 P3C §四.7 既定规则只挂在 `goals` 表，新 task 挂在同一个 `goal_id` 下自动沿用该 goal 的 OKR 归属，不存在"新开一份"的问题。 +3. **心跳成本策略：事件触发为主 + 低频兜底轮询**（不加"异常持续够久才唤醒"的抖动过滤，先简单落地）。主路径挂在 `transitionRun` 等既有钩子上，异常状态一出现就唤醒；另加一个量级在 30 分钟左右的低频轮询兜底，防钩子覆盖不到的漏网情况——直接照抄 `task-scheduler.js` 头部注释里"兜底扫描周期"那个既有设计哲学，不重新发明。 +4. **`ceo` 可以全权自主 `enqueue` 自己提的 draft task，不需要等人类点**——这是五个选项里最激进的一档，明确高于 `task-planning`（§四.9 定案：产出永远先落 draft，人点"全部下达"）的自主权限。**这个选择意味着安全网必须落在别处，不能靠"人工审核"这一层**：落地时要确保 `max_parallel_tasks`（防止一次性并发太多）、`DEFAULT_TASK_BUDGET`（防止单任务无限烧钱）、goal 级 `org-validator` 收敛验收（防止"完成"了但没真正达成）这几道既有闸门都乘上了 `ceo` 自主创建的 task，不能因为创建路径变了就绕开——这几道闸门本来就是数据层/调度器层强制的（不挂在"谁创建的"这个字段上），照理天然覆盖，但落地时要专门写一条回归测试钉死这一点。 +5. **P5 org graph 交付物落点调研：已做完**，结论见 §二 P5 小节——不是两套系统（复用同一个 `path-resolver`），但分配粒度是"每个 task 一份全新 sandbox"，同公司任务之间都不共享代码，比预想的工作量更大，且与"跨 task 并发"直接联动，需要一条并发约束兜底。 +6. **P4 确定性通路的实际挂载点：已实现并确认（2026-08-30）**。文档原先设想挂在 DevLoop 的四分类（`spec_ambiguous`/`contract_mismatch`）上——但那是 DevLoop 专属词汇，`graph-engine.js` 的 `routeFailure` 用的是另一套（`impl_bug`/`input_underspecified`/`skill_defect`/`infra_flake`），根本没有这两个取值。实现时改挂在 `handleBackwardEdge` 的双层硬顶熔断（单边 `loop_count>3` 或 run 级 `backward_count>5` → `force_terminated`）上——**任何**原因导致的反复回退不收敛都触发，不按 `fail_reason` 精筛。**已确认维持这个实现，不额外收窄**。副作用是良性的：`infra_flake` 走的是完全独立的原地重跑代码路径（不经过 `handleBackwardEdge`），结构上天然不会触发这条自动开新任务的规则，不需要专门加排除逻辑。落点函数：`graph-engine.js` 的 `maybeProposeReplanTask()`，挂在 `handleBackwardEdge` 熔断分支里（约 2131-2133 行）。 + +--- + +## 六、已知遗留（实现后核实，2026-08-30） + +代码落地后回查，发现两个当初设计里提过、但没有专门验证/没做完的点，记在这里而不是假装文档已经全部兑现： + +1. **§四.4 定案的"回归测试钉死闸门"没有单独落地**。`ceo` 自主 `draft` + `enqueue` 走的是和人类调用完全相同的 `POST /:cid/tasks` → `POST /:cid/tasks/:taskId/enqueue` 两个端点（`max_parallel_tasks`/`DEFAULT_TASK_BUDGET`/goal 级 `org-validator` 这几道闸门都挂在数据层/调度器层，不认"谁创建的"，理论上自动覆盖），但没有一条测试专门断言"ceo 创建的 task 一样会被这几道闸门拦下"——现有测试（`task-entry-draft-mode.test.js`、`task-blocked-ceo-wake.test.js`）验的是 draft 模式本身和唤醒机制，不是闸门穿透性。理论上没有绕过的口子，但没有测试钉死就不能说"已确认"。 +2. **`company.json.target_dir`/`target_mode` 没有任何 API/UI 入口去设置**——现在只能手工编辑公司态目录下的 `company.json` 文件才能配置。P5 落地的是"读取并生效"这一半，"人怎么把这两个字段填进去"这一半还没做（哪怕只是一个 `PATCH /api/company/:cid` 端点）。 +3. **`server/routes/graph-run.js` 漏了同一处鉴权修复，已在真实跑动中撞出来并修复（2026-08-30）**。地基 0 当时只改了 `company.js`（goals/tasks 端点），`graph-run.js`（run 的 start/stop/retry/budget 等控制端点）还是纯 `requireAuth`。真实端到端测试里 `ceo` 被唤醒后能读写 goal/task 板，但调 `/api/graph-runs/*` 处理卡住的 run 时精确撞上 401，自己在对话记录里诊断出这一点并写出了人工需要跑的 curl 命令。已修：`router`/`companyRouter` 两个挂载点都改成 `requireAuthOrInternal`，两处 `:companyId`/`:id` 的 `param` 中间件加了与 `company.js` 一致的 `req.user?.internal` 旁路，`route-auth-gate.test.js` 同步更新断言，全量测试零回归（1469/1473，剩余 4 个是核实过的 pre-existing 失败）。**这次的教训**：地基 0 的"这一步做完了"判据不能只看 `company.js` 一个文件——`ceo` 需要触达的控制面横跨两个路由文件，遗漏了没有靠代码审查发现，是靠真实跑一遍才暴露的。 + +--- + +## 七、真跑复盘（2026-08-30，`snakegame-co` 端到端测试） + +P1-P5 落地后，用它做了一次真实端到端测试：建公司 → 手工配 `target_dir` 指向一个真实的空目录 → 下一个"做 HTML 版贪吃蛇游戏"的 goal → `task-planning` 真实拆分 → 全程真实 Claude CLI 调用把 org-planner（PRD/SDD/验收标准）→ org-coder（RESEARCH/PLAN/EXECUTE/VERIFY，含真实的 test/validator/impl 修正迭代）跑完，最终 `goal status: done`、`task status: completed`，产出的 `index.html` 用独立跑的 Playwright 测试验证 5/5 通过（一个可以在浏览器里直接玩的贪吃蛇游戏）。 + +**核心结论：1469 个单测全绿，这一次真实端到端跑动却测出了至少三个单测完全没覆盖到的真问题。** "全部测试通过"不能当"系统能用"的证据——这次最有价值的发现，没有一个是单测挑出来的，全是真实跑一遍撞出来的。 + +### 7.1 真跑撞出的技术缺口 + +按发现顺序： + +1. **服务器重启会让 in-flight 的 graph 节点变僵尸，没有任何机制能自动发现**。为了让 `graph-run.js` 鉴权修复生效重启了一次服务器，正在跑 `org-planner-sdd` 的真实 Claude CLI 子进程被连带杀掉，但 `graph_run_nodes.status` 永远停在 `running`——`ceo` 的两条唤醒路径（事件驱动 + 30 分钟兜底扫描）判据都只认 `status='blocked'`，对"运行中但背后进程已死"这个状态完全不可见。查过现成的"重启后清理残留"机制（`server/index.js` 的 `resumeIncompleteTasks()`），发现它只管 ArenaSK 的 Skill 训练任务，跟 org/work graph 毫无关系；`shutdown()` 也只关插件管理器，不碰 `graph_run_nodes`。这是这次代价最大的一个坑，恢复时手写了一段脚本直接调 `graph-run-sse.transitionNode` 强制把节点判成 `fail`（走的是引擎自己的转换机制，不是绕过系统直接改数据库），才能接上标准的 `retry` 端点继续推进——但这条恢复路径本身也暴露了：**"这个节点看着卡住了，强制判失败以便恢复"这个动作现在没有任何 REST 入口**，只能改代码。 +2. **`graph-run.js` 的鉴权缺口**（见「六、已知遗留」第 3 条，已修复推送）。 +3. **规划/行动/反思没有统一的可追溯位置**。`org-coder` 的四段式阶段流转（RESEARCH→PLAN→EXECUTE→VERIFY）靠调 `bin/lemon.js task transition`，打到 `agent-chat.js` 的 `/task/transition` 端点——这个端点靠自己的 `sessions` Map 找"当前活跃会话"，但 `org-coder` 作为 work graph 节点跑的时候走的是 `graph-engine.js` → `AgentManager` → `session-pool.js`，是 CLAUDE.md 里早就记录过的"两个互不相干的会话池"那个坑的又一个受害者：阶段流转的业务逻辑（P0 审批拦截、OKR 子状态更新）在这条路径上**静默跳过**，`_plan.md` 这类中间产物既不进 `graph_files` 契约（这个是刻意的——validator 判定不该依赖"coder 计划写得像不像样"），也不进任何跨节点共享的轨迹，人类/`ceo` 事后想知道"这一步当时怎么想的"，只能去读原始的 agent transcript。 + +这三条已经拆成具体的开发计划：[42-org-work-graph-reliability-followups.md](./42-org-work-graph-reliability-followups.md)。 + +### 7.2 过程方法上的教训 + +1. **三个并行 fork 分工做 P1-P5 这个模式本身是对的**——文件边界分得干净，`git diff` 核实过没有意外重叠，最后能精确按 hunk（不是整文件）拆成三个独立 commit。值得作为以后类似规模改动的默认工作方式。 +2. **"全部测试通过"不能替代真实跑一遍**——见上，这是本次复盘最核心的教训，直接决定了 41 号文档 Phase 1-2 优先做"让已经在跑的东西更可靠"而不是急着加新功能。 +3. **"这一步做完了"的判据容易只验证了子集**——`graph-run.js` 的鉴权缺口就是典型：地基 0 当时的验证只覆盖了 `company.js`，`ceo` 实际需要触达的控制面横跨两个路由文件。以后给 agent 开权限类的工作，落地前要先列一份"这个角色实际会调哪些端点"的清单，逐条核对，不能默认"改了一个入口就等于都改了"。 +4. **重启共享的开发服务器要谨慎**——为了让代码改动生效重启了一次服务器，没意识到这会杀掉正在跑的真实 Claude CLI 子进程，浪费了一整轮真实 LLM 调用（真金白银）。以后类似场景应该先确认有没有 in-flight 的真实执行，能等就等它到一个安全点再重启。 +5. **"为什么不能自动恢复"这类追问是复盘里最值钱的部分**——第一反应往往是"手动修一下继续跑"，是持续追问"这本该由谁负责、为什么没发生"才把表面的一次性意外，看清楚成系统性盲区（僵尸节点检测缺失）。这次几个最高价值的发现，都来自这种不满足于表面解释、继续往下问一层的模式，值得作为以后排查问题的默认姿势，不只是这一次的运气。 diff --git a/docs/done/system-design/42-org-work-graph-reliability-followups.md b/docs/done/system-design/42-org-work-graph-reliability-followups.md new file mode 100644 index 0000000..306cd33 --- /dev/null +++ b/docs/done/system-design/42-org-work-graph-reliability-followups.md @@ -0,0 +1,130 @@ +# 42. Org/Work Graph 可靠性收尾 —— 39 号文档真跑复盘的待办 + +> **状态**：Phase 1-4 全部 ✅ 已实现（2026-08-30）。Phase 3 前端缺一次真实浏览器验证（见该节说明），其余无已知缺口。 +> **日期**：2026-08-30 +> **背景**：[39-boss-agent-task-supervision.md](./39-boss-agent-task-supervision.md) 的 P1-P5 落地后，用它做了一次真实端到端测试（建公司 → 下 goal → `ceo` 监督 → 真实跑出一个可玩的贪吃蛇游戏，Playwright 5/5 验证通过）。**1469 个单测全绿，这次真跑却测出至少 3 个单测完全没覆盖到的真问题**——这份文档是那次复盘沉淀下来的待办，按开工顺序分四个 phase。 +> **读者须知**：每个 phase 的现状描述都来自那次真实测试里实际撞到的场景，不是推测；具体文件/行号落地前按惯例重新核实。 + +--- + +## 一、为什么排这个顺序 + +四个 phase 分两类：**Phase 1-2 是"让已经在跑的东西更可靠"**（不改变行为，只是补上恢复路径和验证），**Phase 3-4 是"补功能缺口"**（新增能力）。前者优先——真跑复盘里代价最大的坑（僵尸节点、鉴权漏挂）都是"东西本来能跑，只是卡住了没人能救"这一类，越早补上，后面几个 phase 开工时越不容易被同样的坑绊到。Phase 5（timeline 承接规划轨迹）单独放最后，因为它是结构性改动，需要先摸清 `org-coder` 之外还有哪些角色也在打那条断线的 `/task/transition`，工作量比其余四个 phase 加起来还大。 + +``` +Phase 1：卡住恢复闭环（僵尸节点检测 + 强制判失败端点）——两个互补的口子一起补 +Phase 2：§四.4 闸门穿透性回归测试 —— 纯测试，零设计风险 +Phase 3：target_dir 的 API/UI 入口 —— 纯加法 +Phase 4：timeline.ndjson 承接 planning/reflection 轨迹 —— 结构性改动，排最后 +``` + +--- + +## 二、Phase 1：卡住恢复闭环 —— ✅ 已实现（2026-08-30） + +**落地结果**（与下面的设计一一对应，实现时没有偏离）： +- 1a：`graph-engine.js` 新增 `sweepOrphanedRunningNodes(cutoffIso)`，复用 `routeFailure` 的 `infra_flake` 分支；`server/index.js` 在 `PROCESS_STARTED_AT`（模块顶层捕获的本次进程启动时刻）挂上开机一次性调用，排在其余「开机补一次全量扫描」钩子之前。测试：`server/tests/unit/graph-engine-orphan-sweep.test.js`（4 例：孤儿转 infra_flake 原地重跑、晚于 cutoff 的不受影响、连续判孤儿撞硬顶转 blocked、无孤儿时安静 no-op）。 +- 1b：`graph-engine.js` 新增 `forceFailNode(runId, nodeRunId, failReason='operator_intervention')`；`graph-run.js` 新增 `POST /:id/nodes/:nodeId/force-fail`，只接受 `status='running'`。测试：`server/tests/unit/graph-run-force-fail.test.js`（8 例：正常转 fail 并可被 retry 接上、自定义 failReason 透传、五种非 running 状态各返 400、节点不存在返 404）。 +- 全量测试 1483/1487，零回归（剩余 4 个是核实过的 pre-existing 失败）。 + +--- + +### 1a. 服务器重启的僵尸节点检测 + +**现状（真跑撞到的）**：`graph_run_nodes.status='running'` 这一行，没有任何机制确认"背后真的还有个活的进程"。真实测试里为了让 `graph-run.js` 鉴权修复生效重启了一次服务器，正在跑 `org-planner-sdd` 的 Claude CLI 子进程被连带杀掉，但那一行的状态永远停在 `running`——不会自己变成 `blocked`，`ceo` 的两条唤醒路径（事件驱动 + 30 分钟兜底扫描）判据都是 `status='blocked'`，对这个状态完全不可见。 + +查过现成的"重启后清理残留"机制：`server/index.js` 的 `resumeIncompleteTasks()` 只处理 ArenaSK 的 Skill 训练任务（`skill-task-manager`），跟 org/work graph 毫无关系；`shutdown()`（`SIGTERM`/`SIGINT` 处理）只关插件管理器，不碰 `graph_run_nodes`。两处都不覆盖这个场景。 + +**设计**：启动时扫一遍 `graph_run_nodes`，`status='running'` 且 `updated_at`（或 `startedAt`）早于**本次进程启动时间**的行，判定为孤儿（整个进程树都被换过一轮，不可能有真实进程还在跑它）。判定后按 **`infra_flake` 语义**处理，不发明新状态——原地重跑逻辑本来就是为"基础设施打断，跟设计/实现对不对无关"这类场景设计的，服务器重启只是这个桶里更严重的一个成员。复用 `graph-engine.js` 已有的 `routeFailure` 里 `INFRA_FLAKE_REASON` 那条分支，不用另起一套判定/熔断逻辑。 + +**落点**：`server/index.js` 启动流程（挂在 `resumeIncompleteTasks()`/`sweepStuckActiveGoals()` 同一批"开机补一次全量扫描"的地方，跟这些既有钩子形状一致），加一个 `sweepOrphanedRunningNodes()`；判定逻辑放 `graph-engine.js` 或 `work-graph-db.js`（参照 `infra_flake` 现有实现挂在哪个文件）。 + +**验收**：新增测试——起一个 `status='running'`、`startedAt` 早于"当前进程启动时间"的节点，跑一次 `sweepOrphanedRunningNodes()`，断言它被转成 `infra_flake` 路径能处理的状态，且不影响 `startedAt` 晚于启动时间的正常运行节点。 + +### 1b. "强制判失败以便恢复"的 REST 端点 + +**现状**：`POST /:id/nodes/:nodeId/retry` 只接受 `status ∈ {fail, blocked}` 的节点。真实测试里遇到一个卡住的 `running` 节点，唯一的恢复手段是**直接写一段脚本调用 `graph-run-sse.transitionNode` 内部函数**，绕过了任何 REST 接口——这对人类操作者或 `ceo` 都不现实，两者都只能走 HTTP。 + +**设计**：新增 `POST /api/graph-runs/:id/nodes/:nodeId/force-fail`，语义是"我确认这个节点已经不可能再自己完成了，把它判成 `fail`（`failReason` 可选，默认某个通用值如 `operator_intervention`），交给既有的 fail→retry/backward-edge 路径处理"。**只接受 `status='running'` 的节点**（`fail`/`blocked` 已经有 `retry` 端点了，不重复造轮子）；调用方是人类还是 `ceo` 不做区分，鉴权走已有的 `requireAuthOrInternal`（跟着 Phase 1a 一起补，`graph-run.js` 这次已经全部换过了）。1a 落地后，这个端点的日常触发频率应该会显著下降（大部分"卡住"场景 1a 已经自动兜底），但保留它作为人工/`ceo` 判断"这个不是重启造成的，就是卡了"时的手动出口。 + +**验收**：新增测试——`running` 节点调 `force-fail` 转 `fail` 且可被 `retry` 端点接上；`fail`/`blocked`/`pending` 状态调用返回 400（沿用 `ensureStatus` 现成的错误形状）。 + +--- + +## 三、Phase 2：§四.4 闸门穿透性回归测试 —— ✅ 已实现（2026-08-30） + +**落地结果**：新建 `server/tests/unit/ceo-created-task-gates.test.js`，3 例全部走 `ceo` 实际会用的通路（`POST /tasks` 的 `draft:true` + `created_by:'ceo'` → `/enqueue`，不抄近道直接摆数据库行）： +1. `max_parallel_tasks=1` 时坑已占满，`ceo` 建的第二条任务落 `queued`，不插队。 +2. 预算给 `total_agent_calls:0`，`engine.checkBudget()` 照样判耗尽，`created_by='ceo'` 不改变结果。 +3. `ceo` 建的两条 task 挂在同一个 goal 下，全部 `completed` 后 `goal-validation` 的 `validateGoal` 钩子只被调一次（用 `validation.setValidateGoal()` 注入假验收，照抄 `goal-task-acceptance.test.js` 的既有手法）。 + +全量测试 1486/1490，零回归（剩余 4 个是核实过的 pre-existing 失败）。 + +**过程小插曲**：驱动第二条 task 的 run 出队时，先试了直接调 `task-scheduler.tick()`——撞上一个跟这次改动无关的既有工具链毛刺（`require.cache` 手工失效对 vitest 的 CJS 模块图不完全生效，`task-scheduler.js` 惰性 `require` 的 `work-graph-db` 引用有时会绑定到清缓存之前的实例，触发 `graph-db.js` 的"测试进程别碰生产库"守卫）。绕开的办法是不依赖 `scheduleTick` 的 `setImmediate` 时序，坑空出来后直接调 `updateRunStatus(runB,'queued','ready')`——这条路径本来就是准入事务的真实实现，只是不经过调度器这层编排，测试意图（"闸门拦不拦得住"）不受影响。 + +**现状**：39 号文档 §四.4 已拍板"`ceo` 全权自主 `enqueue`，但 `max_parallel_tasks`/`DEFAULT_TASK_BUDGET`/goal 级 `org-validator` 这几道闸门必须照样拦住它"，落地时没有补这条测试（§六"已知遗留"记过一笔）。理论上这几道闸门挂在数据层/调度器层，不认"谁创建的"，天然覆盖，但没有测试钉死就不能说"已确认"。 + +**设计**：不涉及任何设计决策，纯粹是补测试。新增用例（大致形状，落地时按现有测试文件的辅助函数抄写法）： +1. 把公司 `max_parallel_tasks` 设成 1，已有一条 task 占着坑，`ceo` 走 `draft`+`enqueue` 建第二条——断言它排队而不是插队执行。 +2. 把公司 `DEFAULT_TASK_BUDGET` 设小，`ceo` 建的任务跑到预算耗尽——断言按现有 `budget-exhausted` 路径 `blocked`，不会因为"是 agent 建的"就获得额外预算。 +3. `ceo` 建的多 task goal 全部 `completed` 后，断言 goal 级 `org-validator` 照样被调一次（不因创建者是 agent 而跳过收敛验收）。 + +**落点**：新建 `server/tests/unit/ceo-created-task-gates.test.js`，或并入现有 `task-blocked-ceo-wake.test.js`（按当时哪个更顺手）。 + +--- + +## 四、Phase 3：`target_dir` 的 API/UI 入口 —— ✅ 已实现（2026-08-30） + +**落地结果**： +- 后端复用了已存在的 `PUT /api/company/:companyId`（`companyService.update()`），没有新建端点——设计里"如果已存在就扩展"这条命中了。`update()` 新增 `target_dir`/`target_mode` 分支，校验直接调 `path-resolver.validateLinkedTarget`（39 号文档 P5 抽出来的共享函数，和 `graph-engine.js` 运行时校验同一份判据），校验失败抛出，路由层 `try/catch` 转 400；`target_dir` 传空字符串清空配置；不传 `target_mode` 时默认 `linked-existing`，与 `graph-engine.js` 的 `readCompanyTargetConfig` 同一口径。测试：`server/tests/unit/company-target-dir-config.test.js`（8 例：`linked-existing`/`linked-new` 各自成功路径、默认 mode、敏感路径黑名单、`linked-new` 非空目录、`linked-existing` 不存在、清空配置、公司不存在）。 +- 前端：`CompanyDashboard.vue` 的"概览"tab 加一张卡片（目标目录输入框 + 模式下拉 + 保存按钮），本地表单状态不直接双向绑定 `selectedCompany`（保存失败时不该让用户刚打的字被冲掉）。 + +**验证方式的取舍**：`npm run web:build` 编译通过 + 后端测试直接打真实路由层（不 mock service）。**没有做真实浏览器点击验证**——当时服务器上有其它并行会话真实在跑的 agent 进程（`ps` 能看到 3 个 `claude` 子进程），而重启服务器才能让后端改动生效，42 号文档 §二 已经记过一次"重启服务器杀掉别人真实进程"的教训，这次选择不重复。**这是一个已知的验证缺口，不是"做完了"**，下次服务器有安全窗口（没有并行会话在跑真实进程）时应该补一次真实点击验证。 + +--- + +**现状**：P5 落地的是"配了 `company.json.target_dir` 就生效"这一半，"人怎么把这两个字段填进去"这一半没做——真实测试里是手工编辑公司态目录下的 JSON 文件配的。 + +**设计**： +- **后端**：`PATCH /api/company/:companyId`（如果这个端点已存在就扩展，不存在就新建）接受 `target_dir`/`target_mode`，写回 `company.json`。校验复用 `path-resolver.js` 的 `validateLinkedTarget`（39 号文档 P5 已经抽出来的共享校验函数），配置阶段就能提前报错（不用等到第一次 `ensureProjectRoot` 才发现路径不对）。 +- **前端**：公司设置页面（或 `TaskBoard.vue`/`GraphConsole.vue` 附近，具体挂哪个页面待定）加一个表单，填目录路径 + 选 `linked-new`/`linked-existing`。 + +**验收**：新增测试覆盖 `PATCH` 端点的校验分支（合法路径写入成功、`isSensitivePath` 命中黑名单拒绝、`linked-new` 目录非空拒绝）；前端至少过一次真实点击验证表单能提交成功。 + +--- + +## 五、Phase 4：`timeline.ndjson` 承接 planning/reflection 轨迹 —— ✅ 已实现（2026-08-30） + +**调研结论（落地前按设计要求先做的那一步）**：`grep` 全仓库 `system/agents/*/agent.md`，引用 `task transition` 的有 9 个真实角色（`_base`、`code-planner`、`coder`、`org-coder`、`org-planner`、`org-writer`、`pricing-api-integrator`、`unit-tester`、`workgraph-planning`，另有几个 `zz-*` 测试夹具不算）。**`_base` 在列**——这是所有新建 agent 复制的骨架模板，意味着这条能力管的不是几个角色的特例，是整个"多阶段流转"这一类角色的通用约定，往后任何继承 `_base` 的新角色自动适用。 + +**关键发现，决定了整个实现方式**：`AgentManager.callAgent()` 的 `metadata`（含 `taskId`/`nodeRunId`/`rootRunId`）**只进服务端日志和 hook，agent 读不到**（代码原文注释）。但 agent 的节点私有产物目录本来就以 `data/companies/{cid}/runs/{rootRunId}/nodes/{nodeRunId}/` 这个形状写进它的提示词（`describeArtifactContract`），而 `--artifact` 参数本来就是这个目录下的文件路径——**两个 ID 已经现成地编码在调用方唯一知道、唯一会传的那个参数里**，不需要给 `AgentManager`/子进程塞任何新的环境变量，也不需要改一个字的 agent.md 提示词。 + +**实现**（与设计里"两种做法二选一"对应：选的是**不改 `bin/lemon.js` 的 CLI 签名、不碰 `agent-chat.js`**这条更保守的路）： +- `bin/lemon.js` 的 `task transition` 命令保持原有对 `/agent/:agentId/task/transition`（legacy）的调用完全不变，额外 best-effort 打一次新端点 `POST /api/graph-runs/phase-note`（body 只传 `artifact`/`phase`/`agentId`），失败静默吞掉，不影响命令本身的返回值/退出码。 +- 新端点从 `artifact` 路径正则解出 `rootRunId`/`nodeRunId`，校验 `rootRunId` 对应真实存在的 run（不存在就是 legacy 会话式调用的路径形状，安静返回 `not-a-graph-artifact`，不是错误），校验通过后调 `graph-run-sse.emitEvent()` 追加一条 `kind:'agent.phase'` 的 timeline 记录，`ref` 是 `nodeRunId`。 +- **`agent-chat.js` 完全没有改动**——这次特意避开了它：落地当天这个文件正被另一个并行会话实时编辑（`git status` 显示未提交修改），去碰一个正在被别人改的共享文件风险太高，改成把新能力放进这次 Phase 1-3 已经在用的 `graph-run.js`，物理上不产生交集。 +- **"不改的部分"边界确认成立**：新端点只调 `emitEvent`（纯追加 timeline，`apply` 传 `null`），不碰 `graph_run_nodes`/`graph_runs` 任何一行——测试里断言了这一点（节点状态在调用前后不变）。 +- **设计里 open 的第三个问题（P0 拦截/OKR 更新怎么处理）就此关闭**：答案是"完全不动"——这两段逻辑挂在 legacy `/task/transition` 里，图执行场景下（`sessions` Map 找不到会话）本来就从没触发过，这次也没打算让它们触发；新端点是完全独立的第二条路径，不是对旧端点的迁移或替换。 + +**测试**：`server/tests/unit/graph-run-phase-note.test.js`（4 例：合法节点产物路径写进 timeline 且节点状态不受影响、路径形状不对时安静跳过、路径形状对但 run 不存在时安静跳过、没传 artifact 时报 `no-artifact`）。全量测试 1503/1506，零回归（剩余 3 个失败全部来自另一个并行会话正在进行中、还没提交的工作）。 + +**现状（真跑撞到的，这是四个 phase 里最大的一个）**：`org-coder` 的四段式（RESEARCH→PLAN→EXECUTE→VERIFY）流转靠调 `bin/lemon.js task transition`，打到 `agent-chat.js` 的 `/task/transition` 端点——这个端点靠自己的 `sessions` Map 找"当前活跃会话"，但 `org-coder` 作为 work graph 节点跑的时候走的是 `graph-engine.js` → `AgentManager` → `session-pool.js`，是 CLAUDE.md 里早就记录过的"两个互不相干的会话池"那个坑的又一个受害者。结果：`org-coder` 在 work graph 里调这条流转指令时，`sessions.entries()` 根本找不到它的会话，阶段流转的业务逻辑（P0 审批拦截、OKR 子状态更新）**静默跳过**；它的中间产物（`_research.md`/`_plan.md`/`_lessons.md`）不进 `graph_files` 契约（这个是刻意的，见下"不改的部分"），但也**不进任何跨节点/跨角色共享的轨迹**，人类或 `ceo` 事后想搞清楚"这一步当时是怎么想的"，只能去读原始的 agent 会话 transcript（`GET /:id/nodes/:nodeRunId/transcript`），没有结构化的入口。 + +**不改的部分（上一轮已经讨论定案，写在这里防止实现时跑偏）**： +- `_plan.md` 这类中间产物**不进 `needs`/`produces` 契约**，`org-validator` 判定依据仍然只认 `acceptance.md` + `artifact`/`log`。理由：validator 判定"代码对不对"，不该依赖"coder 计划写得像不像样"，这条边界一旦模糊，两个坏结果都会发生——coder 学会把计划写漂亮而不是把代码写对；`graph_files` 的契约面失控（这个仓库反复栽在"两套体系不统一"上）。 +- 本 phase 只解决**可见性**（人类/`ceo` 事后能不能追溯），不解决**契约**（下游节点该不该依赖）——这是两件事，上一轮讨论已经拆开过。 + +**设计**（需要先做的调研，落地前必做）： +1. **调研范围**：`org-coder` 是这次撞到的一个，不代表只有它——扫一遍 `system/agents/*/agent.md` 里还有哪些角色的提示词也在调 `bin/lemon.js task transition`，把范围摸清楚再动手，不要只按 `org-coder` 这一个样本改。 +2. **迁移方向**：把"阶段流转"这个动作，从打 `agent-chat.js` 的 `/task/transition`（legacy，不认 graph run），改成写一条 `timelineNote()`（`graph-engine.js` 已有机制，per-run、append-only、永不改已写行），带上 `phase`（research/plan/execute/verify 或角色自定义的阶段名）+ `artifact` 路径。**具体是改 `bin/lemon.js task transition` 这条命令本身去打新端点，还是给它接一条新命令**，两种做法都要过一遍现有 agent 提示词的改动成本再定——这些提示词文件散在几十个 `agent.md` 里，改一条命令的调用方式等于牵动所有引用它的本体。 +3. **P0 审批拦截 / OKR 子状态更新这两块旧逻辑怎么处理**：`/task/transition` 里现在还挂着 P0 任务拦截、OKR 子状态更新这两段业务逻辑——这两者本身是不是还需要（尤其 OKR 那段，跟 P3C 的新 goal/task 模型是不是还有效对应），需要单独判断，不能假设"迁移流转机制"就等于"这两段逻辑原样照抄"。 + +**验收**（待设计细化后补全，这里先占位）：至少要有一条测试证明——`org-coder`（或调研出的任意一个角色）在 work graph 里完成一次阶段流转后，`timeline.ndjson` 里能查到对应的 `phase`+`artifact` 记录，且这条记录不影响 `graph_files`/`needs`/`produces` 的既有行为（回归测试守住"不改的部分"那条边界）。 + +--- + +## 六、开放问题 + +1. Phase 1a 的孤儿判定条件（`startedAt` 早于进程启动时间）在多进程/多副本部署下是否还成立？现在是单进程部署，这条先按当前架构写，多副本场景不在这次范围内。 +2. Phase 3 的 `PATCH /api/company/:companyId` 端点如果本来就不存在，是新建这一个端点，还是这次顺手看一下公司配置类的改动有没有更合适的既有入口——落地前查一遍 `company.js` 现状再定，不在这里预判。 +3. Phase 4 的调研如果发现有 10+ 个角色都在用旧的 `/task/transition`，工作量会明显超出"一个 phase"的量级，届时可能需要再拆细——先按"调研完再评估"处理，不在这里预先估工作量。 diff --git a/docs/todo/system-design/39-boss-agent-task-supervision.md b/docs/todo/system-design/39-boss-agent-task-supervision.md deleted file mode 100644 index afbfae8..0000000 --- a/docs/todo/system-design/39-boss-agent-task-supervision.md +++ /dev/null @@ -1,218 +0,0 @@ -# 39. Boss Agent 任务看板监督 + 公司目标代码目录 — 需求评估与设计草案 - -> **状态**：✅ P1-P5 已实现（2026-08-30，commit `a00590a` P1/P3/P4 后端、`5108d67` P2 前端、`d967ac0` P5、`14cbaf5` graph-run.js 鉴权补丁）。本文档是落地前的设计草案，实现细节以代码为准，仅存档决策过程。**已知未覆盖的后续工作见「六、已知遗留」，真实端到端跑测的复盘见「七、真跑复盘」，复盘沉淀的待办已拆成独立文档 [42-org-work-graph-reliability-followups.md](./42-org-work-graph-reliability-followups.md)（按 phase 排开工顺序）**。 -> **日期**：2026-08-30 -> **背景**：承接对话讨论——goal/task 两级模型（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md)）已落地，但推进它的是纯确定性代码（`task-scheduler.js` + `transitionRun` 钩子），没有任何 agent 在持续监督这块看板、处理异常、把执行中发现的新问题回写成新任务。用户提出五阶段方案补上这一层，并追加公司级目标代码目录需求。 -> **读者须知**：本文档大量引用现有代码路径核实"已有 vs 缺失"，结论以文内给出的具体函数/文件为准；这些引用会随代码演进过期，落地前请重新核实。 - ---- - -## 一、先说结论 - -用户的五阶段里，**P2（任务看板）本质已完成，P1/P3 的基础设施已有大半，P4 是真正的新增核心，P5 的机制已经实现了 70%，只是没有暴露到公司层面。** 真正从零开始的工作量比五个"phase"暗示的要小得多，但顺序建议大改：**P4（回写闭环）应该提到最前面**，因为它才是这次讨论最初的诉求（"自己发现问题、自己重新规划"），P1/P3 的 boss agent 只有在 P4 的工具/数据通路建好之后才有事可做。 - -| 用户的 phase | 名义工作量 | 实际现状 | 建议 | -|---|---|---|---| -| P1 雇佣通用 boss agent | 新建一个角色 + 训练 | 心跳基础设施、`ceo` 本体、Innovator 训练方法论**全部已有** | 复用 `ceo`，不新建角色；工作量收窄成"写 heartbeat.md + 工具" | -| P2 任务看板独立页面 | 一个新系统 | goal/task 两级看板**已实现**（`GoalTaskPane.vue`），只是嵌在控制台里 | 降级成 UI 改造，非必须，可排最后 | -| P3 心跳挨个决定下一个 task | 新的调度逻辑 | 挨个执行**已经是** `task-scheduler.js` 在做，且做得更好（事件驱动、零成本、已测试） | **不要重建调度**；心跳的职责收窄为"异常判断"，且应事件触发而非纯轮询 | -| P4 bug/新任务回写看板 | 一条新闭环 | **不存在**——没有任何 agent 可读写 goal/task 板的工具，四分类失败归因（30 号文档）目前只导向"重试或人工介入"，不导向"开新任务" | **真正的核心工作，优先做** | -| P5 公司目标代码目录 | 新能力 | DevLoop 的 `path-resolver.js` 已实现 `sandbox` / `linked-new` / `linked-existing` 三种模式，**`linked-existing`（接管已有目录）已经是完整实现**，只是没有公司级默认值，也没打通到 org/work graph（非 DevLoop）路径 | 补一个公司级默认配置 + 核实非 DevLoop 路径是否需要同样机制 | - ---- - -## 二、逐 phase 现状核实 - -### P1：每个公司雇佣 boss agent，system agent 层训练通用版本 - -**已有的基础设施**（全部实地核实过）： - -1. **通用心跳机制**：`server/services/heartbeat-service.js`。状态落在 `system/agents/{aid}/{cid}/heartbeat.json`（公司态目录，不是共享本体——这条边界是踩过坑之后加的，见文件头注释），本体 `config.json.heartbeat` 只是只读默认建议间隔。`_triggerHeartbeat()` 按 `setInterval` 定时给 agent 发一条 `[SYSTEM HEARTBEAT]` 系统消息（走正常的 `/api/agent/{agentId}/chat`），要求 agent "**根据你的身份和 heartbeat.md 规则**……如果一切正常，无事发生，请直接回复『心跳正常』"，带 30 分钟会话互斥防重叠。**这套机制现成可用，不用重建。** - - ✅ **修正一处之前的误判**：原以为 prompt 里"扫描全局 OKR 目标状态和节点"那句硬编码需要改代码才能适配新 goal/task 模型。查了 `system/agents/` 下已有 **35 个**本体带 `heartbeat.md`（如 `org-innovator/heartbeat.md`），内容五花八门、完全跟 OKR 无关，说明触发消息里那句"扫描 OKR"从来就只是**默认示例文案**，各 agent 早就按自己 `heartbeat.md` 里写的规则各干各的。**结论：`heartbeat-service.js` 大概率零改动**，只需要新建 `system/agents/ceo/heartbeat.md`，写清楚"去查 goal/task 板、按 §四.9 的规则判断"，agent 读到自己的 `heartbeat.md` 就会照着做，不需要动服务端代码。落地时找一个现有 `heartbeat.md` 生效的真实案例复核一次这个推断，再动手写 `ceo` 的那份。 -2. **本体已存在**：`system/agents/ceo/`（`type: "cxo"`，"Chief Executive Officer"，`heartbeat.enabled: false` 默认关）。同时存在 `system/agents/master/`（`type: "master"`，**全局唯一**，`/api/master/chat`，负责建公司/招聘等跨公司操作）。两者定位不同：`master` 是平台层面的单例助手，`ceo` 才是"每个公司一个"的角色。 -3. **训练方法论已验证**：`36-prd-agent-methodology-training-feasibility.md` 已经用 Innovator（Hunt→Digest→Evolve）训练出过一个方法论型 agent（`prd-methodology-trial`），2 轮收敛、96/97 分，方法论对这类"判断型"角色确实管用。可以照搬这条路径训练 `ceo` 的监督方法论，而不是手写一份 prompt 拍脑袋。 - -**结论**：不建议新建"boss"角色。**复用 `system/agents/ceo/`**——它的岗位定义（CEO）本来就该管"任务有没有卡住、要不要重新分解"，另起一个语义重叠的角色只会重犯这个仓库反复踩过的"名字歧义"坑（`27-naming-conventions.md` 通篇在防这个）。P1 的实际工作量是：① 给 `ceo` 补一份 `heartbeat.md`（监督规则）；② 给它挂上 P4 需要的工具（见下）；③ 默认 `heartbeat.enabled: true`（但见 P3 的成本讨论，建议先不无脑轮询）；④ 可选：用 Innovator 训练它的监督方法论。 - -**缺口 A**：目前**没有任何 agent 工具能读写 `goals`/`tasks` 表或操作 graph run**（搜了 `server/src/tools/` 全目录，零命中）。`ceo` 就算被唤醒也无事可做——这是 P1 能不能生效的真正前提，见 P4。 - -**缺口 B（新发现，之前漏了）：`ceo` 现在没有被雇进任何公司，`hire()` 也没有任何自动触发点会调它**。查了 `hire(companyId, roleName)`（`company-service.js:422`）——它只查本体目录 + `company_agents` 表，**不查 org graph**，机制上雇一个不在图里的角色完全没问题（数据模型层面，"雇了"和"进图"是两件独立的事）。但目前**没有任何代码路径会主动调 `hire(companyId, 'ceo')`**——它不在三份 org-graph-templates 里，也没有类似 `orggraph-planning` 那样的自动招聘钩子替它兜底。`37-org-graph-department-scoping.md` 里记录过一模一样的处境：`hr/` 本体"已经真实存在……只是从没被装进任何图……今天完全是编外人员"——`ceo` 现在是同款处境，**不是有先例可抄，是同一个坑还没人填**。P1 必须显式加一步：① 公司创建流程里（不管选哪个 org-graph-template）固定 `hire(companyId, 'ceo')` 一次；② 存量公司需要一次性回填脚本，遍历现有公司补雇。这条不做，前面说的"复用 ceo"就是一句空话——压根没有 `ceo` 实例在跑。 - ---- - -### P2：任务看板独立页面 - -**已实现**（[27-P3C](../../done/system-design/27-p3c-goal-task-model.md)，✅ 2026-08-20）：`web/src/components/graph-console/GoalTaskPane.vue` + `goal-task-model.js`，挂在 `/:companyId/graph-console` 左栏。goal/task 两级状态、优先级排队位次、颜色语义全部已有，REST 是 `server/routes/company.js` 的 `GET/POST /api/company/:cid/goals` 系列。 - -**用户要的"独立页面"** 目前是控制台的一个侧栏，不是路由级独立页面。这是纯 UI 改造，**不涉及数据模型或后端**，随时可做，风险最低。 - -**"subtask" 层**：当前**没有独立的 subtask 表**，`task` 就是看板能管理的最细颗粒度。task 再往下是 `graph_runs`（work graph 节点，可能含嵌套子图），这层在中间的执行画布（`WorkGraphCanvas`）里看，不在左栏。 - -> ⚠️ **不建议新增一张 subtask 表**去对应 work graph 节点。这个仓库已经因为"两套任务体系不统一"吃过至少两次苦头（P3C §十二"批 5"整章在处理这个债，`27-p3c-batch3-handover.md` 也记过一次事故）。如果要在看板上展示"这个 task 内部具体在跑哪几步"，应该是**只读地把该 task 当前 `current_run_id` 对应的 `graph_run_nodes` 渲染成一份"子步骤列表"**，复用现有表和现有执行画布的数据源，不新建写路径。 - -#### P2 决定：与 OKR 页面的关系（已拍板，2026-08-30） - -排查发现现状比预期乱：**OKR 相关 UI 现在有两份几乎逐行相同的重复实现**——`web/src/views/OkrDashboard.vue`（路由 `/okr`，`requireAdmin`，零导航入口的孤儿页面）和 `CompanyDashboard.vue` 里挂着 "goals" 名字、实际渲染 "Goals (Full OKR Tree)" 的 tab——两者都是旧 OKR 树（`O-xxx`，owner + progress%），是"OKR 正名"（`27-naming-conventions.md` §六）前端没跟着改完的遗留物，前端两处都调 `/api/okr/*`，和 P3C 的新 goal/task 模型完全不是一回事。 - -**已拍板**：**不合并**，OKR 这套前端 UI**直接废弃**，新任务看板**另起一个独立页面**。具体动作： - -1. **新增路由**：仿照 `GraphConsole` 已经立好的先例（`/:id/graph-console` 是独立路由，不挤在 `CompanyDetail` 的 `:tab(...)` 白名单里），新增 `/:id/task-board`（命名待定）→ 新建 `web/src/views/TaskBoard.vue`。**不要塞进 `:tab(...)` 正则**，理由与 `graph-console` 当年的注释一致：任务看板信息密度高，值得一个整页。 -2. **复用现有逻辑，不重写数据层**：`GoalTaskPane.vue` + `goal-task-model.js` 现在已经封装了 goal/task 的状态映射、排序、颜色语义（且有专门的单测 `goal-task-model.test.js` 兜底）。新页面应该是把这个组件从 `GraphConsole` 的侧栏布局里"拔出来"放大铺满整页，**不是重新实现一遍**。`GraphConsole` 侧栏可以保留一份精简版（点某个 task 仍需跳转去看它的执行图），也可以改成跳转链接指向新页面——两种都行，实现时再定。 -3. **废弃 OKR 前端**：删 `/okr` 路由 + `OkrDashboard.vue`；删 `CompanyDashboard.vue` 里那个挂着 "goals" 名字实为 OKR 树的 tab；路由 `:tab(...)` 白名单里的 `goals`/`okr` 两个值一并摘掉，避免留死链接。 -4. **导航入口**：新页面必须挂真实导航入口（`AppNav` 或公司详情页的显眼位置），不能重蹈 `/okr` 那种"孤儿页面"的覆辙。 -5. **鉴权**：`okr.js` 当年挂 `requireAdmin` 是因为它是孤儿页面、没做归属校验的权宜之计（`38-auth-multi-tenant-isolation.md`），**不是"任务看板天生该管理员专属"**。新路由要按 `company.js` 等其他公司级路由的标准做法，走 `canAccessCompany` 归属校验，不能照抄 `requireAdmin`。 - -**范围之外、本次不动**（留作独立的后续决定，不在这次 P2 改造里顺手做）：`/api/okr/*` 后端路由、`okr` 相关 SQLite 表、`goals.okr_node_id` 这个可选外键字段——前端 UI 废弃不等于后端子系统也要一起拆，那是一次单独的、影响面更大的退役决定（牵涉数据迁移/存量数据处理），需要单独评估，这里先只处理前端。 - ---- - -### P3：心跳挨个决定下一个 task - -**这条按用户原话实现是在重建一个已经存在、已经测试、且更优的系统。** `task-scheduler.js` 的队列排序口径是 `priority → seq → created_at`（`ORDER BY priority, seq, created_at`），出队靠 `transitionRun` 这个唯一漏斗事件触发，不是轮询；v1 约束 `max_parallel_tasks`（`company.json`，缺省 1）决定"挨个"还是"并发几个"，`server/tests/unit/task-slots-parallel.test.js` 覆盖了 >1 的情况。这套机制零 LLM 成本、毫秒级触发、已经过多轮真实回归验证（`31-work-graph-fail-fallback-coverage.md` 的真实 LLM 端到端案例）。 - -**成本账**：`heartbeat-service.js` 现在的实现是**每一次 tick 都真的发一次 LLM 调用**，只是 prompt 要求"没事就回复 `[心跳正常]`"——省不了那次调用的 token/延迟。如果 N 家公司、每家每 5 分钟一次心跳，24 小时就是 N×288 次 LLM 调用，绝大多数只会换回一句"心跳正常"。 - -**修订建议**：boss agent 心跳**只负责调度器处理不了的判断题**，而且触发方式改成"事件优先、轮询兜底"，不是纯定时轮询： - -1. 判断题清单（调度器管不了、需要 LLM 判断的）： - - task 长时间 `blocked` 或 `failed`（预算耗尽/依赖死锁）——要不要重新分解、要不要升级给人类； - - 同一 goal 下多个 task 出现优先级冲突（业务变化导致原定顺序不再合理）——要不要调整 `priority`； - - `task-planning` 3 轮降级成单任务（P3C §四.9 的降级路径）——要不要人工介入重新审视这条 goal 的描述。 -2. **优先事件驱动**：在 `transitionRun`/`settleGoal` 这类既有钩子里，遇到上述判断题触发的状态变化（比如 task 转 `blocked`）时，**主动**唤醒 `ceo` 处理这一条，而不是让它等下一次心跳才发现。心跳退化成**低频兜底**（比如 30 分钟一次，只扫"有没有钩子漏掉的异常"），不是主决策路径——这与现有 `task-scheduler.js` 头部注释里"兜底扫描周期"的设计哲学完全一致，照抄这个模式即可。 - ---- - -### P4：org/work graph 产生的新 bug / 新 task 回写看板，形成闭环 - -**这是五个 phase 里唯一真正从零开始、也是这次讨论最初诉求（"自己发现问题、自己重新规划"）真正要落地的地方。** - -**现有的失败归因机制**（`30-task-delegation-reliability-gaps.md`）：`BugTriager`/`validator-triager` 类节点已经在做四分类——`contract_mismatch` / `impl_bug` / `spec_ambiguous` / `infra_flake`——但**四条路径的终点目前都是"原地重试"或"预算耗尽后 blocked 等人工"**，没有一条走向"生成一条新 task/goal"。 - -**需要新增的两个通路**： - -1. **确定性通路（不需要 agent 判断）**：把四分类里"显然该开新任务"的情形直接在 `routeFailure`（`graph-engine.js`）里接一条规则，而不是等 boss agent 心跳才处理——比如 `spec_ambiguous` 在 goal 级预算内重试超过阈值，直接生成一条 `status='draft'`、`created_by='system'`、挂在同一 `goal_id` 下的新 task，附上失败节点的诊断产物作为新 task 的 `description` 素材，人工/`ceo` 再审。这条不需要 LLM 判断"要不要开新任务"，只需要判断"开一条什么样的"——后者才是可选的 agent 介入点。 -2. **主观通路（需要 agent 判断，这是 P1 的 `ceo`/工具的用武之地）**：agent 在执行任务过程中发现的、**不在当前 task 描述范围内**的问题（比如 coder 顺手发现一个无关的历史 bug），需要一个**工具**让它"提一条新任务"而不是把不相关的修复硬塞进当前 task 的产物里。这是当前完全没有的能力。 - -**必须先建的地基**——查完代码，发现比"包一层工具"更底层的东西还没有，得先排清楚三件事，顺序不能反： - -#### 地基 0（阻塞项）：`ceo` 现在物理上调不通这套 REST API - -`server/src/tools/tool-registry.js` 开头写得明明白白——**这是"Master Agent 工具注册中心"**，`[TOOL_CALL: xxx]` 这套 JSON 文本协议是 Master 专属的自定义解析层，`server/src/tools/devloop/` 下另有一套 DevLoop 专属的 tool-registry。`ceo` 这类普通 org node agent（走标准 Claude CLI 子进程）**两套都不属于**——它能用的只有 Claude CLI 原生的 Bash/curl，具体调用哪个接口靠 `tools.md` 里的**大白话 + curl 示例**（`task-planning/tools.md` 就是这个写法的范本）。所以"task-board-tools.js" 这个提法本身**不成立**——不需要新写一个 JS 工具模块，需要写的是一份 `system/agents/ceo/tools.md`（现在是空文件）。 - -但更麻烦的是：`server/routes/company.js` 顶部 `router.use(requireAuth)`（14 行），**goals/tasks 全系列端点只认人类 JWT**，没有走 `agent-chat.js` 那样的 `requireAuthOrInternal`。也就是说，就算 `ceo` 的 `tools.md` 写得再clear，它发出的每一条 curl **现在都会静默 401**——这正是最近几个 commit（`d48425a` selfChat 自环漏带内部令牌、`9e58656` bin/lemon.js task report/dispatch 401）反复修的那一类坑，company.js 这次还没打这个补丁。**这是全部 P4 工作的前提阻塞项**，必须先给 goals/tasks 这组路由加上 `requireAuthOrInternal`（或者更收紧一点，只给这几条挂内部令牌白名单），agent 才有物理上调得通的可能。 - -#### 地基 1：`POST /:companyId/tasks` 没有"草稿"模式，agent 提的任务会立刻烧预算 - -现有 `POST /:companyId/tasks`（`company.js:2077`）建完 task 行**无条件紧接着调 `enqueueTaskRun` + `startNextIfSlotFree`**——语义是"下达即执行"，服务的是"人类/外部 agent 派工"这个存量场景（代码注释原话："存量调用方的心智是下达即执行"）。这条路径不适合 `ceo` 自主提的新任务：`task-planning` 拆出来的 task 尚且要先落 `draft`、人点"全部下达"才转 `queued`（P3C §四.9 的既定哲学——"一次 LLM 猜测直接烧 5 份预算"是要避免的事），`ceo` 一次判断失误直接把新任务怼进队列烧钱，风险比 task-planning 更高（task-planning 只在 goal 刚建时跑一次，`ceo` 是持续在线判断）。 - -**需要的改动很小**：给 `POST /:companyId/tasks` 加一个 `draft: true`（或 `status: 'draft'`）入参，为真时只调 `wdb.createTask()` 落库，跳过 `enqueueTaskRun`/`markGoalDispatched`/`startNextIfSlotFree` 三步，返回 `status: 'draft'`。已有的 `POST /:companyId/tasks/:taskId/enqueue`（`company.js:2275`，`draft → queued`）原样复用，不用新建。默认行为（不传这个参数）完全不变，纯加法，不影响存量调用方。 - -#### 地基 2：`ceo` 的 `tools.md` 写什么 - -在地基 0/1 落地后，照抄 `task-planning/tools.md` 的写法（先说"大概率不需要工具"、给出何时才用、给出 curl 示例、专辟一节"你不该用的工具"防止越权）给 `ceo` 写一份，覆盖： - -- **读**：`GET /:cid/goals?status=active`（扫哪些 goal 在跑）、`GET /:cid/tasks?status=blocked` / `?status=failed`（找卡住的）、`GET /:cid/goals/:goalId`（看某 goal 下全部 task + run 摘要） -- **写**：`PATCH /:cid/tasks/:taskId`（改 `priority`）、`POST /:cid/tasks`（带 `draft:true`，提新任务）、`POST /:cid/tasks/:taskId/enqueue`（把自己或别人提的草稿正式下达——这一步要不要也留给人类点，是个开放问题，见 §四） -- **明确不该用**：`org-graph/replan`、招聘类端点（这些是 HR/`orggraph-planning` 的事，`ceo` 判断"缺角色"之后应该是发通知/提 task，不是自己动手改组织结构） - -#### 确定性通路（routeFailure 里那条规则）不走这套 REST - -30 号文档四分类里"显然该开新任务"的情形（比如 `spec_ambiguous` 重试超阈值），是 `graph-engine.js` 服务端内部代码，**直接调 `wdb.createTask()`**（同进程函数调用），不必经过 HTTP、不必带内部令牌，落库同样是 `draft`。这条通路和 `ceo` 的 agent 通路是并行的两条腿，共享同一个"落 draft、不自动下达"的规则，但触发方式不同（一个是引擎钩子里的确定性规则，一个是 agent 主观判断）。 - -**先做地基 0（鉴权）→ 地基 1（draft 模式）→ 地基 2（`tools.md`），P1/P3 的 boss agent 才有事可干**——三步不做完，`ceo` 被心跳唤醒了也只能干瞪眼，或者干瞪眼都算好的，更可能是每次尝试都吃一个静默 401。 - ---- - -### P5：公司级目标代码目录（"接管已有工作目录"） - -**核实结论：这个能力在 DevLoop 层面已经完整实现，只是没有公司级默认值，也没有确认是否覆盖非 DevLoop 的执行路径。** - -`server/services/devloop/path-resolver.js` 的 `allocateProjectRoot()` 已支持三种模式（`server/routes/devloop.js` 建项目时传 `mode`/`target_path`）： - -| mode | 语义 | 现状 | -|---|---|---| -| `sandbox` | 自动分配到 `data/companies/{cid}/projects/{pid}/`（lemonboss 内部） | ✅ 已实现，默认值 | -| `linked-new` | 用户指定一个**空/新建**的绝对路径作为项目根，登记进 `~/.devloop/linked-projects.json` | ✅ 已实现 | -| `linked-existing` | 用户指定一个**已存在**的目录，接管为项目根 | ✅ **已实现，不是文件头注释说的"预留接口拒收"**——代码实测有完整校验：路径必须存在且是目录、不能已经是别的 DevLoop 项目（`project.json` 冲突检测）、若有 `.git` 必须 working tree 干净（防止 agent 的 `git add -A` 把用户脏改动卷进自动 commit）。文件头那句注释是过期文档，**建议顺手修正**。 | - -这正是用户要的"像 Claude Code 选工作目录一样接管一个已有目录"，**核心机制已经有**，且安全校验（黑名单敏感路径、git 干净树）已经比较完善。 - -**org/work graph（非 DevLoop）路径已核实**，结论比预期更好也更麻烦，分开说： - -**好消息：不是两套系统**。`graph-engine.js` 有自己的 `ensureProjectRoot(ctx)`（3476 行），文件头注释写明"位置的分配**复用 DevLoop 的 `path-resolver.allocateProjectRoot`（sandbox 模式）**，不新造一套"——`allocateRunProjectRoot()`（3458 行）内部真的就是调 `require('./devloop/path-resolver').allocateProjectRoot({ company_id, mode: 'sandbox' })`。org-coder 类节点的交付物落点、`graph_files` 索引、`34号文档` 提到的"项目根"，指的都是这同一套机制，不是 `locator.taskDir`（那是 agent 自己的运行 cwd，`_applyRuntimeScope` 分配的，两者不是一回事——agent 在 `locator.taskDir` 里跑，但写产物是写去 `ctx.projectRoot`，这个区分在 `graph-engine.js` 3736 行的"越界写入"检测里能看到：写到项目根之外会被判越界）。**结论：P5 只需要改一处入口（`allocateRunProjectRoot`），不需要在 org graph 侧另建一套。** - -**坏消息：现在的分配粒度是"每个 root run 一份全新 sandbox"，不是"每个公司一份持久目录"**。`allocateRunProjectRoot()` 硬编码 `mode: 'sandbox'`，且**没有任何"复用已有项目根"的入参**——`ensureProjectRoot()` 的幂等只在**同一个 root run 内**成立（先读 `project-root.json` 再决定要不要新分配），跨 run（也就是跨 task）**永远分配一个新 `pid`**，哪怕是同一个公司、同一个 goal 下的两个 task，也会落进两个互不相干的空目录。这比"没法接管外部目录"更根本——现在**同一家公司自己的两个任务都不共享代码**，遑论接管一个外部已有仓库。 - -**P5 真正要做的三件事**（比原先设想的"补个配置项"要深一层）： - -1. **公司级配置**：`company.json` 加 `target_dir`（绝对路径，可空）+ `target_mode`（`linked-new` / `linked-existing`，配了 `target_dir` 才有意义）。 -2. **改 `allocateRunProjectRoot(run)`**：读 `run.company_id` 对应的 `company.json.target_dir`。**配了就不再"每 run 分配新 pid"，而是所有该公司的 run 一律解析到同一个 `root_path`**（跳过 `path-resolver` 的 pid/registry 那一整套，直接返回固定路径，首次访问时按 `target_mode` 做一次 `linked-existing`/`linked-new` 的校验——现成的校验逻辑，`path-resolver.js` 261-310 行原样复用，只是只做一次，不是每个 run 各做一次）；没配 `target_dir` 就走现在的 `sandbox` 老路径，行为不变。 -3. **⚠️ 并发风险，必须在设计里显式处理**：一旦多个 task 共享同一个 `target_dir`，就与前面讨论过的"跨 task 并发"（`max_parallel_tasks > 1`）正面相撞——两个 coder agent 同时写同一个 git 仓库会冲突，`linked-existing` 现有的"进入时 working tree 必须干净"只是一次性校验，不是运行期互斥锁。**建议 v1 做法**：`company.json.target_dir` 非空时，该公司的 `max_parallel_tasks` 强制钉死为 1（在 `maxActiveRootRuns()` 里加一条：读到 `target_dir` 就忽略/覆盖用户配的 `max_parallel_tasks`），从根上排除并发写冲突，比引入 git worktree/分支合并那一整套复杂度便宜得多。`ponytail`: 这是刻意的简化，天花板是"一家公司同一时间只能有一个任务真正动代码"；真要多任务并发写同一个仓库，需要 git worktree + 完成时合并这一层，属于独立工作量，不在这次范围内。 - -**建议**：P5 独立于 P1-P4 推进（数据面完全不相关），优先级可以更高——但工作量比最初评估要大一档，不是"公司级配置 + 一次核实"就完，是"公司级配置 + 改分配粒度 + 并发约束联动"三件套。 - ---- - -## 三、修订后的建议顺序 - -用户原始顺序是 P1→P2→P3→P4，本文档建议倒过来做地基： - -``` -第一步：P4 地基 —— 建 task-board-tools（读写 goal/task 的 agent 工具） - + routeFailure 里接确定性的「四分类 → 自动开新 task」规则 -第二步：P1 收窄版 —— 给 ceo 配 heartbeat.md（监督规则，认新 goal/task 模型不是旧 OKR） - + 挂上第一步的工具 -第三步：P3 收窄版 —— 心跳只做异常判断，事件触发优先、轮询兜底、绝不重做调度 -第四步：P4 完整版 —— 把「主观判断要不要开新 task」的部分交给已经装好工具的 ceo -第五步：P2（UI） —— 独立任务看板页面，随时可插入，风险最低 -并行轨：P5 —— 公司级默认 target dir 配置 + 核实 org graph 交付物落点是否需要同样机制 -``` - -理由：P1/P3 的 boss agent 在 P4 地基建好之前没有可操作的对象；P2 是纯 UI，不卡任何人；P5 数据面独立，可以完全并行推进。 - ---- - -## 四、开放问题（已拍板，2026-08-30） - -1. ~~`ceo` 会不会和已有流水线角色冲突~~ **已核实排除**：`system/org-graph-templates/{dev,content,ops}.json` 三份模板全文搜索 `ceo`，零命中——`ceo` 现在没有出现在任何一张图里，是完全没被使用的孤儿本体。给它加监督职责没有冲突。 -2. **P4 确定性通路新开 task 的 `report_to`：继承原 goal 的 `report_to`**。`okr_node_id` 不用单独决定——它按 P3C §四.7 既定规则只挂在 `goals` 表，新 task 挂在同一个 `goal_id` 下自动沿用该 goal 的 OKR 归属，不存在"新开一份"的问题。 -3. **心跳成本策略：事件触发为主 + 低频兜底轮询**（不加"异常持续够久才唤醒"的抖动过滤，先简单落地）。主路径挂在 `transitionRun` 等既有钩子上，异常状态一出现就唤醒；另加一个量级在 30 分钟左右的低频轮询兜底，防钩子覆盖不到的漏网情况——直接照抄 `task-scheduler.js` 头部注释里"兜底扫描周期"那个既有设计哲学，不重新发明。 -4. **`ceo` 可以全权自主 `enqueue` 自己提的 draft task，不需要等人类点**——这是五个选项里最激进的一档，明确高于 `task-planning`（§四.9 定案：产出永远先落 draft，人点"全部下达"）的自主权限。**这个选择意味着安全网必须落在别处，不能靠"人工审核"这一层**：落地时要确保 `max_parallel_tasks`（防止一次性并发太多）、`DEFAULT_TASK_BUDGET`（防止单任务无限烧钱）、goal 级 `org-validator` 收敛验收（防止"完成"了但没真正达成）这几道既有闸门都乘上了 `ceo` 自主创建的 task，不能因为创建路径变了就绕开——这几道闸门本来就是数据层/调度器层强制的（不挂在"谁创建的"这个字段上），照理天然覆盖，但落地时要专门写一条回归测试钉死这一点。 -5. **P5 org graph 交付物落点调研：已做完**，结论见 §二 P5 小节——不是两套系统（复用同一个 `path-resolver`），但分配粒度是"每个 task 一份全新 sandbox"，同公司任务之间都不共享代码，比预想的工作量更大，且与"跨 task 并发"直接联动，需要一条并发约束兜底。 -6. **P4 确定性通路的实际挂载点：已实现并确认（2026-08-30）**。文档原先设想挂在 DevLoop 的四分类（`spec_ambiguous`/`contract_mismatch`）上——但那是 DevLoop 专属词汇，`graph-engine.js` 的 `routeFailure` 用的是另一套（`impl_bug`/`input_underspecified`/`skill_defect`/`infra_flake`），根本没有这两个取值。实现时改挂在 `handleBackwardEdge` 的双层硬顶熔断（单边 `loop_count>3` 或 run 级 `backward_count>5` → `force_terminated`）上——**任何**原因导致的反复回退不收敛都触发，不按 `fail_reason` 精筛。**已确认维持这个实现，不额外收窄**。副作用是良性的：`infra_flake` 走的是完全独立的原地重跑代码路径（不经过 `handleBackwardEdge`），结构上天然不会触发这条自动开新任务的规则，不需要专门加排除逻辑。落点函数：`graph-engine.js` 的 `maybeProposeReplanTask()`，挂在 `handleBackwardEdge` 熔断分支里（约 2131-2133 行）。 - ---- - -## 六、已知遗留（实现后核实，2026-08-30） - -代码落地后回查，发现两个当初设计里提过、但没有专门验证/没做完的点，记在这里而不是假装文档已经全部兑现： - -1. **§四.4 定案的"回归测试钉死闸门"没有单独落地**。`ceo` 自主 `draft` + `enqueue` 走的是和人类调用完全相同的 `POST /:cid/tasks` → `POST /:cid/tasks/:taskId/enqueue` 两个端点（`max_parallel_tasks`/`DEFAULT_TASK_BUDGET`/goal 级 `org-validator` 这几道闸门都挂在数据层/调度器层，不认"谁创建的"，理论上自动覆盖），但没有一条测试专门断言"ceo 创建的 task 一样会被这几道闸门拦下"——现有测试（`task-entry-draft-mode.test.js`、`task-blocked-ceo-wake.test.js`）验的是 draft 模式本身和唤醒机制，不是闸门穿透性。理论上没有绕过的口子，但没有测试钉死就不能说"已确认"。 -2. **`company.json.target_dir`/`target_mode` 没有任何 API/UI 入口去设置**——现在只能手工编辑公司态目录下的 `company.json` 文件才能配置。P5 落地的是"读取并生效"这一半，"人怎么把这两个字段填进去"这一半还没做（哪怕只是一个 `PATCH /api/company/:cid` 端点）。 -3. **`server/routes/graph-run.js` 漏了同一处鉴权修复，已在真实跑动中撞出来并修复（2026-08-30）**。地基 0 当时只改了 `company.js`（goals/tasks 端点），`graph-run.js`（run 的 start/stop/retry/budget 等控制端点）还是纯 `requireAuth`。真实端到端测试里 `ceo` 被唤醒后能读写 goal/task 板，但调 `/api/graph-runs/*` 处理卡住的 run 时精确撞上 401，自己在对话记录里诊断出这一点并写出了人工需要跑的 curl 命令。已修：`router`/`companyRouter` 两个挂载点都改成 `requireAuthOrInternal`，两处 `:companyId`/`:id` 的 `param` 中间件加了与 `company.js` 一致的 `req.user?.internal` 旁路，`route-auth-gate.test.js` 同步更新断言，全量测试零回归（1469/1473，剩余 4 个是核实过的 pre-existing 失败）。**这次的教训**：地基 0 的"这一步做完了"判据不能只看 `company.js` 一个文件——`ceo` 需要触达的控制面横跨两个路由文件，遗漏了没有靠代码审查发现，是靠真实跑一遍才暴露的。 - ---- - -## 七、真跑复盘（2026-08-30，`snakegame-co` 端到端测试） - -P1-P5 落地后，用它做了一次真实端到端测试：建公司 → 手工配 `target_dir` 指向一个真实的空目录 → 下一个"做 HTML 版贪吃蛇游戏"的 goal → `task-planning` 真实拆分 → 全程真实 Claude CLI 调用把 org-planner（PRD/SDD/验收标准）→ org-coder（RESEARCH/PLAN/EXECUTE/VERIFY，含真实的 test/validator/impl 修正迭代）跑完，最终 `goal status: done`、`task status: completed`，产出的 `index.html` 用独立跑的 Playwright 测试验证 5/5 通过（一个可以在浏览器里直接玩的贪吃蛇游戏）。 - -**核心结论：1469 个单测全绿，这一次真实端到端跑动却测出了至少三个单测完全没覆盖到的真问题。** "全部测试通过"不能当"系统能用"的证据——这次最有价值的发现，没有一个是单测挑出来的，全是真实跑一遍撞出来的。 - -### 7.1 真跑撞出的技术缺口 - -按发现顺序： - -1. **服务器重启会让 in-flight 的 graph 节点变僵尸，没有任何机制能自动发现**。为了让 `graph-run.js` 鉴权修复生效重启了一次服务器，正在跑 `org-planner-sdd` 的真实 Claude CLI 子进程被连带杀掉，但 `graph_run_nodes.status` 永远停在 `running`——`ceo` 的两条唤醒路径（事件驱动 + 30 分钟兜底扫描）判据都只认 `status='blocked'`，对"运行中但背后进程已死"这个状态完全不可见。查过现成的"重启后清理残留"机制（`server/index.js` 的 `resumeIncompleteTasks()`），发现它只管 ArenaSK 的 Skill 训练任务，跟 org/work graph 毫无关系；`shutdown()` 也只关插件管理器，不碰 `graph_run_nodes`。这是这次代价最大的一个坑，恢复时手写了一段脚本直接调 `graph-run-sse.transitionNode` 强制把节点判成 `fail`（走的是引擎自己的转换机制，不是绕过系统直接改数据库），才能接上标准的 `retry` 端点继续推进——但这条恢复路径本身也暴露了：**"这个节点看着卡住了，强制判失败以便恢复"这个动作现在没有任何 REST 入口**，只能改代码。 -2. **`graph-run.js` 的鉴权缺口**（见「六、已知遗留」第 3 条，已修复推送）。 -3. **规划/行动/反思没有统一的可追溯位置**。`org-coder` 的四段式阶段流转（RESEARCH→PLAN→EXECUTE→VERIFY）靠调 `bin/lemon.js task transition`，打到 `agent-chat.js` 的 `/task/transition` 端点——这个端点靠自己的 `sessions` Map 找"当前活跃会话"，但 `org-coder` 作为 work graph 节点跑的时候走的是 `graph-engine.js` → `AgentManager` → `session-pool.js`，是 CLAUDE.md 里早就记录过的"两个互不相干的会话池"那个坑的又一个受害者：阶段流转的业务逻辑（P0 审批拦截、OKR 子状态更新）在这条路径上**静默跳过**，`_plan.md` 这类中间产物既不进 `graph_files` 契约（这个是刻意的——validator 判定不该依赖"coder 计划写得像不像样"），也不进任何跨节点共享的轨迹，人类/`ceo` 事后想知道"这一步当时怎么想的"，只能去读原始的 agent transcript。 - -这三条已经拆成具体的开发计划：[42-org-work-graph-reliability-followups.md](./42-org-work-graph-reliability-followups.md)。 - -### 7.2 过程方法上的教训 - -1. **三个并行 fork 分工做 P1-P5 这个模式本身是对的**——文件边界分得干净，`git diff` 核实过没有意外重叠，最后能精确按 hunk（不是整文件）拆成三个独立 commit。值得作为以后类似规模改动的默认工作方式。 -2. **"全部测试通过"不能替代真实跑一遍**——见上，这是本次复盘最核心的教训，直接决定了 41 号文档 Phase 1-2 优先做"让已经在跑的东西更可靠"而不是急着加新功能。 -3. **"这一步做完了"的判据容易只验证了子集**——`graph-run.js` 的鉴权缺口就是典型：地基 0 当时的验证只覆盖了 `company.js`，`ceo` 实际需要触达的控制面横跨两个路由文件。以后给 agent 开权限类的工作，落地前要先列一份"这个角色实际会调哪些端点"的清单，逐条核对，不能默认"改了一个入口就等于都改了"。 -4. **重启共享的开发服务器要谨慎**——为了让代码改动生效重启了一次服务器，没意识到这会杀掉正在跑的真实 Claude CLI 子进程，浪费了一整轮真实 LLM 调用（真金白银）。以后类似场景应该先确认有没有 in-flight 的真实执行，能等就等它到一个安全点再重启。 -5. **"为什么不能自动恢复"这类追问是复盘里最值钱的部分**——第一反应往往是"手动修一下继续跑"，是持续追问"这本该由谁负责、为什么没发生"才把表面的一次性意外，看清楚成系统性盲区（僵尸节点检测缺失）。这次几个最高价值的发现，都来自这种不满足于表面解释、继续往下问一层的模式，值得作为以后排查问题的默认姿势，不只是这一次的运气。 diff --git a/docs/todo/system-design/42-org-work-graph-reliability-followups.md b/docs/todo/system-design/42-org-work-graph-reliability-followups.md deleted file mode 100644 index 306cd33..0000000 --- a/docs/todo/system-design/42-org-work-graph-reliability-followups.md +++ /dev/null @@ -1,130 +0,0 @@ -# 42. Org/Work Graph 可靠性收尾 —— 39 号文档真跑复盘的待办 - -> **状态**：Phase 1-4 全部 ✅ 已实现（2026-08-30）。Phase 3 前端缺一次真实浏览器验证（见该节说明），其余无已知缺口。 -> **日期**：2026-08-30 -> **背景**：[39-boss-agent-task-supervision.md](./39-boss-agent-task-supervision.md) 的 P1-P5 落地后，用它做了一次真实端到端测试（建公司 → 下 goal → `ceo` 监督 → 真实跑出一个可玩的贪吃蛇游戏，Playwright 5/5 验证通过）。**1469 个单测全绿，这次真跑却测出至少 3 个单测完全没覆盖到的真问题**——这份文档是那次复盘沉淀下来的待办，按开工顺序分四个 phase。 -> **读者须知**：每个 phase 的现状描述都来自那次真实测试里实际撞到的场景，不是推测；具体文件/行号落地前按惯例重新核实。 - ---- - -## 一、为什么排这个顺序 - -四个 phase 分两类：**Phase 1-2 是"让已经在跑的东西更可靠"**（不改变行为，只是补上恢复路径和验证），**Phase 3-4 是"补功能缺口"**（新增能力）。前者优先——真跑复盘里代价最大的坑（僵尸节点、鉴权漏挂）都是"东西本来能跑，只是卡住了没人能救"这一类，越早补上，后面几个 phase 开工时越不容易被同样的坑绊到。Phase 5（timeline 承接规划轨迹）单独放最后，因为它是结构性改动，需要先摸清 `org-coder` 之外还有哪些角色也在打那条断线的 `/task/transition`，工作量比其余四个 phase 加起来还大。 - -``` -Phase 1：卡住恢复闭环（僵尸节点检测 + 强制判失败端点）——两个互补的口子一起补 -Phase 2：§四.4 闸门穿透性回归测试 —— 纯测试，零设计风险 -Phase 3：target_dir 的 API/UI 入口 —— 纯加法 -Phase 4：timeline.ndjson 承接 planning/reflection 轨迹 —— 结构性改动，排最后 -``` - ---- - -## 二、Phase 1：卡住恢复闭环 —— ✅ 已实现（2026-08-30） - -**落地结果**（与下面的设计一一对应，实现时没有偏离）： -- 1a：`graph-engine.js` 新增 `sweepOrphanedRunningNodes(cutoffIso)`，复用 `routeFailure` 的 `infra_flake` 分支；`server/index.js` 在 `PROCESS_STARTED_AT`（模块顶层捕获的本次进程启动时刻）挂上开机一次性调用，排在其余「开机补一次全量扫描」钩子之前。测试：`server/tests/unit/graph-engine-orphan-sweep.test.js`（4 例：孤儿转 infra_flake 原地重跑、晚于 cutoff 的不受影响、连续判孤儿撞硬顶转 blocked、无孤儿时安静 no-op）。 -- 1b：`graph-engine.js` 新增 `forceFailNode(runId, nodeRunId, failReason='operator_intervention')`；`graph-run.js` 新增 `POST /:id/nodes/:nodeId/force-fail`，只接受 `status='running'`。测试：`server/tests/unit/graph-run-force-fail.test.js`（8 例：正常转 fail 并可被 retry 接上、自定义 failReason 透传、五种非 running 状态各返 400、节点不存在返 404）。 -- 全量测试 1483/1487，零回归（剩余 4 个是核实过的 pre-existing 失败）。 - ---- - -### 1a. 服务器重启的僵尸节点检测 - -**现状（真跑撞到的）**：`graph_run_nodes.status='running'` 这一行，没有任何机制确认"背后真的还有个活的进程"。真实测试里为了让 `graph-run.js` 鉴权修复生效重启了一次服务器，正在跑 `org-planner-sdd` 的 Claude CLI 子进程被连带杀掉，但那一行的状态永远停在 `running`——不会自己变成 `blocked`，`ceo` 的两条唤醒路径（事件驱动 + 30 分钟兜底扫描）判据都是 `status='blocked'`，对这个状态完全不可见。 - -查过现成的"重启后清理残留"机制：`server/index.js` 的 `resumeIncompleteTasks()` 只处理 ArenaSK 的 Skill 训练任务（`skill-task-manager`），跟 org/work graph 毫无关系；`shutdown()`（`SIGTERM`/`SIGINT` 处理）只关插件管理器，不碰 `graph_run_nodes`。两处都不覆盖这个场景。 - -**设计**：启动时扫一遍 `graph_run_nodes`，`status='running'` 且 `updated_at`（或 `startedAt`）早于**本次进程启动时间**的行，判定为孤儿（整个进程树都被换过一轮，不可能有真实进程还在跑它）。判定后按 **`infra_flake` 语义**处理，不发明新状态——原地重跑逻辑本来就是为"基础设施打断，跟设计/实现对不对无关"这类场景设计的，服务器重启只是这个桶里更严重的一个成员。复用 `graph-engine.js` 已有的 `routeFailure` 里 `INFRA_FLAKE_REASON` 那条分支，不用另起一套判定/熔断逻辑。 - -**落点**：`server/index.js` 启动流程（挂在 `resumeIncompleteTasks()`/`sweepStuckActiveGoals()` 同一批"开机补一次全量扫描"的地方，跟这些既有钩子形状一致），加一个 `sweepOrphanedRunningNodes()`；判定逻辑放 `graph-engine.js` 或 `work-graph-db.js`（参照 `infra_flake` 现有实现挂在哪个文件）。 - -**验收**：新增测试——起一个 `status='running'`、`startedAt` 早于"当前进程启动时间"的节点，跑一次 `sweepOrphanedRunningNodes()`，断言它被转成 `infra_flake` 路径能处理的状态，且不影响 `startedAt` 晚于启动时间的正常运行节点。 - -### 1b. "强制判失败以便恢复"的 REST 端点 - -**现状**：`POST /:id/nodes/:nodeId/retry` 只接受 `status ∈ {fail, blocked}` 的节点。真实测试里遇到一个卡住的 `running` 节点，唯一的恢复手段是**直接写一段脚本调用 `graph-run-sse.transitionNode` 内部函数**，绕过了任何 REST 接口——这对人类操作者或 `ceo` 都不现实，两者都只能走 HTTP。 - -**设计**：新增 `POST /api/graph-runs/:id/nodes/:nodeId/force-fail`，语义是"我确认这个节点已经不可能再自己完成了，把它判成 `fail`（`failReason` 可选，默认某个通用值如 `operator_intervention`），交给既有的 fail→retry/backward-edge 路径处理"。**只接受 `status='running'` 的节点**（`fail`/`blocked` 已经有 `retry` 端点了，不重复造轮子）；调用方是人类还是 `ceo` 不做区分，鉴权走已有的 `requireAuthOrInternal`（跟着 Phase 1a 一起补，`graph-run.js` 这次已经全部换过了）。1a 落地后，这个端点的日常触发频率应该会显著下降（大部分"卡住"场景 1a 已经自动兜底），但保留它作为人工/`ceo` 判断"这个不是重启造成的，就是卡了"时的手动出口。 - -**验收**：新增测试——`running` 节点调 `force-fail` 转 `fail` 且可被 `retry` 端点接上；`fail`/`blocked`/`pending` 状态调用返回 400（沿用 `ensureStatus` 现成的错误形状）。 - ---- - -## 三、Phase 2：§四.4 闸门穿透性回归测试 —— ✅ 已实现（2026-08-30） - -**落地结果**：新建 `server/tests/unit/ceo-created-task-gates.test.js`，3 例全部走 `ceo` 实际会用的通路（`POST /tasks` 的 `draft:true` + `created_by:'ceo'` → `/enqueue`，不抄近道直接摆数据库行）： -1. `max_parallel_tasks=1` 时坑已占满，`ceo` 建的第二条任务落 `queued`，不插队。 -2. 预算给 `total_agent_calls:0`，`engine.checkBudget()` 照样判耗尽，`created_by='ceo'` 不改变结果。 -3. `ceo` 建的两条 task 挂在同一个 goal 下，全部 `completed` 后 `goal-validation` 的 `validateGoal` 钩子只被调一次（用 `validation.setValidateGoal()` 注入假验收，照抄 `goal-task-acceptance.test.js` 的既有手法）。 - -全量测试 1486/1490，零回归（剩余 4 个是核实过的 pre-existing 失败）。 - -**过程小插曲**：驱动第二条 task 的 run 出队时，先试了直接调 `task-scheduler.tick()`——撞上一个跟这次改动无关的既有工具链毛刺（`require.cache` 手工失效对 vitest 的 CJS 模块图不完全生效，`task-scheduler.js` 惰性 `require` 的 `work-graph-db` 引用有时会绑定到清缓存之前的实例，触发 `graph-db.js` 的"测试进程别碰生产库"守卫）。绕开的办法是不依赖 `scheduleTick` 的 `setImmediate` 时序，坑空出来后直接调 `updateRunStatus(runB,'queued','ready')`——这条路径本来就是准入事务的真实实现，只是不经过调度器这层编排，测试意图（"闸门拦不拦得住"）不受影响。 - -**现状**：39 号文档 §四.4 已拍板"`ceo` 全权自主 `enqueue`，但 `max_parallel_tasks`/`DEFAULT_TASK_BUDGET`/goal 级 `org-validator` 这几道闸门必须照样拦住它"，落地时没有补这条测试（§六"已知遗留"记过一笔）。理论上这几道闸门挂在数据层/调度器层，不认"谁创建的"，天然覆盖，但没有测试钉死就不能说"已确认"。 - -**设计**：不涉及任何设计决策，纯粹是补测试。新增用例（大致形状，落地时按现有测试文件的辅助函数抄写法）： -1. 把公司 `max_parallel_tasks` 设成 1，已有一条 task 占着坑，`ceo` 走 `draft`+`enqueue` 建第二条——断言它排队而不是插队执行。 -2. 把公司 `DEFAULT_TASK_BUDGET` 设小，`ceo` 建的任务跑到预算耗尽——断言按现有 `budget-exhausted` 路径 `blocked`，不会因为"是 agent 建的"就获得额外预算。 -3. `ceo` 建的多 task goal 全部 `completed` 后，断言 goal 级 `org-validator` 照样被调一次（不因创建者是 agent 而跳过收敛验收）。 - -**落点**：新建 `server/tests/unit/ceo-created-task-gates.test.js`，或并入现有 `task-blocked-ceo-wake.test.js`（按当时哪个更顺手）。 - ---- - -## 四、Phase 3：`target_dir` 的 API/UI 入口 —— ✅ 已实现（2026-08-30） - -**落地结果**： -- 后端复用了已存在的 `PUT /api/company/:companyId`（`companyService.update()`），没有新建端点——设计里"如果已存在就扩展"这条命中了。`update()` 新增 `target_dir`/`target_mode` 分支，校验直接调 `path-resolver.validateLinkedTarget`（39 号文档 P5 抽出来的共享函数，和 `graph-engine.js` 运行时校验同一份判据），校验失败抛出，路由层 `try/catch` 转 400；`target_dir` 传空字符串清空配置；不传 `target_mode` 时默认 `linked-existing`，与 `graph-engine.js` 的 `readCompanyTargetConfig` 同一口径。测试：`server/tests/unit/company-target-dir-config.test.js`（8 例：`linked-existing`/`linked-new` 各自成功路径、默认 mode、敏感路径黑名单、`linked-new` 非空目录、`linked-existing` 不存在、清空配置、公司不存在）。 -- 前端：`CompanyDashboard.vue` 的"概览"tab 加一张卡片（目标目录输入框 + 模式下拉 + 保存按钮），本地表单状态不直接双向绑定 `selectedCompany`（保存失败时不该让用户刚打的字被冲掉）。 - -**验证方式的取舍**：`npm run web:build` 编译通过 + 后端测试直接打真实路由层（不 mock service）。**没有做真实浏览器点击验证**——当时服务器上有其它并行会话真实在跑的 agent 进程（`ps` 能看到 3 个 `claude` 子进程），而重启服务器才能让后端改动生效，42 号文档 §二 已经记过一次"重启服务器杀掉别人真实进程"的教训，这次选择不重复。**这是一个已知的验证缺口，不是"做完了"**，下次服务器有安全窗口（没有并行会话在跑真实进程）时应该补一次真实点击验证。 - ---- - -**现状**：P5 落地的是"配了 `company.json.target_dir` 就生效"这一半，"人怎么把这两个字段填进去"这一半没做——真实测试里是手工编辑公司态目录下的 JSON 文件配的。 - -**设计**： -- **后端**：`PATCH /api/company/:companyId`（如果这个端点已存在就扩展，不存在就新建）接受 `target_dir`/`target_mode`，写回 `company.json`。校验复用 `path-resolver.js` 的 `validateLinkedTarget`（39 号文档 P5 已经抽出来的共享校验函数），配置阶段就能提前报错（不用等到第一次 `ensureProjectRoot` 才发现路径不对）。 -- **前端**：公司设置页面（或 `TaskBoard.vue`/`GraphConsole.vue` 附近，具体挂哪个页面待定）加一个表单，填目录路径 + 选 `linked-new`/`linked-existing`。 - -**验收**：新增测试覆盖 `PATCH` 端点的校验分支（合法路径写入成功、`isSensitivePath` 命中黑名单拒绝、`linked-new` 目录非空拒绝）；前端至少过一次真实点击验证表单能提交成功。 - ---- - -## 五、Phase 4：`timeline.ndjson` 承接 planning/reflection 轨迹 —— ✅ 已实现（2026-08-30） - -**调研结论（落地前按设计要求先做的那一步）**：`grep` 全仓库 `system/agents/*/agent.md`，引用 `task transition` 的有 9 个真实角色（`_base`、`code-planner`、`coder`、`org-coder`、`org-planner`、`org-writer`、`pricing-api-integrator`、`unit-tester`、`workgraph-planning`，另有几个 `zz-*` 测试夹具不算）。**`_base` 在列**——这是所有新建 agent 复制的骨架模板，意味着这条能力管的不是几个角色的特例，是整个"多阶段流转"这一类角色的通用约定，往后任何继承 `_base` 的新角色自动适用。 - -**关键发现，决定了整个实现方式**：`AgentManager.callAgent()` 的 `metadata`（含 `taskId`/`nodeRunId`/`rootRunId`）**只进服务端日志和 hook，agent 读不到**（代码原文注释）。但 agent 的节点私有产物目录本来就以 `data/companies/{cid}/runs/{rootRunId}/nodes/{nodeRunId}/` 这个形状写进它的提示词（`describeArtifactContract`），而 `--artifact` 参数本来就是这个目录下的文件路径——**两个 ID 已经现成地编码在调用方唯一知道、唯一会传的那个参数里**，不需要给 `AgentManager`/子进程塞任何新的环境变量，也不需要改一个字的 agent.md 提示词。 - -**实现**（与设计里"两种做法二选一"对应：选的是**不改 `bin/lemon.js` 的 CLI 签名、不碰 `agent-chat.js`**这条更保守的路）： -- `bin/lemon.js` 的 `task transition` 命令保持原有对 `/agent/:agentId/task/transition`（legacy）的调用完全不变，额外 best-effort 打一次新端点 `POST /api/graph-runs/phase-note`（body 只传 `artifact`/`phase`/`agentId`），失败静默吞掉，不影响命令本身的返回值/退出码。 -- 新端点从 `artifact` 路径正则解出 `rootRunId`/`nodeRunId`，校验 `rootRunId` 对应真实存在的 run（不存在就是 legacy 会话式调用的路径形状，安静返回 `not-a-graph-artifact`，不是错误），校验通过后调 `graph-run-sse.emitEvent()` 追加一条 `kind:'agent.phase'` 的 timeline 记录，`ref` 是 `nodeRunId`。 -- **`agent-chat.js` 完全没有改动**——这次特意避开了它：落地当天这个文件正被另一个并行会话实时编辑（`git status` 显示未提交修改），去碰一个正在被别人改的共享文件风险太高，改成把新能力放进这次 Phase 1-3 已经在用的 `graph-run.js`，物理上不产生交集。 -- **"不改的部分"边界确认成立**：新端点只调 `emitEvent`（纯追加 timeline，`apply` 传 `null`），不碰 `graph_run_nodes`/`graph_runs` 任何一行——测试里断言了这一点（节点状态在调用前后不变）。 -- **设计里 open 的第三个问题（P0 拦截/OKR 更新怎么处理）就此关闭**：答案是"完全不动"——这两段逻辑挂在 legacy `/task/transition` 里，图执行场景下（`sessions` Map 找不到会话）本来就从没触发过，这次也没打算让它们触发；新端点是完全独立的第二条路径，不是对旧端点的迁移或替换。 - -**测试**：`server/tests/unit/graph-run-phase-note.test.js`（4 例：合法节点产物路径写进 timeline 且节点状态不受影响、路径形状不对时安静跳过、路径形状对但 run 不存在时安静跳过、没传 artifact 时报 `no-artifact`）。全量测试 1503/1506，零回归（剩余 3 个失败全部来自另一个并行会话正在进行中、还没提交的工作）。 - -**现状（真跑撞到的，这是四个 phase 里最大的一个）**：`org-coder` 的四段式（RESEARCH→PLAN→EXECUTE→VERIFY）流转靠调 `bin/lemon.js task transition`，打到 `agent-chat.js` 的 `/task/transition` 端点——这个端点靠自己的 `sessions` Map 找"当前活跃会话"，但 `org-coder` 作为 work graph 节点跑的时候走的是 `graph-engine.js` → `AgentManager` → `session-pool.js`，是 CLAUDE.md 里早就记录过的"两个互不相干的会话池"那个坑的又一个受害者。结果：`org-coder` 在 work graph 里调这条流转指令时，`sessions.entries()` 根本找不到它的会话，阶段流转的业务逻辑（P0 审批拦截、OKR 子状态更新）**静默跳过**；它的中间产物（`_research.md`/`_plan.md`/`_lessons.md`）不进 `graph_files` 契约（这个是刻意的，见下"不改的部分"），但也**不进任何跨节点/跨角色共享的轨迹**，人类或 `ceo` 事后想搞清楚"这一步当时是怎么想的"，只能去读原始的 agent 会话 transcript（`GET /:id/nodes/:nodeRunId/transcript`），没有结构化的入口。 - -**不改的部分（上一轮已经讨论定案，写在这里防止实现时跑偏）**： -- `_plan.md` 这类中间产物**不进 `needs`/`produces` 契约**，`org-validator` 判定依据仍然只认 `acceptance.md` + `artifact`/`log`。理由：validator 判定"代码对不对"，不该依赖"coder 计划写得像不像样"，这条边界一旦模糊，两个坏结果都会发生——coder 学会把计划写漂亮而不是把代码写对；`graph_files` 的契约面失控（这个仓库反复栽在"两套体系不统一"上）。 -- 本 phase 只解决**可见性**（人类/`ceo` 事后能不能追溯），不解决**契约**（下游节点该不该依赖）——这是两件事，上一轮讨论已经拆开过。 - -**设计**（需要先做的调研，落地前必做）： -1. **调研范围**：`org-coder` 是这次撞到的一个，不代表只有它——扫一遍 `system/agents/*/agent.md` 里还有哪些角色的提示词也在调 `bin/lemon.js task transition`，把范围摸清楚再动手，不要只按 `org-coder` 这一个样本改。 -2. **迁移方向**：把"阶段流转"这个动作，从打 `agent-chat.js` 的 `/task/transition`（legacy，不认 graph run），改成写一条 `timelineNote()`（`graph-engine.js` 已有机制，per-run、append-only、永不改已写行），带上 `phase`（research/plan/execute/verify 或角色自定义的阶段名）+ `artifact` 路径。**具体是改 `bin/lemon.js task transition` 这条命令本身去打新端点，还是给它接一条新命令**，两种做法都要过一遍现有 agent 提示词的改动成本再定——这些提示词文件散在几十个 `agent.md` 里，改一条命令的调用方式等于牵动所有引用它的本体。 -3. **P0 审批拦截 / OKR 子状态更新这两块旧逻辑怎么处理**：`/task/transition` 里现在还挂着 P0 任务拦截、OKR 子状态更新这两段业务逻辑——这两者本身是不是还需要（尤其 OKR 那段，跟 P3C 的新 goal/task 模型是不是还有效对应），需要单独判断，不能假设"迁移流转机制"就等于"这两段逻辑原样照抄"。 - -**验收**（待设计细化后补全，这里先占位）：至少要有一条测试证明——`org-coder`（或调研出的任意一个角色）在 work graph 里完成一次阶段流转后，`timeline.ndjson` 里能查到对应的 `phase`+`artifact` 记录，且这条记录不影响 `graph_files`/`needs`/`produces` 的既有行为（回归测试守住"不改的部分"那条边界）。 - ---- - -## 六、开放问题 - -1. Phase 1a 的孤儿判定条件（`startedAt` 早于进程启动时间）在多进程/多副本部署下是否还成立？现在是单进程部署，这条先按当前架构写，多副本场景不在这次范围内。 -2. Phase 3 的 `PATCH /api/company/:companyId` 端点如果本来就不存在，是新建这一个端点，还是这次顺手看一下公司配置类的改动有没有更合适的既有入口——落地前查一遍 `company.js` 现状再定，不在这里预判。 -3. Phase 4 的调研如果发现有 10+ 个角色都在用旧的 `/task/transition`，工作量会明显超出"一个 phase"的量级，届时可能需要再拆细——先按"调研完再评估"处理，不在这里预先估工作量。 -- libgit2 0.21.4