diff --git a/docs/design/v2.8-state-enhancement.md b/docs/design/v2.8-state-enhancement.md index aeaa5c8..c05226a 100644 --- a/docs/design/v2.8-state-enhancement.md +++ b/docs/design/v2.8-state-enhancement.md @@ -1,25 +1,29 @@ -# v2.8 状态增强 + 前端易用性优化 +# v2.8 + M3 完整设计:状态增强 + 前端易用性 + Checkpoint + Artifact -> 状态: 设计中 +> 状态: 设计评审中 > 日期: 2026-05-18 -> 作者: 庞统 +> 作者: 庞统 --- ## 📋 概述 +### 背景 +v2.7 已完成 Card 回滚、SubTask 聚合、Mail Tab。本设计覆盖 v2.8 状态增强 + 前端易用性 + M3 Checkpoint/Artifact,一次性完成。 + ### 问题 -1. v2.7 状态机缺少 `paused`、`escalated`、`waiting_human` 三个 v1.0 已有的状态 -2. 前端缺少「已取消」「已归档」筛选,无法管理已完成任务 +1. v2.7 状态机缺少 `paused`、`escalated`、`waiting_human`(v1.0 已有) +2. 前端缺少已取消/已归档筛选,无法管理已完成任务 3. 卡片没有快捷操作按钮,每次操作需点进 Modal -4. 项目切换在 header 里,不在筛选栏,操作不便 +4. 项目切换在 header,不在筛选栏 +5. Checkpoint 人工干预和成果物展示是 M3 核心功能,依赖 `waiting_human` 状态 ### 目标 -1. 补齐 3 个缺失状态(paused/escalated/waiting_human) -2. 加归档机制(archived 字段 + 一键归档) -3. 前端两行筛选栏(仿 v1.0 布局)+ 卡片快捷按钮 -4. 项目下拉移入筛选栏 + 支持"全部任务"跨项目聚合 -5. 新建军令 title 可选(后端自动生成) +1. 补齐 3 个缺失状态 +2. 归档机制 + 前端两行筛选栏 + 卡片快捷按钮 +3. 项目下拉移入筛选栏 + 跨项目聚合 +4. Checkpoint 三种类型 + Artifact 成果物面板 +5. 新建军令 title 可选 --- @@ -29,77 +33,83 @@ | 状态 | 中文 | 颜色 | 类型 | 说明 | |------|------|------|------|------| -| `paused` | 已暂停 | `#818cf8` 紫 | 手动 | 用户主动暂停,不参与聚合、不超时回收 | +| `paused` | 已暂停 | `#818cf8` 紫 | 手动 | 用户主动暂停,不参与聚合、不超时 | | `escalated` | 已升级 | `#ff5270` 红 | 手动 | Agent 升级求助,需人工介入 | -| `waiting_human` | 等待人工 | `#f59e0b` 橙 | 中间态 | Checkpoint 等人工确认后自动推进 | +| `waiting_human` | 等待人工 | `#f59e0b` 橙 | 中间态 | Checkpoint 等人工确认后推进 | -### 1.2 完整状态转换表 +### 1.2 完整状态转换表(共 11 个状态) ``` pending: [claimed, cancelled] -claimed: [working, pending, cancelled] -working: [review, blocked, failed, paused, escalated, cancelled] -paused: [working, cancelled] ← 新增 +claimed: [working, paused, pending, cancelled] +working: [review, blocked, failed, paused, escalated, waiting_human, 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] ← 新增 +escalated: [working, pending, cancelled] +waiting_human: [working, done, cancelled] done: [] cancelled: [] ``` +**设计决策**: +- `claimed → paused`:已认领但未开始的任务也可以暂停(用户可能想暂时搁置) +- `waiting_human` 只从 `working` 进入(Agent 正在执行时才需要人工确认) +- `review → escalated`:审查阶段发现问题也可升级 +- `escalated` 可回到 `working`(继续执行)或 `pending`(重新分配) + ### 1.3 各状态设计细节 #### paused(已暂停) - **触发**:用户点暂停按钮(卡片右上角 ⏸) - **恢复**:用户点 ▶ 继续 → 回到 working -- **调度**:Ticker 跳过 paused 状态的任务(不 claim、不超时回收) -- **聚合**:paused 不参与父 Task 聚合(同 cancelled) -- **超时**:无超时,无限等待用户恢复 +- **调度**:Ticker 跳过(不 claim、不超时回收) +- **聚合**:不参与父 Task 聚合(同 cancelled) +- **超时**:无,无限等待 #### escalated(已升级) -- **触发**:Agent 遇到无法处理的问题主动升级(通过 status API) +- **触发**:Agent 遇到无法处理的问题,通过 status API 设置 - **恢复**:用户介入后手动恢复到 working 或 pending -- **调度**:Ticker 跳过 escalated 状态 -- **聚合**:escalated 视同 working 参与父 Task 聚合(表示活跃但需关注) +- **调度**:Ticker 跳过 +- **聚合**:视同 working 参与(表示活跃但需关注) +- **DB**:复用现有 `escalated INTEGER` 字段 - **UI**:卡片红色高亮 + ⚠️ 图标 -- **DB**:复用现有 `escalated INTEGER` 字段作为标志位 #### waiting_human(等待人工) -- **触发**:Agent 执行到 Checkpoint 节点,通过 status API 设置 -- **推进**:人工确认后(approve/reject),API 推进到 working 或 done -- **调度**:Ticker 跳过 waiting_human(等人工,不等超时) -- **聚合**:waiting_human 视同 working 参与父 Task 聚合 +- **触发**:Agent 执行到 Checkpoint,写 checkpoint 数据 + 设置此状态 +- **推进**:人工 approve → working/done;reject → working(带回退信息) +- **调度**:Ticker 跳过(等人工不等超时) +- **聚合**:视同 working 参与 - **UI**:卡片橙色高亮 + 🔔 图标 + Checkpoint 面板入口 -### 1.4 聚合规则更新 +### 1.4 聚合规则 ``` 父 Task 聚合优先级(高→低): escalated > waiting_human > review > working/claimed > pending > failed > blocked 不参与聚合: - paused, cancelled(手动状态) + paused, cancelled(手动/被动状态) 全部 done → done ``` ### 1.5 Ticker 调度规则 -| 状态 | Ticker 行为 | -|------|------------| -| pending | 正常 claim 调度 | -| claimed | 正常超时回收 | -| working | 正常超时监控 | -| review | 正常 review 调度 | -| **paused** | **跳过** | -| **escalated** | **跳过** | -| **waiting_human** | **跳过** | -| done | 终态 | -| failed | 不调度 | -| blocked | 不调度 | -| cancelled | 终态 | +| 状态 | claim | 超时回收 | review 调度 | +|------|-------|---------|------------| +| pending | ✅ | - | - | +| claimed | - | ✅(超时→pending) | - | +| working | - | ✅(超时→failed) | - | +| review | - | - | ✅ | +| paused | ❌ | ❌ | ❌ | +| escalated | ❌ | ❌ | ❌ | +| waiting_human | ❌ | ❌ | ❌ | +| done | 终态 | | | +| failed | ❌ | | | +| blocked | ❌ | | | +| cancelled | 终态 | | | --- @@ -110,54 +120,52 @@ cancelled: [] - `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 新增: + - `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` 默认过滤 +- 列表查询 API 默认 `?archived=0` ### 2.2 前端 -- 筛选栏第 1 行:活跃/归档/全部 切换 -- 一键归档按钮:仅在有可归档任务时显示 -- 卡片上 done 状态的任务显示 `📦 归档` 按钮 +- 第 1 行:活跃/归档/全部 切换 +- 一键归档按钮(有可归档任务时显示) +- 卡片上 done/cancelled 显示归档按钮 --- ## 三、前端易用性改造 -### 3.1 筛选栏两行布局 +### 3.1 筛选栏两行布局(仿 v1.0) **第 1 行(项目 + 归档控制)**: ``` [📦 项目▾] [活跃] [归档] [全部] 活跃12 · 归档5 · 共17 [📦 一键归档] ``` - -- 项目下拉选项:`📋 全部任务`("")→ `📁 一般任务`("projects")→ 动态项目列表 -- 全部任务:聚合所有项目的 tasks(loadV2Tasks 遍历所有项目合并) -- 活跃/归档/全部:类似 v1.0 的 archive-bar +- 项目下拉:`📋 全部任务`("")→ `📁 一般任务`("projects")→ 动态项目列表 +- 全部任务:聚合所有项目的 tasks **第 2 行(状态筛选 + 搜索)**: ``` -[📋全部] [📋待认领] [👤已认领] [⚔️执行中] [🔍审查中] [⏸已暂停] [⚠️已升级] [🔔等待人工] [✅已完成] [❌失败] [🚧阻塞] [🚫已取消] 🔍[搜索框] +[📋全部] [📋待认领] [👤已认领] [⚔️执行中] [🔍审查中] [⏸已暂停] [⚠️已升级] [🔔等人工] [✅已完成] [❌失败] [🚧阻塞] [🚫已取消] 🔍[搜索框] ``` ### 3.2 卡片改造 -**暂停按钮(右上角)**: -- working/claimed/claimed → 右上角 `⏸` 小图标按钮 -- paused → 右上角 `▶` 恢复按钮 -- escalated/waiting_human → 右上角对应图标(⚠️/🔔) -- 其他状态不显示 +**右上角状态图标**: +- working/claimed → `⏸` 暂停按钮 +- paused → `▶` 恢复按钮 +- escalated → `⚠️` 图标 +- waiting_human → `🔔` 图标 -**底部动作按钮**(替换"详情 →"): +**底部动作按钮**: -| 状态 | 右侧按钮 | -|------|----------| +| 状态 | 按钮 | +|------|------| | pending | `👤 认领` `🚫 取消` | -| claimed | `⚔️ 开始` `🚫 取消` | +| claimed | `⚔️ 开始` `⏸ 暂停` `🚫 取消` | | working | `🔍 提审` `⏸ 暂停` `🚫 取消` | | paused | `▶ 继续` `🚫 取消` | | review | `✅ 通过` `🔄 打回` `❌ 驳回` | @@ -168,97 +176,227 @@ cancelled: [] | blocked | `🔄 解除` `🚫 取消` | | cancelled | `📦 归档` | -- 点击详情:改为点击卡片标题区域打开 Modal +- 点击标题区域打开 Modal - 动作按钮直接调 API + toast 反馈 ### 3.3 新建军令 title 自动生成 -- 前端:title 标注"可选",placeholder 改"不填将自动生成" -- 后端:`create_task` 路由,若 title 为空,取 description 前 30 字 + "…" +- 前端 title 可选,placeholder "不填将自动生成" +- 后端 title 为空时:description 前 30 字 + "…" --- -## 四、影响范围 +## 四、Checkpoint 机制(M3) -### 后端(6 文件) +### 4.1 概念 -| 文件 | 改动 | -|------|------| -| `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;聚合规则更新 | +Agent 执行到需要人工确认的节点时,创建 Checkpoint 并设置 `waiting_human` 状态。用户在前端看到 Checkpoint 面板,审核后任务继续。 -### 前端(5 文件) +### 4.2 三种 Checkpoint 类型 -| 文件 | 改动 | -|------|------| -| `EdictBoard.tsx` | 两行布局 + 项目下拉 + 卡片动作按钮 + 暂停/归档按钮 + 新状态筛选 | -| `TaskModal.tsx` | VALID_TRANSITIONS 更新 + 新状态按钮 | -| `App.tsx` | 移除 header 项目 select | -| `store.ts` | loadV2Tasks 全项目聚合 + 归档 state/action + 新状态支持 | -| `api.ts` | 新增 archive/pause/escalate/waiting_human API | +| 类型 | 图标 | 主色 | 场景 | 核心交互 | +|------|------|------|------|----------| +| **验证** | 🔍 | `#6a9eff` 蓝 | 产出物确认、效果验收 | 自动核验 + 人工核验 + 双按钮审批 | +| **决策** | 🎯 | `#818cf8` 紫 | 多方案定夺、技术选型 | 三方案并排 + 利弊 + 推荐 + 确认 | +| **执行** | 🔧 | `#f59e0b` 橙 | 人工操作、环境变更 | 分步打勾 + 命令行 + 进度条 | + +### 4.3 后端数据模型 + +#### checkpoints 表 + +```sql +CREATE TABLE checkpoints ( + id TEXT PRIMARY KEY, + task_id TEXT NOT NULL, + type TEXT NOT NULL CHECK (type IN ('verify', 'decision', 'action')), + title TEXT NOT NULL, + description TEXT, + status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')), + payload TEXT NOT NULL, -- JSON,按 type 不同结构不同 + created_at TEXT NOT NULL DEFAULT (datetime('now')), + resolved_at TEXT, + resolved_by TEXT, + resolve_note TEXT, + FOREIGN KEY (task_id) REFERENCES tasks(id) +); +``` + +#### payload 结构 + +**验证(verify)**: +```json +{ + "auto_checks": [{"label": "测试通过", "passed": true}], + "human_steps": ["确认代码风格", "确认功能正确"], + "preview_url": "http://..." +} +``` + +**决策(decision)**: +```json +{ + "options": [ + {"id": "opt1", "label": "方案A", "desc": "...", "pros": ["..."], "cons": ["..."], "recommended": true}, + {"id": "opt2", "label": "方案B", "desc": "...", "pros": ["..."], "cons": ["..."]}, + {"id": "opt3", "label": "方案C", "desc": "...", "pros": ["..."], "cons": ["..."]} + ] +} +``` + +**执行(action)**: +```json +{ + "steps": [ + {"id": "s1", "desc": "备份数据库", "command": "mysqldump ..."}, + {"id": "s2", "desc": "执行迁移", "command": "python migrate.py"} + ], + "verify_command": "python check.py" +} +``` + +### 4.4 API + +``` +GET /api/projects/{pid}/tasks/{tid}/checkpoints — 列出 task 的所有 checkpoint +POST /api/projects/{pid}/tasks/{tid}/checkpoints — Agent 创建 checkpoint +POST /api/projects/{pid}/tasks/{tid}/checkpoints/{cid}/approve — 用户通过 +POST /api/projects/{pid}/tasks/{tid}/checkpoints/{cid}/reject — 用户驳回 +``` + +approve/reject 时后端自动将 task 从 `waiting_human` 推进到 `working`(reject)或 `done/working`(approve,取决于 checkpoint 类型)。 + +### 4.5 Agent 触发流程 + +``` +1. Agent 执行到需要人工确认的节点 +2. Agent 调 POST /checkpoints 创建 checkpoint(type + payload) +3. Agent 调 POST /tasks/{id}/status 设置 waiting_human +4. Ticker 检测到 waiting_human → 跳过调度 +5. 前端轮询检测到 waiting_human + checkpoint → 渲染 CheckpointPanel +6. 用户 approve/reject +7. 后端自动推进状态 → working/done +8. Ticker 下次 tick 继续调度 +``` + +### 4.6 前端 CheckpointPanel 组件 + +在 TaskModal 中新增 Tab「🔐 检查点」,或当 status=waiting_human 时自动切换显示。 + +- **验证面板**:自动核验结果 ✅/❌ + 人工核验步骤列表 + 预览链接 + 双按钮 +- **决策面板**:三列方案卡片 + 利弊展示 + 推荐标签 + 御批备注 + 确认按钮 +- **执行面板**:步骤列表(可打勾)+ 命令行高亮 + 进度条 + 验证确认 + +--- + +## 五、Artifact 成果物面板(M3) + +### 5.1 概念 + +任务的产出文件(文档、代码、数据、日志等)统一展示和下载。 + +### 5.2 后端 + +#### outputs 表(已有,扩展) + +```sql +-- 已有 outputs 表,增加 file 相关字段 +-- 当前:id, task_id, node_id, content, output_type, created_at +-- 新增字段: +ALTER TABLE outputs ADD COLUMN file_name TEXT; +ALTER TABLE outputs ADD COLUMN file_size INTEGER; +ALTER TABLE outputs ADD COLUMN file_path TEXT; -- NAS/本地路径 +ALTER TABLE outputs ADD COLUMN mime_type TEXT; +``` + +#### API + +``` +GET /api/projects/{pid}/tasks/{tid}/outputs — 列出成果物 +GET /api/projects/{pid}/tasks/{tid}/outputs/{oid} — 获取内容/预览 +GET /api/projects/{pid}/tasks/{tid}/outputs/{oid}/download — 下载文件 +``` + +### 5.3 前端 ArtifactPanel 组件 + +在 TaskModal 中现有「📦 产出」Tab 下展示。 + +- **文件类型图标**:📄文档 / 💻代码 / 📊数据 / ⚙️配置 / 📁其他 +- **卡片布局**:文件名 + 类型标签 + 大小 + 时间 + 预览/下载按钮 +- **预览**:弹窗显示(Markdown 渲染 / 代码高亮 / 纯文本 / iframe) +- **下载**:直接下载 + +--- + +## 六、影响范围 + +### 后端(8 文件) + +| 文件 | 改动 | 阶段 | +|------|------|------| +| `db.py` | CHECK 约束加 3 状态 + archived 字段 + checkpoints 表 | v2.8 | +| `models.py` | Task 加 archived/archived_at;from_row 已有防御 | v2.8 | +| `operations.py` | 归档方法 + 状态转换 + Checkpoint CRUD | v2.8+M3 | +| `queries.py` | 聚合规则更新 | v2.8 | +| `blackboard_routes.py` | 归档 API + title 自动生成 + 新状态 | v2.8 | +| `ticker.py` | 调度规则 + 聚合更新 | v2.8 | +| **新增** `checkpoint_routes.py` | Checkpoint CRUD API | M3 | +| `main.py` | 注册 checkpoint router | M3 | + +### 前端(7 文件) + +| 文件 | 改动 | 阶段 | +|------|------|------| +| `EdictBoard.tsx` | 两行布局 + 项目下拉 + 卡片按钮 + 新状态 | v2.8 | +| `TaskModal.tsx` | 新状态转换按钮 | v2.8 | +| `App.tsx` | 移除 header 项目 select | v2.8 | +| `store.ts` | 全项目聚合 + 归档 + 新状态 | v2.8 | +| `api.ts` | 新 API | v2.8+M3 | +| **新增** `CheckpointPanel.tsx` | 三种 Checkpoint 面板 | M3 | +| **新增** `ArtifactPanel.tsx` | 成果物展示面板 | M3 | ### 测试 | 文件 | 覆盖 | |------|------| -| `test_blackboard.py` | 新状态的 CRUD + 转换 | +| `test_blackboard.py` | 新状态 CRUD + 转换 + 归档 | | `test_v27_subtasks.py` | 新状态聚合规则 | -| 新增 `test_state_enhancement.py` | paused/escalated/waiting_human + 归档 E2E | +| `test_checkpoints.py` | Checkpoint 生命周期 E2E | +| `test_state_enhancement.py` | paused/escalated/waiting_human 完整测试 | --- -## 五、与 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` — 聚合规则更新 +### Phase 1:v2.8 后端状态增强 +1. `db.py` — schema migration + CHECK + MANUAL_STATUSES +2. `models.py` — archived/archived_at +3. `operations.py` — 归档方法 + 新状态转换 +4. `queries.py` — 聚合规则 5. `blackboard_routes.py` — 归档 API + title 自动生成 -6. `ticker.py` — 调度规则更新 +6. `ticker.py` — 调度规则 7. 测试验证 -### 阶段 2:前端筛选栏 + 项目下拉 -1. `store.ts` — 全项目聚合 + 归档 state -2. `EdictBoard.tsx` — 两行布局 + 项目下拉 +### Phase 2:v2.8 前端改造 +1. `store.ts` — 全项目聚合 + 归档 +2. `EdictBoard.tsx` — 两行布局 + 项目下拉 + 卡片按钮 3. `App.tsx` — 移除 header select +4. `TaskModal.tsx` — 新状态按钮 +5. 前端构建验证 -### 阶段 3:卡片动作按钮 -1. `EdictBoard.tsx` — 卡片右上角暂停 + 底部动作按钮 -2. `TaskModal.tsx` — 新状态转换按钮 -3. `api.ts` — 新 API +### Phase 3:M3 Checkpoint 后端 +1. checkpoints 表 + CRUD +2. checkpoint_routes.py +3. Agent 触发流程(status API + checkpoint API) +4. approve/reject 自动推进状态 -### 阶段 4:集成测试 + 部署 -1. 新状态 E2E 测试 -2. 前端构建验证 -3. 发司马懿评审 +### Phase 4:M3 前端 +1. CheckpointPanel.tsx(三种类型) +2. ArtifactPanel.tsx(成果物展示) +3. TaskModal 集成 +4. E2E 测试 + +### Phase 5:集成 + 部署 +1. 全量测试 +2. 前端构建 +3. 司马懿评审 4. 部署上线