# 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 管理，不改代码路径