auto-sync: 2026-05-18 22:55:02

2026-05-18 22:55:02 +08:00
parent 0d693c2e80
commit 3e5cc60a7a
1 changed files with 102 additions and 72 deletions
@@ -1,15 +1,16 @@
 # v2.8 + M3 完整设计：状态增强 + 前端易用性 + Checkpoint + Artifact

-> 状态: 设计评审中  
+> 状态: ✅ 评审通过（Mail #303/#304/#305），待用户确认  
 > 日期: 2026-05-18  
 > 作者: 庞统  
+> 评审: 司马懿  

 ---

 ## 📋 概述

 ### 背景
-v2.7 已完成 Card 回滚、SubTask 聚合、Mail Tab。本设计覆盖 v2.8 状态增强 + 前端易用性 + M3 Checkpoint/Artifact，一次性完成。
+v2.7 已完成 Card 回滚、SubTask 聚合、Mail Tab。本设计覆盖 v2.8 状态增强 + 前端易用性 + M3 Checkpoint/Artifact。

 ### 问题
 1. v2.7 状态机缺少 `paused`、`escalated`、`waiting_human`（v1.0 已有）
@@ -44,7 +45,7 @@ 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, cancelled]
+review:        [done, pending, failed, escalated, waiting_human, cancelled]
 blocked:       [pending, escalated, cancelled]
 failed:        [pending, escalated, cancelled]
 escalated:     [working, pending, cancelled]
@@ -53,12 +54,6 @@ done:          []
 cancelled:     []
 ```

-**设计决策**：
- `claimed → paused`：已认领但未开始的任务也可以暂停（用户可能想暂时搁置）
- `waiting_human` 只从 `working` 进入（Agent 正在执行时才需要人工确认）
- `review → escalated`：审查阶段发现问题也可升级
- `escalated` 可回到 `working`（继续执行）或 `pending`（重新分配）
-
 ### 1.3 各状态设计细节

 #### paused（已暂停）
@@ -73,7 +68,8 @@ cancelled:     []
 - **恢复**：用户介入后手动恢复到 working 或 pending
 - **调度**：Ticker 跳过
 - **聚合**：视同 working 参与（表示活跃但需关注）
- **DB**：复用现有 `escalated INTEGER` 字段
+- **字段迁移**：废弃 `task.escalated` 布尔字段判断，改用 `task.status === 'escalated'`。保留 DB 字段做向后兼容
+- **旧数据处理**：旧 DB 中 `escalated=1` 但 `status=working` 的任务，按 working 继续调度，可接受
 - **UI**：卡片红色高亮 + ⚠️ 图标

 #### waiting_human（等待人工）
@@ -122,7 +118,7 @@ cancelled:     []
 - `Blackboard` 新增方法：
  - `archive_task(task_id)` → archived=1
  - `unarchive_task(task_id)` → archived=0
-  - `archive_all_done()` → 批量归档 done + cancelled
+  - `archive_all_done()` → 批量归档当前项目 done + cancelled 的任务（单项目操作）
 - API：
  - `POST /api/projects/{pid}/tasks/{tid}/archive` — 归档/取消归档
  - `POST /api/projects/{pid}/tasks/archive-done` — 一键归档
@@ -134,6 +130,17 @@ cancelled:     []
 - 一键归档按钮（有可归档任务时显示）
 - 卡片上 done/cancelled 显示归档按钮

+### 2.3 Schema 迁移（db.py）
+
+```sql
+-- 新增字段
+ALTER TABLE tasks ADD COLUMN archived INTEGER DEFAULT 0;
+ALTER TABLE tasks ADD COLUMN archived_at TEXT;
+
+-- 更新 CHECK 约束（重建 tasks 表或用新连接 pragma）
+-- 完整 CHECK: status IN ('pending','claimed','working','review','done','failed','blocked','cancelled','paused','escalated','waiting_human')
+```
+
 ---

 ## 三、前端易用性改造
@@ -160,20 +167,36 @@ cancelled:     []
 - escalated → `⚠️` 图标
 - waiting_human → `🔔` 图标

-**底部动作按钮**：
+**卡片按钮（最多 3 个）**：

-| 状态 | 按钮 |
-|------|------|
+| 状态 | 卡片按钮 |
+|------|---------|
+| pending | `👤 认领` `🚫` |
+| claimed | `⚔️ 开始` `🚫` |
+| working | `🔍 提审` `⏸` `🚫` |
+| paused | `▶ 继续` `🚫` |
+| review | `✅ 通过` `🚫` |
+| escalated | `▶ 继续` `🚫` |
+| waiting_human | `✅ 确认` `🚫` |
+| done | `📦 归档` |
+| failed | `🔄 重试` |
+| blocked | `🔄 解除` `🚫` |
+| cancelled | `📦 归档` |
+
+**Modal 完整按钮（最多 4 个）**：
+
+| 状态 | Modal 按钮 |
+|------|-----------|
 | pending | `👤 认领` `🚫 取消` |
 | claimed | `⚔️ 开始` `⏸ 暂停` `🚫 取消` |
-| working | `🔍 提审` `⏸ 暂停` `🚫 取消` |
+| working | `🔍 提审` `⏸ 暂停` `⚠️ 升级` `🚫 取消` |
 | paused | `▶ 继续` `🚫 取消` |
-| review | `✅ 通过` `🔄 打回` `❌ 驳回` |
+| review | `✅ 通过` `🔄 打回` `❌ 驳回` `⚠️ 升级` |
 | escalated | `▶ 继续` `🔄 重置` `🚫 取消` |
 | waiting_human | `✅ 确认` `❌ 驳回` |
 | done | `📦 归档` |
-| failed | `🔄 重试` |
-| blocked | `🔄 解除` `🚫 取消` |
+| failed | `🔄 重试` `⚠️ 升级` `🚫 取消` |
+| blocked | `🔄 解除` `⚠️ 升级` `🚫 取消` |
 | cancelled | `📦 归档` |

 - 点击标题区域打开 Modal
@@ -200,7 +223,17 @@ Agent 执行到需要人工确认的节点时，创建 Checkpoint 并设置 `wai
 | **决策** | 🎯 | `#818cf8` 紫 | 多方案定夺、技术选型 | 三方案并排 + 利弊 + 推荐 + 确认 |
 | **执行** | 🔧 | `#f59e0b` 橙 | 人工操作、环境变更 | 分步打勾 + 命令行 + 进度条 |

-### 4.3 后端数据模型
+### 4.3 approve/reject 状态推进规则
+
+| Checkpoint 类型 | approve → | reject → |
+|----------------|-----------|----------|
+| verify | **done** | working（带回退信息） |
+| decision | working（Agent 按选定方案继续） | working（带驳回信息） |
+| action | working（Agent 继续后续步骤） | working（带失败信息） |
+
+**统一规则**：verify approve → done（验证通过即完成），其余 approve → working。reject 一律 → working。
+
+### 4.4 后端数据模型

 #### checkpoints 表

@@ -212,7 +245,7 @@ CREATE TABLE checkpoints (
    title TEXT NOT NULL,
    description TEXT,
    status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')),
-    payload TEXT NOT NULL,          -- JSON，按 type 不同结构不同
+    payload TEXT NOT NULL,          -- JSON，含 version 字段
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    resolved_at TEXT,
    resolved_by TEXT,
@@ -221,11 +254,12 @@ CREATE TABLE checkpoints (
 );
 ```

-#### payload 结构
+#### payload 结构（version: 1）

 **验证（verify）**：
 ```json
 {
+  "version": 1,
  "auto_checks": [{"label": "测试通过", "passed": true}],
  "human_steps": ["确认代码风格", "确认功能正确"],
  "preview_url": "http://..."
@@ -235,6 +269,7 @@ CREATE TABLE checkpoints (
 **决策（decision）**：
 ```json
 {
+  "version": 1,
  "options": [
    {"id": "opt1", "label": "方案A", "desc": "...", "pros": ["..."], "cons": ["..."], "recommended": true},
    {"id": "opt2", "label": "方案B", "desc": "...", "pros": ["..."], "cons": ["..."]},
@@ -246,6 +281,7 @@ CREATE TABLE checkpoints (
 **执行（action）**：
 ```json
 {
+  "version": 1,
  "steps": [
    {"id": "s1", "desc": "备份数据库", "command": "mysqldump ..."},
    {"id": "s2", "desc": "执行迁移", "command": "python migrate.py"}
@@ -254,18 +290,20 @@ CREATE TABLE checkpoints (
 }
 ```

-### 4.4 API
+### 4.5 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   — 用户驳回
+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/{cid}/reject                    — 用户驳回
 ```

-approve/reject 时后端自动将 task 从 `waiting_human` 推进到 `working`（reject）或 `done/working`（approve，取决于 checkpoint 类型）。
+approve/reject 时后端自动将 task 从 `waiting_human` 推进：
+- approve: verify → done, decision/action → working
+- reject: 一律 → working

-### 4.5 Agent 触发流程
+### 4.6 Agent 触发流程

 ```
 1. Agent 执行到需要人工确认的节点
@@ -278,51 +316,42 @@ approve/reject 时后端自动将 task 从 `waiting_human` 推进到 `working`
 8. Ticker 下次 tick 继续调度
 ```

-### 4.6 前端 CheckpointPanel 组件
+### 4.7 前端 CheckpointPanel 组件

-在 TaskModal 中新增 Tab「🔐 检查点」，或当 status=waiting_human 时自动切换显示。
+文件已存在：`CheckpointPanel.tsx`（350 行），未被引用。**扩展不重写**，对接 v2.8 新 API。

- **验证面板**：自动核验结果 ✅/❌ + 人工核验步骤列表 + 预览链接 + 双按钮
- **决策面板**：三列方案卡片 + 利弊展示 + 推荐标签 + 御批备注 + 确认按钮
+在 TaskModal 中当 `status=waiting_human` 时自动显示 CheckpointPanel：
+- **验证面板**：自动核验结果 ✅/❌ + 人工核验步骤 + 预览链接 + 双按钮
+- **决策面板**：三列方案卡片 + 利弊 + 推荐 + 御批备注 + 确认
 - **执行面板**：步骤列表（可打勾）+ 命令行高亮 + 进度条 + 验证确认

 ---

 ## 五、Artifact 成果物面板（M3）

-### 5.1 概念
+### 5.1 后端

-任务的产出文件（文档、代码、数据、日志等）统一展示和下载。
-
-### 5.2 后端
-
-#### outputs 表（已有，扩展）
+扩展现有 `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
-
+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  — 下载文件
+GET  /api/projects/{pid}/tasks/{tid}/outputs                   — 列出成果物
+GET  /api/projects/{pid}/tasks/{tid}/outputs/{oid}/download    — 下载文件
 ```

-### 5.3 前端 ArtifactPanel 组件
+### 5.2 前端 ArtifactPanel 组件

-在 TaskModal 中现有「📦 产出」Tab 下展示。
+文件已存在：`ArtifactPanel.tsx`（185 行），未被引用。**扩展不重写**。

 - **文件类型图标**：📄文档 / 💻代码 / 📊数据 / ⚙️配置 / 📁其他
- **卡片布局**：文件名 + 类型标签 + 大小 + 时间 + 预览/下载按钮
- **预览**：弹窗显示（Markdown 渲染 / 代码高亮 / 纯文本 / iframe）
+- **卡片布局**：文件名 + 类型标签 + 大小 + 时间 + 下载按钮
 - **下载**：直接下载

 ---
@@ -334,7 +363,7 @@ GET  /api/projects/{pid}/tasks/{tid}/outputs/{oid}/download  — 下载文件
 | 文件 | 改动 | 阶段 |
 |------|------|------|
 | `db.py` | CHECK 约束加 3 状态 + archived 字段 + checkpoints 表 | v2.8 |
-| `models.py` | Task 加 archived/archived_at；from_row 已有防御 | v2.8 |
+| `models.py` | Task 加 archived/archived_at | v2.8 |
 | `operations.py` | 归档方法 + 状态转换 + Checkpoint CRUD | v2.8+M3 |
 | `queries.py` | 聚合规则更新 | v2.8 |
 | `blackboard_routes.py` | 归档 API + title 自动生成 + 新状态 | v2.8 |
@@ -351,17 +380,8 @@ GET  /api/projects/{pid}/tasks/{tid}/outputs/{oid}/download  — 下载文件
 | `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_v27_subtasks.py` | 新状态聚合规则 |
-| `test_checkpoints.py` | Checkpoint 生命周期 E2E |
-| `test_state_enhancement.py` | paused/escalated/waiting_human 完整测试 |
+| `CheckpointPanel.tsx` | 扩展对接新 API | M3 |
+| `ArtifactPanel.tsx` | 扩展对接新 API | M3 |

 ---

@@ -376,27 +396,37 @@ GET  /api/projects/{pid}/tasks/{tid}/outputs/{oid}/download  — 下载文件
 6. `ticker.py` — 调度规则
 7. 测试验证

-### Phase 2：v2.8 前端改造
+### Phase 2：v2.8 前端改造（可与 Phase 3 并行）
 1. `store.ts` — 全项目聚合 + 归档
 2. `EdictBoard.tsx` — 两行布局 + 项目下拉 + 卡片按钮
 3. `App.tsx` — 移除 header select
 4. `TaskModal.tsx` — 新状态按钮
 5. 前端构建验证

-### Phase 3：M3 Checkpoint 后端
+### Phase 3：M3 Checkpoint 后端（可与 Phase 2 并行）
 1. checkpoints 表 + CRUD
-2. checkpoint_routes.py
-3. Agent 触发流程（status API + checkpoint API）
-4. approve/reject 自动推进状态
+2. checkpoint_routes.py（approve/reject 推进表写入注释）
+3. Agent 触发流程
+4. outputs 表扩展

-### Phase 4：M3 前端
-1. CheckpointPanel.tsx（三种类型）
-2. ArtifactPanel.tsx（成果物展示）
+### Phase 4：M3 前端（依赖 Phase 2 + 3）
+1. CheckpointPanel.tsx 对接 API
+2. ArtifactPanel.tsx 对接 API
 3. TaskModal 集成
 4. E2E 测试

 ### Phase 5：集成 + 部署
 1. 全量测试
 2. 前端构建
-3. 司马懿评审
-4. 部署上线
+3. 部署上线
+
+---
+
+## 八、评审记录
+
+| # | 时间 | 内容 |
+|---|------|------|
+| Mail #303 | 2026-05-18 22:45 | 庞统发设计文档给司马懿 |
+| Mail #304 | 2026-05-18 22:48 | 司马懿评审：BUG-29（escalated 字段冲突）+ BUG-30（approve 推进）+ 5 OBS + 2 Q |
+| Mail #304 | 2026-05-18 22:50 | 庞统回复：BUG-29 废弃布尔改 status、BUG-30 明确推进规则、采纳 OBS-30/32/33 |
+| Mail #305 | 2026-05-18 22:51 | 司马懿最终结论：✅ 评审通过 |