chore: checkpoint Boss app v2.5.11

2026-06-08 12:22:50 +08:00
parent bddbe8b5ba
commit 3b51641d99
78 changed files with 5706 additions and 954 deletions
--- a/docs/architecture/ai_handoff_index_cn.md
+++ b/docs/architecture/ai_handoff_index_cn.md
@@ -180,6 +180,7 @@
 - 当前已补 Codex App Server 版 Boss 用户消息镜像：普通单线程 `conversation_reply` 任务携带 `mirrorBossUserMessageToCodexDesktop=true` 时，`local-agent/codex-app-server-runner.mjs` 会在 `thread/resume` 后、`turn/start` 前调用 `thread/inject_items`，把 Boss APP 用户原文作为 `role=user` 的 Responses item 写入目标 Codex 线程模型可见历史；任务结果只回传 `threadHistorySync.threadId / injectedItemCount / source`，不回传消息 ID、内部 prompt 或用户原文。CLI rollout 镜像仍保留为 App Server 不可用前的 fallback 链路。
 - 当前 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 不覆盖终态。
+- 当前任务 SLA 面板、失败自动恢复和后台告警已沉淀为独立交接文档：`docs/architecture/task_sla_auto_recovery_admin_alerts_cn.md`。该文档记录 `taskSlaPanel`、`adminNotifications`、pre-turn 安全自动恢复边界、本地验证结果和后续云部署检查清单；当前尚未部署云端，等待新的服务器入口后再按文档执行。
 - 当前群聊 `dispatch_execution` 完成回写已补幂等，重复完成不会再向群聊重复追加结果
 - 当前已支持微信式消息转发：长按消息可直接 `转发 / 多选 / 复制 / 删除`，单条消息转发显示为普通转发消息，多条消息转发显示为聊天记录卡片
 - 当前已支持聊天附件主链：原生聊天框左侧 `+` 会打开底部抽屉，支持图片 / 视频 / 文件发送；图片 / PDF / 文本默认自动进入主 Agent 附件分析，视频 / Office / 大文件默认手动触发
--- a/docs/architecture/api_and_service_inventory_cn.md
+++ b/docs/architecture/api_and_service_inventory_cn.md
@@ -385,7 +385,7 @@
  - `companies[]`：优先使用显式客户公司 / 租户，其次按账号域名或默认公司聚合
  - `accounts[]`：脱敏账号列表，不包含 `passwordHash`
  - `devices[]`：设备在线状态、CLI/GUI 能力、项目数和风险数
-  - `risks[]`：离线设备、运维故障、线程上下文风险和失败主 Agent 任务；运维故障和线程上下文风险会带出负责人和 SLA
+  - `risks[]`：离线设备、运维故障、线程上下文风险、失败主 Agent 任务和任务 SLA 告警；运维故障和线程上下文风险会带出负责人和 SLA
  - `notifications[]`：开放中的风险 SLA 通知，当前由 `/api/v1/admin/risks/scan` 生成
  - `grantsSummary`：设备 / 项目 / Skill 授权数量与过期授权数量

@@ -400,6 +400,7 @@
  - `users[]`：脱敏账号列表，不包含 `passwordHash / mfaSecret / authSessions`
  - `roles`：内置角色与 `BOSS_PERMISSION_TEMPLATES`
  - `resourceGroups`：设备、项目线程、Skill 聚合目录和授权记录
+  - `insights.taskSlaPanel`：MasterAgentTask 的 SLA 面板，包含状态分布、SLA 截止、空闲时间、尝试次数、是否可自动恢复和建议动作
  - `audit`：风险、通知、风险时间线和 `permissionAuditLogs`
  - `yudaoMapping`：Boss 账本字段到后台概念的映射，用于后续数据库化或模块拆分
 - 当前定位：供 `https://admin.boss.hyzq.net/ -> apps/boss-admin-web` 消费；旧 `/admin` UI 已下线，不再消费 `/api/v1/admin/overview` 和旧数据 provider
@@ -423,7 +424,10 @@
 - 当前行为：
  - 扫描未关闭的 `opsFaults` 和 `threadContextAlerts`
  - 同步检查运行态异常：在线设备 `Computer Use` 不可用会补 `BOSS.COMPUTER_USE.UNAVAILABLE` 运维故障，`boss-agent OTA` 失败日志会补 `BOSS_AGENT.OTA.FAILED` 运维故障
+  - 同步扫描 `MasterAgentTask` SLA：基于 lease、最近进度、尝试次数和 recoverable 标记生成任务 SLA 告警
+  - 只对 `queued / claimed / executor_starting / recoverable_failed` 这类 pre-turn 安全阶段的可恢复任务自动重排队，避免已进入目标线程回复阶段的任务被重复执行
  - 当 `slaDueAt` 已早于当前时间时，写入 `adminNotifications[]`
+  - 任务 SLA 告警同样写入 `adminNotifications[]`，自动恢复会写入 `adminRiskTimeline[]` 和 `permissionAuditLogs[]`
  - 同一个 `riskId` 只生成一条 `risk_sla_overdue` 通知，重复扫描不会重复膨胀账本
  - 生成新通知时发布 `project.context_risk.updated`

--- a/docs/architecture/current_runtime_and_deploy_status_cn.md
+++ b/docs/architecture/current_runtime_and_deploy_status_cn.md
@@ -30,6 +30,8 @@
 - 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 线程扫描卡死
+- 2026-06-07 已补量产可靠性降载：`local-agent` 的 reliable outbox 会优先保留 `task.complete`，按任务合并重复 `task.progress`，并对同类 `app.log` 做去重和上限保护；`/health` 默认只返回轻量摘要，完整 runtime 只允许通过 `/health?verbose=1` 做诊断；Android SSE 已新增 `message-patch-v1` 能力声明，服务端只对支持该能力的客户端下发 `projectMessagesPatch`，旧客户端继续使用完整 `projectMessagesPayload`
+- 2026-06-07 已补任务 SLA 企业治理：新增 `src/lib/master-agent-task-sla.ts` 统一计算 MasterAgentTask 的 `ok / watch / breached / recoverable / terminal` 状态、SLA 截止时间、空闲时间、尝试次数和建议动作；`GET /api/v1/admin/backoffice` 会返回 `insights.taskSlaPanel`，独立 Web 管理后台的平台风险页和企业风险页都会展示任务 SLA 面板；`POST /api/v1/admin/risks/scan` 会对 SLA 超时、可恢复失败和终态失败幂等写入 `adminNotifications`，并把可安全重试的 pre-turn recoverable 任务自动重排队，写入 `adminRiskTimeline` 和 `permissionAuditLogs`
 - 本地 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`
@@ -139,7 +141,7 @@ cd /Users/kris/code/boss
 - 当前最高管理员授权管理接口已落地：`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`。
+- 当前后台风险处理接口已落地：`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`，也会扫描 MasterAgentTask SLA 并对安全阶段可恢复失败自动重排队；管理后台总览会展示开放风险通知和任务 SLA 面板；不支持的风险类型会明确返回 `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 跨设备聚合并撤销单条授权
@@ -372,7 +374,7 @@ cd /Users/kris/code/boss
 - 数据存储默认仍是文件型，但已经有 PostgreSQL store adapter、schema 和维护脚本；生产切换前需先执行备份、dry-run 迁移和回滚演练
 - 设备发现、项目扫描和额度采集仍是静态配置驱动的 MVP
 - APP 实时日志当前已能同步到主 Agent 会话，但还没有单独的日志检索、分页和告警升级规则
- Skill 清单当前按设备同步和展示已经可用；远程治理目前只有最高管理员创建 lifecycle 请求和 list 状态，尚未真正下发到设备端执行安装 / 更新 / 卸载 / 回滚
+- Skill 清单当前按设备同步和展示已经可用；远程治理已贯通最高管理员创建 lifecycle 请求、设备端认领、local-agent 执行安装 / 更新 / 卸载 / 回滚 / 版本锁、执行后同步 Skill 清单和完成回写。当前仍属于文件型状态与 Git 来源驱动的 MVP，生产使用前需要配置设备侧 source allowlist / trusted sources、校验和策略和失败告警。
 - 服务器侧主 Agent 实时回复依赖被绑定设备的 `local-agent` 在线并能执行 `codex exec`；如果设备离线，只能保留任务或走 API 容灾账号
 - 设备导入主链的后端状态机已经跑通，并且已经分成两条：
  - 新接入设备继续走 `import draft -> 勾选 -> review -> apply`
--- a/docs/architecture/task_sla_auto_recovery_admin_alerts_cn.md
+++ b/docs/architecture/task_sla_auto_recovery_admin_alerts_cn.md
@@ -0,0 +1,259 @@
+# 任务 SLA 面板、失败自动恢复与后台告警开发记录
+
+更新时间：`2026-06-07`
+
+## 目标
+
+把主 Agent / Codex 执行任务从“只在聊天窗口里看进度”升级为企业后台可治理对象，平台侧可以看到任务是否超时、是否可恢复、是否需要人工介入，并在安全前提下自动恢复可重试失败任务。
+
+这批功能面向量产交付，核心目标是降低客户现场出现“任务卡住但后台无感知”的概率。
+
+## 已完成能力
+
+### 1. 任务 SLA 统一投影
+
+新增 `src/lib/master-agent-task-sla.ts`，统一计算 `MasterAgentTask` 的 SLA 状态。
+
+当前状态分为：
+
+- `ok`：任务在 SLA 内，无需处理。
+- `watch`：接近 SLA 或长时间无进展，需要观察。
+- `breached`：任务已超过 SLA，需要后台告警。
+- `recoverable`：任务处于可恢复失败状态，可以安全重排队。
+- `terminal`：任务已经终态失败，需要人工排障或工单处理。
+
+投影字段包括：
+
+- `taskId / riskId / notificationId`
+- `projectId / deviceId / companyId`
+- `taskType / status / phase`
+- `requestedAt / claimedAt / lastProgressAt / leaseExpiresAt / slaDueAt`
+- `elapsedMs / idleMs`
+- `attemptCount / maxAttempts / attemptLabel`
+- `stale / recoverable / autoRecoverable`
+- `slaLevel / severity / recommendedAction`
+
+### 2. 后台 BFF 增加任务 SLA 面板
+
+`GET /api/v1/admin/backoffice` 已新增：
+
+```json
+{
+  "insights": {
+    "taskSlaPanel": {
+      "generatedAt": "...",
+      "summary": {
+        "total": 0,
+        "active": 0,
+        "ok": 0,
+        "watch": 0,
+        "breached": 0,
+        "recoverable": 0,
+        "terminal": 0,
+        "autoRecoverable": 0
+      },
+      "rows": []
+    }
+  }
+}
+```
+
+旧字段 `insights.taskRiskSummary` 保留，避免影响既有前端和旧客户端。
+
+### 3. 风险扫描写入后台告警
+
+`POST /api/v1/admin/risks/scan` 现在会同时扫描三类风险：
+
+- 已设置 `slaDueAt` 且超时的 `opsFaults`
+- 已设置 `slaDueAt` 且超时的 `threadContextAlerts`
+- `MasterAgentTask` 的 SLA 超时、可恢复失败和终态失败
+
+任务 SLA 告警写入：
+
+- `adminNotifications[]`
+- `adminRiskTimeline[]`
+- `permissionAuditLogs[]`
+
+通知 ID 使用 `risk-sla-overdue:master-task:<taskId>`，同一个任务重复扫描不会重复膨胀账本。
+
+### 4. 失败自动恢复策略
+
+风险扫描会自动恢复满足条件的任务：
+
+- `recoverable === true`
+- 未超过 `maxAttempts`
+- `nextRetryAt` 为空或已经到期
+- 阶段属于安全 pre-turn 阶段
+
+允许自动恢复的阶段：
+
+- `queued`
+- `claimed`
+- `executor_starting`
+- `recoverable_failed`
+
+禁止自动恢复的阶段：
+
+- `turn_started`
+- `awaiting_reply`
+- `completing`
+- `completed`
+- `timed_out`
+- `canceled`
+
+禁止这些阶段自动恢复的原因是：任务可能已经进入目标 Codex 线程或执行器真实工作阶段，重复下发可能导致同一轮用户指令被执行两次。
+
+自动恢复动作会：
+
+- 把任务重置为 `status=queued`
+- 把任务阶段重置为 `phase=queued`
+- 清除 `claimedAt / leaseExpiresAt / errorMessage / nextRetryAt`
+- 写入新的 `execution_progress` 队列态
+- 写入 `permissionAuditLogs.action=master_agent.task_retried`
+- 写入 `adminRiskTimeline.action=task.auto_recovery_requeued`
+- 发布 `master_agent.task.updated` 和对应会话刷新事件
+
+### 5. 独立 Web 管理后台页面
+
+`apps/boss-admin-web` 已在以下页面增加“任务 SLA 面板”：
+
+- 平台后台：`全局风险`
+- 企业后台：`风险与审计`
+
+面板显示：
+
+- 运行任务数
+- SLA 超时数
+- 可自动恢复数
+- 终态失败数
+- 任务类型、状态、阶段、设备、尝试次数、空闲时间和建议动作
+
+## 涉及文件
+
+核心实现：
+
+- `src/lib/master-agent-task-sla.ts`
+- `src/lib/boss-risk-notifications.ts`
+- `src/lib/boss-data.ts`
+- `src/lib/boss-admin-overview.ts`
+- `src/app/api/v1/admin/backoffice/route.ts`
+
+Web 管理后台：
+
+- `apps/boss-admin-web/src/api/bossAdmin.ts`
+- `apps/boss-admin-web/src/App.vue`
+
+测试：
+
+- `tests/admin-backoffice-bff-route.test.ts`
+- `tests/admin-risk-sla-notifications-route.test.ts`
+
+配套文档：
+
+- `docs/architecture/current_runtime_and_deploy_status_cn.md`
+- `docs/architecture/api_and_service_inventory_cn.md`
+
+## 本地验证结果
+
+已通过：
+
+```bash
+npx tsx --test tests/admin-backoffice-bff-route.test.ts tests/admin-risk-sla-notifications-route.test.ts tests/admin-overview-route.test.ts tests/master-agent-task-recovery-route.test.ts tests/master-agent-task-reliability.test.ts
+npm run lint
+npm run build
+npm run admin:web:build
+```
+
+本地接口烟测已通过：
+
+```bash
+curl 'http://localhost:3000/api/v1/admin/backoffice?scope=platform' \
+  -H 'Cookie: boss_session=<highest_admin_session>'
+```
+
+确认结果：
+
+- `insights.taskSlaPanel` 存在
+- `riskAggregates` 中包含 `任务 SLA 告警`
+- 当前本地生产账本没有未完成任务时，`taskSlaPanel.rows` 为 `0` 属于正常状态
+
+## 后续云部署待办
+
+这批功能尚未部署到云。等提供云服务器入口后，按以下步骤执行。
+
+### 1. 部署前检查
+
+- 确认服务器入口、账号、认证方式可用。
+- 确认目标服务仍是 Boss Web 管理后台服务，不要误部署到 APP Web 版或其他站点。
+- 确认当前云端 `data/boss-state.json` 已有备份。
+- 确认 `admin.boss.hyzq.net` 仍指向独立 Web 管理后台 `/admin-web/index.html`。
+
+### 2. 服务器构建
+
+建议在服务器或发布流水线执行：
+
+```bash
+npm run lint
+npm run build
+npm run admin:web:build
+```
+
+### 3. 发布文件
+
+需要同步：
+
+- Next standalone 产物
+- `public/admin-web` 静态产物
+- `src/lib/master-agent-task-sla.ts`
+- 本次涉及的 `src/lib`、`src/app/api/v1/admin`、`apps/boss-admin-web` 文件
+- 文档更新
+
+### 4. 重启服务
+
+重启目标服务后检查：
+
+```bash
+curl -fsS https://boss.hyzq.net/api/health
+curl -fsS https://admin.boss.hyzq.net/admin-web/index.html
+```
+
+如果 `admin.boss.hyzq.net/` 是根路径 rewrite 到 `/admin-web/index.html`，还要检查：
+
+```bash
+curl -I https://admin.boss.hyzq.net/
+```
+
+### 5. 管理后台验证
+
+用 `highest_admin` 登录后验证：
+
+- 打开 `https://admin.boss.hyzq.net/`
+- 进入 `全局风险`
+- 能看到 `任务 SLA 面板`
+- 面板无前端报错
+- `GET /api/v1/admin/backoffice?scope=platform` 返回 `insights.taskSlaPanel`
+
+### 6. 风险扫描验证
+
+用最高管理员会话触发：
+
+```bash
+curl -X POST https://boss.hyzq.net/api/v1/admin/risks/scan \
+  -H 'Cookie: boss_session=<highest_admin_session>'
+```
+
+预期：
+
+- 返回 `createdFaults[]`
+- 返回 `created[]`
+- 返回 `autoRecovered[]`
+- 返回 `notifications[]`
+
+如果没有卡住任务或超时任务，`created[] / autoRecovered[]` 为空是正常结果。
+
+## 风险边界
+
+- 自动恢复只处理 pre-turn 安全阶段，不对已经进入 Codex 真实回复阶段的任务做自动重试。
+- 当前仍是文件账本 MVP，企业级大规模部署前建议继续推进 PostgreSQL 状态存储和自动备份演练。
+- 任务 SLA 当前是规则计算，不依赖数据库表；后续数据库化时应把 `taskSlaPanel` 继续作为投影层，不要把投影结果反写成主状态源。
+- 后台告警当前进入 `adminNotifications`，外部通知派发仍依赖现有 `dispatchAdminRiskNotifications` 配置；如果客户需要企业微信 / 飞书 / 短信，需要另开通知渠道配置。