krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8da592bddf65dd0a804cca4064ff1b16a146136b
boss/docs/architecture/api_and_service_inventory_cn.md

15 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

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. 当前实现边界

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

不要误以为已经存在：

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