init: ops-assistant codebase

docs/ops-assistant-v1.md

@@ -0,0 +1,200 @@
+# 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 验收完成后）