# 主 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 发送后不会表现成“卡死在发送动作里”，而是立即出现等待态