257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
# Proposal B2: tasks 状态机重构为 phase enum + task_leases 表
|
||
|
||
> 来源：问题.md B2（行 45-64）、附录 F 样本 1（行 424-441）、样本 2（行 444-457）
|
||
> 状态：proposed（待 B5 eval harness 就绪后实施）
|
||
> 提出：Roundtable 2026-04-20（Linus + Karpathy + Steve Jobs）
|
||
> Owner: TBD
|
||
> 估计工时：3-4 周（与 C1 共享 migration 窗口）
|
||
> Blocking dependencies：B1（pi 版本收敛，已完成）、B5（eval harness 建立，仍 blocked by user constraint）
|
||
|
||
## 问题陈述
|
||
|
||
单张 `tasks` 表并行持有 5 个锁/状态字段，彼此之间没有代数约束：
|
||
- `status`（枚举：backlog / todo / in_progress / done / blocked / …）
|
||
- `active_run_id`（当前运行的 run id）
|
||
- `checkout_run_id`（正在抢占执行权的 run id）
|
||
- `execution_locked_at`（执行锁 timestamp）
|
||
- `active_session_id`（pi agent session id）
|
||
|
||
这 5 列的合法组合本应由状态机约束，实际由散落在 10+ 处的 SQL 片段手动维护。`src/main/database/tasks-status.ts:160-189` 的 `checkoutTask` 函数 CAS 条件里已经被迫加了补丁分支：
|
||
|
||
```sql
|
||
AND (
|
||
status IN ('todo', 'backlog')
|
||
OR (status = 'in_progress' AND active_run_id IS NULL)
|
||
)
|
||
```
|
||
|
||
这个 `OR (status = 'in_progress' AND active_run_id IS NULL)` 分支是"从 orphan 状态恢复"的补丁。代码注释自己承认：
|
||
|
||
> "recovers from a specific orphan: finishRun has cleared active_run_id and checkout_run_id but the status transition never fired … without the reclaim, heartbeat picks the task and then loops on `checkout_race_lost` forever"
|
||
|
||
进一步证据：
|
||
- `src/main/database-base.ts:369-387` 的 `interruptStaleRuns`：只清 `active_run_id`、把 agents 设为 idle、释放 workspace lock。**没清** `checkout_run_id` 和 `execution_locked_at`。
|
||
- `src/main/database-base.ts:389-400` 的 `recoverStaleLocks`：用 15 分钟 cutoff 清 `checkout_run_id` 和 `execution_locked_at`。
|
||
- 两条独立路径各写各的字段，顺序错位就出现「status=in_progress，active_run_id=null，checkout_run_id=null」的 zombie。
|
||
|
||
## 根因分析
|
||
|
||
Linus 视角（好品味原则第一条）："特殊情况就是你数据结构错了"。
|
||
|
||
当前设计把"执行权 lease"的元数据打散到 tasks 表的多个列里，违反了**最基本的关系代数**：tasks 是实体，执行权是有起止时间的租约，这是两个有独立生命周期的东西。把它们塞在同一行就必然出现：
|
||
|
||
1. **部分更新问题**：清 lease 时必须同时清 `active_run_id` / `checkout_run_id` / `execution_locked_at`，任何一处漏掉就是 zombie。
|
||
2. **状态组合爆炸**：5 个字段理论组合数是 5! = 120 种（真实合法的只有 ~6 种），SQL 层无法约束。
|
||
3. **多 writer 竞态**：`interruptStaleRuns` 和 `recoverStaleLocks` 各自只负责一部分字段，顺序依赖靠 code review 维持。
|
||
4. **补丁放大效应**：`checkoutTask` 的 OR 分支注释里写得很清楚——"如果不补，heartbeat 就会永远循环 checkout_race_lost"。这不是"修"，这是给错的数据结构打绷带。
|
||
|
||
问题的根源是：**tasks 表承担了两个职责**——"我是什么任务"（entity）和"我现在被谁锁着"（lease）。这两个职责必须拆开。
|
||
|
||
## 设计方案
|
||
|
||
### 新 schema
|
||
|
||
```sql
|
||
-- 主表：只保留任务本身的语义
|
||
ALTER TABLE tasks ADD COLUMN phase TEXT NOT NULL
|
||
CHECK (phase IN ('backlog', 'ready', 'running', 'awaiting_review', 'done', 'blocked'));
|
||
-- 删除：active_run_id, checkout_run_id, execution_locked_at, active_session_id, status（等迁移完成）
|
||
|
||
-- 新表：租约独立生命周期
|
||
CREATE TABLE task_leases (
|
||
task_id TEXT PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
|
||
run_id TEXT NOT NULL REFERENCES runs(id),
|
||
acquired_at INTEGER NOT NULL,
|
||
expires_at INTEGER NOT NULL,
|
||
session_id TEXT,
|
||
-- 显式外键 + 唯一约束，SQL 层强制"一个 task 同时只能有一个 lease"
|
||
UNIQUE (task_id)
|
||
);
|
||
CREATE INDEX idx_task_leases_expires ON task_leases(expires_at);
|
||
```
|
||
|
||
### 状态机语义
|
||
|
||
| phase | 合法来源 phase | lease 是否存在 | 触发条件 |
|
||
|------|---------|---------|---------|
|
||
| `backlog` | (init) / `blocked` 清除 | 否 | 任务初建 |
|
||
| `ready` | `backlog` | 否 | 需求就绪 |
|
||
| `running` | `ready` | **必须有** | `checkoutTask` 成功 |
|
||
| `awaiting_review` | `running` | 否（finishRun 释放） | deliverable 产出 |
|
||
| `done` | `awaiting_review` | 否 | 审核通过 |
|
||
| `blocked` | 任何（除 done） | 否 | 显式 block |
|
||
|
||
**关键不变式**：`phase = 'running'` ⇔ `task_leases` 存在对应行。SQL 层面用 trigger 强制。
|
||
|
||
### 单一状态迁移函数
|
||
|
||
```ts
|
||
// src/main/database/tasks-status.ts（重写）
|
||
export function advanceTaskPhase(
|
||
taskId: string,
|
||
from: TaskPhase,
|
||
to: TaskPhase,
|
||
ctx: { runId?: string; sessionId?: string; ts?: number }
|
||
): { ok: true } | { ok: false; reason: string } {
|
||
return db.transaction(() => {
|
||
// 1. CAS 写 tasks.phase
|
||
// 2. 根据 from/to 组合插入/删除 task_leases 行
|
||
// 3. 违反不变式直接 throw（let it crash）
|
||
})();
|
||
}
|
||
```
|
||
|
||
**所有**状态迁移都走这一个函数，禁止直接 `UPDATE tasks SET status = ...`。改造 call sites:
|
||
- `src/main/database/tasks-status.ts`（checkoutTask, finishRun, interruptRun）
|
||
- `src/main/database-base.ts:369-400`（interruptStaleRuns, recoverStaleLocks）
|
||
- `src/main/orchestration/scheduler.ts`、`task-runner.ts`、`heartbeat.ts` 的所有 tasks 写路径
|
||
|
||
### 删除 OR 补丁
|
||
|
||
重构后，`checkoutTask` 变成：
|
||
|
||
```sql
|
||
UPDATE tasks SET phase = 'running' WHERE id = ? AND phase = 'ready';
|
||
INSERT INTO task_leases (task_id, run_id, acquired_at, expires_at, session_id) VALUES (?, ?, ?, ?, ?);
|
||
```
|
||
|
||
没有 OR，没有 orphan。如果 `interruptRun` 漏清 lease，trigger 会在下次 advanceTaskPhase 时直接报 constraint violation——**让它 crash，不掩盖**。
|
||
|
||
## Migration 计划
|
||
|
||
1. **v49 migration**（dual-write 阶段，1 周）
|
||
- 新建 `task_leases` 表（空）
|
||
- 新增 `tasks.phase` 列，默认值从 `status` 映射：`backlog→backlog, todo→ready, in_progress+active_run_id→running, …`
|
||
- 应用层所有写路径同时写 `phase` 和旧 `status`，写 lease 同时写 `active_run_id`/`checkout_run_id`
|
||
2. **backfill**（自动）
|
||
- v49 启动时一次性 SQL：根据旧 5 列反推 phase + 插入 lease 行
|
||
- 写 validation：phase = running ⇔ lease 存在；不成立直接 crash（暴露现存 orphan）
|
||
3. **v50 switch-read**（2 周后）
|
||
- 所有读路径切到 `phase` + `task_leases` JOIN
|
||
- 确认 telemetry 没有新 404/500
|
||
4. **v51 drop-old**（4 周后）
|
||
- 删 `active_run_id`、`checkout_run_id`、`execution_locked_at`、`active_session_id`、`status` 列
|
||
- 删 `checkoutTask` 的 OR 分支（届时代码里已不存在）
|
||
|
||
## 风险与回滚
|
||
|
||
| 风险 | 触发条件 | 回滚方法 |
|
||
|------|---------|---------|
|
||
| backfill 发现现存 orphan | v49 启动时 assertion fail | v49 migration 提供 `--heal-orphans` flag，根据最后活跃 run 推断正确 phase |
|
||
| dual-write 导致写冲突 | 并发 advanceTaskPhase vs 旧路径 | v49 → v50 之间禁止 `UPDATE tasks SET status = ...`（ESLint rule + SQL trigger 拦截） |
|
||
| switch-read 性能回退 | JOIN 开销增加 | 给 `task_leases(task_id)` 建 UNIQUE 索引（schema 已含） |
|
||
| 测试 fixture 不同步 | tests/unit 里的 stub 数据没 phase 列 | 所有测试 fixture 走 `makeTaskRecord()` helper 统一生成 |
|
||
|
||
**真回滚路径**：v51 前每一步都可降级——任何时候发现新 schema 有 bug，停止应用层双写、所有读切回旧列，v49 migration 可以通过删 `task_leases` 表 + 清 `phase` 列回到原状态。
|
||
|
||
## 验证标准
|
||
|
||
**前置依赖：B5 eval harness 必须先就绪**（Karpathy 强烈反对无 eval 下做状态机改动）。
|
||
|
||
具体验证：
|
||
1. **契约测试**：构造 30+ 种非法状态组合，验证 `advanceTaskPhase` 全部拒绝
|
||
2. **并发 fuzz**：2 个 worker 同时 checkoutTask 同一个 task，只有一个成功
|
||
3. **崩溃恢复**：kill -9 worker，下次启动 `recoverStaleLocks` 能清掉过期 lease
|
||
4. **行为 eval**：相同 company 输入，v48 和 v51 产出的 run trace 在 agent 行为层一致（tool calls / state transitions 序列）
|
||
5. **Telemetry 指标**：生产环境 `checkout_race_lost` 发生率不增，`sqlite_busy` 不增
|
||
|
||
## 不在范围
|
||
|
||
- **不重构 runs 表**：runs 的 status 机自身健康，本 proposal 只动 tasks。
|
||
- **不改 IPC 契约**：renderer 看到的仍是 `TaskRecord.status`，由 map 层从 phase/lease 合成。
|
||
- **不做 per-agent quota**：执行权限流控是另一件事，走独立 proposal。
|
||
- **不引入分布式锁**：SQLite 单 writer 前提不变，B4 的 single-writer actor 是独立 proposal。
|
||
- **不做 phase transition 审计 log**：需要的话另开 event 表，和本 proposal 解耦。
|
||
|
||
## 参考文件清单
|
||
|
||
- `src/main/database/tasks-status.ts:160-189`（checkoutTask + OR 补丁）
|
||
- `src/main/database-base.ts:369-387`（interruptStaleRuns 只清一半字段）
|
||
- `src/main/database-base.ts:389-400`（recoverStaleLocks 另一半字段）
|
||
- `src/main/database-base.ts:49-51`（作者自白 pass-through 架构）
|
||
- `src/main/database/migrations/`（48 个既有 migration 作为 v49/v50/v51 的 template）
|
||
- `src/main/orchestration/scheduler.ts`（heartbeat 写路径）
|
||
- `src/main/worker/worker-runner.ts:239` 附近（worker 回写 run 状态）
|
||
|
||
## 附：为什么现在修而不是等
|
||
|
||
`checkoutTask` 的 OR 补丁在生产环境就是**一个 agent 完全卡死并持续烧钱**——每次 heartbeat 唤醒都重新尝试 checkout，每次失败产生日志 / 事件 / cost 记录。数据结构错误导致 agent 静默陷入死循环，这是最糟糕的一类 bug：不 crash，不报错，只是不前进。用户付钱看着 agent 原地踏步。
|
||
|
||
每多拖一周，新 call site 就多一批——数据结构错误会 viral 扩散。把 5 列乱象标准化后，后续所有 feature（new phase、priority、deadline）都受益。
|
||
|
||
## 附：gating matrix
|
||
|
||
| Gate | 条件 | 放行判断人 |
|
||
|------|------|----------|
|
||
| G1 | B5 eval harness 可以 record baseline behavior | Roundtable |
|
||
| G2 | v49 dual-write 测试环境跑 48 小时无 assertion fail | Owner |
|
||
| G3 | v50 switch-read 灰度 1 个 company 7 天 | Owner |
|
||
| G4 | v51 drop-old 前所有 call site 静态 scan 无 `status IN ('todo', 'backlog')` | Linus |
|
||
| G5 | `checkoutTask` OR 分支删除后 telemetry `checkout_race_lost` 连续 14 天为 0 | Karpathy |
|
||
|
||
## 附：与其他 proposal 的耦合
|
||
|
||
| 相关 | 关系 |
|
||
|------|-----|
|
||
| B1（pi 版本 pin） | 已完成 |
|
||
| B4（single-writer actor） | 互补：B4 收敛"谁能写"，B2 收敛"写什么语义" |
|
||
| C1（AppDatabase pass-through） | 共享 migration 窗口：两者都需要改 DB 访问 call site，codemod 可同时改 |
|
||
| C6（error taxonomy） | B2 的 let-it-crash 依赖 C6 的 error 分类来决定 crash vs retry |
|
||
|
||
## 附：反模式对比（before / after）
|
||
|
||
**Before**（`src/main/database/tasks-status.ts:160-189`）：
|
||
```sql
|
||
UPDATE tasks
|
||
SET checkout_run_id = ?, execution_locked_at = ?, status = 'in_progress', updated_at = ?
|
||
WHERE id = ?
|
||
AND checkout_run_id IS NULL
|
||
AND (
|
||
status IN ('todo', 'backlog')
|
||
OR (status = 'in_progress' AND active_run_id IS NULL) -- orphan 恢复补丁
|
||
);
|
||
```
|
||
|
||
**After**（B2 完成后）：
|
||
```sql
|
||
-- 原子操作 1：phase 转移
|
||
UPDATE tasks SET phase = 'running' WHERE id = ? AND phase = 'ready';
|
||
-- 原子操作 2：插入 lease（UNIQUE 约束防止重复）
|
||
INSERT INTO task_leases (task_id, run_id, acquired_at, expires_at, session_id) VALUES (?, ?, ?, ?, ?);
|
||
```
|
||
|
||
两个 statement 走一个 transaction；UNIQUE(task_id) 约束让"同一个 task 同时只有一个 lease"成为 SQL 层不变式，无需应用层 CAS。
|
||
|
||
## 附：涉及 SQL 片段清单（待改造）
|
||
|
||
- `src/main/database/tasks-status.ts:160-189` checkoutTask
|
||
- `src/main/database/tasks-status.ts` finishRun（释放 lease）
|
||
- `src/main/database-base.ts:369-387` interruptStaleRuns
|
||
- `src/main/database-base.ts:389-400` recoverStaleLocks
|
||
- `src/main/orchestration/scheduler.ts` 的 wake writer
|
||
- `src/main/orchestration/heartbeat.ts` markHeartbeatAt（touch lease.expires_at）
|
||
- `src/main/worker/worker-runner.ts` 的 finishRun 回调
|
||
|
||
每处都从"直接 UPDATE 5 列"改为"调 `advanceTaskPhase`"。改造 PR 按文件拆，每个 PR 跑 typecheck + 单测。
|
||
|
||
## 附：为什么不选其他方案
|
||
|
||
考虑过的替代设计：
|
||
|
||
**方案 A（直接拆 leases 表）**：当前 proposal 采用。优点：SQL 层可强约束；缺点：需要 dual-write migration。
|
||
|
||
**方案 B（保留 5 列但用 check constraint）**：SQLite check constraint 表达力有限，无法精确表达"running 时 active_run_id 非空且 checkout_run_id 也非空"这类跨列约束。
|
||
|
||
**方案 C（单独一个 state machine 中间层 service）**：应用层约束比 SQL 层约束弱——任何代码绕过 service 直接 SQL 就失效。
|
||
|
||
方案 A 是唯一把约束放在数据结构层的。
|
||
|
||
## 附：phase 枚举外的状态跟踪
|
||
|
||
某些运行态信息仍需要但不属于 phase 枚举：
|
||
- `blocked_reason`（为什么 block）
|
||
- `awaiting_review_since`（等待审核已多久）
|
||
- `attempted_count`（重试次数）
|
||
|
||
这些存在 tasks 的辅助列或独立表——独立于 phase enum，不参与 CAS。
|