krisolo/boss

Fork 0

Files

AI Bot 3b51641d99 chore: checkpoint Boss app v2.5.11

2026-06-08 12:22:50 +08:00

7.3 KiB

Raw Blame History

任务 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 已新增：

{
  "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

本地验证结果

已通过：

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

本地接口烟测已通过：

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. 服务器构建

建议在服务器或发布流水线执行：

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. 重启服务

重启目标服务后检查：

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，还要检查：

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. 风险扫描验证

用最高管理员会话触发：

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 配置；如果客户需要企业微信 / 飞书 / 短信，需要另开通知渠道配置。

7.3 KiB Raw Blame History Unescape Escape