From e9ae37028ec3b9a3cf6f25f931f75291fd93831e Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Tue, 31 Mar 2026 17:26:34 +0800
Subject: [PATCH] docs: add master-agent chat controls spec

---
 ...03-31-master-agent-chat-controls-design.md | 183 ++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-03-31-master-agent-chat-controls-design.md

diff --git a/docs/superpowers/specs/2026-03-31-master-agent-chat-controls-design.md b/docs/superpowers/specs/2026-03-31-master-agent-chat-controls-design.md
new file mode 100644
index 0000000..5db00bd
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-31-master-agent-chat-controls-design.md
@@ -0,0 +1,183 @@
+# 主 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 发送后不会表现成“卡死在发送动作里”，而是立即出现等待态
+