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

11 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/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/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 正常
  • 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 项目页会实时吸收 APP 端日志，用于边对话边指导 APK / Web 优化
  • 移动端 UI 已去掉假的状态栏与桌面预览壳；底部一级导航固定在视口底部，返回逻辑不会再把 APP 根页直接弹回桌面
  • 项目目标 支持用户编辑、主 Agent 复核、完成项自动划线
  • 版本迭代记录 只读，由主 Agent 汇总
  • 我的 根页当前保留 账号与安全 / 设置 / 运维与修复 / AI 账号 / 技能 / 关于
  • 我的 > 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.4.0（versionCode=12）

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

  • 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 为真相
  • 每次改动都同步文档
  • 只在有明确收益时再引入更重的基础设施