From 631151540db1877e21ffed1e32c5801d33ad0a03 Mon Sep 17 00:00:00 2001 From: yibo Date: Tue, 18 Aug 2026 14:48:01 +0800 Subject: [PATCH] docs(27-P3C): 与并行的 agent 目录重构对账 —— 纠正一条写反的约束 --- docs/todo/system-design/27-p3c-goal-task-model.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/todo/system-design/27-p3c-goal-task-model.md b/docs/todo/system-design/27-p3c-goal-task-model.md index 600153f..c06b9d2 100644 --- a/docs/todo/system-design/27-p3c-goal-task-model.md +++ b/docs/todo/system-design/27-p3c-goal-task-model.md @@ -311,7 +311,18 @@ AgentManager 调 task-planning（输入：goal.description + 公司 org graph 1. **token 记账**：复用 `defaultPlanWorkGraph` 那个 `onAcpEvent` 累加 `usage` 的写法，结果写进 `goals.planning_tokens`（§四.1）。这是 goal 层唯一一笔花费，不记就是隐形的。 2. **失败必须降级，不能把 goal 卡在 `planning`**：3 轮都没产出合法 DAG → **退化成 1 条同描述的 task**（`created_by='human'`、`seq=1`、`depends_on=[]`），goal 转 `active`，并在界面标注「自动拆分失败，已按单任务下达」。绝不能留一个永远转圈的 `planning` goal —— 那正是这次要消灭的那类静默状态。 -3. **`_registry.json` 必须同时登记**：新建本体目录而漏登记，`server/tests/unit/template-refs.test.js` 会直接把 CI 跑红 —— 27-P3/P4 §八.21 记着这个前科（六个本体建了目录没登记，718 passed / 1 failed）。本体文件按 `workgraph-planning` 的形态给齐：`agent.md` / `config.json` / `identity.md` / `soul.md` / `tools.md`。 +3. **本体落点是 `system/agents/task-planning/`**（`system/templates/` 已在 2026-08-18 的 agent 目录重构里**彻底取消**，50 个本体全部 `git mv` 进 `system/agents/`，`base` → `_base`）。形态照 `workgraph-planning`：`agent.md` / `config.json` / `identity.md` / `soul.md` / `tools.md`。**不要用 `_` 开头命名** —— `_` 是保留前缀，扫描时会被跳过。 + +4. **`agent.md` + `soul.md` 必须一次写完，不能先建骨架后填**。本体现在有**毕业闸门**：`agent.md` 与 `soul.md` 非空、且不带 `_base` 的骨架哨兵，才会从 `system_agents.status='draft'` 毕业；否则 `hire()` 直接拒绝并返回 `body_not_ready`。「从 `_base` 复制骨架 → 以后再填」的中间态**雇不进公司**。（`.claude/skills/main_skill/SKILL.md` 是可选的，57 个本体里 54 个没有。） + +5. **`_registry.json` 登记是可选的，建目录才是关键动作** —— 这条与初稿写反了，留档纠正：`graph-seed-service.seedAgents()` 现在直接 `readdirSync(system/agents/)` 把**目录当真相**，`_registry.json`（已随重构挪到 `system/agents/_registry.json`，数组格式不变）只用于按 id 补 `benchmark_score`，registry 缺条目照样 seed。初稿写的「不登记会把 CI 跑红」引的是 27-P3/P4 §八.21 的前科，那条前科属于 `template-refs.test.js` 硬编码 `system/templates` 路径的时代，**该测试正随重构一起改**。仍建议顺手登记（`benchmark_score` 要用），但它不是闸门。 + +6. **本体正文里的路径有三条硬规矩，写错不报错、只静默降级**（agent 运行时 cwd 是 `system/agents/{aid}/{cid}/{taskId}/`，深度 3）： + - 引用本体自己的文件 → `../../`（如 `../../tools.md`）； + - 引用仓库根 → `../../../../../`； + - **交付物路径绝不能写裸相对**（`workspace/x.md` 会落进任务态目录，之后被清理）。必须用提示词开头「运行时坐标」里「你的交付物必须写到」那一行给的**绝对路径**，本体正文里统一记作 `$W`。 + + 照 `system/agents/orggraph-planning/agent.md`（重构后版本）抄写法。这三条错了全都**不报错**，只是产物落在没人看的地方 —— 与本文档反复点名的那类静默故障同源。 #### 跳过拆分 @@ -632,7 +643,7 @@ for (const t of queuedTasks) { 1. **多一次会失败的 LLM 调用挡在「下达任务」前面**。今天下达是一次同步 DB 写，现在中间插了一次几十秒、可能失败的 agent 调用。降级路径（§四.9 约束 2）和界面上的逃生口（§七.2）**不是可选项** —— 少了任何一个，一次 agent 卡死就等于整个下达入口不可用。 2. **拆分质量决定预算消耗**。拆出 5 条 task 就是 5 份 `DEFAULT_TASK_BUDGET`（各 100 次调用 / 500 万 token）。这是「产出一律 `draft`、必须人确认」的根本理由 —— 那一步是唯一一道成本闸门。界面上要显式提示「N 个任务 ≈ N × 单任务成本」。 -3. **新本体不登记 `_registry.json` 会直接把 CI 跑红**。27-P3/P4 §八.21 有前科（六个本体建了目录没登记，`template-refs.test.js` 当场红）。建目录与登记必须在同一个 commit 里。 +3. **新本体的真正闸门是「毕业」，不是 registry 登记**（§四.9 约束 4/5 已纠正初稿的反向结论）。`agent.md` + `soul.md` 没写满就停在 `draft`，`hire()` 返回 `body_not_ready`；而 `_registry.json` 缺条目只是少个 `benchmark_score`。另外本体正文的相对路径写错**不报错只静默降级**（§四.9 约束 6）—— 这是本文档点名的静默故障家族里最新的一个成员。 ### 5. 两套 `T-` id —— 由 §十二 的统一消解，但在那之前是真风险 @@ -656,6 +667,20 @@ for (const t of queuedTasks) { > 批 3 的验收从 6 条涨到 12 条，是本次复核的直接结果 —— 13/14/15 三条各自对应一个「初稿会实现出来的静默故障」。 +### 与并行进行中的「agent 目录结构重构」的关系（2026-08-18 核实） + +写本文档期间，另一条工作线正在做 **agent 目录结构重构**（`system/templates/` 并入 `system/agents/`，两份 `_registry.json` 合一），工作区约 900 个变更**尚未提交**。它与本文档有实质交集，逐条核实结果： + +| 交集点 | 结论 | +|---|---| +| 本文档逐字引用的全部函数 / 常量（`settleRun` / `markRunReady` / `stopRun` / `defaultPlanWorkGraph` / `PLAN_MAX_ROUNDS` / `writeTaskGoalArtifact` / `reportRunOutcome` / `ACTIVE_ROOT_RUN_STATUS` / `saveTaskMeta` / `getAggregatedTasks`）| **全部存活**。重构改了约 650 行、5 个文件，但没有动这些锚点 —— 27-P3/P4 那条「只写函数名不写行号」的体例在这里直接兑现了价值 | +| 本文档的五条**行为性**结论（`markRunReady` 写死 `planning`、`settleRun` 只在 `advanceOne` 内被调、`stopRun` 不走 `settleRun`、`reportRunOutcome` 读 `run.okr_node_id` 与闭包里的 `ctx.reportTo`）| **逐条复验仍然成立** | +| `work-graph-db.js`（`createRun` 建节点行、`updateRunStatus` 条件更新、`RUN_TRANSITIONS`、唯一索引）| **完全未被改动** —— 第二轮复核里最关键的那批发现不受影响 | +| 新建本体的做法（§四.9）| **初稿有一条写反了，已纠正**：`system/templates/` 彻底取消（本体落 `system/agents/`）；`_registry.json` 已不是数据源头（`seedAgents` 扫目录当真相），登记是可选的；真正的闸门是**毕业**（`agent.md` + `soul.md` 非空且无 `_base` 哨兵，否则 `hire()` 返回 `body_not_ready`）；本体正文的相对路径另有三条硬规矩，写错静默降级。详见 §四.9 约束 3-6 | +| `agent-chat.js`（+455 行）、`company.js`、`agent-manager.js` | 都是本文档批 1 / 批 5 要改的文件。**新端点是新增代码，不冲突**；但 §十二 的前提「`/task/dispatch` 的 URL 与请求体一个字都不能动」需要在批 5 开工前**基于重构后的版本重新核一遍**（`tools-base.md` 目前未被改动，是个好迹象） | + +**对排期的影响**：批 1 可照常开工（`work-graph-db.js` 无人触碰，建表 + 回填是纯新增）。**批 2 的 `task-planning` 本体应当等 agent 重构落地后再建** —— 否则本体目录与登记方式要按旧形态做一遍、再按新形态改一遍。批 5 在那之后重新核 `agent-chat.js`。 + 批 1+2 上线就已经解决用户提的核心痛点（历史任务看不见、需求无法分解）；批 3 才是「不再只能有一个」。 --- -- libgit2 0.21.4