auto-sync: 2026-05-18 22:36:43

docs/design/v2.8-state-enhancement.md

@@ -0,0 +1,264 @@
+# v2.8 状态增强 + 前端易用性优化
+
+> 状态: 设计中  
+> 日期: 2026-05-18  
+> 作者: 庞统
+
+---
+
+## 📋 概述
+
+### 问题
+1. v2.7 状态机缺少 `paused`、`escalated`、`waiting_human` 三个 v1.0 已有的状态
+2. 前端缺少「已取消」「已归档」筛选，无法管理已完成任务
+3. 卡片没有快捷操作按钮，每次操作需点进 Modal
+4. 项目切换在 header 里，不在筛选栏，操作不便
+
+### 目标
+1. 补齐 3 个缺失状态（paused/escalated/waiting_human）
+2. 加归档机制（archived 字段 + 一键归档）
+3. 前端两行筛选栏（仿 v1.0 布局）+ 卡片快捷按钮
+4. 项目下拉移入筛选栏 + 支持"全部任务"跨项目聚合
+5. 新建军令 title 可选（后端自动生成）
+
+---
+
+## 一、状态机增强
+
+### 1.1 新增状态定义
+
+| 状态 | 中文 | 颜色 | 类型 | 说明 |
+|------|------|------|------|------|
+| `paused` | 已暂停 | `#818cf8` 紫 | 手动 | 用户主动暂停，不参与聚合、不超时回收 |
+| `escalated` | 已升级 | `#ff5270` 红 | 手动 | Agent 升级求助，需人工介入 |
+| `waiting_human` | 等待人工 | `#f59e0b` 橙 | 中间态 | Checkpoint 等人工确认后自动推进 |
+
+### 1.2 完整状态转换表
+
+```
+pending:       [claimed, cancelled]
+claimed:       [working, pending, cancelled]
+working:       [review, blocked, failed, paused, escalated, cancelled]
+paused:        [working, cancelled]               ← 新增
+review:        [done, pending, failed, escalated, cancelled]
+blocked:       [pending, escalated, cancelled]
+failed:        [pending, escalated, cancelled]
+escalated:     [working, pending, cancelled]      ← 新增
+waiting_human: [working, done, cancelled]          ← 新增
+done:          []
+cancelled:     []
+```
+
+### 1.3 各状态设计细节
+
+#### paused（已暂停）
+- **触发**：用户点暂停按钮（卡片右上角 ⏸）
+- **恢复**：用户点 ▶ 继续 → 回到 working
+- **调度**：Ticker 跳过 paused 状态的任务（不 claim、不超时回收）
+- **聚合**：paused 不参与父 Task 聚合（同 cancelled）
+- **超时**：无超时，无限等待用户恢复
+
+#### escalated（已升级）
+- **触发**：Agent 遇到无法处理的问题主动升级（通过 status API）
+- **恢复**：用户介入后手动恢复到 working 或 pending
+- **调度**：Ticker 跳过 escalated 状态
+- **聚合**：escalated 视同 working 参与父 Task 聚合（表示活跃但需关注）
+- **UI**：卡片红色高亮 + ⚠️ 图标
+- **DB**：复用现有 `escalated INTEGER` 字段作为标志位
+
+#### waiting_human（等待人工）
+- **触发**：Agent 执行到 Checkpoint 节点，通过 status API 设置
+- **推进**：人工确认后（approve/reject），API 推进到 working 或 done
+- **调度**：Ticker 跳过 waiting_human（等人工，不等超时）
+- **聚合**：waiting_human 视同 working 参与父 Task 聚合
+- **UI**：卡片橙色高亮 + 🔔 图标 + Checkpoint 面板入口
+
+### 1.4 聚合规则更新
+
+```
+父 Task 聚合优先级（高→低）：
+  escalated > waiting_human > review > working/claimed > pending > failed > blocked
+
+不参与聚合：
+  paused, cancelled（手动状态）
+
+全部 done → done
+```
+
+### 1.5 Ticker 调度规则
+
+| 状态 | Ticker 行为 |
+|------|------------|
+| pending | 正常 claim 调度 |
+| claimed | 正常超时回收 |
+| working | 正常超时监控 |
+| review | 正常 review 调度 |
+| **paused** | **跳过** |
+| **escalated** | **跳过** |
+| **waiting_human** | **跳过** |
+| done | 终态 |
+| failed | 不调度 |
+| blocked | 不调度 |
+| cancelled | 终态 |
+
+---
+
+## 二、归档机制
+
+### 2.1 后端
+
+- `tasks` 表新增：`archived INTEGER DEFAULT 0`、`archived_at TEXT`
+- `Task` dataclass 新增：`archived: int = 0`、`archived_at: Optional[str] = None`
+- `Blackboard` 新增方法：
+  - `archive_task(task_id)` → 设置 archived=1
+  - `unarchive_task(task_id)` → 设置 archived=0
+  - `archive_all_done()` → 批量归档 done + cancelled 的任务
+- API 新增：
+  - `POST /api/projects/{pid}/tasks/{tid}/archive` — 归档/取消归档
+  - `POST /api/projects/{pid}/tasks/archive-done` — 一键归档
+- 列表查询 API 加 `?archived=0` 默认过滤
+
+### 2.2 前端
+
+- 筛选栏第 1 行：活跃/归档/全部 切换
+- 一键归档按钮：仅在有可归档任务时显示
+- 卡片上 done 状态的任务显示 `📦 归档` 按钮
+
+---
+
+## 三、前端易用性改造
+
+### 3.1 筛选栏两行布局
+
+**第 1 行（项目 + 归档控制）**：
+```
+[📦 项目▾] [活跃] [归档] [全部]    活跃12 · 归档5 · 共17    [📦 一键归档]
+```
+
+- 项目下拉选项：`📋 全部任务`（""）→ `📁 一般任务`（"projects"）→ 动态项目列表
+- 全部任务：聚合所有项目的 tasks（loadV2Tasks 遍历所有项目合并）
+- 活跃/归档/全部：类似 v1.0 的 archive-bar
+
+**第 2 行（状态筛选 + 搜索）**：
+```
+[📋全部] [📋待认领] [👤已认领] [⚔️执行中] [🔍审查中] [⏸已暂停] [⚠️已升级] [🔔等待人工] [✅已完成] [❌失败] [🚧阻塞] [🚫已取消]    🔍[搜索框]
+```
+
+### 3.2 卡片改造
+
+**暂停按钮（右上角）**：
+- working/claimed/claimed → 右上角 `⏸` 小图标按钮
+- paused → 右上角 `▶` 恢复按钮
+- escalated/waiting_human → 右上角对应图标（⚠️/🔔）
+- 其他状态不显示
+
+**底部动作按钮**（替换"详情 →"）：
+
+| 状态 | 右侧按钮 |
+|------|----------|
+| pending | `👤 认领` `🚫 取消` |
+| claimed | `⚔️ 开始` `🚫 取消` |
+| working | `🔍 提审` `⏸ 暂停` `🚫 取消` |
+| paused | `▶ 继续` `🚫 取消` |
+| review | `✅ 通过` `🔄 打回` `❌ 驳回` |
+| escalated | `▶ 继续` `🔄 重置` `🚫 取消` |
+| waiting_human | `✅ 确认` `❌ 驳回` |
+| done | `📦 归档` |
+| failed | `🔄 重试` |
+| blocked | `🔄 解除` `🚫 取消` |
+| cancelled | `📦 归档` |
+
+- 点击详情：改为点击卡片标题区域打开 Modal
+- 动作按钮直接调 API + toast 反馈
+
+### 3.3 新建军令 title 自动生成
+
+- 前端：title 标注"可选"，placeholder 改"不填将自动生成"
+- 后端：`create_task` 路由，若 title 为空，取 description 前 30 字 + "…"
+
+---
+
+## 四、影响范围
+
+### 后端（6 文件）
+
+| 文件 | 改动 |
+|------|------|
+| `models.py` | Task 加 archived/archived_at 字段；from_row 已有防御 |
+| `db.py` | CHECK 约束加 paused/escalated/waiting_human；TERMINAL_STATUSES 不变；MANUAL_STATUSES 加 paused/escalated/waiting_human；schema migration |
+| `operations.py` | 新增 archive_task/unarchive_task/archive_all_done 方法；update_status 支持 paused/escalated/waiting_human |
+| `queries.py` | compute_parent_status 更新聚合规则（escalated/waiting_human 视同 working） |
+| `blackboard_routes.py` | 新增归档 API；create_task title 自动生成；update_status 支持新状态 |
+| `ticker.py` | 调度跳过 paused/escalated/waiting_human；聚合规则更新 |
+
+### 前端（5 文件）
+
+| 文件 | 改动 |
+|------|------|
+| `EdictBoard.tsx` | 两行布局 + 项目下拉 + 卡片动作按钮 + 暂停/归档按钮 + 新状态筛选 |
+| `TaskModal.tsx` | VALID_TRANSITIONS 更新 + 新状态按钮 |
+| `App.tsx` | 移除 header 项目 select |
+| `store.ts` | loadV2Tasks 全项目聚合 + 归档 state/action + 新状态支持 |
+| `api.ts` | 新增 archive/pause/escalate/waiting_human API |
+
+### 测试
+
+| 文件 | 覆盖 |
+|------|------|
+| `test_blackboard.py` | 新状态的 CRUD + 转换 |
+| `test_v27_subtasks.py` | 新状态聚合规则 |
+| 新增 `test_state_enhancement.py` | paused/escalated/waiting_human + 归档 E2E |
+
+---
+
+## 五、与 M3 Checkpoint 的关系
+
+### M3 已设计内容
+- 三种 Checkpoint 类型：验证/决策/执行
+- ArtifactPanel 成果物面板
+- 前端代码已回滚（ArtifactPanel.tsx、CheckpointPanel.tsx 已删）
+
+### v2.8 为 M3 铺路
+- `waiting_human` 状态是 M3 Checkpoint 的前置条件
+- Checkpoint 触发 → Agent 设置 `waiting_human` → 用户在卡片/Modal 看到确认入口
+- M3 只需在前端加 CheckpointPanel 组件 + 后端加 checkpoint 数据模型
+
+### M3 剩余工作（v2.8 状态增强完成后）
+
+| M3 任务 | 说明 | 依赖 |
+|---------|------|------|
+| Checkpoint 数据模型 | `checkpoints` 表 + API | v2.8 waiting_human 状态 |
+| CheckpointPanel 前端 | 验证/决策/执行三种面板 | v2.8 卡片改造 |
+| ArtifactPanel 前端 | 成果物卡片展示 + 下载 | 无 |
+| Agent Checkpoint 触发 | Agent 写 checkpoint 数据 + 设置 waiting_human | v2.8 状态 |
+| Ticker Checkpoint 超时 | waiting_human 超时提醒 | v2.8 状态 |
+| M3 设计文档更新 | 更新到 v2.8 状态机 | v2.8 完成 |
+
+---
+
+## 六、实施计划
+
+### 阶段 1：后端状态增强（核心）
+1. `db.py` — schema migration + CHECK 约束 + MANUAL_STATUSES
+2. `models.py` — Task 加 archived/archived_at
+3. `operations.py` — 归档方法 + 状态转换支持
+4. `queries.py` — 聚合规则更新
+5. `blackboard_routes.py` — 归档 API + title 自动生成
+6. `ticker.py` — 调度规则更新
+7. 测试验证
+
+### 阶段 2：前端筛选栏 + 项目下拉
+1. `store.ts` — 全项目聚合 + 归档 state
+2. `EdictBoard.tsx` — 两行布局 + 项目下拉
+3. `App.tsx` — 移除 header select
+
+### 阶段 3：卡片动作按钮
+1. `EdictBoard.tsx` — 卡片右上角暂停 + 底部动作按钮
+2. `TaskModal.tsx` — 新状态转换按钮
+3. `api.ts` — 新 API
+
+### 阶段 4：集成测试 + 部署
+1. 新状态 E2E 测试
+2. 前端构建验证
+3. 发司马懿评审
+4. 部署上线