From 3c5ed2dc76ec75784d37b87d22ae724c15bf7b08 Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Thu, 21 May 2026 19:58:22 +0800
Subject: [PATCH] auto-sync: 2026-05-21 19:58:22

---
 docs/design/v3.0-router-refactor.md | 107 ++++++++++++++++++++++------
 1 file changed, 86 insertions(+), 21 deletions(-)

diff --git a/docs/design/v3.0-router-refactor.md b/docs/design/v3.0-router-refactor.md
index dbccb38..a4c86ba 100644
--- a/docs/design/v3.0-router-refactor.md
+++ b/docs/design/v3.0-router-refactor.md
@@ -338,31 +338,96 @@ Agent 超时/广播无人认领
 | 状态转换 API | `blackboard_routes.py` POST /tasks/{id}/status | VALID_TRANSITIONS 校验 |
 | 转换矩阵 | `db.py` VALID_TRANSITIONS | escalated → {working, pending, cancelled} |
 
-### 5.6 前端按钮完整矩阵
+### 5.6 前端按钮完整矩阵（v3.1 用户确认版）
 
-**PRIMARY_ACTIONS（主操作区，直接展示）：**
+**设计原则：**
+- 暂停和取消是用户的通用权利，所有非终态都有
+- AI 自动流转的操作（认领、开始、提审、通过、打回）不需要按钮
+- escalated / waiting_human 是 AI 发起后等待用户决策，不是通用按钮
+- blocked 任务本身没在动，暂停无意义
+- failed 的升级是 AI 发起不是按钮
 
-| 状态 | 按钮 | 目标状态 | 说明 |
-|------|------|----------|------|
-| pending | ⏳ 等待 Agent 自动认领... | — | 提示文字（待补取消按钮） |
-| claimed | ⏳ Agent 已认领，即将开始... | — | 提示文字 |
-| working | ⏸ 暂停任务 | paused | |
-| review | 🔍 Agent 审查中... | — | 提示文字 |
-| waiting_human | ✅ 确认完成 / 🔄 拒绝继续做 | done / working | |
-| escalated | ▶ 继续执行 / 🔄 重新分配 | working / pending | |
-| failed | 🔄 重试 | pending | |
-| blocked | 🔓 解除阻塞 | pending | |
-| paused | ▶ 继续执行 / 🚫 取消任务 | working / cancelled | |
-| done | 📦 归档 | — | |
-| cancelled | 📦 归档 | — | |
+#### 状态定义
 
-**ADVANCED_ACTIONS（折叠在"▸ 高级操作"下）：**
+| 状态 | 含义 | 谁触发 | 颜色 |
+|------|------|--------|------|
+| pending | 等待 AI 认领 | 用户创建/AI流转 | 蓝 |
+| claimed | AI 已认领 | AI 认领 | 紫 |
+| working | AI 执行中 | AI 开始 | 蓝 |
+| paused | 用户暂停 | 用户 | 紫 |
+| review | AI 审查中 | AI 提交审查 | 紫 |
+| failed | 失败 | AI 或 daemon | 红 |
+| blocked | 缺条件卡住 | Agent 遇到外部阻塞 | 橙 |
+| escalated | AI 解决不了，升级求助 | Agent | 红 |
+| waiting_human | 流程验收点等用户确认 | Agent Checkpoint | 橙 |
+| done | 完成 | 审查通过/用户确认 | 绿 |
+| cancelled | 取消 | 用户 | 灰 |
 
-| 状态 | 按钮 | 说明 |
-|------|------|------|
-| working | 🔍 手动提交审查 / 🚫 取消 | |
-| review | ✅ 手动通过 / 🔄 打回重做 | |
-| failed | 🚫 取消 | |
+**escalated vs waiting_human 区别：**
+- escalated：Agent 遇到**意外问题**解决不了（如技术选型不确定）→ 红色 → 严重
+- waiting_human：执行到**计划中的验收点**（如 Checkpoint）→ 橙色 → 正常进度
+
+#### 按钮矩阵
+
+| 状态 | 用户按钮 | 说明 |
+|------|---------|------|
+| **pending** | ⏸ 暂停、🚫 取消 | 等 AI 认领时用户可暂停或取消 |
+| **claimed** | ⏸ 暂停、🚫 取消 | AI 已认领未开始 |
+| **working** | ⏸ 暂停、🚫 取消 | AI 执行中 |
+| **paused** | ▶ 恢复、🚫 取消 | 恢复回暂停前状态 |
+| **review** | ⏸ 暂停、🚫 取消 | AI 审查中 |
+| **failed** | 🔄 重试、🚫 取消 | 重试回 pending |
+| **blocked** | 🔓 解除(→pending)、🚫 取消 | 任务本身没在动，暂停无意义 |
+| **escalated** | ▶ 继续(→working)、🔄 重分配(→pending)、🚫 取消 | AI 发起升级后用户决策 |
+| **waiting_human** | ✅ 确认、🔄 拒绝(→working)、🚫 取消 | 流程验收点 |
+| **done** | 📦 归档 | 终态 |
+| **cancelled** | 🔄 重新启动(→pending)、📦 归档 | 可重启保留历史 |
+
+#### 状态机变更
+
+暂停是通用权利，需要在更多状态允许 → paused 转换：
+
+```python
+# 当前
+VALID_TRANSITIONS = {
+    "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(),
+}
+
+# 变更后
+VALID_TRANSITIONS = {
+    "pending":       {"claimed", "paused", "cancelled"},            # +paused
+    "claimed":       {"working", "paused", "pending", "cancelled"},  # 不变
+    "working":       {"review", "blocked", "failed", "paused", "escalated", "waiting_human", "cancelled"},  # 不变
+    "paused":        {"working", "pending", "cancelled"},           # +pending（恢复到原状态）
+    "review":        {"done", "pending", "failed", "paused", "escalated", "waiting_human", "cancelled"},  # +paused
+    "blocked":       {"pending", "escalated", "paused", "cancelled"},  # +paused
+    "failed":        {"pending", "escalated", "cancelled"},  # 不变（暂停语义不清晰）
+    "escalated":     {"working", "pending", "paused", "cancelled"},  # +paused
+    "waiting_human": {"working", "done", "paused", "cancelled"},  # +paused
+    "done":          {"cancelled"},                             # +cancelled（取消已完成任务）
+    "cancelled":     {"pending"},                               # +pending（重新启动）
+}
+```
+
+**paused 恢复机制：** paused 加 `resumed_from` 字段，记录暂停前状态。恢复时回到暂停前状态：
+- pending → paused → ▶恢复 → pending
+- review → paused → ▶恢复 → review
+- claimed → paused → ▶恢复 → claimed
+
+#### 取消 ADVANCED_ACTIONS 折叠区
+
+v3.1 不再使用 ADVANCED_ACTIONS 折叠区。所有用户操作直接展示在主操作区。
+原因：暂停和取消是通用权利，不应隐藏在折叠区里。
 
 ---