# 聊天主链补完设计

## 背景

当前 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：发送后不会只停在“消息已发送”，而是能收束成真实回复 / 推荐确认 / 失败提示