# Boss 项目 AI 交接总入口

这份文档的目标是让另一个 AI 线程在不依赖当前对话上下文的情况下，直接接管 `/Users/kris/code/boss`。

## 1. 当前项目是什么

当前仓库已经落地了一个可运行的 Boss 控制台 MVP，包含：

- 一个基于 `Next.js App Router` 的移动端风格 Web 控制台
- 一个本地 `device-agent`
- 一个原生 Android 客户端，可直接构建 APK
- 一组已经落地的 `/api/v1/*` 聚合接口、线程预算接口和 SSE 出口
- 一套可工作的 `Caddy + systemd + launchd` 部署链路
- 已整理进仓库的 UI 原稿、架构文档、部署文档和交接提示词

## 2. 先读顺序

1. `README.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. `docs/architecture/wechat_project_conversation_mapping_cn.md`
7. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
8. `prompts/codex_fullstack_build_and_deploy_prompt_cn.md`
9. `docs/superpowers/specs/2026-04-16-master-agent-fast-path-design.md`
10. `docs/superpowers/specs/2026-04-16-master-agent-evolution-engine-design.md`

## 3. 当前有效实现边界

当前真正生效的内容只有这些：

- `src/app`：页面和 API
- `src/components`：共享 UI 和交互组件
- `src/lib/boss-data.ts`：当前状态模型和文件存储
- `src/lib/boss-auth.ts`：最小会话 Cookie 和页面 / API 鉴权辅助
- `src/lib/boss-device-auth.ts`：设备 token / 登录会话混合鉴权辅助
- `src/lib/boss-events.ts`：SSE 事件总线
- `src/lib/boss-master-agent.ts`：主 Agent 真实回复链路、Master Codex Node relay 与 API 容灾逻辑
- `src/lib/master-agent-evolution.ts`：主 Agent 自动进化引擎，负责 signal、proposal、rule 与 controlled / autonomous 模式
- `src/lib/boss-attachments.ts`：附件类型识别、分析状态决策和下载头
- `src/lib/boss-storage.ts`：附件存储抽象、配置校验和脱敏输出
- `src/lib/boss-storage-server-file.ts`：服务器文件存储上传 / 读取
- `src/lib/boss-storage-aliyun-oss.ts`：阿里 OSS 私有桶上传 / 签名下载
- `src/lib/boss-ota.ts`：APK OTA 产物定位与元数据读取
- `src/lib/boss-projections.ts`：当前聚合 BFF 投影视图
- `src/components/app-runtime.tsx`：APP 日志桥、SSE 刷新和 Skill 面板
- `local-agent/server.mjs`：设备端心跳和 thread-context 上报服务
- `local-agent/config.cloud.json`：本机常驻 agent 对接 `https://boss.hyzq.net` 的生产配置
- `local-agent/config.example.json`：本地 `127.0.0.1:3000` 回环开发配置
- `deployment`：部署配置
- `scripts`：启动和部署脚本
- `android`：原生 Android 客户端工程
- `android/app/src/main/java/com/hyzq/boss/MainActivity.java`：原生入口 Activity
- `android/app/src/main/java/com/hyzq/boss/BossApiClient.java`：原生 API 客户端
- `android/app/src/main/java/com/hyzq/boss/ProjectDetailActivity.java`：原生聊天优先项目页，只保留目标/版本轻入口
- `android/app/src/main/java/com/hyzq/boss/MasterAgentEvolutionActivity.java`：原生主 Agent 自动进化页，可查看信号/提案/规则并切换模式
- `android/app/src/main/java/com/hyzq/boss/ConversationInfoActivity.java`：原生微信式会话信息页，支持线程改名和发起群聊
- `android/app/src/main/java/com/hyzq/boss/GroupInfoActivity.java`：原生群资料页，支持群名修改与成员查看
- `android/app/src/main/java/com/hyzq/boss/GroupCreateActivity.java`：原生独立群聊创建页
- `android/app/src/main/java/com/hyzq/boss/ForwardTargetActivity.java`：原生微信式会话选择页，承接单条转发与多选合并转发
- `android/app/src/main/java/com/hyzq/boss/AttachmentComposerState.java`：原生附件发送确认规则与待上传附件模型
- `android/app/src/main/java/com/hyzq/boss/BossWindowInsets.java`：原生顶部安全区处理，负责把状态栏 / 刘海区让出来
- `android/app/src/main/java/com/hyzq/boss/DeviceDetailActivity.java`：原生设备详情与技能入口
- `android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java`：原生 AI 账号管理页
- `android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java`：原生运维 / 审计中心
- `android/app/src/main/java/com/hyzq/boss/WechatSurfaceMapper.java`：原生微信式 surface contract
- `android/app/src/main/res/layout/activity_project_chat.xml`：原生聊天页布局
- `android/signing/release-signing.properties.example`：release 签名模板

这些不是当前运行真相：

- `docs/source-material`
- `deploy`
- `src/boss_control`
- `src/boss_device_agent`

## 4. 当前运行真相

本地：

- Web 已可运行
- `GET /api/health` 正常
- `GET /api/v1/conversations` 正常
- `GET /api/v1/projects/master-agent` 正常，主 Agent 项目页已能看到 APP 实时日志
- `GET /api/v1/accounts` 正常，已返回主 GPT / 备用 GPT / API 容灾摘要
- `GET /api/v1/devices/mac-studio/skills` 正常
- `GET /api/v1/storage/config` 正常，已返回当前登录用户的附件存储模式和脱敏 OSS 摘要
- `POST /api/v1/storage/config/validate` 正常，已验证可校验并保存阿里 OSS 私有桶配置
- `POST /api/v1/projects/[projectId]/attachments` 正常，已支持图片 / 视频 / 文件上传与附件消息写入
- `POST /api/v1/projects/[projectId]/attachments/[attachmentId]/analyze` 正常，已支持手动触发主 Agent 附件分析
- `POST /api/v1/group-chats` 正常，已支持从会话首页直接发起独立群聊
- `GET /api/v1/projects/[projectId]/dispatch-plans` 正常，已支持读取群聊最新主 Agent 推荐下发方案
- `POST /api/v1/projects/[projectId]/dispatch-plans/[planId]/confirm` 正常，已支持把推荐目标确认成真正的线程执行单
- `GET /api/v1/devices/[deviceId]/import-draft` 正常，已支持读取设备导入草稿与最新决议
- `POST /api/v1/devices/[deviceId]/import-draft/select|review|apply` 正常，已支持设备候选线程勾选、导入决议和落地成真实聊天窗口
- `GET /api/v1/conversations/home` 正常，已支持会话首页使用“项目聚合 + 线程下钻”视图
- `GET /api/v1/conversation-folders/[folderKey]` 正常，已支持读取某个项目归档下的全部线程
- 这些设备导入接口当前仅允许 `highest_admin` 或设备所属账号访问
- `GET /api/v1/attachments/[attachmentId]/download` 正常，已支持会话鉴权下载和 task token 下载
- `POST /api/auth/login` 正常，会写入 `boss_session`
- `boss_session` 当前默认保持 30 天
- `GET /api/auth/session` 正常
- `POST /api/auth/restore` 正常，原生 Android 客户端可用 `restore token` 自动恢复登录态
- `GET /api/v1/app-logs` 正常，可按登录态分页读取 APP 日志
- `POST /api/v1/projects/master-agent/messages` 正常，已验证通过 `local-agent -> codex exec -> complete` 返回真实主 Agent 回复
- `GET /api/v1/user/ota/package` 正常，当前会返回最新 APK
- `npm run apk:release` 正常，已能输出 signed release APK
- 当前原生 Android 页面已覆盖会话、设备、我的三栏和主要二级页，不再依赖 WebView 承载业务页面
- 本地 `device-agent` 正常
- 本地 agent 手动 heartbeat 后会同时上报 `thread-context`
- 本地 agent 会递归扫描 `~/.codex/skills` 并同步设备 Skill
- 设备写接口 `POST /api/v1/app-logs`、`POST /api/v1/devices/[deviceId]/skills`、`POST /api/v1/workers/[workerId]/thread-context` 已加设备 token / 会话鉴权
- fixed 验证码 `000000` 已改成先申请再校验；`send-code` 会按用途校验账号是否存在
- `launchd` 常驻已安装

服务器：

- 服务器地址：`106.53.170.158`
- 用户：`ubuntu`
- 代码路径：`/opt/boss`
- `boss-web.service` 正常
- `caddy.service` 正常

域名：

- 服务器日志显示 `Caddy` 已为 `boss.hyzq.net` 成功获取证书
- 服务器本机 `dig` 已解析到 `106.53.170.158`
- 服务器本机 `--resolve` 打 `127.0.0.1:443` 能正常返回 `307 /auth/login`
- 当前本机网络虽然 `dig` 仍显示 `198.18.1.188`，但 `http://boss.hyzq.net` 已 `308`、`https://boss.hyzq.net` 已 `307 /auth/login`
- 当前本机和服务器本机访问 `https://boss.hyzq.net/api/health` 与 `https://boss.hyzq.net/api/v1/conversations` 都已返回正常数据
- 当前结论是：外部 HTTPS 现在可达，公网域名下的 Web API 也已经可用，但入口前面可能还有代理层或分裂 DNS，不要再沿用“443 未打通”的旧判断

## 5. 当前最重要的产品逻辑

- 一级导航固定：`会话 / 设备 / 我的`
- `会话` 页当前按“项目聚合 + 线程下钻”渲染聊天列表：单线程项目直接显示线程，多线程项目先显示文件夹归档，`主 Agent / 审计对话` 以普通置顶会话样式固定在最上面
- 单线程会话主标题显示线程名，第二行显示所属文件夹名，第三行显示最后一条消息预览，右下角显示后台活跃数量动态图标
- 单设备项目显示单头像，多线程群聊显示群聊式组合头像
- 项目聊天页当前已经改成聊天优先，只保留 `项目目标 / 版本记录` 两个轻入口；线程预算、handoff、运维与转发能力仍保留数据和深层活动页，但不再出现在主聊天面
- 线程改名当前遵循微信最新逻辑：从聊天页右上角进入会话信息页，再进行改名
- 当前已支持从单线程会话发起独立群聊：原会话保留，新群聊自动命名并可在群资料页改名
- 当前群聊编排主链已经补到第一阶段：群聊消息先进入主 Agent，主 Agent 生成推荐下发方案，用户确认后再创建执行单；执行完成后线程原始结果会回群，主 Agent 再追加汇总
- 当前设备导入主链已经补到第一阶段：设备 heartbeat 可上报真实候选线程，系统会生成导入草稿；用户勾选后可生成导入决议，并把选中的线程真正落成聊天窗口
- 当前设备导入草稿不会再被旧 `projects` 字段绕过；只有 `apply` 之后，候选线程才会真正变成聊天窗口
- 当前设备导入 `review` 已经会留下 `device_import_resolution` master task 轨迹，但决议内容仍是服务端 heuristic 版，尚未真正交给 `local-agent -> codex exec`
- Web 和原生 Android 当前都已经接上“新设备导入草稿 -> 勾选 -> 决议预览 -> 应用导入”的前台页面；已绑定生产设备继续保留 heartbeat 自动导入链路
- 原生首页的刷新失败策略当前已改成按当前 tab 独立判错，不会再因为 `设备 / 设置 / OTA` 的旁路请求失败把会话页刷新一并判成失败
- 当前群聊 `dispatch_execution` 完成回写已补幂等，重复完成不会再向群聊重复追加结果
- 当前已支持微信式消息转发：长按消息可直接 `转发 / 多选 / 复制 / 删除`，单条消息转发显示为普通转发消息，多条消息转发显示为聊天记录卡片
- 当前已支持聊天附件主链：原生聊天框左侧 `+` 会打开底部抽屉，支持图片 / 视频 / 文件发送；图片 / PDF / 文本默认自动进入主 Agent 附件分析，视频 / Office / 大文件默认手动触发
- 当前附件与存储配置页位于 `我的 > 附件与存储`：默认使用服务器文件存储，用户可按账号切到阿里 OSS 私有桶；下载链会优先使用附件上传时固化的 OSS 快照，避免用户后续改配置后旧附件失效
- 主 Agent 项目页会实时吸收 APP 端日志，用于边对话边指导 APK / Web 优化
- 移动端 UI 已去掉假的状态栏与桌面预览壳；底部一级导航固定在视口底部，返回逻辑不会再把 APP 根页直接弹回桌面
- `项目目标` 支持用户编辑、主 Agent 复核、完成项自动划线
- `版本迭代记录` 只读，由主 Agent 汇总
- `我的` 根页当前保留 `账号与安全 / 设置 / 运维与修复 / AI 账号 / 技能 / 关于`
- `我的 > 主 Agent 提示词 / 记忆` 当前可编辑管理员全局主提示词、用户主提示词、当前对话附加提示词，以及用户通用记忆 / 项目记忆
- `我的 > 主 Agent 自动进化` 当前可查看进化信号、待审批提案、已生效规则，并切换 `controlled / autonomous`
- 原生 Android 也已接上 `我的 > 主 Agent 自动进化` 与 `主 Agent 会话右上角 ... > 自动进化` 两个入口
- `我的 > AI 账号` 必须可查看和切换 `主 GPT / 备用 GPT / API 容灾`
- `我的 > 技能` 必须按绑定设备展示 Skill，并支持一键复制调用语句
- `设备` 页当前只允许出现生产设备，旧演示脏数据不能回流到正式视图
- 登录后必须形成最小会话，受保护页面和核心 `/api/v1/*` 接口不能再裸奔
- 必须保留登录、注册、忘记密码和验证码入口

## 6. 当前技术路线

- Web：`Next.js 16.2.1 + React 19`
- 数据：当前是文件型持久化 `data/boss-state.json`
- 状态写入：串行事务队列 + 原子写入 + `.bak` 备份恢复
- device-agent：原生 Node HTTP 服务
- 部署：`systemd + Caddy + launchd`
- 邮件：`Postfix + Dovecot`
- Android：`AppCompatActivity + 原生 XML 布局 + HttpURLConnection`
- 原生登录恢复：`SharedPreferences + restore token`
- 当前最新原生 APK：`2.5.4`（`versionCode=17`）

当前不要误判成已经用了：

- PostgreSQL
- Redis
- NATS
- 真实用户会话系统

## 7. 接手后的第一批验证

本地：

```bash
cd /Users/kris/code/boss
npm install
npm run build
npm run lint
curl -sS http://127.0.0.1:3000/api/health
curl -sS -H 'Content-Type: application/json' -d '{"account":"17600003315","password":"boss123456","method":"password"}' http://127.0.0.1:3000/api/auth/login
curl -sS http://127.0.0.1:3000/api/auth/session
curl -sS http://127.0.0.1:3000/api/v1/conversations
curl -sS http://127.0.0.1:3000/api/v1/projects/master-agent
curl -sS http://127.0.0.1:3000/api/v1/devices/mac-studio/skills
curl -I http://127.0.0.1:3000/api/v1/user/ota/package
curl -sS http://127.0.0.1:4317/health
curl -sS http://127.0.0.1:4317/api/v1/skills
curl -sS -X POST http://127.0.0.1:4317/api/v1/heartbeat
npm run apk:debug
```

服务器：

```bash
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" health
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status boss-web --no-pager"
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status caddy --no-pager"
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/health"
"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "curl -sS http://127.0.0.1:3000/api/v1/conversations"
```

## 8. 当前已知未完成项

- 认证仍是 MVP 级别：虽然已有最小会话 Cookie，但还没有刷新令牌、跨端会话治理和 CSRF 防护
- 当前已补“原生 restore token 自动恢复”，但这仍不是完整的多端会话系统
- 当前默认最高管理员账号是 `17600003315`，默认密码 `boss123456`，并已绑定本机 Codex 节点
- 主 Agent 实时回复当前依赖被绑定设备的 `local-agent` 在线，并能在本机跑通 `codex exec`
- API 容灾当前由用户在 APP 的 `我的 > AI 账号` 中自行配置 `OpenAI API` 账号
- 服务器默认固定验证码仍是 `000000`
- 服务器邮件栈已部署完成，应用内也已经支持 email 模式，但默认开关还没切到 email
- OTA 版本中心、检查更新、执行升级和 APK 包下载已接通，但当前仍是文件型状态驱动的 MVP
- APP 实时日志同步、主 Agent 日志镜像、SSE 自动刷新和 Skill 同步页已经接通，但日志检索、告警和远程 Skill 管理仍未做
- 设备导入主链当前已经具备后端闭环和 Web/Android 前台接线，后续重点改成继续细化导入筛选规则和主 Agent 理解策略，而不是再从 0 接页面
- 数据库尚未替代文件存储
- 域名入口的代理 / 分裂 DNS 结构仍未完全摸清
- 当前只支持服务器文件存储和阿里 OSS，尚未接更多对象存储或更丰富的附件详情页
- 认证没有真实 session 和令牌吊销

## 9. 继续开发时的工作原则

- 不要先重构，再理解现状
- 先以当前运行中的 MVP 为真相
- 每次改动都同步文档
- 只在有明确收益时再引入更重的基础设施