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

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. 部署上线