ops-assistant/docs/architecture-core.md

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