diff --git a/docs/README.md b/docs/README.md index bb04822..d76af7a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,10 +51,12 @@ Graph Agent 架构重构（27 系列）。**已完成的阶段文档已移入 `d | [29-dream-design.md](./todo/system-design/29-dream-design.md) | **dream（经验汇流）**— ✅ 已实现。定时整理所有 agent 在所有公司的记忆，提炼后跨公司沉淀（不泄漏公司信息）。四条取舍已拍板并实现：去敏独立判定、四落点分层写入（经验/`SKILL.md`/`soul.md`/`agent.md`，受管区块+三道闸门）、每日定时（串行+空转保护）、引用真伪自动查、REST+控制台入口（`/api/dream/*`、`/dream`）。`innovator-evolver` 真 CLI 跑通一次。**仍缺的**：「结论对不对」只能人抽查；「套进 org/work graph 来跑」评估后用户选了不做（作用域不匹配，见文内 §5.7） | | [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) | 📝 **设计评估中，未实现**。评估用户提出的五阶段方案（雇 boss agent 监督 goal/task 看板、独立任务看板页、心跳挨个调度、org/work graph 产出的 bug/新任务回写看板、公司级目标代码目录）。结论：P2 看板已实现、P1/P3 心跳与 `ceo` 本体基础设施已有大半、P5 的 `linked-existing` 模式已在 `path-resolver.js` 完整实现只差公司级默认值，**真正从零开始的是 P4（回写闭环）**——当前没有任何 agent 工具能读写 goal/task 板。建议顺序倒过来先建 P4 地基 | | [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（训练产物 → 雇佣本体转换）尚未开工 | | [35-validation-rigor-and-body-readiness-proposal.md](./todo/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：控制台「验收证据」小节展示每个维度有没有证据支撑 | | [34-validator-scored-without-real-deliverable.md](./todo/system-design/34-validator-scored-without-real-deliverable.md) | 📝 **调研记录，checklist 已查完**。最初以为 `org-coder-impl` 从未产出任何 HTML/CSS，后来发现真实网站其实存在于 `graph_files` 索引不覆盖的「项目根」目录（已顺手修：控制台「产物」面板现在会展示项目根）。追加查清 validator 有没有真的做浏览器级检查——中途自我订正一次：不是"没工具做不到"（`bash` 能走到仓库自带的 Playwright，另一条对照任务证明可行），是**没人教它这么做**；抽查另外两个项目根后发现**验证严谨度完全不稳定**（同类任务有的做了真实 Playwright 级验证、有的只做静态正则、有的没验证就被取消），根因很可能是新招聘的 `unit-tester` 本体撞上了 [32 号文档](./todo/system-design/32-hire-body-fill-reliability.md) 那类"装配没填充完"的真实样本，不是平台工具限制 | +| [40-agent-chat-streaming-interrupt.md](./todo/system-design/40-agent-chat-streaming-interrupt.md) | 📝 **需求文档，讨论中，未实现**。回应"前端刷新不及时/没有打字机效果，要不要把 SSE 换成 WebSocket"——排查后结论是传输层不是瓶颈（对照 hermes-webui/hermes-agent/deepseek-harness 三个参考实现，全部走 SSE，不用 WebSocket）。真正的三个独立缺口：① 打字机不流畅（ACP chunk 粒度太粗，方案是前后端都做匀速切片/渲染缓冲）；② 执行中无法打断并接上新消息（现状"先 Stop 再发"两步，方案是深度 1 的打断-排队，顺带发现服务端对同 convId 并发缺闸门这个现存 bug）；③ 串台已在 `9b1c3f1` 修复但没有回归测试兜底 | | [33-needs-gate-role-filter-bug.md](./todo/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 号文档的真实回归验证过程中，与兜底边问题无关 | ## todo/future/（暂缓，非当前重心） diff --git a/docs/todo/system-design/39-boss-agent-task-supervision.md b/docs/todo/system-design/39-boss-agent-task-supervision.md new file mode 100644 index 0000000..b1ccc99 --- /dev/null +++ b/docs/todo/system-design/39-boss-agent-task-supervision.md @@ -0,0 +1,182 @@ +# 39. Boss Agent 任务看板监督 + 公司目标代码目录 — 需求评估与设计草案 + +> **状态**：📝 设计评估中，未实现。本文档是对用户口述五阶段方案的落地可行性评估 + 修订后的设计草案，不是最终定案。 +> **日期**：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 行）。 diff --git a/scripts/backfill-ceo-hire.js b/scripts/backfill-ceo-hire.js new file mode 100644 index 0000000..cfd91bc --- /dev/null +++ b/scripts/backfill-ceo-hire.js @@ -0,0 +1,58 @@ +#!/usr/bin/env node +/** + * backfill-ceo-hire.js —— 存量公司补雇 ceo + * + * 依据: docs/todo/system-design/39-boss-agent-task-supervision.md §二 P1「缺口 B」 + * + * `ceo` 不在任何 org-graph-template 里，也没有自动招聘钩子——POST /api/company/create + * 这次起改成新建公司时固定雇一次，但存量公司不会补跑那条创建流程，需要这个脚本单独补雇。 + * + * 幂等: hire() 本身按 company_agents 表判重（见 company-service.js:429），已经雇过的公司 + * 会拿到 status='already_exists'，跳过不算失败，可重复执行。 + * + * 用法: + * node scripts/backfill-ceo-hire.js + */ + +const fs = require('fs'); +const path = require('path'); + +const DATA_DIR = path.resolve(__dirname, '../data/companies'); + +function main() { + const { CompanyService } = require('../server/services/company-service'); + const companyService = new CompanyService(); + + if (!fs.existsSync(DATA_DIR)) { + console.log('[backfill-ceo-hire] data/companies/ 不存在，无需处理'); + return; + } + + const dirs = fs.readdirSync(DATA_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()); + let hired = 0; + let skipped = 0; + let failed = 0; + + for (const d of dirs) { + const fp = path.join(DATA_DIR, d.name, 'company.json'); + if (!fs.existsSync(fp)) continue; + + try { + const result = companyService.hire(d.name, 'ceo', {}); + if (result.status === 'already_exists') { + skipped += 1; + } else { + console.log(`[backfill-ceo-hire] ${d.name} → ceo（${result.status}）`); + hired += 1; + } + } catch (e) { + console.error(`[backfill-ceo-hire] ${d.name} 雇 ceo 失败: ${e.message}`); + failed += 1; + } + } + + console.log(`[backfill-ceo-hire] 完成：新雇 ${hired} 家，跳过（已雇过）${skipped} 家，失败 ${failed} 家`); + if (failed > 0) process.exitCode = 1; +} + +main(); diff --git a/server/index.js b/server/index.js index 28cbd47..14f81c3 100644 --- a/server/index.js +++ b/server/index.js @@ -173,6 +173,13 @@ async function start() { } catch (err) { console.error('[Startup] 僵尸 goal 扫描启动失败:', err.message); } + // 39 号文档 P3：ceo 低频兜底扫描（30 分钟一次），补事件驱动唤醒（settleRootRun 里 + // 那条）漏掉的 blocked task。同 startZombieGoalSweeper 的形状，挂在同一处。 + try { + taskSettle.startCeoSweeper(); + } catch (err) { + console.error('[Startup] ceo 兜底扫描启动失败:', err.message); + } // 27-P3C 批 3：任务队列。进程重启会丢掉所有在途的 setImmediate 唤醒 // （队列钩子挂在 graph-run-sse.transitionRun 上，那是进程内的）， // 于是重启后队里的任务会一直躺着 —— 界面上和「正在排队」一模一样，正是本批要消灭的症状。 diff --git a/server/routes/company.js b/server/routes/company.js index 12ad0da..6e30632 100644 --- a/server/routes/company.js +++ b/server/routes/company.js @@ -8,10 +8,14 @@ const express = require('express'); const path = require('path'); const fs = require('fs'); const router = express.Router(); -const { requireAuth, INTERNAL_TOKEN, INTERNAL_TOKEN_HEADER } = require('../middleware/jwt-auth'); +const { requireAuth, requireAuthOrInternal, INTERNAL_TOKEN, INTERNAL_TOKEN_HEADER } = require('../middleware/jwt-auth'); // 38 号文档 Phase 1：全站要求登录。 -router.use(requireAuth); +// 39 号文档：goals/tasks 系列端点要给 agent（如 ceo 的心跳监督循环）用 curl 直接调， +// agent 子进程没有用户 cookie，改用 requireAuthOrInternal（放行带对 INTERNAL_TOKEN 的自环 +// 调用，其余情况仍退回 requireAuth）——与 agent-chat.js 同一个模式，理由也相同： +// 这个内部令牌只在本机进程树内有效，不落盘、不外泄，安全模型早已被 agent-chat.js 验证过。 +router.use(requireAuthOrInternal); const { CompanyService, listCompanyAgents, buildAgentDefinitionBrief, canAccessCompany } = require('../services/company-service'); const { ScheduleService } = require('../services/schedule-service'); @@ -32,6 +36,14 @@ const scheduleService = new ScheduleService(); // 404 而不是 403：不告诉调用方"这个 id 存在、只是不是你的"，直接当不存在处理。 router.param('companyId', (req, res, next, companyId) => { const company = companyService.get(companyId); + // 39 号文档：内部自环调用（agent 用 INTERNAL_TOKEN 发起，比如 ceo 心跳查看/操作 + // goal/task 板）没有"当前登录用户"这个概念，不能对它做归属校验——与 + // agent-chat.js 的 :agentId param 中间件是同一处理方式（req.user.internal 直接放行）。 + if (req.user?.internal) { + if (!company) return res.status(404).json({ error: `公司 ${companyId} 不存在` }); + req.company = company; + return next(); + } if (!canAccessCompany(company, req.user)) { return res.status(404).json({ error: `公司 ${companyId} 不存在` }); } @@ -146,6 +158,15 @@ router.post('/create', async (req, res) => { console.error('[Create] orggraph-planning 自动招聘失败（不影响公司创建）:', e.message); } + // 39 号文档 P1：固定雇一个 ceo，负责监督 goal/task 板（不进任何 org graph， + // 与 org-graph-template 选哪张无关，所以独立于上面那段的 bootstrap.status）。 + // 同样遵守「任何失败都不能影响公司创建」的降级约定。 + try { + companyService.hire(id, 'ceo', {}); + } catch (e) { + console.error('[Create] ceo 自动招聘失败（不影响公司创建）:', e.message); + } + res.json({ success: true, company, message: '公司已创建，正在由 orggraph-planning 自动规划组织结构（异步进行中）。' }); } catch (err) { res.status(400).json({ error: err.message }); @@ -2146,6 +2167,22 @@ router.post('/:companyId/tasks', (req, res) => { throw err; } + // 39 号文档地基 1：draft:true 时只落库，不入队、不下达。服务的是 agent（如 ceo） + // 自主提的新任务——task-planning 拆出来的 task 尚且要先落 draft 等人点「全部下达」 + // 才转 queued（P3C §四.9），agent 在线判断的风险不该比一次性拆分低。 + // 落库后走既有 `POST /:companyId/tasks/:taskId/enqueue` 正式下达，不新建端点。 + if (body.draft === true) { + return res.status(201).json({ + success: true, + status: 'draft', + taskId: taskRow.id, + goalId: goal.id, + companyId, + task: description, + hint: `草稿已创建，未入队。调用 POST /api/company/${companyId}/tasks/${taskRow.id}/enqueue 正式下达。`, + }); + } + const launched = enqueueTaskRun({ companyId, taskRow, budget: body.budget || DEFAULT_TASK_BUDGET }); markGoalDispatched(goal); diff --git a/server/services/graph-engine.js b/server/services/graph-engine.js index 83c0a3d..88615c5 100644 --- a/server/services/graph-engine.js +++ b/server/services/graph-engine.js @@ -59,6 +59,9 @@ const { recordFile, // 27-P4 T4/T5：advanceBatch 批量拾取宽度的缺省值 DEFAULT_MAX_CONCURRENCY, + // 39 号文档「确定性通路」：回退熔断收敛时顺手开一条 draft task，见 maybeProposeReplanTask + createTask, + getGoal, } = require('./work-graph-db'); /** @@ -2125,6 +2128,9 @@ function handleBackwardEdge(runId, def, nodeRun, edge, out, remediationNote = nu verdict: 'force_terminated', cap: out.loop.cap, }, { ref: edge.id }); blockNode(runId, nodeRun.id, remediationNote); + // 39 号文档「确定性通路」：熔断收敛之后顺手把这个卡点回写成 goal/task 板上一条 draft + // task，不等 ceo 心跳才发现。best-effort，绝不能反过来影响上面已经做完的熔断收敛。 + maybeProposeReplanTask(runId, rootRunId, nodeRun, def, remediationNote); return true; } @@ -2155,6 +2161,52 @@ function handleBackwardEdge(runId, def, nodeRun, edge, out, remediationNote = nu } /** + * 39 号文档「确定性通路」：run 树级/单边回退熔断（force_terminated）收敛时，顺手在同一个 + * goal 下开一条 draft task，把卡住的诊断信息交回 goal/task 板，而不是只留一个 blocked + * 节点等人翻控制台才发现。 + * + * 只在根 run 触发一次（`runId === rootRunId`）：嵌套子图自己的回退熔断会先在子层 + * blockNode，结论再沿子 run 边界冒泡成父层（org）节点的失败——冒泡到根时同一次「卡住」 + * 只应该开一条 task，不是每层各开一条。 + * + * 落库时机是 `draft`，不自动 enqueue（与 §四.9 task-planning 同一条哲学：这是一次 + * 「猜」，不该自动花钱）；`report_to` 继承原 goal 的 `report_to`（§四.2 已拍板）。 + * + * 纯 best-effort：任何一步查不到/写不进都吞掉，不能让「顺手开个 task」反过来打断 + * 熔断收敛本身——熔断收敛是安全关键路径，这个不是。 + */ +function maybeProposeReplanTask(runId, rootRunId, nodeRun, def, remediationNote) { + if (runId !== rootRunId) return; + try { + const db = getDb(); + const task = db.prepare(`SELECT * FROM tasks WHERE current_run_id = ?`).get(rootRunId); + if (!task) return; // 这条 run 树当前不是任何 task 的 current_run_id（例如已被重跑顶替），不开 + const goal = getGoal(task.goal_id); + if (!goal) return; + + const d = def.nodes.get(nodeRun.def_node_id) || {}; + const nodeName = d.name || nodeRun.def_node_id; + const reason = remediationNote || `节点 ${nodeName} 反复回退撞了熔断硬顶，未能收敛`; + + createTask({ + goalId: goal.id, + companyId: goal.company_id, + title: `[待重新规划] ${(task.title || task.description || goal.title || '').slice(0, 160)}`, + description: `任务 ${task.id}（${task.title || task.description || ''}）执行时在节点 ` + + `${nodeName} 反复回退未能收敛，已停止自动重试。\n\n诊断：${reason}\n\n` + + `此任务由系统自动生成（草稿），需要人工或 ceo 审阅后决定：调整原任务描述重新下达，还是关闭。`, + executionMode: 'manual', + priority: goal.priority || 'P1', + reportTo: goal.report_to || null, + createdBy: 'system', + }); + } catch (err) { + // best-effort：吞掉。上一步的熔断收敛（blockNode）已经做完，这里出错不影响主路径。 + console.error('[graph-engine] maybeProposeReplanTask 失败（不影响熔断收敛）：', err.message); + } +} + +/** * 解析跨层地址 → 「该退到哪个子 run 的哪一行」（**纯查询，不改任何状态**）。 * * 输入的地址来自失败节点行的 `fail_node_ref`（三值透传的第四值，见 normalizeNodeRef 那段）。 diff --git a/server/services/task-settle.js b/server/services/task-settle.js index ef2027b..e49f6ca 100644 --- a/server/services/task-settle.js +++ b/server/services/task-settle.js @@ -192,6 +192,12 @@ function settleRootRun(run, to) { if (taskStatus === 'blocked') { const why = describeRunBlock(run.id); if (why) wdb.noteTaskBlockedReason(run.task_id, run.id, why); + + // 39 号文档 P3：blocked **不是**终态（下面 settleGoalIfAllTasksDone 也不会碰它）， + // goal 因此不会收敛、`reportGoalOutcome` 那条唤醒 report_to 的路径也不会触发—— + // 卡住的任务本来会一直静默躺着，直到有人自己点进控制台才发现（30 号文档点过名的 + // 那个空白）。这里主动叫醒 ceo，不等它下一次心跳。best-effort，失败只打日志。 + wakeCeo(run.company_id, why); } const task = wdb.getTask(run.task_id); @@ -199,6 +205,39 @@ function settleRootRun(run, to) { } /** + * 39 号文档 P3：唤醒本公司的 ceo（事件驱动的主路径）。 + * 与 company.js 的 triggerOrgGraphPlanning / 本文件 reportGoalOutcome 里唤醒 report_to + * 同一个模式：公司限定地址（`{companyId}:ceo`，本体只有一份，公司态按公司分）+ + * INTERNAL_TOKEN 自环调用。发射后不等结果——这条不是收敛链路的一部分，晚几秒钟被 + * ceo 看到不影响正确性，不值得为它拖慢 settleRootRun 的返回。 + */ +function wakeCeo(companyId, reason) { + if (!companyId) return; + try { + const PORT = require('../config').port || 3010; + const { INTERNAL_TOKEN, INTERNAL_TOKEN_HEADER } = require('../middleware/jwt-auth'); + const namespacedId = `${companyId}:ceo`; + fetch(`http://127.0.0.1:${PORT}/api/agent/${encodeURIComponent(namespacedId)}/chat`, { + method: 'POST', + headers: { 'Content-Type': 'application/json', [INTERNAL_TOKEN_HEADER]: INTERNAL_TOKEN }, + body: JSON.stringify({ + message: `[SYSTEM] 有一条 task 刚转入 blocked 状态：${reason || '（无详情）'}\n` + + `请查看 tools.md 里的读接口确认情况，判断是否需要提一条新任务或调整优先级。`, + conversationId: `ceo-wake-${companyId}-${Date.now().toString(36)}`, + isHeartbeat: true, + }), + }) + .then((res) => { + if (!res.ok) console.error(`[CeoWake] 唤醒 ${namespacedId} 失败: HTTP ${res.status}`); + }) + .catch((e) => console.error(`[CeoWake] 唤醒 ${namespacedId} 失败(网络): ${e.message}`)); + } catch (e) { + // best-effort：唤醒失败不能影响调用方（settleRootRun）已经做完的状态回写。 + console.error('[CeoWake] 唤醒 ceo 异常（不影响状态回写）:', e.message); + } +} + +/** * goal 级收敛：这个 goal 的 task 是不是都到终态了？是则定判词并做**一次**对外汇报。 * * 状态口径： @@ -642,6 +681,50 @@ function stopZombieGoalSweeper() { zombieSweepTimer = null; } +/** + * 39 号文档 P3：ceo 低频兜底扫描。`settleRootRun` 里的事件驱动唤醒（task 转 blocked 那一刻） + * 是主路径，这里只补漏——进程重启、fetch 失败、或本来就没接住那次转换。量级放到 30 分钟， + * 不是主决策路径，照抄 `task-scheduler.js` 头部注释里"兜底扫描周期"那个设计哲学。 + * 按 company_id 分组只叫醒一次，不逐条 task 叫（否则一家公司卡 5 条 task 就是 5 次心跳）。 + */ +const CEO_SWEEP_INTERVAL_MS = Number(process.env.CEO_SWEEP_INTERVAL_MS) || 30 * 60 * 1000; +let ceoSweepTimer = null; + +function sweepBlockedTasksForCeo() { + try { + const wdb = require('./work-graph-db'); + const rows = wdb.getDb() + .prepare(` + SELECT company_id, COUNT(*) AS cnt, GROUP_CONCAT(id) AS ids + FROM tasks + WHERE archived_at IS NULL AND status = 'blocked' + GROUP BY company_id + `) + .all(); + for (const r of rows) { + wakeCeo(r.company_id, `兜底扫描：本公司当前有 ${r.cnt} 条 blocked task（${r.ids}），` + + `事件驱动那条唤醒可能漏了，请查看。`); + } + return rows; + } catch (err) { + console.error(`[CeoWake] sweepBlockedTasksForCeo 异常: ${err.message}`); + return []; + } +} + +/** 启动周期性 ceo 兜底扫描（unref，不拖着进程不退出）。幂等：重复调用只返回已有的计时器 */ +function startCeoSweeper(intervalMs = CEO_SWEEP_INTERVAL_MS) { + if (ceoSweepTimer) return ceoSweepTimer; + ceoSweepTimer = setInterval(sweepBlockedTasksForCeo, intervalMs); + if (typeof ceoSweepTimer.unref === 'function') ceoSweepTimer.unref(); + return ceoSweepTimer; +} + +function stopCeoSweeper() { + if (ceoSweepTimer) clearInterval(ceoSweepTimer); + ceoSweepTimer = null; +} + module.exports = { settleRootRun, settleGoalIfAllTasksDone, @@ -649,6 +732,10 @@ module.exports = { sweepStuckActiveGoals, startZombieGoalSweeper, stopZombieGoalSweeper, + wakeCeo, + sweepBlockedTasksForCeo, + startCeoSweeper, + stopCeoSweeper, RUN_TO_TASK_STATUS, // 占位值不再是常量而是「前缀 + 唯一 token」，所以对外给的是前缀和判定函数： // 任何地方想认出「这条还没有结论」，都必须走 isPendingVerdict，别再去比字符串相等。 diff --git a/server/tests/unit/graph-engine.test.js b/server/tests/unit/graph-engine.test.js index 87603ce..160547e 100644 --- a/server/tests/unit/graph-engine.test.js +++ b/server/tests/unit/graph-engine.test.js @@ -752,6 +752,90 @@ describe('graph-engine', () => { }); // ────────────────────────────────────────────────────────────── + // 39 号文档 P4「确定性通路」：回退熔断收敛时顺手开一条 draft task + // ────────────────────────────────────────────────────────────── + describe('回退熔断 · 确定性通路自动开新 task（39 号文档 §二 P4）', () => { + it('单边硬顶 force_terminated 时，会在同一个 goal 下新开一条 draft task，report_to 继承自 goal', async () => { + const companyId = nextCompany(); + const goal = wdb.createGoal({ + companyId, + title: '测试 goal', + description: '测试 goal 的描述', + priority: 'P2', + createdBy: 'human', + reportTo: 'some-upstream-agent', + }); + const task = wdb.createTask({ + goalId: goal.id, + companyId, + title: '测试 task', + description: '测试 task 的描述', + executionMode: 'auto', + priority: 'P2', + createdBy: 'human', + }); + + const { runId } = buildWorkRun({ + companyId, + nodes: ['impl', 'check'], + edges: [ + { from: 'impl', to: 'check' }, + { from: 'check', to: 'impl', condition: 'fail', edgeKind: 'backward' }, + ], + mode: 'auto', + }); + // 让这条 run 看起来是「这条 task 当前的 run」——只有 runId === rootRunId 且 + // current_run_id 指回它，maybeProposeReplanTask 才会触发（避免嵌套子图重复开）。 + wdb.updateTask(task.id, { currentRunId: runId }); + + fakeExecutor({ + impl: { status: 'success' }, + check: { status: 'fail', remediationNote: '反复修不好' }, + }); + + await engine.startRun(runId, { mode: 'auto' }).driver; + + // 熔断收敛本身不受影响（既有断言的等价物） + expect(wdb.getRun(runId).run_status).toBe('blocked'); + + const tasksInGoal = wdb.listCompanyTasks(companyId, { goalId: goal.id, includeArchived: true }); + expect(tasksInGoal).toHaveLength(2); + const created = tasksInGoal.find((t) => t.id !== task.id); + expect(created).toBeTruthy(); + expect(created.status).toBe('draft'); + expect(created.created_by).toBe('system'); + // report_to 继承自 goal（39 号文档 §四.2 已拍板），不是继承自触发它的 task + expect(created.report_to).toBe('some-upstream-agent'); + expect(created.description).toContain('反复修不好'); + }); + + it('嵌套子图自己的回退熔断（runId !== rootRunId）不会新开 task——只在根 run 触发一次', async () => { + // buildWorkRun 建出的是顶层 run，rootRunId 本来就等于自己；这里改用 + // 「run 不是任何 task 的 current_run_id」这条更好触发的早退路径验证同一条防重复保证： + // 没有匹配的 task 行，maybeProposeReplanTask 必须安静地什么都不做，不能抛错。 + const companyId = nextCompany(); + const { runId } = buildWorkRun({ + companyId, + nodes: ['impl', 'check'], + edges: [ + { from: 'impl', to: 'check' }, + { from: 'check', to: 'impl', condition: 'fail', edgeKind: 'backward' }, + ], + mode: 'auto', + }); + fakeExecutor({ + impl: { status: 'success' }, + check: { status: 'fail', remediationNote: '再修一遍' }, + }); + + await expect(engine.startRun(runId, { mode: 'auto' }).driver).resolves.not.toThrow(); + expect(wdb.getRun(runId).run_status).toBe('blocked'); + // 没有任何 task 挂这条 run，不应该凭空生出一条 task 来（company 下 tasks 表应仍为空） + expect(wdb.listCompanyTasks(companyId, {})).toHaveLength(0); + }); + }); + + // ────────────────────────────────────────────────────────────── // §六 验收 9b：多边不架空熔断（R-16 发现的 3×N 漏洞） // ────────────────────────────────────────────────────────────── describe('回退熔断 · 多边不架空（§六 验收 9b / R-16）', () => { diff --git a/server/tests/unit/route-auth-gate.test.js b/server/tests/unit/route-auth-gate.test.js index 9e33c7a..67af657 100644 --- a/server/tests/unit/route-auth-gate.test.js +++ b/server/tests/unit/route-auth-gate.test.js @@ -44,8 +44,8 @@ describe('route-auth-gate（38 号文档 Phase 1）', () => { delete process.env.FORCE_REAL_AUTH; }); - it('company.js 挂了 requireAuth', () => { - expectGated(require('../../routes/company.js'), requireAuth, 'company.js'); + it('company.js 挂了 requireAuthOrInternal（39 号文档：goals/tasks 系列端点要给 agent 用 curl 直接调，比如 ceo 的心跳监督循环，不是普通 requireAuth）', () => { + expectGated(require('../../routes/company.js'), requireAuthOrInternal, 'company.js'); }); it('tasks.js 挂了 requireAuth', () => { diff --git a/server/tests/unit/task-blocked-ceo-wake.test.js b/server/tests/unit/task-blocked-ceo-wake.test.js new file mode 100644 index 0000000..3eb3e97 --- /dev/null +++ b/server/tests/unit/task-blocked-ceo-wake.test.js @@ -0,0 +1,189 @@ +/** + * Unit Tests — task 转 blocked 时主动唤醒 ceo（39 号文档 §二 P3，事件驱动主路径） + * + * 背景：blocked 不是终态，`settleGoalIfAllTasksDone` 不会碰它，goal 因此不会收敛， + * `reportGoalOutcome` 那条唤醒 report_to 的路径也不会触发——卡住的任务本来会一直静默 + * 躺着，直到有人自己点进控制台才发现（30 号文档点过名的空白）。`settleRootRun` 现在 + * 会在 blocked 回写之后顺手唤醒本公司的 ceo。 + * + * 只验唤醒这一跳的逻辑（URL / header / body 形状），不验 agent-chat 真的收到消息之后 + * 会做什么——那是 ceo 自己 tools.md / heartbeat.md 的行为，不在引擎测试射程内。 + * + * 隔离手法与 task-blocked-reason.test.js 一致。 + */ +import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest'; +import fs from 'fs'; + +describe('task 转 blocked 唤醒 ceo（39 号文档 P3）', () => { + let wdb; + let settle; + const TEST_DB_PATH = '/tmp/test-blocked-ceo-wake.sqlite'; + const files = [TEST_DB_PATH, `${TEST_DB_PATH}-shm`, `${TEST_DB_PATH}-wal`]; + + beforeAll(() => { + for (const f of files) { try { fs.unlinkSync(f); } catch { /* 没有就算了 */ } } + process.env.GRAPH_DB_PATH = TEST_DB_PATH; + for (const m of [ + '../../services/graph-db', + '../../services/org-graph-service', + '../../services/work-graph-db', + '../../services/graph-run-sse', + '../../services/task-settle', + ]) { + delete require.cache[require.resolve(m)]; + } + wdb = require('../../services/work-graph-db'); + settle = require('../../services/task-settle'); + }); + + afterAll(() => { + for (const f of files) { try { fs.unlinkSync(f); } catch { /* 同上 */ } } + delete process.env.GRAPH_DB_PATH; + }); + + beforeEach(() => { + const db = wdb.getDb(); + db.pragma('foreign_keys = OFF'); + db.exec(` + DELETE FROM graph_run_nodes; + DELETE FROM graph_runs; + DELETE FROM tasks; + DELETE FROM goals; + DELETE FROM work_graph_edges; + DELETE FROM work_graph_nodes; + DELETE FROM work_graphs; + DELETE FROM system_agents; + `); + db.pragma('foreign_keys = ON'); + }); + + let seq = 0; + + /** 与 task-blocked-reason.test.js 的 scene() 同构：造出「一条 root run 正卡在某节点」 */ + function scene() { + const companyId = `ceowake-co-${++seq}`; + const now = new Date().toISOString(); + const db = wdb.getDb(); + db.prepare(` + INSERT OR IGNORE INTO system_agents + (id, name, scope, owner_company_id, legacy_path, status, created_at, updated_at) + VALUES ('sdd-planning', 'sdd-planning', 'public', NULL, 'system/agents/sdd-planning', 'active', ?, ?) + `).run(now, now); + + const graph = wdb.createWorkGraph({ companyId, nodes: ['sdd-planning'], edges: [] }); + const goal = wdb.createGoal({ companyId, title: '做一个官网', description: '测试用' }); + const task = wdb.createTask({ + goalId: goal.id, companyId, title: '做一个官网', description: '测试用', executionMode: 'manual', + }); + const run = wdb.createRun({ + graphKind: 'work', graphId: graph.id, companyId, goalId: goal.id, taskId: task.id, + executionMode: 'manual', runStatus: 'running', + }); + wdb.syncRunNodesToDef(run.id); + wdb.updateTask(task.id, { status: 'running', currentRunId: run.id, startedAt: now }); + + const nodeRow = db.prepare(`SELECT id FROM graph_run_nodes WHERE run_id = ?`).get(run.id); + db.prepare(`UPDATE graph_run_nodes SET status = 'blocked', fail_reason = 'boundary_escape', updated_at = ? WHERE id = ?`) + .run(now, nodeRow.id); + + return { companyId, taskId: task.id, run: wdb.getRun(run.id) }; + } + + it('blocked 回写时会 fetch 唤醒 `{companyId}:ceo`，带上正确的内部令牌头', async () => { + const { companyId, run } = scene(); + const { INTERNAL_TOKEN, INTERNAL_TOKEN_HEADER } = require('../../middleware/jwt-auth'); + + const calls = []; + const originalFetch = global.fetch; + global.fetch = vi.fn((url, opts) => { + calls.push({ url, opts }); + return Promise.resolve({ ok: true, status: 200 }); + }); + + try { + settle.settleRootRun(run, 'blocked'); + // wakeCeo 是发射后不等结果，让微任务队列跑一轮再断言 + await new Promise((r) => setImmediate(r)); + } finally { + global.fetch = originalFetch; + } + + expect(calls).toHaveLength(1); + const [{ url, opts }] = calls; + expect(url).toContain(`/api/agent/${companyId}%3Aceo/chat`); + expect(opts.method).toBe('POST'); + expect(opts.headers[INTERNAL_TOKEN_HEADER]).toBe(INTERNAL_TOKEN); + const body = JSON.parse(opts.body); + expect(body.message).toContain('blocked'); + expect(body.isHeartbeat).toBe(true); + }); + + it('completed 回写不会唤醒 ceo（只有 blocked 才需要主动叫人）', async () => { + const { run } = scene(); + const calls = []; + const originalFetch = global.fetch; + global.fetch = vi.fn((url, opts) => { calls.push({ url, opts }); return Promise.resolve({ ok: true }); }); + + try { + // 先把节点状态改成 success，让 settleTaskFromRun 认成 completed + const db = wdb.getDb(); + db.prepare(`UPDATE graph_run_nodes SET status = 'success', fail_reason = NULL WHERE run_id = ?`).run(run.id); + settle.settleRootRun(run, 'completed'); + await new Promise((r) => setImmediate(r)); + } finally { + global.fetch = originalFetch; + } + + expect(calls).toHaveLength(0); + }); + + it('fetch 唤醒失败（网络异常）不影响 settleRootRun 的返回值 —— best-effort，不能拖垮主路径', () => { + const { run } = scene(); + const originalFetch = global.fetch; + global.fetch = vi.fn(() => Promise.reject(new Error('网络挂了'))); + + let result; + try { + result = settle.settleRootRun(run, 'blocked'); + } finally { + global.fetch = originalFetch; + } + + expect(result).toEqual({ task: 'blocked', goal: null }); + }); + + it('低频兜底扫描 sweepBlockedTasksForCeo：按公司分组只唤醒一次，不逐条 task 叫', async () => { + const a = scene(); + const b = scene(); + // 同一家公司再卡一条 —— a.companyId 应该只被唤醒一次，不是两次 + const db = wdb.getDb(); + const now = new Date().toISOString(); + const graph2 = wdb.createWorkGraph({ companyId: a.companyId, nodes: ['sdd-planning'], edges: [] }); + const goal2 = wdb.createGoal({ companyId: a.companyId, title: '第二条', description: '测试用' }); + const task2 = wdb.createTask({ + goalId: goal2.id, companyId: a.companyId, title: '第二条', description: '测试用', executionMode: 'manual', + }); + wdb.updateTask(task2.id, { status: 'blocked' }); + // scene() 已经把 a/b 的 task 结算成 blocked（settleRootRun 还没跑，这里直接跑一次让状态落到位） + settle.settleRootRun(a.run, 'blocked'); + settle.settleRootRun(b.run, 'blocked'); + + const calls = []; + const originalFetch = global.fetch; + global.fetch = vi.fn((url) => { calls.push(url); return Promise.resolve({ ok: true }); }); + + try { + const rows = settle.sweepBlockedTasksForCeo(); + await new Promise((r) => setImmediate(r)); + const companiesSwept = rows.map((r) => r.company_id).sort(); + expect(companiesSwept).toEqual([a.companyId, b.companyId].sort()); + const aRow = rows.find((r) => r.company_id === a.companyId); + expect(aRow.cnt).toBe(2); // a 公司这次有 2 条 blocked task，但下面只应该 fetch 一次 + } finally { + global.fetch = originalFetch; + } + + const aCalls = calls.filter((u) => u.includes(`${a.companyId}%3Aceo`)); + expect(aCalls).toHaveLength(1); + }); +}); diff --git a/server/tests/unit/task-entry-draft-mode.test.js b/server/tests/unit/task-entry-draft-mode.test.js new file mode 100644 index 0000000..7844220 --- /dev/null +++ b/server/tests/unit/task-entry-draft-mode.test.js @@ -0,0 +1,135 @@ +/** + * task-entry-draft-mode.test.js —— POST /:companyId/tasks 的 draft:true 分支（39 号文档地基 1） + * + * 现有 `POST /:companyId/tasks` 建完任务无条件立刻入队执行（"下达即执行"）。 + * `draft:true` 时只应该落库，不应该 enqueue/start——服务的是 agent（如 ceo）自主提的新任务， + * 不该像 task-planning 一样先经过 draft 就自动花预算。 + * + * 隔离手法与 graph-engine.test.js / company-goal-task-routes.test.js 一致：先设 + * GRAPH_DB_PATH / GRAPH_RUNS_DIR 再 require，真实的 data/graph.sqlite、data/companies/ 全程不被碰。 + */ +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const TEST_DB_PATH = '/tmp/test-task-entry-draft-mode.sqlite'; +const DB_FILES = [TEST_DB_PATH, `${TEST_DB_PATH}-shm`, `${TEST_DB_PATH}-wal`]; +const MODULES = [ + '../../services/graph-db', + '../../services/work-graph-db', + '../../services/org-graph-service', + '../../services/graph-run-sse', + '../../routes/company', +]; + +const CID = 'draft-mode-test-co'; + +let wdb; +let orgSvc; +let server; +let base; +let origCompanyGet; + +async function call(method, url, body) { + const r = await fetch(base + url, { + method, + headers: { 'Content-Type': 'application/json' }, + body: body === undefined ? undefined : JSON.stringify(body), + }); + return [r.status, await r.json()]; +} + +function ensureAgents(ids) { + const db = wdb.getDb(); + const now = new Date().toISOString(); + const ins = db.prepare(` + INSERT OR IGNORE INTO system_agents + (id, name, scope, owner_company_id, legacy_path, status, created_at, updated_at) + VALUES (?, ?, 'public', NULL, ?, 'active', ?, ?) + `); + for (const id of new Set(ids)) ins.run(id, id, `system/agents/${id}`, now, now); +} + +describe('POST /:companyId/tasks draft 模式（39 号文档地基 1）', () => { + beforeAll(async () => { + for (const f of DB_FILES) { try { fs.unlinkSync(f); } catch { /* 本来就没有 */ } } + process.env.GRAPH_DB_PATH = TEST_DB_PATH; + process.env.GRAPH_RUNS_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'draft-mode-runs-')); + for (const m of MODULES) delete require.cache[require.resolve(m)]; + + wdb = require('../../services/work-graph-db'); + orgSvc = require('../../services/org-graph-service'); + + const { CompanyService } = require('../../services/company-service'); + origCompanyGet = CompanyService.prototype.get; + CompanyService.prototype.get = (companyId) => + (companyId === CID ? { id: CID, name: CID, status: 'running' } : null); + + // 一张最小 org graph：POST /tasks 建行前会先查「公司有没有 org graph」，没有直接 409， + // 这一步不是本文件要测的东西，先把它铺好。 + ensureAgents(['org-planner', 'org-coder', 'org-validator']); + expect( + orgSvc.writeGraph(CID, { + nodes: ['org-planner', 'org-coder', 'org-validator'], + edges: [ + { from: 'org-planner', to: 'org-coder', condition: 'success' }, + { from: 'org-coder', to: 'org-validator', condition: 'success' }, + ], + }).ok + ).toBe(true); + + const express = require('express'); + const app = express(); + app.use(express.json()); + app.use('/api/company', require('../../routes/company')); + + await new Promise((resolve) => { server = app.listen(0, resolve); }); + base = `http://127.0.0.1:${server.address().port}/api/company/${CID}`; + }); + + afterAll(() => { + if (server) server.close(); + if (origCompanyGet) require('../../services/company-service').CompanyService.prototype.get = origCompanyGet; + for (const f of DB_FILES) { try { fs.unlinkSync(f); } catch { /* 已经删了 */ } } + try { fs.rmSync(process.env.GRAPH_RUNS_DIR, { recursive: true, force: true }); } catch { /* ignore */ } + delete process.env.GRAPH_DB_PATH; + delete process.env.GRAPH_RUNS_DIR; + for (const m of MODULES) delete require.cache[require.resolve(m)]; + }); + + it('draft:true → 201 + status draft，不落 runId，task 不入队（current_run_id 仍为空）', async () => { + const [status, body] = await call('POST', '/tasks', { + task: '（草稿）先别执行的一条任务', + draft: true, + created_by: 'ceo', + }); + + expect(status).toBe(201); + expect(body.status).toBe('draft'); + expect(body.runId).toBeUndefined(); + expect(body.taskId).toBeTruthy(); + expect(body.hint).toContain(`/tasks/${body.taskId}/enqueue`); + + const row = wdb.getTask(body.taskId); + expect(row.status).toBe('draft'); + expect(row.current_run_id).toBeFalsy(); + expect(row.created_by).toBe('ceo'); + }); + + it('draft:true 建出的任务，之后走既有 /enqueue 端点能正常下达（不是死路）', async () => { + const [, created] = await call('POST', '/tasks', { task: '（草稿）待下达', draft: true }); + const [status, body] = await call('POST', `/tasks/${created.taskId}/enqueue`); + expect(status).toBe(201); + expect(['queued', 'running'].includes(body.status)).toBe(true); + + const row = wdb.getTask(created.taskId); + expect(['queued', 'running'].includes(row.status)).toBe(true); + }); + + it('默认行为不变：不传 draft 时仍然立刻入队/起跑（存量调用方不受影响）', async () => { + const [status, body] = await call('POST', '/tasks', { task: '正常下达一条任务' }); + expect(status).toBe(201); + expect(body.status).not.toBe('draft'); + expect(body.runId).toBeTruthy(); + }); +}); diff --git a/system/agents/ceo/heartbeat.md b/system/agents/ceo/heartbeat.md new file mode 100644 index 0000000..cc0a2fb --- /dev/null +++ b/system/agents/ceo/heartbeat.md @@ -0,0 +1,21 @@ +# 心跳任务 + +你收到的心跳消息会提"扫描全局 OKR 目标状态"——那是通用触发文案，对你不适用。 +你要看的是本公司的 **goal/task 板**（`tools.md` 里的读接口），不是 OKR。 + +## 每次心跳 + +- [ ] 查 `GET /tasks?status=blocked` 和 `?status=failed`，看有没有需要处理的 +- [ ] 查 `GET /goals?status=active`，扫一眼有没有明显该调整优先级的 +- [ ] 都正常就直接回复"心跳正常"，不要为了"用一下工具"而用工具 + +## 发现问题时 + +- 具体判断依据见 `tools.md` 的"什么时候该提新任务、什么时候该改优先级"一节 +- 新提的任务一律带 `draft:true`，判断确实清楚、值得马上跑再 `enqueue` +- 不确定的情况，把观察写进正文回复，不要瞎猜着动手改数据 + +## 不用管的 + +- 正在排队 / 正在跑但没超时的 task——那是调度器的活，不用你盯 +- 纯技术性的失败（比如基础设施抖动）——引擎自己有重试和熔断机制 diff --git a/system/agents/ceo/tools.md b/system/agents/ceo/tools.md new file mode 100644 index 0000000..8097d53 --- /dev/null +++ b/system/agents/ceo/tools.md @@ -0,0 +1,104 @@ +# CEO 工具箱 + +> 你的岗位是监督本公司的 goal/task 板（不是执行任务——`org-planner`/`org-coder`/`org-validator` +> 那条流水线干活，你只看板、判断、必要时提一条新任务或调一下优先级）。 +> +> 大部分心跳触发下，你**只需要读**：看一眼有没有 `blocked`/`failed` 太久的 task，正常就 +> 回复"心跳正常"，什么都不用调用。只有真发现问题时才用下面的写工具。 + +--- + +## 认证：每次调用都要带这个头 + +```bash +curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company//goals" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +``` + +`LEMON_INTERNAL_TOKEN` 是你的进程环境变量里现成的（服务端 spawn 你的时候自动带上）， +不用去别处找、也不用自己生成。**忘了带这个头，所有请求都会 401**——先检查这个， +不要一看到 401 就怀疑接口路径写错了。 + +`` 换成你自己所在的公司 id（就是你运行时坐标里那个 cid）。 + +--- + +## 读：先看板子上有什么 + +### 看哪些 goal 在跑 +```bash +curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company//goals?status=active" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +``` + +### 找卡住的 task（这是你心跳时主要要查的） +```bash +curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company//tasks?status=blocked" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company//tasks?status=failed" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +``` + +### 看某个 goal 下全部 task + 每条 task 的当前 run 摘要 +```bash +curl -s "${LEMON_API_BASE:-http://localhost:3010/api}/company//goals/" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +``` + +--- + +## 写：只在真正判断需要时才用 + +### 改一条 task 的优先级 +```bash +curl -s -X PATCH "${LEMON_API_BASE:-http://localhost:3010/api}/company//tasks/" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"priority":"P0"}' +``` + +### 提一条新任务（草稿，不会立刻执行） +```bash +curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/company//tasks" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"goal_id":"","task":"<这条新任务要做什么，写清楚，别人要能看懂>","draft":true}' +``` +**必须带 `"draft":true`。** 不带的话这条任务会立刻入队执行——你的判断和 `task-planning` +拆分一样，都是一次"猜"，不该自己直接烧预算。落库后返回一个 `taskId`。 + +### 把你（或别人）提的草稿正式下达 +```bash +curl -s -X POST "${LEMON_API_BASE:-http://localhost:3010/api}/company//tasks//enqueue" \ + -H "x-internal-token: $LEMON_INTERNAL_TOKEN" +``` +你被授权可以自主调这一步（不需要等人类点），但前提是你已经确认过这条草稿的描述是清楚、 +必要的——`enqueue` 之后就会真的排队执行、真的烧预算。判断依据不够就先别 enqueue， +留着草稿等人类看到也行。 + +--- + +## 什么时候该提新任务、什么时候该改优先级 + +- **一条 task 长时间 `blocked` 或 `failed`**（预算耗尽 / 依赖死锁 / 反复回退熔断）：看它的 + `blocked_reason` 或诊断信息，判断是「原任务描述本身有问题，需要重新拆」还是「暂时的技术 + 问题，等修复」。前者提一条新任务说明清楚问题、把原 task 的教训写进 description； + 后者不用你管，等基础设施问题解决会自动恢复。 + （注意：某些"卡住已回退熔断"的情形系统会**自动**先开一条草稿任务——你去看板前可能已经 + 有一条 `created_by: 'system'` 的草稿在等你审了，先看有没有再决定要不要自己再开一条。） +- **同一 goal 下多个 task 优先级冲突**（业务变化导致原定顺序不再合理）：改 `priority`， + 不需要新建任务。 +- **`task-planning` 降级成单任务**（goal 描述里能看出"自动拆分失败，已按单任务下达"的 + 标注）：这种情况不要自己再拆一次——把情况记下来，正文回复里说明，等人类看一眼原始 + goal 描述是不是本身就有歧义。 + +--- + +## 你不该用的工具 + +| 工具 / 动作 | 为什么不该 | +|---|---| +| `POST /:companyId/org-graph/replan` | 改组织结构是 `orggraph-planning` 的事，不是你的判断范围 | +| 任何招聘 / 解雇端点 | 公司缺角色是 HR 与 `orggraph-planning` 的活，你发现"缺人"应该提一条 task 说明缺口，不是自己动手改编制 | +| 直接改 `graph_runs` / `graph_run_nodes`（没有这类端点，但如果你找到裸 SQL 或内部函数也一样不许碰） | 执行状态由引擎维护，你只通过 goals/tasks 这层 REST 接口操作 | +| `POST /:companyId/tasks`（不带 `draft:true`） | 会立刻烧预算，见上面的强调 |