krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dbdaab8d0ff241e7c51fa22313ef03f237f775e0
boss/docs/architecture/api_and_service_inventory_cn.md
AI Bot dbdaab8d0f feat: mirror boss messages via app server
2026-06-03 15:00:25 +08:00

90 KiB
Raw Blame History

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，再按一次返回进入后台”
  • 当前会话列表：
    • 已切到“线程 = 会话窗口”
    • 主标题显示线程名
    • 第二行显示所属文件夹名
    • 右下角显示后台活跃数量动态图标
    • 主 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 启动后失败不回退，避免重复执行。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=notLoaded，只保留 turn 计数、运行中 / 完成计数、最近状态和更新时间，不保存 turn id、items、用户正文、模型输出或内部 prompt。
  • 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.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
    • 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 开关）