feat: 模块化命令框架 + runbook 严格断言与查询结果回传

- core/module: 命令模板、门控(feature flag/confirm/dry-run)、ecode 错误标签、ResultFormatter
- runbook executor: http.get/http.post/assert.json(expect_success 严格断言)、目标主机管理、任务落库、最终 stdout 直接回传
- cf 模块: /cf dns list 支持域名自动解析 zone_id;dns list/zones/workers list 格式化回传;API success:false 判真失败
- 全部 CF/CPA runbook 接入严格断言,杜绝假阳性 success
- 新增 cpa/cfdav/mail/sub 模块与 runbooks;QQ 订阅到期提醒调度
- Web 后台: 模块设置(CF/CPA/cfdav/AI)、OPS 任务、渠道管理、审计页
This commit is contained in:
2026-09-13 07:42:17 +08:00
parent 9085c490f3
commit 81939825d1
86 changed files with 6885 additions and 467 deletions
+104
View File
@@ -0,0 +1,104 @@
# Ops-Assistant Core Architecture (v0.0.1)
> 目标:程序可独立运行,AI 可选接入但无执行权;新通道/新功能模块可低成本适配接入。
## 1. 设计红线(强约束)
1. **执行权唯一入口**:所有变更类动作只能经 `Command -> Policy -> Runbook Engine`。
2. **AI 不可执行**:AI 仅能做建议/解释,不可直接调用执行器。
3. **通道与业务解耦**:TG/QQ/Feishu 仅适配输入输出,不承载业务规则。
4. **模块与核心解耦**:CPA/CF/Mail 仅注册命令和构建 runbook 请求。
5. **全链路可审计**:job/step、operator、request_id、risk_level、input_json 必须可追溯。
---
## 2. 分层结构
1) **Channel Adapter 层**
- 责任:收消息、身份映射、回消息。
- 输入:平台消息。
- 输出:统一消息结构(text/operator/channel)。
2) **Command Runtime 层**
- 责任:命令解析、路由、参数校验。
- 输出:模块请求(Module Request)。
3) **Policy Gate 层**
- 责任:权限、feature flag、confirm token、dry-run。
- 输出:允许/拒绝(含原因)。
4) **Runbook Engine 层**
- 责任:确定性执行 step(白名单动作)、锁、超时、断言、取消。
5) **Audit/State 层**
- 责任:记录 job/step 状态和执行证据。
6) **AI Advisor(可选)**
- 责任:建议命令、参数补全、解释结果。
- 限制:**无执行器句柄、无 DB 写权限、无外部动作权限**。
---
## 3. 接入标准
### 3.1 新通道接入(最小接口)
- 实现统一消息输入
- 实现统一回复输出
- 提供身份映射(operator_id)
> 新通道不允许直接操作 runbook / db。
### 3.2 新功能模块接入(最小接口)
- 注册命令前缀(如 `/cpa` `/cf` `/mail`)
- 输入校验
- 构建 runbook 请求(name + inputs + meta + policy)
> 新模块不允许直接执行 shell/ssh,只能请求 runbook 引擎。
### 3.3 当前注册机制
- Parser 按 `/xxx` 自动识别 `module=xxx`
- Registry 支持两种注册:
- 精确命令注册(`Register("/health", ...)`)
- 模块前缀注册(`RegisterModule("cpa", ...)`)
- 推荐新模块使用 `RegisterModule`,降低接入成本。
---
## 4. AI 介入模式
- `off`:完全关闭 AI(默认可用)
- `suggest`:允许 AI 给出命令建议,不自动执行
- `explain`:允许 AI 解释结果,不自动执行
### 安全边界
- AI 输出必须是文本建议,不是可执行指令。
- 任何执行动作都需要用户命令触发并通过 Policy Gate。
---
## 5. 统一执行链
`Channel -> Command -> Module.BuildRequest -> Policy.Check -> Runbook.Execute -> Audit -> Reply`
这条链是扩展 CF/Mail 时的唯一合法路径。
---
## 6. 当前状态与后续
### 已具备
- Runbook 引擎(执行/锁/超时/取消)
- CPA 模块(status/backup/restore)
- 任务审计(jobs/steps)
- CF/Mail 模块骨架(`/cf status`、`/mail status` 占位)
### 下一步(框架整理)
1. 将模块内零散 gate 逻辑统一沉淀到 `core/policy`
2. 形成通道适配模板和模块适配模板
3. 引入 `core/ai` 的 Noop Advisor(默认 off)
4. 在 CF/Mail 骨架上补齐真实 runbook(不改核心)
### 模块管理可观测性
- 聊天命令:`/ops modules` 查看注册模块与启用状态
- Web 首页:模块状态卡片(读取 `enable_module_*`)
- 模块启停:统一通过 feature flag 管理,不改代码路径