krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f496838ced1378f4aaa9c77335e545fb0fdcb4a8
boss/docs/source-material/ops_layer_and_repair_protocol_cn.md
kris 90cb6b7ff1 feat: ship native boss android console
2026-03-26 23:16:56 +08:00

21 KiB
Raw Blame History

运维层与运维审计层开发规格

适用范围：

  • Codex 多机协作控制系统
  • 主控、Worker、审计层、硬件测试层、数据层的统一运维与抢修
  • 每台接入终端设备上的本地运维 Agent 与本地运维审计 Agent

目标：

  • 在整个系统最外层增加 运维层 和 运维审计层
  • 让运维层成为整个系统的 主运维层，并可继续接管其他项目的运维场景
  • 把运维层做成开放式能力底座，而不是只服务当前这一套 Codex 系统
  • 让任何一个环节发生故障时，都能用最省 token 的方式快速定位与修复
  • 定义主 Agent 在线与离线两种情况下的修复审批和复验机制
  • 定义运维层自身故障时，由主 Agent 反向抢救运维层的机制
  • 保证每一台接入系统的终端设备都具备本地自救与被监管能力

1. 总体原则

  1. 运维层是整个系统的外圈保护层，也是全局 主运维层，不只看主控，也看 Worker、审计层、硬件测试层、数据库、额度系统，以及后续接入的其他项目运维域。
  2. 每一台接入系统的设备都必须常驻两个本地角色：
    • Ops Agent
    • Ops Audit Agent
  3. Ops Agent 负责发现问题、执行修复、运行脚本、拉起服务、切换配置。
  4. Ops Audit Agent 负责监督 Ops Agent 是否健康、是否有权修复、修复是否成功、是否需要升级到紧急决策。
  5. 只要主 Agent 在线且能够正常返回信息，Ops Agent 的修复动作必须先得到主 Agent 同意。
  6. 当主 Agent 失联且超过阈值，Ops Audit Agent 才能代行最终修复执行判断。
  7. 运维层必须是开放式的，支持通过标准化 Connector / Adapter / Runbook 注册新的项目运维域。
  8. 如果运维层本身挂了，而主 Agent 仍然在线，主 Agent 必须具备反向抢救运维层的能力。
  9. 所有故障、修复、复验、切换都必须写入统一事件流和运维账本。

2. 组件设计

2.1 云端组件

  • Ops Control Plane 负责汇总节点健康、统一策略、下发巡检与修复任务。
  • Ops Policy Engine 负责判断巡检频率、自动修复权限、紧急接管条件。
  • Ops Ledger 负责记录故障、修复工单、复验结论、主控恢复后的同步结果。
  • Chief Ops Audit Agent 负责跨节点复核、紧急情况下最终判定、主控恢复后的回填汇报。
  • Ops Extension Registry 负责注册其他项目或其他系统的运维域、连接器、协议适配器、能力标签和 Runbook 集合。
  • Ops Connector Runtime 负责装载 SSH、HTTP、Docker、Kubernetes、Windows Service、局域网 RPC 等运维连接器。

2.2 每台终端设备上的本地组件

  • Local Ops Agent 负责本机服务巡检、日志采集、健康探针、执行修复动作。
  • Local Ops Audit Agent 负责监督本机 Local Ops Agent、校验修复结果、在主控失联时决定是否允许继续修复。
  • Local Watchdog 负责当本地服务崩溃时自动拉起最小监控能力。

2.3 被监管对象

  • 主 Agent / Master Agent Runtime
  • API 网关 / WebSocket
  • Worker Daemon / Thread Gateway
  • Audit Orchestrator / Specialist Audit Agents
  • Capability Registry / Test Rig Gateway
  • Postgres / Redis / Object Storage / Event Store
  • gptpluscontrol Backend / Agent
  • GPU Bridge / Windows Tool Bridge
  • 其他项目的运维域
    • 外部服务
    • 外部测试台
    • 外部边缘盒子
    • 外部 CI / 运维主机

2.4 开放式运维扩展模型

运维层不应该写死只服务这一套系统，建议增加 3 层开放接口：

  • Ops Domain 表示一个被接管的运维域，例如：
    • 当前 Codex 协作系统
    • 某个独立设备云
    • 某个视频分析服务
    • 某个生产测试线
  • Ops Connector 表示接入方式，例如：
    • ssh
    • http_api
    • docker
    • k8s
    • windows_service
    • lan_rpc
  • Ops Runbook Pack 表示一组可被版本化管理的运维修复剧本。

任何新项目要接入主运维层，只需要注册：

  • 它属于哪个 Ops Domain
  • 用什么 Ops Connector
  • 提供哪些健康探针
  • 有哪些修复 Runbook
  • 权限边界是什么
  • 是否允许自动修复

2.5 跨设备运维能力

运维层必须支持跨设备运维，而不是每台机器只能各修各的。

建议至少支持以下跨设备能力：

  • 跨设备拉取日志
  • 跨设备读取健康快照
  • 跨设备重启服务
  • 跨设备下发配置与热更新
  • 跨设备切换账号 / 切换备用通道
  • 跨设备回收孤儿 thread / lease / repair ticket
  • 跨设备重连 Thread Gateway、GPU Bridge、Test Rig Gateway
  • 跨设备触发最小修复 Runbook

建议把跨设备运维动作抽象成标准能力：

  • remote_exec
  • remote_restart_service
  • remote_fetch_logs
  • remote_push_config
  • remote_switch_account
  • remote_reconnect_channel
  • remote_collect_snapshot
  • remote_run_runbook

跨设备运维的执行原则：

  1. 默认由云端 Ops Control Plane 发起跨设备动作。
  2. 实际执行仍然落在目标节点的 Local Ops Agent 上。
  3. Local Ops Audit Agent 负责复核跨设备动作是否成功、是否越权。
  4. 所有跨设备动作必须记录 source_node_id 和 target_node_id。
  5. 禁止未经授权的节点直接互相执行运维指令，必须经过主运维层或紧急救援通道。

3. 部署要求

3.1 每个节点必须具备的最小组合

每台接入系统的 Mac、Windows、云工作机、独立测试台，至少都要有：

  • Local Ops Agent
  • Local Ops Audit Agent
  • Health Probe Runner
  • Repair Runbook Executor
  • Ops Event Uploader

3.2 云端部署

云端至少部署：

  • Ops Control Plane
  • Ops Policy Engine
  • Ops Ledger
  • Chief Ops Audit Agent
  • Ops Extension Registry
  • Ops Connector Runtime
  • Standby Controller

3.3 主 Agent 的运维监管规则

  • 主 Agent 每小时至少主动检查一次运维层是否健康。
  • 检查内容包括：
    • 每个节点的 Ops Agent 是否在线
    • 每个节点的 Ops Audit Agent 是否在线
    • 最近一次巡检是否成功
    • 是否存在未结清的修复工单
    • 是否存在长时间未复验完成的修复动作
    • 运维层本身的控制面、账本、连接器和扩展注册是否健康

3.4 运维层作为主运维层的边界

主运维层至少要覆盖两类对象：

  • 系统内域 当前这套 Codex 协作系统内部组件
  • 外部项目域 后续接入的其他项目、其他机器群、其他测试台、其他后台服务

这意味着运维层的数据模型里必须有：

  • domain_id
  • domain_type
  • connector_type
  • ownership_scope
  • runbook_pack_version

4. 动态巡检频率

4.1 高频模式

以下任一条件满足时，巡检频率切到 每 5 分钟：

  • 有用户正在手机端 / Web 端活跃使用
  • 有项目正在执行
  • 有 Worker thread 正在跑任务
  • 有能力租约正在占用摄像头、串口、机器人等硬件
  • 有未完成的审计任务
  • 有未关闭的高优先级告警

4.2 空闲模式

以下条件全部满足时，巡检频率降到 每 1 小时：

  • 当前没有在线用户会话
  • 没有任何活跃项目或任务
  • 没有任何设备租约占用
  • 没有现场测试正在运行
  • 没有待处理高优先级故障

4.3 模式切换策略

  • 由 Ops Policy Engine 根据近 10 分钟活动窗口判定模式。
  • 切换时写入事件：
    • ops_mode_switched_to_active
    • ops_mode_switched_to_idle

5. 故障命名与日志规范

5.1 设计目标

日志必须做到：

  • 一眼能看出故障发生在哪个环节
  • 一眼能看出受影响组件和动作
  • 能直接映射到修复 Runbook
  • 让主 Agent、Ops Agent、Ops Audit Agent 都能低 token 地总结问题

5.2 统一命名格式

建议所有错误键都遵循：

<LAYER>.<DOMAIN>.<COMPONENT>.<ACTION>.<ERROR_CODE>

例如：

  • ENTRY.APP.PROJECT_CREATE.VALIDATION_FAIL
  • MASTER.SCHEDULER.DISPATCH.NODE_UNAVAILABLE
  • WORKER.CODEX.THREAD_START.RATE_LIMIT
  • THREAD.BROKER.MESSAGE_ROUTE.PERMISSION_DENIED
  • AUDIT.MULTIMODAL.VERIFY.EVIDENCE_MISSING
  • CAPABILITY.CAMERA.LEASE.PREEMPT_TIMEOUT
  • DATA.POSTGRES.WRITE.REPLICATION_LAG
  • OPS.LOCAL_AGENT.HEARTBEAT.MISSED
  • OPS_AUDIT.REPAIR.VERIFY.RESTART_FAILED

5.3 每条错误日志最少字段

  • fault_key
  • severity
  • node_id
  • service_name
  • project_id
  • thread_ref
  • trace_id
  • runbook_id
  • first_seen_at
  • last_seen_at
  • summary
  • suggested_next_action

5.4 日志分层前缀建议

  • ENTRY
  • MASTER
  • WORKER
  • THREAD
  • AUDIT
  • CAPABILITY
  • DATA
  • AUTH
  • QUOTA
  • OPS
  • OPS_AUDIT
  • RECOVERY

5.5 Token 节省策略

Ops Agent 汇报时不直接贴长日志，而是优先输出：

  • fault_key
  • 影响节点数
  • 首次时间 / 最近时间
  • top 3 关联错误
  • 绑定的 runbook_id
  • 当前是否可自动修复

6. 除日志之外的运维检测方式

只靠日志不够，建议同时启用以下机制：

6.1 心跳与存活探针

  • 每个服务定期发送 heartbeat
  • 每个节点的 Ops Agent 和 Ops Audit Agent 互相监督 heartbeat
  • 主控、Worker、审计层、硬件网关都要有独立存活探针

6.2 合成探针 / 端到端冒烟

  • 周期性模拟：
    • 创建一个测试项目
    • 下发一个轻量任务
    • 启动一个测试线程
    • 拉取一次线程历史
    • 触发一次能力租约
  • 如果冒烟链路断掉，说明系统虽然“进程活着”，但业务已经不通

6.3 队列与事件流监测

  • 检测消息队列积压
  • 检测 Event Store 写入延迟
  • 检测线程消息是否长时间停滞
  • 检测 SSE / WebSocket 是否失去推送

6.4 资源与性能监测

  • CPU / 内存 / 磁盘 / GPU 占用
  • WSL2 健康度
  • 数据库复制延迟
  • 对象存储写入失败率
  • 网络抖动和丢包

6.5 认证与额度健康监测

  • ChatGPT / Codex 登录态有效期
  • API key 可用性
  • gptpluscontrol 上报的新鲜度
  • 5h / 7d 剩余额度阈值预警

6.6 配置与版本漂移检测

  • Worker 版本不一致
  • Gateway 配置漂移
  • Runbook 版本落后
  • 审计协议版本不兼容

6.7 孤儿状态清理

  • 孤儿 lease
  • 孤儿 thread
  • 孤儿 repair ticket
  • 无人接管的审计任务

6.8 本地屏幕 / 设备快照抽样

在硬件项目中，可周期性采样：

  • 关键设备截图
  • 摄像头关键帧
  • 串口短日志
  • UI OCR 状态

用于快速判断“服务活着但现场已经坏了”的情况。

7. 修复权限与决策规则

7.1 当主 Agent 在线且能正常返回信息

流程：

  1. Ops Agent 发现问题
  2. 生成修复建议与最小证据包
  3. 向主 Agent 请求批准
  4. 主 Agent 同意后，Ops Agent 执行修复
  5. Ops Audit Agent 做复验
  6. 复验结果回报主 Agent

原则：

  • Ops Agent 不得自行越权修复
  • 主 Agent 有权拒绝、延后、改用人工介入
  • 复验未通过则不能直接关闭工单

7.2 当主 Agent 失联

定义失联建议：

  • 连续 3 次心跳缺失，或
  • 超过 15 分钟无法返回健康响应

流程：

  1. Ops Audit Agent 确认主 Agent 失联
  2. 通知 Chief Ops Audit Agent
  3. 进入紧急运维模式
  4. Ops Audit Agent 依据策略与证据，做最终是否修复的执行判断
  5. Ops Agent 执行修复
  6. Ops Audit Agent 复验
  7. 修复结果写入 Ops Ledger
  8. 主 Agent 恢复后，向其回放修复详情

7.3 当主 Agent 恢复在线

恢复后必须同步：

  • 故障摘要
  • 故障影响范围
  • 已执行修复动作
  • 修复结果
  • 复验结论
  • 是否仍有残余风险
  • 是否需要人工复盘

7.4 当运维层自身挂了，但主 Agent 在线

这是一个单独处理场景，不能等同于普通服务故障。

定义运维层自身故障示例：

  • Ops Control Plane 无法响应
  • Ops Ledger 写入失败
  • Ops Connector Runtime 大面积失效
  • 多个节点的 Ops Agent / Ops Audit Agent 同时失联
  • 运维层事件流中断

流程：

  1. 主 Agent 在每小时健康检查或告警事件中发现运维层异常
  2. 主 Agent 切换到 ops_rescue_mode
  3. 主 Agent 通过独立的最小救援通道直连节点或备用控制器
  4. 主 Agent 对运维层发起反向修复任务
  5. 节点上的最小本地 Watchdog / Standby 代理执行运维层恢复
  6. 恢复后由 Ops Audit Agent 复验运维层是否重新可用
  7. 恢复结果写入账本，并结束 ops_rescue_mode

要求：

  • 主 Agent 抢救运维层时，不能依赖已经损坏的运维控制面本身
  • 必须保留至少一条最小救援通道，例如：
    • 直连节点的紧急 RPC
    • 备用控制器通道
    • 本地 Watchdog 的保底命令接口
    • 只读日志和健康快照通道

8. 运维修复状态机

8.1 Repair Ticket 状态

  • detected
  • classified
  • approval_pending
  • approved_by_master
  • approved_by_ops_audit_emergency
  • repairing
  • repair_failed
  • verification_pending
  • verified_pass
  • verified_fail
  • reported_to_master
  • closed

8.2 自动修复白名单

仅允许以下低风险动作默认自动化：

  • 重启本地 Agent 进程
  • 重连 WebSocket / SSE
  • 重试心跳上传
  • 重拉轻量配置
  • 恢复日志采集

以下动作必须更高权限：

  • 切换主账号 / 备用账号
  • 重启数据库
  • 回滚 Worker 版本
  • 强制释放能力租约
  • 重启 GPU Bridge
  • 重刷固件 / 重置测试设备

9. 修复动作与复验规范

9.1 RepairAction 输入字段

  • repair_ticket_id
  • fault_key
  • node_id
  • service_name
  • decision_source 值：
    • master_agent
    • ops_audit_agent_emergency
  • runbook_id
  • action_type
  • risk_level
  • expected_result
  • timeout_seconds

9.2 RepairVerification 输出字段

  • repair_ticket_id
  • verification_status 值：
    • pass
    • fail
    • partial_pass
    • inconclusive
  • post_health_summary
  • remaining_risks
  • evidence_refs
  • recommended_followup

9.3 复验最少检查项

  • 原故障是否停止出现
  • 关键进程是否恢复
  • 事件流是否恢复
  • 相关接口是否恢复
  • 如涉及硬件，现场状态是否恢复
  • 是否引入新的副作用

10. 建议 API / 事件

10.1 API

  • POST /api/v1/ops/nodes/heartbeat
  • POST /api/v1/ops/health/report
  • POST /api/v1/ops/domains/register
  • POST /api/v1/ops/connectors/register
  • POST /api/v1/ops/remote-actions/request
  • POST /api/v1/ops/remote-actions/{action_id}/approve
  • POST /api/v1/ops/remote-actions/{action_id}/result
  • POST /api/v1/ops/repair-tickets
  • POST /api/v1/ops/repair-tickets/{ticket_id}/approval-request
  • POST /api/v1/ops/repair-actions/start
  • POST /api/v1/ops/repair-actions/{action_id}/result
  • POST /api/v1/ops/repair-verifications
  • POST /api/v1/ops/rescue/enter
  • POST /api/v1/ops/rescue/actions/start
  • POST /api/v1/ops/rescue/complete
  • GET /api/v1/ops/events/stream

10.2 事件

  • ops_agent_heartbeat_missed
  • ops_audit_agent_heartbeat_missed
  • ops_domain_registered
  • ops_connector_registered
  • ops_remote_action_requested
  • ops_remote_action_approved
  • ops_remote_action_completed
  • ops_remote_action_failed
  • ops_fault_detected
  • ops_fault_classified
  • ops_repair_approval_requested
  • ops_repair_approved_by_master
  • ops_repair_approved_by_ops_audit_emergency
  • ops_repair_started
  • ops_repair_completed
  • ops_repair_failed
  • ops_repair_verification_passed
  • ops_repair_verification_failed
  • ops_layer_degraded
  • ops_rescue_mode_entered
  • ops_rescue_action_started
  • ops_rescue_action_completed
  • ops_layer_recovered
  • master_agent_offline_confirmed
  • master_agent_recovered
  • ops_repair_report_synced_to_master

11. 最小数据库表建议

  • ops_nodes
  • ops_domains
  • ops_connectors
  • ops_agent_heartbeats
  • ops_audit_agent_heartbeats
  • ops_faults
  • ops_fault_occurrences
  • ops_repair_tickets
  • ops_repair_actions
  • ops_repair_verifications
  • ops_runbooks
  • ops_mode_history
  • ops_rescue_actions
  • ops_reports_to_master

12. MVP 建议

V1

  • 每个节点部署 Local Ops Agent 与 Local Ops Audit Agent
  • 实现 heartbeat、fault_key 命名、repair ticket、主 Agent 审批、修复复验
  • 高频 / 空闲巡检切换
  • 主 Agent 对运维层的每小时健康检查

V2

  • 加入合成探针、业务冒烟、孤儿状态清理、主控离线后的紧急修复授权
  • 加入主 Agent 恢复后的修复回放
  • 加入 Ops Domain / Connector / Runbook Pack 的开放式接入

V3

  • 加入更精细的 Runbook 路由
  • 加入多节点联动修复
  • 加入版本回滚与策略化自愈
  • 加入主 Agent 对运维层自身的反向抢救通道与 ops_rescue_mode

13. 一句话总结

运维层 解决“谁去发现、执行和扩展运维修复”的问题，
运维审计层 解决“谁有权批准、谁来复验、主控失联时谁来兜底”的问题。

它们必须常驻在每个节点，并且站在整个系统最外层，持续保护主控、Worker、审计层、硬件层、数据层，以及后续接入的其他项目运维域；当运维层自己挂掉时，还要允许主 Agent 反向抢救它。

14. 支持两种保活模式

运维层和运维审计层也要兼容两种备用接管模式：

14.1 单云 + 设备端备用池

说明：

  • Cloud A 作为主用控制面
  • 一台首选 Standby Mac 或其他设备，作为首选备用控制器
  • 同时维护一个 standby_device_pool 作为后备容灾池

最低要求：

  • 至少一台首选备用设备必须常开
  • 必须具备独立于主云的可达路径
  • 每台候选备用设备至少运行：
    • Standby Controller
    • Local Ops Agent
    • Local Ops Audit Agent
    • Ops Rescue Gateway

当主云故障时：

  1. 当前活动备用设备接收主控失联告警
  2. 提升本机备用控制面
  3. 恢复最小项目视图、工单视图、修复审批链路
  4. 运维审计层继续做复验和修复回放

14.2 双云热备 / 温备

说明：

  • Cloud A 主用
  • Cloud B 备用

最低要求：

  • Cloud B 只做接管准备，不承担常态重负载
  • 保留备用控制面、备库、快照和恢复钩子

当主云故障时：

  1. Cloud B 接管控制面
  2. Chief Ops Audit Agent 继续保留紧急修复判定权
  3. 现场各节点 Local Ops Agent 继续执行修复动作
  4. 主云恢复后，再做账本回放与状态对账

14.3 统一抽象

无论采用哪种模式，运维层都应统一抽象为：

  • standby_provider = standby_mac | cloud_b | both

这样修复流程、审计流程、修复复验、主控恢复回放都不需要重新设计，只替换备用提供者即可。

14.4 单服务器模式下的自动备用设备切换

如果采用“单服务器 + 设备端保活”，就必须支持自动切换备用设备。

新增对象

  • standby_device_pool
  • standby_device_candidate
  • active_standby_device
  • takeover_package
  • standby_device_score

每台设备需要上报

  • device_id
  • eligible_for_standby
  • preferred_rank
  • always_on
  • memory_free_mb
  • disk_free_mb
  • lan_reachability
  • tunnel_reachability
  • last_heartbeat_at
  • takeover_package_version

自动切换规则

  1. 控制面维护 standby_device_pool
  2. 为排名前 N 的设备同步最小 takeover_package
  3. 如果当前 active_standby_device 心跳超时：
    • 立即标记为 degraded
    • 重新计算 standby_device_score
    • 自动提升下一台候选设备
  4. 新的备用设备接管后：
    • 发布新的 endpoint 清单
    • 更新 ops_mode_history
    • 通知主 Agent、Worker、手机 App

备用设备模式要求

  • cold standby
    • 未预部署接管组件
    • 不允许进入自动切换路径
  • warm standby
    • 已预部署接管组件
    • 已同步最近的 takeover_package
    • 允许自动切换
  • hot standby
    • 已预部署接管组件
    • 保持更高频状态同步
    • 允许自动切换，且优先级更高

结论：

  • 自动切换只允许选用 warm standby 或 hot standby
  • cold standby 只能作为人工应急候选，不能当自动保活候选

takeover_package 最小内容

  • 最近的项目 / 任务索引
  • endpoint 注册表
  • 修复工单索引
  • 权限与审批快照
  • 当前 standby_epoch

新增事件

  • standby_device_registered
  • standby_device_score_updated
  • active_standby_device_changed
  • takeover_package_synced
  • standby_device_failed

新增数据库表

  • standby_devices
  • standby_device_scores
  • standby_device_packages
  • standby_failover_history

候选设备预部署清单

每个 warm/hot standby 候选设备至少预部署：

  • Standby Controller
  • Local Ops Agent
  • Local Ops Audit Agent
  • Ops Rescue Gateway
  • 最小运行时依赖
  • 最小配置模板
  • endpoint 注册表缓存
  • 最近的 takeover_package