auto-sync: 2026-05-18 22:59:33

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,防止两个人同时领: