feat: ship native boss android console

2026-03-26 23:16:56 +08:00
parent 90e904814d
commit 90cb6b7ff1
261 changed files with 40051 additions and 135 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,265 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Boss 控制台 MVP

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

-First, run the development server:
+## 先读哪里
+
+按这个顺序看，交接成本最低：
+
+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
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+构建态：

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+cd /Users/kris/code/boss
+npm run build
+npm start
+```

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+说明：

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

-To learn more about Next.js, take a look at the following resources:
+默认入口：

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- 登录页：[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)

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## 设备端本地服务

-## Deploy on Vercel
+手动启动：

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```bash
+cd /Users/kris/code/boss
+./scripts/start-local-agent.sh ./local-agent/config.example.json
+```

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+安装常驻 `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 会话