openclaw/ops-assistant

Fork 0

Files

OpenClaw Agent 81deba4766 init: ops-assistant codebase

2026-03-19 21:23:28 +08:00

5.2 KiB

Raw Blame History

Ops Assistant 独立项目 v1 方案

目标

把高频运维动作做成固定命令 + 固定流水线，AI 只负责解释，不参与关键执行决策。

v1 范围（先做）

优先只落地 CPA 管理中枢：

固定命令入口（Telegram/QQ/飞书统一）
Runbook（YAML）确定性执行器
审计日志（步骤级）
高风险能力默认关闭（Feature Flag）

后续再扩展：Cloudflare DNS、邮箱转发。

目录结构（新增）

ops-assistant/
├── internal/
│   ├── core/
│   │   ├── command/             # 命令解析
│   │   ├── registry/            # 命令注册与路由
│   │   ├── runbook/             # runbook 结构、执行器、锁、target 解析
│   │   └── ops/                 # ops 服务编排、重试
│   └── module/
│       └── cpa/                 # CPA 模块命令与高风险闸门
├── runbooks/
│   ├── cpa_status.yaml
│   ├── cpa_usage_backup.yaml
│   └── cpa_usage_restore.yaml
└── docs/
    └── ops-assistant-v1.md

命令清单（v1）

/cpa status
/cpa usage backup
/cpa usage restore <backup_id>
/cpa codex clean
/cpa codex test
/cpa codex isolate

约束

仅允许上述命令（严格白名单）
每个命令映射到唯一 runbook
不支持自由 shell 指令输入

Runbook DSL（v1）

仅支持这些动作：

ssh.exec：远程执行固定命令
http.get / http.post：调用固定接口
file.upload：上传压缩包到 staging
file.extract：解压到 staging
assert.json：断言字段值
sleep：延迟

每个步骤必须有：

id
action
on_fail（stop | continue）

所有变量只能来自：

inputs.*（命令参数）
env.*（服务端配置）
steps.<id>.output.*（前置步骤输出）

审计与可追溯

建议新增两张表：

1) `ops_jobs`

id
command
runbook
operator_id
status（pending/running/success/failed）
started_at
ended_at

2) `ops_job_steps`

id
job_id
step_id
action
status
rc
stdout_tail
stderr_tail
started_at
ended_at

所有 Bot 命令回执都返回 job_id，便于追踪。

风险控制

默认 dry-run=true（先演练）
高风险步骤（restore/import）必须：
- 双确认（命令 + confirm token）
- feature flag 开启才允许执行
审计日志不写明文 secrets
全部 secrets 走现有 channel 加密机制存储

与现有系统的集成点（独立项目并存）

Bot 层：在 Telegram/QQ/飞书消息处理中增加 /cpa 命令分流
Web 层：新增 /ops 页面查看任务状态与步骤日志
模型层：新增 ops_jobs / ops_job_steps
配置层：增加 ops.targets（如 hwsg/wjynl）

阶段性进度汇报原则（必须遵守）

模板（四要素）

阶段名（设计/实现/自测/上线等）
已执行动作（具体到做了什么）
可验证证据（日志、产物路径、返回码、截图等）
下一步与前置条件（还差什么、需谁确认）

硬规则

无证据不使用“完成/已执行/进行中”等措辞
遇到卡点必须立即说明：卡点 + 原因 + 需要的唯一输入
先清单后执行的任务，未确认不得执行

事故复盘（2026-03-13，CF DNS Runbook）

详见：docs/cf-dns-runbook-incident-20260313.md

要点摘要：

认证方式误判（API Token 被当作 API Key）。
heredoc/转义在 ssh.exec 中导致脚本未执行。
最终采用 base64 + python3 -c exec 稳定执行。
强化“阶段性汇报必须带证据”的纪律。

验收标准（v1）

/cpa status 能返回结构化结果（非自由文本）
/cpa usage backup 能输出：备份路径 + sha256 + usage 快照
/cpa usage restore <id> 支持双校验（立即 + 延迟）
任一步骤失败时可追溯到具体 step 日志
未授权命令必须被拒绝并记录审计

当前已落地（2026-03-10）

已打通命令入口：Telegram / QQ / 飞书
已支持命令：
- /cpa status
- /cpa usage backup
- /cpa usage restore <backup_id>
已提供查询接口：
- GET /api/v1/ops/jobs
- GET /api/v1/ops/jobs/:id（含 steps）
assert.json 已支持真实 JSON 路径断言
已增加安全闸门：
- allow_ops_restore feature flag（默认 false）
- restore 需要 --confirm YES_RESTORE
- 支持 --dry-run
已支持 ops_targets 目标主机表（优先解析 target 名称）

当前 Core 强化（2026-03-10 第二阶段）

同 target 串行锁（避免并发覆盖）
作业元信息增强：target/risk_level/request_id/confirm_hash
统一错误码前缀（如 ERR_FEATURE_DISABLED / ERR_CONFIRM_REQUIRED / ERR_STEP_FAILED）
step 超时控制（默认 45s）
任务取消接口：POST /api/v1/ops/jobs/:id/cancel

下一步落地建议

为取消操作增加权限细分（ops.cancel）
增加 job 重试接口（仅失败任务可重试）
增加步骤级超时配置（runbook 可覆盖）
增加 Cloudflare / Mail 模块（在 Core 验收完成后）

5.2 KiB Raw Blame History Unescape Escape