boss/docs/architecture/api_and_service_inventory_cn.md

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

1.2 boss-android-native

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

1.3 boss-local-agent

• 形态：Node 原生 HTTP 服务
• 本地端口：默认 4317
• 健康检查：GET /health
• 当前常驻方式：launchd
• 当前额外职责：向云端上报 thread-context
• 当前新增职责：递归扫描本机 ~/.codex/skills 并同步到设备 Skill 接口

1.4 Caddy

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

1.5 boss-server-debug skill

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

1.6 Postfix + Dovecot

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

2. Web 页面路由

2.1 一级页

• GET /auth/login
• GET /conversations
• GET /devices
• GET /me

2.2 二级页

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

3. Web API 路由

3.1 健康和状态

GET /api/health

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

GET /api/state

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

3.2 认证相关

POST /api/auth/send-code

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

POST /api/auth/login

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

GET /api/auth/session

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

POST /api/auth/restore

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

POST /api/auth/logout

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

POST /api/auth/register

• 输入：
  • account
  • password
  • confirmPassword
  • code

POST /api/auth/forgot-password

• 输入：
  • account
  • password
  • confirmPassword
  • code

3.3 设备心跳和当前老接口

POST /api/device-heartbeat

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

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

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

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

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

3.4 聚合 BFF / 实时接口

GET /api/v1/conversations

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

GET /api/v1/conversations/home

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

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

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

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

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

GET /api/v1/projects/[projectId]

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

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

• 用途：向项目消息账本写文本/语音/图片/视频意图消息
• 输入：
  • body
  • kind: text | voice_intent | image_intent | video_intent
• 当前行为：
  • 普通单线程项目当前会在写入用户消息后，继续创建 taskType=conversation_reply 的主 Agent 任务
  • 返回体会附带 task.taskId / taskType / status，给 Web 和原生 Android 保持等待真实回写使用
  • projectId=master-agent 且 kind=text 时，会继续触发主 Agent 真实回复链路
  • 当前主链路优先走 Master Codex Node：task queue -> local-agent -> codex exec -> complete
  • 如果当前主控是 Master Codex Node，但节点离线或执行立即失败，主 Agent 当前会优先尝试已配置的 OpenAI API 账号，避免聊天直接只剩失败日志
  • 如本机节点未接通，可切到 OpenAI API 容灾账号
  • 群聊项目当前会带上 collaborationGate，用于标明当前是否需要先经主 Agent / 用户审批
  • 群聊文本消息当前还会返回 dispatchPlan / dispatchRecommendation，用于展示主 Agent 推荐的线程下发方案

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

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

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

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

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

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

POST /api/v1/group-chats

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

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

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

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

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

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
  • 若服务器当前无法访问 api.openai.com，会直接返回明确中文网络错误，而不是只返回 fetch failed

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
• 当前产品语义：
  • master_codex_node 表示已经在绑定电脑上登录 ChatGPT Plus / Codex 的执行节点
  • openai_api 只作为用户自行配置的 API 容灾

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：实际调用模型返回探针结果
• 当前约束：
  • openai_api 的容灾 Key 由用户在 APP 内配置，不走服务器默认预置
  • 手机端当前没有直接的 ChatGPT OAuth 登录流程；主 GPT 必须先在绑定电脑上的 Codex / ChatGPT Plus 会话里完成登录

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

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

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

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

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

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

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

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

GET /api/v1/storage/config

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

PATCH /api/v1/storage/config

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

POST /api/v1/storage/config/validate

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

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

• 用途：新增项目目标
• 输入：
  • text

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

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

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

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

GET /api/v1/devices

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

GET /api/v1/devices/enrollments

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

POST /api/v1/devices/enrollments

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

PATCH /api/v1/devices/[deviceId]

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

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

• 用途：读取某台设备最新的项目候选导入草稿
• 当前行为：
  • 返回最新 deviceImportDraft
  • 如果已经做过导入决议，还会一并返回最新 deviceImportResolution
• 当前保护：
  • 仅 highest_admin 或设备所属账号可读

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

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

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

• 用途：生成主 Agent 风格的设备导入决议
• 当前行为：
  • 会先落一条 device_import_resolution master task，再把决议写回 deviceImportResolution
  • 当前决议内容仍为服务端 heuristic 版
  • 决议会区分 create_thread_conversation | attach_existing | skip
• 当前保护：
  • 仅 highest_admin 或设备所属账号可写

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

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

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

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

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

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

GET /api/v1/app-logs

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

POST /api/v1/app-logs

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

POST /api/v1/settings

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

GET /api/v1/user/ota

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

POST /api/v1/user/ota

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

GET /api/v1/user/ota/package

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

GET /api/v1/ops/summary

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

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

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

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

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

GET /api/v1/audits/summary

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

GET /api/v1/events

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

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

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

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

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

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 子线程，会优先过滤这些子线程，避免误导入过多聊天窗口
  • 对已绑定的生产设备，服务端会在 heartbeat 时自动应用建议导入项；对新设备则继续走 deviceImportDraft 的人工勾选与应用流程
  • 自动应用时，如果某些已导入线程已经不再出现在最新 projectCandidates[] 中，服务端会在同一轮 heartbeat 清理这些过时线程会话

4.5 主 Agent 轮询任务

• local-agent 会周期性请求 POST /api/v1/master-agent/tasks/claim
• 认领到任务后会执行本机 codex exec
• conversation_reply / dispatch_execution 当前会优先走 codex exec resume <targetCodexThreadRef>，把任务恢复到真实 Codex 线程；只有缺失真实线程引用时才退回 --ephemeral
• 执行完成后会调用 POST /api/v1/master-agent/tasks/[taskId]/complete
• 对群聊下发链路，认领到的 dispatch_execution 任务会带 dispatchExecutionId / targetProjectId / targetThreadId
• 对普通单线程聊天，认领到的 conversation_reply 任务会带 targetProjectId / targetThreadId / targetCodexThreadRef
• local-agent 回写完成时会同时带上 rawThreadReply，服务端据此把线程原始结果和主 Agent 汇总回写到群聊

5. 当前状态存储

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

• data/boss-state.json

关键对象：

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

6. 当前实现边界

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

不要误以为已经存在：

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