feat: harden agent onboarding and device import flows

2026-03-31 05:18:58 +08:00
parent 4aed93e90c
commit f417fe1955
18 changed files with 975 additions and 132 deletions
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@
 - `src/boss_control`：空占位目录，不参与当前运行
 - `src/boss_device_agent`：空占位目录，不参与当前运行

-## 当前运行状态（2026-03-30）
+## 当前运行状态（2026-03-31）

 本地：

@@ -54,7 +54,7 @@
 - `POST http://127.0.0.1:3000/api/v1/projects/[projectId]/messages` 正常，普通单线程会话当前会返回 `conversation_reply` 任务，并等待绑定设备上的真实 Codex 线程回写
 - `POST http://127.0.0.1:3000/api/auth/logout` 正常，退出后访问受保护 `/api/v1/*` 会返回 `401`
 - `GET http://127.0.0.1:3000/api/v1/user/ota/package` 正常，当前会返回最新 APK 包
- `GET http://127.0.0.1:4317/health` 正常
+- 当前这台开发机在本轮 `launchctl` 重载后，`GET http://127.0.0.1:4317/health` 仍未恢复；代码已改成先起本地 health 监听、再异步执行首次 heartbeat / task poll，剩余问题已收敛到 launchd 环境差异排查
 - `GET http://127.0.0.1:4317/api/v1/skills` 正常，已返回本机扫描到的 Codex Skill
 - `POST http://127.0.0.1:4317/api/v1/heartbeat` 正常，且会顺带触发 `thread-context` 上报
 - `launchd` 已加载：`~/Library/LaunchAgents/com.hyzq.boss.local-agent.plist`
@@ -94,7 +94,7 @@ Android APK：
 - 已生成 Android debug APK：`android/app/build/outputs/apk/debug/app-debug.apk`
 - 已生成 Android signed release APK：`android/app/build/outputs/apk/release/app-release.apk`
 - `npm run apk:release` 还会额外产出带版本号的文件：`android/app/build/outputs/apk/release/boss-android-v{versionName}-release.apk`
- 当前最新 release 构建版本：`2.5.5`（`versionCode=18`）
+- 当前最新 release 构建版本：`2.5.6`（`versionCode=19`）
 - 当前 APK 已切到原生 Android 客户端：`MainActivity + BossApiClient + 原生 XML 布局`
 - 当前原生活动页已经覆盖：会话首页、项目详情、项目目标、版本记录、会话信息、群资料、发起群聊、消息转发、线程详情、设备详情、添加设备、账号与安全、设置、AI 账号、技能、运维中心、关于
 - 当前原生一级体验已回退到微信式交互：`会话 / 设备 / 我的` 固定底部 tab，会话首页是简单聊天列表，`主 Agent / 审计对话` 以普通置顶会话样式排在最前；项目详情页是聊天优先，只保留 `项目目标 / 版本记录` 两个轻入口
@@ -108,9 +108,11 @@ Android APK：
 - 当前群聊调度主链已补上第一轮业务闭环：群聊文字消息会先进入主 Agent 生成推荐下发方案，用户确认后创建真正的线程执行单，执行完成后会把线程原始结果回写到群聊，再追加一条主 Agent 汇总
 - 当前 `approval_required` 群聊已补齐两条审批动作：可以确认主 Agent 推荐，也可以明确拒绝；拒绝后会把群审批状态写成 `rejected`，并在群里追加系统提示，不会继续下发到线程
 - 当前原生聊天页已把待审批推荐前移到主消息流：`ProjectDetailActivity` 会直接显示 `确认下发 / 拒绝`，刷新后也能恢复最近一条待确认推荐
+- 当前 `approval_required` 群聊在已有待确认推荐时，会拒绝继续生成新的推荐，并提示用户先确认或拒绝当前推荐，避免审批消息叠加
 - 当前三条聊天主链都已接入真实等待链路：`主 Agent 单聊 / 普通线程单聊 / 群聊确认下发` 当前都会返回任务信息，原生 Android 会保持等待直到收到真实回写或明确超时提示
 - 当前 `我的 > AI 账号` 已补 `登录 OpenAI 平台账号` 与 `绑定 Master Codex Node` 两条显式入口；OpenAI API 登录成功后会立即设为当前主控
 - 当前 `登录 OpenAI 平台账号` 已升级成浏览器辅助登录流：会先进入原生引导页，再自动打开 `OpenAI Platform` 登录页；用户登录后可直接跳到 `API Keys` 页面，回 APP 粘贴 key 完成接入
+- 当前 `AI 账号` 页顶部会显式展示“当前主控身份”，并提供 `校验主控 / 测试主 Agent 对话` 两个动作，切换主控后可直接验证聊天通路
 - 当前 `OpenAiOnboardingActivity` 在登录成功后会直接给出 `测试主 Agent 对话` 入口，可一键跳到 `master-agent` 聊天页
 - 当前主控若还是 `Master Codex Node`，但节点离线或执行立即失败，主 Agent 会优先尝试已配置的 `OpenAI API` 备用账号，避免聊天直接掉成失败日志
 - 当前群资料页已经支持“修复群成员”：如果历史脏群里混入了 `master-agent` 或失效线程引用，前台会明确提示并允许重新选择真实线程成员，修复后会正式写回群成员账本
@@ -118,6 +120,7 @@ Android APK：
 - 当前 Web 群聊页也已补上待确认推荐的刷新恢复：群聊详情会在服务端读取最近一条 `pending_user_confirmation` 的 dispatch plan，并在刷新或重新进入页面后继续显示“等待你确认主 Agent 推荐”
 - 当前设备导入主链已补上第一轮后端闭环：设备 heartbeat 可上报真实项目候选，服务端会生成 `import draft`；用户可提交勾选结果、触发主 Agent 风格的导入决议，并把选中的线程真正落成聊天窗口
 - 当前新设备导入前台已经接通：Web `添加设备` 成功后会直接进入“导入项目”步骤；设备页详情里也可再次打开导入草稿。原生 Android 端同样已补 `DeviceImportDraftActivity`，可完成 `勾选 -> 预览决议 -> 应用导入`
+- 当前设备导入前台文案与状态卡已收口：会明确显示 `等待候选线程 / 等待勾选 / 建议已生成 / 已导入`，并在导入后回显真正落到会话首页的线程名
 - 当前 `dispatch_execution` 完成回写已补幂等：同一个执行单重复完成，不会再向群聊重复追加线程原始回复和主 Agent 汇总
 - 当前当 heartbeat 同时携带旧 `projects` 和新 `projectCandidates` 时，服务端会优先走 `import draft`，不再绕过勾选/应用阶段直接把旧项目目录导入为聊天窗口
 - 当前设备导入 `review` 已补 owner/admin 鉴权，并会留下 `device_import_resolution` master task 轨迹，再把决议写回草稿和会话账本
@@ -199,6 +202,7 @@ device-agent 当前职责：
 - 对普通单线程会话，认领到的 `conversation_reply` 任务会直接恢复到目标 Codex 线程，并把线程原始回复回写到对应聊天窗口
 - 对群聊线程分发任务，认领到的 `dispatch_execution` 任务会把原始线程结果和主 Agent 汇总一起回写到群聊消息账本
 - `local-agent` 对 `conversation_reply / dispatch_execution` 当前会优先使用 `codex exec resume <targetCodexThreadRef>`，只有缺失真实线程引用时才退回 `--ephemeral`
+- `local-agent` 当前会先启动本地 `4317` 健康监听，再异步执行首次 heartbeat 和 task poll，避免控制面短暂阻塞时本地健康检查一起挂死
 - 如果某个历史群聊里已经没有真实线程成员，当前不会再表现成“发了没反应”，而是会在群里追加一条 `system_notice`，提示用户先重新整理群成员
 - 设备导入审核当前也会落 `device_import_resolution` 任务轨迹，但决议内容仍是服务端 heuristic 版；下一阶段可再升级成真正通过 `local-agent -> codex exec` 参与理解
 - 提供本地 `/health`、`/api/v1/device`、`/api/v1/skills`、`/api/v1/heartbeat`