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. 先读顺序

README.md
docs/architecture/repo_map_cn.md
docs/architecture/current_runtime_and_deploy_status_cn.md
docs/architecture/api_and_service_inventory_cn.md
docs/architecture/enterprise_ai_ops_architecture_cn.md
docs/architecture/rbac_skill_regression_matrix_cn.md
docs/architecture/boss_server_connection_and_deploy_cn.md
docs/architecture/wechat_project_conversation_mapping_cn.md
docs/architecture/thread_context_budget_and_handoff_protocol_cn.md
docs/architecture/dependency_security_audit_cn.md
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-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-agent-ota.ts：boss-agent macOS 运行包 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/AccessManagementActivity.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 正常
GET/POST /api/v1/auth/sessions 正常，已支持基础跨端会话治理和单会话撤销
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
GET /api/v1/boss-agent/ota 与 GET /api/v1/boss-agent/ota/package 已接入 boss-agent Mac 端 OTA，要求设备 token；打包脚本会发布 boss-agent-mac-latest.zip/json
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 再追加汇总
当前 Boss APP 按“Codex 同一线程客户端”同步桌面记录：APP 直连线程和主 Agent 托管线程都会把用户原文镜像进目标 Codex rollout，供 Codex 桌面版打开/刷新该线程时看到同一段沟通记录；内部 prompt、调度字段和系统约束不得写入桌面可见记录
当前桌面实时性新增轻量刷新桥：镜像成功后 local-agent 会优先调用本机常驻 Codex Desktop Bridge endpoint，再由 bridge 打开 codex://threads/{threadId} 目标线程深链并发送一次应用刷新快捷键，让 Codex 桌面版切到目标线程后重新感知线程更新；endpoint 不可用时会回退到原命令式刷新。这条桥只做打开/刷新提示，不承担消息输入，失败也不能阻断主链。默认配置会在短暂失败时重试 2 次、间隔 120ms，并保留 deep link 与尝试次数，方便排查桌面端是否收到刷新提示。bridge 还提供本机 SSE：GET /api/v1/codex-desktop/events，只广播安全元数据；scripts/codex-desktop-event-consumer.mjs 已作为 Desktop 插件/IPC 的消费样例
当前还新增 scripts/codex-desktop-integration-probe.mjs 与 bridge GET /api/v1/codex-desktop/capabilities：用于自动探测当前 Codex Desktop 是否支持 codex://threads/{threadId} 这类稳定入口，并明确禁止把“修改 Codex.app 签名包体”作为支持能力
当前设备导入主链已经补到第一阶段：设备 heartbeat 可上报真实候选线程，系统会生成导入草稿；用户勾选后可生成导入决议，并把选中的线程真正落成聊天窗口
当前设备导入草稿不会再被旧 projects 字段绕过；只有 apply 之后，候选线程才会真正变成聊天窗口
当前设备导入 review 已经会留下 device_import_resolution master task 轨迹，但决议内容仍是服务端 heuristic 版，尚未真正交给 local-agent -> codex exec
Web 和原生 Android 当前都已经接上“新设备导入草稿 -> 勾选 -> 决议预览 -> 应用导入”的前台页面；已绑定生产设备继续保留 heartbeat 自动导入链路
原生首页的刷新失败策略当前已改成按当前 tab 独立判错，不会再因为 设备 / 设置 / OTA 的旁路请求失败把会话页刷新一并判成失败
当前量产方向已经明确为“Boss 企业控制面 + 可插拔执行协议”：多租户、权限、审批、审计、备份、回退和 Skill 治理由 Boss 承担，Codex App Server / Codex MCP / Codex CLI / Computer Use / 业务系统 API 都作为 provider 接入；详见 docs/architecture/enterprise_ai_ops_architecture_cn.md
当前 Codex App Server 已完成十一批接入：boss-agent 默认开启 local-agent/codex-app-server-runner.mjs 作为 Codex 绑定入口，优先走 codex app-server stdio，也可灰度连接 ws://127.0.0.1:<port> 或 unix://PATH 同机长驻 App Server；长驻连接支持 Authorization: Bearer <token>，配置上优先使用 codexAppServerAuthTokenFile。turn 启动前失败才回退 CLI，turn 启动后不重复执行；桌面远程控制默认先走 codex-computer-use，失败后回退 cua-driver-computer-use。2026-05-31 已按本机 codex-cli 0.135.0-alpha.1 生成协议快照 docs/protocol-snapshots/codex-app-server/0.135.0-alpha.1/，并把 turn/plan/updated、turn/diff/updated、item/started|completed、thread/started、item/*/requestApproval、item/autoApprovalReview/*、guardianWarning、serverRequest/resolved、item/fileChange/patchUpdated、thread/status/changed、thread/realtime/*、model/rerouted、thread/tokenUsage/updated、mcpServer/startupStatus/updated、remoteControl/status/changed、thread/goal/*、thread/settings/updated、thread/compacted、account/updated、account/rateLimits/updated、model/verification、warning、configWarning、deprecationNotice、ThreadItem.collabToolCall、ThreadItem.contextCompaction、mcpToolCall、dynamicToolCall、webSearch、imageView、imageGeneration、hook/started|completed、enteredReviewMode、exitedReviewMode、commandExecution、ThreadItem.plan、ThreadItem.reasoning.summary 归一到 Boss execution_progress 卡片；realtime 只保留状态、文本摘要和计数，运行状态只保留模型切换、上下文用量、MCP 状态和远控连接摘要，线程配置只保留目标、模型、审批、沙箱、协作模式和压缩状态，线程协作只保留工具名、状态、目标类型和智能体状态，工具活动只保留类型、名称、状态和安全摘要，图像生成只保留状态与安全文件名，钩子生命周期只保留事件名、处理器类型、状态、来源、执行模式和耗时，思考摘要只保留官方 summary 文本和状态，账号状态只保留认证方式、套餐、额度窗口、积分余额和模型校验摘要，不保存 SDP、音频原始数据、raw item、remote installationId、cwd、turnId、配置文件路径、collab 源/目标线程 ID、collab prompt、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning content、reasoning item id、imageGeneration revisedPrompt/result、hook sourcePath/statusMessage/entries 或未清洗密钥。heartbeat 已能缓存 model/list / skills/list / plugin/list / app/list / modelProvider/capabilities/read 的能力摘要；同批已补 turn/steer 活跃 turn 干预和 POST /api/v1/projects/[projectId]/thread-collaboration 服务端线程协作排队入口。
当前 boss-agent 已支持 Mac OTA：local-agent/boss-agent-ota-runner.mjs 默认开启，每 5 分钟检查服务端最新包；状态页可手动检查或下载并安装，安装时保留原绑定配置，只更新版本号和本机 runtime 路径。最新验证版本为 20260516221619，已在 MacBook Air macbook-air 上确认 OTA 下载校验、暂存、覆盖安装后不会误切到默认 config.cloud.json。正式分发脚本已预留 Developer ID 公证路径：BOSS_AGENT_NOTARIZE=1 配合 notary profile 或 Apple ID 凭据。
当前量产治理已补设备撤权和任务可靠性底座：revoke_device 会清空设备 token、标记离线并阻断 heartbeat / 任务认领 / Skill 同步 / 日志上报 / boss-agent OTA；MasterAgentTask claim 会记录 attempt 和 lease，运行中任务可按租约重试，超过上限转 timed_out，用户或管理员可通过 cancel 接口转 canceled 且迟到 complete 不覆盖终态。
当前群聊 dispatch_execution 完成回写已补幂等，重复完成不会再向群聊重复追加结果
当前已支持微信式消息转发：长按消息可直接 转发 / 多选 / 复制 / 删除，单条消息转发显示为普通转发消息，多条消息转发显示为聊天记录卡片
当前已支持聊天附件主链：原生聊天框左侧 + 会打开底部抽屉，支持图片 / 视频 / 文件发送；图片 / PDF / 文本默认自动进入主 Agent 附件分析，视频 / Office / 大文件默认手动触发
当前附件与存储配置页位于 我的 > 附件与存储：默认使用服务器文件存储，用户可按账号切到阿里 OSS 私有桶；下载链会优先使用附件上传时固化的 OSS 快照，避免用户后续改配置后旧附件失效
主 Agent 项目页会实时吸收 APP 端日志，用于边对话边指导 APK / Web 优化
移动端 UI 已去掉假的状态栏与桌面预览壳；底部一级导航固定在视口底部，返回逻辑不会再把 APP 根页直接弹回桌面
项目目标 支持用户编辑、主 Agent 复核、完成项自动划线
版本迭代记录 只读，由主 Agent 汇总
我的 根页当前保留 账号与安全 / 设置 / 运维与修复 / AI 账号 / 附件与存储 / Telegram 接入 / 技能 / 关于，其中 用户与权限 仅最高管理员可见
我的 > 账号与安全 已支持查看和撤销登录会话；最高管理员可管理全部活跃会话，子账号只能管理自己的会话
我的 > 用户与权限 与 Web /me/access 共用 /api/v1/admin/access，可创建子账号、分配设备 / 项目 / Skill 权限，并查看同名 Skill 跨设备聚合；PC 总后台已收敛到 https://admin.boss.hyzq.net/ 根路径，/admin 仅保留跳转兼容
多用户 / RBAC / Skill / 主 Agent 权限和多设备控制的集中状态、回归矩阵与缺口清单见 docs/architecture/rbac_skill_regression_matrix_cn.md
我的 > 主 Agent 提示词 / 记忆 当前可编辑管理员全局主提示词、用户主提示词、当前对话附加提示词，以及用户通用记忆 / 项目记忆
我的 > AI 账号 必须可查看和切换 主 GPT / 备用 GPT / API 容灾
我的 > 技能 必须按绑定设备展示 Skill，并支持一键复制调用语句
Skill 远程治理第一版已经接通最高管理员后端入口和设备端执行：GET/POST /api/v1/admin/skills/requests 可创建和查看 install / update / uninstall / rollback / version_lock 请求，local-agent 通过 claim / complete 认领执行并回写最新 Skill 清单。当前设备端已增加 source allowlist / trusted source、checksum / expectedChecksum sha256 校验、更新 / 卸载 / 回滚前备份和失败恢复；仍未做签名校验和依赖安装沙箱
设备 页当前只允许出现生产设备，旧演示脏数据不能回流到正式视图
登录后必须形成最小会话，受保护页面和核心 /api/v1/* 接口不能再裸奔
必须保留登录、注册、忘记密码和验证码入口

6. 当前技术路线

Web：Next.js 16.2.4 + 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.11（versionCode=24）

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

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":"krisolo","password":"<admin-password>","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、restore token 轮换、浏览器 CSRF 基础防护、子账号 MFA、基础跨端会话治理和后台高危动作审计；临时免验证登录默认关闭，只能通过 BOSS_AUTH_AUTO_LOGIN=1/true/yes 显式开启
当前已补“原生 restore token 自动恢复”，但这仍不是完整的多端会话系统
当前默认最高管理员账号是 krisolo，默认密码由线上初始化配置管理，并已绑定本机 Codex 节点
主 Agent 实时回复当前依赖被绑定设备的 local-agent 在线，并能在本机跑通 codex exec
API 容灾当前由用户在 APP 的 我的 > AI 账号 中自行配置 OpenAI API 账号
服务器默认验证码模式仍是 fixed，但验证码登录也必须先申请验证码，不允许只靠固定码直接登录
服务器邮件栈已部署完成，应用内也已经支持 email 模式，但默认开关还没切到 email
OTA 版本中心、检查更新、执行升级和 APK 包下载已接通，但当前仍是文件型状态驱动的 MVP
APP 实时日志同步、主 Agent 日志镜像、SSE 自动刷新和 Skill 同步页已经接通；日志检索已有基础分页，风险 SLA 通知账本已接入，外部通知渠道仍未做
设备导入主链当前已经具备后端闭环和 Web/Android 前台接线；主 Agent 理解同步已经避免未接管状态下主动问线程，后续重点是继续细化导入筛选规则和用户主动同步体验
数据库尚未替代文件存储；当前已补 BOSS_STATE_STORE=postgres 单行 JSONB 适配层、schema 和 scripts/boss-state-store-maintenance.mjs schema 校验 / 文件备份 / dry-run 迁移 / PostgreSQL 备份导出 / 备份恢复 / 文件回滚工具，但生产仍默认文件状态。PostgreSQL 路径必须显式设置 BOSS_STATE_STORE=postgres，真实连接 / 写入还必须设置 BOSS_DATABASE_URL。最高管理员后台已新增 GET/POST /api/v1/admin/backups 文件状态快照能力，可手动创建、列出和恢复快照，恢复前会自动生成 pre-restore 快照；文件状态写入层已默认开启自动 auto:writeState 历史快照
域名入口的代理 / 分裂 DNS 结构仍未完全摸清
当前只支持服务器文件存储和阿里 OSS，尚未接更多对象存储或更丰富的附件详情页
认证已有真实 session、restore token 轮换、单会话撤销、CSRF 基础防护和 MFA 开关，但还没有企业 SSO / IdP

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

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

24 KiB Raw Blame History Unescape Escape

Boss 项目 AI 交接总入口

1. 当前项目是什么

2. 先读顺序

3. 当前有效实现边界

4. 当前运行真相

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

6. 当前技术路线

7. 接手后的第一批验证

8. 当前已知未完成项

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

24 KiB

Raw Blame History