boss/docs/superpowers/plans/2026-03-30-conversation-orchestration-and-device-import.md

会话编排、主 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

## 当前阶段进度（2026-03-30）

- Web、主 Agent、local-agent、原生 Android、部署链路已跑通
- 当前缺口集中在：
  - 会话/群聊/主 Agent 编排主链
  - 设备候选项目 -> Agent 理解导入主链

• Step 2: 在运行状态文档登记“下一条逻辑主链目标”

- 下一阶段主目标：把群聊消息默认接到主 Agent，由主 Agent 推荐下发线程，用户确认后再正式执行
- 下一阶段设备接入目标：从手填项目列表升级为真实候选项目勾选与 Agent 理解导入

• Step 3: 在 AI 交接入口补上“当前先做 WP1 + WP2”

- 当前优先工作包：WP1 文档收口、WP2 会话/群聊/主 Agent 编排主链

• Step 4: 提交文档阶段基线

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 编排计划和执行记录

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

dispatchPlans: DispatchPlan[];
dispatchExecutions: DispatchExecution[];

• Step 3: 实现最小 CRUD helper

export async function createDispatchPlan(...) {}
export async function listDispatchPlansByProject(groupProjectId: string) {}
export async function confirmDispatchPlan(...) {}
export async function createDispatchExecutionsFromPlan(...) {}
export async function completeDispatchExecution(...) {}

• Step 4: 提交状态模型扩展

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: 在群聊消息发送接口里识别“需要编排”的场景

const shouldCreateDispatchPlan =
  project?.isGroup &&
  project.id !== "master-agent" &&
  (body.kind ?? "text") === "text" &&
  message.body.trim().length > 0;

• Step 2: 为主 Agent 增加新的任务类型或复用现有 conversation reply 生成推荐 plan

type MasterAgentTaskType =
  | "conversation_reply"
  | "attachment_analysis"
  | "group_dispatch_plan";

• Step 3: 当群聊用户消息到来时，创建 DispatchPlan 而不是直接下发线程

const plan = await queueGroupDispatchPlan({
  groupProjectId: projectId,
  requestMessageId: message.id,
  requestText: message.body,
  requestedBy: session.account,
});

• Step 4: 接口返回编排状态给前端

return NextResponse.json({
  ok: true,
  message,
  dispatchPlan: plan ?? null,
  collaborationGate,
});

• Step 5: 提交群聊编排入口

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: 增加查询群聊编排计划接口

GET /api/v1/projects/[projectId]/dispatch-plans

• Step 2: 增加用户确认推荐下发对象接口

POST /api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm
body: { approvedTargetProjectIds: string[] }

• Step 3: 确认后创建 DispatchExecution 记录，并排队给 local-agent / codex 线程

const executions = await createDispatchExecutionsFromPlan({
  planId,
  approvedTargetProjectIds,
  confirmedBy: session.account,
});

• Step 4: 在群聊账本插入“已确认下发”系统消息

sender: "master",
senderLabel: "主 Agent",
body: "已根据你的确认把任务下发到 2 个线程。"

• Step 5: 提交 dispatch plan 确认链

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

export async function appendDispatchExecutionResult(...) {}

• Step 2: local-agent 执行完成后，除了原来的任务 complete，还要带回 target project / thread result

await postJson(`/api/v1/master-agent/tasks/${taskId}/complete`, {
  ...
  dispatchExecutionId,
  targetProjectId,
  targetThreadId,
  rawThreadReply,
});

• Step 3: 服务端在 complete 时把原始结果镜像进群聊，再由主 Agent 追加一条汇总

await appendProjectMessage({
  projectId: groupProjectId,
  sender: "device",
  senderLabel: `${threadTitle} · ${deviceName}`,
  body: rawThreadReply,
});

await appendProjectMessage({
  projectId: groupProjectId,
  sender: "master",
  senderLabel: "主 Agent",
  body: summary,
});

• Step 4: 提交结果回流链

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:

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:

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:

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: 同步文档

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"