# 01 - 任务执行系统设计清单

## 目录

- [1. 核心功能设计清单](#1-核心功能设计清单)
  - [1.1 任务启动机制](#11-任务启动机制)
  - [1.2 任务取消机制](#12-任务取消机制)
  - [1.3 任务暂停/恢复机制](#13-任务暂停恢复机制)
  - [1.4 子任务重试机制](#14-子任务重试机制)
- [2. 状态管理设计清单](#2-状态管理设计清单)
  - [2.1 任务状态流转](#21-任务状态流转)
  - [2.2 协作阶段状态](#22-协作阶段状态)
  - [2.3 子任务状态管理](#23-子任务状态管理)
- [3. 用户交互设计清单](#3-用户交互设计清单)
  - [3.1 RunManager 界面](#31-runmanager-界面)
  - [3.2 任务控制操作](#32-任务控制操作)
  - [3.3 进度展示](#33-进度展示)
- [4. 数据存储设计清单](#4-数据存储设计清单)
  - [4.1 输出流持久化](#41-输出流持久化)
  - [4.2 任务执行历史](#42-任务执行历史)
  - [4.3 实时状态同步](#43-实时状态同步)
- [5. API 接口设计清单](#5-api-接口设计清单)
- [6. 待决策问题清单](#6-待决策问题清单)

---
后续文档规划
文档编号	名称	优先级
02	任务启动机制详细设计	P0
03	任务取消机制详细设计	P0
04	任务暂停恢复机制详细设计	P1
05	输出流持久化详细设计	P1
06	RunManager UI 交互设计	P1
07	API 接口详细设计	P1
08	状态管理详细设计	P1

## 1. 核心功能设计清单

### 1.1 任务启动机制

#### 问题描述
当前点击"启动"按钮后，任务状态变为 executing，但 Supervisor 并没有真正开始执行子任务。

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 1.1.1 | 启动触发方式 | 如何在 `authorize-execution` 后触发 Supervisor 执行 | P0 | 待设计 |
| 1.1.2 | 启动权限检查 | 检查任务状态、执行授权、依赖满足条件 | P0 | 待设计 |
| 1.1.3 | 启动失败处理 | 启动失败时的错误返回和重试机制 | P1 | 待设计 |
| 1.1.4 | 启动通知机制 | 通知前端任务已开始执行 | P1 | 待设计 |

#### 待决策问题
- [ ] Supervisor 触发方式：主动调用 vs 事件监听 vs 轮询检查
- [ ] 启动时是否需要 Lead Agent 参与？
- [ ] 启动后如何保持执行状态（防止页面关闭后丢失）？


### 1.2 任务取消机制

#### 问题描述
当前取消只改状态，但子任务的 background_task 和 LangGraph 线程仍在运行。

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 1.2.1 | 取消范围定义 | 取消主任务？子任务？background_task？LangGraph 线程？ | P0 | 待设计 |
| 1.2.2 | 子任务终止 | 如何终止正在运行的子任务 background_task | P0 | 待设计 |
| 1.2.3 | LangGraph 线程终止 | 如何取消/终止 LangGraph 执行线程 | P0 | 待设计 |
| 1.2.4 | 取消确认机制 | 用户确认对话框，防止误操作 | P1 | 待设计 |
| 1.2.5 | 取消后清理 | 清理临时文件、释放资源、保存状态 | P1 | 待设计 |
| 1.2.6 | 取消通知 | 通知所有相关组件任务已取消 | P1 | 待设计 |

#### 待决策问题
- [ ] 是否支持"强制取消"（立即停止）vs "优雅取消"（等待当前步骤完成）？
- [ ] 取消后是否保留部分执行结果？
- [ ] 取消后是否可以"恢复"？还是只能"重试"？


### 1.3 任务暂停/恢复机制

#### 问题描述
当前没有暂停/恢复功能，用户无法临时停止任务。

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 1.3.1 | 暂停语义定义 | 暂停时正在运行的子任务怎么办？ | P1 | 待设计 |
| 1.3.2 | 暂停实现机制 | 如何停止新的子任务派发？ | P1 | 待设计 |
| 1.3.3 | 恢复触发机制 | 恢复时如何重新触发 Supervisor 执行？ | P1 | 待设计 |
| 1.3.4 | 暂停状态持久化 | 暂停状态如何保存？页面关闭后是否保持？ | P1 | 待设计 |
| 1.3.5 | 暂停超时处理 | 暂停太久是否自动取消？ | P2 | 待设计 |
| 1.3.6 | 暂停次数限制 | 是否限制暂停次数？ | P2 | 待设计 |

#### 待决策问题
- [ ] 暂停时是否终止正在运行的子任务？（A: 不终止 B: 也终止）
- [ ] 暂停期间是否占用资源？
- [ ] 是否支持计划暂停（定时暂停/恢复）？


### 1.4 子任务重试机制

#### 问题描述
子任务失败后，用户需要能够重试单个子任务。

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 1.4.1 | 重试范围 | 重试单个子任务？还是整个任务？ | P2 | 待设计 |
| 1.4.2 | 重试条件 | 什么状态下可以重试？失败？取消？超时？ | P2 | 待设计 |
| 1.4.3 | 重试次数限制 | 最大重试次数？失败几次后停止？ | P2 | 待设计 |
| 1.4.4 | 重试策略 | 立即重试？延迟重试？指数退避？ | P2 | 待设计 |
| 1.4.5 | 失败原因分析 | 是否需要分析失败原因再决定重试？ | P3 | 待设计 |
| 1.4.6 | 自动重试 | 是否支持失败自动重试？ | P3 | 待设计 |

#### 待决策问题
- [ ] 重试时是否重置子任务状态和历史？
- [ ] 重试失败是否影响下游依赖子任务？
- [ ] 是否支持"跳过"失败的子任务？


## 2. 状态管理设计清单

### 2.1 任务状态流转

#### 需要设计的内容

```
当前状态流转:
pending → planning → planned → executing → completed/failed/cancelled

需要补充的状态流转:
pending → planning → planned → [awaiting_exec] → executing → [paused] → executing → completed/failed/cancelled
```

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 2.1.1 | 状态流转图 | 完整的状态机流转图 | P0 | 待设计 |
| 2.1.2 | 状态转换条件 | 每个状态转换的前提条件 | P0 | 待设计 |
| 2.1.3 | 状态转换钩子 | 状态变化时触发的操作 | P1 | 待设计 |
| 2.1.4 | 非法状态拦截 | 防止非法状态转换 | P1 | 待设计 |
| 2.1.5 | 状态历史记录 | 记录状态变化历史 | P2 | 待设计 |

#### 待决策问题
- [ ] 是否需要 `awaiting_exec`（等待执行授权）状态？
- [ ] paused 状态是否可以转为 cancelled？
- [ ] failed 状态是否可以转为 executing（重试）？


### 2.2 协作阶段状态

#### 需要设计的内容

```
当前 CollabPhase:
IDLE → REQ_CONFIRM → PLANNING → PLAN_READY → AWAITING_EXEC → EXECUTING → DONE

与 TaskStatus 的映射关系需要明确
```

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 2.2.1 | 阶段与状态映射 | CollabPhase 与 TaskStatus 的对应关系 | P0 | 待设计 |
| 2.2.2 | 阶段自动推进 | 阶段自动推进的触发条件 | P1 | 待设计 |
| 2.2.3 | 阶段回退机制 | 是否支持阶段回退？ | P2 | 待设计 |
| 2.2.4 | 阶段超时处理 | 某个阶段停留太久怎么办？ | P2 | 待设计 |


### 2.3 子任务状态管理

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 2.3.1 | 子任务状态定义 | 子任务有哪些状态？与主任务状态的关系？ | P0 | 待设计 |
| 2.3.2 | 依赖检查机制 | 子任务执行前如何检查依赖？ | P1 | 待设计 |
| 2.3.3 | 状态自动同步 | 子任务状态变化如何同步到主任务？ | P1 | 待设计 |
| 2.3.4 | 子任务超时处理 | 子任务执行超时怎么办？ | P2 | 待设计 |
| 2.3.5 | 子任务并行度 | 同时执行多少个子任务？ | P2 | 待设计 |


## 3. 用户交互设计清单

### 3.1 RunManager 界面

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 3.1.1 | 任务列表展示 | 显示哪些字段？如何排序？ | P0 | 待设计 |
| 3.1.2 | 任务筛选过滤 | 按状态筛选？按来源筛选？ | P1 | 待设计 |
| 3.1.3 | 任务搜索功能 | 支持按名称搜索？ | P2 | 待设计 |
| 3.1.4 | 任务批量操作 | 支持批量启动/取消？ | P2 | 待设计 |
| 3.1.5 | 子任务展开/折叠 | 如何展示子任务列表？ | P1 | 待设计 |
| 3.1.6 | 智能体名称显示 | 如何显示子任务分配的智能体？ | P1 | 已完成 |

#### 待决策问题
- [ ] 运行中的任务是否置顶显示？
- [ ] 已完成任务是否自动归档？
- [ ] 任务列表分页还是无限滚动？


### 3.2 任务控制操作

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 3.2.1 | 按钮状态逻辑 | 什么状态下显示什么按钮？ | P0 | 待设计 |
| 3.2.2 | 操作确认对话框 | 哪些操作需要确认？ | P1 | 待设计 |
| 3.2.3 | 操作反馈提示 | 操作成功/失败的提示方式 | P1 | 待设计 |
| 3.2.4 | 操作权限控制 | 哪些用户可以操作？ | P2 | 待设计 |
| 3.2.5 | 操作历史记录 | 记录用户的操作历史 | P2 | 待设计 |

#### 按钮显示逻辑（待细化）

```
状态: pending → [启动]
状态: planning → [取消]（可能需要）
状态: executing → [暂停] [取消]
状态: paused → [恢复] [取消]
状态: completed → [查看结果] [删除]
状态: failed → [重试] [查看错误] [取消]
状态: cancelled → [删除]（可能需要）
```


### 3.3 进度展示

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 3.3.1 | 进度计算方式 | 如何计算整体进度？ | P0 | 待设计 |
| 3.3.2 | 子任务进度展示 | 子任务进度如何展示？ | P1 | 待设计 |
| 3.3.3 | 进度条样式 | 进度条的颜色、动画效果 | P1 | 已完成 |
| 3.3.4 | 预计完成时间 | 是否显示 ETA？ | P2 | 待设计 |
| 3.3.5 | 实时输出展示 | 如何展示实时输出流？ | P1 | 待设计 |
| 3.3.6 | 历史输出回放 | 如何回看历史输出？ | P1 | 待设计 |


## 4. 数据存储设计清单

### 4.1 输出流持久化

#### 问题描述
页面关闭后，实时输出流丢失，用户重新打开无法查看。

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 4.1.1 | 存储位置 | 输出流存到哪里？文件？数据库？ | P1 | 待决策 |
| 4.1.2 | 存储格式 | 按行存储？JSON？二进制？ | P1 | 待设计 |
| 4.1.3 | 分块策略 | 大输出如何分块？ | P1 | 待设计 |
| 4.1.4 | 加载策略 | 如何加载历史输出？分页？流式？ | P1 | 待设计 |
| 4.1.5 | 清理策略 | 何时清理旧输出？保留多久？ | P2 | 待设计 |
| 4.1.6 | 实时追加 | 新输出如何实时追加到前端？ | P1 | 待设计 |

#### 待决策问题
- [ ] 存储位置：A) 文件系统 B) 数据库 C) 混合
- [ ] 是否压缩存储？
- [ ] 最大输出大小限制？


### 4.2 任务执行历史

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 4.2.1 | 历史记录内容 | 记录哪些信息？状态变化？输出？ | P2 | 待设计 |
| 4.2.2 | 历史记录存储 | 存到哪里？如何查询？ | P2 | 待设计 |
| 4.2.3 | 历史版本管理 | 多次执行如何管理？ | P2 | 待设计 |
| 4.2.4 | 历史对比功能 | 是否支持对比不同执行？ | P3 | 待设计 |


### 4.3 实时状态同步

#### 需要设计的内容

| 序号 | 设计项 | 说明 | 优先级 | 状态 |
|------|--------|------|--------|------|
| 4.3.1 | 同步机制 | WebSocket？轮询？Server-Sent Events？ | P1 | 待决策 |
| 4.3.2 | 同步频率 | 多久同步一次？ | P1 | 待设计 |
| 4.3.3 | 增量更新 | 只传输变化的部分？ | P2 | 待设计 |
| 4.3.4 | 断线重连 | 页面关闭重开后如何恢复同步？ | P1 | 待设计 |
| 4.3.5 | 并发控制 | 多个前端同时查看同一任务？ | P2 | 待设计 |

#### 待决策问题
- [ ] WebSocket vs 轮询 vs SSE？
- [ ] 是否支持离线模式？


## 5. API 接口设计清单

### 需要新增/修改的接口

| 序号 | 接口 | 方法 | 说明 | 优先级 | 状态 |
|------|------|------|------|--------|------|
| 5.1 | `/tasks/{id}/start` | POST | 启动任务（已存在，需增强） | P0 | 需增强 |
| 5.2 | `/tasks/{id}/cancel` | POST | 取消任务（已存在，需增强） | P0 | 需增强 |
| 5.3 | `/tasks/{id}/pause` | POST | 暂停任务（新增） | P1 | 待设计 |
| 5.4 | `/tasks/{id}/resume` | POST | 恢复任务（新增） | P1 | 待设计 |
| 5.5 | `/tasks/{id}/retry` | POST | 重试失败子任务（新增） | P2 | 待设计 |
| 5.6 | `/tasks/{id}/subtasks/{subtask_id}/retry` | POST | 重试单个子任务（新增） | P2 | 待设计 |
| 5.7 | `/tasks/{id}/output` | GET | 获取任务输出流（新增） | P1 | 待设计 |
| 5.8 | `/tasks/{id}/history` | GET | 获取任务执行历史（新增） | P2 | 待设计 |

### 接口设计要点（每个接口需要明确）

- [ ] 请求参数
- [ ] 响应格式
- [ ] 错误码定义
- [ ] 权限检查
- [ ] 状态校验
- [ ] 副作用说明


## 6. 待决策问题清单

### 6.1 架构决策

| 序号 | 问题 | 选项 | 影响 | 建议 |
|------|------|------|------|------|
| 6.1.1 | Supervisor 触发机制 | A) 主动调用 B) 事件监听 C) 轮询检查 D) 常驻进程 | 任务启动的可靠性 | 待决策 |
| 6.1.2 | 调度器架构 | A) 当前（Lead Agent 兼任）B) 独立 Agent C) 轻量级调度器 | 系统复杂度、性能 | 建议 C→B |
| 6.1.3 | 状态同步机制 | A) WebSocket B) 轮询 C) SSE D) 混合 | 实时性、资源消耗 | 待决策 |

### 6.2 功能决策

| 序号 | 问题 | 选项 | 影响 | 建议 |
|------|------|------|------|------|
| 6.2.1 | 暂停时是否终止运行中的子任务 | A) 不终止 B) 终止 C) 可配置 | 用户体验、实现复杂度 | 建议 A |
| 6.2.2 | 输出流存储位置 | A) 文件 B) 数据库 C) 混合 | 性能、查询能力 | 建议 C |
| 6.2.3 | 取消后是否可恢复 | A) 可恢复 B) 不可恢复（只能重试） | 用户体验 | 建议 B |
| 6.2.4 | 是否支持自动重试 | A) 支持 B) 不支持 | 可靠性、资源消耗 | 建议 P2 支持 |
| 6.2.5 | 简单任务快速路径 | A) 特殊流程 B) 统一流程 | 代码复杂度、用户体验 | 建议 P2 支持 |

### 6.3 体验决策

| 序号 | 问题 | 选项 | 影响 | 建议 |
|------|------|------|------|------|
| 6.3.1 | 运行中任务是否置顶 | A) 是 B) 否 C) 可配置 | 用户查找便利性 | 建议 A |
| 6.3.2 | 已完成任务自动归档 | A) 是 B) 否 C) 按时间归档 | 列表整洁度 | 建议 C |
| 6.3.3 | 是否显示 ETA | A) 是 B) 否 | 用户期望管理 | 建议 B（难估算）|
| 6.3.4 | 任务来源标识 | A) 显示 B) 不显示 | 用户理解 | 建议 A |


## 7. 设计文档产出清单

后续需要产出的详细设计文档：

| 序号 | 文档名称 | 说明 | 优先级 |
|------|----------|------|--------|
| 02 | 任务启动机制详细设计 | 包含时序图、状态机、API 设计 | P0 |
| 03 | 任务取消机制详细设计 | 包含取消流程、资源清理、错误处理 | P0 |
| 04 | 任务暂停恢复机制详细设计 | 包含状态流转、实现方案、边界情况 | P1 |
| 05 | 输出流持久化详细设计 | 包含存储方案、加载策略、清理策略 | P1 |
| 06 | RunManager UI 交互设计 | 包含界面原型、交互流程、状态对应 | P1 |
| 07 | API 接口详细设计 | 包含所有接口的请求/响应/错误码 | P1 |
| 08 | 状态管理详细设计 | 包含完整状态机、转换条件、钩子 | P1 |


## 8. 当前已完成的设计

### 已确定的内容

| 序号 | 内容 | 状态 |
|------|------|------|
| 8.1 | 三种任务来源定义 | ✅ 已完成 |
| 8.2 | 用户角色定位（干预者而非创建者） | ✅ 已完成 |
| 8.3 | RunManager 按钮布局（启动/暂停/取消/刷新） | ✅ 已完成 |
| 8.4 | 子任务智能体名称显示 | ✅ 已完成 |
| 8.5 | 取消任务 API（基础版） | ✅ 已完成 |
| 8.6 | 启动任务 API（基础版） | ✅ 已完成 |

### 待开始的设计

- [ ] 任务启动机制详细设计（P0）
- [ ] 任务取消机制详细设计（P0）
- [ ] 任务暂停/恢复机制详细设计（P1）
- [ ] 输出流持久化设计（P1）
- [ ] 状态流转详细设计（P1）


**文档更新日期**: 2025-04-17
**下次更新**: 完成 02 号详细设计文档后
