# Ops Assistant 独立项目 v1 方案

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

---

## v1 范围（先做）

优先只落地 **CPA 管理中枢**：

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

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

---

## 目录结构（新增）

```text
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` 加密机制存储

---

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

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

---

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

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

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

---

## 事故复盘（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）

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

---

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

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

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

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

## 下一步落地建议

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