# 主 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 中能查看线程状态，但默认不可编辑。