init: ops-assistant codebase

docs/architecture-core.md

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