docs: replace README with ops-assistant overview

2026-03-20 02:15:45 +08:00
parent 81deba4766
commit d83e25e95f
1 changed files with 71 additions and 163 deletions
--- a/README.md
+++ b/README.md
@@ -1,186 +1,94 @@
 # 🛠️ Ops-Assistant

-一个支持 **Telegram Bot** 和 **QQ Bot** 的智能记账机器人，带 Web 管理后台。
+一个面向运维场景的 **命令化 + Runbook** 自动化助手。通过 Telegram / QQ / 飞书等入口，触发 **可审计、可回溯、可控风控** 的运维流程。

-> 当前稳定版本：`v1.1.12`
+> 当前稳定版本：`v0.0.1`

-## 🆕 v1.1.12 更新
+## 🎯 设计目标

- 新增渠道管理页：`/channels`（移动端优先，统一 UI）
- 新增审计页面：`/audit`（中文化）
- 新增一键生效接口：`POST /api/v1/admin/channels/:platform/apply`
- 渠道配置安全增强：`***` 脱敏占位符不会覆盖真实 secrets
- apply 失败返回增强：失败时返回 `stage` 与 `committed` 字段
- 首页/登录/渠道/审计页面版本显示统一为 `vX.Y.Z`
+- **固定命令 + 固定流水线**：AI 只做解释，不参与关键执行决策
+- **步骤级审计**：每一步都有状态、输出、耗时与错误记录
+- **高风险能力默认关闭**：必须显式开关 + 二次确认
+- **Runbook 驱动**：流程可复用、可回溯、可迁移

-## ✨ 功能特性
+## ✅ 当前能力

- **多平台支持**：同时接入 Telegram Bot 和 QQ Bot（WebSocket 模式）
- **智能记账**：发送自然语言自动识别金额和消费分类（基于 jieba 分词）
- **150+ 预设分类关键词**：餐饮、交通、购物、饮品、水果、住房、医疗、娱乐等
- **Web 管理后台**：响应式设计，支持记录查看、删除、CSV 导出
- **金额精确**：使用分（int64）存储，避免浮点精度问题
- **优雅关闭**：支持 SIGTERM/SIGINT 信号，干净退出
+### 核心功能
+- 统一命令入口（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. 复制配置文件
+# 1. 复制配置
 cp config.yaml.example config.yaml

-# 2. 编辑配置（填入 Bot Token 等信息）
+# 2. 编辑配置（Bot Token / 管理员账号等）
 vi config.yaml

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

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

-```bash
-# 1. 准备配置文件
-cp config.yaml.example config.yaml
-vi config.yaml
-
-# 2. 使用 docker-compose
-docker-compose up -d
-
-# 或直接 docker run
-docker run -d \
-  --name ops-assistant \
-  -p 9621:9621 \
-  -v $(pwd)/config.yaml:/app/config.yaml:ro \
-  -v $(pwd)/data:/app/data \
-  ouaone/ops-assistant:latest
-```
-
-### 从源码编译
-
-```bash
-# 需要 Go 1.22+、GCC（gojieba 依赖 CGO）
-make build
-
-# 交叉编译 Linux
-make build-linux
-```
-
-## ⚙️ 配置说明
-
-```yaml
-server:
-  port: 9621                    # Web 后台端口
-  key: "your-secret-key"        # 会话密钥
-
-database:
-  path: "./xiaji.db"            # SQLite 数据库路径
-
-admin:
-  username: "admin"             # Web 后台用户名
-  password: "your_password"     # Web 后台密码
-
-telegram:
-  enabled: true                 # 是否启用 Telegram Bot
-  token: "YOUR_BOT_TOKEN"       # BotFather 获取的 Token
-
-qqbot:
-  enabled: false                # 是否启用 QQ Bot
-  appid: "YOUR_APPID"           # QQ 开放平台 AppID
-  secret: "YOUR_SECRET"         # QQ 开放平台 AppSecret
-```
-
-## 💬 使用方式
-
-### Telegram Bot 命令
-
-| 命令 | 说明 |
-|------|------|
-| `/start` | 欢迎信息 |
-| `/help` | 使用帮助 |
-| `/list` | 最近 10 条记录 |
-| `/today` | 今日消费汇总 |
-| 直接发消息 | 自动记账（如"午饭 25元"） |
-
-### QQ Bot 关键词
-
-| 关键词 | 说明 |
-|--------|------|
-| `帮助` / `菜单` / `功能` | 显示帮助 |
-| `查看` / `记录` / `列表` | 最近 10 条记录 |
-| `今日` / `今天` | 今日消费汇总 |
-| 直接发消息 | 自动记账 |
-
-### 记账格式
-
-支持多种自然语言格式：
-
-```
-午饭 25元
-打车 ¥30
-买咖啡15块
-车费10元
-超市买水果38.5
-```
-
-### 消费分类
-
-系统预设了 150+ 个关键词，自动匹配以下分类：
-
-| 分类 | 示例关键词 |
-|------|-----------|
-| 🍜 餐饮 | 早饭、午饭、晚饭、外卖、火锅、面条 |
-| 🚗 交通 | 打车、车费、地铁、公交、加油 |
-| 🛒 购物 | 买、淘宝、超市、衣服、手机 |
-| ☕ 饮品 | 咖啡、奶茶、星巴克、可乐 |
-| 🍎 水果 | 水果、苹果、香蕉、西瓜 |
-| 🍪 零食 | 零食、面包、蛋糕、甜品 |
-| 🏠 住房 | 房租、水电、物业、宽带 |
-| 📱 通讯 | 话费、流量、充值 |
-| 💊 医疗 | 看病、药、医院、挂号 |
-| 🎮 娱乐 | 电影、游戏、健身、旅游 |
-| 📚 教育 | 书、课、培训、学费 |
-| 🚬 烟酒 | 烟、白酒、红酒 |
-
-## 🌐 Web 管理后台
-
-访问 `http://localhost:9621`：
-
- 📊 今日支出 / 本月支出 / 总记录数统计
- 📋 最近 50 条记录列表
- 🔍 按分类筛选
- 🗑️ 删除记录
- 📥 CSV 导出（Excel 兼容 BOM 编码）
-
-## 🏗️ 项目结构
-
-```
-ops-assistant/
-├── cmd/main.go              # 入口文件
-├── config/config.go         # 配置加载与验证
-├── version/version.go       # 版本信息
-├── models/models.go         # 数据模型与分类关键词
-├── internal/
-│   ├── bot/telegram.go      # Telegram Bot
-│   ├── qq/qq.go             # QQ Bot (WebSocket)
-│   ├── service/finance.go   # 记账核心服务（jieba 分词）
-│   └── web/server.go        # Web 管理后台
-├── templates/index.html     # Web 前端页面
-├── config.yaml.example      # 配置示例
-├── Dockerfile               # Docker 镜像
-├── docker-compose.yml       # Docker Compose
-└── Makefile                 # 构建脚本
-```
-
-## 📋 技术栈
-
- **语言**: Go 1.22
- **Web 框架**: Gin
- **数据库**: SQLite (GORM)
- **分词**: gojieba (结巴分词 Go 版)
- **Telegram SDK**: go-telegram-bot-api v5
- **QQ SDK**: tencent-connect/botgo v0.2.1 (WebSocket 模式)
+## 📌 相关文档
+- `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