krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/master-agent-autonomous-evolution
boss/docs/superpowers/specs/2026-04-04-master-agent-thread-status-sync-design.md
kris f180a5e4a8 docs: add thread status sync design
2026-04-04 10:43:39 +08:00

9.8 KiB
Raw Permalink Blame History

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