# 🛠️ Ops-Assistant

一个面向运维场景的 **命令化 + Runbook** 自动化助手。通过 Telegram / QQ / 飞书等入口，触发 **可审计、可回溯、可控风控** 的运维流程。

> 当前稳定版本：`v0.0.1`

## 🎯 设计目标

- **固定命令 + 固定流水线**：AI 只做解释，不参与关键执行决策
- **步骤级审计**：每一步都有状态、输出、耗时与错误记录
- **高风险能力默认关闭**：必须显式开关 + 二次确认
- **Runbook 驱动**：流程可复用、可回溯、可迁移

## ✅ 当前能力

### 核心功能
- 统一命令入口（Telegram / QQ / 飞书）
- Runbook 执行引擎（YAML）
- 步骤级审计与回溯
- 目标主机管理（ops targets）
- 风险控制与干跑（dry-run）

### 已支持模块
- **CPA 模块**
  - `/cpa status`
  - `/cpa usage backup`
  - `/cpa usage restore <backup_id> [--confirm YES_RESTORE] [--dry-run]`

- **Cloudflare 模块（CF）**
  - `/cf status`
  - `/cf zones`
  - `/cf dns list <zone_id>`
  - `/cf dns update <zone_id> <record_id> <type> <name> <content> [ttl] [proxied:true|false]`
  - `/cf dnsadd <name> <content> [on|off] [type]`
  - `/cf dnsset <record_id> <content> [true]`
  - `/cf dnsdel <record_id> YES`
  - `/cf dnsproxy <record_id|name> on|off`
  - `/cf workers list`

> 详细命令设计见：`docs/cf-commands-design.md`

## 🧩 Runbook DSL（概览）
支持动作：
- `ssh.exec`
- `http.get` / `http.post`
- `file.upload` / `file.extract`
- `assert.json`
- `sleep`

变量来源：
- `inputs.*`
- `env.*`
- `steps.<id>.output`

## 🗂️ 项目结构

```
ops-assistant/
├── cmd/                 # 入口
├── internal/
│   ├── core/            # 命令解析/执行/审计/风险控制
│   └── module/          # CPA/CF/Mail 等模块
├── runbooks/            # YAML Runbook
├── templates/           # Web 控制台模板
├── docs/                # 设计/规范/复盘
└── config.yaml.example  # 配置示例
```

## ⚙️ 快速开始

```bash
# 1. 复制配置
cp config.yaml.example config.yaml

# 2. 编辑配置（Bot Token / 管理员账号等）
vi config.yaml

# 3. 运行
./ops-assistant
```

## 🔒 风控与审计
- 高风险操作默认关闭（feature flag）
- 需要二次确认的命令必须带确认词
- 每个命令产生 `ops_jobs` 记录，步骤落地 `ops_job_steps`

## 📌 相关文档
- `docs/ops-assistant-v1.md`：v1 方案
- `docs/cf-commands-design.md`：CF 命令设计
- `docs/cf-dns-runbook-incident-20260313.md`：事故复盘
- `docs/debug/cf-dnsproxy-dnsadd-20260319.md`：本次修复记录

## 📄 License
MIT
