105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
# 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 管理，不改代码路径
|