# 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-admin-web

- 形态：独立 PC 企业后台前端
- 工程目录：`apps/boss-admin-web`
- 技术栈：`Vue 3 + Vite + Ant Design Vue`
- 本地开发脚本：`npm run admin:web:dev`
- 构建脚本：`npm run admin:web:build`
- 数据入口：`GET /api/v1/admin/backoffice`
- 登录态：复用 `boss_session` HttpOnly Cookie
- 当前定位：平台侧 To B 总后台，面向公司、账号、设备、项目、Skill、风险与审计治理；生产入口为 `https://admin.boss.hyzq.net/` 根路径，Caddy 内部 rewrite 到 `/admin-web/index.html`，旧 `/admin` UI 已移除，仅作为跳转到根域的兼容入口

### 1.3 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`
  - `AccessManagementActivity`
  - `SettingsActivity`
  - `StorageSettingsActivity`
  - `AiAccountsActivity`
  - `TelegramIntegrationActivity`
  - `OpenAiOnboardingActivity`
  - `OpsCenterActivity`
  - `AboutActivity`
- 当前项目聊天页：
  - `ProjectDetailActivity` 已改成聊天优先布局
  - 主面只保留 `项目目标 / 版本记录`
  - 右上角会进入微信式 `会话信息 / 群资料`
  - `approval_required` 群聊的待确认推荐会直接显示在主消息流里，支持 `确认下发 / 拒绝`
  - 脏群会在主消息流上方直接显示 `去修复` 入口，并跳转到 `GroupInfoActivity`
  - 单线程会话支持按微信最新逻辑改线程名
  - 当前已经支持从单线程会话发起独立群聊，群聊创建后作为新会话保留，原会话不升级
  - 当前单线程会话已经支持打开 `线程状态` 只读页，查看主 Agent 当前掌握的线程状态文档和最近进展事件
  - 当前已经支持微信式消息转发：长按消息可直接 `转发 / 多选 / 复制 / 删除`，其中删除会调用服务端账本删除接口并刷新会话预览
  - 当前多选模式会切换成微信式 `取消 + 已选数量 + 底部转发` 状态
  - 当前统一使用 `ForwardTargetActivity` 选择目标会话，替换旧的备注转发主链
  - 当前已支持聊天附件主链：输入框左侧 `+` 会打开底部抽屉，支持图片 / 视频 / 文件发送；图片 / 视频先确认，文件直接发送
  - 当前附件消息支持下载、原生打开、手动分析和自动分析状态展示
  - 当前线程聊天消息会按该线程绑定的 Codex 电脑显示来源头像：单线程会话使用项目绑定设备头像，多设备 / 群聊消息会优先根据发送人里的设备名匹配对应电脑头像；主 Agent 总入口自身仍保留主 Agent 对话样式
  - 当前已支持 `execution_progress` 执行进度卡：普通线程对话、主 Agent 托管线程和群聊目标线程执行时，会在对应聊天窗口显示“进度 / 线程状态 / 实时状态 / 线程配置 / 线程协作 / 工具活动 / 思考摘要 / 账号状态 / 运行状态 / 安全提醒 / 审批状态 / 文件变更 / 分支详情 / 生成结果 / 后台智能体”结构化卡片；运行状态里也会展示 Codex Windows 沙箱准备摘要；线程过程噪音仍走 `thread_process` 折叠
  - `线程详情 / 运维调试` 仍保留对应原生活动页，但已退出主聊天面
  - 当前已补上本地发送中气泡、发送按钮状态控制，以及“只有接近底部才自动滚到底”的消息流行为
- 当前根页导航：
  - `MainActivity` 会记住最近一次停留的 `会话 / 设备 / 我的` tab
  - 根页返回逻辑已改成“先回会话 tab，再按一次返回进入后台”
- 当前设备详情页：
  - `DeviceDetailActivity` 已同步展示 Codex App Server 连接态、模型、扩展、治理、账号、线程、轮次、线程操作、线程协作口径和协议漂移摘要；线程协作固定表达为 Boss Broker 受控协作，协议漂移只显示兼容/告警、失败探针数量、文档跟进数量和 Boss Broker 兜底，不渲染错误原文、线程 ID、用户正文或内部 prompt
- 当前会话列表：
  - 已切到“线程 = 会话窗口”
  - 主标题显示线程名
  - 第二行显示所属文件夹名
  - 右下角显示后台活跃数量动态图标
  - `主 Agent / 审计对话` 已作为普通置顶会话固定在顶部
  - 会话首页右上角当前为微信式 `+` 入口，可直接从会话列表发起独立群聊
- 当前 `关于` 页：
  - 保留版本与 OTA 操作
  - 当前已补上 OTA 下载进度、失败重试、安装授权提示和返回关于页后的本地状态恢复
- 当前 `我的` 根页：
  - 已按登录角色过滤入口：`member` 只显示 `账号与安全 / 设置 / 技能 / 关于`
  - `admin / highest_admin` 额外显示 `运维与修复 / AI 账号 / 附件与存储 / Telegram 接入`
  - `用户与权限` 仅 `highest_admin` 可见，用于创建子账号和分配设备 / 项目 / Skill 权限
  - `运维与修复` 直接进入 `OpsCenterActivity`
  - `技能` 入口会继续依赖服务端 Skill 授权过滤，不在客户端自行扩大可见范围
- 当前 `OpenAiOnboardingActivity`：
  - 会先自动打开 `OpenAI Platform` 登录页
  - 支持继续打开 `API Keys` 页面
  - 回 APP 后可直接粘贴 key，并设为当前主控
  - 登录成功后会直接给出 `测试主 Agent 对话` 入口
- 当前登录：默认要求账号密码或验证码校验；临时开发兜底只允许通过显式环境变量开启
- 当前会话恢复：`SharedPreferences` 中保存 `boss_session / restore_token / account`

### 1.4 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 协议
- 当前 Codex 任务完成回写会附带 `executionProgress` 快照：包含 Git diff 简表、GitHub CLI 可用状态和从执行回复中提取的产物文件名，服务端更新同一张 `execution_progress` 卡片，不重复刷屏
- 当前 `RemoteRuntimeAdapter` 还负责拦截固定模式的线程内部环境提示；命中后会直接改写成失败，避免把只读/cwd 这类脏文本写进聊天记录
- 当前普通单线程 `conversation_reply` 在真正执行 `codex exec resume` 前，会先把 Boss 用户消息镜像进目标 Codex Desktop rollout；定位优先走 `state_5.sqlite`，不可用时回退扫描 `~/.codex/sessions`，并按 `sourceMessageId` 去重
- 当前 Codex Desktop 同步新增常驻刷新桥：`scripts/codex-desktop-refresh-bridge-daemon.mjs` 通过 launchd 监听 `127.0.0.1:4318`，暴露 `POST /api/v1/codex-desktop/refresh`、`GET /api/v1/codex-desktop/events`、`GET /api/v1/codex-desktop/events/recent` 和 `GET /api/v1/codex-desktop/capabilities`；`local-agent` 会优先调用 refresh endpoint，失败时回退到 `scripts/codex-desktop-refresh-hint.mjs` 命令式刷新。SSE 事件只包含线程引用、消息 ID、状态、deep link 等安全元数据，不包含用户正文或内部 prompt；`scripts/codex-desktop-event-consumer.mjs` 可作为 Desktop 插件/IPC 接入前的订阅 smoke；`scripts/codex-desktop-integration-probe.mjs` 负责只读探测 Codex.app 能力
- 当前新增 Codex App Server runner：`local-agent/codex-app-server-runner.mjs`。boss-agent 默认配置 `codexAppServerEnabled=true`，会接管 `conversation_reply / dispatch_execution`；它默认通过 stdio 启动 `codex app-server`，也支持 `codexAppServerTransport=ws + codexAppServerUrl=ws://127.0.0.1:<port>` 或 `codexAppServerTransport=unix + codexAppServerUrl=unix:///absolute/path.sock` 连接同机长驻 App Server，bearer token 可通过 `codexAppServerAuthTokenFile` 读取并在握手时发送 `Authorization: Bearer <token>`。runner 执行 `initialize -> thread/resume|thread/start -> turn/start|turn/steer`，并把 `item/agentMessage/delta` 或 `item/completed` 归一成 Boss 任务回复；当 App Server 对单个 JSON-RPC 请求返回 `-32001 / retry later` 时，runner 会做最多 3 次指数退避重试。turn 启动前失败可回退 CLI，turn 启动后失败不回退，避免重复执行。boss-agent 本机状态页另新增 `Codex Remote Control` 摘要：读取 `codexRemoteControlEnabled / codexRemoteControlCommand / codexRemoteControlArgs`，默认展示 `codex remote-control start --json` 作为官方 daemon 远控入口；状态页只展示能力，不因刷新自动启动 daemon。2026-05-31 起，runner 会把 `turn/plan/updated`、`turn/diff/updated`、`item/started|completed`、`thread/started` 归一成 `executionProgress.steps / branch / artifacts / agents`，把 `item/*/requestApproval`、`item/autoApprovalReview/*`、`guardianWarning`、`serverRequest/resolved`、`item/fileChange/patchUpdated` 归一成 `executionProgress.approvals / warnings / fileChanges`，把 `thread/status/changed`、`thread/realtime/started|transcript|outputAudio|itemAdded|error|closed` 归一成 `executionProgress.threadStatus / realtime`，把 `model/rerouted`、`thread/tokenUsage/updated`、`mcpServer/startupStatus/updated`、`remoteControl/status/changed` 归一成 `executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl`，并把 `thread/goal/*`、`thread/settings/updated`、`thread/compacted`、`account/updated`、`account/rateLimits/updated`、`model/verification`、`warning`、`configWarning`、`deprecationNotice`、`ThreadItem.collabToolCall`、`ThreadItem.contextCompaction`、`mcpToolCall`、`dynamicToolCall`、`webSearch`、`imageView`、`imageGeneration`、`hook/started|completed`、`windowsSandbox/setupCompleted`、`enteredReviewMode`、`exitedReviewMode`、`commandExecution`、`ThreadItem.plan`、`ThreadItem.reasoning.summary` 归一成线程配置、账号状态、模型校验、安全提醒、线程协作、上下文压缩、工具活动、图片产物、钩子生命周期、Windows 沙箱准备状态、计划步骤和思考摘要；新版 `ThreadItem.collabToolCall.receiverThreadIds / agentsStates` 只归一为目标数量和 agent 状态集合。2026-06-03 起，runner 还会把 `item/agentMessage/delta`、`item/plan/delta`、`item/reasoning/summaryPartAdded|summaryTextDelta|textDelta`、`item/mcpToolCall/progress`、`command/exec/outputDelta`、`item/commandExecution/outputDelta|terminalInteraction` 和 `item/fileChange/outputDelta` 归一成 `executionProgress.streamEvents` 计数。服务端 complete/progress 回写会与本地 Git/GitHub 进度合并，且不保存 SDP、音频 base64、raw realtime item、remote installationId、cwd、turnId、配置路径、collab 源/目标线程 ID、receiverThreadIds、collab prompt、agentsStates 私有消息、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning content、reasoning item id、原始 delta、terminal input、file output、imageGeneration revisedPrompt/result、hook sourcePath/statusMessage/entries、Windows sandbox sourcePath/samplePaths/本地绝对路径或未清洗的 MCP 错误。heartbeat 同时支持按 TTL 拉取 `model/list / skills/list / hooks/list / plugin/list / app/list / modelProvider/capabilities/read`，并把摘要保存在 `capabilities.codexAppServer.metadata`。
- App Server heartbeat discovery 现在还会按 TTL 拉取 `experimentalFeature/list / collaborationMode/list / permissionProfile/list / mcpServerStatus/list`，写入 `capabilities.codexAppServer.metadata.experimentalFeatures / collaborationModes / permissionProfiles / mcpServers`。这些字段用于 APP/后台治理页展示 Codex 当前可用的实验特性、多 Agent/协作模式、权限 profile 和 MCP 服务健康；MCP 请求固定使用 `detail=toolsAndAuthOnly`，服务端状态里不保存 resource URI、工具参数、permission profile 文件规则、本地路径或密钥。
- App Server heartbeat discovery 现在还会按 TTL 拉取 `account/read / account/rateLimits/read / config/read / configRequirements/read / externalAgentConfig/detect`，写入 `capabilities.codexAppServer.metadata.accountSummary / rateLimitSummary / appConfigSummary / configRequirements / externalAgentMigration`。这些字段用于 APP/后台展示账号、额度、App 配置、企业托管要求和外部 Agent 迁移候选摘要；当前只做观测，不通过 Boss 远程写 `config.toml` 或执行外部 Agent 导入，且不保存邮箱、完整 config、API key、本地路径或迁移描述。
- App Server heartbeat discovery 现在还会按 TTL 拉取 `thread/list / thread/loaded/list`，写入 `capabilities.codexAppServer.metadata.threadSummary`。该字段用于 APP/后台展示 Codex 当前可见线程数量、加载态、活跃态和非归档线程轻量目录；目录只保留 `id / name / sourceKind / status / updatedAt / loaded`，不保存 cwd、本地路径、turn 内容、用户正文或内部 prompt。
- App Server heartbeat discovery 现在还会按 TTL 对非归档可见线程拉取 `thread/turns/list`，写入 `capabilities.codexAppServer.metadata.threadTurnSummary`。该字段用于 APP/后台展示 Codex 当前线程 turn 运行态；请求固定 `itemsView=summary`，只保留 turn 计数、运行中 / 完成计数、最近状态、更新时间和最终 `agentMessage` 安全摘要，不保存用户正文、reasoning 原文、命令输出、原始 items、内部 prompt 或系统提示词。
- App Server heartbeat discovery 现在还会把最终 `agentMessage` 安全摘要合并进 `projectCandidates.recentAssistantMessages`。服务端根据 `codexThreadRef` 将 Codex Desktop 自己产生的新回复反向同步到 Boss APP 对应会话、preview、lastMessageAt 和未读数；已有本地扫描候选的 folder/thread 映射优先，App Server 只补充最新回复摘要。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.threadActionSummary`。该字段用于 APP/后台展示当前协议下可接入的线程治理动作数量和分组，覆盖 archive / unarchive / fork / compact / rollback / rename / metadata / steer / interrupt / shell / unsubscribe；它只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用这些写操作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.threadCollaborationSummary`。该字段用于 APP/后台展示 Boss Broker、协作事件 handler、协作模式数量和“非原生私聊”边界；当前本机 `codex-cli 0.136.0-alpha.2` schema 未声明 `ThreadItem.collabToolCall`，所以线程协作继续走 Boss 服务端 `thread-collaboration` 入口和受控 App Server 注入/执行链路。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.protocolDriftSummary`。该字段用于 APP/后台展示协议漂移状态，包含 `driftLevel`、`failedProbeCount`、`runtimeFailureMethods`、`docFollowupItems` 和 `fallbackStrategy`；其中 `runtimeFailureMethods` 只保留 method 名，不保存错误原文、线程 ID、用户正文或内部 prompt。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.pluginGovernanceSummary`。该字段用于 APP/后台展示当前协议下可接入的插件治理动作数量和分组，覆盖 install / uninstall / read / skill-read / share；它只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用插件安装、卸载或共享写操作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.accountGovernanceSummary / configGovernanceSummary`。这些字段用于 APP/后台展示当前协议下可接入的账号与配置治理动作数量和分组，覆盖 login / logout / token refresh / add credits nudge / config write / MCP reload / Skill config write；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用账号或配置写操作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.fileSystemGovernanceSummary / commandSessionSummary`。这些字段用于 APP/后台展示当前协议下可接入的文件系统与命令会话动作数量和分组，覆盖 file read/write/remove/watch 以及 command stdin / resize / terminate / stream；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用文件读写或命令控制操作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.externalAgentGovernanceSummary / marketplaceGovernanceSummary / experimentalFeatureGovernanceSummary`。这些字段用于 APP/后台展示当前协议下可接入的外部 Agent 迁移、Marketplace 和实验特性治理动作数量和分组，覆盖 external-agent import、marketplace add/remove/upgrade 和 experimental feature enablement；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用迁移导入、marketplace 写入或实验特性启用操作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.reviewGovernanceSummary / windowsSandboxGovernanceSummary / fuzzyFileSearchSummary`。这些字段用于 APP/后台展示当前协议下可接入的审查、Windows 沙箱和文件搜索事件能力，覆盖 review start、Windows sandbox readiness/setup 和 fuzzy file search updated/completed；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用审查启动、沙箱设置或文件搜索动作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.mcpGovernanceSummary / userInteractionGovernanceSummary / guardianGovernanceSummary`。这些字段用于 APP/后台展示当前协议下可接入的 MCP、用户交互和 Guardian 治理能力，覆盖 MCP OAuth/resource/tool/elicitation、tool requestUserInput、Guardian denied action approval 和 permission request approval；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中调用 MCP、用户输入或 Guardian 放行动作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.runtimeEventSummary / extensionEventSummary / threadLifecycleEventSummary`。这些字段用于 APP/后台展示当前协议下可接入的运行事件、扩展事件和线程生命周期事件能力，覆盖 process output/exited、raw response completed、skills changed、plugin installed、thread started/closed/archived/unarchived/name updated；它们只来自 runner 安全 catalog 和协议快照，不会在 heartbeat 中主动触发进程、插件、Skill 或线程生命周期动作。
- App Server heartbeat discovery 现在还会写入 `capabilities.codexAppServer.metadata.streamDeltaEventSummary`。该字段用于 APP/后台展示当前协议下可接入的流式增量事件能力，覆盖 agent delta、plan delta、reasoning delta、MCP progress、command output、terminal interaction 和 file output；它只来自 runner 安全 catalog 和协议快照，不保存原始增量文本、命令输出、推理正文或文件输出。
- App Server heartbeat discovery 现在支持 `skills/extraRoots/set`：配置 `codexAppServerSkillExtraRoots` 或环境变量 `BOSS_CODEX_APP_SERVER_SKILL_EXTRA_ROOTS` 后，runner 会先把共享 Skill 根下发给 App Server，再刷新 `skills/list`，并写入 `capabilities.codexAppServer.metadata.skillExtraRootsSummary`。该字段用于 APP/后台展示企业共享 Skill 根是否已下发；只保留数量、basename 和状态，不保存根目录绝对路径、Skill 文件路径或配置原文。
- App Server heartbeat discovery 现在支持 `hooks/list`，写入 `capabilities.codexAppServer.metadata.hookSummary`。该字段用于 APP/后台展示本机 Codex hook 治理状态；只保留 workspace 数、hook 数、启用数、受管 / 可信 / 修改 / 未信任计数、warning / error 计数和事件 / handler 类型，不保存 hook key、command、sourcePath、statusMessage、hash、error message 或本地路径。
- 当前 Codex App Server runner 已新增第一版 Boss Inter-Thread Broker：任务携带 `intentCategory=thread_collaboration`、`sourceCodexThreadRef` 和 `targetCodexThreadRef` 时，会先 `thread/read` 源线程，再通过 `thread/inject_items` 向目标线程注入受控摘要，最后 `turn/start` 目标线程；服务端入口是 `POST /api/v1/projects/[projectId]/thread-collaboration`，负责权限、源/目标线程校验和任务排队。这不是假设官方线程 P2P，而是 Boss 自己做线程协作编排。
- 当前 Codex App Server runner 已新增 Boss 用户消息镜像：普通 `conversation_reply` 任务携带 `mirrorBossUserMessageToCodexDesktop=true`、`sourceMessageBody` 和目标 `codexThreadRef` 时，会先 `thread/resume`，再 `thread/inject_items` 写入 `role=user` 的 Boss APP 用户原文，最后 `turn/start`；该链路用于让 APP 发起的对话进入 Codex Desktop 同一线程历史。执行结果只保存 `threadHistorySync` 安全摘要，不保存 App Server 原始 item、消息 ID、用户原文、系统提示词或内部调度字段。
- 当前 Codex App Server runner 已新增受控线程回滚：任务携带 `intentCategory=thread_rollback`、目标 `codexThreadRef` 和 `rollbackNumTurns` 时，会调用 `thread/rollback` 回滚目标线程最近 N 轮，不会启动新 turn，也不会把 App Server 返回的 thread/turn/items 写回 APP。服务端入口是 `POST /api/v1/projects/[projectId]/thread-rollback`，只保存回滚轮数、原因和执行摘要；边界是只回滚 Codex 线程历史，不自动还原本地文件变更。
- 当前 Codex App Server runner 已新增受控线程压缩：任务携带 `intentCategory=thread_compact` 和目标 `codexThreadRef` 时，会调用 `thread/compact/start` 发起上下文压缩，不会启动普通 turn，也不会把 contextCompaction item 的原始字段写回 APP。服务端入口是 `POST /api/v1/projects/[projectId]/thread-compact`，只保存压缩原因和执行摘要；边界是只压缩 Codex 线程上下文，不代表代码修改、文件恢复或版本发布完成。
- 当前 Codex App Server runner 已新增受控线程归档 / 恢复：任务携带 `intentCategory=thread_archive|thread_unarchive`、目标 `codexThreadRef` 和 `threadLifecycleAction` 时，会直接调用 `thread/archive` 或 `thread/unarchive`，不会先 resume 已归档线程，也不会启动普通 turn。服务端入口是 `POST /api/v1/projects/[projectId]/thread-archive`，只保存生命周期动作、原因和执行摘要；边界是只改变 Codex 线程生命周期状态，不代表代码修改、文件恢复或版本发布完成。
- 当前 Codex App Server runner 已新增受控线程改名：任务携带 `intentCategory=thread_rename`、目标 `codexThreadRef` 和 `threadRenameName` 时，会直接调用 `thread/name/set`，不会先 resume 线程，也不会启动普通 turn。服务端入口复用 `POST /api/v1/projects/[projectId]/rename` 的 `mode=thread` 分支；本地 Boss 会话改名先成功，随后异步创建 Codex 改名任务，设备离线或冲突只返回非致命 `codexThreadRenameError`。
- 当前 Codex App Server runner 已新增受控线程目标同步：任务携带 `intentCategory=thread_goal_sync`、目标 `codexThreadRef`、`threadGoalObjective` 和 `threadGoalStatus` 时，会直接调用 `thread/goal/set`，不会启动普通 turn。服务端入口复用 `POST /api/v1/projects/[projectId]/goals`；本地 Boss 项目目标先成功，单线程且已绑定 Codex 线程时再异步创建 Codex goal 同步任务，设备离线或冲突只返回非致命 `codexThreadGoalError`。
- 当前 Codex App Server runner 已新增受控线程 Git 元数据同步：任务携带 `intentCategory=thread_metadata_sync`、目标 `codexThreadRef` 和 `threadMetadataGitInfo` 时，会直接调用 `thread/metadata/update`，不会启动普通 turn。服务端入口是 `POST /api/v1/projects/[projectId]/thread-metadata`；当前只允许 patch `gitInfo.sha / branch / originUrl`，不开放任意 metadata 写入。
- 当前 Codex App Server runner 已新增受控线程分叉：任务携带 `intentCategory=thread_fork`、目标 `codexThreadRef` 和 `threadForkEphemeral` 时，会直接调用 `thread/fork`，不会启动普通 turn。服务端入口是 `POST /api/v1/projects/[projectId]/thread-fork`；当前只使用源 thread id 分叉，不允许远程覆盖 model、sandbox、instructions 或 config，新 Codex 线程进入 Boss 会话列表仍依赖后续 discovery / 导入链路。
- 当前 boss-agent Mac OTA 已接入：`local-agent/boss-agent-ota-runner.mjs` 会用设备 token 调 Boss 服务端 `/api/v1/boss-agent/ota` 检查最新 Mac 运行包，`/api/v1/boss-agent/ota/apply` 会下载 `boss-agent-mac-latest.zip`、校验 sha256、暂存安装 wrapper，并拉起本机安装器；安装脚本会保留绑定配置并只更新版本号与本机 runtime 路径。安装器会优先沿用当前 LaunchAgent active config，并保留所有 `config*.json`，避免多电脑场景中误绑定到默认设备配置。当前最新验证包为 `20260516221619`；构建脚本支持 `BOSS_AGENT_NOTARIZE=1` 的 Developer ID 公证路径。
- 当前 `local-agent` 还新增了两条统一电脑控制 runtime：
  - `local-agent/browser-control-task-runner.mjs`
  - `local-agent/computer-use-task-runner.mjs`
- 当前 `browser_control / desktop_control` 任务已经可以被 `local-agent/server.mjs` 识别并分流；当本机配置了对应 runtime 命令时，会通过 JSON stdin/stdout 协议委托给外部进程执行，否则返回明确 runtime disabled 错误，不再回退占位成功结果
- 当前 `browser_control / desktop_control` 的完成回写已贯通 `targetUrl / targetApp -> RemoteRuntimeAdapter -> /api/v1/master-agent/tasks/[taskId]/complete -> boss-state.json`，服务端写入 `control_summary` 消息时会保留 `controlTarget`，Android 会话页可直接渲染“目标：URL/应用名”
- 相关配置项：
  - `browserControlEnabled / browserControlCommand / browserControlArgs / browserControlWorkdir / browserControlTimeoutMs`
  - `computerUseEnabled / computerUseCommand / computerUseArgs / computerUseWorkdir / computerUseTimeoutMs`
  - `codexComputerUseEnabled / codexComputerUseCommand / codexComputerUseArgs / codexComputerUseWorkdir / codexComputerUseTimeoutMs / codexComputerUseFallbackToCua`
  - `codexAppServerEnabled / codexAppServerCommand / codexAppServerArgs / codexAppServerWorkdir / codexAppServerTimeoutMs / codexAppServerFallbackToCli / codexAppServerTransport / codexAppServerUrl / codexAppServerAuthTokenFile / codexAppServerSkillExtraRoots / codexAppServerDiscoveryEnabled / codexAppServerDiscoveryTtlMs / codexAppServerDiscoveryLimit`
  - `codexRemoteControlEnabled / codexRemoteControlCommand / codexRemoteControlArgs`
  - `scripts/codex-app-server-protocol-snapshot.mjs`：生成本机 Codex App Server help、JSON Schema、TypeScript bindings、协议方法清单和 support matrix；当前快照目录为 `docs/protocol-snapshots/codex-app-server/0.136.0-alpha.2/`

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

- 用途：设备端在执行中实时刷新同一张 `execution_progress` 卡
- 权限：设备 token / 设备写鉴权
- 请求体：`deviceId`、可选 `status=queued|running`、可选 `requestId`、可选 `executionProgress`
- 当前行为：只更新任务进度卡和实时事件，不把任务置为 completed / failed；最终成功或失败仍必须走 `POST /api/v1/master-agent/tasks/[taskId]/complete`

#### `POST /api/v1/projects/[projectId]/thread-collaboration`

- 用途：从当前线程发起一次受控线程协作，把源线程上下文注入目标 Codex 线程并让目标线程执行
- 权限：登录态；源项目和目标项目都需要 `project.view`，源项目需要 `master_agent.ask`
- 请求体：`targetProjectId`、`body` 或 `requestText`
- 行为：先在源项目追加用户消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_collaboration`、源/目标 `threadId`、`codexThreadRef` 和目标 `codexFolderRef`

#### `POST /api/v1/projects/[projectId]/thread-rollback`

- 用途：对当前会话绑定的 Codex 线程发起一次受控历史回滚，适合误触发、错误继续、接管误操作后的线程级撤回
- 权限：登录态；目标项目需要 `project.view` 和 `master_agent.ask`
- 请求体：`numTurns`，可选 `reason`
- 行为：先在目标项目追加一条用户可见原因消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_rollback`、目标 `threadId`、`codexThreadRef`、`codexFolderRef`、`rollbackNumTurns` 和 `rollbackReason`
- 边界：设备端通过 Codex App Server 调用 `thread/rollback`，只回滚线程历史；不会自动还原本地文件变更，也不会把 App Server 返回的 thread/turn/items 明文写回 APP

#### `POST /api/v1/projects/[projectId]/thread-compact`

- 用途：对当前会话绑定的 Codex 线程发起一次受控上下文压缩，适合长线程接近上下文上限、继续开发前需要清理上下文的场景
- 权限：登录态；目标项目需要 `project.view` 和 `master_agent.ask`
- 请求体：可选 `reason`
- 行为：先在目标项目追加一条用户可见原因消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_compact`、目标 `threadId`、`codexThreadRef`、`codexFolderRef` 和 `compactReason`
- 边界：设备端通过 Codex App Server 调用 `thread/compact/start`，只发起上下文压缩；不会启动普通 turn，不会把 contextCompaction item 的原始字段写回 APP，也不代表代码修改、文件恢复或版本发布完成

#### `POST /api/v1/projects/[projectId]/thread-archive`

- 用途：对当前会话绑定的 Codex 线程发起受控归档或恢复，适合项目阶段性结束、误归档恢复或清理会话首页前先同步 Codex 线程生命周期
- 权限：登录态；目标项目需要 `project.view` 和 `master_agent.ask`
- 请求体：`action=archive|unarchive`，可选 `reason`
- 行为：先在目标项目追加一条用户可见原因消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_archive|thread_unarchive`、目标 `threadId`、`codexThreadRef`、`codexFolderRef`、`threadLifecycleAction` 和 `threadLifecycleReason`
- 边界：设备端通过 Codex App Server 调用 `thread/archive` 或 `thread/unarchive`；不会启动普通 turn，不会把 App Server 返回的 thread 原始字段写回 APP，也不代表代码修改、文件恢复或版本发布完成

#### `POST /api/v1/projects/[projectId]/thread-metadata`

- 用途：对当前会话绑定的 Codex 线程发起受控 Git 元数据同步，适合把 Boss 当前已知的分支、提交和远端仓库信息写回 Codex 线程
- 权限：登录态；目标项目需要 `project.view` 和 `master_agent.ask`
- 请求体：`gitInfo`，可选字段 `sha`、`branch`、`originUrl`；字段值为字符串表示设置，为 `null` 表示清除，字段缺省表示不改；可选 `reason`
- 行为：先在目标项目追加一条用户可见原因消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_metadata_sync`、目标 `threadId`、`codexThreadRef`、`codexFolderRef`、`threadMetadataGitInfo` 和 `threadMetadataReason`
- 边界：设备端通过 Codex App Server 调用 `thread/metadata/update`；不会启动普通 turn，不会把 App Server 返回的 thread 原始字段写回 APP，也不允许写入 Git 信息之外的任意 metadata

#### `POST /api/v1/projects/[projectId]/thread-fork`

- 用途：对当前会话绑定的 Codex 线程发起受控分叉，适合在不破坏原线程历史的情况下复制当前上下文继续试验
- 权限：登录态；目标项目需要 `project.view` 和 `master_agent.ask`
- 请求体：可选 `reason`，可选 `ephemeral`
- 行为：先在目标项目追加一条用户可见原因消息，再创建 `conversation_reply` 任务，任务携带 `intentCategory=thread_fork`、目标 `threadId`、`codexThreadRef`、`codexFolderRef`、`threadForkEphemeral` 和 `threadForkReason`
- 边界：设备端通过 Codex App Server 调用 `thread/fork`；不会启动普通 turn，不会把 App Server 返回的 path、cwd、turns、instructions 写回 APP；当前不允许远程覆盖 model、sandbox、instructions 或 config；新线程进入 Boss 会话列表依赖后续 thread discovery / 导入链路

- 当前仓库已自带 browser smoke runtime、desktop Cua runtime 和旧 desktop smoke 兜底：
  - `scripts/browser-control-smoke.mjs`
  - `scripts/codex-computer-use-runtime.mjs`
  - `scripts/cua-driver-computer-use-runtime.mjs`
  - `scripts/computer-use-smoke.mjs`
- `scripts/browser-control-smoke.mjs` 当前已支持两段式最小真实动作：
  - 能从目标 URL 拉取 HTML 标题并回写到 `replyBody / executionSummary`
  - 在显式配置 opener 命令时可实际执行打开 URL
- `scripts/codex-computer-use-runtime.mjs` 当前通过 `codex app-server` 发起 Codex Computer Use 桌面控制，是 boss-agent 的默认桌面控制入口；失败时由 `local-agent/computer-use-task-runner.mjs` 自动回退 CUA
- `scripts/cua-driver-computer-use-runtime.mjs` 当前通过外部 `cua-driver` 执行 macOS 桌面 GUI 控制：先 `launch_app`，再按返回窗口做 `get_window_state`，需要写入文本时调用 `type_text` 并再次观测；发送、提交、删除、支付等高风险动作默认返回 `needs_user_action`，不静默下发
- `scripts/computer-use-smoke.mjs` 当前已支持识别常见桌面应用名，macOS 下默认用 `osascript` 激活目标应用，并支持把用户请求中的引号文本输入到当前前台应用、按需回车发送；它保留为旧兜底和回归资产
- `config.example.json / config.cloud.json` 现默认把 browser smoke runtime 和 desktop Cua runtime 作为 browser/desktop 控制的推荐起步配置
- `config.example.json / config.cloud.json` 现同时默认把 `browserAutomationConnected / computerUseConnected` 置为 `true`，让前台设备详情默认按“这台 Mac 已具备浏览器控制 / 桌面控制能力”展示
- 这两条 smoke runtime 当前还会返回结构化字段：
  - browser：`targetUrl / artifacts`
  - desktop：`targetApp / typedText / artifacts`
- 这样前台与后续真实 runtime 可以共用同一套结果形态，而不需要等接入 Playwright / Computer Use 后再改返回协议
- heartbeat 的 `browserAutomation / computerUse` 能力上报会同时参考静态 connected 标记和 runtime 配置状态；`codexAppServer` 能力上报会参考 feature flag，stdio 模式校验 app-server 命令可执行性，ws/unix 模式校验 `codexAppServerUrl` 是否已配置

### 1.5 Caddy

- 作用：反向代理和 HTTPS 自动续签
- 服务器服务名：`caddy.service`
- 配置文件：`deployment/Caddyfile`
- 当前站点：`boss.hyzq.net` 服务客户 Web / App API；`admin.boss.hyzq.net` 根路径内部 rewrite 到 `/admin-web/index.html`，浏览器地址栏保持 `https://admin.boss.hyzq.net/`，作为平台级 To B 独立后台入口；旧 `/admin` 页面不再渲染旧 UI，只做兼容跳转到根路径

### 1.6 boss-server-debug skill

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

### 1.7 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/access`
- `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`

- 用途：读取当前完整状态
- 当前行为：最高管理员可读取完整状态；非最高管理员会返回已按当前账号授权裁剪后的状态快照，设备、项目、线程状态、进展事件、Skill、日志和任务都会尽量限制在可见范围内
- 注意：这是内部 MVP 调试接口，仍不建议作为普通业务页面的主数据源；业务页面应优先使用具体 `/api/v1/*` 投影接口

### 3.1.1 多用户 RBAC 与 Skill 授权

- 权限模块：`src/lib/boss-permissions.ts`
- 状态字段：
  - `accountDeviceGrants`
  - `accountProjectGrants`
  - `accountSkillGrants`
  - `skillCatalog`
  - `permissionAuditLogs`
- 当前规则：
  - `highest_admin` 全局可见
  - 非管理员必须通过设备、项目或 Skill 授权获得可见性
  - `device.view` 只提供设备与关联项目只读可见性，不自动放大为聊天、接管、电脑控制或 Skill 使用权限
  - `thread.chat / master_agent.ask / master_agent.takeover / computer.control / skill.use` 需要显式授权
- 当前已接入过滤的接口：
  - `GET/POST /api/v1/admin/access`（仅最高管理员）
  - `GET /api/v1/devices`
  - `GET /api/v1/conversations`
  - `GET /api/v1/conversations/home`
  - `GET /api/v1/conversation-folders/[folderKey]`
  - `GET /api/v1/projects/[projectId]`
  - `GET/POST /api/v1/projects/[projectId]/messages`
  - `GET /api/v1/devices/[deviceId]/skills`
  - `GET /api/state`
- 当前主 Agent 行为：执行提示词使用授权快照生成，任务队列会记录 `authorizedDeviceIds / authorizedProjectIds / authorizedSkillIds / requiredPermissions`
- 当前前台入口：Web `/me/access` 与原生 Android `AccessManagementActivity` 共用 `/api/v1/admin/access`，仅 `highest_admin` 可见；`admin/member` 不显示入口且直接请求会返回 `403`

#### `GET /api/v1/admin/access`

- 用途：最高管理员读取账号与授权管理台所需数据
- 权限：仅 `highest_admin`
- 返回：
  - 脱敏 `accounts`，不包含 `passwordHash`
  - `companies`：显式客户公司 / 租户列表
  - `devices / projects / skills`
  - 按同名 Skill 聚合的 `skillCatalog`
  - 内置 `permissionTemplates`
  - `grants.devices / grants.projects / grants.skills`
  - `auditLogs`

#### `POST /api/v1/admin/access`

- 用途：最高管理员执行最小授权管理动作
- 权限：仅 `highest_admin`
- 支持动作：
  - `upsert_company`：创建或更新客户公司 / 租户
  - `set_company_status`：启用或停用客户公司；停用时同步禁用该租户普通子账号并撤销活跃会话
  - `assign_account_company`：把账号绑定到指定客户公司
  - `assign_device_company`：把设备绑定到指定客户公司
  - `preview_bulk_import_accounts`：预览批量导入结果，返回新增 / 更新 / 异常数量，不写入状态
  - `bulk_import_accounts`：按公司批量导入 `member/admin` 子账号
  - `reset_account_password`：最高管理员重置子账号密码，重置后撤销该账号活跃会话且响应不返回 `passwordHash`
  - `reclaim_account`：离职回收，停用账号、撤销活跃会话并清理设备 / 项目 / Skill 授权
  - `upsert_account`：创建或更新子账号
  - `set_account_status`：启用或停用子账号；停用时撤销该账号当前活跃会话，且禁止停用最高管理员账号
  - `revoke_device`：吊销指定设备，立即清空设备 token、标记离线、写入 `device.revoked` 审计；旧 token 后续不能 heartbeat、领任务、同步 Skill、上传日志或拉取 boss-agent OTA
  - `grant_device`：授予设备权限
  - `grant_project`：授予项目权限
  - `grant_skill`：授予 Skill 权限
  - `apply_template`：对指定账号和目标设备 / 项目 / Skill 批量套用内置权限模板
  - `revoke_grant`：撤销任意设备 / 项目 / Skill 授权
- 当前行为：所有变更类动作都会写入 `permissionAuditLogs`，用于后续审计和主 Agent 接手时判断权限来源；后台 mutation 会记录 `ipAddress / userAgent / requestId`，高危动作可记录安全化 `beforeJson / afterJson`

#### `GET /api/v1/admin/overview`

- 用途：最高管理员读取 To B 管理后台总览数据
- 权限：仅 `highest_admin`
- 返回：
  - `summary`：公司、账号、设备、在线设备、开放风险、风险通知、严重风险数量
  - `companies[]`：优先使用显式客户公司 / 租户，其次按账号域名或默认公司聚合
  - `accounts[]`：脱敏账号列表，不包含 `passwordHash`
  - `devices[]`：设备在线状态、CLI/GUI 能力、项目数和风险数
  - `risks[]`：离线设备、运维故障、线程上下文风险和失败主 Agent 任务；运维故障和线程上下文风险会带出负责人和 SLA
  - `notifications[]`：开放中的风险 SLA 通知，当前由 `/api/v1/admin/risks/scan` 生成
  - `grantsSummary`：设备 / 项目 / Skill 授权数量与过期授权数量

#### `GET /api/v1/admin/backoffice`

- 用途：独立 PC 企业后台读取 YuDao/Vben 风格的总后台契约数据
- 权限：仅 `highest_admin`
- 返回：
  - `menuTree`：工作台、租户管理、账号管理、角色权限、资源授权、Skill 中心、风险告警、审计日志、系统设置
  - `workbench`：平台总览、客户健康、设备健康、风险、通知和授权摘要
  - `tenants[]`：客户公司 / 租户列表，来自 `adminCompanies` 与现有聚合
  - `users[]`：脱敏账号列表，不包含 `passwordHash / mfaSecret / authSessions`
  - `roles`：内置角色与 `BOSS_PERMISSION_TEMPLATES`
  - `resourceGroups`：设备、项目线程、Skill 聚合目录和授权记录
  - `audit`：风险、通知、风险时间线和 `permissionAuditLogs`
  - `yudaoMapping`：Boss 账本字段到后台概念的映射，用于后续数据库化或模块拆分
- 当前定位：供 `https://admin.boss.hyzq.net/ -> apps/boss-admin-web` 消费；旧 `/admin` UI 已下线，不再消费 `/api/v1/admin/overview` 和旧数据 provider

#### `GET/POST /api/v1/admin/backups`

- 用途：最高管理员做文件状态快照、查看可回退点和执行状态回退
- 权限：仅 `highest_admin`
- `GET` 返回：
  - `status`：当前文件状态路径、备份目录、最近快照时间、可回退点数量和校验状态
  - `snapshots[]`：快照 ID、创建时间、创建人、备注、大小、sha256 和 schema 版本
- `POST` 输入：
  - `action=create_snapshot`：创建当前 `boss-state` 快照，可带 `reason`
  - `action=restore_snapshot`：恢复到指定 `snapshotId`
- 当前行为：恢复前会自动创建 `pre-restore:<snapshotId>` 快照，避免误操作后无法回滚；文件状态写入层默认按 `BOSS_STATE_AUTO_BACKUP_INTERVAL_MS` 自动创建 `auto:writeState` 快照，并按 `BOSS_STATE_AUTO_BACKUP_KEEP` 保留；独立 PC 管理后台的“备份与回退”页已接入创建、刷新和恢复动作。

#### `POST /api/v1/admin/risks/scan`

- 用途：扫描当前风险 SLA，幂等生成平台侧待跟进通知
- 权限：仅 `highest_admin`
- 当前行为：
  - 扫描未关闭的 `opsFaults` 和 `threadContextAlerts`
  - 同步检查运行态异常：在线设备 `Computer Use` 不可用会补 `BOSS.COMPUTER_USE.UNAVAILABLE` 运维故障，`boss-agent OTA` 失败日志会补 `BOSS_AGENT.OTA.FAILED` 运维故障
  - 当 `slaDueAt` 已早于当前时间时，写入 `adminNotifications[]`
  - 同一个 `riskId` 只生成一条 `risk_sla_overdue` 通知，重复扫描不会重复膨胀账本
  - 生成新通知时发布 `project.context_risk.updated`

#### `POST /api/v1/admin/risks/actions`

- 用途：最高管理员在管理后台处理风险
- 权限：仅 `highest_admin`
- 输入：
  - `riskId`：当前支持 `ops-fault:<faultId>` 和 `thread-alert:<alertId>`
  - `action`：`assign_owner | set_sla | ack | resolve | create_repair_ticket`
  - `ownerAccount`：`assign_owner` 必填
  - `slaDueAt`：`set_sla` 必填
  - `note`：可选处理备注
- 当前行为：
  - `ops-fault` 支持指派负责人、设置 SLA、确认、关闭、创建或复用修复工单
  - `thread-alert` 支持指派负责人、设置 SLA、确认和关闭，关闭时写入 `resolvedAt`
  - 离线设备、失败主 Agent 任务等暂不支持直接动作，会返回 `RISK_ACTION_UNSUPPORTED`
- 当前事件：成功动作会发布 `project.context_risk.updated`

#### `GET /api/v1/audits/permission-logs`

- 用途：查询 `permissionAuditLogs` 并返回第一版权限审计风险摘要
- 权限：仅 `highest_admin`；普通 `admin/member` 直接返回 `403`
- 查询参数：
  - `action`
  - `actorAccount`
  - `targetAccount`
  - `deviceId`
  - `projectId`
  - `skillId`
  - `cursor`
  - `limit`，默认 `50`，最大 `200`
- 返回：
  - `logs[]`：按 `createdAt` 最新在前排序后的当前页审计日志
  - `nextCursor`：下一页游标；没有更多数据时为 `null`
  - `total`：匹配过滤条件的总数
  - `riskSummary`：基于现有 `permissionAuditLogs` 和仍存在授权记录生成的 deterministic 摘要
- 当前风险规则：
  - `rapid_permission_grants`：同一 actor / target 在 10 分钟内出现 5 条及以上授权类日志
  - `skill_lifecycle_failed`：Skill lifecycle 完成日志中可识别失败，或后续写入 `skill.lifecycle.failed`
  - `expired_grant_present`：设备 / 项目 / Skill 授权记录已过期但仍留存在状态中
  - `admin_route_denied`：已有 `task.denied` 日志能识别非最高管理员访问 admin route 被拒
- 当前限制：权限审计风险摘要仍是查询时实时计算；持久化通知账本只覆盖风险 SLA 超时场景。

#### `GET /api/v1/admin/skills/requests`

- 用途：最高管理员读取 Skill 远程治理请求队列
- 权限：仅 `highest_admin`；普通 `admin/member` 直接返回 `403`
- 返回：
  - `requests[]`：当前保存在 `boss-state.json` 的 Skill lifecycle 请求
- 当前行为：按最新请求在前返回；设备端认领后状态会从 `pending` 变成 `running / completed / failed`

#### `POST /api/v1/admin/skills/requests`

- 用途：最高管理员创建 Skill 生命周期治理请求
- 权限：仅 `highest_admin`
- 支持动作：
  - `install`
  - `update`
  - `uninstall`
  - `rollback`
  - `version_lock`
- 输入要求：
  - 必须提供 `deviceId`
  - 必须提供 `skillId` 或 `sourceUrl` 之一
  - 可选 `targetVersion / rollbackToVersion / lockedVersion / checksum / expectedChecksum / trustedSource / note`
- 当前行为：请求以 `pending` 状态写入 `skillLifecycleRequests`，local-agent 会按设备 token 认领执行，并把 `completed / failed` 与结果摘要写回
- 当前设备端安全策略：远程 `install` 或带 `sourceUrl` 的更新必须命中本机 `skillLifecycleAllowedSources` 或 `skillLifecycleTrustedSources`；allowlist 为空时只允许既有本地 Skill 的 `update / rollback / uninstall / version_lock`。如果请求带 `checksum / expectedChecksum`，local-agent 会对 `manifest.json` 或 `SKILL.md` 做 sha256 校验；校验失败会失败回写，并清理半安装目录或尽量从 `skillsDir/.boss-skill-backups` 恢复
- 当前限制：第一版仅支持 Git 安装 / 更新、本地目录卸载、Git checkout 回滚和 `.boss-skill-locks.json` 版本锁；尚未做签名校验、依赖安装沙箱或 per-run Skill 执行审计

#### `POST /api/v1/devices/[deviceId]/skill-requests/claim`

- 用途：设备端领取下一条属于自己的 Skill 生命周期请求
- 权限：设备 token 或具备 `device.manage` 的登录会话
- 返回：
  - `request`：下一条请求；无待处理时为 `null`
- 当前行为：只领取当前设备 `pending` 请求，领取后改为 `running`

#### `POST /api/v1/devices/[deviceId]/skill-requests/[requestId]/complete`

- 用途：设备端回写 Skill 生命周期请求执行结果
- 权限：设备 token 或具备 `device.manage` 的登录会话
- 输入：
  - `status`：`completed` 或 `failed`
  - `resultSummary` / `error`
- 当前行为：写回 `completedAt / updatedAt / resultSummary / error`，并追加 `permissionAuditLogs`

### 3.1.2 执行底座抽象层

- 目录：`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 自身执行链
  - 当前已补 `browser_control / desktop_control` 两个新的 execution tool，并已纳入统一权限与风险分级判断
  - 当前已最小接入 `ClawBackendAdapter`，但默认关闭，仅在显式配置且可用性探测通过时才参与执行
  - 如果历史 `backendOverride=claw-runtime` 当前不可用，运行时会自动回退到默认后端，并把原因回给前台
  - 当前仓库自带 `scripts/claw-runtime-smoke.mjs` 作为兼容 JSON 协议的 smoke runtime，可用于本地和服务器验证 `ClawBackendAdapter`
  - 当前已最小接入 `OmxTeamBackendAdapter`，但默认关闭；Web 群聊详情页和原生群资料页已经可以在 `Boss Native` 与 `OMX Team` 间切换编排后端，OMX 不可用时会自动回退到默认后端并返回明确原因
  - 当前仓库自带 `scripts/omx-team-smoke.mjs`，可用于本地和服务器验证 `OmxTeamBackendAdapter` 的 `dispatch_execution` JSON 协议

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

- 状态字段：
  - `threadStatusDocuments`
  - `threadProgressEvents`
- 当前用途：
  - 让主 Agent 优先读取线程状态文档和最近进展事件，而不是常态重复深问线程
  - 让 Web / Android 前台能直接查看线程的当前目标、阶段、进度、架构、阻塞、建议下一步
- 当前同步策略：
  - `heartbeat / thread reply` 平时优先写轻量进展事件
  - 只有单线程接管、全局接管或用户明确要求同步项目目标 / 版本记录时，才补排隐藏全量理解任务
  - 关闭接管会同步清理仍在 queued/running 的项目理解同步任务，避免取消接管后继续主动打扰线程

### 3.2 认证相关

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

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

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

- 输入：
  - `account`
  - `method`: `password | code`
  - `password`
  - `code`
- 当前行为：
  - 默认不再允许临时免验证登录，只有显式配置 `BOSS_AUTH_AUTO_LOGIN=1/true/yes` 时才开启开发兜底
  - 原生 Android 端登录后会持久化 `boss_session + restore token`，用于 30 天登录保持和 OTA / 覆盖安装后的会话恢复
  - 正常模式要求 `password` 或 `code` 校验通过
  - 校验通过后会写入 `boss_session` Cookie
  - 当请求头带 `x-boss-native-app: 1` 时，还会额外返回 `restoreToken`
  - 当前 `boss_session` 默认保持 30 天
  - 连续失败 5 次后会锁定 10 分钟
- 当前密码存储：新注册 / 重置密码使用 `scrypt`；历史 `sha256` 会在下次密码登录时自动迁移
- 当前默认管理员账号：`krisolo`
- 当前默认测试密码由线上初始化配置管理，文档不再明文记录

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

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

#### `GET /api/v1/auth/sessions`

- 用途：查看可管理的登录会话
- 当前行为：
  - `highest_admin` 可查看全部活跃会话
  - 其他账号只能查看自己的活跃会话
  - 返回内容只包含 `sessionId / account / role / displayName / loginMethod / createdAt / expiresAt / lastSeenAt / current`
  - 不返回 `sessionToken / restoreToken`
- 前台入口：Web `/me/security` 与原生 Android `SecurityActivity`

#### `POST /api/v1/auth/sessions`

- 用途：撤销单个登录会话
- 输入：
  - `action=revoke_session`
  - `sessionId`
- 当前权限：
  - `highest_admin` 可撤销任意活跃会话
  - 其他账号只能撤销自己的会话

#### `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`
- 当前保护：
  - 已存在设备必须携带有效 `token` 或未过期 enrollment 的 `pairingCode`
  - 未准备 enrollment 的新 `deviceId` 不能通过心跳自注册
  - 已吊销设备返回 `DEVICE_REVOKED`，不会更新 `lastSeenAt / status / projects / projectCandidates`

#### `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 任务
  - 返回体会附带 `task.taskId / taskType / status`，给 Web 和原生 Android 保持等待真实回写使用
  - `projectId=master-agent` 且 `kind=text` 时，会先返回 `masterReplyState + task`，真实回复随后异步回写到账本
  - Telegram Gateway 当前也复用这条主 Agent 链路：Telegram 私聊文本会写入 `master-agent` 项目，快速回复直接返回，异步任务通过 `externalReplyTarget` 在完成后回推 Telegram
  - 当前主链路优先走 `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`，要求先确认或拒绝当前推荐，避免审批消息叠加

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

- 用途：删除当前项目消息账本里的一条聊天消息
- 输入：
  - `messageId`：优先从 query string 读取，也兼容 JSON body
- 当前行为：
  - 删除成功后会刷新项目预览、更新时间和未读计数
  - 会发布 `project.messages.updated / conversation.updated`
  - Android 长按消息的“删除”菜单已接入该接口

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

- 用途：读取当前对话级别的 `modelOverride / reasoningEffortOverride / backendOverride`
- 当前约束：
  - 当前只支持 `projectId=master-agent`
  - 未配置时返回 `controls: null`

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

- 用途：更新当前对话级别的 `modelOverride / reasoningEffortOverride / promptOverride / backendOverride`
- 当前约束：
  - 当前只支持 `projectId=master-agent`
  - 仅 `highest_admin` 可写
  - `backendOverride` 当前仅支持 `claw-runtime`
  - 只有在 `Claw Runtime` 可用性探测通过时才允许保存 `claw-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` 时同步更新 Boss 线程显示名和会话标题；如果该会话已绑定 `codexThreadRef`，会追加创建 `intentCategory=thread_rename` 的 `conversation_reply` 任务，由本机 App Server runner 调用 `thread/name/set` 同步 Codex 线程名称
  - `mode=group` 时更新群聊名称
- 边界：Codex 线程改名任务不会启动普通 turn，不会把线程原始历史写回 APP；设备离线、并发冲突或 App Server 不可用时，本地 Boss 改名仍保留，响应会带非致命 `codexThreadRenameError`

#### `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`

- 用途：读取当前登录用户的附件存储配置
- 当前入口：Web `我的 > 附件与存储` 与 Android `StorageSettingsActivity`
- 返回：
  - `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`
- 当前行为：
  - 本地 Boss 项目目标先落盘
  - 如果目标项目是已绑定 `codexThreadRef` 的单线程会话，会追加创建 `intentCategory=thread_goal_sync` 的 `conversation_reply` 任务，由本机 App Server runner 调用 `thread/goal/set` 同步 Codex 线程 goal
  - 设备离线、并发冲突或 App Server 不可用时，本地目标仍保留，响应会带非致命 `codexThreadGoalError`
- 返回：
  - `goal`
  - `codexThreadGoalTask`（可选）
  - `codexThreadGoalError`（可选）

#### `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/boss-agent/ota`

- 用途：被控电脑上的 boss-agent 用设备 token 检查 Mac agent 运行包 OTA
- 输入：`deviceId`、`currentVersion`
- 返回：`hasUpdate` 与最新 `boss-agent-mac-latest.zip` 的版本、大小、sha256、下载地址
- 当前保护：要求 `x-boss-device-token`

#### `GET /api/v1/boss-agent/ota/package`

- 用途：下载当前已发布的最新 boss-agent macOS 运行包
- 当前来源：`public/downloads/boss-agent-mac-latest.zip`
- 当前元数据：`public/downloads/boss-agent-mac-latest.json`
- 当前保护：要求 `x-boss-device-token` 与 `deviceId`

#### `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` 或匹配登录会话
- 当前可靠性：claim 会写入 `attemptCount / maxAttempts / claimedAt / lastClaimedAt / leaseExpiresAt`；运行中任务租约过期后可重试认领，超过最大次数会转为 `timed_out` 并更新进度卡；被吊销设备不能继续认领

#### `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 账号健康状态
  - 如果任务带有 `externalReplyTarget.provider=telegram`，完成后会尝试调用 Telegram Bot API 把 `replyBody` 回推到原始聊天
  - 终态任务 `completed / failed / timed_out / canceled` 的迟到重复 complete 会直接返回当前任务，不再覆盖终态或重复写消息
- 对群聊分发推荐失败的情况，消息入口当前会额外写入一条 `system_notice`，把“没有真实线程”或“成员引用失效”明确回显给用户

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

- 用途：取消仍在 `queued / running / needs_user_action` 的主 Agent 任务
- 权限：任务请求账号、`highest_admin`，或具备目标设备 `device.manage` 的账号
- 当前行为：任务转为 `canceled`，写入 `canceledAt / canceledBy / cancelReason`，清除租约；如果之后设备端迟到回写成功，服务端不会覆盖取消终态

#### `GET /api/v1/master-agent/tasks/[taskId]/control-state`

- 用途：设备端在执行中轮询任务控制状态，用于把 APP / Web 的取消动作同步到正在运行的本地 runtime
- 权限：目标设备 token，或具备目标设备写权限的会话
- 返回：`taskId / status / canceled / cancelReason / canceledAt`
- 安全边界：不返回 `requestText / executionPrompt / sourceMessageBody`，避免把用户消息、内部提示词或调度字段泄露给设备外的调用方
- 当前 App Server 行为：`local-agent` 在 `turn/start` 后轮询该接口；如果返回 `canceled=true`，会调用当前 App Server 连接的 `turn/interrupt`，把 Codex 活跃 turn 真实中断

#### `GET /api/v1/integrations/telegram`

- 用途：读取 Telegram Bot 接入配置
- 当前保护：仅 `highest_admin` 可读
- 返回：脱敏后的 `enabled / mode / botTokenConfigured / webhookSecretConfigured / allowFrom / groups / defaultProjectId / groupProjectRoutes`

#### `POST /api/v1/integrations/telegram`

- 用途：保存 Telegram Bot 接入配置，并可选执行 `getMe` 探测
- 当前保护：仅 `highest_admin` 可写
- 输入：
  - `enabled`
  - `mode`: `webhook | polling`
  - `botToken`
  - `dmPolicy`: `allowlist | open | disabled`
  - `allowFrom`: Telegram user id 字符串数组
  - `groupPolicy`: `allowlist | open | disabled`
  - `groups`: Telegram chat id 字符串数组
  - `requireMentionInGroups`
  - `defaultProjectId`
  - `groupProjectRoutes`: 群 / Topic 到 Boss 项目的路由表，单项格式为 `{ chatId, threadId?, projectId, label? }`
  - `webhookSecret`
  - `webhookUrl`
  - `testConnection`
- 当前行为：
  - `mode=webhook` 且提供 `webhookUrl` 时，会自动调用 Telegram `setWebhook`
  - `mode=polling` 或关闭接入时，会自动调用 Telegram `deleteWebhook`
  - `testConnection=true` 时会额外调用 `getMe`，并把返回的 bot username 回写到配置视图

#### `POST /api/v1/integrations/telegram/webhook`

- 用途：Telegram Bot webhook 入口
- 当前保护：优先校验 `x-telegram-bot-api-secret-token`，再执行 DM / group allowlist
- 当前行为：
  - 私聊文本默认桥接到 `master-agent`
  - 群聊文本需要命中 `groups` 白名单；开启 `requireMentionInGroups` 时，必须 `@Bot` 或直接回复当前 Bot 上一条消息；进入主 Agent 前会自动清洗 bot mention
  - 如果配置了 `groupProjectRoutes`，会优先按 `chatId + threadId` 精确匹配，再按 `chatId` 匹配，把消息写入指定 Boss 项目；未命中时回到 `defaultProjectId`
  - 本地 fast path 回复会立即调用 Telegram `sendMessage`
  - 需要排队的主 Agent 任务会保存 `externalReplyTarget`，任务完成后从 `/api/v1/master-agent/tasks/[taskId]/complete` 自动回推 Telegram
  - 已处理的 `update_id` 会保留最近 256 条用于幂等去重
- 当前保护：要求 `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`
- 对已绑定 `targetCodexThreadRef` 的普通单线程 `conversation_reply`，local-agent 现在会在 `codex exec resume` 前先把 Boss 用户消息镜像写入目标 Codex Desktop 线程 rollout；镜像按 `sourceMessageId` 去重，不会因任务重试重复写入。rollout 定位优先走 `state_5.sqlite`，不可用时回退扫描 `~/.codex/sessions`；状态库可写且能命中 thread 时会同步刷新线程活跃时间
- `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`

状态存储默认仍走文件模式。PostgreSQL 仅作为显式量产切换路径存在：必须设置 `BOSS_STATE_STORE=postgres`，涉及真实连接 / 写入的维护命令还必须设置 `BOSS_DATABASE_URL`。`scripts/boss-state-store-maintenance.mjs` 当前支持：

- `validate-schema`：校验 `scripts/postgres-state-schema.sql` 是否包含 `boss_state_snapshots`、`snapshot_key` 主键、`state JSONB` 和更新时间索引
- `backup-file / export-file`：在文件模式下导出当前状态文件备份
- `migrate-file-to-postgres --dry-run`：只校验文件状态和 schema，不连接数据库；正式迁移会 upsert 到 `boss_state_snapshots`
- `export-postgres-backup`：从 PostgreSQL 导出带元数据和 sha256 的 JSON 备份包
- `restore-postgres-backup`：把备份包或原始状态 JSON 恢复回 PostgreSQL，可先用 `--dry-run` 验证
- `rollback-postgres-to-file`：把 PostgreSQL 当前快照回写到文件，用于数据库切换失败后的文件模式回退

状态文件当前带有迁移前置元数据：

- `schemaVersion`：当前 BossState schema 版本
- `migratedAt`：最近一次从旧 schema 迁移到当前 schema 的时间

读取状态时会先经过 `migrateBossState`，用于从无版本或旧版本 JSON 补齐当前结构，并规范化授权和 Skill 生命周期相关数组。这个机制只为后续正式 DB 迁移提供稳定 schema 边界，不表示数据库化已经完成。

关键对象：

- `schemaVersion`
- `migratedAt`
- `user`
- `devices`
- `projects`
- `verificationCodes`
- `verificationDispatches`
- `adminCompanies`
- `adminNotifications`
- `adminRiskTimeline`
- `authAccounts`
- `authSessions`
- `accountDeviceGrants`
- `accountProjectGrants`
- `accountSkillGrants`
- `skillCatalog`
- `skillLifecycleRequests`
- `aiAccounts`
- `aiAccountSwitchHistory`
- `userAttachmentStorageConfigs`
- `threadContextSnapshots`
- `threadHandoffPackages`
- `threadContextAlerts`
- `deviceEnrollments`
- `deviceSkills`
- `appLogs`
- `masterAgentTasks`
- `dispatchPlans`
- `dispatchExecutions`
- `deviceImportDrafts`
- `deviceImportResolutions`
- `opsFaults`
- `opsRepairTickets`
- `opsRepairVerifications`
- `auditRequests`
- `auditResults`
- `capabilities`

## 6. 当前实现边界

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

不要误以为已经存在：

- 已直接切换完成的正式数据库
- 企业 SSO / IdP
- 多家对象存储适配（当前只有服务器文件存储和阿里 OSS）
- 完整的附件详情页与富预览器
- 完整的多端会话风控平台（当前已有 restore token 轮换、CSRF 基础防护和 MFA 开关）