1|# PRD — 模块6：对话生命周期
2|
3|> 版本：V1.0
4|> 最后更新：2026-04-17
5|> 优先级：P1（增强功能）
6|> 依赖：模块1（项目导入）、模块2（多 Agent 编排）、模块3（任务体系）
7|
8|---
9|
10|## 1. 功能概述
11|
12|对话生命周期是 TeamClaw 的流程骨架。每一次项目协作都以「对话」为核心载体，从用户提出需求开始，经历 8 个阶段、9 种状态转换，最终交付产物并归档。本模块定义对话的完整状态机、阶段流转规则、用户干预点、上下文管理策略和归档/解冻机制，确保 Agent 在人类监督下按既定流程协作。
13|
14|### 设计原则
15|
16|- **人机协作，人不离场** — 关键决策点必须用户确认
17|- **状态可回溯** — 每次状态变更都有记录，支持回滚
18|- **一次一个活跃对话** — 同一项目同时只有一个活跃对话
19|- **归档可解冻** — 归档对话可恢复为活跃状态，保留完整上下文
20|
21|### 与其他模块的关系
22|
23|```
24|模块1（项目导入）
25| │
26| ▼
27|模块6（对话生命周期） ←── 本模块
28| │
29| ├── 模块2（多 Agent 编排）：阶段④⑤⑥的核心执行引擎
30| ├── 模块3（任务体系）：阶段③④的任务管理
31| ├── 模块4（外围能力）：微信端消息适配
32| └── 模块5（知识库）：上下文积累与 RAG 检索
33|```
34|
35|---
36|
37|## 2. 对话生命周期全景图
38|
39|```
40|┌─────────────────────────────────────────────────────────────┐
41|│ 对话生命周期 8 阶段 │
42|│ │
43|│ ① 创建 ② 需求澄清 ③ 任务拆分 ④ Agent 编排执行 │
44|│ ┌────┐ ┌─────────┐ ┌────────┐ ┌──────────────┐ │
45|│ │新建 │───►│ 澄清需求 │──►│ 拆分任务 │──►│ Agent 并行 │ │
46|│ └────┘ └─────────┘ └────────┘ │ /串行执行 │ │
47|│ └──────┬───────┘ │
48|│ │ │
49|│ ⑧ 归档 ⑦ 最终交付 ⑥ 迭代修改 ⑤ 中间审核 │
50|│ ┌────┐ ┌─────────┐ ┌────────┐ ┌──────▼───────┐ │
51|│ │归档 │◄───│ 交付确认 │◄──│ 修改迭代 │◄──│ 审核中间产物 │ │
52|│ └────┘ └─────────┘ └────────┘ └──────────────┘ │
53|│ ▲ │
54|│ └── 解冻：archived → reviewing（保留完整上下文） │
55|└─────────────────────────────────────────────────────────────┘
56|```
57|
58|---
59|
60|## 3. 用户故事
61|
62|| 编号 | 用户故事 | 优先级 |
63||------|---------|--------|
64|| US-01 | 作为用户，我想在项目中发起新对话并描述我的需求 | P1 |
65|| US-02 | 作为用户，我想看到对话当前处于哪个阶段，一目了然 | P1 |
66|| US-03 | 作为用户，我想在 Agent 提问时统一回答，而不是被逐个轰炸 | P1 |
67|| US-04 | 作为用户，我想确认 PRD 后再进入任务拆分，确保方向正确 | P1 |
68|| US-05 | 作为用户，我想在对话执行过程中随时中止 | P1 |
69|| US-06 | 作为用户，我想查看对话的完整历史记录和状态变更日志 | P1 |
70|| US-07 | 作为用户，我想在同一项目中同时只能有一个活跃对话，避免混乱 | P1 |
71|| US-08 | 作为用户，我想对话完成后归档，释放资源并保持项目整洁 | P1 |
72|| US-09 | 作为用户，我想从归档列表恢复某个对话并继续工作 | P1 |
73|| US-10 | 作为用户，我想在对话列表中筛选活跃/归档对话 | P1 |
74|| US-11 | 作为用户，我想通过微信端参与对话的关键确认环节 | P1 |
75|| US-12 | 作为用户，我想看到对话的阶段进度条，了解整体完成度 | P1 |
76|| US-13 | 作为用户，我想限制同一问题的迭代次数，避免无限循环 | P1 |
77|| US-14 | 作为用户，我想搜索历史对话内容 | P2 |
78|| US-15 | 作为用户，我想导出对话记录（Markdown/JSON） | P2 |
79|| US-16 | 作为用户，我想设置对话的上下文长度上限 | P2 |
80|| US-17 | 作为用户，我想对话超时未响应时自动暂停并通知我 | P2 |
81|
82|---
83|
84|## 4. 功能需求清单
85|
86|### 4.1 对话状态机 [P1]
87|
88|**状态定义**：
89|
90|| 状态 | 标识 | 所属阶段 | 说明 |
91||------|------|---------|------|
92|| 创建中 | `creating` | ① 创建 | 对话刚建立，等待初始需求输入 |
93|| 澄清中 | `clarifying` | ② 需求澄清 | Agent 追问细节，明确需求边界 |
94|| 拆分中 | `splitting` | ③ 任务拆分 | Main Agent 将需求拆解为任务 DAG |
95|| 执行中 | `executing` | ④ Agent 编排执行 | Agent 团队并行/串行工作 |
96|| 审核中 | `reviewing` | ⑤ 中间审核 | 等待用户审核中间产物 |
97|| 迭代中 | `iterating` | ⑥ 迭代修改 | 根据用户反馈修改产物 |
98|| 交付中 | `delivering` | ⑦ 最终交付 | 最终产物确认与交付 |
99|| 已归档 | `archived` | ⑧ 归档 | 对话完成，归档保存 |
100|| 已中止 | aborted | 异常 | 用户主动中止对话 | 101| 102|状态流转规则： 103| 104| 105| ┌──────────────────────────────────────────────┐ 106| │ 对话状态机 │ 107| │ │ 108| │ creating ──────► clarifying │ 109| │ │ │ 110| │ ▼ │ 111| │ splitting │ 112| │ │ │ 113| │ ▼ │ 114| │ executing ◄─────► reviewing │ 115| │ │ │ │ │ 116| │ │ │ ▼ │ 117| │ │ iterating │ 118| │ │ │ 119| │ ▼ │ 120| │ delivering │ 121| │ │ │ 122| │ ▼ │ 123| │ archived ────► reviewing（解冻） │ 124| │ │ 125| │ 任意状态 ──────► aborted │ 126| └──────────────────────────────────────────────┘ 127| 128| 129|状态转换矩阵： 130| 131|| 从 → 到 | 触发条件 | 执行者 | 是否可逆 | 132||---------|---------|--------|---------| 133|| creating → clarifying | 系统自动创建对话记录后 | 系统 | 否 | 134|| clarifying → splitting | 用户确认 PRD | 用户 | 是（↩️ 退回澄清） | 135|| splitting → executing | 用户确认任务 DAG | 用户 | 是（↩️ 退回拆分） | 136|| executing → reviewing | 里程碑完成 | 系统 | 否（但可⏸️暂停） | 137|| reviewing → iterating | 用户驳回（附修改意见） | 用户 | 否 | 138|| iterating → reviewing | Agent 修改完成，重新提交 | 系统 | 否 | 139|| reviewing → delivering | 所有审核通过 | 用户 | 是（↩️ 退回审核） | 140|| delivering → archived | 用户确认交付 | 用户 | 是（解冻） | 141|| archived → reviewing | 用户主动解冻 | 用户 | 是（可再次归档） | 142|| 任意 → aborted | 用户主动中止 | 用户 | 否 | 143| 144|### 4.2 阶段 ①：创建（creating）[P1] 145| 146|触发：用户在桌面端或微信端发起新对话 147| 148|前置条件： 149|- 项目已存在且状态为 active 150|- 当前项目无其他活跃对话 151| 152|流程： 153|1. 用户选择项目（或从项目详情页点击「新对话」） 154|2. 输入初始需求描述 155|3. 系统校验：项目是否存在、是否有活跃对话 156|4. 创建对话记录，分配对话 ID 157|5. 自动进入阶段 ②（clarifying） 158| 159|输入： 160|typescript 161|interface CreateConversationInput { 162| project_id: string; 163| initial_requirement: string; // 初始需求描述 164|} 165| 166| 167|输出：对话创建成功，进入对话界面 168| 169|### 4.3 阶段 ②：需求澄清（clarifying）[P1] 170| 171|目标：充分理解需求，消除歧义，明确边界 172| 173|流程： 174|1. PM Agent 分析初始需求 175|2. 生成澄清问题列表 176|3. Main Agent 汇总所有问题，统一向用户提问 177|4. 用户回答（可补充/修改需求） 178|5. PM Agent 确认需求理解，生成 PRD 草稿 179|6. 用户确认 PRD → 进入阶段 ③ 180| 181|用户干预点： 182| 183|| 操作 | 说明 | 184||------|------| 185|| ✏️ 修改 PRD | 用户可编辑 PRD 草稿的任意内容 | 186|| ❓ 补充信息 | 用户主动补充额外需求或约束 | 187|| ↩️ 重写需求 | 回到澄清阶段起点，重新提问 | 188|| ↩️ 退回创建 | 删除当前对话，重新创建 | 189| 190|输出物：确认的 PRD 文档（Markdown 格式，存储于对话上下文中） 191| 192|### 4.4 阶段 ③：任务拆分（splitting）[P1] 193| 194|目标：将 PRD 拆解为可执行的任务 DAG 195| 196|流程： 197|1. Architect Agent 分析 PRD，设计技术方案 198|2. Main Agent 将方案拆解为具体任务 199|3. 为每个任务分配 Agent 角色 200|4. 建立任务间依赖关系（DAG） 201|5. 展示任务清单和执行顺序给用户 202|6. 用户确认 → 进入阶段 ④ 203| 204|用户干预点： 205| 206|| 操作 | 说明 | 207||------|------| 208|| ✏️ 调整优先级 | 拖拽或手动修改任务优先级 | 209|| ✏️ 修改分配 | 更改任务的 Agent 角色 | 210|| ✏️ 增删任务 | 新增或删除任务节点 | 211|| ✏️ 修改依赖 | 调整任务间的依赖关系 | 212|| ↩️ 退回澄清 | 返回阶段 ② 重新确认需求 | 213| 214|输出物：任务 DAG（含依赖关系、Agent 分配、预估时间） 215| 216|### 4.5 阶段 ④：Agent 编排执行（executing）[P1] 217| 218|目标：Agent 团队按 DAG 执行任务 219| 220|流程： 221|1. Main Agent 按 DAG 调度 Agent 222|2. 无依赖的任务并行执行 223|3. 有依赖的任务等待前置完成 224|4. Agent 实时上报进度 225|5. 遇到问题 → Main Agent 汇总后统一提问用户 226|6. 关键里程碑完成 → 进入阶段 ⑤ 227| 228|用户干预操作（7 种，详见模块2 PRD）： 229| 230|| 操作 | 图标 | 说明 | 231||------|------|------| 232|| 暂停 | ⏸️ | 暂停当前所有 Agent 执行 | 233|| 修改 | ✏️ | 修改当前任务的参数或方向 | 234|| 跳过 | ⏭️ | 跳过当前任务，继续后续 | 235|| 回滚 | ↩️ | 回滚到上一个检查点 | 236|| 中止 | 🛑 | 终止整个对话 | 237|| 插入 | 📝 | 插入一个新任务到 DAG | 238|| 提问 | 💬 | 向执行中的 Agent 发送补充指令 | 239| 240|并发提问汇总规则： 241|- 每累积 3 个问题或每隔 30 秒（取先到），统一向用户提问 242|- 相关问题归类：技术选型、功能确认、边界条件等 243|- 避免重复问题：相似问题合并提问 244| 245|### 4.6 阶段 ⑤：中间审核（reviewing）[P1] 246| 247|目标：确保阶段性产物符合预期 248| 249|流程： 250|1. Agent 提交中间产物（代码、文档、设计稿等） 251|2. 系统展示产物预览（diff、截图、文档摘要） 252|3. 用户审核： 253| - ✅ 通过 → 继续后续任务（回到 ④）或所有任务完成则进入 ⑦ 254| - ❌ 不通过 → 进入阶段 ⑥ 255| 256|用户干预点： 257| 258|| 操作 | 说明 | 259||------|------| 260|| ✅ 批准 | 确认当前产物符合预期，继续执行 | 261|| ❌ 驳回 | 附修改意见，退回修改 | 262|| 💬 追加评论 | 对产物添加评论或建议 | 263| 264|审核触发时机： 265|- 单个任务完成时（默认） 266|- 里程碑节点（用户可配置） 267|- 用户主动触发审核 268| 269|### 4.7 阶段 ⑥：迭代修改（iterating）[P1] 270| 271|目标：根据审核反馈修改产物 272| 273|流程： 274|1. Main Agent 分配修改任务给对应 Agent 275|2. Agent 根据反馈修改 276|3. 重新提交审核 → 回到阶段 ⑤ 277|4. 达到迭代上限 → 提示用户考虑重写需求 278| 279|迭代限制： 280|- 同一问题最多迭代 5 轮 281|- 每轮修改必须标注变更范围 282|- 超出迭代限制时提示：⚠️ 此问题已迭代 5 轮仍未解决，建议重新评估需求或调整方向。是否继续迭代？ 283| 284|迭代计数规则： 285|typescript 286|interface IterationRecord { 287| review_id: string; 288| task_id: string; 289| issue_description: string; // 原始问题描述 290| iteration_count: number; // 当前迭代轮次 291| change_summary: string; // 本轮变更摘要 292|} 293| 294| 295|### 4.8 阶段 ⑦：最终交付（delivering）[P1] 296| 297|目标：确认最终产物，完成交付 298| 299|流程： 300|1. 所有任务完成，Main Agent 汇总最终产物 301|2. 生成交付清单（文件列表、变更摘要、测试报告） 302|3. 用户最终确认： 303| - ✅ 确认交付 → 进入阶段 ⑧（归档） 304| - ❌ 需要修改 → 回到阶段 ⑥ 305| 306|交付清单内容： 307| 308|| 项目 | 说明 | 309||------|------| 310|| 产物文件列表 | 所有生成的代码、文档、配置文件路径 | 311|| 变更摘要 | 相对于项目原始状态的变更说明 | 312|| 测试报告 | 单元测试/集成测试结果（如有） | 313|| 使用说明 | 产物使用指南、注意事项 | 314|| 对话摘要 | 本次对话的需求、决策、关键信息记录 | 315| 316|### 4.9 阶段 ⑧：归档（archived）[P1] 317| 318|目标：归档对话，释放资源 319| 320|流程： 321|1. 对话状态标记为 archived 322|2. 完整上下文压缩存储 323|3. 对话从活跃列表移至归档列表 324|4. 该项目可创建新对话 325| 326|归档操作： 327| 328|| 操作 | 说明 | 329||------|------| 330|| 归档 | 对话完成后自动归档，或用户手动归档 | 331|| 删除 | 用户可永久删除已归档对话（需二次确认） | 332|| 导出 | 导出对话记录为 Markdown/JSON | 333| 334|解冻规则： 335|- 用户可从归档列表选择对话「解冻」 336|- 解冻后该对话恢复为 reviewing 状态 337|- 同时自动冻结该项目其他活跃对话（如有） 338|- 保留完整上下文，可继续工作 339|- 解冻后可重新进入 executing / iterating 等阶段 340| 341|解冻流程： 342| 343|用户选择归档对话 → 点击「解冻」 344| ↓ 345|系统检查：该项目是否有其他活跃对话 346| │ 347| ├─ 有活跃对话 → 提示用户：「解冻此对话将暂停当前活跃对话『XXX』，是否继续？」 348| │ ├─ 确认 → 暂停当前活跃对话 → 解冻目标对话 349| │ └─ 取消 → 不操作 350| │ 351| └─ 无活跃对话 → 直接解冻 352| ↓ 353|目标对话状态 → reviewing 354|项目活跃对话 → 已暂停对话 355| 356| 357|### 4.10 活跃对话唯一性约束 [P1] 358| 359|规则：同一项目同时只有一个活跃对话 360| 361|校验时机： 362|- 创建新对话时：检查项目是否有 非 archived/aborted 状态的对话 363|- 解冻归档对话时：检查项目是否有其他活跃对话 364| 365|违反时的提示： 366| 367|⚠️ 当前项目已有活跃对话「对话标题」 368|请先完成或归档当前对话，再创建新对话。 369|[查看当前对话] [归档当前对话] 370| 371| 372|### 4.11 对话上下文管理 [P1] 373| 374|上下文组成： 375| 376|| 组件 | 说明 | 存储 | 377||------|------|------| 378|| 消息记录 | 所有 user/agent/system 消息 | SQLite | 379|| PRD 文档 | 阶段②产出的需求文档 | SQLite + 文件系统 | 380|| 任务 DAG | 阶段③产出的任务计划 | SQLite | 381|| 状态变更日志 | 每次状态转换的审计记录 | SQLite | 382|| Agent 执行日志 | Agent 的运行日志 | SQLite | 383|| 产物引用 | 关联的所有文件产物 | SQLite（引用） | 384| 385|上下文长度管理： 386|- 对话上下文有长度上限（默认 128K tokens，可配置） 387|- 超出上限时： 388| 1. 将最早的消息摘要后压缩存储 389| 2. 摘要信息写入知识库（ChromaDB），保留检索能力 390| 3. 通知用户：「对话上下文已接近上限，早期消息已压缩归档」 391| 392|数据保留策略： 393| 394|| 数据类型 | 保留时长 | 存储方式 | 395||---------|---------|---------| 396|| 活跃对话上下文 | 对话期间 | SQLite | 397|| 归档对话上下文 | 永久（压缩） | SQLite + 文件系统 | 398|| Agent 执行日志 | 90 天 | SQLite | 399|| 产物文件 | 永久 | 文件系统 + Git | 400|| 向量索引 | 跟随对话 | ChromaDB | 401| 402|### 4.12 对话列表与管理 [P1] 403| 404|视图结构： 405|- 活跃对话列表（默认视图） 406|- 归档对话列表（可切换） 407| 408|对话卡片信息： 409| 410|┌─────────────────────────────────────┐ 411|│ 📋 对话标题 状态标签 │ 412|│ 📁 所属项目名 │ 413|│ 🕐 创建时间 · 最后活跃时间 │ 414|│ 📝 需求摘要（首 50 字） │ 415|│ │ 416|│ ████████░░░░░ 阶段进度 4/8 │ 417|│ 任务完成 12/18 · Agent 执行 2.3h │ 418|└─────────────────────────────────────┘ 419| 420| 421|筛选与搜索： 422|- 按状态筛选：活跃 / 归档 / 已中止 423|- 按项目筛选 424|- 按时间范围筛选 425|- 按标题或内容搜索 426| 427|排序： 428|- 最后活跃时间（默认） 429|- 创建时间 430|- 阶段进度 431| 432|### 4.13 对话阶段进度展示 [P1] 433| 434|进度条设计： 435| 436| 437| ① 创建 ② 澄清 ③ 拆分 ④ 执行 ⑤ 审核 ⑥ 迭代 ⑦ 交付 ⑧ 归档 438| ┌──┐ ┌──┐ ┌──┐ ┌────┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ 439| │✅│───►│✅│───►│✅│───►│████│──►│ │ │ │ │ │ │ │ 440| └──┘ └──┘ └──┘ └────┘ └──┘ └──┘ └──┘ └──┘ 441| 442| ✅ 已完成 ████ 当前阶段 ○ 待执行 443| 444| 445|进度计算规则： 446|- 已完成阶段 = 当前阶段序号 - 1 447|- 总进度 = (已完成阶段数 / 8) × 100% 448|- 迭代阶段不计入总进度（视为审核阶段的子流程） 449| 450|### 4.14 微信端适配 [P1] 451| 452|消息格式： 453| 454|📋 阶段：需求澄清 455|━━━━━━━━━━━━━━━━ 456|PM Agent 有 3 个问题： 457| 458|1️⃣ 这个功能面向什么用户群？ 459|2️⃣ 预计并发量是多少？ 460|3️⃣ 是否需要移动端适配？ 461| 462|━━━━━━━━━━━━━━━━ 463|回复编号+答案，如"1 C端用户 2 约1000 3 需要" 464| 465| 466|审核确认消息： 467| 468|⚠️ 需要确认操作 469| 470|操作：执行数据库迁移 471|影响：新增 3 张表，修改 2 张表 472| 473|确认请回复「确认」 474|取消请回复「取消」 475| 476| 477|阶段进度消息： 478| 479|📊 对话进度 480|━━━━━━━━━━━━━━━━ 481|当前阶段：④ Agent 编排执行 482|总体进度：████████░░░░ 50% 483|任务完成：9/18 484|Agent 执行时间：1.5 小时 485| 486|正在执行： 487|🖥️ CoderA - 实现用户认证模块 (████░░ 60%) 488|🗄️ DBA - 设计数据库 Schema (██░░░░ 30%) 489|━━━━━━━━━━━━━━━━ 490| 491| 492|微信端约束： 493| 494|| 约束 | 说明 | 495||------|------| 496|| 仅文字交互 | 不支持语音消息 | 497|| 二次确认 | 所有需确认操作必须二次确认 | 498|| 消息长度 | 单条不超过 2000 字，超出自动分段 | 499|| 图片展示 | 以缩略图 + 链接形式展示 | 500|| 实时性 | 消息推送延迟 ≤ 3 秒 | 501|