diff --git a/docs/design/architecture-v2.6.md b/docs/design/architecture-v2.6.md index 329b2f3..661e847 100644 --- a/docs/design/architecture-v2.6.md +++ b/docs/design/architecture-v2.6.md @@ -410,46 +410,68 @@ def get_connection(): return conn ``` -### 3.3 简化状态机 +### 3.3 状态机(v2.8:11 个状态) ``` pending → claimed → working → review → done - ↑ │ ├→ blocked ──┘ ├→ failed - │ │ └→ failed └→ cancelled - └─────────┘ + ↑ │ ↕ ├→ blocked ──┘ ├→ failed + │ │ paused ├→ paused └→ cancelled + └─────────┘ ├→ escalated + └→ waiting_human ← M3 Checkpoint + (review→pending: 审核不通过,打回重做) + (review→waiting_human: 审查阶段需人工裁定) (blocked→pending: 阻塞解除) + (blocked→escalated: 阻塞升级求助) (failed→pending: 重试) + (failed→escalated: 失败升级求助) + (escalated→working: 用户介入后恢复) + (waiting_human→working: Checkpoint reject) + (waiting_human→done: verify Checkpoint approve) ``` -**与 v2.0 的区别:** v2.0 有 9 个状态(spawning, ready, reporting 等),v2.6 简化为 8 个。原因是 spawn 逻辑从状态机移到了 daemon--daemon tick 发现黑板需要某人介入就 spawn,不需要 spawning/ready 这些中间状态。 +**v2.8 变更:** v2.6 有 8 个状态,v2.8 新增 3 个: paused(用户暂停)、escalated(Agent 升级求助)、waiting_human(Checkpoint 人工确认)。 -| 状态 | 含义 | 谁触发 | -|------|------|--------| -| pending | 待领取 | 任何 Agent 或用户创建 | -| claimed | 已认领 | Agent 自己或被指派 | -| working | 执行中 | Agent | -| review | 待审核 | Agent 完成产出 | -| blocked | 需要帮助 | Agent | -| done | 完成 | **审核通过且所有问题达成一致** | -| failed | 失败 | Agent 或 daemon | -| cancelled | 取消 | 用户 | +| 状态 | 含义 | 谁触发 | 调度 | 聚合 | +|------|------|--------|------|------| +| pending | 待领取 | 任何 Agent 或用户创建 | ✅ 正常调度 | ✅ 参与 | +| claimed | 已认领 | Agent 自己或被指派 | ✅ 超时回收 | ✅ 参与 | +| working | 执行中 | Agent | ✅ 超时监控 | ✅ 参与 | +| review | 待审核 | Agent 完成产出 | ✅ review 调度 | ✅ 参与 | +| **paused** | **已暂停** | **用户主动** | **❌ 跳过** | **❌ 不参与** | +| **escalated** | **已升级** | **Agent 求助** | **❌ 跳过** | **✅ 视同 working** | +| **waiting_human** | **等人工** | **Agent Checkpoint** | **❌ 跳过** | **✅ 视同 working** | +| done | 完成 | 审核通过 | 终态 | ✅ 参与 | +| failed | 失败 | Agent 或 daemon | ❌ 不调度 | ✅ 参与 | +| blocked | 需要帮助 | Agent | ❌ 不调度 | ✅ 参与 | +| cancelled | 取消 | 用户 | 终态 | ❌ 不参与 | + +**聚合规则(v2.8):** 优先级 escalated > waiting_human > review > working/claimed > pending > failed > blocked。paused/cancelled 不参与。全部 done → done。 **完整合法流转矩阵:** ```python VALID_TRANSITIONS = { - "pending": {"claimed", "cancelled"}, - "claimed": {"working", "pending", "cancelled"}, # pending: 放弃认领 - "working": {"review", "blocked", "failed", "cancelled"}, - "review": {"done", "pending", "failed", "cancelled"}, # pending: 审核不通过打回 - "blocked": {"pending", "cancelled"}, # pending: 阻塞解除 - "done": set(), # 终态 - "failed": {"pending"}, # pending: 重试 - "cancelled": set(), # 终态 + "pending": {"claimed", "cancelled"}, + "claimed": {"working", "paused", "pending", "cancelled"}, + "working": {"review", "blocked", "failed", "paused", "escalated", "waiting_human", "cancelled"}, + "paused": {"working", "cancelled"}, + "review": {"done", "pending", "failed", "escalated", "waiting_human", "cancelled"}, + "blocked": {"pending", "escalated", "cancelled"}, + "failed": {"pending", "escalated", "cancelled"}, + "escalated": {"working", "pending", "cancelled"}, + "waiting_human": {"working", "done", "cancelled"}, + "done": set(), # 终态 + "cancelled": set(), # 终态 } ``` +**字段迁移(v2.8):** `escalated` 从布尔字段改为 status 判断。DB 保留 `escalated INTEGER` 做向后兼容,前端/Ticker 改用 `task.status == 'escalated'`。 + +**归档机制(v2.8):** tasks 表新增 `archived INTEGER DEFAULT 0`、`archived_at TEXT`。归档不改变状态,只影响前端显示(默认不显示已归档任务)。 + +**Checkpoint 机制(M3):** Agent 执行到需人工确认的节点 → 创建 checkpoint + 设置 waiting_human → 用户 approve/reject → 自动推进状态。详见 `docs/design/v2.8-state-enhancement.md`。 + ### 3.4 原子操作 **任务认领(claim)** - 原子 CAS,防止两个人同时领: