1|# TeamClaw 对话生命周期设计文档 V1.0
2|
3|> 最后更新：2026-04-16
4|> 状态：已确认，待开发
5|
6|---
7|
8|## 1. 概述
9|
10|TeamClaw 的每一次项目协作都以「对话」为核心载体。对话从用户提出需求开始，经历 8 个阶段、9 种状态转换，最终交付产物并归档。用户可在关键节点介入，确保 Agent 始终在人类监督下工作。
11|
12|### 设计原则
13|- **人机协作，人不离场** — 关键决策点必须用户确认
14|- **状态可回溯** — 每次状态变更都有记录，支持回滚
15|- **一次一个活跃对话** — 同一项目同时只有一个活跃对话
16|- **归档可解冻** — 归档对话可恢复为活跃状态，保留完整上下文
17|
18|---
19|
20|## 2. 对话生命周期全景图
21|
22|```
23|┌─────────────────────────────────────────────────────────────┐
24|│ 对话生命周期 8 阶段 │
25|│ │
26|│ ① 创建 ② 需求澄清 ③ 任务拆分 ④ Agent 编排执行 │
27|│ ┌────┐ ┌─────────┐ ┌────────┐ ┌──────────────┐ │
28|│ │新建 │───►│ 澄清需求 │──►│ 拆分任务 │──►│ Agent 并行 │ │
29|│ └────┘ └─────────┘ └────────┘ │ /串行执行 │ │
30|│ └──────┬───────┘ │
31|│ │ │
32|│ ⑧ 归档 ⑦ 最终交付 ⑥ 迭代修改 ⑤ 中间审核 │
33|│ ┌────┐ ┌─────────┐ ┌────────┐ ┌──────▼───────┐ │
34|│ │归档 │◄───│ 交付确认 │◄──│ 修改迭代 │◄──│ 审核中间产物 │ │
35|│ └────┘ └─────────┘ └────────┘ └──────────────┘ │
36|│ ▲ │
37|│ └── 解冻：归档 → 活跃（保留完整上下文） │
38|└─────────────────────────────────────────────────────────────┘
39|```
40|
41|---
42|
43|## 3. 状态定义
44|
45|| 状态 | 英文标识 | 所属阶段 | 说明 |
46||------|---------|---------|------|
47|| 创建中 | `creating` | ① 创建 | 对话刚建立，等待初始需求输入 |
48|| 澄清中 | `clarifying` | ② 需求澄清 | Agent 追问细节，明确需求边界 |
49|| 拆分中 | `splitting` | ③ 任务拆分 | Main Agent 将需求拆解为任务 DAG |
50|| 执行中 | `executing` | ④ Agent 编排执行 | Agent 团队并行/串行工作 |
51|| 审核中 | `reviewing` | ⑤ 中间审核 | 等待用户审核中间产物 |
52|| 迭代中 | `iterating` | ⑥ 迭代修改 | 根据用户反馈修改产物 |
53|| 交付中 | `delivering` | ⑦ 最终交付 | 最终产物确认与交付 |
54|| 已归档 | `archived` | ⑧ 归档 | 对话完成，归档保存 |
55|| 已中止 | `aborted` | 异常 | 用户主动中止对话 |
56|
57|---
58|
59|## 4. 各阶段详细设计
60|
61|### 阶段 ①：创建（creating）
62|
63|**触发**：用户在桌面端或微信端发起新对话
64|
65|**流程**：
66|1. 用户选择项目（或创建新项目）
67|2. 输入初始需求描述
68|3. 系统创建对话记录，分配对话 ID
69|4. 自动进入阶段 ②
70|
71|**用户干预点**：无（自动流转）
72|
73|---
74|
75|### 阶段 ②：需求澄清（clarifying）
76|
77|**目标**：充分理解需求，消除歧义，明确边界
78|
79|**流程**：
80|1. PM Agent 分析初始需求
81|2. 生成澄清问题列表
82|3. **Main Agent 汇总所有问题，统一向用户提问**
83|4. 用户回答（可补充/修改需求）
84|5. PM Agent 确认需求理解，生成 PRD 草稿
85|6. 用户确认 PRD → 进入阶段 ③
86|
87|**用户干预点**：
88|- ✏️ 修改 PRD 内容
89|- ❓ 补充额外信息
90|- ↩️ 重写需求（回到本阶段起点）
91|
92|**输出物**：确认的 PRD 文档
93|
94|---
95|
96|### 阶段 ③：任务拆分（splitting）
97|
98|**目标**：将 PRD 拆解为可执行的任务 DAG
99|
100|流程： 101|1. Architect Agent 分析 PRD，设计技术方案 102|2. Main Agent 将方案拆解为具体任务 103|3. 为每个任务分配 Agent 角色 104|4. 建立任务间依赖关系（DAG） 105|5. 展示任务清单和执行顺序给用户 106|6. 用户确认 → 进入阶段 ④ 107| 108|用户干预点： 109|- ✏️ 调整任务优先级 110|- ✏️ 修改任务分配 111|- ✏️ 增删任务 112|- ↩️ 退回需求澄清阶段 113| 114|输出物：任务 DAG（含依赖关系、Agent 分配、预估时间） 115| 116|--- 117| 118|### 阶段 ④：Agent 编排执行（executing） 119| 120|目标：Agent 团队按 DAG 执行任务 121| 122|流程： 123|1. Main Agent 按 DAG 调度 Agent 124|2. 无依赖的任务并行执行 125|3. 有依赖的任务等待前置完成 126|4. Agent 实时上报进度 127|5. 遇到问题 → Main Agent 汇总后统一提问用户 128|6. 关键里程碑完成 → 进入阶段 ⑤ 129| 130|用户干预点（7 种操作）： 131| 132|| 操作 | 说明 | 133||------|------| 134|| ⏸️ 暂停 | 暂停当前所有 Agent 执行 | 135|| ✏️ 修改 | 修改当前任务的参数或方向 | 136|| ⏭️ 跳过 | 跳过当前任务，继续后续 | 137|| ↩️ 回滚 | 回滚到上一个检查点 | 138|| 🛑 中止 | 终止整个对话 | 139|| 📝 插入 | 插入一个新任务到 DAG | 140|| 💬 提问 | 向执行中的 Agent 发送补充指令 | 141| 142|并发提问规则： 143| 144|AgentA 提问: "数据库用 PostgreSQL 还是 MySQL？" 145|AgentB 提问: "缓存用 Redis 吗？" 146|AgentC 提问: "需要做国际化吗？" 147| 148| ↓ Main Agent 汇总 ↓ 149| 150|Main Agent 统一提问用户: 151| "有 3 个问题需要确认： 152| 1. 数据库选型：PostgreSQL / MySQL？ 153| 2. 是否需要 Redis 缓存？ 154| 3. 是否需要国际化支持？" 155| 156| 157|--- 158| 159|### 阶段 ⑤：中间审核（reviewing） 160| 161|目标：确保阶段性产物符合预期 162| 163|流程： 164|1. Agent 提交中间产物（代码、文档、设计稿等） 165|2. 系统展示产物预览（diff、截图、文档摘要） 166|3. 用户审核： 167| - ✅ 通过 → 继续后续任务（回到 ④ 或进入 ⑦） 168| - ❌ 不通过 → 进入阶段 ⑥ 169| 170|用户干预点： 171|- ✅ 批准 172|- ❌ 驳回（附修改意见） 173|- 💬 追加评论 174| 175|--- 176| 177|### 阶段 ⑥：迭代修改（iterating） 178| 179|目标：根据审核反馈修改产物 180| 181|流程： 182|1. Main Agent 分配修改任务给对应 Agent 183|2. Agent 根据反馈修改 184|3. 重新提交审核 → 回到阶段 ⑤ 185|4. 最多迭代 5 轮，超出提示用户考虑重写需求 186| 187|限制： 188|- 同一问题最多迭代 5 轮 189|- 每轮修改必须标注变更范围 190| 191|--- 192| 193|### 阶段 ⑦：最终交付（delivering） 194| 195|目标：确认最终产物，完成交付 196| 197|流程： 198|1. 所有任务完成，Main Agent 汇总最终产物 199|2. 生成交付清单（文件列表、变更摘要、测试报告） 200|3. 用户最终确认： 201| - ✅ 确认交付 → 进入阶段 ⑧ 202| - ❌ 需要修改 → 回到阶段 ⑥ 203| 204|输出物： 205|- 完整代码/文件 206|- 变更摘要 207|- 测试报告 208|- 使用说明 209| 210|--- 211| 212|### 阶段 ⑧：归档（archived） 213| 214|目标：归档对话，释放资源 215| 216|流程： 217|1. 对话状态标记为 archived 218|2. 完整上下文压缩存储 219|3. 对话从活跃列表移至归档列表 220|4. 该项目可创建新对话 221| 222|解冻规则： 223|- 用户可从归档列表选择对话「解冻」 224|- 解冻后该对话恢复为 reviewing 状态 225|- 同时自动冻结该项目其他活跃对话 226|- 保留完整上下文，可继续工作 227| 228|--- 229| 230|## 5. 状态转换矩阵 231| 232| 233| ┌──────────────────────────────────────┐ 234| │ 状态转换规则 │ 235| ├──────────┬───────────────────────────┤ 236| │ 从 → 到 │ 触发条件 │ 237| ├──────────┼───────────────────────────┤ 238| │ creating │ 自动 │ 239| │ ↓ │ │ 240| │ clarifying│ │ 241| ├──────────┼───────────────────────────┤ 242| │ clarifying│ 用户确认 PRD │ 243| │ ↓ │ │ 244| │ splitting │ │ 245| ├──────────┼───────────────────────────┤ 246| │ splitting │ 用户确认任务 DAG │ 247| │ ↓ │ │ 248| │ executing │ │ 249| ├──────────┼───────────────────────────┤ 250| │ executing │ 里程碑完成 │ 251| │ ↓ │ │ 252| │ reviewing │ │ 253| ├──────────┼───────────────────────────┤ 254| │ reviewing │ 用户驳回 │ 255| │ ↓ │ │ 256| │ iterating │ │ 257| ├──────────┼───────────────────────────┤ 258| │ iterating │ 修改完成 │ 259| │ ↓ │ │ 260| │ reviewing │ │ 261| ├──────────┼───────────────────────────┤ 262| │ reviewing │ 全部通过 │ 263| │ ↓ │ │ 264| │ delivering│ │ 265| ├──────────┼───────────────────────────┤ 266| │ delivering│ 用户确认交付 │ 267| │ ↓ │ │ 268| │ archived │ │ 269| ├──────────┼───────────────────────────┤ 270| │ archived │ 用户主动解冻 │ 271| │ ↓ │ │ 272| │ reviewing │ │ 273| ├──────────┼───────────────────────────┤ 274| │ 任意状态 │ 用户主动中止 │ 275| │ ↓ │ │ 276| │ aborted │ │ 277| └──────────┴───────────────────────────┘ 278| 279| 280|--- 281| 282|## 6. 微信端适配 283| 284|### 消息格式 285| 286|📋 阶段：需求澄清 287|━━━━━━━━━━━━━━━━ 288|PM Agent 有 3 个问题： 289| 290|1️⃣ 这个功能面向什么用户群？ 291|2️⃣ 预计并发量是多少？ 292|3️⃣ 是否需要移动端适配？ 293| 294|━━━━━━━━━━━━━━━━ 295|回复编号+答案，如"1 C端用户 2 约1000 3 需要" 296| 297| 298|### 审核确认 299| 300|⚠️ 需要确认操作 301| 302|操作：执行数据库迁移 303|影响：新增 3 张表，修改 2 张表 304| 305|确认请回复「确认」 306|取消请回复「取消」 307| 308| 309|### 约束 310|- 仅文字交互，不支持语音 311|- 所有需确认操作必须二次确认 312|- 单条消息不超过 2000 字，超出自动分段 313|- 图片以缩略图+链接形式展示 314| 315|--- 316| 317|## 7. 数据保留策略 318| 319|| 数据类型 | 保留时长 | 存储方式 | 320||---------|---------|---------| 321|| 活跃对话上下文 | 对话期间 | SQLite | 322|| 归档对话上下文 | 永久（压缩） | SQLite + 文件系统 | 323|| Agent 执行日志 | 90 天 | SQLite | 324|| 产物文件 | 永久 | 文件系统 + Git | 325|| 向量索引 | 跟随对话 | ChromaDB | 326| 327|--- 328| 329|文档维护者：TeamClaw 项目组 330|