1|# PRD — 模块3：任务体系
2|
3|> 版本：V1.0
4|> 最后更新：2026-04-16
5|> 优先级：P0（MVP 核心）
6|
7|---
8|
9|## 1. 功能概述
10|
11|任务体系是 TeamClaw 的骨架。它将用户需求具象化为可追踪、可管理的任务单元，贯穿整个对话生命周期。任务从 DAG 生成到最终完成，经历多种状态流转，关联产物、依赖关系和执行日志。本模块定义任务的数据结构、状态机、依赖管理、产物关联和看板视图。
12|
13|---
14|
15|## 2. 用户故事
16|
17|| 编号 | 用户故事 | 优先级 |
18||------|---------|--------|
19|| US-01 | 作为用户，我想看到所有任务的状态一目了然（看板视图） | P0 |
20|| US-02 | 作为用户，我想点击任务查看详情（描述、Agent、产物、日志） | P0 |
21|| US-03 | 作为用户，我想看到任务之间的依赖关系 | P0 |
22|| US-04 | 作为用户，我想看到任务状态实时更新，无需刷新 | P0 |
23|| US-05 | 作为用户，我想在任务完成后查看生成的产物（代码、文档、配置等） | P0 |
24|| US-06 | 作为用户，我想筛选任务（按状态、Agent、优先级） | P0 |
25|| US-07 | 作为用户，我想重新执行失败的任务 | P0 |
26|| US-08 | 作为用户，我想查看任务的执行时间统计 | P1 |
27|| US-09 | 作为用户，我想为任务添加备注或标签 | P1 |
28|| US-10 | 作为用户，我想导出任务报告（Markdown/JSON） | P2 |
29|| US-11 | 作为用户，我想对比不同版本的产物（diff） | P2 |
30|| US-12 | 作为用户，我想批量操作任务（批量暂停、批量取消） | P2 |
31|
32|---
33|
34|## 3. 功能需求清单
35|
36|### 3.1 任务状态机 [P0]
37|
38|**状态定义**：
39|
40|| 状态 | 标识 | 说明 |
41||------|------|------|
42|| 待办 | `pending` | 任务已创建，等待调度 |
43|| 已分配 | `assigned` | 已分配 Agent，等待启动 |
44|| 执行中 | `in_progress` | Agent 正在执行 |
45|| 已暂停 | `paused` | 用户暂停或系统挂起 |
46|| 被阻塞 | `blocked` | 前置依赖未完成 |
47|| 审核中 | `reviewing` | 任务完成，等待用户审核 |
48|| 已完成 | `done` | 审核通过，任务结束 |
49|| 已失败 | `failed` | 执行失败 |
50|| 已跳过 | `skipped` | 用户主动跳过 |
51|| 已取消 | `cancelled` | 用户取消任务 |
52|
53|**状态流转规则**：
54|
55|```
56| ┌──────────────────────────────────────────────┐
57| │ 任务状态机 │
58| │ │
59| │ pending ──────► assigned ──────► in_progress
60| │ │ │ │ │
61| │ │ │ ┌───────┘ └──────┐
62| │ │ │ ▼ ▼
63| │ │ │ paused reviewing
64| │ │ │ │ │ │
65| │ │ │ │ ┌────┘ └──┐
66| │ │ │ │ ▼ ▼
67| │ ▼ ▼ │ done iterating
68| │ cancelled ◄──── cancelled │ │
69| │ resumed │
70| │ │ │
71| │ ▼ │
72| │ in_progress ◄────────────┘
73| │ │
74| │ ┌─────────┼─────────┐
75| │ ▼ ▼ ▼
76| │ done failed skipped
77| │ │
78| │ retry
79| │ │
80| │ ▼
81| │ pending
82| └──────────────────────────────────────────────┘
83|```
84|
85|**触发条件**：
86|
87|| 从 → 到 | 触发条件 | 执行者 |
88||---------|---------|--------|
89|| pending → assigned | DAG 调度分配 Agent | 系统 |
90|| assigned → in_progress | Agent 开始执行 | 系统 |
91|| in_progress → paused | 用户暂停 | 用户 |
92|| paused → in_progress | 用户恢复 | 用户 |
93|| in_progress → reviewing | Agent 完成执行 | 系统 |
94|| reviewing → done | 用户审核通过 | 用户 |
95|| reviewing → iterating | 用户驳回（附修改意见） | 用户 |
96|| iterating → in_progress | Agent 重新执行 | 系统 |
97|| in_progress → failed | Agent 执行异常或超时 | 系统 |
98|| failed → pending | 用户重试 | 用户 |
99|| in_progress → skipped | 用户跳过 | 用户 |
100|| 任意 → cancelled | 用户取消 | 用户 | 101| 102|### 3.2 任务依赖管理 [P0] 103| 104|依赖类型： 105| 106|| 类型 | 标识 | 说明 | 107||------|------|------| 108|| 完成依赖 | finish_to_start | 前置任务完成后才能开始（默认） | 109|| 产物依赖 | artifact_dependency | 当前任务需要前置任务的产物作为输入 | 110| 111|依赖规则： 112|1. 禁止循环依赖：DAG 生成时检测，有环则拒绝并提示 113|2. 阻塞传播：前置任务失败 → 后置任务自动进入 blocked 114|3. 解除阻塞：前置任务重试成功 → 后置任务自动恢复为 pending 115|4. 跳过传播：前置任务被跳过 → 提示用户确认后置任务处理方式（跳过/强制执行/取消） 116| 117|依赖变更： 118|- 用户可在 DAG 确认阶段修改依赖关系 119|- 执行过程中插入新任务时，自动计算依赖 120|- 不允许删除已执行任务的依赖 121| 122|### 3.3 任务看板 [P0] 123| 124|视图模式： 125| 126|#### 看板视图（默认） 127| 128|┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ 129|│ 待办 │ │ 进行中 │ │ 审核中 │ │ 已完成 │ │ 失败/跳过 │ 130|│ │ │ │ │ │ │ │ │ │ 131|│ ┌──────┐ │ │ ┌──────┐ │ │ ┌──────┐ │ │ ┌──────┐ │ │ ┌──────┐ │ 132|│ │任务A │ │ │ │任务C │ │ │ │任务D │ │ │ │任务E │ │ │ │任务G │ │ 133|│ │PM │ │ │ │CoderA│ │ │ │Architect│ │ │DBA │ │ │ │DevOps│ │ 134|│ │⏱ 5min│ │ │ │████░░│ │ │ │审核中 │ │ │ ✅ │ │ │ │❌ │ │ 135|│ └──────┘ │ │ └──────┘ │ │ └──────┘ │ │ └──────┘ │ │ └──────┘ │ 136|│ ┌──────┐ │ │ ┌──────┐ │ │ │ │ │ │ │ 137|│ │任务B │ │ │ │任务F │ │ │ │ │ │ │ │ 138|│ │Designer│ │ │CoderB│ │ │ │ │ │ │ │ 139|│ │⏱ 8min│ │ │ │██░░░░│ │ │ │ │ │ │ │ 140|│ └──────┘ │ │ └──────┘ │ │ │ │ │ │ │ 141|└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ 142| 143| 144|任务卡片信息： 145|- 任务标题 146|- 分配的 Agent 角色（图标 + 名称） 147|- 进度条（执行中任务） 148|- 预估/已用时间 149|- 状态标签 150|- 优先级标记（P0 红色、P1 黄色、P2 灰色） 151| 152|#### 列表视图 153|- 紧凑表格展示 154|- 列：状态、标题、Agent、优先级、耗时、操作 155|- 支持排序和筛选 156| 157|#### DAG 图视图 158|- 节点为任务，边为依赖关系 159|- 实时更新节点颜色反映状态 160|- 可缩放、拖拽、点击查看详情 161| 162|### 3.4 任务详情页 [P0] 163| 164|布局： 165| 166|┌─────────────────────────────────────────────────────┐ 167|│ ← 返回 任务标题 状态标签 │ 168|├─────────────────────────────────────────────────────┤ 169|│ │ 170|│ 📋 基本信息 │ 171|│ ┌─────────────────────────────────────────────┐ │ 172|│ │ 描述：根据 PRD 设计数据库 Schema... │ │ 173|│ │ Agent：DBA │ │ 174|│ │ 优先级：P0 │ │ 175|│ │ 依赖：[任务A] → 本任务 │ │ 176|│ │ 预估时间：15 分钟 │ │ 177|│ │ 实际耗时：12 分钟 │ │ 178|│ └─────────────────────────────────────────────┘ │ 179|│ │ 180|│ 📦 产物 │ 181|│ ┌─────────────────────────────────────────────┐ │ 182|│ │ schema.sql (v1) 📥 👁️ 📝 │ │ 183|│ │ migration_001.sql (v1) 📥 👁️ 📝 │ │ 184|│ └─────────────────────────────────────────────┘ │ 185|│ │ 186|│ 📝 执行日志 │ 187|│ ┌─────────────────────────────────────────────┐ │ 188|│ │ [10:32:01] 开始分析 PRD... │ │ 189|│ │ [10:32:05] 识别到 5 个实体... │ │ 190|│ │ [10:32:12] 生成 Schema 草案... │ │ 191|│ │ [10:32:18] 创建迁移脚本... │ │ 192|│ │ [10:32:20] ✅ 任务完成 │ │ 193|│ └─────────────────────────────────────────────┘ │ 194|│ │ 195|│ ⚡ 操作 │ 196|│ [暂停] [修改] [跳过] [回滚] [重新执行] │ 197|│ │ 198|└─────────────────────────────────────────────────────┘ 199| 200| 201|### 3.5 产物管理 [P0] 202| 203|产物类型： 204| 205|| 类型 | 标识 | 文件示例 | 206||------|------|---------| 207|| 代码 | code | *.ts, *.py, *.rs | 208|| 文档 | doc | *.md, *.txt | 209|| 设计 | design | *.html, *.css | 210|| 配置 | config | *.yaml, *.json, *.toml | 211|| 数据库 | db_schema | *.sql | 212|| 脚本 | script | *.sh, *.bat | 213| 214|产物生命周期： 215| 216|Agent 生成产物 → 自动保存到项目目录 → 记录版本 → 用户可预览/下载/对比 217| 218| 219|产物操作： 220| 221|| 操作 | 说明 | 222||------|------| 223|| 预览 | 在详情页内直接查看文件内容（代码高亮） | 224|| 下载 | 导出单个文件或打包下载 | 225|| 对比 | 查看不同版本的 diff（P2） | 226|| 编辑 | 用户手动微调产物内容 | 227| 228|产物版本规则： 229|- 同一任务重新执行时，产物版本号递增 230|- 旧版本不删除，可在版本历史中查看 231|- 回滚时恢复到指定版本 232| 233|### 3.6 任务筛选与搜索 [P0] 234| 235|筛选条件： 236|- 状态：多选（pending / in_progress / done / failed / ...） 237|- Agent 角色：多选 238|- 优先级：多选（P0 / P1 / P2） 239|- 时间范围：创建时间 / 完成时间 240| 241|搜索： 242|- 按任务标题搜索（模糊匹配） 243|- 按任务描述搜索（全文检索） 244| 245|排序： 246|- 创建时间（默认） 247|- 优先级 248|- 状态 249|- 预估时间 250| 251|### 3.7 任务统计 [P1] 252| 253|项目级统计： 254| 255|┌──────────────────────────────────────┐ 256|│ 📊 项目统计 │ 257|│ │ 258|│ 总任务数：23 │ 259|│ ████████████░░░░ 完成 65% (15/23) │ 260|│ │ 261|│ 按 Agent： │ 262|│ CoderA ████████░░ 8 个 │ 263|│ CoderB ██████░░░░ 6 个 │ 264|│ Architect ████░░░░░░ 4 个 │ 265|│ DBA ██░░░░░░░░ 2 个 │ 266|│ │ 267|│ 平均耗时：12 分钟 │ 268|│ 总 Agent 执行时间：4.6 小时 │ 269|│ 产物数量：34 个文件 │ 270|└──────────────────────────────────────┘ 271| 272| 273|### 3.8 任务备注与标签 [P1] 274| 275|备注： 276|- 用户可为任务添加文字备注 277|- 支持多条备注，按时间排列 278|- Agent 不可见，仅供用户记录 279| 280|标签： 281|- 预设标签：bug、enhancement、refactor、docs 282|- 支持自定义标签 283|- 可按标签筛选 284| 285|### 3.9 任务导出 [P2] 286| 287|导出格式： 288|- Markdown：任务清单，含标题、状态、Agent、描述 289|- JSON：完整数据，含依赖关系、产物路径 290|- PDF：格式化报告（调用系统打印） 291| 292|### 3.10 批量操作 [P2] 293| 294|支持操作： 295|- 批量暂停 296|- 批量取消 297|- 批量修改优先级 298|- 批量重新分配 Agent 299| 300|操作流程： 301|1. 用户多选任务（复选框或 Shift+点击） 302|2. 选择操作类型 303|3. 确认操作（二次确认） 304|4. 批量执行 305| 306|--- 307| 308|## 4. 数据模型 309| 310|sql 311|-- 任务表（补充模块2中的定义） 312|-- 与模块2共用同一张 tasks 表，这里补充查询索引 313| 314|CREATE INDEX idx_tasks_project_status ON tasks(project_id, status); 315|CREATE INDEX idx_tasks_conversation ON tasks(conversation_id); 316|CREATE INDEX idx_tasks_agent_role ON tasks(agent_role); 317|CREATE INDEX idx_tasks_priority ON tasks(priority); 318| 319|-- 任务备注表 320|CREATE TABLE task_notes ( 321| id TEXT PRIMARY KEY, 322| task_id TEXT NOT NULL, 323| content TEXT NOT NULL, 324| created_at INTEGER NOT NULL, 325| FOREIGN KEY (task_id) REFERENCES tasks(id) 326|); 327| 328|-- 任务标签关联表 329|CREATE TABLE task_tags ( 330| id TEXT PRIMARY KEY, 331| task_id TEXT NOT NULL, 332| tag TEXT NOT NULL, 333| created_at INTEGER NOT NULL, 334| FOREIGN KEY (task_id) REFERENCES tasks(id), 335| UNIQUE(task_id, tag) 336|); 337| 338|-- 任务时间记录表 339|CREATE TABLE task_time_logs ( 340| id TEXT PRIMARY KEY, 341| task_id TEXT NOT NULL, 342| action TEXT NOT NULL, -- started | paused | resumed | completed | failed 343| timestamp INTEGER NOT NULL, 344| FOREIGN KEY (task_id) REFERENCES tasks(id) 345|); 346| 347|-- 任务操作记录表（审计日志） 348|CREATE TABLE task_audit_log ( 349| id TEXT PRIMARY KEY, 350| task_id TEXT NOT NULL, 351| action TEXT NOT NULL, -- status_change | priority_change | agent_reassign | note_added 352| old_value TEXT, 353| new_value TEXT, 354| operator TEXT NOT NULL, -- user | system | agent:{role} 355| created_at INTEGER NOT NULL, 356| FOREIGN KEY (task_id) REFERENCES tasks(id) 357|); 358| 359| 360|--- 361| 362|## 5. Tauri Commands 接口 363| 364|typescript 365|// 任务查询 366|get_task(taskId: string): Promise<TaskDetail> 367|list_tasks(filter: TaskFilter): Promise<Task[]> 368|get_task_stats(projectId: string): Promise<TaskStats> 369| 370|// 任务操作 371|retry_task(taskId: string): Promise<void> 372|cancel_task(taskId: string): Promise<void> 373|skip_task(taskId: string): Promise<void> 374|update_task_priority(taskId: string, priority: number): Promise<void> 375|reassign_task(taskId: string, agentRole: AgentRole): Promise<void> 376| 377|// 任务备注 378|add_task_note(taskId: string, content: string): Promise<TaskNote> 379|list_task_notes(taskId: string): Promise<TaskNote[]> 380|delete_task_note(noteId: string): Promise<void> 381| 382|// 任务标签 383|add_task_tag(taskId: string, tag: string): Promise<void> 384|remove_task_tag(taskId: string, tag: string): Promise<void> 385|list_all_tags(projectId: string): Promise<string[]> 386| 387|// 产物管理 388|list_artifacts(taskId: string): Promise<Artifact[]> 389|get_artifact_content(artifactId: string): Promise<string> 390|download_artifact(artifactId: string, targetPath: string): Promise<void> 391|get_artifact_versions(taskId: string): Promise<ArtifactVersion[]> 392| 393|// 任务时间线 394|get_task_timeline(taskId: string): Promise<TaskTimeLog[]> 395|get_task_audit_log(taskId: string): Promise<TaskAuditEntry[]> 396| 397|// 导出 398|export_tasks(projectId: string, format: 'markdown' | 'json'): Promise<string> 399| 400|// 批量操作 401|batch_update_tasks(taskIds: string[], action: BatchAction): Promise<BatchResult> 402| 403| 404|--- 405| 406|## 6. UI 交互流程 407| 408|### 6.1 看板操作流程 409| 410| 411|[项目详情页 → 任务 Tab] 412| │ 413| ├─ 看板视图（默认） 414| │ ├─ 拖拽任务卡片到其他列 → 更新状态 415| │ ├─ 点击卡片 → 打开任务详情 416| │ └─ 右键卡片 → 快捷操作菜单 417| │ 418| ├─ 列表视图 419| │ ├─ 表头点击排序 420| │ ├─ 复选框多选 → 批量操作 421| │ └─ 行点击 → 打开任务详情 422| │ 423| ├─ DAG 视图 424| │ ├─ 节点点击 → 弹出任务摘要 425| │ ├─ 双击节点 → 打开任务详情 426| │ └─ 缩放/拖拽/居中 427| │ 428| └─ 筛选栏 429| ├─ 状态筛选（多选） 430| ├─ Agent 筛选（多选） 431| ├─ 搜索框 432| └─ 排序切换 433| 434| 435|### 6.2 任务详情操作流程 436| 437| 438|[任务详情页] 439| │ 440| ├─ 产物区域 441| │ ├─ 点击文件 → 内联预览（代码高亮） 442| │ ├─ 点击版本号 → 版本历史列表 443| │ ├─ 点击 📥 → 下载文件 444| │ └─ 点击 📝 → 编辑产物（弹出编辑器） 445| │ 446| ├─ 日志区域 447| │ ├─ 自动滚动到底部（最新日志） 448| │ ├─ 支持搜索日志内容 449| │ └─ 支持按级别筛选（info/warn/error） 450| │ 451| └─ 操作区域 452| ├─ ⏸️ 暂停 → 确认弹窗 → 暂停 453| ├─ ✏️ 修改 → 修改弹窗 → 重新执行 454| ├─ ⏭️ 跳过 → 确认弹窗 → 跳过 455| ├─ ↩️ 回滚 → 选择检查点 → 回滚 456| ├─ 🔄 重试 → 确认弹窗 → 重新执行 457| └─ 💬 指令 → 输入框 → 发送给 Agent 458| 459| 460|--- 461| 462|## 7. 边界条件与异常处理 463| 464|| 场景 | 处理方式 | 465||------|---------| 466|| 任务 DAG 有环 | 生成时检测，提示用户修正 | 467|| 删除有后置依赖的任务 | 提示影响范围，确认后级联处理 | 468|| 产物文件被外部删除 | 检测到缺失，标记为「产物丢失」，支持重新生成 | 469|| 任务卡片拖拽到非法列 | 拒绝操作，提示合法的状态转换 | 470|| 同时打开多个任务详情 | 支持 Tab 切换 | 471|| 大量任务（100+）渲染卡顿 | 虚拟滚动，懒加载 | 472|| 搜索结果为空 | 提示无匹配，建议放宽条件 | 473|| Agent 执行超时 | 自动标记 failed，通知用户 | 474| 475|--- 476| 477|## 8. 验收标准 478| 479|### P0 验收（MVP） 480|- [ ] 看板视图正确展示任务状态（5 列） 481|- [ ] 任务卡片展示完整信息（标题、Agent、进度、时间） 482|- [ ] 任务状态按状态机正确流转 483|- [ ] 任务依赖关系正确阻断/解锁 484|- [ ] 任务详情页展示描述、产物、日志 485|- [ ] 产物可预览和下载 486|- [ ] 支持按状态、Agent 筛选 487|- [ ] 支持按标题搜索 488|- [ ] 失败任务可重试 489|- [ ] 任务可跳过和取消 490| 491|### P1 验收 492|- [ ] 列表视图可用 493|- [ ] DAG 图视图可用 494|- [ ] 任务统计信息准确 495|- [ ] 任务备注和标签功能可用 496|- [ ] 任务时间线记录完整 497| 498|### P2 验收 499|- [ ] 任务导出（Markdown/JSON） 500|- [ ] 产物版本 diff 对比 501|