feat: complete chat routing and openai onboarding

2026-03-31 03:31:22 +08:00
parent 5b590f7cc1
commit 9c02ebb574
25 changed files with 2241 additions and 133 deletions
--- a/docs/superpowers/plans/2026-03-31-chat-path-completion.md
+++ b/docs/superpowers/plans/2026-03-31-chat-path-completion.md
@@ -0,0 +1,66 @@
+# 聊天主链补完 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 打通主 Agent 单聊、普通线程单聊和群聊推荐执行三条聊天链，并让 Android 端能稳定展示等待、确认、失败和结果回流。
+
+**Architecture:** 后端继续沿用 `boss-state.json + master-agent task queue + local-agent` 路线，把普通线程单聊纳入 `conversation_reply` 任务执行链；群聊继续沿用 `dispatch_execution`。Android 端用轮询项目详情和待确认计划来收束聊天状态，而不是一次发送后只做单次刷新。
+
+**Tech Stack:** Next.js App Router, TypeScript, file-backed state store, local-agent, Android AppCompat/Java, node:test, Gradle unit tests
+
+---
+
+### Task 1: 后端补普通线程单聊执行链
+
+**Files:**
+- Modify: `/Users/kris/code/boss/src/app/api/v1/projects/[projectId]/messages/route.ts`
+- Modify: `/Users/kris/code/boss/src/lib/boss-data.ts`
+- Modify: `/Users/kris/code/boss/local-agent/server.mjs`
+- Test: `/Users/kris/code/boss/tests/single-thread-message-execution.test.ts`
+
+- [ ] 写失败测试，覆盖“普通线程单聊发送后会排 `conversation_reply` 任务”
+- [ ] 跑测试确认当前失败
+- [ ] 在消息路由和状态模型里补任务创建
+- [ ] 在 `local-agent` 完成回写时把线程原始回复写回单线程项目
+- [ ] 再跑测试确认通过
+
+### Task 2: 后端补主 Agent/普通线程统一任务状态语义
+
+**Files:**
+- Modify: `/Users/kris/code/boss/src/app/api/v1/projects/[projectId]/messages/route.ts`
+- Modify: `/Users/kris/code/boss/src/lib/boss-master-agent.ts`
+- Test: `/Users/kris/code/boss/tests/project-message-task-status.test.ts`
+
+- [ ] 写失败测试，覆盖发送返回 `taskId/taskType/status`
+- [ ] 跑测试确认失败
+- [ ] 在消息接口里把任务状态统一返回给客户端
+- [ ] 主 Agent 单聊保持现有执行逻辑，但返回值补清晰任务状态
+- [ ] 再跑测试确认通过
+
+### Task 3: Android 补发送后等待/轮询/收束链
+
+**Files:**
+- Modify: `/Users/kris/code/boss/android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
+- Modify: `/Users/kris/code/boss/android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
+- Test: `/Users/kris/code/boss/android/app/src/test/java/com/hyzq/boss/ProjectDetailActivityChatFlowTest.java`
+
+- [ ] 写失败测试，覆盖主 Agent / 普通线程 / 群聊三种发送后的状态流
+- [ ] 跑测试确认失败
+- [ ] 在 `ProjectDetailActivity` 增加轮询与等待态收束
+- [ ] 群聊确认后继续轮询直到看到线程结果或主 Agent 汇总
+- [ ] 再跑测试确认通过
+
+### Task 4: 文档、验证、部署
+
+**Files:**
+- Modify: `/Users/kris/code/boss/README.md`
+- Modify: `/Users/kris/code/boss/docs/architecture/current_runtime_and_deploy_status_cn.md`
+- Modify: `/Users/kris/code/boss/docs/architecture/api_and_service_inventory_cn.md`
+
+- [ ] 运行 `npm run lint`
+- [ ] 运行 `npm run build`
+- [ ] 运行新增 node:test 与 Android 单测
+- [ ] 验证 `curl -sS http://127.0.0.1:3000/api/health`
+- [ ] 验证 `curl -sS http://127.0.0.1:4317/health`
+- [ ] 部署到服务器并验证 `curl -sS https://boss.hyzq.net/api/health`
+- [ ] 同步文档写明三条聊天链当前状态
--- a/docs/superpowers/specs/2026-03-31-chat-path-completion-design.md
+++ b/docs/superpowers/specs/2026-03-31-chat-path-completion-design.md
@@ -0,0 +1,162 @@
+# 聊天主链补完设计
+
+## 背景
+
+当前 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：发送后不会只停在“消息已发送”，而是能收束成真实回复 / 推荐确认 / 失败提示
+