krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: harden enterprise control plane

Browse Source
This commit is contained in:
AI Bot
2026-05-17 02:20:08 +08:00
parent 67511c31f4
commit e1aed590f8
112 changed files with 10977 additions and 2004 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/architecture/admin_refine_backoffice_cn.md
View File

@@ -26,14 +26,14 @@
边界：
- 现有 `/admin` 不删除，继续作为主站内 fallback。
- 旧 `/admin` UI 已删除，`/admin` 仅保留为跳转到根路径 `/` 的兼容入口；生产域名 `https://admin.boss.hyzq.net/` 直接承载新独立 PC 后台。
- 独立后台只消费 Admin BFF，不直接读取 `boss-state.json`。
- 独立后台当前复用 Boss Cookie 登录态，后续再绑定 `admin.boss.hyzq.net` 的独立部署。
- `/api/v1/admin/backoffice` 仍只允许 `highest_admin`，并过滤 `passwordHash`、`mfaSecret` 和 session token。
## 当前落地范围
- 新增 `/admin` 页面。
- `/admin` 页面收敛为兼容跳转，不再承载旧 Next 管理 UI。
- 新增 `/api/v1/admin/overview` 聚合接口。
- 新增 `/api/v1/admin/backoffice` 独立企业后台聚合接口。
- 新增 `/api/v1/admin/risks/actions` 风险处理动作接口。
@@ -122,8 +122,8 @@
## 权限边界
- `/admin` 页面要求登录。
- 非 `highest_admin` 只看到“仅最高管理员可用”提示。
- `/admin` 页面直接跳转根路径 `/`，生产根路径由 `admin.boss.hyzq.net` 站点内部 rewrite 到独立后台静态入口。
- 非 `highest_admin` 访问 `/enterprise-admin` 时只看到“仅最高管理员可用”提示。
- `/api/v1/admin/overview` 未登录返回 `401`，非最高管理员返回 `403`。
- `/api/v1/admin/risks/actions` 未登录返回 `401`，非最高管理员返回 `403`。
- `/api/v1/admin/risks/scan` 未登录返回 `401`，非最高管理员返回 `403`。

23
docs/architecture/ai_handoff_index_cn.md
View File

@@ -19,12 +19,13 @@
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/rbac_skill_regression_matrix_cn.md`
6. `docs/architecture/boss_server_connection_and_deploy_cn.md`
7. `docs/architecture/wechat_project_conversation_mapping_cn.md`
8. `docs/architecture/thread_context_budget_and_handoff_protocol_cn.md`
9. `docs/architecture/dependency_security_audit_cn.md`
10. `prompts/codex_fullstack_build_and_deploy_prompt_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. 当前有效实现边界
@@ -42,6 +43,7 @@
- `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 上报服务
@@ -105,6 +107,7 @@
- `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` 正常
@@ -149,6 +152,10 @@
- 当前设备导入 `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，turn 启动前失败才回退 CLI，turn 启动后不重复执行；桌面远程控制默认先走 `codex-computer-use`，失败后回退 `cua-driver-computer-use`。
- 当前 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 / 大文件默认手动触发
@@ -159,7 +166,7 @@
- `版本迭代记录` 只读，由主 Agent 汇总
- `我的` 根页当前保留 `账号与安全 / 设置 / 运维与修复 / AI 账号 / 附件与存储 / Telegram 接入 / 技能 / 关于`，其中 `用户与权限` 仅最高管理员可见
- `我的 > 账号与安全` 已支持查看和撤销登录会话；最高管理员可管理全部活跃会话，子账号只能管理自己的会话
- `我的 > 用户与权限` 与 Web `/me/access` 共用 `/api/v1/admin/access`，可创建子账号、分配设备 / 项目 / Skill 权限，并查看同名 Skill 跨设备聚合；PC `/admin` 已补公司停用、CSV/文本批量导入预览、重置密码、子账号 MFA、风险 SLA 通知派发、风险时间线和后台审计来源字段
- `我的 > 用户与权限` 与 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 容灾`
@@ -232,7 +239,7 @@ npm run apk:debug
- OTA 版本中心、检查更新、执行升级和 APK 包下载已接通，但当前仍是文件型状态驱动的 MVP
- APP 实时日志同步、主 Agent 日志镜像、SSE 自动刷新和 Skill 同步页已经接通；日志检索已有基础分页，风险 SLA 通知账本已接入，外部通知渠道仍未做
- 设备导入主链当前已经具备后端闭环和 Web/Android 前台接线；主 Agent 理解同步已经避免未接管状态下主动问线程，后续重点是继续细化导入筛选规则和用户主动同步体验
- 数据库尚未替代文件存储；当前已补 `BOSS_STATE_STORE=postgres` 单行 JSONB 适配层、schema 和 `scripts/boss-state-store-maintenance.mjs` 备份 / 迁移 / 回滚工具，但生产仍默认文件状态
- 数据库尚未替代文件存储；当前已补 `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

71
docs/architecture/api_and_service_inventory_cn.md
View File

@@ -25,7 +25,7 @@
- 构建脚本：`npm run admin:web:build`
- 数据入口：`GET /api/v1/admin/backoffice`
- 登录态：复用 `boss_session` HttpOnly Cookie
- 当前定位：平台侧 To B 总后台，面向公司、账号、设备、项目、Skill、风险与审计治理；现有 `/admin` 继续作为主站内 fallback
- 当前定位：平台侧 To B 总后台，面向公司、账号、设备、项目、Skill、风险与审计治理；生产入口为 `https://admin.boss.hyzq.net/` 根路径，Caddy 内部 rewrite 到 `/admin-web/index.html`，旧 `/admin` UI 已移除，仅作为跳转到根域的兼容入口
### 1.3 boss-android-native
@@ -117,6 +117,8 @@
- 当前 `RemoteRuntimeAdapter` 还负责拦截固定模式的线程内部环境提示；命中后会直接改写成失败，避免把只读/cwd 这类脏文本写进聊天记录
- 当前普通单线程 `conversation_reply` 在真正执行 `codex exec resume` 前，会先把 Boss 用户消息镜像进目标 Codex Desktop rollout；定位优先走 `state_5.sqlite`，不可用时回退扫描 `~/.codex/sessions`，并按 `sourceMessageId` 去重
- 当前 Codex Desktop 同步新增常驻刷新桥：`scripts/codex-desktop-refresh-bridge-daemon.mjs` 通过 launchd 监听 `127.0.0.1:4318`，暴露 `POST /api/v1/codex-desktop/refresh`、`GET /api/v1/codex-desktop/events`、`GET /api/v1/codex-desktop/events/recent` 和 `GET /api/v1/codex-desktop/capabilities`；`local-agent` 会优先调用 refresh endpoint，失败时回退到 `scripts/codex-desktop-refresh-hint.mjs` 命令式刷新。SSE 事件只包含线程引用、消息 ID、状态、deep link 等安全元数据，不包含用户正文或内部 prompt；`scripts/codex-desktop-event-consumer.mjs` 可作为 Desktop 插件/IPC 接入前的订阅 smoke；`scripts/codex-desktop-integration-probe.mjs` 负责只读探测 Codex.app 能力
- 当前新增 Codex App Server runner：`local-agent/codex-app-server-runner.mjs`。boss-agent 默认配置 `codexAppServerEnabled=true`，会接管 `conversation_reply / dispatch_execution`；它通过 stdio 启动 `codex app-server`，执行 `initialize -> thread/resume|thread/start -> turn/start`，并把 `item/agentMessage/delta` 或 `item/completed` 归一成 Boss 任务回复。turn 启动前失败可回退 CLI，turn 启动后失败不回退，避免重复执行。
- 当前 boss-agent Mac OTA 已接入：`local-agent/boss-agent-ota-runner.mjs` 会用设备 token 调 Boss 服务端 `/api/v1/boss-agent/ota` 检查最新 Mac 运行包，`/api/v1/boss-agent/ota/apply` 会下载 `boss-agent-mac-latest.zip`、校验 sha256、暂存安装 wrapper，并拉起本机安装器；安装脚本会保留绑定配置并只更新版本号与本机 runtime 路径。安装器会优先沿用当前 LaunchAgent active config，并保留所有 `config*.json`，避免多电脑场景中误绑定到默认设备配置。当前最新验证包为 `20260516221619`；构建脚本支持 `BOSS_AGENT_NOTARIZE=1` 的 Developer ID 公证路径。
- 当前 `local-agent` 还新增了两条统一电脑控制 runtime：
- `local-agent/browser-control-task-runner.mjs`
- `local-agent/computer-use-task-runner.mjs`
@@ -125,27 +127,33 @@
- 相关配置项：
- `browserControlEnabled / browserControlCommand / browserControlArgs / browserControlWorkdir / browserControlTimeoutMs`
- `computerUseEnabled / computerUseCommand / computerUseArgs / computerUseWorkdir / computerUseTimeoutMs`
- 当前仓库已自带最小 smoke runtime：
- `codexAppServerEnabled / codexAppServerCommand / codexAppServerArgs / codexAppServerWorkdir / codexAppServerTimeoutMs / codexAppServerFallbackToCli`
- `codexComputerUseEnabled / codexComputerUseCommand / codexComputerUseArgs / codexComputerUseWorkdir / codexComputerUseTimeoutMs / codexComputerUseFallbackToCua`
- 当前仓库已自带 browser smoke runtime、desktop Cua runtime 和旧 desktop smoke 兜底：
- `scripts/browser-control-smoke.mjs`
- `scripts/codex-computer-use-runtime.mjs`
- `scripts/cua-driver-computer-use-runtime.mjs`
- `scripts/computer-use-smoke.mjs`
- `scripts/browser-control-smoke.mjs` 当前已支持两段式最小真实动作：
- 能从目标 URL 拉取 HTML 标题并回写到 `replyBody / executionSummary`
- 在显式配置 opener 命令时可实际执行打开 URL
- `scripts/computer-use-smoke.mjs` 当前已支持识别常见桌面应用名，macOS 下默认用 `osascript` 激活目标应用，并支持把用户请求中的引号文本输入到当前前台应用、按需回车发送；同时保留 `open -a` 兜底，并会落盘结构化 artifact，便于后续真实 Computer Use runtime 复用同一回写协议
- `config.example.json / config.cloud.json` 现默认把这两条 smoke runtime 作为 browser/desktop 控制的推荐起步配置
- `scripts/codex-computer-use-runtime.mjs` 当前通过 `codex app-server` 发起 Codex Computer Use 桌面控制，是 boss-agent 的默认桌面控制入口；失败时由 `local-agent/computer-use-task-runner.mjs` 自动回退 CUA
- `scripts/cua-driver-computer-use-runtime.mjs` 当前通过外部 `cua-driver` 执行 macOS 桌面 GUI 控制：先 `launch_app`，再按返回窗口做 `get_window_state`，需要写入文本时调用 `type_text` 并再次观测；发送、提交、删除、支付等高风险动作默认返回 `needs_user_action`，不静默下发
- `scripts/computer-use-smoke.mjs` 当前已支持识别常见桌面应用名，macOS 下默认用 `osascript` 激活目标应用，并支持把用户请求中的引号文本输入到当前前台应用、按需回车发送；它保留为旧兜底和回归资产
- `config.example.json / config.cloud.json` 现默认把 browser smoke runtime 和 desktop Cua runtime 作为 browser/desktop 控制的推荐起步配置
- `config.example.json / config.cloud.json` 现同时默认把 `browserAutomationConnected / computerUseConnected` 置为 `true`，让前台设备详情默认按“这台 Mac 已具备浏览器控制 / 桌面控制能力”展示
- 这两条 smoke runtime 当前还会返回结构化字段：
- browser：`targetUrl / artifacts`
- desktop：`targetApp / typedText / artifacts`
- 这样前台与后续真实 runtime 可以共用同一套结果形态，而不需要等接入 Playwright / Computer Use 后再改返回协议
- heartbeat 的 `browserAutomation / computerUse` 能力上报会同时参考静态 connected 标记和 runtime 配置状态
- heartbeat 的 `browserAutomation / computerUse` 能力上报会同时参考静态 connected 标记和 runtime 配置状态；`codexAppServer` 能力上报会参考 feature flag 与 app-server 命令可执行性
### 1.5 Caddy
- 作用：反向代理和 HTTPS 自动续签
- 服务器服务名：`caddy.service`
- 配置文件：`deployment/Caddyfile`
- 当前站点：`boss.hyzq.net` 服务客户 Web / App API；`admin.boss.hyzq.net` 服务平台总后台。独立后台第一批仍未替换线上 `/admin`，后续部署完成后再把该域名切到 `apps/boss-admin-web` 静态产物
- 当前站点：`boss.hyzq.net` 服务客户 Web / App API；`admin.boss.hyzq.net` 根路径内部 rewrite 到 `/admin-web/index.html`，浏览器地址栏保持 `https://admin.boss.hyzq.net/`，作为平台级 To B 独立后台入口；旧 `/admin` 页面不再渲染旧 UI，只做兼容跳转到根路径
### 1.6 boss-server-debug skill
@@ -267,6 +275,7 @@
- `reclaim_account`：离职回收，停用账号、撤销活跃会话并清理设备 / 项目 / Skill 授权
- `upsert_account`：创建或更新子账号
- `set_account_status`：启用或停用子账号；停用时撤销该账号当前活跃会话，且禁止停用最高管理员账号
- `revoke_device`：吊销指定设备，立即清空设备 token、标记离线、写入 `device.revoked` 审计；旧 token 后续不能 heartbeat、领任务、同步 Skill、上传日志或拉取 boss-agent OTA
- `grant_device`：授予设备权限
- `grant_project`：授予项目权限
- `grant_skill`：授予 Skill 权限
@@ -300,7 +309,19 @@
- `resourceGroups`：设备、项目线程、Skill 聚合目录和授权记录
- `audit`：风险、通知、风险时间线和 `permissionAuditLogs`
- `yudaoMapping`：Boss 账本字段到后台概念的映射，用于后续数据库化或模块拆分
- 当前定位：供 `apps/boss-admin-web` 消费；现有 `/admin` 仍继续使用 `/api/v1/admin/overview` 和 `/api/v1/admin/access`
- 当前定位：供 `https://admin.boss.hyzq.net/ -> apps/boss-admin-web` 消费；旧 `/admin` UI 已下线，不再消费 `/api/v1/admin/overview` 和旧数据 provider
#### `GET/POST /api/v1/admin/backups`
- 用途：最高管理员做文件状态快照、查看可回退点和执行状态回退
- 权限：仅 `highest_admin`
- `GET` 返回：
- `status`：当前文件状态路径、备份目录、最近快照时间、可回退点数量和校验状态
- `snapshots[]`：快照 ID、创建时间、创建人、备注、大小、sha256 和 schema 版本
- `POST` 输入：
- `action=create_snapshot`：创建当前 `boss-state` 快照，可带 `reason`
- `action=restore_snapshot`：恢复到指定 `snapshotId`
- 当前行为：恢复前会自动创建 `pre-restore:<snapshotId>` 快照，避免误操作后无法回滚；文件状态写入层默认按 `BOSS_STATE_AUTO_BACKUP_INTERVAL_MS` 自动创建 `auto:writeState` 快照，并按 `BOSS_STATE_AUTO_BACKUP_KEEP` 保留；独立 PC 管理后台的“备份与回退”页已接入创建、刷新和恢复动作。
#### `POST /api/v1/admin/risks/scan`
@@ -308,6 +329,7 @@
- 权限：仅 `highest_admin`
- 当前行为：
- 扫描未关闭的 `opsFaults` 和 `threadContextAlerts`
- 同步检查运行态异常：在线设备 `Computer Use` 不可用会补 `BOSS.COMPUTER_USE.UNAVAILABLE` 运维故障，`boss-agent OTA` 失败日志会补 `BOSS_AGENT.OTA.FAILED` 运维故障
- 当 `slaDueAt` 已早于当前时间时，写入 `adminNotifications[]`
- 同一个 `riskId` 只生成一条 `risk_sla_overdue` 通知，重复扫描不会重复膨胀账本
- 生成新通知时发布 `project.context_risk.updated`
@@ -553,6 +575,10 @@
- 更新设备状态
- 若 `pairingCode` 合法，则 claim 设备绑定草稿并返回 token
- 若携带 `projectCandidates[]`，则会同步生成或刷新对应设备的 `deviceImportDraft`
- 当前保护：
- 已存在设备必须携带有效 `token` 或未过期 enrollment 的 `pairingCode`
- 未准备 enrollment 的新 `deviceId` 不能通过心跳自注册
- 已吊销设备返回 `DEVICE_REVOKED`，不会更新 `lastSeenAt / status / projects / projectCandidates`
#### `POST /api/projects/[projectId]/goals/[goalId]/toggle`
@@ -1113,6 +1139,20 @@
- 当前归档：发布脚本还会额外保留 `public/downloads/boss-android-v{versionName}-{flavor}.apk`
- 当前保护：要求有效 `boss_session`
#### `GET /api/v1/boss-agent/ota`
- 用途：被控电脑上的 boss-agent 用设备 token 检查 Mac agent 运行包 OTA
- 输入：`deviceId`、`currentVersion`
- 返回：`hasUpdate` 与最新 `boss-agent-mac-latest.zip` 的版本、大小、sha256、下载地址
- 当前保护：要求 `x-boss-device-token`
#### `GET /api/v1/boss-agent/ota/package`
- 用途：下载当前已发布的最新 boss-agent macOS 运行包
- 当前来源：`public/downloads/boss-agent-mac-latest.zip`
- 当前元数据：`public/downloads/boss-agent-mac-latest.json`
- 当前保护：要求 `x-boss-device-token` 与 `deviceId`
#### `GET /api/v1/ops/summary`
- 用途：读取运维 `fault / repair ticket / verification` 聚合数据
@@ -1148,6 +1188,7 @@
- 用途：由 local-agent 认领分配给本机的主 Agent 任务
- 当前保护：要求 `x-boss-device-token` 或匹配登录会话
- 当前可靠性：claim 会写入 `attemptCount / maxAttempts / claimedAt / lastClaimedAt / leaseExpiresAt`；运行中任务租约过期后可重试认领，超过最大次数会转为 `timed_out` 并更新进度卡；被吊销设备不能继续认领
#### `POST /api/v1/master-agent/tasks/[taskId]/complete`
@@ -1168,8 +1209,15 @@
- `taskType=dispatch_execution` 时，会把线程原始结果镜像回群聊，再追加一条主 Agent 汇总，并更新对应执行单状态
- `failed` 时写入 relay 失败消息，并更新 AI 账号健康状态
- 如果任务带有 `externalReplyTarget.provider=telegram`，完成后会尝试调用 Telegram Bot API 把 `replyBody` 回推到原始聊天
- 终态任务 `completed / failed / timed_out / canceled` 的迟到重复 complete 会直接返回当前任务，不再覆盖终态或重复写消息
- 对群聊分发推荐失败的情况，消息入口当前会额外写入一条 `system_notice`，把“没有真实线程”或“成员引用失效”明确回显给用户
#### `POST /api/v1/master-agent/tasks/[taskId]/cancel`
- 用途：取消仍在 `queued / running / needs_user_action` 的主 Agent 任务
- 权限：任务请求账号、`highest_admin`，或具备目标设备 `device.manage` 的账号
- 当前行为：任务转为 `canceled`，写入 `canceledAt / canceledBy / cancelReason`，清除租约；如果之后设备端迟到回写成功，服务端不会覆盖取消终态
#### `GET /api/v1/integrations/telegram`
- 用途：读取 Telegram Bot 接入配置
@@ -1402,6 +1450,15 @@
- `data/boss-state.json`
状态存储默认仍走文件模式。PostgreSQL 仅作为显式量产切换路径存在：必须设置 `BOSS_STATE_STORE=postgres`，涉及真实连接 / 写入的维护命令还必须设置 `BOSS_DATABASE_URL`。`scripts/boss-state-store-maintenance.mjs` 当前支持：
- `validate-schema`：校验 `scripts/postgres-state-schema.sql` 是否包含 `boss_state_snapshots`、`snapshot_key` 主键、`state JSONB` 和更新时间索引
- `backup-file / export-file`：在文件模式下导出当前状态文件备份
- `migrate-file-to-postgres --dry-run`：只校验文件状态和 schema，不连接数据库；正式迁移会 upsert 到 `boss_state_snapshots`
- `export-postgres-backup`：从 PostgreSQL 导出带元数据和 sha256 的 JSON 备份包
- `restore-postgres-backup`：把备份包或原始状态 JSON 恢复回 PostgreSQL，可先用 `--dry-run` 验证
- `rollback-postgres-to-file`：把 PostgreSQL 当前快照回写到文件，用于数据库切换失败后的文件模式回退
状态文件当前带有迁移前置元数据：
- `schemaVersion`：当前 BossState schema 版本

39
docs/architecture/codex_server_progress_card_cn.md
View File

@@ -1,10 +1,26 @@
# Codex Server 协议与 Boss 执行进度卡接入记录
更新时间：`2026-05-08`
更新时间：`2026-05-16`
## 1. Codex 最新开放协议结论
当前可作为 Boss 稳定集成入口的是 Codex CLI MCP server：
2026-05-16 的最新架构判断：Boss 后续优先围绕 Codex App Server 做深度接入，但当前生产链路仍保留 `codex exec resume`，`codex mcp-server` 作为兼容 provider 候选。
Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富客户端和产品级集成，覆盖：
- authentication
- conversation history
- approvals
- streamed agent events
- Thread / Turn / Item
- model/list、skills/list、plugin/list、app/list
- command execution、file change、tool input、MCP tool-call approvals
Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 `local-agent/codex-app-server-runner.mjs`，把 App Server 的 `thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed` 映射成 Boss 的普通任务完成回写；下一批再继续把 Approval、Skill、file changes 和更细粒度 progress 归一化为 Boss 自有的 `execution_progress / approval_card / change_set / risk_event / skill_capability`。
官方文档入口：`https://developers.openai.com/codex/app-server`
当前仍可作为 Boss 兼容集成入口的是 Codex CLI MCP server：
- 启动命令：`codex mcp-server`
- Inspector 调试：`npx @modelcontextprotocol/inspector codex mcp-server`
@@ -16,10 +32,12 @@
本机当前检测结果：
- 本机 `codex --version`：`codex-cli 0.114.0`
- npm 最新稳定包：`@openai/codex 0.129.0`
- npm alpha：`0.130.0-alpha.5`
- 本机 `0.114.0` 已支持 `codex mcp-server --help`，但落后于当前 `0.129.0` 的 app-server / protocol 拆分、ThreadStore、MCP turn metadata、plugin sharing 等新能力
- 本机 `codex --version`：`codex-cli 0.131.0-alpha.9`
- 本机 `codex app-server --help` 已可用；本机 help 当前显示 `--listen` 支持 `stdio://`、`unix://`、`unix://PATH` 和 `off`
- 官方文档仍提到 WebSocket 传输，但标注 experimental / unsupported；Boss 当前只把 `stdio` 作为默认接入，后续如要接 WebSocket 必须先做协议快照和灰度开关
- Boss 第一批只用 App Server 做任务级 provider，不直接复用 ChatGPT Mobile 到 Codex App 的官方 relay；官方移动控制链路仍属于 ChatGPT App 与 Codex App 同账号/工作区之间的产品能力，不是第三方 Boss 可以稳定依赖的私有通道
下一轮再核对版本时，不要只看 npm 包版本号；必须同时读取 App Server schema / TypeScript 定义，并把 protocol snapshot 保存到 `docs/protocol-snapshots/codex-app-server/<version>/`。
## 2. Boss 当前采用的接入策略
@@ -76,8 +94,13 @@ APP 展示结构对齐截图：
- Boss 消息账本新增 `execution_progress`
- Android 原生聊天页新增结构化进度卡
- local-agent 完成回写会补 Git diff、GitHub CLI 状态和产物名
- `local-agent` 新增 `Codex App Server` runner，boss-agent 默认打开；`conversation_reply / dispatch_execution` 会先尝试 App Server，任务尚未真正启动 turn 时允许回退 CLI，turn 已启动后不再重复下发，避免双写同一线程
- `local-agent` 新增 `Codex Computer Use -> CUA Driver` 桌面控制级 fallback：远程控制这台电脑时默认先通过 Codex Computer Use 执行，失败后再走 Boss 既有 CUA Driver runtime
- `device-heartbeat` 设备能力新增 `codexAppServer`，用于前台和后台知道该设备是否具备 App Server provider
后续建议按两步继续：
1. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的可选实现，先 feature flag 默认关闭，保留 `codex exec resume` 作为生产主链。
2. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
1. 把当前 runner 提升为完整 `CodexAppServerBackendAdapter`：继续补 Approval / file change / skill / app / browser / computer-use 事件映射，但保持 feature flag 默认关闭。
2. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
3. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
4. 建立协议快照目录和兼容测试：每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。

44
docs/architecture/current_runtime_and_deploy_status_cn.md
View File

@@ -1,6 +1,6 @@
# Boss 当前运行与部署状态
更新时间：`2026-04-27`
更新时间：`2026-05-16`
## 1. 本地状态
@@ -26,14 +26,17 @@
- 独立企业后台 BFF：`GET http://127.0.0.1:3000/api/v1/admin/backoffice`
- 管理后台授权接口：`GET/POST http://127.0.0.1:3000/api/v1/admin/access`
- 管理后台风险 SLA 扫描接口：`POST http://127.0.0.1:3000/api/v1/admin/risks/scan`
- 管理后台状态备份与回退接口：`GET/POST http://127.0.0.1:3000/api/v1/admin/backups`，仅 `highest_admin` 可用；支持创建状态快照、列出快照和恢复到指定快照，恢复前会自动创建 pre-restore 快照。文件状态写入层已默认开启自动快照，可用 `BOSS_STATE_AUTO_BACKUP_INTERVAL_MS` 和 `BOSS_STATE_AUTO_BACKUP_KEEP` 调整频率与保留数量
- OTA 包下载接口：`GET http://127.0.0.1:3000/api/v1/user/ota/package`
- boss-agent Mac OTA 接口：`GET http://127.0.0.1:3000/api/v1/boss-agent/ota?deviceId=...&currentVersion=...` 与 `GET http://127.0.0.1:3000/api/v1/boss-agent/ota/package`
- 本地 agent 健康检查：`http://127.0.0.1:4317/health`。当前这台开发机的 `launchd` 常驻已经恢复，`/health` 可在数十毫秒内返回，并且在手动 heartbeat 执行期间也不会再被 Codex 线程扫描卡死
- 本地 Skill 扫描接口：`http://127.0.0.1:4317/api/v1/skills`
- 本地 agent 手动 heartbeat：`POST http://127.0.0.1:4317/api/v1/heartbeat`
- `launchd` 已安装：`~/Library/LaunchAgents/com.hyzq.boss.local-agent.plist`
- 当前执行底座抽象层已落地在 `src/lib/execution/`，并已补齐 `ExecutionBackend / PromptAssembler / PermissionPolicy / RemoteRuntimeAdapter / OrchestrationBackend` 默认实现
- 当前生产主链仍然沿用 `local-agent -> codex exec resume -> /api/v1/master-agent/tasks/[taskId]/complete`，执行底座重构以“先抽象、不改行为”为准
- 当前 Codex server 调研结论已记录在 `docs/architecture/codex_server_progress_card_cn.md`：官方稳定入口是 `codex mcp-server` 的 MCP 协议，本机 `codex-cli 0.114.0` 已支持该命令但落后于 npm 最新 `0.129.0`；Boss 当前先保留 `codex exec resume` 主链，并新增 `execution_progress` 结构化进度卡作为 APP 可见执行态
- 当前 Codex server 调研结论已记录在 `docs/architecture/codex_server_progress_card_cn.md`：长期优先方向更新为 `Codex App Server -> CodexMcpBackendAdapter -> codex exec resume` 的分层 provider 策略；当前 boss-agent 默认打开 `Codex App Server` runner 作为 Codex 绑定入口，Boss 仍保留 `codex exec resume` 兜底，并继续用 `execution_progress` 结构化进度卡作为 APP 可见执行态
- 当前量产 B+ 架构开发文档已新增：`docs/architecture/enterprise_ai_ops_architecture_cn.md`。该文档把 PPT 中的主 Agent / 业务 Agent / 老板端 / 经理端 / 员工端 / 治理层 / 系统层 / 设备层 / 执行层 / 接入层整理成后续产品架构约束，并明确数据库备份、业务回退、Codex 协议扩展和 Skill 治理方向；它是规划文档，不代表当前全部已落地
- 当前 `claw-code` 已以最小 `ClawBackendAdapter` 形式接入执行底座，但默认关闭；只有显式配置 `BOSS_CLAW_*` 且可用性探测通过时，`master-agent` 当前对话中才会出现并允许选择 `claw-runtime`
- 当前已新增最小 `Telegram Gateway`：Boss 当前可直接暴露 Telegram webhook，把 Telegram 私聊或受控群聊文本桥接进 `master-agent` 或按群 / Topic 路由到指定 Boss 项目，并在主 Agent 异步任务完成后自动回推 Telegram；配置入口已接到 Web `/me/telegram` 和原生 Android `我的 > Telegram 接入`
- 如果历史上已经保存过 `backendOverride=claw-runtime`，但当前 `Claw Runtime` 不可用，运行时会自动回退到默认后端，并在 Web/Android 前台给出明确原因
@@ -47,10 +50,15 @@
- 当前 `conversation_reply / dispatch_execution` 的线程执行结果会先经过 `RemoteRuntimeAdapter` 标准化；如果线程返回的是固定模式的内部环境提示（如“当前会话环境只读 / cwd …”），会直接转成失败，不再把原文写回会话消息
- 当前设备模型已支持同一台 Mac / Windows 同时接入 Codex `GUI + CLI` 双能力；Web / Android 设备详情页都会展示两种能力状态，并允许切换默认执行模式
- 当前同项目 `GUI / CLI` 并行写入风险已接入项目/文件夹级冲突控制：默认阻断，用户只能对当前异常项目/文件夹选择 `禁止 / 允许本次 / 永久放行`
- 当前已补上“Boss 统一电脑控制中枢”第二批本地 runtime：主 Agent 已能把聊天请求识别为 `discussion_only / project_development / browser_control / desktop_control`；`browser_control / desktop_control` 已能作为正式 `MasterAgentTask` 入队，并返回 `executionMode / riskLevel / requiresConfirmation` 元数据给前台；本机 `local-agent` 现已把 `browser-control-task-runner.mjs / computer-use-task-runner.mjs` 升级成外部 runtime 桥，并默认带上 `scripts/browser-control-smoke.mjs / scripts/computer-use-smoke.mjs` 作为 smoke 执行器，后续只需要替换配置就能接真实 browser automation 与 computer use runtime
- 当前已补上“Boss 统一电脑控制中枢”第二批本地 runtime：主 Agent 已能把聊天请求识别为 `discussion_only / project_development / browser_control / desktop_control`；`browser_control / desktop_control` 已能作为正式 `MasterAgentTask` 入队，并返回 `executionMode / riskLevel / requiresConfirmation` 元数据给前台；本机 `local-agent` 现已把 `browser-control-task-runner.mjs / computer-use-task-runner.mjs` 升级成外部 runtime 桥，并默认带上 `scripts/browser-control-smoke.mjs / scripts/cua-driver-computer-use-runtime.mjs` 作为 browser / desktop 起步执行器
- 当前这条电脑控制链先只按 macOS 交付：`browser_control / desktop_control` 任务会写入 `controlPlatform=macos` 和 `computerUseProvider`，其中浏览器控制默认 `openai-computer-use`，桌面 GUI 控制默认 `codex-computer-use`；`local-agent` 会先调用 Codex Computer Use，失败后自动回退 `cua-driver-computer-use`。`local-agent` 下发 runtime stdin 时也会携带同一组字段，桌面 dialog guard 只保留 macOS adapter，Windows 分支不进入当前生产链路
- 当前这两条控制链的 `control_summary` 已能回写结构化目标信息：browser 会保留 `targetUrl`，desktop 会保留 `targetApp`，Android 聊天窗口会在控制结果卡片里直接显示执行目标
- 当前 `scripts/browser-control-smoke.mjs` 已提升到“最小真实浏览器探测”：如果目标 URL 可访问，会抓取页面 `<title>` 并回写结果；`scripts/computer-use-smoke.mjs` 也已升级为 macOS 默认 `osascript` 激活应用、引号文本输入、按需回车发送、`open -a` 兜底和 artifact 回写，因此 Boss App 里的 browser/desktop 控制消息都已开始返回真实执行结果而不是固定 smoke 文案
- 当前本机 `local-agent` 默认 heartbeat 已把 `browserAutomation / computerUse` 两项能力视为“已接通起步版 runtime”，因此 Boss 前台设备能力会直接显示这两条链路在线；如果后续需要临时关闭，可在 `local-agent/config.cloud.json` 里单独下掉对应 connected 标记或 runtime 命令
- 当前 `scripts/browser-control-smoke.mjs` 已提升到“最小真实浏览器探测”：如果目标 URL 可访问，会抓取页面 `<title>` 并回写结果；`scripts/codex-computer-use-runtime.mjs` 会通过 Codex App Server 发起 Codex Computer Use 执行；`scripts/cua-driver-computer-use-runtime.mjs` 作为 fallback 接入 `cua-driver` 的 macOS 窗口级控制能力，默认执行 `launch_app -> get_window_state`，并支持安全范围内的引号文本写入；涉及发送、提交、删除、支付等动作时默认返回确认卡，不直接执行高风险提交
- 当前 boss-agent 已补 Mac OTA：`scripts/package-boss-agent-mac-runtime.sh` 会生成 `dist/boss-agent-mac-runtime-{version}.zip`，并同步发布 `public/downloads/boss-agent-mac-latest.zip/json`；本机 `local-agent` 默认每 5 分钟检查一次，可在 boss-agent 状态页手动“检查更新 / 下载并安装”。安装采用“下载校验 -> 写入暂存 wrapper -> 拉起 install.command”的安全路径，失败不会覆盖当前运行版本。正式分发脚本已支持 `BOSS_AGENT_NOTARIZE=1 + BOSS_AGENT_NOTARY_PROFILE` 的 Developer ID 公证路径，本地开发默认仍可 ad-hoc / Apple Development 签名。
- 当前最新 boss-agent Mac 包版本为 `20260516221619`，已部署到 `https://boss.hyzq.net/api/v1/boss-agent/ota` 并在局域网 MacBook Air `macbook-air` 上完成真实 OTA 下载、sha256 校验、暂存、覆盖安装和 up-to-date 检查：安装后 `config.installed.json` 仍保持 `deviceId=macbook-air`、账号 `krisolo`、版本 `20260516221619`，`launchd` 状态为 running。
- 当前安装器已做多电脑绑定保护：`install.command` 会保留所有 `config*.json` 并优先沿用当前 launchd active config；底层 `scripts/install-local-launchagent.sh` 在无显式参数时也会优先读取现有 LaunchAgent 的配置路径，再回退自定义设备配置，避免多台 Mac 重装/OTA 时误切到默认 `config.cloud.json`。
- 当前 Cua runtime 已补上 launchd 友好的可执行文件发现：除 `PATH` 外会主动查找 `~/.local/bin/cua-driver` 和 `/Applications/CuaDriver.app/Contents/MacOS/cua-driver`；如果 `launch_app` 对已运行 App 返回 not found，会兜底走 `list_apps -> list_windows -> get_window_state` 复用现有窗口
- 当前本机 `local-agent` 默认 heartbeat 已把 `browserAutomation / computerUse` 两项能力视为“已接通起步版 runtime”，因此 Boss 前台设备能力会直接显示这两条链路在线；`codexAppServer` 能力只有在显式打开 App Server runner 且本机 `codex` 命令可执行时才会上报在线；如果后续需要临时关闭，可在 `local-agent/config.cloud.json` 里单独下掉对应 connected 标记或 runtime 命令
本地已知运行方式：
@@ -101,16 +109,17 @@ cd /Users/kris/code/boss
- `npm start`、服务器 `systemd` 与远端 `npm run build` 当前都显式设置了 `BOSS_RUNTIME_ROOT`，避免 `process.cwd()` 在 standalone / 服务器构建阶段误扫描整个仓库
- `next.config.ts` 当前已把 `deployment / docs / design / local-agent / prompts / scripts / android` 等目录排除出 standalone tracing，服务器端构建不会再把非运行时资产卷进 `.next/standalone`
- `data/boss-state.json` 的写入已经改成串行事务队列、原子替换和 `.bak` 备份恢复，`heartbeat` 与 APP 日志并发写入已复核通过
- `data/boss-state.json` 当前额外具备自动历史快照：每次写入后按 `BOSS_STATE_AUTO_BACKUP_INTERVAL_MS` 节流写入 `data/backups/state-snapshot-*.json`，元数据标记 `actorAccount=system / reason=auto:writeState`，管理后台可直接作为回退点查看和恢复
- `BossState` 当前新增 `schemaVersion / migratedAt` 元数据和 `migrateBossState` 迁移入口；读取旧的无版本状态时会补齐当前 schema，并规范化 `accountDeviceGrants / accountProjectGrants / accountSkillGrants / skillLifecycleRequests / permissionAuditLogs`
- 这只是正式数据库迁移前置层，当前生产读写仍然是 `data/boss-state.json`，尚未完成 PostgreSQL / Redis / 其他 DB 落地
- 当前登录成功后会写入 `boss_session` Cookie；`会话 / 设备 / 我的 / 线程` 页面以及主要 `/api/v1/*` 路由都要求有效会话
- 当前 `boss_session` 默认保持 30 天，`Set-Cookie` 已验证为 `Max-Age=2592000`
- 原生 Android 客户端当前会把登录返回的 `boss_session / restore token / account` 落到 `SharedPreferences`，并在 APP 启动时通过 `/api/auth/restore` 自动补回会话；已本地验证“登录 -> 取 restore token -> restore 接口恢复”链路
- 当前多用户 / RBAC 第一阶段已落地：状态文件新增 `accountDeviceGrants / accountProjectGrants / accountSkillGrants / skillCatalog / skillLifecycleRequests / permissionAuditLogs`，非最高管理员访问 `devices / conversations / projects / messages / device skills / state` 时都会先走 `src/lib/boss-permissions.ts` 和 session-aware projections 过滤
- 当前最高管理员授权管理接口已落地：`GET/POST /api/v1/admin/access` 可以查看脱敏账号、公司、设备、项目、Skill、授权、权限模板和审计日志，并支持公司管理、公司启用/停用、账号/设备归属、批量导入预览、批量导入子账号、重置子账号密码、离职回收、创建/更新子账号、启用/停用子账号、授予设备/项目/Skill 权限、套用权限模板、撤销授权；停用公司会禁用该租户普通子账号并撤销会话，停用 / 回收 / 重置账号也会撤销该账号当前活跃会话，普通账号访问返回 `403`
- 当前 To B 管理后台第一版可操作面已经落地：Web `/admin` 仅 `highest_admin` 可进，包含 `总览 / 账号与授权 / Skill 治理` 三个页签；总览使用 `/api/v1/admin/overview`，账号与授权复用 `/api/v1/admin/access`，Skill 治理复用 `/api/v1/admin/skills/requests`；公司聚合优先使用显式 `adminCompanies`，未绑定时才回退账号域名。
- 当前企业级后台独立化第一批已开始落地：新增 `apps/boss-admin-web` 作为 Vue + Vite + Ant Design Vue 独立 PC 后台骨架，新增 `/api/v1/admin/backoffice` 作为 YuDao/Vben 风格 BFF；现有 `/admin` 暂保留为主站 fallback，`admin.boss.hyzq.net` 后续再切到独立后台静态产物。
- 当前后台风险处理接口已落地：`POST /api/v1/admin/risks/actions` 仅 `highest_admin` 可用，支持对 `ops_fault` 指派负责人、设置 SLA、确认、关闭、创建或复用修复工单，对 `thread_context_alert` 指派负责人、设置 SLA、确认和关闭；`POST /api/v1/admin/risks/scan` 会扫描超时 SLA 并幂等写入 `adminNotifications`，管理后台总览会展示开放风险通知；不支持的风险类型会明确返回 `RISK_ACTION_UNSUPPORTED`。
- 当前最高管理员授权管理接口已落地：`GET/POST /api/v1/admin/access` 可以查看脱敏账号、公司、设备、项目、Skill、授权、权限模板和审计日志，并支持公司管理、公司启用/停用、账号/设备归属、设备吊销、批量导入预览、批量导入子账号、重置子账号密码、离职回收、创建/更新子账号、启用/停用子账号、授予设备/项目/Skill 权限、套用权限模板、撤销授权；停用公司会禁用该租户普通子账号并撤销会话，停用 / 回收 / 重置账号也会撤销该账号当前活跃会话，吊销设备会清空设备 token、置离线并阻断 heartbeat / 任务认领 / Skill 同步 / 日志上报 / boss-agent OTA，普通账号访问返回 `403`
- 当前旧 Web `/admin` 管理 UI 已下线：`src/components/admin/boss-admin-app.tsx` 和旧 data provider 已移除，`/admin` 现在只做兼容跳转到根路径 `/`。
- 当前企业级后台独立化第一批已部署到云：`apps/boss-admin-web` 作为 Vue + Vite + Ant Design Vue 独立 PC 后台，静态产物位于 `/admin-web/index.html`；`admin.boss.hyzq.net` 根路径由 Caddy 内部 rewrite 到该静态入口，不再跳转到 `/enterprise-admin`。
- 当前后台风险处理接口已落地：`POST /api/v1/admin/risks/actions` 仅 `highest_admin` 可用，支持对 `ops_fault` 指派负责人、设置 SLA、确认、关闭、创建或复用修复工单，对 `thread_context_alert` 指派负责人、设置 SLA、确认和关闭；`POST /api/v1/admin/risks/scan` 会扫描超时 SLA 并幂等写入 `adminNotifications`，并会把 Computer Use 不可用、boss-agent OTA 失败等运行态异常补成可治理 `opsFaults`，管理后台总览会展示开放风险通知；不支持的风险类型会明确返回 `RISK_ACTION_UNSUPPORTED`。
- 当前权限审计查询第一版已落地：`GET /api/v1/audits/permission-logs` 仅 `highest_admin` 可读，支持按 `action / actorAccount / targetAccount / deviceId / projectId / skillId / cursor / limit` 查询 `permissionAuditLogs`，并实时返回短时间大量授权、Skill lifecycle 失败、过期授权仍存在、admin route 拒绝访问等 deterministic 风险摘要；后台 mutation 审计已支持 `ipAddress / userAgent / requestId / beforeJson / afterJson`，其中重置密码会记录安全化前后快照；Web `/me/ops/audit` 会向最高管理员展示最近权限审计和风险摘要
- 当前 Skill 远程治理第一版可执行链路已落地：`GET/POST /api/v1/admin/skills/requests` 仅允许 `highest_admin` 创建和查看 `install / update / uninstall / rollback / version_lock` 请求；设备端通过 `/api/v1/devices/[deviceId]/skill-requests/claim` 和 `/complete` 认领回写，local-agent 默认每 5 秒执行本机 Skill 安装 / 更新 / 卸载 / 回滚 / 版本锁，并同步最新 Skill 清单。远程安装或带 `sourceUrl` 的更新必须命中本机 `skillLifecycleAllowedSources` 或 `skillLifecycleTrustedSources`；配置为空时不允许远程新来源安装，但保留既有本地 Skill 的更新 / 回滚 / 卸载 / 版本锁。携带 `checksum / expectedChecksum` 的请求会校验 `manifest.json` 或 `SKILL.md` 的 sha256，更新 / 卸载 / 回滚前会写入 `skillsDir/.boss-skill-backups` 并在失败时尽量恢复
- 当前授权管理前台已接入：Web `/me/access` 与原生 Android `我的 > 用户与权限` 仅最高管理员可见，可创建子账号、授权设备/项目/Skill、套用 `只读观察员 / 项目开发者 / 设备操作者` 模板、查看同名 Skill 跨设备聚合并撤销单条授权
@@ -237,14 +246,16 @@ cd /Users/kris/code/boss
- 当前 `local-agent` 已能回写带 `dispatchExecutionId / targetProjectId / targetThreadId / rawThreadReply` 的任务完成载荷，群聊分发执行结果不再只停留在主 Agent 队列
- 当前 `local-agent` 对 `conversation_reply` 任务会优先使用 `codex exec resume <targetCodexThreadRef>`，只有缺失真实线程引用时才退回 `--ephemeral`
- 当前已绑定真实 `codexThreadRef` 的普通单线程聊天，会在 `local-agent` 执行 `codex exec resume` 前，先把 Boss 用户消息镜像写入对应 Codex Desktop rollout；这样 APP 发起的消息也能进入桌面版同一线程历史，并按 `sourceMessageId` 去重。rollout 定位优先使用 `state_5.sqlite`，状态库不可用或索引缺失时回退扫描 `~/.codex/sessions`；写入后会尽量刷新 `threads.updated_at / updated_at_ms / has_user_event`，再通过 `codex://threads/{threadId}` 深链提示桌面版打开目标线程
- 当前 `local-agent` 已新增 `Codex App Server` provider：boss-agent 默认配置 `codexAppServerEnabled=true`，`conversation_reply / dispatch_execution` 会先通过 `codex app-server` 的 stdio JSON-RPC 恢复或创建线程，再下发 `turn/start` 并收集流式 agent 回复；如果 App Server 在 turn 启动前失败，默认允许回退到 `codex exec resume`，如果 turn 已经启动则不再回退，避免同一轮用户消息被重复执行。桌面控制另有 `codexComputerUseEnabled=true`，默认先走 Codex Computer Use，再回退 CUA Driver。
- 当前 `local-agent` 对 `dispatch_execution` 任务会按 `orchestrationBackendId` 分流：默认走 `codex exec resume`；当任务显式选择 `omx-team` 且本机 `omxEnabled + omxCommand/omxArgs` 可用时，会改走 `OMX Team Runtime` JSON 协议执行并回写 `rawThreadReply / replyBody`
- 当前 `local-agent` 会在 Codex 任务完成时回传 `executionProgress`：服务端把同一任务的进度卡从 queued / running 更新到 completed / failed，Android 原生聊天页会显示“进度 / 分支详情 / 生成结果 / 后台智能体”，其中 Git diff、GitHub CLI 可用性和产物名由本地 agent 补齐
- 当前 `MasterAgentTask` 已具备服务端租约和取消基础状态机：claim 会写入 `attemptCount / maxAttempts / leaseExpiresAt`，运行中任务租约过期后可被重新认领，超过重试上限会转 `timed_out`；`POST /api/v1/master-agent/tasks/[taskId]/cancel` 会把任务转 `canceled`，迟到的成功 complete 不会覆盖终态
- 当前 `local-agent` 对 `browser_control / desktop_control` 已从占位骨架升级成外部 runtime 桥：当本机配置了 `browserControlEnabled + browserControlCommand` 或 `computerUseEnabled + computerUseCommand` 时，会把标准化 JSON 请求透传给外部进程，并解析单行 JSON 结果；未启用时会 fail closed，返回明确的 runtime disabled 错误，不再假装执行成功
- 远程电脑控制链路当前已有可复用压测基线：`npm run stress:remote-control` 可按参数压测 `local-agent -> MasterAgentTask -> browser_control / desktop_control runtime -> complete 回写` 全链路；`npm run stress:remote-control:ci` 固定 120 条链路任务和 360 条 runtime 并发任务，并用 p95 延迟预算判断是否退化。压测报告可通过 `--report-json=PATH` 落盘，便于后续接入真实 macOS AX / Windows UIA helper 后复用同一套稳定性判断。
- 当前历史脏群如果不再包含真实线程成员，群聊消息不会再表现成“无响应”；服务端会在群内追加明确 `system_notice`，提示先重新添加线程成员
- 当前设备导入决议已经升级成真正通过 `local-agent -> codex exec -> /complete` 回写的主 Agent 决议链；Web 和 Android 前台都会在 `pending_resolution` 阶段显示审核任务状态，并在任务完成后自动刷新出正式导入建议
- 当前 `local-agent` 已改成先启动本地 `4317` 健康监听，再异步跑首次 heartbeat 和 task poll，避免控制面短时阻塞时本地健康探针不可用
- 当前 heartbeat 上报 `browserAutomation / computerUse` 能力时，不再只看静态 `browserAutomationConnected / computerUseConnected` 布尔值；如果本机已经配置可执行的 browser/computer runtime，也会自动把对应能力标记成 connected
- 当前 heartbeat 上报 `browserAutomation / computerUse / codexAppServer` 能力时，不再只看静态 connected 布尔值；browser/computer 会参考 runtime 配置状态，Codex App Server 会参考 `codexAppServerEnabled` 和本机 app-server 命令可执行性
- Codex 项目/线程扫描当前已搬到 worker 线程执行，避免 `.codex/logs_1.sqlite` 和 `state_5.sqlite` 的同步扫描阻塞主线程健康接口
- 当前 `local-agent` 的任务完成回写已通过 `RemoteRuntimeAdapter` 标准化，`conversation_reply / dispatch_execution` 的完成载荷会先做统一归一化，再进入主 Agent 完成路由
- 原生 Android 当前对 `master-agent` 聊天不再依赖长时间同步等待；发送后会先显示“主 Agent 思考中”，右上角改成微信式 `...` 菜单，菜单项包含 `模型 / 推理强度 / 会话信息 / 刷新`
@@ -275,7 +286,7 @@ cd /Users/kris/code/boss
- `boss-web` 当前通过 `npm start` 启动
- 实际监听端口为 `3000`
- `boss-web.service` 显式设置了 `BOSS_STATE_FILE=/opt/boss/data/boss-state.json`
- `Caddy` 反代 `127.0.0.1:3000`；`boss.hyzq.net` 服务客户 Web / App API，`admin.boss.hyzq.net` 作为平台总后台独立 PC 入口并把根路径跳转到 `/admin`
- `Caddy` 反代 `127.0.0.1:3000`；`boss.hyzq.net` 服务客户 Web / App API，`admin.boss.hyzq.net` 作为平台级 To B 独立后台入口并把根路径内部 rewrite 到 `/admin-web/index.html`
- 服务器上存在 `gptpluscontrol-boss-caddy-reconcile.timer`，会周期性用 `/home/ubuntu/build/gptpluscontrol/deploy/server/caddy.boss_hyzq_net.gptpluscontrol.conf` 重写 `/etc/caddy/Caddyfile` 和 `/opt/boss/deployment/Caddyfile`；以后改 Caddy 入口必须同步更新这份 canonical，否则会重新生成重复站点块并导致 Caddy reload 失败
- `Postfix` 监听 `25 / 465 / 587`
- `Dovecot` 监听 `993`
@@ -296,12 +307,12 @@ cd /Users/kris/code/boss
- 服务器本机 `dig +short boss.hyzq.net` 返回 `106.53.170.158`
- 服务器本机访问 `http://boss.hyzq.net` 会被 `308` 跳转到 `https://boss.hyzq.net`
- 服务器本机执行 `curl --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net -I` 返回 `307` 并跳转到 `/auth/login`
- 当前 `admin.boss.hyzq.net` 用于平台总后台，应用根路由会在该 host 下把已登录用户送到 `/admin`，未登录用户送到 `/auth/login`
- 当前 `admin.boss.hyzq.net` 用于平台级 To B 独立后台入口，站点根路径直接承载新 PC 后台；`/admin` 不再渲染旧 UI，只保留跳转到根路径的兼容入口
同时也确认了这些事实：
- 当前本机网络 `dig +short boss.hyzq.net` 仍返回 `198.18.1.188`
- 当前本机网络 `dig +short admin.boss.hyzq.net` 暂无 A 记录；需要在 DNSPod 增加 `admin -> 106.53.170.158`
- 当前本机网络 `dig +short admin.boss.hyzq.net` 已返回 `106.53.170.158`
- 当前本机网络 `curl -I http://boss.hyzq.net` 返回 `308`
- 当前本机网络 `curl -I https://boss.hyzq.net` 返回 `HTTP/2 307`，并跳转到 `/auth/login`
- 当前本机网络 `curl https://boss.hyzq.net/api/health` 返回 `{"ok":true,"service":"boss-web",...}`
@@ -346,7 +357,7 @@ cd /Users/kris/code/boss
- Android 本地 Gradle 验证当前必须串行执行；如果并发跑 `testDebugUnitTest / compileDebugJavaWithJavac / assembleDebug`，会导致中间产物互踩并出现假失败
- 聊天附件当前已经支持真实上传、消息落账本、受保护下载和原生打开；默认后端为服务器文件存储，可按用户切到阿里 OSS 私有桶
- 企业认证默认值已收紧：`POST /api/auth/login` 默认不再允许临时免验证登录，只有显式设置 `BOSS_AUTH_AUTO_LOGIN=1/true/yes` 才会开启开发兜底。
- 状态存储现在通过 `src/lib/boss-state-store.ts` 抽象，默认继续使用 `data/boss-state.json`；设置 `BOSS_STATE_STORE=postgres` 时必须同时配置 `BOSS_DATABASE_URL`，schema 见 `scripts/postgres-state-schema.sql`。
- 状态存储现在通过 `src/lib/boss-state-store.ts` 抽象，默认继续使用 `data/boss-state.json`；只有显式设置 `BOSS_STATE_STORE=postgres` 才会进入 PostgreSQL 路径，真实连接 / 写入还必须同时配置 `BOSS_DATABASE_URL`。schema 见 `scripts/postgres-state-schema.sql`，生产切换前需先跑 `validate-schema`、文件备份、`migrate-file-to-postgres --dry-run`、PostgreSQL 备份导出和恢复演练。
- 认证已补 CSRF 基础防护、restore token 轮换、账号锁定和子账号 MFA 开关；后续仍可继续补更完整的企业 IdP / SSO
- 邮件对外正式投递仍缺少 DNS / 信誉相关的最终收口，例如 SPF、DKIM、DMARC、MX 与退信策略
- 外部真实邮箱的 end-to-end 收件链路还没有在生产账号上完成最终验收
@@ -363,7 +374,10 @@ 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
node scripts/boss-state-store-maintenance.mjs backup-file --dry-run
node scripts/boss-state-store-maintenance.mjs migrate-file-to-postgres --dry-run
node scripts/boss-state-store-maintenance.mjs validate-schema
BOSS_STATE_STORE=postgres BOSS_DATABASE_URL="$BOSS_DATABASE_URL" node scripts/boss-state-store-maintenance.mjs migrate-file-to-postgres --dry-run
BOSS_STATE_STORE=postgres BOSS_DATABASE_URL="$BOSS_DATABASE_URL" node scripts/boss-state-store-maintenance.mjs export-postgres-backup --output /tmp/boss-postgres-backup.json --dry-run
BOSS_STATE_STORE=postgres BOSS_DATABASE_URL="$BOSS_DATABASE_URL" node scripts/boss-state-store-maintenance.mjs restore-postgres-backup --input data/boss-state.json --dry-run
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

463
docs/architecture/enterprise_ai_ops_architecture_cn.md Normal file
View File

@@ -0,0 +1,463 @@
# Boss 企业 AI 运营中枢量产架构开发文档
更新时间：`2026-05-17`
## 1. 文档定位
这份文档把 `outputs/boss-product-intro-image2-full-raster.pptx` 里的产品架构、此前确认的量产 B+ 方案、以及 Codex App Server 最新开放协议思路统一成后续开发约束。
当前结论：Boss 不能只做一个“手机控制 Codex”的工具，而要升级成企业级 AI 运营中枢。Boss 负责组织、权限、任务、审计、数据安全、回退和跨设备协作；Codex、Computer Use、Skill、业务系统和第三方 Agent 都只是可替换执行能力。
本文件描述的是量产目标架构，不代表当前所有能力都已经落地。当前运行真相仍以 `docs/architecture/current_runtime_and_deploy_status_cn.md` 为准。
## 2. 来源材料
- 产品 PPT：`outputs/boss-product-intro-image2-full-raster.pptx`
- PPT 抽图校对目录：`outputs/pptx-architecture-read/slides`
- Codex App Server 官方文档：`https://developers.openai.com/codex/app-server`
- 当前 Boss 运行文档：`docs/architecture/current_runtime_and_deploy_status_cn.md`
- 当前 API 与服务清单：`docs/architecture/api_and_service_inventory_cn.md`
## 3. 产品总目标
Boss 的产品目标是把主 Agent、业务 Agent、组织角色、真实电脑、企业系统和 Skill 连接成可执行的企业管理系统。
PPT 中的核心判断需要进入产品开发主线：
- AI 已经能对话，但企业执行还没有被完整接管。
- 真正的成本不在模型本身，而在重复沟通、人工汇总、跨系统搬运和不可追踪的执行过程。
- Boss 的价值不是再做一个聊天机器人，而是让经营目标变成可拆解、可审批、可执行、可追踪、可复盘、可回退的闭环。
- 企业级 AI 必须先可控，再谈自动化。
## 4. 采用方案 B：Boss 企业控制面 + 可插拔执行协议
量产版本默认采用方案 B。
方案 B 的定义：
- Boss 是企业级控制面和数据事实源。
- Codex App Server、Codex MCP、Codex CLI、Computer Use、CUA Driver、Browser Automation、业务系统 API、Skill Runtime 都作为执行 provider 接入。
- 所有 provider 的原始事件必须先归一化为 Boss 自有事件和消息模型，再进入 APP、Web 管理后台、审计日志和回退系统。
- UI、权限、审计、备份、任务 SLA、风险处置和企业账号体系不能直接依赖某一个 provider 的私有字段。
选择方案 B 的原因：
- 企业客户最关心的是权限、审批、审计、稳定性、数据边界和可回退，不是某个单一执行引擎的能力展示。
- Codex 协议未来会持续变化，Boss 必须通过适配层快速跟进，而不是把协议字段写死到业务模型里。
- Boss 还需要支持我们自研的 Computer Use、未来的企业系统 API、Telegram/飞书/微信入口、Skill 分发和多租户后台，单独围绕 Codex 建模会限制长期扩展。
## 5. 方案 C 的优劣势
方案 C 指把 Codex App Server 作为更核心的数据和执行事实源，让 Boss 尽量贴近 Codex 原生 Thread、Turn、Item、Approval、Skill、Plugin 和 App Server event。
优势：
- 最接近 Codex 原生体验，线程、实时事件、审批、Skill、命令执行和文件变更可以更快跟随官方能力。
- APP 与 Codex 桌面端的同线程实时同步理论上更顺，重复实现更少。
- Codex 新增功能时，Boss 可以更快暴露给用户。
劣势：
- 业务核心会强绑定 Codex 协议，协议变更会直接冲击 Boss 的权限、审计、回退和消息账本。
- 企业级多租户、子账号授权、跨公司隔离、平台总后台、Skill 分配和数据留存不能完全交给 Codex 原生模型。
- 非 Codex 执行能力会变成二等能力，比如自研 Computer Use、业务系统 API、Telegram/飞书入口和后续企业 OA 集成。
- 数据自动备份和业务级回退会受限于 Codex 本地会话存储语义，不能满足 To B 生产级治理。
最终策略：
- 不采用方案 C 作为总架构。
- 在执行层内部吸收方案 C 的优点，优先新增 `CodexAppServerBackendAdapter`。
- Boss 数据模型保持独立，Codex App Server 只作为强执行 provider 和实时事件来源。
## 6. 多层级协作关系
PPT 第 3、4、5、8、9 页确定的协作链路必须成为产品模型的骨架。
### 6.1 组织层级
| 层级 | 角色 | 主要职责 | 可见范围 |
| --- | --- | --- | --- |
| 平台最高管理员 | Boss 平台运营方 | 创建企业、开通老板账号、查看全局风险、处理服务异常、管理套餐和授权 | 全平台治理数据，不默认看企业业务内容明细 |
| 企业老板端 | 企业超级管理员 | 看全局目标、成本、现金流、风险和最终结果；通过主 Agent 问询公司执行状态 | 本企业全局 |
| 经理端 | 部门或项目负责人 | 接收目标、拆解任务、审批异常、追踪团队进度、协调资源 | 授权团队、部门、项目 |
| 员工端 | 具体执行人员 | 处理具体任务、补充判断、上传材料、确认结果 | 自己任务和授权上下文 |
| 系统端 | Boss 控制面 | 维护账号、设备、权限、SOP、审批、审计、日志、备份和回退 | 按租户和权限隔离 |
### 6.2 Agent 层级
| 层级 | Agent | 职责 |
| --- | --- | --- |
| 调度层 | 主 Agent | 理解目标、判断权限、拆解任务、分配资源、汇总结果、协调多线程/多设备/多业务 Agent |
| 执行层 | 业务 Agent | 按 SOP 执行业务流程，如销售、客服、财务、HR、项目、行政、运维 |
| 设备层 | 本地 Agent | 接入真实电脑、Codex、Computer Use、浏览器、文件、系统权限和本地 Skill |
| Provider 层 | 执行 provider | Codex App Server、Codex CLI/MCP、CUA Driver、Browser Automation、业务系统 API、Skill Runtime |
### 6.3 主 Agent 与业务 Agent 分工
主 Agent 负责“为什么做、谁来做、能不能做”：
- 理解业务目标和约束条件。
- 拆解任务、里程碑和依赖关系。
- 判断账号、设备、项目、Skill 和数据访问权限。
- 选择合适业务 Agent、设备 Agent 或执行 provider。
- 在关键节点请求用户、经理或审批人确认。
- 汇总执行结果、风险、阻塞和下一步动作。
业务 Agent 负责“按 SOP 把事情做完”：
- 销售 Agent：线索跟进、商机管理、合同执行、回款跟踪。
- 客服 Agent：客户咨询、工单处理、服务跟进、满意度管理。
- 财务 Agent：费用报销、预算管理、账务处理、财务分析。
- HR Agent：招聘管理、入职管理、考勤管理、绩效管理。
- 项目 Agent：项目计划、进度跟踪、风险管理、交付验收。
- 行政 Agent：采购管理、资产管理、会议管理、用品管理。
- 运维 Agent：巡检、告警、故障复盘和修复建议。
## 7. 标准执行闭环
所有企业动作都应尽量落到同一条闭环：
1. 用户提出经营目标或执行请求。
2. 主 Agent 将自然语言目标拆成任务、里程碑、依赖和风险。
3. 系统检查账号、设备、项目、Skill、SOP 和数据权限。
4. 经理或授权人确认边界、资源、预算和高风险动作。
5. 业务 Agent 或设备 Agent 按 SOP 执行。
6. 员工只处理例外、补充材料、做判断和确认结果。
7. 系统回写过程记录、权限记录、结果记录和异常记录。
8. 主 Agent 形成复盘、版本记录、项目目标更新和下一步建议。
这条闭环必须沉淀四类记录：
- 权限记录：谁在何时对哪些内容拥有什么操作权限。
- 过程记录：任务流转、操作步骤、审批意见和执行过程。
- 结果记录：关键输出、指标达成、交付物和数据回写。
- 异常记录：异常识别、处理过程、原因分析和改进措施。
## 8. 治理能力必须前置
PPT 第 8 页强调“AI 执行必须先可控，再谈自动化”。量产版本的功能优先级必须体现这一点。
| 治理能力 | 产品要求 |
| --- | --- |
| RBAC 角色权限 | 老板、经理、员工、子账号、设备、项目、Skill 和数据权限必须可裁剪 |
| 审批与确认 | 高风险任务必须进入人工确认，不允许 AI 越权操作 |
| 审计日志 | 记录任务来源、执行过程、结果回写、异常原因和审批链 |
| 账号与设备治理 | 管理 AI 账号、真实电脑、本地 Agent、Skill 能力和授权状态 |
| 数据边界 | 按企业、部门、项目、账号隔离上下文，越权数据不展示 |
| SLA 与风险处置 | 异常任务、离线设备、执行失败、超时任务必须进入风险台 |
## 9. 量产数据安全与自动备份机制
当前文件型 `data/boss-state.json` 只能支撑 MVP，量产必须迁移到数据库和可回退的数据架构。
### 9.1 数据事实源
量产推荐：
- PostgreSQL 作为主业务库。
- 对象存储保存附件、截图、执行产物、日志归档和备份包。
- Redis 或队列系统只做缓存、锁和异步任务，不作为最终事实源。
- 每一个重要状态变化都写入 append-only 事件账本。
核心原则：
- 普通业务表保存当前状态。
- 事件账本保存“发生过什么”。
- 审计表保存“谁允许了什么”。
- 快照表保存“某个时刻可以回到哪里”。
### 9.2 自动备份
必须具备：
- PostgreSQL WAL 归档和定时全量备份。
- 每日全量备份、小时级增量备份、关键变更前即时快照。
- 跨区域或独立对象存储备份。
- 备份加密、备份校验和定期恢复演练。
- 按企业租户拆分可导出数据包，便于企业级交付和迁移。
建议目标：
- RPO：普通业务不超过 15 分钟，关键企业客户可配置到 5 分钟。
- RTO：普通故障 1 小时内恢复，关键演示或生产客户 15 分钟内恢复核心链路。
### 9.3 业务级回退
量产回退不能只依赖数据库备份。必须提供业务级回退能力：
| 场景 | 回退方式 |
| --- | --- |
| 消息误删 | 软删除 + 会话级恢复 |
| 项目目标或版本记录误改 | 版本化保存 + 一键恢复上一版 |
| 权限误授权 | 授权变更事件可撤销，撤销后同步清理会话和任务上下文 |
| Skill 安装或升级失败 | 安装前备份、版本锁、回滚到上一可用版本 |
| 主 Agent 错误接管 | 关闭接管、取消 queued/running 主动任务、恢复原线程控制权 |
| Codex 开发任务误操作 | 执行前 checkpoint、Git 分支隔离、diff 审批、必要时 revert |
| Computer Use 错误点击 | 高风险动作前确认、动作录像/截图留档、支持人工中止 |
| 企业配置误改 | 配置快照 + 审计原因 + 指定时间点恢复 |
## 10. Codex 协议扩展策略
Codex App Server 官方文档明确了它面向深度产品集成，包含 authentication、conversation history、approvals 和 streamed agent events。它当前基于 JSON-RPC 形态暴露 Thread、Turn、Item、Approval、Skill、Plugin、App、MCP、文件系统和模型列表等能力。
Boss 后续要把 Codex App Server 当作优先升级方向，但不能把业务模型绑死在它的字段上。
### 10.1 Provider 抽象
新增或强化统一执行 provider 接口：
```text
Boss Task
-> ExecutionBackendSelector
-> CodexAppServerBackendAdapter
-> CodexMcpBackendAdapter
-> CodexCliExecBackendAdapter
-> NativeComputerUseBackendAdapter
-> BrowserAutomationBackendAdapter
-> BusinessSystemApiBackendAdapter
```
每个 provider 必须声明：
- `providerId`
- `protocolVersion`
- `capabilities`
- `riskPolicy`
- `approvalModes`
- `streamingModes`
- `rollbackSupport`
- `healthCheck`
- `fallbackProviderId`
### 10.2 事件归一化
Codex App Server 的原始事件不能直接进入前台 UI。必须先归一化为 Boss 事件：
| Codex 原始概念 | Boss 归一化概念 |
| --- | --- |
| Thread | ProjectConversation / CodexThreadRef |
| Turn | ExecutionTurn / UserRequest |
| Item | ExecutionItem / MessageSegment / ProgressStep |
| Approval Request | ApprovalCard |
| Command Execution | ExecutionStep |
| File Change | ChangeSet |
| Skill | SkillCapability |
| Plugin/App | ExternalCapability |
| Error | RiskEvent / TaskFailure |
### 10.3 版本兼容机制
每次 Codex 协议升级时必须走以下流程：
1. 拉取或生成当前 Codex App Server TypeScript / JSON Schema。
2. 保存到 `docs/protocol-snapshots/codex-app-server/<version>/`。
3. 自动生成 provider capability manifest。
4. 跑协议兼容测试，确认 Thread、Turn、Item、Approval、Skill、Plugin 和 model/list 是否仍能映射。
5. 新能力先挂 feature flag，不直接进入生产默认链路。
6. 对关键企业租户先做灰度，再全量开启。
### 10.4 禁止写死的内容
以下内容不得写死进业务逻辑或 UI：
- Codex CLI 输出 envelope。
- Codex Desktop 私有数据库字段。
- 某一个 Codex 版本的 stderr/stdout 文案。
- 某一个 App Server event 的完整原始字段。
- 本地线程文件路径。
- Codex 具体模型列表。
- Skill 的本地绝对路径。
允许写死的是 Boss 自己的领域模型、权限模型、审计模型和回退模型。
## 11. 进度卡与实时协作
PPT 强调从目标到结果的可追踪闭环，Codex App Server 又提供 streamed agent events。Boss 的聊天窗口必须把“正在做什么”表达为结构化进度，而不是刷屏输出过程噪音。
建议统一进度卡结构：
- 进度：计划、执行中、完成、失败、等待审批。
- 分支详情：Git 分支、diff 摘要、测试状态、生成产物。
- 生成结果：文档、APK、图片、代码文件、报告。
- 后台智能体：主 Agent、业务 Agent、Codex、explorer、Computer Use provider。
- 风险：权限不足、设备离线、测试失败、审批等待、回退点。
执行过程中的低价值输出默认折叠，只显示最终结果和关键节点。用户需要查看细节时再展开过程日志。
## 12. Skill 治理与共享
Skill 是 Boss 企业扩展性的关键能力，但不能只做本机目录同步。
量产 Skill 治理需要支持：
- 平台级 Skill 市场。
- 企业级私有 Skill 仓库。
- 按公司、部门、账号、设备、项目授权 Skill。
- Skill 安装、升级、回滚、版本锁。
- Skill 依赖、来源、checksum、签名和安全等级。
- Skill 使用审计和失败率统计。
- 多电脑共享 Skill，但执行时仍按设备本地能力和权限裁剪。
主 Agent 在选择 Skill 时，只能看到当前用户、当前企业、当前设备和当前项目被授权的 Skill。
## 13. 当前落地进度与量产剩余清单
本节用于承接当前开发状态。这里的“已落地”只表示代码和本地回归已具备，不代表已经完成生产灰度、客户验收或长期稳定性验证。
### 13.1 已落地的量产底座
| 方向 | 当前状态 | 关键文件 / 接口 |
| --- | --- | --- |
| 多租户与 RBAC | 已具备最高管理员、企业管理员、成员账号、公司归属、设备 / 项目 / Skill 授权和审计日志 | `src/lib/boss-permissions.ts`、`GET/POST /api/v1/admin/access` |
| 设备撤权 | 已支持 `revoke_device`：清空设备 token、置离线、写 `device.revoked` 审计，并阻断 heartbeat、任务认领、Skill 同步、日志上报、boss-agent OTA | `src/lib/boss-data.ts`、`src/app/api/device-heartbeat/route.ts`、`src/app/api/v1/admin/access/route.ts` |
| 设备心跳安全 | 已禁止无 token 的已存在设备续命，禁止未准备 enrollment 的新设备自注册，吊销设备不会刷新 `lastSeenAt / status / projects / projectCandidates` | `POST /api/device-heartbeat` |
| 主 Agent 任务租约 | 已支持 `attemptCount / maxAttempts / leaseExpiresAt`，运行中任务租约过期可重试认领，超过上限转 `timed_out` | `claimNextMasterAgentTask()`、`POST /api/v1/master-agent/tasks/claim` |
| 主 Agent 任务取消 | 已支持取消 `queued / running / needs_user_action`，写 `canceledAt / canceledBy / cancelReason`，迟到 complete 不覆盖终态 | `POST /api/v1/master-agent/tasks/[taskId]/cancel` |
| Codex 桌面同步 | 已支持 APP 用户消息镜像到 Codex Desktop rollout，并通过本机刷新桥提示桌面端感知更新 | `local-agent`、Codex Desktop Refresh Bridge |
| Codex App Server 接入 | 已有第一批 provider runner，turn 启动前失败可回退 CLI，turn 启动后不重复执行 | `local-agent/codex-app-server-runner.mjs` |
| 电脑控制 provider | macOS 链路优先 Codex Computer Use，失败后回退 CUA Driver；browser / desktop 任务统一走 `MasterAgentTask` 和进度卡 | `local-agent/computer-use-task-runner.mjs`、`scripts/codex-computer-use-runtime.mjs`、`scripts/cua-driver-computer-use-runtime.mjs` |
| 状态快照与回退 | 文件状态已有自动快照、手动创建快照和恢复前 pre-restore 快照 | `src/lib/boss-state-backups.ts`、`GET/POST /api/v1/admin/backups` |
| PostgreSQL 切换前置 | 已有 Postgres JSONB store、schema 校验、dry-run 迁移、Postgres 备份导出和恢复脚本 | `src/lib/boss-state-store.ts`、`scripts/boss-state-store-maintenance.mjs` |
| boss-agent Mac OTA | 已支持 Mac agent 包检查、下载、校验和覆盖安装，并保留绑定配置 | `src/lib/boss-agent-ota.ts`、`local-agent/boss-agent-ota-runner.mjs` |
| Skill 生命周期治理 | 已支持 install / update / uninstall / rollback / version_lock 请求、设备端 claim / complete、source allowlist、checksum、更新前备份和失败恢复 | `GET/POST /api/v1/admin/skills/requests`、`skill-requests/claim` |
### 13.2 量产 P0：上线前必须补齐
P0 的定义：不补齐会影响企业客户数据安全、权限边界、稳定演示或生产事故恢复。
1. 数据库正式切换：把 `BOSS_STATE_STORE=postgres` 从可选适配层推进到生产主路径，补正式 PostgreSQL 表拆分、迁移脚本、灰度开关和回滚剧本。
2. 事件账本：新增 append-only event ledger，覆盖账号、设备、权限、任务、审批、Skill、备份、Computer Use 动作和主 Agent 接管。
3. 备份恢复演练自动化：把文件快照和 Postgres 备份纳入后台“恢复演练”流程，记录演练时间、耗时、校验结果和负责人。
4. 任务调度服务化：把 `MasterAgentTask` 从状态文件轮询升级为数据库任务队列或可靠队列，支持 lease、retry、cancel、dead-letter 和 worker 心跳。
5. 企业 SSO / IdP：补 OIDC/SAML 之一，支持企业管理员配置登录策略、MFA 强制、离职回收和会话全量吊销。
6. 设备绑定与正版授权：boss-agent 绑定二维码、授权到期、许可证校验、设备换绑、离线宽限期和吊销恢复流程需要闭环。
7. 审计不可抵赖：关键操作需要稳定审计 ID、操作者、来源 IP、UA、前后快照、关联任务和导出能力。
8. 高风险审批：Computer Use、代码提交、部署、权限变更、批量 Skill 下发必须进入审批卡，不允许只靠主 Agent 自行判断。
9. 生产监控与告警：补服务端 metrics、错误率、任务积压、设备离线、API 失败、OTA 失败、备份失败和客户维度 SLA 告警。
10. 客户数据隔离验收：对所有 Web / APP / API 投影视图做租户隔离回归，确保子账号看不到未授权设备、项目、线程、Skill、日志和附件。
### 13.3 量产 P1：首批企业客户试点必须补齐
P1 的定义：不影响最小上线，但会影响试点客户规模化复制、运营效率和长期留存。
1. 管理后台企业化：平台总后台和企业自管后台进一步拆清，补租户套餐、授权席位、设备额度、用量统计、客户健康分和客户成功视图。
2. Skill 市场：支持平台 Skill、企业私有 Skill、版本签名、依赖扫描、灰度发布、回滚统计和失败率看板。
3. 业务 Agent 目录：把销售、客服、财务、HR、项目、行政、运维 Agent 做成可配置目录，并绑定 SOP、权限和数据源。
4. 进度卡增强：把 `execution_progress` 扩展为统一 task timeline，支持步骤、截图、文件变更、测试结果、审批记录和可展开过程日志。
5. Codex 协议快照：建立 `docs/protocol-snapshots/codex-app-server/`，自动比较 protocol version、capabilities、model/list、approval、skill、plugin 变化。
6. 多入口一致会话：Telegram 已有最小链路，后续补飞书、企业微信或微信生态入口，并统一权限、审计、通知和会话状态。
7. 企业知识库与长期记忆：把项目目标、版本记录、任务结果、回退点、客户 SOP 和主 Agent 记忆纳入统一版本化记录。
8. Computer Use 证据链：关键桌面动作需要截图 / 屏幕录制 / AX tree 摘要 / 操作序列留档，便于复盘和客户信任。
### 13.4 当前验证基线
截至本次文档更新，以下本地验证命令作为当前量产底座的最小回归基线：
```bash
npx tsx --test tests/device-revocation-auth.test.ts tests/master-agent-task-reliability.test.ts tests/device-import-draft.test.ts tests/ai-account-validation.test.ts tests/device-import-candidate-id-regression.test.ts tests/master-agent-task-claim-route.test.ts tests/device-execution-conflict.test.ts tests/browser-desktop-control-summary-message.test.ts tests/skill-lifecycle-route.test.ts tests/state-store-maintenance-script.test.ts tests/boss-state-store.test.ts
npm run lint
npm run build
```
本次验证结果：49 项核心测试通过，`npm run lint` 通过，`npm run build` 通过。
## 14. 90 天量产试点路径
PPT 第 10 页给出的 90 天路径进入后续 To B 交付方法论。
### 阶段 1：0-30 天
目标：选择 1-2 个高频流程，搭好企业账号、权限、设备和数据接入基础。
交付：
- 梳理老板、经理、员工权限。
- 选择高频、规则清晰、跨系统搬运多的流程。
- 接入关键系统和数据，如 CRM、ERP、财务、OA、知识库。
- 接入真实电脑和本地 Agent。
### 阶段 2：31-60 天
目标：部署主 Agent 和 2-3 个业务 Agent，跑真实任务。
交付：
- 主 Agent 统筹，业务 Agent 执行具体流程。
- 建立审批、审计、异常处理和权限边界。
- 跑通真实任务并持续优化 SOP。
- 形成可复制配置模板。
### 阶段 3：61-90 天
目标：接入经营看板，评估效率和复制条件。
交付：
- 实时展示任务进度、效率指标和业务价值。
- 评估从发起到结果的整体响应时间。
- 评估人工汇总减少、流程稳定性和复制条件。
- 输出下一部门复制方案。
成功标准：
- 可持续执行。
- 可审批。
- 可追踪。
- 可复制。
## 15. 产品开发优先级
第一优先级：稳定和治理。
- 数据库正式替换文件状态。
- append-only 事件账本。
- 自动备份和恢复演练。
- 业务级回退。
- 主 Agent 任务取消、接管关闭和主动任务清理。当前已有任务 cancel / timed_out 底座，仍需数据库队列化和 dead-letter。
- 设备离线、执行失败、审批超时进入风险台。
第二优先级：Codex App Server 深度接入。
- App Server provider adapter。当前已有第一批 runner，仍需协议快照、能力清单和 streamed events 完整映射。
- Thread / Turn / Item 映射。
- Approval card 映射。
- streamed events 进入进度卡。
- skills/list、model/list、plugin/list 进入能力清单。
- 协议快照和兼容测试。
第三优先级：企业协作网络。
- 老板端、经理端、员工端权限视图。
- 业务 Agent 目录和 SOP。
- 部门/项目维度执行闭环。
- Skill 企业分配和跨设备同步。
- 平台总后台风险与客户成功视图。
第四优先级：前瞻扩展。
- Telegram、飞书、微信、Web、APP 多入口一致会话。
- 自研 Computer Use 与 Codex Computer Use 并存。
- 多 provider 智能路由。
- 企业知识库和长期记忆。
- 自动复盘、流程优化和策略建议。
## 16. 非协商性原则
- 不允许把系统提示词、内部 prompt、设备 token、API key、工作目录调度说明写进用户可见消息。
- 不允许主 Agent 在用户取消接管后继续主动向线程发起任务。
- 不允许没有审计记录的高风险操作。
- 不允许没有回退点的批量权限、Skill、数据或代码变更。
- 不允许把 Codex 当前某个版本的协议字段直接作为 Boss 业务事实源。
- 不允许把过程噪音当作未读消息。
- 不允许让企业子账号看到未授权设备、项目、Skill 或线程上下文。
## 17. 下一步落地清单
1. 输出 PostgreSQL 正式 schema 设计：账号、企业、设备、项目、线程、消息、任务、审批、事件账本、审计、备份、Skill。
2. 把 `MasterAgentTask` 调度从文件状态轮询迁到可靠队列或数据库任务表，并保留现有 lease / retry / cancel 语义。
3. 新增 `docs/protocol-snapshots/codex-app-server/` 目录规范和兼容测试。
4. 把 `execution_progress` 进度卡扩展成统一 task timeline。
5. 把项目目标、版本记录、任务结果和回退点纳入同一套版本化记录。
6. 为平台总后台增加恢复演练、租户风险、设备离线、主 Agent 失败和任务积压看板。
7. 为 Skill 治理增加签名、依赖扫描、灰度发布和失败率统计。
8. 为 boss-agent 增加企业正版授权、授权到期提醒、离线宽限和设备换绑流程。