docs: add master-agent chat controls spec
This commit is contained in:
kris
@@ -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 发送后不会表现成“卡死在发送动作里”，而是立即出现等待态
|
||||
|
||||
Reference in New Issue
Block a user