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-27）

本地：

• 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.2.1（versionCode=10）
• 当前 APK 已切到原生 Android 客户端：MainActivity + BossApiClient + 原生 XML 布局
• 当前原生活动页已经覆盖：会话首页、项目详情、项目目标、版本记录、消息转发、线程详情、设备详情、添加设备、账号与安全、设置、AI 账号、技能、运维中心、关于
• 当前原生一级体验已回退到微信式交互：会话 / 设备 / 我的 固定底部 tab，会话首页是简单聊天列表，项目详情页是聊天优先，只保留 项目目标 / 版本记录 两个轻入口
• 当前 设备 和 我的 根页已收口为简单列表；运维 / 审计 / 修复 不再出现在一级 我的，而是下沉到 关于 > 高级与调试
• 原生客户端当前直接调用 https://boss.hyzq.net 的 Boss API，不再打开 WebView
• 2.0.1 已修复华为真机上因 Theme.SplashScreen 与 AppCompatActivity 不兼容导致的启动闪退
• 2.1.0 已在本机连接的华为真机上完成签名包覆盖安装与启动复核，原生三栏入口和子活动页声明已全部接通
• 2.1.1 已补上原生 OTA 下载链路：关于页会直接请求受保护的 /api/v1/user/ota/package，下载完成后可拉起系统安装器
• 2.2.0 已把原生 UI 从控制台风格回退到微信式简单列表和聊天优先视图，并复核了设备页 / 我的页 / 深层高级入口
• 2.2.1 已继续补齐原生交互细节：聊天页发送后会先出现本地“发送中”气泡，关于页会展示 OTA 下载进度 / 重试 / 安装授权提示，根 tab 会记住用户上次停留位置并改成“再按一次返回进入后台”

本地启动

开发态：

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

构建态：

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/conversations
• 设备页：http://127.0.0.1:3000/devices

设备端本地服务

手动启动：

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

安装常驻 launchd：

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

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

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
• Android 微信式 surface contract：android/app/src/main/java/com/hyzq/boss/WechatSurfaceMapper.java
• Android 聊天页布局：android/app/src/main/res/layout/activity_project_chat.xml
• 服务器环境示例：.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 构建：

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

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

cd /Users/kris/code/boss
npm run aab: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
• npm run aab:release 会先准备本机 release keystore，再构建 signed release AAB，并发布到 public/downloads
• 最新 AAB 会同步到 public/downloads/boss-android-latest.aab
• 同时也会额外保留一份带版本号的 AAB：public/downloads/boss-android-v{versionName}-{flavor}.aab
• AAB 归档元数据会写入 public/downloads/boss-android-latest-aab.json
• 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，不再出现圆角矩形外壳
• 原生 Android 当前也和这套产品口径对齐：根页采用微信式简单列表，项目聊天页改成消息流优先，设备 / 我的 页不再展示控制台式统计卡片
• 原生聊天页当前会即时渲染本地发送中消息，并且只有在用户接近底部或本次发送是主动触发时才自动滚到底
• 登录成功后的进入首页链路已做稳态处理：会先确认 /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 密码会在下一次密码登录时自动迁移
• 原生 Android 当前把 ProjectForwardActivity / ThreadDetailActivity / OpsCenterActivity 等复杂能力下沉到二级或更深层入口，不再把线程预算 / 转发 / 运维说明堆在主聊天页和一级我的页
• 原生 OTA 当前除了整包下载和系统安装器拉起，还会在关于页保留本地下载状态；离开关于页再回来时，仍能看到进行中 / 失败 / 待授权 / 可安装状态
• Android 本地 Gradle 验证当前必须串行执行，避免并发 testDebugUnitTest / compileDebugJavaWithJavac / assembleDebug 相互踩坏中间产物
• 当前默认最高管理员账号：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 会话