docs: add thread status sync design

docs/superpowers/specs/2026-04-04-master-agent-thread-status-sync-design.md

@@ -0,0 +1,360 @@
+# 主 Agent 线程状态文档与增量同步设计
+
+日期：`2026-04-04`
+
+## 1. 背景
+
+当前 Boss 已经具备：
+
+- 新设备导入时，主 Agent 会主动理解活跃线程的项目目标、当前进度、技术架构、阻塞点和建议下一步。
+- 已导入设备上的活跃线程一旦继续活动，系统会自动同步项目理解，并在主 Agent 会话里补轻量提醒。
+- 主 Agent 当前已经能读取最近的活跃项目理解，并基于这些理解给出下一步建议和接手提示。
+
+当前问题也很明确：
+
+1. **主 Agent 为了跟上线程进展，仍然会在不少场景重新向线程发起完整理解请求。**
+   - token 消耗偏高
+   - prompt 体积偏大
+   - 当活跃线程很多时，成本会快速放大
+
+2. **如果只依赖“完整项目理解快照”，实时性又不够。**
+   - 用户继续在电脑上操作 Codex 线程时，主 Agent 可能落后一段时间
+   - 主 Agent 接手时，需要重新拉很多上下文
+
+3. **把状态写回线程项目工作区作为文档文件不可取。**
+   - 会污染工作区
+   - 容易制造脏 diff
+   - 容易被误提交
+   - 多线程并行时容易冲突
+
+因此，这个设计的目标是：
+
+- 让主 Agent 平时更多依赖结构化状态，而不是反复扫整段聊天历史
+- 保持接近实时的项目进展同步
+- 只在关键时刻多花 token
+- 不污染线程项目工作区
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. 为每个真实线程建立一份 **线程状态文档**，作为主 Agent 理解线程的主入口。
+2. 为每个线程建立一组 **线程进展事件**，用于记录最近的轻量增量变化。
+3. 主 Agent 默认改为基于：
+   - 线程状态文档
+   - 最近几条线程进展事件
+   - 项目记忆
+   来理解活跃线程。
+4. 仅在关键时刻再向线程发起完整深拉，以保持高实时性。
+5. 让“新设备导入”和“已导入设备的持续同步”共用同一套机制。
+6. 在线程详情或会话信息里提供一个只读的 `线程状态` 入口，便于用户查看主 Agent 当前掌握的状态。
+
+### 2.2 非目标
+
+1. 不把线程状态文档写入用户项目仓库。
+2. 不把线程状态文档开放成默认可编辑内容。
+3. 不引入向量数据库、复杂 embedding 检索或多级知识库系统。
+4. 不重写现有群聊审批、设备导入或主 Agent 记忆架构。
+5. 不把所有线程活动都升级成完整项目理解请求。
+
+## 3. 设计概览
+
+本设计采用三层结构：
+
+1. **线程状态文档**
+   - 稳定快照
+   - 代表“当前线程现在是什么状态”
+
+2. **线程进展事件**
+   - 轻量增量
+   - 代表“最近发生了什么变化”
+
+3. **关键时刻深拉**
+   - 只在主 Agent 真要接手、真要调度、真要做关键判断时触发
+   - 用更高 token 成本换取更高准确度
+
+主 Agent 后续默认读取路径为：
+
+1. 当前用户指令
+2. 对应线程/项目的线程状态文档
+3. 最近 3 到 5 条线程进展事件
+4. 项目记忆
+5. 必要时再向线程发起一次深拉
+
+## 4. 数据模型
+
+### 4.1 ThreadStatusDocument
+
+新增线程级状态文档模型。
+
+建议字段：
+
+- `documentId`
+- `projectId`
+- `threadId`
+- `threadDisplayName`
+- `folderName`
+- `deviceId`
+- `projectGoal`
+- `currentPhase`
+- `currentProgress`
+- `technicalArchitecture`
+- `currentBlockers`
+- `recommendedNextStep`
+- `keyFiles: string[]`
+- `keyCommands: string[]`
+- `updatedAt`
+- `sourceTaskId`
+- `sourceKind`
+
+说明：
+
+- `currentPhase` 用于把线程从“当前在做什么阶段”抽出来，例如：
+  - 需求梳理
+  - 架构设计
+  - 功能实现
+  - 联调验证
+  - 修复回归
+  - 部署上线
+- `keyFiles` 和 `keyCommands` 不追求完整，只保留主 Agent 接手时最需要知道的关键点。
+
+### 4.2 ThreadProgressEvent
+
+新增线程增量进展事件模型。
+
+建议字段：
+
+- `eventId`
+- `projectId`
+- `threadId`
+- `threadDisplayName`
+- `deviceId`
+- `eventType`
+  - `phase_changed`
+  - `progress_updated`
+  - `blocker_added`
+  - `blocker_resolved`
+  - `next_step_changed`
+  - `architecture_updated`
+  - `handoff_ready`
+- `summary`
+- `phase`
+- `blockerDelta`
+- `nextStepDelta`
+- `createdAt`
+- `sourceTaskId`
+- `sourceMessageId`
+
+说明：
+
+- 这层的目标不是完整审计，而是为主 Agent 提供低 token 的“最近变化摘要”。
+- 事件数量需要限流和裁剪，例如每线程只保留最近 20 条。
+
+### 4.3 与现有模型的关系
+
+当前已有：
+
+- `ProjectUnderstandingSnapshot`
+- `MasterAgentMemory`
+- `threadContextSnapshots`
+
+本次关系建议：
+
+- `ProjectUnderstandingSnapshot` 继续保留，用于兼容现有项目级理解视图。
+- `ThreadStatusDocument` 成为线程级主结构化状态。
+- 项目级 `projectUnderstanding` 继续作为“项目展示层聚合结果”，但底层来源应逐步转向线程状态文档。
+- `MasterAgentMemory` 继续负责长期记忆，不负责替代线程当前状态。
+- `threadContextSnapshots` 继续负责上下文预算和风险状态，不负责承载项目理解正文。
+
+## 5. 同步策略
+
+### 5.1 全量理解刷新
+
+触发场景：
+
+1. 新设备导入后的首次理解
+2. 已导入设备中，主 Agent 第一次接触某个线程
+3. 用户明确要求主 Agent 接手当前项目
+4. 检测到线程进入明显新阶段
+5. 距离上一次全量理解已经超过阈值
+
+行为：
+
+- 向目标线程发起一次结构化“线程状态理解”任务
+- 更新整份 `ThreadStatusDocument`
+- 必要时同步更新 `ProjectUnderstandingSnapshot`
+- 对主 Agent 会话补一条轻量进展提醒
+
+### 5.2 轻量增量同步
+
+触发场景：
+
+1. heartbeat 检测到线程最近活跃
+2. 线程刚回写了新执行结果
+3. 但当前还没有进入需要完整深拉的关键阶段
+
+行为：
+
+- 不重做完整线程理解
+- 只抽取一条轻量 `ThreadProgressEvent`
+- 必要时更新 `ThreadStatusDocument` 中的少数字段：
+  - `currentProgress`
+  - `currentBlockers`
+  - `recommendedNextStep`
+  - `updatedAt`
+
+### 5.3 关键时刻深拉
+
+触发场景：
+
+1. 主 Agent 要真正接手当前项目
+2. 主 Agent 要发起线程调度或群聊协作
+3. 主 Agent 要给出指导性的下一步开发建议
+4. 当前线程状态文档和最近事件不足以支撑判断
+
+行为：
+
+- 向线程发起一次完整深拉
+- 允许在这个关键时刻多花 token
+- 更新线程状态文档并刷新主 Agent 的接手上下文
+
+## 6. Prompt 组装策略
+
+主 Agent 以后默认不再反复扫线程完整聊天历史。
+
+新的理解顺序为：
+
+1. 用户当前消息
+2. 线程状态文档
+3. 最近 3 到 5 条线程进展事件
+4. 项目级长期记忆
+5. 当前线程上下文预算和风险信息
+6. 必要时才深拉线程
+
+这样做的收益：
+
+- token 成本更稳定
+- 主 Agent 理解更连续
+- 接手时不需要每次从零重新扫历史
+
+## 7. 主 Agent 与线程的交互变化
+
+### 7.1 线程状态理解 Prompt
+
+全量理解时，线程不再返回泛化的“项目理解 JSON”，而是更明确地返回线程状态文档字段。
+
+要求：
+
+- 只返回结构化 JSON
+- 不返回无意义内部字段
+- 不重复线程 ID、目录路径、设备 ID
+- 只保留主 Agent 接手真正需要的事实
+
+### 7.2 轻量事件 Prompt
+
+增量同步时，线程不需要重写整份文档，只需返回：
+
+- 是否进入新阶段
+- 最近完成了什么
+- 是否出现新阻塞
+- 下一步是否变化
+
+这类 prompt 需要尽量短，并显式禁止输出冗长总结。
+
+## 8. 前台体验
+
+### 8.1 主 Agent 会话
+
+继续保留轻提醒，但来源改成“线程状态文档 + 最近进展事件”。
+
+可见文案示例：
+
+- `已同步线程状态：...`
+- `最新进展：...`
+- `建议下一步：...`
+- `主 Agent 可接手：...`
+
+### 8.2 线程详情 / 会话信息
+
+新增一个只读入口：`线程状态`
+
+展示内容：
+
+- 当前目标
+- 当前阶段
+- 当前进度
+- 技术架构
+- 当前阻塞
+- 建议下一步
+- 关键文件
+- 关键命令
+- 最近更新时间
+
+默认不可编辑。
+
+### 8.3 已导入设备与新导入设备
+
+两者统一走同一套机制：
+
+- 新导入设备：首次理解
+- 已导入设备：活跃线程持续增量同步
+- 主 Agent 最终都读取同一套线程状态文档和最近进展事件
+
+## 9. 约束与风险
+
+### 9.1 不能把线程状态文档写进项目仓库
+
+原因：
+
+- 污染工作区
+- 容易制造脏 diff
+- 容易被误提交
+- 多线程并行修改时易冲突
+
+所以文档必须由 Boss 自己维护，并保存在 Boss 状态层。
+
+### 9.2 不能完全放弃深拉
+
+如果完全变成“只查文档”，主 Agent 会因为文档滞后而接手失败。
+
+所以深拉仍然保留，但只在关键时刻触发。
+
+### 9.3 增量事件必须限流
+
+如果线程每次活动都写大段事件，最终只是把 token 压力从“全量理解”转移成“事件堆积”。
+
+因此：
+
+- 每线程只保留最近有限数量事件
+- 重复事件应合并
+- 明显无价值事件不写入
+
+## 10. 分期实现建议
+
+### 第一批
+
+1. 新增 `ThreadStatusDocument`
+2. 新增 `ThreadProgressEvent`
+3. 新增线程状态文档的全量刷新任务
+4. 主 Agent prompt 默认改为读取“线程状态文档 + 最近事件”
+
+### 第二批
+
+1. 新增轻量事件同步任务
+2. 为 heartbeat / thread reply 增加“轻量事件优先、全量理解兜底”的策略
+3. 主 Agent 会话补更稳定的轻提醒
+
+### 第三批
+
+1. 在线程详情或会话信息增加 `线程状态`
+2. 对主 Agent 接手场景补更明确的接手卡片
+3. 对阶段切换、阻塞变化做更强的事件归并
+
+## 11. 验收标准
+
+1. 主 Agent 平时不再因为线程每次活动都重跑完整项目理解。
+2. 活跃线程继续推进时，主 Agent 仍能在较短时间内获得最新进展。
+3. 当用户明确要求主 Agent 接手项目时，主 Agent 能依赖线程状态文档与最近事件快速进入正确上下文。
+4. 不会向线程项目工作区写入状态文档文件。
+5. APP 中能查看线程状态，但默认不可编辑。
+