krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e6215211c56425b590c0169d8c8feed3093a6323
boss/docs/architecture/ai_handoff_index_cn.md

9.7 KiB
Raw Blame History

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

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/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/DeviceDetailActivity.java：原生设备详情和技能入口
  • android/app/src/main/java/com/hyzq/boss/AiAccountsActivity.java：原生 AI 账号管理页
  • android/app/src/main/java/com/hyzq/boss/OpsCenterActivity.java：原生运维 / 审计中心
  • 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 正常
  • 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 项目页会实时吸收 APP 端日志，用于边对话边指导 APK / Web 优化
  • 移动端 UI 已去掉假的状态栏与桌面预览壳；底部一级导航固定在视口底部，返回逻辑不会再把 APP 根页直接弹回桌面
  • 项目目标 支持用户编辑、主 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.1.1（versionCode=8）

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

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

7. 接手后的第一批验证

本地：

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

服务器：

"$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 管理仍未做
  • 数据库尚未替代文件存储
  • 域名入口的代理 / 分裂 DNS 结构仍未完全摸清
  • 图片 / 视频真实文件上传仍未接对象存储
  • 认证没有真实 session 和令牌吊销

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

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