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

适用范围：

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