# v2.6 前端任务管理改造方案

**作者**: 庞统（副军师）🐦
**日期**: 2026-05-17
**状态**: 待确认

---

## 一、从 v2.0 定位出发

### v2.0 的核心定位（PRD v2.0）

> **用户提一个方向，AI 帮他梳理成清晰目标，然后自主组织 Agent 团队执行，全程持续指挥、自主协调、主动汇报，人只在关键决策点介入。**

四条信念：
1. AI 帮人想清楚要什么
2. 编排层是 AI 指挥官，不是确定性代码
3. Agent 之间共享意识，不传递消息
4. 人退到系统的边缘

### Dashboard 在 v2.0 中的角色

**不是"管理控制台"，而是"AI 工作可视化窗口"**。

| 传统 Dashboard | AI Native Dashboard |
|---|---|
| 用户主动操作（点按钮、填表单） | AI 主动展示（推送状态、产出、决策请求） |
| 用户监控一切 | AI 只在关键点拉人，其余自主 |
| 表格+表单为主 | 时间线+卡片+对话为主 |
| 用户是驾驶员 | 用户是乘客，偶尔导航 |

参考的优秀实践：
- **Devin 模式**：全自主执行，Dashboard 是观察窗口
- **Claude Code App**：多 session 并排 + diff review
- **Linear**：精准通知，不噪音，状态流转极简
- **Edict**：MiniPipe 管道可视化 + 心跳 + 操作按钮
- **Hermes Kanban**：任务卡片 + 结果区 + 评论线程 + 事件流 + Nudge 按钮

---

## 二、当前后端能力盘点

### 已有（v2.6 F1-F18 实现）

| 能力 | API | 数据表 |
|------|-----|--------|
| 多项目管理 | GET/POST /api/projects | _registry.yaml |
| 任务 CRUD | GET/POST /api/projects/{pid}/tasks | tasks |
| 任务认领 | POST /tasks/{id}/claim | tasks.claimed_at |
| 状态流转 | POST /tasks/{id}/status | tasks.status + events |
| 评论/Handoff | GET/POST /tasks/{id}/comments | comments |
| 产出写入 | GET/POST /tasks/{id}/outputs | outputs |
| 决策记录 | POST /tasks/{id}/decisions | decisions |
| 观察/吹哨 | POST /tasks/{id}/observations | observations |
| 评审 | GET/POST /tasks/{id}/reviews | reviews |
| 事件流 | GET /tasks/{id}/events（缺） | events |
| SSE 推送 | GET /api/events | SSEBroker |
| Daemon 状态 | GET /api/daemon/status | 内存 |
| 经验沉淀 | experiences.jsonl + 读取API | experiences |
| Agent 注册 | agents 表 | agents |

### 缺失但设计中有

| 能力 | 设计位置 | 说明 |
|------|---------|------|
| **任务详情聚合 API** | §9.1 `GET /tasks/{id}` 返回关联数据 | 前端需要一次性拿全部关联数据 |
| **任务事件查询 API** | §9.1 `GET /tasks/{id}/events` | Flow Log 时间线 |
| **任务关联经验 API** | §9.1 | 关联经验展示 |
| **Checkpoint 机制** | 课题7 §6 + §11 前端架构 | 三种检查点（验证/决策/执行），后端无实现 |
| **通知推送对接** | §9.3 SSE + §7 异常通知 | SSEBroker 存在，但 ticker 未推送事件 |
| **AI Briefing** | 课题7 §8 + §3.5 | 日报/周报自动生成，完全未实现 |
| **/api/daemon/sessions** | §9.2 | 活跃 Agent session 列表 |

---

## 三、改造方案

### 设计原则

1. **从 AI Native 出发，不是从后端有什么出发**
2. **前后端联动**——前端需要的数据，后端必须提供；后端已有的数据，前端必须展示
3. **缺的功能标记为 TODO**，不隐藏也不糊弄
4. **参考 Edict + Hermes + Claude Code 的优秀实践**

### 页面设计（5页 + 通知中心）

#### P1. 任务看板（核心页面）

**参考**: Edict EdictBoard + Hermes Kanban

**卡片设计**（v2.0 简化版，无 DAG 节点概念）：

```
┌─────────────────────────────────────────────┐
│ task-013                                     │
│ 动量因子策略回测                               │
│                                              │
│ 🔄 working   👤 agent1   📊 coding           │
│ ⏱ 12min前创建   ⚠️ standard                  │
│                                              │
│ ┌─ 状态管线 ──────────────────────────────┐  │
│ │ ●pending → ●claimed → ◉working → ○done  │  │
│ └──────────────────────────────────────────┘  │
│                                              │
│ [⏸ 暂停]  [🚫 取消]  [📋 详情]               │
└─────────────────────────────────────────────┘
```

数据来源：tasks 表全部字段，映射清晰。

#### P2. 任务详情面板（Modal）

**参考**: Edict TaskModal + Claude Code diff review + Hermes result section

**8 个区域**（按优先级排列）：

| # | 区域 | 数据来源 | 交互 | 状态 |
|---|------|---------|------|------|
| 1 | **基本信息** | tasks 表 | 只读 | ✅ 后端有 |
| 2 | **状态管线** | tasks.status + VALID_TRANSITIONS | 按钮（基于守卫） | ✅ 后端有 |
| 3 | **产出物** | outputs 表 | 预览/下载 | ✅ 后端有 |
| 4 | **评审记录** | reviews 表 | 只读展示 | ✅ 后端有 |
| 5 | **事件时间线** | events 表 | 时间线展示 | ⚠️ 需补 API |
| 6 | **评论/决策** | comments + decisions 表 | 只读展示 | ✅ 后端有 |
| 7 | **关联经验** | experiences 表 | 只读展示 | ⚠️ 需补 API |
| 8 | **Checkpoint** | ❌ 后端未实现 | 占位（"Checkpoint 功能开发中"） | ❌ TODO |

#### P3. 全局监控

保留 v1.0 的 MonitorPanel 适配 v2.6 API。新增 Agent 状态展示。

#### P4. 系统配置

保留 v1.0 的 SettingsPanel + 项目管理。适配 v2.6 的项目 API。

#### P5. AI Briefing

**参考**: v2.0 设计 §8（日报/周报格式）

当前状态：后端未实现。前端做占位页面，显示"Briefing 功能开发中"。

#### P6. 通知中心（Header 铃铛）

**参考**: v2.0 设计 §3.4 + Linear 通知

当前状态：SSE broker 存在但未对接。前端做铃铛 UI + 占位。

### 后端改动清单

| 优先级 | 改动 | 说明 | 工作量 |
|--------|------|------|--------|
| **P0** | `GET /tasks/{id}?expand=all` | 任务详情聚合（一次返回 comments+outputs+reviews+events+decisions） | 30min |
| **P0** | `GET /tasks/{id}/events` | 事件时间线查询 | 15min |
| **P1** | `GET /tasks/{id}/experiences` | 关联经验查询 | 15min |
| **P1** | ticker 事件推送 SSE | ticker 状态变更 → SSE push | 1h |
| **P2** | Checkpoint 数据模型 + API | 新表 + 交互 API | 设计+编码 3-4h |
| **P2** | AI Briefing 生成 | 聚合数据 + 模板 | 设计+编码 2-3h |

### 前端改动清单

| 优先级 | 改动 | 说明 | 工作量 |
|--------|------|------|--------|
| **P0** | EdictBoard 重写 | v2.0 任务卡片 + 状态管线 + 操作按钮 | 2h |
| **P0** | TaskModal 重写 | 8 区域详情面板 | 3h |
| **P1** | api.ts 补新 API | 对接聚合 API + events + experiences | 30min |
| **P1** | 通知中心占位 | 铃铛 + 下拉面板 | 30min |
| **P1** | AI Briefing 占位 | 页面框架 + "开发中" | 15min |

### 执行顺序

```
Phase 1: 后端补 API（P0 的 3 个接口）    ~1h
Phase 2: 前端核心重写（EdictBoard + TaskModal） ~5h
Phase 3: 前端补完（通知+Briefing占位）   ~1h
Phase 4: 联调 + 部署 + 端到端验证        ~1h
总计: ~8h
```

### Checkpoint 和 AI Briefing 的处理

**v2.8/M3 更新**: Checkpoint 已完成设计（`docs/design/v2.8-state-enhancement.md`），作为 M3 专项开发。
- 三种 Checkpoint 类型（验证/决策/执行）+ Artifact 成果物面板
- 依赖 v2.8 新增的 `waiting_human` 状态
- 前端已有 CheckpointPanel.tsx（350行）和 ArtifactPanel.tsx（185行），扩展对接新 API

AI Briefing 仍未实现，保持占位。

### v2.8 前端易用性改造

详见 `docs/design/v2.8-state-enhancement.md` §三，核心改动：

1. **筛选栏两行布局**（仿 v1.0）：
   - 第 1 行：项目下拉 + 活跃/归档/全部 切换 + 一键归档
   - 第 2 行：11 个状态筛选 + 搜索框

2. **卡片快捷按钮**（最多 3 个）：每个状态有专属操作按钮，直接调 API + toast 反馈

3. **项目下拉移入筛选栏**：支持"全部任务"跨项目聚合

4. **新建军令 title 可选**：后端自动生成（description 前 30 字 + "…"）

---

## 四、与优秀实践的对齐

| 实践 | 我们借鉴了什么 |
|------|--------------|
| **Edict MiniPipe** | 任务卡片上的状态管线可视化（pending→claimed→working→done） |
| **Hermes Kanban** | 卡片 + 结果区 + 评论线程 + 事件流的组合布局 |
| **Claude Code** | TaskModal 的多 Tab 切换（产出/评审/事件），产出 diff 风格展示 |
| **Linear** | 通知铃铛 + 精准推送（不噪音）；状态流转按钮守卫 |
| **Devin** | AI 自主执行的观察窗口理念——Dashboard 不需要密集操作 |
| **OpenClaw Control Center** | WebChat 入口 + Dashboard 入口的双入口对等理念 |
