# 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`
  - `ProjectGoalsActivity`
  - `ProjectVersionsActivity`
  - `ProjectForwardActivity`
  - `ThreadDetailActivity`
  - `DeviceDetailActivity`
  - `DeviceEnrollmentActivity`
  - `SkillInventoryActivity`
  - `SecurityActivity`
  - `SettingsActivity`
  - `AiAccountsActivity`
  - `OpsCenterActivity`
  - `AboutActivity`
- 当前项目聊天页：
  - `ProjectDetailActivity` 已改成聊天优先布局
  - 主面只保留 `项目目标 / 版本记录`
  - `消息转发 / 线程详情 / 运维调试` 仍保留对应原生活动页，但已退出主聊天面
- 当前 `关于` 页：
  - 保留版本与 OTA 操作
  - 新增深层 `高级与调试` 入口，用于进入 `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/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

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

#### `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`
- 当前行为：
  - 普通项目直接写入消息账本
  - `projectId=master-agent` 且 `kind=text` 时，会继续触发主 Agent 真实回复链路
  - 当前主链路优先走 `Master Codex Node`：`task queue -> local-agent -> codex exec -> complete`
  - 如本机节点未接通，可切到 `OpenAI API` 容灾账号

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

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

#### `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`：校验是否配置节点 ID，并提示由 local-agent relay 执行
  - `openai_api`：实际调用模型返回探针结果
- 当前约束：
  - `openai_api` 的容灾 Key 由用户在 APP 内配置，不走服务器默认预置

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

- 用途：把消息转发到另一个项目
- 输入：
  - `targetProjectId`
  - `note`

#### `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]/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`
- 当前行为：
  - `completed` 时把真实主 Agent 回复写回 `master-agent` 项目消息账本
  - `failed` 时写入 relay 失败消息，并更新 AI 账号健康状态
- 当前保护：要求 `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 同步

### 4.5 主 Agent 轮询任务

- local-agent 会周期性请求 `POST /api/v1/master-agent/tasks/claim`
- 认领到任务后会执行本机 `codex exec`
- 执行完成后会调用 `POST /api/v1/master-agent/tasks/[taskId]/complete`

## 5. 当前状态存储

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

- `data/boss-state.json`

关键对象：

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

## 6. 当前实现边界

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

不要误以为已经存在：

- 正式数据库
- 正式鉴权中间件
- 图片 / 视频真实文件上传和对象存储
- 完整的多端用户会话系统与刷新令牌体系