From 949dcf78451330bead760101075984d3e0515191 Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Mon, 30 Mar 2026 01:09:05 +0800
Subject: [PATCH] docs: plan orchestration and device import

---
 ...velopment_subtasks_and_delivery_plan_cn.md |  35 ++
 ...rsation-orchestration-and-device-import.md | 329 ++++++++++++++++++
 ...-orchestration-and-device-import-design.md | 246 +++++++++++++
 3 files changed, 610 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-03-30-conversation-orchestration-and-device-import.md
 create mode 100644 docs/superpowers/specs/2026-03-30-conversation-orchestration-and-device-import-design.md

diff --git a/docs/architecture/development_subtasks_and_delivery_plan_cn.md b/docs/architecture/development_subtasks_and_delivery_plan_cn.md
index a9ffae7..4ae5e07 100644
--- a/docs/architecture/development_subtasks_and_delivery_plan_cn.md
+++ b/docs/architecture/development_subtasks_and_delivery_plan_cn.md
@@ -2,6 +2,41 @@
 
 这份文档的目标不是重复架构，而是把“余下的设计工作”彻底拆成可以直接进入开发的子任务。
 
+---
+
+## 当前阶段进度（2026-03-30）
+
+当前仓库已经不再停留在“纯设计待开发”，而是完成了第一轮可运行闭环：
+
+- Web 控制面、主 Agent 任务队列、local-agent、原生 Android、部署链路均已跑通
+- 原生 Android 已完成微信式首页回退、线程=会话窗口、独立群聊、会话改名、消息转发、附件发送与 OTA 下载主链
+- 主 Agent 已具备 `task queue -> local-agent -> codex exec -> complete` 的基础执行链
+- 设备接入已具备草稿、pairing code/token、claim 与首次心跳的最小链路
+
+当前真正还缺的是“业务主链补完”，尤其是下面两段：
+
+1. `会话/群聊/主 Agent 调度主链`
+   - 群聊消息先进入主 Agent
+   - 主 Agent 推荐下发目标线程
+   - 用户确认后再正式下发
+   - 线程原始结果回群 + 主 Agent 汇总
+   - `development / approval_required` 协作模式接入正式消息链
+
+2. `添加设备 -> 项目候选 -> Agent 理解 -> 会话导入主链`
+   - 不再只靠手填项目字符串
+   - 设备首次接入后上报真实候选文件夹/线程
+   - 用户勾选导入
+   - 主 Agent 理解后映射成正式聊天窗口
+
+当前建议把“余下开发”拆成 4 个工作包推进：
+
+- `WP1. 当前进度与交接文档收口`
+- `WP2. 会话/群聊/主 Agent 编排与审批主链`
+- `WP3. 设备项目候选、勾选导入与 Agent 理解映射`
+- `WP4. 按现有 UI 全量功能做逻辑审计与补洞`
+
+本轮开发默认先做 `WP1 + WP2`，随后再进入 `WP3 + WP4`。
+
 适用范围：
 
 - 单主 Agent
diff --git a/docs/superpowers/plans/2026-03-30-conversation-orchestration-and-device-import.md b/docs/superpowers/plans/2026-03-30-conversation-orchestration-and-device-import.md
new file mode 100644
index 0000000..35ec5b4
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-30-conversation-orchestration-and-device-import.md
@@ -0,0 +1,329 @@
+# 会话编排、主 Agent 调度与设备项目导入 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:** 先补齐 `WP1 + WP2`：把当前真实进度写回开发文档，并打通“群聊消息 -> 主 Agent 推荐 -> 用户确认 -> 线程执行 -> 原始结果回群 + 主 Agent 汇总”的主链。
+
+**Architecture:** 继续沿用当前 `boss-state.json + Next.js API + local-agent + master-agent task queue` 路线，不引入新基础设施。先补文档和状态模型，再扩展群聊消息接口、主 Agent 任务类型和执行回流，最后补验证与文档同步。
+
+**Tech Stack:** Next.js App Router, TypeScript, file-backed state store, local-agent, Android/Next API clients, JUnit/Gradle where needed, curl verification
+
+---
+
+### Task 1: 把当前真实进度和下一阶段工作包写回开发文档
+
+**Files:**
+- Modify: `docs/architecture/development_subtasks_and_delivery_plan_cn.md`
+- Modify: `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- Modify: `docs/architecture/ai_handoff_index_cn.md`
+
+- [ ] **Step 1: 在开发计划文档补“当前阶段进度”和 `WP1-WP4`**
+
+```md
+## 当前阶段进度（2026-03-30）
+
+- Web、主 Agent、local-agent、原生 Android、部署链路已跑通
+- 当前缺口集中在：
+  - 会话/群聊/主 Agent 编排主链
+  - 设备候选项目 -> Agent 理解导入主链
+```
+
+- [ ] **Step 2: 在运行状态文档登记“下一条逻辑主链目标”**
+
+```md
+- 下一阶段主目标：把群聊消息默认接到主 Agent，由主 Agent 推荐下发线程，用户确认后再正式执行
+- 下一阶段设备接入目标：从手填项目列表升级为真实候选项目勾选与 Agent 理解导入
+```
+
+- [ ] **Step 3: 在 AI 交接入口补上“当前先做 WP1 + WP2”**
+
+```md
+- 当前优先工作包：WP1 文档收口、WP2 会话/群聊/主 Agent 编排主链
+```
+
+- [ ] **Step 4: 提交文档阶段基线**
+
+```bash
+cd /Users/kris/code/boss
+git add docs/architecture/development_subtasks_and_delivery_plan_cn.md docs/architecture/current_runtime_and_deploy_status_cn.md docs/architecture/ai_handoff_index_cn.md
+git commit -m "docs: record orchestration and import work packages"
+```
+
+### Task 2: 扩展状态模型，加入 dispatch plan / execution 最小结构
+
+**Files:**
+- Modify: `src/lib/boss-data.ts`
+- Test: `src/lib/boss-data.ts` existing test seams via targeted script or route verification
+
+- [ ] **Step 1: 在状态模型里新增主 Agent 编排计划和执行记录**
+
+```ts
+export interface DispatchPlanTarget {
+  deviceId: string;
+  projectId: string;
+  threadId: string;
+  threadDisplayName: string;
+  folderName: string;
+  codexFolderRef?: string;
+  codexThreadRef?: string;
+  reason: string;
+}
+
+export interface DispatchPlan {
+  planId: string;
+  groupProjectId: string;
+  requestMessageId: string;
+  requestedBy: string;
+  status: "pending_user_confirmation" | "approved" | "rejected" | "dispatched";
+  targets: DispatchPlanTarget[];
+  summary: string;
+  createdAt: string;
+  confirmedAt?: string;
+}
+
+export interface DispatchExecution {
+  executionId: string;
+  planId: string;
+  groupProjectId: string;
+  targetProjectId: string;
+  targetThreadId: string;
+  deviceId: string;
+  status: "queued" | "running" | "completed" | "failed";
+  createdAt: string;
+  completedAt?: string;
+  resultMessageId?: string;
+}
+```
+
+- [ ] **Step 2: 把这两个字段挂进 `BossState` 和默认 state**
+
+```ts
+dispatchPlans: DispatchPlan[];
+dispatchExecutions: DispatchExecution[];
+```
+
+- [ ] **Step 3: 实现最小 CRUD helper**
+
+```ts
+export async function createDispatchPlan(...) {}
+export async function listDispatchPlansByProject(groupProjectId: string) {}
+export async function confirmDispatchPlan(...) {}
+export async function createDispatchExecutionsFromPlan(...) {}
+export async function completeDispatchExecution(...) {}
+```
+
+- [ ] **Step 4: 提交状态模型扩展**
+
+```bash
+cd /Users/kris/code/boss
+git add src/lib/boss-data.ts
+git commit -m "feat: add orchestration dispatch state"
+```
+
+### Task 3: 打通群聊消息 -> 主 Agent 推荐 plan
+
+**Files:**
+- Modify: `src/app/api/v1/projects/[projectId]/messages/route.ts`
+- Modify: `src/lib/boss-master-agent.ts`
+- Modify: `src/lib/boss-data.ts`
+
+- [ ] **Step 1: 在群聊消息发送接口里识别“需要编排”的场景**
+
+```ts
+const shouldCreateDispatchPlan =
+  project?.isGroup &&
+  project.id !== "master-agent" &&
+  (body.kind ?? "text") === "text" &&
+  message.body.trim().length > 0;
+```
+
+- [ ] **Step 2: 为主 Agent 增加新的任务类型或复用现有 conversation reply 生成推荐 plan**
+
+```ts
+type MasterAgentTaskType =
+  | "conversation_reply"
+  | "attachment_analysis"
+  | "group_dispatch_plan";
+```
+
+- [ ] **Step 3: 当群聊用户消息到来时，创建 `DispatchPlan` 而不是直接下发线程**
+
+```ts
+const plan = await queueGroupDispatchPlan({
+  groupProjectId: projectId,
+  requestMessageId: message.id,
+  requestText: message.body,
+  requestedBy: session.account,
+});
+```
+
+- [ ] **Step 4: 接口返回编排状态给前端**
+
+```ts
+return NextResponse.json({
+  ok: true,
+  message,
+  dispatchPlan: plan ?? null,
+  collaborationGate,
+});
+```
+
+- [ ] **Step 5: 提交群聊编排入口**
+
+```bash
+cd /Users/kris/code/boss
+git add src/app/api/v1/projects/[projectId]/messages/route.ts src/lib/boss-master-agent.ts src/lib/boss-data.ts
+git commit -m "feat: create dispatch plans from group messages"
+```
+
+### Task 4: 增加用户确认 dispatch plan 和创建 execution 的接口
+
+**Files:**
+- Create: `src/app/api/v1/projects/[projectId]/dispatch-plans/route.ts`
+- Create: `src/app/api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm/route.ts`
+- Modify: `src/lib/boss-data.ts`
+
+- [ ] **Step 1: 增加查询群聊编排计划接口**
+
+```ts
+GET /api/v1/projects/[projectId]/dispatch-plans
+```
+
+- [ ] **Step 2: 增加用户确认推荐下发对象接口**
+
+```ts
+POST /api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm
+body: { approvedTargetProjectIds: string[] }
+```
+
+- [ ] **Step 3: 确认后创建 `DispatchExecution` 记录，并排队给 local-agent / codex 线程**
+
+```ts
+const executions = await createDispatchExecutionsFromPlan({
+  planId,
+  approvedTargetProjectIds,
+  confirmedBy: session.account,
+});
+```
+
+- [ ] **Step 4: 在群聊账本插入“已确认下发”系统消息**
+
+```ts
+sender: "master",
+senderLabel: "主 Agent",
+body: "已根据你的确认把任务下发到 2 个线程。"
+```
+
+- [ ] **Step 5: 提交 dispatch plan 确认链**
+
+```bash
+cd /Users/kris/code/boss
+git add src/app/api/v1/projects/[projectId]/dispatch-plans/route.ts src/app/api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm/route.ts src/lib/boss-data.ts
+git commit -m "feat: confirm dispatch plans and create executions"
+```
+
+### Task 5: 把执行结果回流到群聊，并补主 Agent 汇总
+
+**Files:**
+- Modify: `src/lib/boss-master-agent.ts`
+- Modify: `src/lib/boss-data.ts`
+- Modify: `local-agent/server.mjs`
+
+- [ ] **Step 1: 为 execution 增加“线程原始结果回群” helper**
+
+```ts
+export async function appendDispatchExecutionResult(...) {}
+```
+
+- [ ] **Step 2: local-agent 执行完成后，除了原来的任务 complete，还要带回 target project / thread result**
+
+```js
+await postJson(`/api/v1/master-agent/tasks/${taskId}/complete`, {
+  ...
+  dispatchExecutionId,
+  targetProjectId,
+  targetThreadId,
+  rawThreadReply,
+});
+```
+
+- [ ] **Step 3: 服务端在 complete 时把原始结果镜像进群聊，再由主 Agent 追加一条汇总**
+
+```ts
+await appendProjectMessage({
+  projectId: groupProjectId,
+  sender: "device",
+  senderLabel: `${threadTitle} · ${deviceName}`,
+  body: rawThreadReply,
+});
+
+await appendProjectMessage({
+  projectId: groupProjectId,
+  sender: "master",
+  senderLabel: "主 Agent",
+  body: summary,
+});
+```
+
+- [ ] **Step 4: 提交结果回流链**
+
+```bash
+cd /Users/kris/code/boss
+git add src/lib/boss-master-agent.ts src/lib/boss-data.ts local-agent/server.mjs
+git commit -m "feat: mirror dispatch execution results to group chats"
+```
+
+### Task 6: 全链验证、部署和文档同步
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- Modify: `docs/architecture/api_and_service_inventory_cn.md`
+- Modify: `docs/architecture/ai_handoff_index_cn.md`
+
+- [ ] **Step 1: 运行本地验证**
+
+Run:
+
+```bash
+cd /Users/kris/code/boss
+npm run lint
+npm run build
+curl -sS http://127.0.0.1:3000/api/health
+curl -sS http://127.0.0.1:4317/health
+```
+
+Expected: 全部通过。
+
+- [ ] **Step 2: 用 curl 验证 dispatch plan 主链**
+
+Run:
+
+```bash
+curl -sS -X POST http://127.0.0.1:3000/api/v1/projects/<groupProjectId>/messages \
+  -H 'Content-Type: application/json' \
+  -H 'Cookie: boss_session=...' \
+  -d '{"body":"请把这个需求拆给两个线程执行","kind":"text"}'
+```
+
+Expected: 返回 `dispatchPlan`，且状态为 `pending_user_confirmation`。
+
+- [ ] **Step 3: 部署服务器并跑远端 health check**
+
+Run:
+
+```bash
+cd /Users/kris/code/boss
+./scripts/deploy-server.sh
+"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/health"
+```
+
+Expected: 部署成功，远端 `api/health` 正常。
+
+- [ ] **Step 4: 同步文档**
+
+```bash
+cd /Users/kris/code/boss
+git add README.md docs/architecture/current_runtime_and_deploy_status_cn.md docs/architecture/api_and_service_inventory_cn.md docs/architecture/ai_handoff_index_cn.md
+git commit -m "docs: record orchestration chain status"
+```
diff --git a/docs/superpowers/specs/2026-03-30-conversation-orchestration-and-device-import-design.md b/docs/superpowers/specs/2026-03-30-conversation-orchestration-and-device-import-design.md
new file mode 100644
index 0000000..dee967f
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-30-conversation-orchestration-and-device-import-design.md
@@ -0,0 +1,246 @@
+# 会话编排、主 Agent 调度与设备项目导入设计
+
+## 背景
+
+当前 Boss 已经具备这些基础能力：
+
+- 会话首页、单线程会话、独立群聊、主 Agent 会话、审计对话
+- `master-agent task queue -> local-agent -> codex exec -> complete` 的主 Agent 基础执行链
+- 设备接入草稿、pairing code / token claim、设备心跳与线程上下文上报
+- 线程 = 聊天窗口、文件夹名副标题、会话改名、微信式转发与附件发送
+
+但这些能力现在仍然是半截主链：
+
+- 群聊已能建，但群聊内用户消息还没有正式进入“主 Agent 先理解、再推荐下发”的编排链
+- 非开发任务下的审批逻辑还停留在部分字段和转发闸口，没有扩展到完整消息发送链
+- 新设备接入时仍然是“手填项目列表”，还没有“设备扫描候选项目 -> 用户勾选 -> 主 Agent 理解 -> 映射成聊天窗口”的导入主链
+- 当前 UI 上露出的功能已不少，但逻辑层和状态机没有系统性收口
+
+本轮目标是先补完两条最关键的业务主链：
+
+1. `会话/群聊/主 Agent 编排链`
+2. `添加设备 -> 项目勾选 -> Agent 理解导入 -> 会话落地链`
+
+同时把当前真实进度写回开发文档，供后续继续扩展时使用。
+
+## 目标
+
+1. 群聊消息默认先进入主 Agent，由主 Agent 给出推荐执行线程，用户确认后再下发
+2. 线程执行结果既要回群显示原始结果，也要有主 Agent 汇总
+3. 明确 `development` 与 `approval_required` 两种协作模式，并贯穿群聊消息与线程间沟通
+4. 添加设备流程升级为“真实候选项目勾选 + Agent 理解导入”，不再依赖纯字符串项目列表
+5. 把当前进度和本轮新增的主链写回开发文档，避免后续线程误判系统状态
+
+## 非目标
+
+- 本轮不做真机联调
+- 本轮不重做原生 UI 外观
+- 本轮不引入数据库或新的消息中间件
+- 本轮不细抠主 Agent 的高级决策策略，只先把结构和状态机打通
+
+## 设计概览
+
+### 1. 群聊编排主链
+
+群聊不再被视为线程自由讨论区，而是主 Agent 主持的受控协作会话。
+
+#### 1.1 用户发言入口
+
+- 用户在群聊内发送消息
+- 这条消息先作为用户消息写入当前群聊账本
+- 系统立刻生成一条 `orchestration pending` 状态，让前端知道这条消息正在等待主 Agent 理解
+
+#### 1.2 主 Agent 理解与推荐
+
+- 主 Agent 收到群聊用户消息后，不立即向线程广播
+- 它会结合：
+  - 群成员线程
+  - 设备在线状态
+  - 线程文件夹和线程名
+  - 线程最近活跃度 / 上下文预算
+  - 群聊协作模式
+- 产出一个推荐执行方案，包括：
+  - 推荐下发到哪些线程
+  - 推荐原因
+  - 是否需要用户审批
+  - 如果要拆多步执行，推荐顺序是什么
+
+#### 1.3 用户确认后下发
+
+- 默认策略不是自动下发，而是“主 Agent 推荐 -> 用户确认”
+- 用户确认后，系统创建真正的线程级执行任务
+- 每个执行任务都要绑定：
+  - `projectId`
+  - `groupProjectId`
+  - `deviceId`
+  - `threadId`
+  - `codexFolderRef`
+  - `codexThreadRef`
+  - `requestedBy`
+  - `dispatchPlanId`
+
+### 2. 结果回流主链
+
+线程执行完后，结果需要双通道回流：
+
+#### 2.1 线程原始结果
+
+- 线程原始执行结果直接写回群聊
+- 前端需要能看到“是哪一个线程/设备返回的”
+- 这样群聊保持透明，不是只有主 Agent 的二次转述
+
+#### 2.2 主 Agent 汇总
+
+- 线程原始结果回流后，主 Agent 再补一条汇总
+- 汇总用于：
+  - 提炼结论
+  - 说明下一步
+  - 标记是否还需要用户确认
+
+### 3. 开发任务与非开发任务模式
+
+项目/群聊协作模式统一只有两种：
+
+- `development`
+- `approval_required`
+
+#### 3.1 development
+
+- 允许线程在群内协作
+- 主 Agent 主要负责调度、监督和汇总
+- 线程之间的上下游回复可以直接继续
+
+#### 3.2 approval_required
+
+- 线程之间不能默认自由对话
+- 主 Agent 如果判断两个线程必须沟通，要先创建审批请求
+- 用户批准后，系统才创建临时的跨线程协作窗口或任务
+
+这条规则需要覆盖：
+
+- 群聊消息编排
+- 线程间消息转发
+- 线程直接对话
+- 设备导入后的自动映射建议
+
+### 4. 添加设备与项目导入主链
+
+#### 4.1 创建设备草稿
+
+用户先创建一个设备接入草稿，只录入基础信息：
+
+- 设备名称
+- 头像
+- 所属账号
+- endpoint
+- 备注
+
+这一步不再要求用户手填最终项目字符串来定义真实会话。
+
+#### 4.2 设备首次心跳后上报候选项目
+
+设备 claim 成功或首次心跳后，要让系统看到这台设备真实可见的候选项目：
+
+- Codex 文件夹
+- 每个文件夹下的线程
+- 线程显示名
+- 最近活跃时间
+- 是否建议导入
+
+#### 4.3 用户勾选导入候选
+
+用户在设备接入流程里勾选：
+
+- 要导入哪些文件夹/线程
+- 哪些先不导入
+- 同文件夹下哪些线程要显示成独立聊天窗口
+
+这里的准则继续保持：
+
+- 一个线程 = 一个聊天窗口
+- 同文件夹多个线程 = 多个会话项
+- 会话标题显示线程名，副标题显示文件夹名
+
+#### 4.4 主 Agent 理解导入建议
+
+用户勾选后，先不直接生成最终会话，而是交给主 Agent 做一次导入理解：
+
+- 判断这些线程应关联到哪些现有会话
+- 哪些线程应新建单线程会话
+- 哪些线程应该进入已有群聊
+- 哪些条目只是临时线程，不适合露出到首页
+- 是否存在命名冲突或重复导入
+
+#### 4.5 导入落地
+
+主 Agent 输出导入建议后，系统再真正写入：
+
+- 新单线程会话
+- 现有会话的新增线程成员
+- 建议创建的群聊草稿
+- 未导入项和原因
+
+### 5. 状态模型补充
+
+本轮需要引入或扩展的最小状态对象：
+
+- `dispatchPlan`
+  - 对应主 Agent 一次推荐下发结果
+- `dispatchExecution`
+  - 对应某个被确认的线程执行任务
+- `deviceImportDraft`
+  - 对应设备上报的候选项目和用户勾选状态
+- `deviceImportResolution`
+  - 对应主 Agent 对导入草稿的理解结果
+
+这些状态仍然保存在当前 `data/boss-state.json`，不引入额外基础设施。
+
+## API 与行为边界
+
+### 会话/群聊编排
+
+需要补齐或扩展的接口方向：
+
+- 群聊消息发送后触发编排建议
+- 获取某条群聊消息的 dispatch plan
+- 用户确认 dispatch plan
+- 查询 dispatch execution 结果
+
+### 设备导入
+
+需要补齐或扩展的接口方向：
+
+- 设备候选项目上报
+- 获取设备导入草稿
+- 提交勾选结果
+- 触发主 Agent 理解
+- 获取导入决议
+- 应用导入决议
+
+## 文档要求
+
+本轮开发必须同步更新至少这些文档：
+
+- `docs/architecture/development_subtasks_and_delivery_plan_cn.md`
+- `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- `docs/architecture/api_and_service_inventory_cn.md`
+- 如有新的主链说明，再补 `docs/architecture/ai_handoff_index_cn.md`
+
+## 验收标准
+
+1. 群聊消息不再直接裸发给线程，而是先进入主 Agent 推荐下发链
+2. 用户可以确认主 Agent 推荐的下发对象，再正式发到具体线程
+3. 线程结果能直接回群，主 Agent 也会补汇总
+4. `development` 与 `approval_required` 模式在主消息链里真正生效，不再只是字段占位
+5. 添加设备后能拿到候选项目列表，用户可勾选，再由主 Agent 理解导入
+6. 导入后的线程能映射成真实聊天窗口，而不是只写进设备项目字符串
+7. 文档同步到位，后续线程可直接接手
+
+## 风险与控制
+
+- 风险：主 Agent 推荐和用户确认之间的状态不稳定
+  - 控制：引入显式 `dispatchPlan` 和 `dispatchExecution`
+- 风险：设备候选项目直接裸暴露成会话，导致首页污染
+  - 控制：必须经过主 Agent 理解导入，再落最终会话
+- 风险：审批逻辑只接了一半，导致 development / approval_required 语义继续漂
+  - 控制：把协作模式接入群聊消息链，不只接转发链