krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8a62e72fd52d10e77d21d2b0059dda419fc03f42
boss/docs/superpowers/specs/2026-03-31-chat-path-completion-design.md

4.8 KiB
Raw Blame History

聊天主链补完设计

背景

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

  • 主 Agent 会话、普通线程会话、群聊会话
  • master-agent task queue -> local-agent -> codex exec -> complete 的基础执行链
  • 群聊消息 -> 主 Agent 推荐下发 -> 用户确认 -> dispatch_execution -> 原始结果回群 的第一轮闭环
  • 设备导入、线程归档、原生 Android 聊天页和会话页

但“聊天通路”还没有真正打通，主要断点有三处：

  1. 主 Agent 单聊
    • 后端能接单并排队任务
    • Android 端没有等待态和轮询回收，用户会感知成“发了消息没反应”
  2. 普通项目线程单聊
    • 当前只把用户消息写进账本
    • 没有创建真正的线程执行任务，也没有线程结果回写
  3. 群聊调度
    • 后端主链基本具备
    • Android 端仍缺“推荐计划待确认 / 执行中 / 回写后收束”的稳定体验

目标

  1. 主 Agent 单聊在 APP 和 Web 中都能形成真实回复，不再只有消息入账
  2. 普通线程单聊也能进入 local-agent -> codex exec -> complete 执行链
  3. 群聊保持“主 Agent 推荐 -> 用户确认 -> 线程原始结果回群 -> 主 Agent 汇总”的现有结构，并补稳前台状态
  4. Android 聊天页发送后要有清晰的等待、超时、失败和完成回显
  5. 不改当前产品路线，不引入数据库或额外消息中间件

非目标

  • 本轮不重做 UI 视觉
  • 本轮不改变设备导入或附件存储路线
  • 本轮不实现 ChatGPT OAuth
  • 本轮不做新的原生真机视觉细抠

设计

1. 统一三条聊天链的后端执行模型

服务端把聊天请求统一收敛成两类：

  • conversation_reply
    • 用于主 Agent 单聊和普通线程单聊
  • dispatch_execution
    • 用于群聊推荐下发后，针对具体线程的执行单

1.1 主 Agent 单聊

  • POST /api/v1/projects/master-agent/messages
  • 继续调用 replyToMasterAgentUserMessage()
  • 仍然允许两种执行后端：
    • master_codex_node
    • openai_api
  • 返回值继续允许“立即有内容”或“任务已排队”
  • 但会明确返回 taskStatus，供 Android 端轮询

1.2 普通线程单聊

  • POST /api/v1/projects/[threadProjectId]/messages
  • 如果目标项目：
    • 不是 master-agent
    • 不是群聊
    • 且有完整 threadMeta
  • 则服务端在写入用户消息后，创建一个新的 conversation_reply 任务
  • 任务必须挂上：
    • projectId
    • targetProjectId
    • targetThreadId
    • deviceId
    • codexFolderRef
    • codexThreadRef
    • requestMessageId
  • local-agent 认领后，通过当前电脑已登录的 codex 会话执行，并把线程原始回复回写到这个单线程项目中

2. 单线程会话回写规则

普通线程单聊完成后：

  • 线程原始结果直接作为一条 device 或 thread 消息回到当前单线程项目
  • 不再额外套一个主 Agent 汇总层
  • 这样单线程会话保持“我和这个线程直接聊天”的心智

如果执行失败：

  • 在当前会话插入一条失败系统消息
  • 保留用户消息，不吞掉失败状态

3. 群聊保持现有编排结构，但补稳状态语义

群聊继续使用：

  • 用户消息入账
  • 主 Agent 推荐计划 dispatchPlan
  • 用户确认
  • dispatch_execution
  • 线程原始结果回群
  • 主 Agent 汇总

本轮只补强两个方面：

  • 前台能稳定恢复“当前还有待确认推荐”
  • 执行中、失败、完成三种状态都能回到聊天页

4. Android 聊天页状态机

发送消息后不再只做“一次 reload”。

新增最小状态：

  • pending_task
  • pending_dispatch_plan
  • awaiting_result
  • failed

4.1 主 Agent / 普通线程单聊

如果发送接口返回：

  • 已经带回真实回复
    • 直接刷新并结束等待态
  • 只返回 taskId
    • Android 进入轮询
    • 轮询项目详情或任务状态，直到看到新回复 / 失败 / 超时

4.2 群聊

如果返回 dispatchPlan

  • 立即显示“等待你确认主 Agent 推荐”
  • 确认后显示“已下发，等待线程返回”
  • 后续靠轮询项目详情把原始回复和主 Agent 汇总拉回来

5. API 返回语义补充

聊天发送接口要统一补足这些字段：

  • masterReply
  • dispatchPlan
  • task
    • taskId
    • taskType
    • status
  • collaborationGate

即使没有立即回复，也要让客户端知道：

  • 是已经排队了
  • 还是需要确认
  • 还是确实失败了

6. 测试与验收

必须覆盖：

  1. 主 Agent 单聊：消息发送后产生真实回复或明确排队状态
  2. 普通线程单聊：消息发送后创建线程执行任务，并把线程回复写回项目
  3. 群聊：推荐计划、确认、结果回流保持可用
  4. Android：发送后不会只停在“消息已发送”，而是能收束成真实回复 / 推荐确认 / 失败提示