# Boss API 与服务清单

这份文档只记录当前已经实现并可用的服务和接口。

## 1. 服务清单

### 1.1 boss-web

- 形态：Next.js App Router 服务
- 本地端口：`3000`
- 本地健康检查：`GET /api/health`
- 服务器进程：`boss-web.service`
- 服务器工作目录：`/opt/boss`
- 状态文件：通过 `BOSS_STATE_FILE` 显式指向 `data/boss-state.json`
- 当前登录态：`boss_session` HttpOnly Cookie
- 当前原生恢复态：`restore token + SharedPreferences`
- 当前执行底座：`src/lib/execution/`，已包含 `ExecutionBackend / PromptAssembler / PermissionPolicy / RemoteRuntimeAdapter / OrchestrationBackend` 默认实现

### 1.2 boss-android-native

- 形态：原生 Android 客户端
- 原生入口：`android/app/src/main/java/com/hyzq/boss/MainActivity.java`
- API 客户端：`android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
- 当前导航：`会话 / 设备 / 我的`
- 当前一级交互：微信式简单列表与聊天优先
- 当前微信式 surface contract：`android/app/src/main/java/com/hyzq/boss/WechatSurfaceMapper.java`
- 当前原生活动页：
  - `MainActivity`
  - `ProjectDetailActivity`
  - `ConversationInfoActivity`
  - `ThreadStatusActivity`
  - `GroupInfoActivity`
  - `GroupCreateActivity`
  - `ProjectGoalsActivity`
  - `ProjectVersionsActivity`
  - `ProjectForwardActivity`
  - `ThreadDetailActivity`
  - `DeviceDetailActivity`
  - `DeviceEnrollmentActivity`
  - `SkillInventoryActivity`
  - `SecurityActivity`
  - `SettingsActivity`
  - `AiAccountsActivity`
  - `OpenAiOnboardingActivity`
  - `OpsCenterActivity`
  - `AboutActivity`
- 当前项目聊天页：
  - `ProjectDetailActivity` 已改成聊天优先布局
  - 主面只保留 `项目目标 / 版本记录`
  - 右上角会进入微信式 `会话信息 / 群资料`
  - `approval_required` 群聊的待确认推荐会直接显示在主消息流里，支持 `确认下发 / 拒绝`
  - 脏群会在主消息流上方直接显示 `去修复` 入口，并跳转到 `GroupInfoActivity`
  - 单线程会话支持按微信最新逻辑改线程名
  - 当前已经支持从单线程会话发起独立群聊，群聊创建后作为新会话保留，原会话不升级
  - 当前单线程会话已经支持打开 `线程状态` 只读页，查看主 Agent 当前掌握的线程状态文档和最近进展事件
  - 当前已经支持微信式消息转发：长按消息可直接 `转发 / 多选 / 复制 / 删除`
  - 当前多选模式会切换成微信式 `取消 + 已选数量 + 底部转发` 状态
  - 当前统一使用 `ForwardTargetActivity` 选择目标会话，替换旧的备注转发主链
  - 当前已支持聊天附件主链：输入框左侧 `+` 会打开底部抽屉，支持图片 / 视频 / 文件发送；图片 / 视频先确认，文件直接发送
  - 当前附件消息支持下载、原生打开、手动分析和自动分析状态展示
  - `线程详情 / 运维调试` 仍保留对应原生活动页，但已退出主聊天面
  - 当前已补上本地发送中气泡、发送按钮状态控制，以及“只有接近底部才自动滚到底”的消息流行为
- 当前根页导航：
  - `MainActivity` 会记住最近一次停留的 `会话 / 设备 / 我的` tab
  - 根页返回逻辑已改成“先回会话 tab，再按一次返回进入后台”
- 当前会话列表：
  - 已切到“线程 = 会话窗口”
  - 主标题显示线程名
  - 第二行显示所属文件夹名
  - 右下角显示后台活跃数量动态图标
  - `主 Agent / 审计对话` 已作为普通置顶会话固定在顶部
  - 会话首页右上角当前为微信式 `+` 入口，可直接从会话列表发起独立群聊
- 当前 `关于` 页：
  - 保留版本与 OTA 操作
  - 当前已补上 OTA 下载进度、失败重试、安装授权提示和返回关于页后的本地状态恢复
- 当前 `我的` 根页：
  - 保留 `账号与安全 / 设置 / 运维与修复 / AI 账号 / 技能 / 关于`
  - `运维与修复` 直接进入 `OpsCenterActivity`
- 当前 `OpenAiOnboardingActivity`：
  - 会先自动打开 `OpenAI Platform` 登录页
  - 支持继续打开 `API Keys` 页面
  - 回 APP 后可直接粘贴 key，并设为当前主控
  - 登录成功后会直接给出 `测试主 Agent 对话` 入口
- 当前登录：临时免验证，点击登录直接创建最高管理员会话
- 当前会话恢复：`SharedPreferences` 中保存 `boss_session / restore_token / account`

### 1.3 boss-local-agent

- 形态：Node 原生 HTTP 服务
- 本地端口：默认 `4317`
- 健康检查：`GET /health`
- 当前常驻方式：`launchd`
- 当前额外职责：向云端上报 `thread-context`
- 当前新增职责：递归扫描本机 `~/.codex/skills` 并同步到设备 Skill 接口
- 当前完成回写：`conversation_reply / dispatch_execution` 会先标准化成统一远程执行结果，再调用 `/api/v1/master-agent/tasks/[taskId]/complete`
- 当前 `dispatch_execution` 会按 `orchestrationBackendId` 分流：默认走 `codex exec resume`，显式选择 `omx-team` 且本机配置可用时改走 `OMX Team Runtime` JSON 协议
- 当前 `RemoteRuntimeAdapter` 还负责拦截固定模式的线程内部环境提示；命中后会直接改写成失败，避免把只读/cwd 这类脏文本写进聊天记录

### 1.4 Caddy

- 作用：反向代理和 HTTPS 自动续签
- 服务器服务名：`caddy.service`
- 配置文件：`deployment/Caddyfile`

### 1.5 boss-server-debug skill

- 作用：跨 Codex 窗口稳定连接 `106.53.170.158`
- 路径：`$HOME/.codex/skills/boss-server-debug/SKILL.md`
- 密码来源：优先读取 macOS Keychain

### 1.6 Postfix + Dovecot

- 作用：服务器侧邮件发送 / 接收基础设施
- SMTP 端口：`25 / 465 / 587`
- IMAPS 端口：`993`
- 本机测试邮箱：`bossmail`
- 当前别名：`verify@boss.hyzq.net`、`no-reply@boss.hyzq.net`
- 部署脚本：`scripts/install-server-mail.sh`
- 服务器配置目录：`deployment/mail/`
- Web 切换入口：`/opt/boss/.env.server`

## 2. Web 页面路由

### 2.1 一级页

- `GET /auth/login`
- `GET /conversations`
- `GET /devices`
- `GET /me`

### 2.2 二级页

- `GET /auth/register`
- `GET /auth/forgot-password`
- `GET /auth/help`
- `GET /conversations/[projectId]`
- `GET /conversations/[projectId]/forward`
- `GET /conversations/[projectId]/goals`
- `GET /conversations/[projectId]/thread-status`
- `GET /conversations/[projectId]/versions`
- `GET /threads/[threadId]`
- `GET /devices/add`
- `GET /me/security`
- `GET /me/about`
- `GET /me/storage`
- `GET /me/ai-accounts`
- `GET /me/ops`
- `GET /me/ops/audit`
- `GET /me/settings`
- `GET /me/skills`
- `GET /me/master-agent`
- `GET /me/master-agent`

## 3. Web API 路由

### 3.1 健康和状态

#### `GET /api/health`

- 用途：Web 健康检查
- 响应：`{ ok, service, now }`

#### `GET /api/state`

- 用途：读取当前完整状态
- 注意：这是内部 MVP 调试接口，会直接返回整个 `BossState`

### 3.1.1 执行底座抽象层

- 目录：`src/lib/execution/`
- 当前默认实现：
  - `types.ts`
  - `execution-backend.ts`
  - `orchestration-backend.ts`
  - `prompt-assembler.ts`
  - `memory-resolver.ts`
  - `permission-policy.ts`
  - `tool-registry.ts`
  - `backend-selector.ts`
  - `remote-runtime-adapter.ts`
  - `backends/*`
- 当前状态：
  - 已在生产代码中被 `boss-master-agent.ts`、`local-agent/server.mjs` 和 `master-agent task complete route` 使用
  - 当前仍服务 Boss 自身执行链
  - 当前已最小接入 `ClawBackendAdapter`，但默认关闭，仅在显式配置且可用性探测通过时才参与执行
  - 如果历史 `backendOverride=claw-runtime` 当前不可用，运行时会自动回退到默认后端，并把原因回给前台
  - 当前仓库自带 `scripts/claw-runtime-smoke.mjs` 作为兼容 JSON 协议的 smoke runtime，可用于本地和服务器验证 `ClawBackendAdapter`
  - 当前已最小接入 `Hermes Runtime`，但默认关闭，仅在显式配置且可用性探测通过时才参与执行
  - 如果历史 `backendOverride=hermes-runtime` 当前不可用，运行时会自动回退到默认后端，并把原因回给前台
  - 当前仓库自带 `scripts/hermes-runtime-smoke.mjs`，可用于本地和服务器验证 `Hermes Runtime`
  - 当前 `master-agent` 会话已支持显式选择 `hermes-runtime`
  - 当前普通单线程会话也已支持显式保存 `backendOverride=hermes-runtime`；未设置 override 时仍走原有目标设备本地线程回复链，显式设置后服务端会异步调用 `Hermes Runtime` 并把结果回写到原线程消息流
  - 当前已最小接入 `OmxTeamBackendAdapter`，但默认关闭；Web 群聊详情页和原生群资料页已经可以在 `Boss Native` 与 `OMX Team` 间切换编排后端，OMX 不可用时会自动回退到默认后端并返回明确原因
  - 当前仓库自带 `scripts/omx-team-smoke.mjs`，可用于本地和服务器验证 `OmxTeamBackendAdapter` 的 `dispatch_execution` JSON 协议

### 3.1.2 线程状态文档与进展事件

- 状态字段：
  - `threadStatusDocuments`
  - `threadProgressEvents`
- 当前用途：
  - 让主 Agent 优先读取线程状态文档和最近进展事件，而不是常态重复深问线程
  - 让 Web / Android 前台能直接查看线程的当前目标、阶段、进度、架构、阻塞、建议下一步
- 当前同步策略：
  - `heartbeat / thread reply` 平时优先写轻量进展事件
  - 首次理解、状态变薄、长时间未刷新或主 Agent 真正接手时，才补排隐藏全量理解任务

### 3.1.3 主 Agent 任务级模型策略

- 当前任务账本 `masterAgentTasks` 已支持：
  - `executionModel`
  - `executionReasoningEffort`
- 当前用途：
  - 把 `master-agent` 会话上的 `smart*` 策略真正下发给深度任务，而不是只停留在设置页
  - 让 `group_dispatch_plan / device_import_resolution / attachment_analysis` 这类深度任务可以和普通聊天使用不同模型
- 当前执行链：
  - 服务端排队深度任务时写入 `executionModel / executionReasoningEffort`
  - `local-agent/codex-task-runner.mjs` 执行时优先使用任务级 `executionModel`
  - `executionReasoningEffort` 当前已落到任务账本，供后续继续扩到更多 Runtime / API 执行器

### 3.2 认证相关

#### `POST /api/auth/send-code`

- 用途：生成验证码
- 输入：
  - `account`
  - `purpose`: `login | register | forgot-password`
- 当前行为：在邮件验证码正式切换前，固定验证码为 `000000`
- 当前说明：Web 侧已经支持 email 模式，email 模式下会通过本机 `sendmail` 调用 `Postfix` 发信；服务器默认仍保持 fixed
- 当前保护：60 秒冷却，同一账号 15 分钟窗口内超过 5 次会被限流
- 当前前置校验：
  - `purpose=login | forgot-password` 时要求账号已存在
  - `purpose=register` 时要求账号尚未注册
- 当前 fixed 模式：登录可直接输入 `000000`，不再依赖先申请验证码；注册和重置密码仍走 `send-code` 申请链路

#### `POST /api/auth/login`

- 输入：
  - `account`
  - `method`: `password | code`
  - `password`
  - `code`
- 当前行为：
  - 当前已临时切到免验证模式，点击登录会直接创建 `17600003315` 的最高管理员会话
  - 原生 Android 端登录后会持久化 `boss_session + restore token`，用于 30 天登录保持和 OTA / 覆盖安装后的会话恢复
  - 当前阶段不会因为账号、密码或验证码为空而拒绝登录
  - 校验通过后会写入 `boss_session` Cookie
  - 当请求头带 `x-boss-native-app: 1` 时，还会额外返回 `restoreToken`
  - 当前 `boss_session` 默认保持 30 天
  - 连续失败 5 次后会锁定 10 分钟
- 当前密码存储：新注册 / 重置密码使用 `scrypt`；历史 `sha256` 会在下次密码登录时自动迁移
- 当前默认管理员账号：`17600003315`
- 当前默认测试密码：`boss123456`

#### `GET /api/auth/session`

- 用途：读取当前登录会话信息
- 返回：
  - `account`
  - `role`
  - `displayName`
  - `loginMethod`
  - `expiresAt`
  - `lastSeenAt`
- 当请求头带 `x-boss-native-app: 1` 时，还会返回：
  - `restoreToken`

#### `POST /api/auth/restore`

- 用途：原生 APP 使用 `restore token` 恢复 `boss_session`
- 输入：
  - `restoreToken`
- 当前行为：
  - 校验 `restoreToken` 是否对应未过期的登录会话
  - 校验通过后重新写入 `boss_session` Cookie
  - 用于 OTA / 同签名覆盖安装后的自动登录恢复

#### `POST /api/auth/logout`

- 用途：注销当前登录会话并清除 `boss_session`

#### `POST /api/auth/register`

- 输入：
  - `account`
  - `password`
  - `confirmPassword`
  - `code`

#### `POST /api/auth/forgot-password`

- 输入：
  - `account`
  - `password`
  - `confirmPassword`
  - `code`

### 3.3 设备心跳和当前老接口

#### `POST /api/device-heartbeat`

- 用途：设备端心跳上报
- 输入：
  - `deviceId`
  - `token`
  - `pairingCode`
  - `name`
  - `avatar`
  - `account`
  - `status`
  - `quota5h`
  - `quota7d`
  - `projects`
  - `endpoint`
- 当前行为：
  - 写入 `data/boss-state.json`
  - 更新设备状态
  - 若 `pairingCode` 合法，则 claim 设备绑定草稿并返回 token
  - 若携带 `projectCandidates[]`，则会同步生成或刷新对应设备的 `deviceImportDraft`

#### `POST /api/projects/[projectId]/goals/[goalId]/toggle`

- 用途：切换目标完成状态
- 输出：更新后的 `goal`

#### `POST /api/projects/[projectId]/goals/update`

- 用途：编辑或新增目标
- 输入：
  - `goalId`
  - `text`
  - `action`: `create | update`
- 输出：更新后的 `goal`

### 3.4 聚合 BFF / 实时接口

#### `GET /api/v1/conversations`

- 用途：返回平铺线程视图，供群聊创建、消息转发等内部能力使用
- 关键字段：
  - `conversationType`
  - `manualPinned`
  - `threadTitle`
  - `folderLabel`
  - `lastMessagePreview`
  - `activityIconCount`
  - `topPinnedLabel`
  - `groupMembers`

#### `GET /api/v1/conversations/home`

- 用途：返回会话首页使用的“项目聚合 + 线程下钻”视图
- 当前行为：
  - 单线程项目直接返回单线程会话项
  - 同一设备 / 同一 Codex 文件夹下存在多个线程时，会聚合成 `folder_archive`
  - `master-agent`、`audit-collab`、群聊等特殊会话会保持普通置顶会话样式直接返回
- 关键字段：
  - `conversationType`
  - `folderKey`
  - `threadCount`
  - `threadTitle`
  - `folderLabel`
  - `lastMessagePreview`

#### `GET /api/v1/conversation-folders/[folderKey]`

- 用途：读取某个项目归档项下的线程列表
- 当前行为：
  - 返回指定 `folderKey` 的汇总信息
  - 返回该文件夹下全部线程会话，供 Web 和原生 Android 的项目线程列表页使用
- 关键字段：
  - `folder.folderKey`
  - `folder.threadCount`
  - `folder.threads[]`

#### `POST /api/v1/conversations/[projectId]/actions`

- 用途：会话置顶 / 标记已读
- 输入：
  - `action`: `toggle_pin | mark_read`

#### `GET /api/v1/projects/[projectId]`

- 用途：项目详情聚合
- 返回：
  - `activeThreadContexts`
  - `threadsRequiringHandoff`
  - `nextCompactionRiskThreadId`
  - `masterContextStrategySummary`
  - `recentAppLogs`
  - `openFaults`
  - `relatedAuditResults`
  - `masterIdentity`（仅主 Agent 项目）

#### `POST /api/v1/projects/[projectId]/messages`

- 用途：向项目消息账本写文本/语音/图片/视频意图消息
- 输入：
  - `body`
  - `kind`: `text | voice_intent | image_intent | video_intent`
- 当前行为：
  - 普通单线程项目当前会在写入用户消息后，继续创建 `taskType=conversation_reply` 的主 Agent 任务
  - 如果该普通单线程项目当前显式设置了 `backendOverride=hermes-runtime`，这条 `conversation_reply` 会改挂到 `master-agent-hermes / hermes-runtime`
  - 如果普通单线程项目没有显式设置 `backendOverride`，仍保持原有 `local-agent -> codex exec resume` 路径不变
  - 返回体会附带 `task.taskId / taskType / status`，给 Web 和原生 Android 保持等待真实回写使用
  - `projectId=master-agent` 且 `kind=text` 时，会先返回 `masterReplyState + task`，真实回复随后异步回写到账本
  - 当前主链路优先走 `Master Codex Node`：`task queue -> local-agent -> codex exec -> complete`
  - 如果当前主控是 `Master Codex Node`，但节点离线或执行立即失败，主 Agent 当前会优先尝试已配置的 `OpenAI API / 阿里百炼 Qwen` 账号，避免聊天直接只剩失败日志
  - 如本机节点未接通，可切到 `OpenAI API` 或 `阿里百炼 Qwen` 备用账号
  - 群聊项目当前会带上 `collaborationGate`，用于标明当前是否需要先经主 Agent / 用户审批
  - 群聊文本消息当前还会返回 `dispatchPlan / dispatchRecommendation`，用于展示主 Agent 推荐的线程下发方案
  - 如果群里已经有一条待确认推荐，接口会直接返回 `409`，要求先确认或拒绝当前推荐，避免审批消息叠加

#### `GET /api/v1/projects/[projectId]/agent-controls`

- 用途：读取当前对话级别的模型、推理、后端与接管控制
- 当前约束：
  - `projectId=master-agent` 时支持 `modelOverride / reasoningEffortOverride / fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride / promptOverride / backendOverride / globalTakeoverEnabled`
  - 普通单线程项目当前只会返回 `takeoverEnabled / backendOverride` 这类会话级覆盖
  - 未配置时返回 `controls: null`

#### `POST /api/v1/projects/[projectId]/agent-controls`

- 用途：更新当前对话级别的模型、推理、后端与接管控制
- 当前约束：
  - `master-agent` 会话当前支持 `modelOverride / reasoningEffortOverride / fastModelOverride / fastReasoningEffortOverride / smartModelOverride / smartReasoningEffortOverride / promptOverride / backendOverride / globalTakeoverEnabled`
  - 主 Agent 普通聊天回复会按 `fast*` 默认策略解析模型与推理强度，深度任务保留 `smart*` 默认策略入口；显式 `modelOverride / reasoningEffortOverride` 始终优先于 fast/smart 策略
  - 普通单线程会话当前只支持 `takeoverEnabled / backendOverride`
  - 普通单线程会话的 `backendOverride` 当前只允许 `hermes-runtime`，不开放 `claw-runtime`
  - 只有在对应 Runtime 可用性探测通过时才允许保存对应覆盖
  - 显式传 `null` 或空字符串表示清空覆盖；省略字段表示保留原值

#### `GET /api/v1/projects/[projectId]/orchestration-backend`

- 用途：读取群聊当前的编排后端状态
- 返回：
  - `currentBackendId`
  - `currentBackendLabel`
  - `requestedBackendId`
  - `requestedBackendLabel`
  - `availableChoices[]`
  - `omxAvailability`
- 当前行为：
  - 当没有显式覆盖时，API 会把 `requestedBackendId` 视为 `null`
  - 当前实际生效的默认后端仍是 `boss-native-orchestrator`
  - `Boss Native` / `OMX Team` 选择会同时暴露给 Web 群聊页和原生群资料页

#### `PATCH /api/v1/projects/[projectId]/orchestration-backend`

- 用途：更新群聊的编排后端偏好
- 输入：
  - `requestedBackendId`
- 当前行为：
  - `requestedBackendId=omx-team` 时会尝试保存 `OMX Team`
  - `requestedBackendId=boss-native-orchestrator` 时会回到默认编排后端
  - 如果 `OMX Team` 不可用，保存时会返回明确的回退原因
  - 该接口与 Web 群聊页、原生群资料页上的编排后端选择卡保持一致

#### `GET /api/v1/projects/[projectId]/participants`

- 用途：读取单线程会话的线程归属信息，或群聊会话的成员线程列表
- 返回：
  - `projectId`
  - `isGroup`
  - `threadMeta`
  - `participants[]`
  - `repairRequired`
  - `repairReason`
  - `validParticipantCount`
  - `invalidParticipantCount`

#### `POST /api/v1/projects/[projectId]/participants`

- 用途：修复或重设群聊成员
- 输入：
  - `memberProjectIds[]`
- 当前行为：
  - 只允许把真实可下发的线程会话加入群聊
  - 至少要求 2 个线程成员
  - 成功后会重写群成员列表，并追加一条 `kind=system_notice` 的“已更新群成员”消息

#### `POST /api/v1/projects/[projectId]/rename`

- 用途：重命名单线程会话或群聊会话
- 输入：
  - `mode`: `thread | group`
  - `name`
- 当前行为：
  - `mode=thread` 时同步更新线程显示名和会话标题
  - `mode=group` 时更新群聊名称

#### `POST /api/v1/projects/[projectId]/group-chat`

- 用途：从当前单线程会话出发，创建新的独立群聊
- 输入：
  - `memberProjectIds[]`
- 当前行为：
  - 原始单线程会话会保留
  - 新群聊默认自动命名
  - 新群聊默认由主 Agent 发起，并以开发任务协作为默认模式

#### `POST /api/v1/group-chats`

- 用途：从会话首页直接发起独立群聊，不依赖某个来源单线程会话
- 输入：
  - `memberProjectIds[]`
- 当前行为：
  - 至少要求 2 个线程
  - 新群聊会作为独立会话插入列表
  - 群名会按成员线程自动生成
  - 创建完成后仍可在群资料页改名

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

- 用途：读取当前群聊最近一批主 Agent 推荐下发方案
- 当前行为：
  - 只返回当前群聊关联的 dispatch plan
  - 会附带目标线程列表、审批状态、已确认目标和最近一次确认人
  - Web/原生前台会用它恢复“等待你确认主 Agent 推荐”的待处理状态；当前 Web 群聊详情页在刷新后会继续渲染最近一条 `pending_user_confirmation` 计划

#### `POST /api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm`

- 用途：由用户确认主 Agent 推荐的下发目标
- 输入：
  - `approvedTargetProjectIds[]`
- 当前行为：
  - 只允许对 `pending_user_confirmation` 的 dispatch plan 执行确认
  - 确认后会创建真正的 `dispatchExecution`
  - 会写入一条 `kind=system_notice` 的群聊系统消息
  - 同时会为每个执行单创建 `taskType=dispatch_execution` 的主 Agent 任务，等待对应设备的 local-agent 认领

#### `POST /api/v1/projects/[projectId]/dispatch-plans/[planId]/reject`

- 用途：拒绝主 Agent 推荐的线程下发方案
- 当前行为：
  - 会把 dispatch plan 标记为 `rejected`
  - 对 `approval_required` 群聊会把项目审批状态写成 `rejected`
  - 会追加一条 `kind=system_notice` 的“已拒绝主 Agent 推荐”消息

#### `GET /api/v1/accounts`

- 用途：返回 AI 账号列表、当前主控身份和切换历史

#### `POST /api/v1/accounts/onboard/openai-api`

- 用途：通过 `OpenAI API Key` 在手机端登录 `OpenAI 平台账号`
- 输入：
  - `label`
  - `displayName`
  - `accountIdentifier`
  - `model`
  - `apiKey`
- 当前行为：
  - 先对候选 `API Key` 做真实 OpenAI 探针校验
  - 校验成功后创建或更新 `openai_api` 主账号
  - 立即设为当前主控
  - 返回 `activeIdentity`
  - 返回结果会带当前主控状态摘要，供原生 Android 直接弹出“测试主 Agent 对话”
  - 若服务器当前无法访问 `api.openai.com`，会直接返回明确中文网络错误，而不是只返回 `fetch failed`

#### `POST /api/v1/accounts/onboard/aliyun-qwen`

- 用途：通过阿里百炼兼容接口接入 `Qwen` 备用账号
- 输入：
  - `label`
  - `displayName`
  - `accountIdentifier`
  - `model`
  - `apiKey`
- 当前行为：
  - 先对候选 `API Key` 做真实阿里百炼兼容 `responses` 探针校验
  - 校验成功后创建或更新 `aliyun_qwen_api` 备用账号
  - 默认不抢占当前主控，只作为 fallback 链路保存
  - 返回当前主控摘要，方便前台立刻刷新账号状态

#### `POST /api/v1/accounts/onboard/master-node`

- 用途：显式绑定一台电脑上的 `Master Codex Node`
- 输入：
  - `label`
  - `displayName`
  - `accountIdentifier`
  - `nodeId`
  - `nodeLabel`
  - `model`
- 当前行为：
  - 创建或更新 `master_codex_node` 主账号
  - 可直接切为当前主控
  - 不假装“手机里直接登录 GPT”
  - 返回登录指引与当前校验结果

#### `POST /api/v1/accounts`

- 用途：新增 AI 账号
- 当前 provider：
  - `master_codex_node`
  - `openai_api`
  - `aliyun_qwen_api`
- 当前产品语义：
  - `master_codex_node` 表示已经在绑定电脑上登录 `ChatGPT Plus / Codex` 的执行节点
  - `openai_api` 作为用户自行配置的 OpenAI 主控或容灾
  - `aliyun_qwen_api` 作为用户自行配置的阿里百炼 Qwen 兼容备用链路

#### `GET /api/v1/accounts/[accountId]`

- 用途：读取单个 AI 账号详情

#### `PATCH /api/v1/accounts/[accountId]`

- 用途：更新 AI 账号配置、启停状态和说明

#### `DELETE /api/v1/accounts/[accountId]`

- 用途：删除非环境回退型 AI 账号

#### `POST /api/v1/accounts/[accountId]/activate`

- 用途：切换当前主控 AI 身份

#### `POST /api/v1/accounts/[accountId]/validate`

- 用途：校验指定 AI 账号是否可用
- 当前行为：
  - `master_codex_node`：明确提示“主 GPT 不在手机里直接登录”，并同时校验绑定设备是否在线；在线时返回 `ready`，离线时返回 `degraded`
  - `openai_api`：实际调用模型返回探针结果
  - `aliyun_qwen_api`：实际调用阿里百炼兼容接口返回探针结果
- 当前约束：
  - `openai_api` 的容灾 Key 由用户在 APP 内配置，不走服务器默认预置
  - 手机端当前没有直接的 ChatGPT OAuth 登录流程；主 GPT 必须先在绑定电脑上的 Codex / ChatGPT Plus 会话里完成登录

#### `POST /api/v1/projects/[projectId]/forwards`

- 用途：把消息转发到另一个项目
- 输入：
  - `mode`: `single | bundle`
  - `targetProjectId`
  - `sourceMessageId`：当 `mode=single`
  - `sourceMessageIds`：当 `mode=bundle`，且至少 2 条
- 当前行为：
  - `single` 会生成 `kind=forward_single` 的普通转发消息，并保留 `forwardSource`
  - `bundle` 会生成 `kind=forward_bundle` 的聊天记录卡片，并保留来源会话、消息数量、时间范围和摘要列表
  - 当前一次只允许选择一个目标会话
  - 当前会过滤源会话本身，避免把消息转发回当前会话
  - 当前目标既可以是单线程会话，也可以是群聊、`主 Agent` 或 `审计对话`
  - 非开发任务下如命中线程沟通限制，接口会预留 `approvalRequired / approvalReason` 返回

#### `POST /api/v1/projects/[projectId]/attachments`

- 用途：上传图片 / 视频 / 文件，并在当前会话写入附件消息
- 输入：
  - `file`
  - `sourceType`: `image | video | file`
- 当前行为：
  - 默认使用当前登录用户的附件存储配置，未配置时走 `server_file`
  - 用户切到 `oss + aliyun_oss` 后，会上传到阿里 OSS 私有桶，并在附件里固化 `storageSnapshot`
  - 图片 / PDF / 文本默认会生成 `queued_auto` 附件分析任务
  - 视频 / Office / 大文件默认标记为 `ready_manual`
- 返回：
  - `message`
  - `attachment`
  - `analysisTask`
  - `downloadUrl`

#### `POST /api/v1/projects/[projectId]/attachments/[attachmentId]/analyze`

- 用途：手动触发某个附件的主 Agent 分析
- 当前行为：
  - 仅允许对 `ready_manual` 或 `failed` 状态的附件重新发起
  - 返回新的 `attachment_analysis` 任务摘要

#### `GET /api/v1/attachments/[attachmentId]/download`

- 用途：受保护下载或预览附件
- 当前保护：
  - 默认要求有效 `boss_session`
  - 对主 Agent 附件分析任务，支持 `taskId + token` 的受控下载
- 当前行为：
  - `server_file` 会直接流式返回文件
  - `aliyun_oss` 会按附件上传时固化的 `storageSnapshot` 生成临时签名 URL 并跳转

#### `GET /api/v1/storage/config`

- 用途：读取当前登录用户的附件存储配置
- 返回：
  - `mode`: `server_file | oss`
  - `ossProvider`
  - 已脱敏的 OSS 配置摘要

#### `PATCH /api/v1/storage/config`

- 用途：更新当前登录用户的附件存储模式或 OSS 草稿配置
- 当前行为：
  - 默认模式为 `server_file`
  - 当前 OSS provider 仅支持 `aliyun_oss`

#### `POST /api/v1/storage/config/validate`

- 用途：校验并保存当前登录用户的阿里 OSS 配置
- 最小配置字段：
  - `accessKeyId`
  - `accessKeySecret`
  - `bucket`
  - `endpoint`
  - `region`
  - `prefix`（可选）
- 当前行为：
  - 只支持阿里 OSS 私有桶 + 签名 URL
  - 成功后会回写已脱敏配置和验证时间

#### `POST /api/v1/projects/[projectId]/goals`

- 用途：新增项目目标
- 输入：
  - `text`

#### `GET /api/v1/threads/[threadId]/context-budget`

- 用途：查看单线程预算、handoff 包和 alert

#### `POST /api/v1/workers/[workerId]/thread-context`

- 用途：worker / local-agent 上报线程上下文预算
- 输入：
  - `nodeId`
  - `projectId`
  - `taskId`
  - `threadId`
  - `title`
  - `summary`
  - `contextBudgetRemainingPct`
  - `contextBudgetLevel`
  - `mustFinishBeforeCompaction`
  - `checklist`
- 返回：
  - `accepted`
  - `next_required_report_in_seconds`
  - `master_actions`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话

#### `GET /api/v1/devices`

- 用途：读取设备列表、绑定草稿和可选设备工作区详情
- 当前行为：只返回生产链路设备，旧演示设备不会再进入正式设备视图

#### `GET /api/v1/devices/enrollments`

- 用途：读取设备绑定草稿

#### `POST /api/v1/devices/enrollments`

- 用途：生成 `pairing code + token` 形式的设备绑定草稿

#### `PATCH /api/v1/devices/[deviceId]`

- 用途：修改设备名称、头像、账号、状态、endpoint、备注和项目列表

#### `GET /api/v1/devices/[deviceId]/import-draft`

- 用途：读取某台设备最新的项目候选导入草稿
- 当前行为：
  - 返回最新 `deviceImportDraft`
  - 如果已经做过导入决议，还会一并返回最新 `deviceImportResolution`
  - 草稿里会带当前导入状态、推荐数量和最终已导入线程名，供 Web / Android 前台直接渲染状态卡
- 当前保护：
  - 仅 `highest_admin` 或设备所属账号可读

#### `POST /api/v1/devices/[deviceId]/import-draft/select`

- 用途：提交用户勾选的候选线程
- 输入：
  - `selectedCandidateIds[]`
- 当前行为：
  - 只接受当前导入草稿里真实存在的候选项
  - 提交后会把草稿推进到 `pending_resolution`
- 当前保护：
  - 仅 `highest_admin` 或设备所属账号可写

#### `POST /api/v1/devices/[deviceId]/import-draft/review`

- 用途：生成主 Agent 风格的设备导入决议
- 当前行为：
  - `review` 本身只负责落一条 `device_import_resolution` master task，并返回 queued/pending 状态
  - local-agent 会认领该任务，通过 `codex exec` 生成 JSON 决议，再由 `/api/v1/master-agent/tasks/[taskId]/complete` 写回 `deviceImportResolution`
  - Web 和 Android 前台会在 `pending_resolution` 阶段显示“主 Agent 审核中”，并自动刷新到 ready/applied 结果
  - 决议会区分 `create_thread_conversation | attach_existing | skip`
- 当前保护：
  - 仅 `highest_admin` 或设备所属账号可写

#### `POST /api/v1/devices/[deviceId]/import-draft/apply`

- 用途：应用导入决议，把选中的线程真正落成聊天窗口
- 当前行为：
  - `create_thread_conversation` 会生成新的单线程会话
  - `attach_existing` 会补充现有会话的设备 / 线程映射
  - 应用后草稿和决议都会变成 `applied`
  - 重复 apply 同一份 resolution 不会再重复创建线程会话
- 当前保护：
  - 仅 `highest_admin` 或设备所属账号可写
- 当前补充：
  - 已绑定的生产设备如果在 heartbeat 中携带真实 `projectCandidates[]`，服务端会自动完成 `select + review + apply`
  - 新设备仍保持人工勾选导入流程，不会被自动跳过

#### `GET /api/v1/devices/[deviceId]/skills`

- 用途：读取指定设备已经同步上来的 Skill 列表
- 返回：
  - `device`
  - `skills`

#### `POST /api/v1/devices/[deviceId]/skills`

- 用途：由 local-agent 覆盖式同步指定设备的 Skill 列表
- 输入：
  - `skills[].name`
  - `skills[].description`
  - `skills[].path`
  - `skills[].invocation`
  - `skills[].category`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话

#### `GET /api/v1/app-logs`

- 用途：分页查询 APP 日志
- 查询参数：
  - `limit`
  - `cursor`
  - `deviceId`
  - `projectId`
  - `level`
  - `category`
  - `source`
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/app-logs`

- 用途：接收 APP 端实时日志
- 输入：
  - `deviceId`
  - `projectId`
  - `level`
  - `category`
  - `message`
  - `detail`
  - `mirrorToMaster`
- 当前行为：
  - 追加到状态文件 `appLogs`
  - 可选镜像到主 Agent 项目消息账本
  - 触发 `app.logs.updated`
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话

#### `POST /api/v1/settings`

- 用途：更新“我的 > 设置”

#### `GET /api/v1/user/ota`

- 用途：读取当前版本、待升级 OTA、权限和 OTA 日志

#### `POST /api/v1/user/ota`

- 用途：检查更新或触发当前 OTA 升级并回写版本号
- 输入：
  - `action`: `check | apply`

#### `GET /api/v1/user/ota/package`

- 用途：下载当前已发布的最新 APK 安装包
- 当前来源：`public/downloads/boss-android-latest.apk`
- 当前归档：发布脚本还会额外保留 `public/downloads/boss-android-v{versionName}-{flavor}.apk`
- 当前保护：要求有效 `boss_session`

#### `GET /api/v1/ops/summary`

- 用途：读取运维 `fault / repair ticket / verification` 聚合数据

#### `POST /api/v1/ops/repair-tickets/[ticketId]/approve`

- 用途：主 Agent 批准修复工单

#### `POST /api/v1/ops/repair-tickets/[ticketId]/verify`

- 用途：运维审计复验修复工单

#### `GET /api/v1/audits/summary`

- 用途：读取 audit request / result / capability 聚合数据

#### `GET /api/v1/events`

- 用途：SSE 订阅会话、项目风险、设备、日志和 OTA 摘要事件
- 当前事件：
  - `conversation.context_indicator.updated`
  - `project.context_risk.updated`
  - `conversation.updated`
  - `project.messages.updated`
  - `app.logs.updated`
  - `devices.updated`
  - `devices.skills.updated`
  - `ota.updated`
  - `master_agent.task.updated`
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/tasks/claim`

- 用途：由 local-agent 认领分配给本机的主 Agent 任务
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话

#### `POST /api/v1/master-agent/tasks/[taskId]/complete`

- 用途：由 local-agent 回写主 Agent 任务完成结果
- 输入：
  - `deviceId`
  - `status`: `completed | failed`
  - `replyBody`
  - `errorMessage`
  - `requestId`
  - `dispatchExecutionId`
  - `targetProjectId`
  - `targetThreadId`
  - `rawThreadReply`
- 当前行为：
  - `completed` 时把真实主 Agent 回复写回 `master-agent` 项目消息账本
  - `taskType=conversation_reply` 时，会把目标 Codex 线程的原始回复写回普通单线程会话
  - `taskType=dispatch_execution` 时，会把线程原始结果镜像回群聊，再追加一条主 Agent 汇总，并更新对应执行单状态
  - `failed` 时写入 relay 失败消息，并更新 AI 账号健康状态
- 对群聊分发推荐失败的情况，消息入口当前会额外写入一条 `system_notice`，把“没有真实线程”或“成员引用失效”明确回显给用户
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话

#### `GET /api/v1/master-agent/prompt-policy`

- 用途：读取管理员全局主提示词
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/prompt-policy`

- 用途：管理员更新全局主提示词
- 输入：
  - `globalPrompt`
- 当前保护：要求 `highest_admin`

#### `GET /api/v1/master-agent/prompt`

- 用途：读取当前用户的主提示词
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/prompt`

- 用途：保存当前用户的主提示词；空内容会清空当前用户提示词
- 输入：
  - `content`
- 当前保护：要求有效 `boss_session`

#### `DELETE /api/v1/master-agent/prompt`

- 用途：清空当前用户的主提示词
- 当前保护：要求有效 `boss_session`

#### `GET /api/v1/master-agent/memories`

- 用途：读取当前用户的主 Agent 记忆
- 备注：当 `projectId=master-agent` 时，项目记忆会返回当前用户全部项目范围的记忆，而不是只返回 `master-agent` 本身
- 查询参数：
  - `includeArchived`
  - `scope`
  - `projectId`
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/memories`

- 用途：新增当前用户的主 Agent 记忆
- 输入：
  - `scope`
  - `projectId`
  - `title`
  - `content`
  - `memoryType`
  - `tags`
  - `sourceMessageId`
- 当前保护：要求有效 `boss_session`

#### `PATCH /api/v1/master-agent/memories/[memoryId]`

- 用途：更新当前用户的主 Agent 记忆
- 输入：
  - `scope`
  - `projectId`
  - `title`
  - `content`
  - `memoryType`
  - `tags`
  - `sourceMessageId`
  - `lastUsedAt`
- 当前保护：要求有效 `boss_session`

#### `DELETE /api/v1/master-agent/memories/[memoryId]`

- 用途：归档当前用户的主 Agent 记忆
- 当前保护：要求有效 `boss_session`

#### `GET /api/v1/master-agent/prompt-policy`

- 用途：读取管理员全局主提示词
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/prompt-policy`

- 用途：管理员更新全局主提示词
- 输入：
  - `globalPrompt`
- 当前保护：要求 `highest_admin`

#### `GET /api/v1/master-agent/prompt`

- 用途：读取当前用户的主提示词
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/prompt`

- 用途：保存当前用户的主提示词；空内容会清空当前用户提示词
- 输入：
  - `content`
- 当前保护：要求有效 `boss_session`

#### `DELETE /api/v1/master-agent/prompt`

- 用途：清空当前用户的主提示词
- 当前保护：要求有效 `boss_session`

#### `GET /api/v1/master-agent/memories`

- 用途：读取当前用户的主 Agent 记忆
- 查询参数：
  - `includeArchived`
  - `scope`
  - `projectId`
- 当前保护：要求有效 `boss_session`

#### `POST /api/v1/master-agent/memories`

- 用途：新增当前用户的主 Agent 记忆
- 输入：
  - `scope`
  - `projectId`
  - `title`
  - `content`
  - `memoryType`
  - `tags`
  - `sourceMessageId`
- 当前保护：要求有效 `boss_session`

#### `PATCH /api/v1/master-agent/memories/[memoryId]`

- 用途：更新当前用户的主 Agent 记忆
- 输入：
  - `scope`
  - `projectId`
  - `title`
  - `content`
  - `memoryType`
  - `tags`
  - `sourceMessageId`
  - `lastUsedAt`
- 当前保护：要求有效 `boss_session`

#### `DELETE /api/v1/master-agent/memories/[memoryId]`

- 用途：归档当前用户的主 Agent 记忆
- 当前保护：要求有效 `boss_session`

## 4. local-agent 接口

### 4.1 `GET /health`

- 用途：本地 agent 健康检查
- 输出：
  - `ok`
  - `service`
  - `runtime`

### 4.2 `GET /api/v1/device`

- 用途：读取本地 agent 配置和最近一次心跳结果

### 4.3 `GET /api/v1/skills`

- 用途：读取本机最近一次扫描到的 Skill 列表和同步状态

### 4.4 `POST /api/v1/heartbeat`

- 用途：手动触发一次心跳
- 当前行为：除了设备心跳，还会顺带触发 `thread-context` 上报和 Skill 同步
- 当前补充：
  - `local-agent` 会优先从 `~/.codex/state_5.sqlite / logs_1.sqlite / session_index.jsonl / .codex-global-state.json` 动态发现真实 Codex 线程，并把结果填进 `projects[] + projectCandidates[]`
  - 线程发现会优先保留每个 Codex 文件夹下的主工作线程；如果同文件夹中存在 `worker / explorer` 子线程，会优先过滤这些子线程，避免误导入过多聊天窗口
  - 如果某条线程在 Codex 本地状态库里的 `sandbox_policy.type=read-only`，`local-agent` 不会把它作为候选线程上报；这样可以避免历史只读线程再次被自动导入到会话首页
  - 对已绑定的生产设备，服务端会在 heartbeat 时自动应用建议导入项；对新设备则继续走 `deviceImportDraft` 的人工勾选与应用流程
  - 自动应用时，如果某些已导入线程已经不再出现在最新 `projectCandidates[]` 中，服务端会在同一轮 heartbeat 清理这些过时线程会话

### 4.5 主 Agent 轮询任务

- local-agent 会周期性请求 `POST /api/v1/master-agent/tasks/claim`
- 认领到任务后会执行本机 `codex exec`
- `conversation_reply` 当前会优先走 `codex exec resume <targetCodexThreadRef>`，把任务恢复到真实 Codex 线程；只有缺失真实线程引用时才退回 `--ephemeral`
- `dispatch_execution` 当前默认也走 `codex exec resume`，但当任务显式选择 `omx-team` 且本机 `omxEnabled + omxCommand/omxArgs` 可用时，会改走 `OMX Team Runtime` JSON 协议
- `codex exec resume` 前当前还会做目标线程绑定预检；若目标线程缺失、已归档、cwd 不匹配或为只读会话，会直接失败并返回标准化错误，不继续把任务派进错误线程
- 如果历史 `worker / explorer` 子线程需要转回可开发线程，除了数据库权限本身，还必须显式补发新的解锁指令覆盖其旧的“只读勘察 / 不改文件”上下文；否则前台看起来像可写，实际执行仍可能被旧上下文限制
- 执行完成后会调用 `POST /api/v1/master-agent/tasks/[taskId]/complete`
- 对群聊下发链路，认领到的 `dispatch_execution` 任务会带 `dispatchExecutionId / targetProjectId / targetThreadId`
- 对普通单线程聊天，认领到的 `conversation_reply` 任务会带 `targetProjectId / targetThreadId / targetCodexThreadRef`
- local-agent 回写完成时会同时带上 `rawThreadReply`，服务端据此把线程原始结果和主 Agent 汇总回写到群聊

## 5. 当前状态存储

当前没有正式数据库，真实数据来自：

- `data/boss-state.json`

关键对象：

- `user`
- `devices`
- `projects`
- `verificationCodes`
- `verificationDispatches`
- `authAccounts`
- `authSessions`
- `aiAccounts`
- `aiAccountSwitchHistory`
- `userAttachmentStorageConfigs`
- `threadContextSnapshots`
- `threadHandoffPackages`
- `threadContextAlerts`
- `deviceEnrollments`
- `deviceSkills`
- `appLogs`
- `masterAgentTasks`
- `dispatchPlans`
- `dispatchExecutions`
- `deviceImportDrafts`
- `deviceImportResolutions`
- `opsFaults`
- `opsRepairTickets`
- `opsRepairVerifications`
- `auditRequests`
- `auditResults`
- `capabilities`

## 6. 当前实现边界

当前这份清单只覆盖已经落地的接口，不覆盖设计文档里未来可能演进的能力。

不要误以为已经存在：

- 正式数据库
- 正式鉴权中间件
- 多家对象存储适配（当前只有服务器文件存储和阿里 OSS）
- 完整的附件详情页与富预览器
- 完整的多端用户会话系统与刷新令牌体系