163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# 聊天主链补完设计
|
||
|
||
## 背景
|
||
|
||
当前 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：发送后不会只停在“消息已发送”，而是能收束成真实回复 / 推荐确认 / 失败提示
|
||
|