# Boss 控制台 MVP

这个仓库当前已经收口成“下一条 AI 线程不需要重新摸索结构和部署方式”的状态。真实实现是一套基于 `Next.js App Router` 的移动控制台，加一个本地 `device-agent`，持久化仍然是 `data/boss-state.json`，部署链路是 `systemd + Caddy + launchd`。

## 先读哪里

按这个顺序看，交接成本最低：

1. `docs/architecture/ai_handoff_index_cn.md`
2. `docs/architecture/repo_map_cn.md`
3. `docs/architecture/current_runtime_and_deploy_status_cn.md`
4. `docs/architecture/api_and_service_inventory_cn.md`
5. `docs/architecture/boss_server_connection_and_deploy_cn.md`
6. `prompts/codex_fullstack_build_and_deploy_prompt_cn.md`

## 当前有效目录

- `src/app`：当前 Web 页面和 API 路由
- `src/components`：共享 UI 和交互组件
- `src/lib`：文件型状态模型和聚合投影视图
- `local-agent`：本地设备端心跳 + thread-context 上报服务
- `deployment`：`Caddy`、`systemd`、`launchd` 配置
- `scripts`：本地启动、安装、远端部署脚本
- `design`：Pencil 原稿和导出图
- `android`：原生 Android 客户端工程和 APK 构建目录
- `docs/architecture`：当前权威中文文档
- `prompts`：交给其他 Codex 线程的提示词

## 当前仅作参考或占位的目录

- `docs/source-material`：历史材料，不是运行时真相
- `deploy`：空占位目录，不参与当前部署
- `src/boss_control`：空占位目录，不参与当前运行
- `src/boss_device_agent`：空占位目录，不参与当前运行

## 当前运行状态（2026-03-26）

本地：

- `npm run lint` 已通过
- `npm run build` 已通过
- `GET http://127.0.0.1:3000/api/health` 正常
- `GET http://127.0.0.1:3000/api/v1/conversations` 正常
- `GET http://127.0.0.1:3000/api/v1/projects/master-agent` 正常，主 Agent 项目页已能显示最近 APP 日志
- `GET http://127.0.0.1:3000/api/v1/accounts` 正常，已返回主 GPT / 备用 GPT / API 容灾账号摘要
- `GET http://127.0.0.1:3000/api/v1/devices/mac-studio/skills` 正常，已返回本机同步 Skill 列表
- `POST http://127.0.0.1:3000/api/auth/login` 正常，会写入 `boss_session` Cookie
- `GET http://127.0.0.1:3000/api/auth/session` 正常
- `POST http://127.0.0.1:3000/api/auth/restore` 正常，已验证可用原生 restore token 恢复登录态
- `POST http://127.0.0.1:3000/api/v1/projects/master-agent/messages` 正常，已验证可通过 `Mac Studio local-agent -> 本机 Master Codex Node -> 回写项目账本` 返回真实主 Agent 回复
- `POST http://127.0.0.1:3000/api/auth/logout` 正常，退出后访问受保护 `/api/v1/*` 会返回 `401`
- `GET http://127.0.0.1:3000/api/v1/user/ota/package` 正常，当前会返回最新 APK 包
- `GET http://127.0.0.1:4317/health` 正常
- `GET http://127.0.0.1:4317/api/v1/skills` 正常，已返回本机扫描到的 Codex Skill
- `POST http://127.0.0.1:4317/api/v1/heartbeat` 正常，且会顺带触发 `thread-context` 上报
- `launchd` 已加载：`~/Library/LaunchAgents/com.hyzq.boss.local-agent.plist`

服务器：

- 服务器地址：`106.53.170.158`
- 代码路径：`/opt/boss`
- `boss-web.service` 正常
- `caddy.service` 正常
- `postfix.service` 正常
- `dovecot.service` 正常
- `GET http://127.0.0.1:3000/api/health` 正常
- `GET http://127.0.0.1:3000/api/v1/conversations` 正常

域名和 HTTPS：

- 服务器本机 `dig +short boss.hyzq.net` 返回 `106.53.170.158`
- 服务器本机 `curl --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net -I` 返回 `307` 并跳转到 `/auth/login`
- 当前本机网络 `dig +short boss.hyzq.net` 仍返回 `198.18.1.188`
- 当前本机网络 `curl -I http://boss.hyzq.net` 返回 `308`
- 当前本机网络 `curl -I https://boss.hyzq.net` 返回 `HTTP/2 307` 并跳转到 `/auth/login`
- 当前本机网络 `curl https://boss.hyzq.net/api/health` 返回 `{"ok":true,...}`
- 当前本机网络 `curl https://boss.hyzq.net/api/v1/conversations` 已返回真实聚合数据
- 当前本机网络 `nc -vz boss.hyzq.net 25 587 993` 全部成功

当前结论更新为：

- 当前网络下 `boss.hyzq.net` 的 HTTP/HTTPS 已可达
- `Caddy/TLS` 和外部 `443` 路径都已经能实际返回页面跳转
- 公网域名下的 Web API 也已经能实际返回健康探针和业务数据
- 服务器上的 `Postfix + Dovecot` 已部署完成，公网 `25 / 587 / 993` 当前也已经可达
- 但当前网络下 `dig` 仍显示 `198.18.1.188`，说明这里可能存在代理层、分裂 DNS 或中间入口，不要再把这个解析值自动当成错误配置

Android APK：

- 已生成 Android debug APK：`android/app/build/outputs/apk/debug/app-debug.apk`
- 已生成 Android signed release APK：`android/app/build/outputs/apk/release/app-release.apk`
- `npm run apk:release` 还会额外产出带版本号的文件：`android/app/build/outputs/apk/release/boss-android-v{versionName}-release.apk`
- 当前最新 release 构建版本：`2.1.0`（`versionCode=7`）
- 当前 APK 已切到原生 Android 客户端：`MainActivity + BossApiClient + 原生 XML 布局`
- 当前原生活动页已经覆盖：会话首页、项目详情、项目目标、版本记录、消息转发、线程详情、设备详情、添加设备、账号与安全、设置、AI 账号、技能、运维中心、关于
- 原生客户端当前直接调用 `https://boss.hyzq.net` 的 Boss API，不再打开 WebView
- `2.0.1` 已修复华为真机上因 `Theme.SplashScreen` 与 `AppCompatActivity` 不兼容导致的启动闪退
- `2.1.0` 已在本机连接的华为真机上完成签名包覆盖安装与启动复核，原生三栏入口和子活动页声明已全部接通

## 本地启动

开发态：

```bash
cd /Users/kris/code/boss
npm install
npm run dev
```

构建态：

```bash
cd /Users/kris/code/boss
npm run build
npm start
```

说明：

- `npm run build` 前会自动清理 `.next`，避免旧目录残留导致 `ENOTEMPTY`

默认入口：

- 登录页：[http://127.0.0.1:3000/auth/login](http://127.0.0.1:3000/auth/login)
- 会话页：[http://127.0.0.1:3000/conversations](http://127.0.0.1:3000/conversations)
- 设备页：[http://127.0.0.1:3000/devices](http://127.0.0.1:3000/devices)

## 设备端本地服务

手动启动：

```bash
cd /Users/kris/code/boss
./scripts/start-local-agent.sh ./local-agent/config.example.json
```

安装常驻 `launchd`：

```bash
cd /Users/kris/code/boss
./scripts/install-local-launchagent.sh
```

如需把常驻 agent 指回本地开发控制面：

```bash
cd /Users/kris/code/boss
./scripts/install-local-launchagent.sh /Users/kris/code/boss/local-agent/config.example.json
```

device-agent 当前职责：

- 上报设备状态、账号、5h/7d 额度和项目列表
- 向云端 `/api/device-heartbeat` 发心跳
- 向云端 `/api/v1/workers/{workerId}/thread-context` 发线程预算更新
- 递归扫描本机 `~/.codex/skills`，并同步到云端 `/api/v1/devices/[deviceId]/skills`
- 轮询云端 `/api/v1/master-agent/tasks/claim`，并用当前电脑已登录的 `codex` 账号执行主 Agent 任务
- 将主 Agent 执行结果回写到云端 `/api/v1/master-agent/tasks/[taskId]/complete`
- 提供本地 `/health`、`/api/v1/device`、`/api/v1/skills`、`/api/v1/heartbeat`

当前常驻默认值：

- `launchd` 默认加载 `local-agent/config.cloud.json`，控制面指向 `https://boss.hyzq.net`
- `local-agent/config.example.json` 保留给本地 `127.0.0.1:3000` 回环开发

## 部署入口

- 服务器连接与部署：`docs/architecture/boss_server_connection_and_deploy_cn.md`
- 服务器调试 skill：`$HOME/.codex/skills/boss-server-debug/SKILL.md`
- 远端部署脚本：`scripts/deploy-server.sh`
- 远端邮件部署脚本：`scripts/install-server-mail.sh`
- 远端初始化脚本：`scripts/bootstrap-server.sh`
- APK 发布脚本：`scripts/publish-apk-to-public.sh`
- `systemd` 配置：`deployment/systemd/boss-web.service`
- `Caddy` 配置：`deployment/Caddyfile`
- 邮件配置：`deployment/mail/`
- Android 原生入口：`android/app/src/main/java/com/hyzq/boss/MainActivity.java`
- Android API 客户端：`android/app/src/main/java/com/hyzq/boss/BossApiClient.java`
- Android 原生会话页：`android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`
- Android 原生设备页：`android/app/src/main/java/com/hyzq/boss/DeviceDetailActivity.java`
- Android 原生我的页：`android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java`、`android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java`、`android/app/src/main/java/com/hyzq/boss/SettingsActivity.java`
- 服务器环境示例：`.env.server.example`

当前 `scripts/deploy-server.sh`：

- 优先从 macOS Keychain 读取 `ubuntu@106.53.170.158` 的密码
- 如果 Keychain 不可用，再回退读取 `BOSS_SERVER_PASS`
- 当前已明确排除 `data/` 目录，部署不会再覆盖服务器上的 `boss-state.json`
- 部署脚本当前会先在本机执行 `npm run build`，再把本机已经验证通过的 `.next` 构建产物同步到服务器
- 同步前会先在服务器上删除旧 `.next` 并修正 `/opt/boss` 所有权，避免 rsync 被历史 root 产物卡住
- 服务器当前不再现编 Next standalone，而是直接重启使用本机同步过去的构建产物，避免服务器端 tracing / 权限差异导致部署失败
- 远端重启服务后会自动执行一次 `curl -fsS http://127.0.0.1:3000/api/health`

APK 构建：

```bash
cd /Users/kris/code/boss
npm run apk:debug
```

```bash
cd /Users/kris/code/boss
npm run apk:release
```

说明：

- `npm run apk:debug` 现在会在 Gradle 构建完成后自动执行 `scripts/publish-apk-to-public.sh`
- `npm run apk:release` 会先准备本机 release keystore，再构建 signed release APK，并发布到 `public/downloads`
- 最新 APK 会同步到 `public/downloads/boss-android-latest.apk`
- 同时也会额外保留一份带版本号的 APK：`public/downloads/boss-android-v{versionName}-{flavor}.apk`
- OTA 下载入口固定走受保护的 `GET /api/v1/user/ota/package`
- release 签名文件当前放在本机：
  - `android/keystores/boss-release.keystore`
  - `android/signing/release-signing.properties`
  - 以上文件已加入 `.gitignore`，不会进仓库

## 关键实现说明

- 当前持久化是真正生效的文件存储：`data/boss-state.json`
- Web 生产启动和服务器 `systemd` 都显式设置了 `BOSS_STATE_FILE`，避免 Next standalone 误把状态写进 `.next/standalone/data/`
- Web 生产启动、服务器 `systemd` 和部署构建当前都显式设置了 `BOSS_RUNTIME_ROOT`，避免 `process.cwd()` 在 standalone / 服务器构建阶段误把整个仓库根目录带进 tracing
- `next.config.ts` 已显式排除 `deployment / docs / design / local-agent / prompts / scripts / android` 等非运行时目录，避免服务器端 standalone tracing 卷入运维资产导致构建失败
- 文件写入已经改成串行事务队列 + 原子写入 + `data/boss-state.json.bak` 备份恢复，`heartbeat` 和 APP 日志并发写不会再互相覆盖
- 当前文件存储里已经包含：
  - `projects / messages / goals / versions`
  - `authAccounts / otaUpdates / otaUpdateLogs`
  - `threadContextSnapshots / threadHandoffPackages / threadContextAlerts`
  - `deviceEnrollments`
  - `deviceSkills / appLogs`
  - `opsFaults / opsRepairTickets / opsRepairVerifications`
  - `auditRequests / auditResults / capabilities`
- 根布局会挂载 `AppLogBridge`，前端路由切换、运行时异常、发送消息、OTA 操作都会通过 `/api/v1/app-logs` 实时同步到服务器
- Web 端根布局当前仍保留 `NativeAppBridge`，用于浏览器态与历史桥接兼容；当前正式 APK 已改为原生 Activity + 原生 API 客户端，不再依赖 WebView
- APP 日志桥已经改成会话感知：只会按当前登录账号解析绑定设备，不再在未登录页默认按全局管理员设备写日志
- APP 外壳已经从“桌面预览卡片”切回真机态：移动端不再渲染假的 `9:41 / 5G` 状态栏，底部 `会话 / 设备 / 我的` 导航固定在视口底部，背景改为全屏 cover，不再出现圆角矩形外壳
- 登录成功后的进入首页链路已做稳态处理：会先确认 `/api/auth/session` 可读，再执行 `replace(/conversations)`，并附带一次原生级兜底跳转，避免真机 WebView 偶发停留在“正在进入会话首页”
- `/api/v1/events` 已作为 SSE 出口使用，会话页、设备页、技能页和项目详情页会按事件自动刷新，不再只靠手动刷新
- 我的页新增 `技能` 入口，`/me/skills` 会按设备分组展示 Skill，并支持一键复制调用语句
- 我的页新增 `AI 账号` 入口，`/me/ai-accounts` 会展示主 GPT / 备用 GPT / API 容灾，并明确主链路优先走已登录 `ChatGPT Plus / Codex` 的 `Master Codex Node`
- API 容灾当前不走服务器预置 Key，而是由用户在 APP 的 `我的 > AI 账号` 中自行配置 `OpenAI API` 账号
- 设备页当前只展示已接入生产链路的设备，历史演示脏数据已经从正式设备视图、运维视图和审计视图中剔除
- 登录页当前已临时切到免验证模式，点击“登录”会直接进入会话首页
- 认证现在已经有最小会话链路：登录后会写入 `boss_session` Cookie，默认保持 30 天，`会话 / 设备 / 我的 / 线程` 页面以及主要 `/api/v1/*` 接口都要求有效会话
- 新增 `GET /api/auth/session`、`POST /api/auth/logout` 与 `POST /api/auth/restore`
- 原生 Android 客户端当前会把 `boss_session / restore token / account` 存到 `SharedPreferences`，用于重启后恢复会话
- 验证码新增防刷与防重放：60 秒冷却、15 分钟窗口限流，登录连续失败 5 次后会锁定 10 分钟
- `POST /api/auth/send-code` 现在会先按用途校验账号状态：登录 / 忘记密码要求账号已存在，注册要求账号尚未注册
- 当前登录页已临时放开成“一键进入”，账号密码和验证码输入暂时不作为拦截条件
- `POST /api/auth/send-code` 与固定验证码 `000000` 仍保留给注册 / 重置密码和后续认证收口，不作为当前登录页前置条件
- 新注册和重置密码现在使用 `scrypt` 哈希；历史 `sha256` 密码会在下一次密码登录时自动迁移
- 当前默认最高管理员账号：`17600003315`
- 当前默认测试密码：`boss123456`
- 当前本机 Codex 节点 `mac-studio` 已绑定到 `17600003315`
- 主 Agent 对话当前真实执行链路是：`Boss Web -> master-agent task queue -> local-agent -> codex exec -> complete task -> project ledger`
- 主 Agent 同步等待窗口已调到 55 秒；如果本机 Codex 节点执行较慢，项目页也会通过 SSE 在任务完成后自动刷新出真实回复
- 服务器已经部署 `Postfix + Dovecot`，邮箱别名 `verify@boss.hyzq.net` / `no-reply@boss.hyzq.net` 当前会投递到本机 `bossmail` 邮箱
- 应用内 `POST /api/auth/send-code` 已经支持 email 模式，并可通过 `/opt/boss/.env.server` 切换；本轮已临时切到 email 模式验证成功，随后恢复默认 fixed
- 应用内 `GET /api/v1/user/ota` / `POST /api/v1/user/ota` / `GET /api/v1/user/ota/package` 现在已经支持 OTA 状态、检查更新、执行升级和 APK 包下载
- `GET /api/v1/app-logs` 现在已支持登录态下按 `deviceId / projectId / level / category / source / cursor` 查询日志分页
- 设备写接口 `POST /api/v1/app-logs`、`POST /api/v1/devices/[deviceId]/skills`、`POST /api/v1/workers/[workerId]/thread-context` 现在都要求有效设备 token 或匹配登录会话
- 当前认证仍是 MVP：已有最小会话 Cookie，但还没有刷新令牌、跨端会话治理、吊销审计和 CSRF 防护
- 当前图片 / 视频入口会写入消息账本，但真实文件上传还没有接对象存储
- 当前采用“极轻云 + 本地设备端”的路线，云端只承载 Web、轻 API 和状态文件
- 服务器侧主 Agent 对话能否返回真实大模型回复，依赖被绑定设备的 `local-agent` 在线并能执行 `codex exec`；服务器本身不直接持有主 GPT 会话