# 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/enterprise_ai_ops_architecture_cn.md`
6. `docs/architecture/rbac_skill_regression_matrix_cn.md`
7. `docs/architecture/boss_server_connection_and_deploy_cn.md`
8. `docs/architecture/wechat_project_conversation_mapping_cn.md`
9. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
10. `docs/architecture/dependency_security_audit_cn.md`
11. `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-06-03 已按本机 `codex-cli 0.136.0-alpha.2` 生成协议快照 `docs/protocol-snapshots/codex-app-server/0.136.0-alpha.2/`，并把 `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`、`windowsSandbox/setupCompleted`、`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 状态、远控连接摘要和 Windows 沙箱准备状态，线程配置只保留目标、模型、审批、沙箱、协作模式和压缩状态，线程协作只保留工具名、状态、目标类型、目标数量和智能体状态集合，工具活动只保留类型、名称、状态和安全摘要，图像生成只保留状态与安全文件名，钩子生命周期只保留事件名、处理器类型、状态、来源、执行模式和耗时，思考摘要只保留官方 summary 文本和状态，账号状态只保留认证方式、套餐、额度窗口、积分余额和模型校验摘要，不保存 SDP、音频原始数据、raw item、remote installationId、cwd、turnId、配置文件路径、collab 源/目标线程 ID、collab receiverThreadIds、collab prompt、agentsStates 私有消息、共享 Skill 根绝对路径、hook key/command/sourcePath/statusMessage/hash/error message、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning content、reasoning item id、imageGeneration revisedPrompt/result、hook sourcePath/statusMessage/entries、Windows sandbox sourcePath/samplePaths/本地绝对路径或未清洗密钥。heartbeat 已能缓存 `model/list / skills/list / skills/extraRoots/set / hooks/list / plugin/list / app/list / modelProvider/capabilities/read / experimentalFeature/list / collaborationMode/list / permissionProfile/list / mcpServerStatus/list / account/read / account/rateLimits/read / config/read / configRequirements/read / externalAgentConfig/detect / thread/list / thread/loaded/list / thread/turns/list` 的能力摘要；同批已补 `turn/steer` 活跃 turn 干预和 `POST /api/v1/projects/[projectId]/thread-collaboration` 服务端线程协作排队入口。MCP、权限、账号、配置、外部 Agent、线程、turn、Hook、Skill extra roots、运行事件、扩展事件、线程生命周期和流式增量 discovery 只保留安全摘要，不保存 resource URI、权限文件规则、工具参数、邮箱、完整 config、本地路径、迁移描述、turn id、turn items、用户正文、模型输出、hook 命令、共享 Skill 根绝对路径、原始增量文本、命令输出、推理正文、文件输出或 token。
- 第十九批另补 `threadActionSummary` 线程操作能力摘要：设备详情页会显示 archive / unarchive / fork / compact / rollback / rename / metadata / steer / interrupt / shell / unsubscribe 等能力分组；该字段只读，不在 heartbeat 中调用任何会改变线程状态的 App Server API。
- 第二十批另补 `pluginGovernanceSummary` 插件治理能力摘要：设备详情页会显示 install / uninstall / read / skill-read / share 等能力分组；该字段只读，不在 heartbeat 中调用任何插件安装、卸载或共享写 API。
- 第二十一批另补 `accountGovernanceSummary / configGovernanceSummary` 账号与配置治理能力摘要：设备详情页会显示 login / logout / token refresh / add credits nudge / config write / MCP reload / Skill config write 等能力分组；这些字段只读，不在 heartbeat 中调用任何账号或配置写 API。
- 第二十二批另补 `fileSystemGovernanceSummary / commandSessionSummary` 文件系统与命令会话治理能力摘要：设备详情页会显示 file read/write/remove/watch 与 command stdin / resize / terminate / stream 等能力分组；这些字段只读，不在 heartbeat 中调用任何文件读写或命令控制 API。
- 第二十三批另补 `externalAgentGovernanceSummary / marketplaceGovernanceSummary / experimentalFeatureGovernanceSummary` 外部 Agent 迁移、Marketplace 和实验特性治理能力摘要：设备详情页会显示 external-agent import、marketplace add/remove/upgrade 和 experimental feature enablement 等能力分组；这些字段只读，不在 heartbeat 中调用任何迁移导入、marketplace 写入或实验特性启用 API。
- 第二十四批另补 `reviewGovernanceSummary / windowsSandboxGovernanceSummary / fuzzyFileSearchSummary` 审查、Windows 沙箱和文件搜索事件能力摘要：设备详情页会显示 review start、Windows sandbox readiness/setup 和 fuzzy file search updated/completed 等能力分组；这些字段只读，不在 heartbeat 中调用任何审查启动、沙箱设置或文件搜索动作。
- 第二十五批另补 `mcpGovernanceSummary / userInteractionGovernanceSummary / guardianGovernanceSummary` MCP、用户交互和 Guardian 治理能力摘要：设备详情页会显示 MCP OAuth/resource/tool/elicitation、tool requestUserInput、Guardian denied action approval 和 permission request approval 等能力分组；这些字段只读，不在 heartbeat 中调用任何 MCP、用户输入或 Guardian 放行动作。
- 第二十六批另补 `runtimeEventSummary / extensionEventSummary / threadLifecycleEventSummary` 运行事件、扩展事件和线程生命周期事件能力摘要：设备详情页会显示 process output/exited、raw response completed、skills changed、plugin installed、thread started/closed/archived/unarchived/name updated 等能力分组；这些字段只读，不在 heartbeat 中主动触发进程、插件、Skill 或线程生命周期动作。
- 第二十七批另补 `streamDeltaEventSummary` 流式增量事件能力摘要：设备详情页会显示 agent delta、plan delta、reasoning delta、MCP progress、command output、terminal interaction 和 file output 等能力分组；该字段只读，不保存原始增量文本、命令输出、推理正文或文件输出。
- 当前任务执行态也已补 `executionProgress.streamEvents`：App Server runner 会把 agent / plan / reasoning / MCP / command / terminal / file 的流式 delta 归一成计数，Android 进度卡展示“流式增量”，不保存或渲染原始 delta、命令输出、终端输入、推理正文或文件输出。
- 当前 App Server 任务取消已从“服务端标记”升级为“真实 turn 中断”：`POST /api/v1/master-agent/tasks/[taskId]/cancel` 仍负责把任务置为 `canceled`，新增 `GET /api/v1/master-agent/tasks/[taskId]/control-state` 供设备端轮询；`local-agent` 在 App Server turn 启动后会按取消状态调用 `turn/interrupt`，并把 `interrupted` 作为干净取消处理，避免取消后长任务继续跑或被误写成失败日志。
- 当前已补 Codex App Server 受控线程回滚：`POST /api/v1/projects/[projectId]/thread-rollback` 会创建 `intentCategory=thread_rollback` 任务，`local-agent` 调用 `thread/rollback` 回滚目标线程最近 N 轮；该链路不启动新 turn，不把 thread/turn/items 原文写回 APP，只提示“线程历史已回滚”，且不会自动还原本地文件变更。
- 当前已补 Codex App Server 受控线程压缩：`POST /api/v1/projects/[projectId]/thread-compact` 会创建 `intentCategory=thread_compact` 任务，`local-agent` 调用 `thread/compact/start` 发起目标线程上下文压缩；该链路不启动普通 turn，不把 contextCompaction item 原文写回 APP，只提示“上下文压缩已发起”。
- 当前已补 Codex App Server 受控线程归档 / 恢复：`POST /api/v1/projects/[projectId]/thread-archive` 会创建 `intentCategory=thread_archive|thread_unarchive` 任务，`local-agent` 直接调用 `thread/archive` 或 `thread/unarchive`；该链路不启动普通 turn，不把 thread 原始字段写回 APP，只提示“线程已归档/已恢复”。
- 当前已补 Codex App Server 受控线程改名：`POST /api/v1/projects/[projectId]/rename` 在 `mode=thread` 且绑定真实 `codexThreadRef` 时，会在本地 Boss 改名后创建 `intentCategory=thread_rename` 任务，`local-agent` 直接调用 `thread/name/set`；该链路不启动普通 turn，不把 thread 原始字段写回 APP，只提示“已同步 Codex 线程名称”。设备离线、并发冲突或 App Server 不可用不会回滚 Boss 本地改名。
- 当前 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. 接手后的第一批验证

本地：

```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":"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
```

服务器：

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