krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/master-agent-controlled-evolution
boss/docs/architecture/ai_handoff_index_cn.md

238 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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/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 提示词 / 记忆` 当前可编辑管理员全局主提示词、用户主提示词、当前对话附加提示词，以及用户通用记忆 / 项目记忆
- `我的 > 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 为真相
- 每次改动都同步文档
- 只在有明确收益时再引入更重的基础设施
Reference in New Issue View Git Blame Copy Permalink