27-P3C. 公司目标与任务 —— goal / task 两级模型 + 控制台任务列表
所属: 27 Graph Agent 架构 的 P3 收尾,直接续 27-P3/P4 执行控制台 §四.B 与 27-P3B 真跑跑道。 日期: 2026-08-18 交付物: ①
goals/tasks两张表,把「人类下达的需求」与「lemonboss 执行的单元」拆成两级;② 基于这两张表的排队与并行;③ 执行控制台(/:id/graph-console)最左侧新增目标·任务两级列表栏。 命名: 全文遵循 27-NAMING,本文档落地的正是它 §四 定义但代码里一直没有载体的goal 1 : task N基数关系。 代码引用体例: 沿用 27-P3/P4 头部约定 —— 只写文件名+ 函数名 / 常量名,不写行号。
一、问题
用户的原话是「一个 company 在控制台下达任务只能有一个」。拆开是三件事:
| # | 现象 | 真实成因 | 本次 |
|---|---|---|---|
| A | 历史任务看不见、切不了、管不了 | 纯界面缺失。GraphConsole.loadRuns() 拿到了全部 root run,却只取 `roots.find(active) \ |
\ |
| B | 一家公司同时只能跑一个,下第二个吃 409 | v1 硬约束:work-graph-db 的 idx_graph_runs_one_active_root 唯一索引 + company.js 的预检查。当时选「拒绝」而不是「排队」的理由写在代码注释里 —— 仓库里没有任何出队 worker,排进去的任务不会被消费,那是一条会静默丢任务的路 |
✅ §五 补上调度器,约束从「拒绝」改成「排队」 |
| C | 「人类提的需求」和「机器执行的单元」是同一个东西 | POST /api/company/:cid/tasks 一次调用同时创造了需求、执行单元和执行实例三层语义,压在一条 root run 上。于是需求无法分解,也就无从并行 |
✅ §三 / §四 |
C 是根因,A 和 B 是它的两个表征。先拆两级模型,A/B 才有干净的解法。
二、与既有命名的对齐(先读这一节)
2.1 这不是新概念,是给一个已存在的悬空外键补上它的表
27-NAMING §四 早已定义好基数:
| 概念 | 基数 | 定义(原文) |
|---|---|---|
| goal | 一个人类需求描述 = 1 个 | 验收的边界。回答「这次交付到底算不算满足了人提的要求」 |
| task | 一个 goal 分解出 N 个 | 图中的执行单元。可并行、可下钻 sub agent |
| okr | 跨多个 goal 的长周期度量树 | Objective / Key Result |
而 graph_runs 里:
goal_id TEXT, -- 全仓库**没有任何写入方**,只有 body.goal_id 透传
task_id TEXT, -- 由 POST /:cid/tasks 现生成,无表、无唯一性保证
company.js 那条注释写得明明白白:goal_id?, okr_node_id?, 三者基数不同不可混用(goal 1 : task N : okr 跨 goal 度量树)。字段在、语义在、表不在。 本文档做的就是把这两张缺席的表补上,不是发明新词。
2.2 「goal」一词的六个用法消歧(实现前必须分清)
| 写法 | 指什么 | 载体 | 本次是否新增 |
|---|---|---|---|
company-goal |
建公司时那句定性目标 | company.json.goal |
否 |
goal(本文档) |
人类下达的一个需求 = 验收边界 | 新 goals 表,G-xxx |
✅ 新增 |
task-goal |
一个 task 的验收边界(= 该 task 的描述) | runs/{runId}/artifacts/task-goal.json |
否,位置不变 |
subtask-goal |
work graph 内分支的验收边界 | workgraph-planning 拆分时产生 |
否 |
OKR Objective |
长周期度量树,O-xxx |
data/companies/{cid}/okr/ |
否 |
goal-benchmark / goal-test-data / goal-test-script |
三种验收产物(agent / 节点名) | work graph 节点 | 否 |
注意
task-goal的归属没变:它是「一次 task 执行的验收边界」,artifact 本来就落在runs/{runId}/下 —— 也就是每个 task 一份。引入 goal 表后它的位置和语义都不用动,goal 的描述是它的上级,不是它的替代。
2.3 G- 前缀可以用,/api/company/:cid/goals 可以要回来
两处历史包袱都已经清干净,实地核实过:
G-前缀已被 OKR 释放。27-NAMING §六 的迁移把 OKR 第 1 层G-001正名为O-001(npm run okr:migrate已执行,且当时存量数据「几乎为空」)。所以新goals表用G-不与任何活数据冲突。/api/goals与/api/company/:cid/goals目前是 OKR 的向后兼容别名,但全仓库零调用方。grep 的结果只有三行,全是别名注册语句本身(index.js/agent-server.js/okr.js的注释)。本次连带退役这两个别名,把路径要回来给新概念 —— 一个词在同一套 API 里指两件事,是比破坏兼容更贵的债。
三、模型:goal → task → run 三级
goals (G-xxx) 人类下达。一条 = 一个需求 = 一条验收边界
│ 描述一经下达不可改(§四.4)
└─ tasks (T-xxx) N 条。lemonboss 的执行单元,可排队、可并行、可有依赖
│ 描述一经下达不可改(§四.4)
└─ graph_runs root run,M 条。一次**执行实例**(重试会产生第 2 条)
└─ 子 run 每个 org node 现规划出的 work graph,及更深的子图
三级各自回答一个问题,不重叠:
| 层 | 回答的问题 | 谁改它 | 状态机 |
|---|---|---|---|
| goal | 人想要什么?做到了没有? | 人 | draft → active → done / cancelled / archived |
| task | 这个需求拆成哪几件事?谁先谁后? | 人(v1)/ task-planning agent(v2,§十一) |
draft → queued → running → completed / failed / blocked / cancelled |
| run | 这一次跑成什么样? | 引擎 | 既有 RUN_TRANSITIONS + 新增 queued(§四.3) |
为什么 task 与 run 必须分开(这是「不能直接把 task 当 root run」的三条硬理由):
- 排队态没有 run。一个排在第 3 位的 task 还没有图、没有节点、没有预算消耗 —— 硬塞一条 run 行进去,
graph_run_nodes是空的,所有按 run 遍历节点的代码都要加空判。 - 重试是 task 1 : run N。今天「重跑一遍这个任务」只能新建一条 run,于是两次执行在数据上毫无关联;有了 task 表,
runs挂在 task 下,「这个任务试了 3 次」才说得出来。 - 依赖与并行是 task 之间的关系,不是 run 之间的。
depends_on只有落在稳定的 task id 上才有意义 —— run id 每次重试都变。
四、数据模型
DB 文件复用 data/graph.sqlite(graph-db.js 的 getDb(),WAL + foreign_keys=ON 已设好),与 graph_runs 同库同连接。迁移写法照抄 work-graph-db.js 现有的「存量库迁移」块(hasColumn 判断 + ALTER TABLE ADD COLUMN)。
4.1 goals 表(新)
CREATE TABLE IF NOT EXISTS goals (
id TEXT PRIMARY KEY, -- G-{base36}-{4hex},见 §四.5
company_id TEXT NOT NULL,
title TEXT NOT NULL, -- 短标题,列表显示用;可改
description TEXT NOT NULL, -- 人类需求原文 = 验收边界;下达后不可改
status TEXT NOT NULL DEFAULT 'draft',
-- draft | active | done | cancelled | archived
priority TEXT NOT NULL DEFAULT 'P1',
okr_node_id TEXT, -- 可选,挂到 OKR 度量树的哪个节点(O-001.1.1)
budget_json TEXT, -- 整个 goal 的总预算;不填则每个 task 各用默认
created_by TEXT, -- 'human' | agent id(Master/CEO 代下单)
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL,
dispatched_at TEXT, -- 首次下达时间;非空 = 描述已冻结
archived_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_goals_company ON goals(company_id, status);
okr_node_id 放在 goal 上而不是 task 上:OKR 度量的是「人的需求达成了没有」,那正是 goal 的粒度。task 级的进度靠 goal 汇总,不各自往 OKR 上写(会重复计数)。
4.2 tasks 表(新)
CREATE TABLE IF NOT EXISTS tasks (
id TEXT PRIMARY KEY, -- T-{base36}-{4hex}
goal_id TEXT NOT NULL REFERENCES goals(id),
company_id TEXT NOT NULL, -- 冗余一份:调度器按公司选任务,避免每次 JOIN
seq INTEGER NOT NULL, -- goal 内序号,列表排序用(1,2,3…)
title TEXT NOT NULL,
description TEXT NOT NULL, -- 落进 task-goal.json 的那句;下达后不可改
status TEXT NOT NULL DEFAULT 'draft',
-- draft | queued | running | completed | failed | blocked | cancelled
execution_mode TEXT NOT NULL DEFAULT 'manual' CHECK (execution_mode IN ('manual','auto')),
depends_on TEXT NOT NULL DEFAULT '[]', -- JSON 数组,同 goal 内的 task id
budget_json TEXT,
current_run_id TEXT, -- 最近一次 root run(逻辑外键,见 §四.6)
attempt INTEGER NOT NULL DEFAULT 0, -- 起过几次 run
priority TEXT NOT NULL DEFAULT 'P1',
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL,
queued_at TEXT, -- 入队时间;非空 = 描述已冻结
started_at TEXT,
finished_at TEXT,
archived_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_tasks_goal ON tasks(goal_id, seq);
CREATE INDEX IF NOT EXISTS idx_tasks_queue ON tasks(company_id, status, priority, created_at);
depends_on 一个字段同时表达串行与并行,不另设 parallel_group:
[]→ 无前置,可立即入队 → 同一 goal 下多个空依赖的 task 天然并行(能不能真并行由 §五.2 的并发上限决定)。["T-a"]→ 等T-a到completed才可调度 → 串行。- 多个元素 → 汇聚点(fan-in)。
也就是说 goal 内部就是一张 task DAG。校验:写入时查环(depends_on 只能引用同 goal 内已存在的 task),有环 400。
4.3 graph_runs 新增一个 run status:queued
这是本次唯一动到既有运行时表的地方。 run_status 列上没有 CHECK 约束(只有 graph_kind / execution_mode 有),所以加值不需要改表,只要给 work-graph-db 的 RUN_TRANSITIONS 加一行:
queued: ['ready', 'stopped'], // 出队 = queued → ready;取消 = queued → stopped
为什么有了 tasks 表还需要它(否则确实是冗余的第二套排队状态)—— 只有一个理由,但足够硬:
它把「出队」这个并发临界区交给已有的唯一索引兜底。
调度器出队时,如果先
INSERT一条ready的 run,两个并发的 tick 会各插一条,超发。而idx_graph_runs_one_active_root的WHERE覆盖ready/running/paused、不覆盖queued—— 于是:入队时创建 run 行为queued(不占坑,可以有任意多条),出队时做一次UPDATE ... SET run_status='ready' WHERE id=? AND run_status='queued',超发的那一条会被唯一索引直接拒绝,而不是靠应用层的「先查后插」(那中间永远有竞态窗口)。
顺带三个收益:入队即有稳定的 run_id(可分享的控制台链接)、task-goal.json 的落盘路径 runs/{runId}/artifacts/ 在入队时就确定(描述冻结点与 artifact 落盘点重合,见 §四.4)、timeline 上能记下「何时入队」这条审计事实。
状态机全貌:
task: draft ──提交──▶ queued ──调度器出队──▶ running ──┬─▶ completed
│ ├─▶ failed
cancelled ├─▶ blocked ──重试──▶ queued
└─▶ cancelled
run: queued ──▶ ready ──▶ running ──┬─▶ completed / failed / blocked / stopped
│ └─▶ paused ──▶ running
stopped (既有转换全部不变)
4.4 描述冻结(用户要求 3)
| 对象 | 可改字段 | 冻结点 | 冻结后改会怎样 |
|---|---|---|---|
| goal | title / priority / okr_node_id |
dispatched_at IS NOT NULL(首个 task 入队)后 description 冻结 |
409 |
| task | title / priority(depends_on 仅 draft) |
queued_at IS NOT NULL 后 description / execution_mode / budget 冻结 |
409 |
这不是保守,是数据一致性的硬要求:task 的 description 在入队时就写进了 runs/{runId}/artifacts/task-goal.json,而 describeTask 等 agent 侧链路读的是 artifact。改库不改 artifact 会让两份记录对不上;两份都改则等于篡改已被 agent 消费过的审计输入。要改就取消后新建,错误响应里直接给这句 hint。
title 留着可改,因为它只是列表上的一个标签,不进任何 agent 的上下文。
4.5 ID 生成 —— 现有格式在本次会真的撞
现在两处都写 `T-${Date.now().toString(36)}`(company.js 与 agent-chat.js)。同一毫秒内生成的两个 id 完全相同 —— 今天没炸是因为一次只建一个;本次「一个 goal 一次性建 N 个 task」是循环建行,同毫秒撞是必然事件,而 tasks.id 是主键,撞了就是 500。
改成仓库既有约定(_spec/CONVENTIONS.md §2:时间戳部分不保证全局唯一 —— 靠后缀随机位避免碰撞):
const genId = (p) => `${p}-${Date.now().toString(36)}-${crypto.randomBytes(2).toString('hex')}`;
// G-mabc123-7f3a / T-mabc123-9e21
agent-chat.js 那处 tasklog 的 T- 生成本次不动(那是另一套存储),但要在 §九 记一笔:两套 T- id 从此可能长得像但不同源,读的时候别混。
4.6 逻辑外键,不重建表
graph_runs.goal_id / task_id 保持现状不加 REFERENCES:SQLite 不支持给已有列追加外键,要加只能重建表 —— 而 graph_runs 上挂着 graph_run_nodes / graph_run_loop_records 的真外键,重建代价远大于收益。约束由服务层保证,文档里标注为逻辑外键。
tasks.goal_id → goals(id) 是新表,可以是真外键,直接写上。
五、排队与并行
5.1 调度器 server/services/task-scheduler.js(新)
一个函数就是全部:
tick(companyId) // 幂等,可重入,同步执行(better-sqlite3 是同步 API)
- 读公司并发上限
max(§五.2)。 - 数当前活跃 root run 数
n(run_status ∈ {ready,running,paused})。 n >= max→ 直接返回(队伍照排,不动)。- 选候选:
status='queued'且depends_on里每个 id 都已completed的 task,按priority→seq→created_at排序,取前max - n条。 - 逐条出队:
UPDATE graph_runs SET run_status='ready' WHERE id=? AND run_status='queued'→ 受影响行数为 0 说明被并发抢走或唯一索引拒绝,跳过继续下一条,不报错。成功则markRunReady建节点行 →startRun(mode)。
触发点四个(少一个就会有任务永远排在队里 —— 这正是当初拒绝做排队的那条理由,必须逐个接上):
| # | 触发 | 接在哪 | 补的是什么洞 |
|---|---|---|---|
| 1 | 任务入队时 | POST /tasks 尾部 |
队伍空时立即起跑 |
| 2 | run 收敛时 | graph-engine.settleRun 转终态处 |
前一个跑完自动带起下一个 —— 队列的主动力 |
| 3 | 服务启动时 | server/index.js 现有的「中断任务恢复」旁边 |
进程重启丢掉的唤醒 |
| 4 | 60s 兜底定时器 | 同 3 | 前三条任意一条漏了都还能自愈 |
ponytail: 触发 2 挂在
settleRun上是唯一能覆盖 manual / auto / blocked 三种收敛路径的位置(reportRunOutcome只挂得上 auto 的 driver —— 27-P3/P4 已经记过这个坑)。升级路径:将来有跨公司的全局配额时,tick要从「按公司」改成「按全局配额池」。
5.2 并发上限与唯一索引
company.json 加一个字段(不新建表,companyService.get 已经在读这个文件):
{ "max_parallel_tasks": 1 } // 缺省 1 = 与今天完全同行为
max = 1(默认、批 2 上线时的形态):idx_graph_runs_one_active_root保留不动,DB 层的守卫还在,行为与今天一致,只是「拒绝」变成了「排队」。max > 1(批 4):这个唯一索引必须DROP,否则第二条并行任务在queued → ready时被索引拒掉。替代守卫是 §五.1 第 2-5 步整体包在一个better-sqlite3事务里(db.transaction(...))—— SQLite 是单写者,写事务天然序列化,「count 完再 admit」在这里是真原子的,不是应用层的乐观检查。
批 4 单独排期、单独验收,理由:删掉一个唯一索引 = 删掉最后一道 DB 兜底,这个动作不该和「界面上能看到任务列表」混在一次上线里。
六、API
全部挂在 server/routes/company.js。错误响应沿用现有 { error, hint, ... } 形态。
6.1 先做一件清理:退役 OKR 的 /goals 别名
index.js / agent-server.js 里 app.use('/api/goals', require('./routes/okr')) 与 company.js 的 okrPath() 里那条 /:companyId/goals${suffix} 一并删除。§二.3 已核实零调用方。删完 /goals 这个词在整套 API 里只剩一个含义。
6.2 goal
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/company/:cid/goals |
列表。query: status / includeArchived / withTasks=1(带出每个 goal 的 task 摘要,列表页一次拉完不 N+1) |
POST |
/api/company/:cid/goals |
新建。body { title, description, priority?, okr_node_id?, budget?, tasks?: [...], dispatch?: bool }。不传 tasks 时自动生成 1 条同描述的 task(seq=1,depends_on=[])—— 保证「只想下达一句话」的最短路径仍是一次调用。dispatch: true 则连带把这些 task 入队 |
GET |
/api/company/:cid/goals/:goalId |
详情:goal + 全部 task + 每个 task 的最近一次 run 摘要 |
PATCH |
/api/company/:cid/goals/:goalId |
改 title / priority / okr_node_id;dispatched_at 非空时带 description 一律 409(§四.4) |
POST |
/api/company/:cid/goals/:goalId/dispatch |
把该 goal 下所有 draft task 入队,写 dispatched_at |
DELETE |
/api/company/:cid/goals/:goalId |
归档。有 task 正在跑 → 409 + hint「先停止 T-xxx」;否则连带归档其下 task |
6.3 task
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/company/:cid/tasks |
改造既有语义:现在返回 task 表的行(含 goalId / status / progress / runId),而不是隐式的 root run 列表 |
POST |
/api/company/:cid/tasks |
保留、行为兼容:不带 goal_id 调用时,自动建一个同描述的 goal(created_by 记调用方)再挂一条 task —— 存量调用方(含 DispatchTaskButton、外部 agent 的 curl)一行不用改就还能用,响应体里多出 goalId 字段。带 goal_id 则挂到既有 goal 下 |
PATCH |
/api/company/:cid/tasks/:taskId |
改 title / priority;depends_on 仅 draft 可改;queued_at 非空时带 description / mode / budget 一律 409 |
POST |
/api/company/:cid/tasks/:taskId/enqueue |
单条入队:建 queued 的 run 行 + 写 task-goal.json + tick() |
POST |
/api/company/:cid/tasks/:taskId/cancel |
queued → 撤出队列(run queued → stopped);running → 转调既有 POST /api/graph-runs/:id/stop |
POST |
/api/company/:cid/tasks/:taskId/retry |
从 failed / blocked 重新入队,attempt + 1,新起一条 run(旧 run 保留在历史里) |
DELETE |
/api/company/:cid/tasks/:taskId |
归档,同 goal 的规则 |
POST /:cid/tasks 的 409 消失了:并发冲突不再是错误,是排队。响应体改为 201 { taskId, goalId, runId, status: 'queued', queuePosition: 2 }。queuePosition 是这次改动里对用户最直观的那个字段。
6.4 不动的端点
GET /api/company/:cid/graph-runs(其它调用方在用)、全部 /api/graph-runs/* 控制端点、/api/okr/*。
七、前端
7.1 布局
┌──────────────┬──────────────┬───────────────────────┬──────────────┐
│ 目标 · 任务 │ Org Graph │ Work Graph │ 节点详情 │
│ 280px │ 320px │ 1fr │ 360px │
│ │ │ │ │
│ [+ 新目标] │ ○─○─○ │ ○──○──○ │ 四个 tab │
│ ▾ G 做个官网 │ │ │ │ │ │ │
│ ● T1 首页 ◀│ ○──○ │ ○ │ │
│ ◌ T2 后台 │ │ │ │
│ ⋯ T3 排队#2│ │ │ │
│ ▸ G 埋点改造 │ │ │ │
└──────────────┴──────────────┴───────────────────────┴──────────────┘
GraphConsole.vue 的 .cols 从 320px 1fr 360px 改为 280px 320px minmax(0,1fr) 360px。
响应式:≤1400px 最左栏收成 44px 图标条 + 抽屉展开(org graph 那栏最不能压,它是全局导航);≤1100px 沿用既有堆叠,目标栏排最上。
7.2 新组件 web/src/components/graph-console/GoalTaskPane.vue
两级树,goal 可折叠,选中态永远落在 task 上(org / work graph 是 task 级的):
- goal 行:状态点 + 标题 +
3/5 任务完成+⋯菜单(编辑 / 下达全部 / 归档)。点标题展开收起;goal 行本身被选中时,中栏显示这个 goal 的任务概览(v1 就是一张简单的任务卡片列表,不画图)。 - task 行:状态点 + 标题(2 行截断)+ 第二排
queued#2 · auto · 3/7 · 12min。depends_on非空时标题前加⇢并 hover 出「等 T1 完成」。 - 状态点配色沿用画布节点的既有色板,不新造:running 蓝 / completed 绿 / failed 红 / blocked 橙 / queued 灰蓝 / draft 空心圈 / cancelled 灰。
「+ 新目标」表单(承接现有 DispatchTaskButton 的内容,搬进这一栏内联展开):标题 + 描述 + 执行模式 + auto 模式的成本预警(原样保留)+ 「拆成多个任务」折叠区(v1 就是一个可增删的行列表,每行 描述 + 依赖前一条 ☑)。主按钮「下达」,次按钮「存草稿」。
canDispatch === false 时主按钮不再禁用 —— 排队之后它永远可点,按钮下方改为提示「当前 1 个任务在跑,新任务将排在第 2 位」。这是 B 类问题在界面上的最终消解。
7.3 选中态与刷新
- 路由
/:id/graph-console?goal=G-xxx&task=T-xxx,刷新 / 分享可复原。无参数时默认选中最近一条running的 task,没有则最近创建的。 - 切 task 时
orgNode / selectedNode / stack全清(不同任务的 def node 不可复用,串了会画出一张不存在的图 —— 与onReplanned的处理同理)。 - 选中 draft / queued task:org 栏画 org graph 定义(现有
hasOrgGraph && !rootRun分支已能画,全 pending),顶部一条「排队中,前面还有 1 个任务」或「草稿,尚未下达」+ 对应按钮。 - 刷新:选中 task 的 run 有 SSE(
GraphRunPane的@state)→ 只更新那一行;整树 20s 轮询兜底。 > ponytail: 没有公司级 SSE 通道,所以未选中的行只能靠轮询。升级路径是graph-run-sse加一个 company topic,前端订一条就够。
八、验收
每条都要在浏览器 /e2e-probe/graph-console 上真点出来,不是只跑单测。
- 建一个 goal 不拆分 → 自动生成 1 条 task 并入队,左栏出现两级树,org 栏画出该 task 的 run。
- 建一个 goal 拆 3 条 task,T2/T3 依赖 T1 → T1 跑时 T2/T3 显示
queued;T1 收敛后 T2 自动起跑(验证触发点 2),全程无人工干预。 max_parallel_tasks=1下建两条无依赖 task → 第二条排队而不是 409,queuePosition=2。- 存量调用方兼容:
curl POST /api/company/:cid/tasks -d '{"task":"…"}'(不带goal_id)仍返回 201,且自动生成了一个 goal。 - 改已下达 goal 的
description→409+ hint;改title→ 200。task 同理。 depends_on写成环 →400,库里没有半条脏数据。- 取消一个
queuedtask → runqueued → stopped,队列后面的顶上来。 failed的 task 点重试 →attempt=1,新起一条 run,旧 run 仍能在历史里点开。- 杀掉服务再起(模拟进程重启)→ 队列里的 task 被触发点 3 捡起来,不需要人工干预。
- 列表端点在 20 goal × 3 task 的公司上不 N+1(
graph_run_nodes的进度用一次GROUP BY出)。 /api/goals与/api/company/:cid/goals的 OKR 别名退役后,OkrDashboard/CompanyDashboard/bin/lemon.js全部功能正常(它们走的是/api/okr)。- 全量
npx vitest run不掉,重点是 §九.1 那批回归。
九、风险与已知取舍
1. queued 混进 run_status 取值域 —— 本次最大的回归面
新增一个状态值,所有按 run_status 分支的地方都要逐个确认 queued 不被误当可执行。实现时必须挨个看过并补测试:
| 位置 | 期望 |
|---|---|
graph-engine.advanceOne / startRun |
queued run 直接拒绝(没有 graph_run_nodes,进去就是空指针) |
TERMINAL_RUN_STATUS / settleRun / propagateToParent |
queued 既非终态也非活跃态,收敛判定不该碰到它;且它只可能是 root run,不涉及向上传播 |
ACTIVE_ROOT_RUN_STATUS(graph-run.js + company.js 两处) |
不含 queued ✅ 天然正确,但要加断言测试钉死 —— 这条正是 §四.3 出队原子性的全部依赖 |
GraphConsole.loadRuns 的 `roots.find(active) \ |
\ |
服务启动的中断任务恢复(server/index.js) |
queued 不该被当成「被中断的 run」拉起,它该走调度器 |
company-heartbeat-service |
同上 |
2. 「排队」这条路当初被明确否决过,现在要对它负责
company.js 的注释原话:选拒绝的理由是,仓库里没有任何出队/唤醒的 worker,排进去的任务不会被自动消费,那是一条会静默丢任务的路。这条判断在今天仍然成立 —— 它只是被 §五.1 的四个触发点解除。所以那四个触发点是本次的功能主体,不是收尾工作;验收 2 和 9 专门验它们。触发点接漏了,症状就是任务静默躺在队里,而界面上它长得跟「正在排队」一模一样。
3. description 双写(DB + task-goal.json)
两份都在入队那一刻写、之后都不可变(§四.4)——结构上不可能不一致。这正是「已下达不给改」的真正理由,而不是保守。
4. 归档只是隐藏
data/companies/{cid}/runs/{runId}/ 仍在磁盘上。本次不做 GC;需要时另立清理任务(按 archived_at 早于 N 天)。
5. 两套 T- id
agent-chat.js 的 tasklog 也发 T- 开头的 id,本次不动它。两者从此长得像但不同源,读日志时别混;本文档的 task id 一律带 -{4hex} 后缀,肉眼可分。
6. 并行是最后一批,且要单独验
批 4 会 DROP idx_graph_runs_one_active_root —— 删掉最后一道 DB 兜底。守卫改成事务内 count + admit(SQLite 单写者天然序列化)。不与界面改动同批上线。
十、实施顺序
| 批 | 内容 | 验收 |
|---|---|---|
| 1 · 两级模型落库 | goals / tasks 建表 + ID 生成器修正 + POST /:cid/tasks 兼容改造(自动建 goal)+ GET 列表端点 + 退役 /goals 别名 |
4 / 10 / 11 |
| 2 · 控制台左栏 | GoalTaskPane 两级树 + URL 选中态 + loadRuns 修正 + 新建表单(含拆分任务) |
1 / 12 |
| 3 · 排队 | run_status='queued' + RUN_TRANSITIONS + task-scheduler 四个触发点 + depends_on 环检测 + 入队/取消/重试端点 + §九.1 全部回归点 |
2 / 3 / 5 / 6 / 7 / 8 / 9 |
| 4 · 并行(单独排期) | max_parallel_tasks + DROP 唯一索引 + 事务内 admit |
另立验收 |
批 1+2 上线就已经解决用户提的核心痛点(历史任务看不见、需求无法分解);批 3 才是「不再只能有一个」。
十一、开放问题
- 谁把 goal 拆成 task? v1 是人手拆(表单里加行)。v2 建议加一个
task-planningagent(命名依 27-NAMING §二「{产出物}-planning」,产出物是 task 列表)—— 它读 goal 描述 + 公司 org graph,产出带depends_on的 task DAG。本次不做,但表结构已经为它留好(depends_on/seq/created_by)。 - goal 级的验收谁做? 现在
org-validator验的是 task 级(task-goal)。一个 goal 的 5 个 task 全completed,不等于人的需求达成了。要不要在 goal 收敛时再跑一次 goal 级验收(goal-benchmark天然就是干这个的)?倾向做,但需要先定「goal 级验收的输入是什么」—— 是 N 个 task 的产物合集吗?留到 P5。 - 失败的 task 挡不挡住依赖它的下游? 当前设计:
depends_on只认completed,所以上游 failed 会让下游永远排队。需要一个显式的「跳过依赖强制入队」操作,还是把这类 task 自动转blocked?倾向后者(自动转blocked并在界面标红),但要防止级联误判。 - 跨公司任务总览。
/api/tasks+TaskTimeline是从会话反推的另一套任务树,与本文档的tasks表同名不同源。将来是把它改成读这张表,还是并存?本次不碰,但这是个明确待收的口子。 max_parallel_tasks放company.json还是建company_settings表? v1 选前者(companyService.get已经在读那个文件,零新增读路径)。公司级配置项超过 3 个时再考虑建表。