boss/docs/superpowers/specs/2026-03-31-master-agent-chat-controls-design.md

主 Agent 对话控制与异步回复设计

背景

当前 master-agent 会话已经具备真实回复链：

• APP / Web -> boss-web -> master-agent -> local-agent / OpenAI API -> 回写账本

但用户体验仍有两个核心问题：

1. 发送给主 Agent 后，前台会同步等待较长时间，体感像“卡住”
2. 主 Agent 单聊缺少像 Codex 那样的“当前对话模型选择 / 推理强度选择”

同时，当前聊天页右上角仍偏向产品内置动作，不是微信式的统一三点菜单入口。

目标

1. 主 Agent 单聊发送后立即给出前台反馈，不再长时间阻塞输入和页面状态
2. 为 master-agent 当前对话提供“模型选择”和“推理强度”设置
3. 右上角改成微信式 ... 入口，把高级控制放进菜单
4. 设置按“当前对话”保存，不影响其它会话
5. 保持当前 Master Codex Node / OpenAI API 双主控路线，不重做整个 AI 账号系统

非目标

• 本轮不重做群聊分发链
• 本轮不把模型/推理强度扩展到普通线程会话或群聊
• 本轮不实现真正的 token 级流式输出
• 本轮不实现纯 OAuth 直接替代 OpenAI API Key

设计

1. 主 Agent 发送链改成“快速入队 + 异步回流”

当前 POST /api/v1/projects/master-agent/messages 的问题，不在于单次超时值太短，而在于它仍试图把“写入消息”和“拿到完整回复”塞进一次前台同步等待里。

本轮改成两段式：

1.1 发送阶段

• 前端发送后，用户消息立刻写入会话
• 服务端立即返回：
  • message
  • task
  • masterReplyState = queued | running | failed
• 如果后端已经在极短时间内拿到真实回复，仍然允许顺带返回
• 但前端不再依赖“同步等完整回复”作为主路径

1.2 回流阶段

• 主 Agent 后端继续正常跑当前执行链
• 回复完成后把正式消息写回账本
• Android / Web 前台靠已有刷新与轮询机制补回正式回复

1.3 前台状态

主 Agent 单聊新增最小等待状态：

• queued
• running
• failed

用户点击发送后：

• 自己的消息立即显示
• 消息流里立即出现一条轻量状态：
  • 主 Agent 思考中
• 如果失败，则变成明确失败提示，并提供轻量 重试

2. 当前对话模型与推理强度

本轮只对 master-agent 会话提供对话级控制。

2.1 保存粒度

设置按“当前对话”保存，而不是全局保存：

• modelOverride
• reasoningEffortOverride

规则：

• 未设置时，沿用当前主控账号默认模型和默认推理强度
• 设置后，只覆盖 master-agent 当前对话

2.2 可选项

模型：

• 初始先支持当前系统已知模型值
• 默认仍为账号已有的默认模型，例如 gpt-5.4

推理强度：

• low
• medium
• high

默认值：

• 沿用当前主控账号默认推理强度
• 若账号层无默认值，则使用 medium

3. 右上角微信式三点菜单

主 Agent 聊天页右上角改成微信式 ...。

菜单项本轮固定为：

1. 模型
2. 推理强度
3. 会话信息
4. 刷新

说明：

• 模型 和 推理强度 使用单选弹层
• 会话信息 继续复用现有会话信息页
• 刷新 从常驻按钮降级成菜单项

这样主聊天面会更接近微信：

• 顶部只保留一个轻量入口
• 高级控制不再直接占据标题栏

4. 服务端状态模型

为 master-agent 会话补一层可选配置：

• modelOverride?: string
• reasoningEffortOverride?: "low" | "medium" | "high"

这些值应存进当前文件型状态模型，并通过项目详情接口返回给前台。

主 Agent 真实调用时，优先级改为：

1. 当前对话 override
2. 当前主控账号默认设置
3. 系统默认值

5. 与当前主控体系的关系

本轮不改变现有主控优先级机制：

• 用户可在 我的 > AI 账号 选择当前主控
• 当前主控可以是：
  • Master Codex Node
  • OpenAI API

主 Agent 调用模型时，只是在当前主控已确定的前提下，再读取“当前对话的模型/推理强度覆盖”。

也就是说：

• 主控决定“走哪条执行路线”
• 对话设置决定“在这条路线里用什么模型、什么推理强度”

6. Android / Web 前台行为

6.1 Android

• 聊天页发送后立即插入本地发送态
• 若接口返回 task queued/running，则显示“主 Agent 思考中”
• 定时刷新项目详情，直到看到新回复或失败
• 顶部右上角改成微信式 ...
• 弹层中提供 模型 / 推理强度 / 会话信息 / 刷新

6.2 Web

• Web 保持同一套后端语义
• 即使先不做完整菜单 UI，也要能读取并应用同一套对话级设置
• Web 主 Agent 会话也不能继续依赖同步长等待作为唯一体验

7. 测试与验收

必须覆盖：

1. 主 Agent 单聊发送后，接口能立即返回 queued/running，而不是强依赖完整回复
2. 主 Agent 回复完成后，正式消息会回到会话账本
3. 当前对话可保存 modelOverride / reasoningEffortOverride
4. 主 Agent 实际调用时会优先使用当前对话覆盖值
5. Android 右上角 ... 菜单能正确展示并修改这两项设置
6. Android 发送后不会表现成“卡死在发送动作里”，而是立即出现等待态