cfdaily
265 lines
9.4 KiB
Markdown
265 lines
9.4 KiB
Markdown
# 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. 部署上线
|