boss/docs/superpowers/specs/2026-03-30-conversation-orchestration-and-device-import-design.md

会话编排、主 Agent 调度与设备项目导入设计

背景

当前 Boss 已经具备这些基础能力：

• 会话首页、单线程会话、独立群聊、主 Agent 会话、审计对话
• master-agent task queue -> local-agent -> codex exec -> complete 的主 Agent 基础执行链
• 设备接入草稿、pairing code / token claim、设备心跳与线程上下文上报
• 线程 = 聊天窗口、文件夹名副标题、会话改名、微信式转发与附件发送

但这些能力现在仍然是半截主链：

• 群聊已能建，但群聊内用户消息还没有正式进入“主 Agent 先理解、再推荐下发”的编排链
• 非开发任务下的审批逻辑还停留在部分字段和转发闸口，没有扩展到完整消息发送链
• 新设备接入时仍然是“手填项目列表”，还没有“设备扫描候选项目 -> 用户勾选 -> 主 Agent 理解 -> 映射成聊天窗口”的导入主链
• 当前 UI 上露出的功能已不少，但逻辑层和状态机没有系统性收口

本轮目标是先补完两条最关键的业务主链：

1. 会话/群聊/主 Agent 编排链
2. 添加设备 -> 项目勾选 -> Agent 理解导入 -> 会话落地链

同时把当前真实进度写回开发文档，供后续继续扩展时使用。

目标

1. 群聊消息默认先进入主 Agent，由主 Agent 给出推荐执行线程，用户确认后再下发
2. 线程执行结果既要回群显示原始结果，也要有主 Agent 汇总
3. 明确 development 与 approval_required 两种协作模式，并贯穿群聊消息与线程间沟通
4. 添加设备流程升级为“真实候选项目勾选 + Agent 理解导入”，不再依赖纯字符串项目列表
5. 把当前进度和本轮新增的主链写回开发文档，避免后续线程误判系统状态

非目标

• 本轮不做真机联调
• 本轮不重做原生 UI 外观
• 本轮不引入数据库或新的消息中间件
• 本轮不细抠主 Agent 的高级决策策略，只先把结构和状态机打通

设计概览

1. 群聊编排主链

群聊不再被视为线程自由讨论区，而是主 Agent 主持的受控协作会话。

1.1 用户发言入口

• 用户在群聊内发送消息
• 这条消息先作为用户消息写入当前群聊账本
• 系统立刻生成一条 orchestration pending 状态，让前端知道这条消息正在等待主 Agent 理解

1.2 主 Agent 理解与推荐

• 主 Agent 收到群聊用户消息后，不立即向线程广播
• 它会结合：
  • 群成员线程
  • 设备在线状态
  • 线程文件夹和线程名
  • 线程最近活跃度 / 上下文预算
  • 群聊协作模式
• 产出一个推荐执行方案，包括：
  • 推荐下发到哪些线程
  • 推荐原因
  • 是否需要用户审批
  • 如果要拆多步执行，推荐顺序是什么

1.3 用户确认后下发

• 默认策略不是自动下发，而是“主 Agent 推荐 -> 用户确认”
• 用户确认后，系统创建真正的线程级执行任务
• 每个执行任务都要绑定：
  • projectId
  • groupProjectId
  • deviceId
  • threadId
  • codexFolderRef
  • codexThreadRef
  • requestedBy
  • dispatchPlanId

2. 结果回流主链

线程执行完后，结果需要双通道回流：

2.1 线程原始结果

• 线程原始执行结果直接写回群聊
• 前端需要能看到“是哪一个线程/设备返回的”
• 这样群聊保持透明，不是只有主 Agent 的二次转述

2.2 主 Agent 汇总

• 线程原始结果回流后，主 Agent 再补一条汇总
• 汇总用于：
  • 提炼结论
  • 说明下一步
  • 标记是否还需要用户确认

3. 开发任务与非开发任务模式

项目/群聊协作模式统一只有两种：

• development
• approval_required

3.1 development

• 允许线程在群内协作
• 主 Agent 主要负责调度、监督和汇总
• 线程之间的上下游回复可以直接继续

3.2 approval_required

• 线程之间不能默认自由对话
• 主 Agent 如果判断两个线程必须沟通，要先创建审批请求
• 用户批准后，系统才创建临时的跨线程协作窗口或任务

这条规则需要覆盖：

• 群聊消息编排
• 线程间消息转发
• 线程直接对话
• 设备导入后的自动映射建议

4. 添加设备与项目导入主链

4.1 创建设备草稿

用户先创建一个设备接入草稿，只录入基础信息：

• 设备名称
• 头像
• 所属账号
• endpoint
• 备注

这一步不再要求用户手填最终项目字符串来定义真实会话。

4.2 设备首次心跳后上报候选项目

设备 claim 成功或首次心跳后，要让系统看到这台设备真实可见的候选项目：

• Codex 文件夹
• 每个文件夹下的线程
• 线程显示名
• 最近活跃时间
• 是否建议导入

4.3 用户勾选导入候选

用户在设备接入流程里勾选：

• 要导入哪些文件夹/线程
• 哪些先不导入
• 同文件夹下哪些线程要显示成独立聊天窗口

这里的准则继续保持：

• 一个线程 = 一个聊天窗口
• 同文件夹多个线程 = 多个会话项
• 会话标题显示线程名，副标题显示文件夹名

4.4 主 Agent 理解导入建议

用户勾选后，先不直接生成最终会话，而是交给主 Agent 做一次导入理解：

• 判断这些线程应关联到哪些现有会话
• 哪些线程应新建单线程会话
• 哪些线程应该进入已有群聊
• 哪些条目只是临时线程，不适合露出到首页
• 是否存在命名冲突或重复导入

4.5 导入落地

主 Agent 输出导入建议后，系统再真正写入：

• 新单线程会话
• 现有会话的新增线程成员
• 建议创建的群聊草稿
• 未导入项和原因

5. 状态模型补充

本轮需要引入或扩展的最小状态对象：

• dispatchPlan
  • 对应主 Agent 一次推荐下发结果
• dispatchExecution
  • 对应某个被确认的线程执行任务
• deviceImportDraft
  • 对应设备上报的候选项目和用户勾选状态
• deviceImportResolution
  • 对应主 Agent 对导入草稿的理解结果

这些状态仍然保存在当前 data/boss-state.json，不引入额外基础设施。

API 与行为边界

会话/群聊编排

需要补齐或扩展的接口方向：

• 群聊消息发送后触发编排建议
• 获取某条群聊消息的 dispatch plan
• 用户确认 dispatch plan
• 查询 dispatch execution 结果

设备导入

需要补齐或扩展的接口方向：

• 设备候选项目上报
• 获取设备导入草稿
• 提交勾选结果
• 触发主 Agent 理解
• 获取导入决议
• 应用导入决议

文档要求

本轮开发必须同步更新至少这些文档：

• docs/architecture/development_subtasks_and_delivery_plan_cn.md
• docs/architecture/current_runtime_and_deploy_status_cn.md
• docs/architecture/api_and_service_inventory_cn.md
• 如有新的主链说明，再补 docs/architecture/ai_handoff_index_cn.md

验收标准

1. 群聊消息不再直接裸发给线程，而是先进入主 Agent 推荐下发链
2. 用户可以确认主 Agent 推荐的下发对象，再正式发到具体线程
3. 线程结果能直接回群，主 Agent 也会补汇总
4. development 与 approval_required 模式在主消息链里真正生效，不再只是字段占位
5. 添加设备后能拿到候选项目列表，用户可勾选，再由主 Agent 理解导入
6. 导入后的线程能映射成真实聊天窗口，而不是只写进设备项目字符串
7. 文档同步到位，后续线程可直接接手

风险与控制

• 风险：主 Agent 推荐和用户确认之间的状态不稳定
  • 控制：引入显式 dispatchPlan 和 dispatchExecution
• 风险：设备候选项目直接裸暴露成会话，导致首页污染
  • 控制：必须经过主 Agent 理解导入，再落最终会话
• 风险：审批逻辑只接了一半，导致 development / approval_required 语义继续漂
  • 控制：把协作模式接入群聊消息链，不只接转发链