From 3c1c40a2a2b71566f8a169afd79bcb01964e3971 Mon Sep 17 00:00:00 2001 From: "guangfei.zhao" Date: Tue, 31 Mar 2026 09:41:03 +0800 Subject: [PATCH] add platform and tools docs --- README.md | 12 + platform/AIOps_Platform_Requirements.md | 606 ++++++++++++++++++++++ tools/AIOps_Tools_Requirements.md | 660 ++++++++++++++++++++++++ 3 files changed, 1278 insertions(+) create mode 100644 platform/AIOps_Platform_Requirements.md create mode 100644 tools/AIOps_Tools_Requirements.md diff --git a/README.md b/README.md index cca704e..94b4379 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,16 @@ - [`workflow/Dify_Lightweight_Customization_and_Upgrade.md`](workflow/Dify_Lightweight_Customization_and_Upgrade.md) ：基于固定 Dify tag 的轻量定制与升级策略 +### Platform 文档 + +- [`platform/AIOps_Platform_Requirements.md`](platform/AIOps_Platform_Requirements.md) + ：`aiops-platform` 需求清单与范围定义 + +### Tools 文档 + +- [`tools/AIOps_Tools_Requirements.md`](tools/AIOps_Tools_Requirements.md) + ：`aiops-tools` 需求清单与范围定义 + ## Dify Baseline Management 当前与 Dify 相关的轻量定制和升级策略，统一参考： @@ -57,6 +67,8 @@ - `pagerduty/`：PagerDuty 对标拆解、MVP 范围与页面设计文档 - `workflow/`：`aiops-workflow` 相关需求与设计文档 +- `platform/`：`aiops-platform` 相关需求与主控流程文档 +- `tools/`：`aiops-tools` 相关需求与接口治理文档 ## 使用建议 diff --git a/platform/AIOps_Platform_Requirements.md b/platform/AIOps_Platform_Requirements.md new file mode 100644 index 0000000..6a4622b --- /dev/null +++ b/platform/AIOps_Platform_Requirements.md @@ -0,0 +1,606 @@ +# AIOps Platform Requirements + +## 1. 文档目标 + +本文档用于定义 `aiops-platform` 项目的职责边界、MVP 范围、核心对象模型、主要页面能力、接口要求与非功能要求。 + +本文档重点回答以下问题： + +1. `aiops-platform` 在三层架构中究竟负责什么。 +2. 平台层为什么必须作为唯一主控层存在。 +3. MVP 阶段平台必须先交付哪些核心能力。 +4. 平台如何与 `aiops-workflow` 和 `aiops-tools` 协同。 + +本文档是平台层的正式需求清单，和 `workflow/`、`tools/` 下的文档共同构成当前架构的三层需求基线。 + +## 2. 项目定位 + +### 2.1 核心定义 + +`aiops-platform` 负责“事件如何流转、谁来审批、结果如何展示”。 + +它是整个系统的唯一主控层，持有核心业务状态，负责对事件、Incident、审批、执行、审计和展示进行统一编排。 + +平台层的核心职责是： + +- 接收并管理 Incident 主流程 +- 维护 Incident 生命周期与状态机 +- 触发 `aiops-workflow` 获取结构化 RCA 和动作建议 +- 调用 `aiops-tools` 执行查询代理和受控动作 +- 提供页面、接口、审计、审批、时间线与运营视图 + +### 2.2 不负责的事情 + +`aiops-platform` 明确不负责： + +- 具体 AI 工作流编排细节 +- Prompt 管理、RAG 检索策略管理 +- 直接对接底层 Prometheus / Loki / K8s / Ansible 协议 +- 直接持有工具查询逻辑和执行器实现细节 + +### 2.3 为什么平台层必须独立 + +平台层必须独立存在，原因在于： + +- Incident 主状态不能放在 workflow 层 +- 审批和执行控制不能放在 AI 层 +- 页面与业务对象不能散落在工具层 +- 审计、时间线、审批、展示必须有统一业务中枢 + +如果没有独立平台层，系统会很快变成： + +- 状态分散 +- 页面和业务逻辑耦合不清 +- AI 建议与真实执行缺少边界 +- 审计链路断裂 + +## 3. 与其他两层的边界关系 + +### 3.1 与 `aiops-workflow` 的关系 + +平台层调用 `aiops-workflow` 获取： + +- 结构化 RCA +- 证据链 +- 影响范围 +- 动作建议 + +但平台层始终保留以下控制权： + +- Incident 状态是否推进 +- 动作是否展示 +- 动作是否需要审批 +- 动作是否允许执行 + +### 3.2 与 `aiops-tools` 的关系 + +平台层调用 `aiops-tools` 获取： + +- 受控查询结果 +- 动作执行结果 +- 工具调用与执行审计关联信息 + +但平台层始终保留以下业务控制： + +- 谁可以发起执行 +- 哪些动作需要审批 +- 哪些结果进入时间线 +- 哪些数据进入页面展示和 KPI 统计 + +### 3.3 平台层的绝对职责 + +只有平台层应当持有以下对象的业务主状态： + +- `incident` +- `incident_timeline` +- `ai_rca_result` +- `remediation_action` +- `approval_record` +- `audit_log` + +## 4. 目标用户 + +### 4.1 一线响应人 + +- NOC / L1 值班人员 +- SRE / 运维工程师 +- 应用负责人 + +核心诉求： + +- 快速看到当前事件 +- 快速进入 Incident 详情 +- 快速理解 RCA、影响和建议动作 +- 快速执行或提交审批 + +### 4.2 高级响应人与负责人 + +- L2 / L3 工程师 +- Incident Commander +- 运维负责人 + +核心诉求： + +- 管理重大 Incident +- 分配责任人 +- 查看完整时间线 +- 审核执行动作和审批状态 + +### 4.3 安全与审计角色 + +- 安全管理员 +- 审批人 +- 审计人员 + +核心诉求： + +- 看到谁提了什么动作 +- 看到谁审批了什么动作 +- 看到执行结果与回滚入口 +- 看到完整可追踪审计链路 + +## 5. MVP 成功标准 + +MVP 阶段，平台层至少应达到以下结果： + +1. 能形成统一 Incident 主流程。 +2. 能稳定维护 Incident 状态机。 +3. 能展示结构化 RCA 与动作建议。 +4. 能对动作执行进行审批与控制。 +5. 能沉淀统一 Timeline 与审计记录。 +6. 能输出基础运营指标。 + +建议的 MVP 指标： + +| 指标 | 说明 | MVP 目标 | +| --- | --- | --- | +| Incident creation success rate | Incident 创建成功率 | 高于 99% | +| Timeline completeness | 时间线事件沉淀完整率 | 100% | +| Approval trace completeness | 审批链可追踪率 | 100% | +| RCA display availability | RCA 展示可用率 | 高于 99% | +| Action execution traceability | 动作执行可回溯率 | 100% | +| Dashboard data availability | 指标看板可用率 | 高于 99% | + +## 6. 范围边界 + +### 6.1 MVP 必须范围 + +- Incident API +- Incident 状态机 +- 事件列表页 +- Incident 详情页 +- Timeline +- RCA 结果展示卡 +- 动作建议展示与执行面板 +- 审批流基础能力 +- 审计中心基础能力 +- KPI / Dashboard 基础能力 + +### 6.2 MVP 可选增强 + +- 更强的筛选与搜索 +- 更丰富的批量操作 +- 更细粒度的角色与权限视图 +- 通知中心 +- Postmortem 入口联动 + +### 6.3 明确不在 MVP + +- 完整 CMDB 平台 +- 完整 ITSM / 工单替代 +- 高复杂度多租户商业化后台 +- 深度 AI 配置管理界面 +- 复杂可视化编排中心 + +## 7. 核心设计原则 + +- 平台层是唯一主控层 +- 状态和展示必须统一归平台持有 +- AI 结果必须结构化接入平台 +- 执行动作必须经过平台确认或审批 +- 所有关键操作都要进入 Timeline 和审计 +- 页面围绕 Incident 主流程组织，而不是围绕底层技术组件组织 + +## 8. 核心对象模型 + +建议平台层至少围绕以下对象建模： + +| 对象 | 说明 | 关键字段 | +| --- | --- | --- | +| `Incident` | 主事件实体 | incident_id, title, status, severity, service, owner | +| `IncidentTimeline` | 时间线事件 | incident_id, event_type, payload, operator | +| `IncidentContext` | 事件上下文摘要 | service, env, topology, recent_changes | +| `AIRCAResult` | AI 诊断结果 | conclusion, confidence, impact_scope, evidence | +| `RemediationAction` | 建议动作或待执行动作 | action_id, risk, mode, approval | +| `ApprovalRecord` | 审批记录 | approval_id, approver, status, comment | +| `AuditLog` | 审计记录 | trace_id, actor, resource, operation, result | +| `DashboardMetric` | 指标聚合对象 | metric_name, value, time_range | + +## 9. MVP 功能需求 + +## 9.1 Incident API + +### 9.1.1 能力目标 + +平台层必须作为 Incident 的统一入口和唯一事实来源。 + +### 9.1.2 基础能力 + +- 创建 Incident +- 查询 Incident +- 更新 Incident 状态 +- 关闭 Incident +- 重开 Incident +- 触发诊断 +- 追加时间线事件 + +### 9.1.3 验收标准 + +1. Incident 状态只能通过平台层接口变更。 +2. 所有状态变更都能被审计。 +3. Incident 可以和 AI 结果、审批、执行记录关联。 + +## 9.2 Incident 状态机 + +### 9.2.1 推荐状态 + +- `new` +- `triaged` +- `diagnosing` +- `remediating` +- `resolved` +- `closed` + +### 9.2.2 必须能力 + +- 校验合法状态跳转 +- 拒绝非法状态变更 +- 状态变更写入时间线 +- 状态变更写入审计 + +### 9.2.3 验收标准 + +1. 平台能明确控制状态机流转。 +2. 不能绕过平台直接改 Incident 主状态。 + +## 9.3 事件列表页 + +### 9.3.1 页面目标 + +这是平台的主入口，用于让用户快速掌握当前故障状态。 + +### 9.3.2 必须展示内容 + +- Incident 标题 +- 状态 +- 严重级别 +- 服务 +- 责任人 +- 开始时间 +- 最近更新时间 +- 是否有 RCA +- 是否有待审批动作 + +### 9.3.3 必须操作 + +- 筛选 +- 搜索 +- 进入详情页 +- 快速确认接手或关闭 + +## 9.4 Incident 详情页 + +### 9.4.1 页面目标 + +这是平台最核心的业务页面，应承载大部分响应、诊断查看、审批和执行入口。 + +### 9.4.2 页面模块建议 + +- 基础信息卡 +- 状态与责任人 +- RCA 卡片 +- 证据链引用 +- 影响范围 +- 动作建议与执行面板 +- Timeline +- 审批记录 +- 审计摘要 + +### 9.4.3 必须操作 + +- 变更状态 +- 触发诊断 +- 查看和刷新 RCA +- 发起审批 +- 执行动作 +- 查看执行结果 + +## 9.5 RCA 展示模块 + +### 9.5.1 平台职责 + +平台层不负责生成 RCA，但必须负责承接、展示和落库 `aiops-workflow` 返回的结构化结果。 + +### 9.5.2 必须展示内容 + +- 诊断结论 +- 置信度 +- 影响范围 +- 证据链 +- 建议动作列表 + +### 9.5.3 验收标准 + +1. 平台无需解析自由文本即可展示核心结果。 +2. 低置信度结果有明确提示。 + +## 9.6 动作建议与执行控制台 + +### 9.6.1 平台职责 + +平台层负责展示建议动作，并决定这些动作是： + +- 仅展示 +- 需要审批 +- 可以执行 + +### 9.6.2 必须展示内容 + +- 动作名称 +- 风险等级 +- 模式 `auto | approval | suggest_only` +- 当前审批状态 +- 当前执行状态 +- 回滚入口提示 + +### 9.6.3 必须操作 + +- 提交审批 +- 审批通过 / 驳回 +- 执行动作 +- 查看执行结果 + +### 9.6.4 验收标准 + +1. 平台能统一展示动作清单。 +2. 平台能和 `aiops-tools` 的执行结果正确关联。 +3. 高风险动作不会绕过平台控制直接执行。 + +## 9.7 审批流 + +### 9.7.1 MVP 范围 + +平台层需要有基础审批能力，但不必一开始就做复杂 BPM 引擎。 + +### 9.7.2 必须能力 + +- 为动作创建审批请求 +- 指定审批人 +- 审批通过 +- 审批驳回 +- 记录审批意见 +- 审批记录进入 Timeline 和审计 + +### 9.7.3 验收标准 + +1. 动作执行前能校验审批状态。 +2. 审批记录可在 Incident 详情页查看。 + +## 9.8 Incident Timeline + +### 9.8.1 目标 + +Timeline 是平台层的关键基础设施，是 Incident 回放、审计联动和复盘的核心数据源。 + +### 9.8.2 必须进入 Timeline 的事件 + +- Incident 创建 +- 状态变更 +- 诊断触发 +- RCA 结果写入 +- 动作建议更新 +- 审批发起 +- 审批通过 / 驳回 +- 执行动作 +- 执行成功 / 失败 +- Incident 关闭 / 重开 + +### 9.8.3 验收标准 + +1. 关键动作不会遗漏时间线记录。 +2. Timeline 可作为 Incident 回放依据。 + +## 9.9 审计中心 + +### 9.9.1 平台职责 + +平台层负责持有业务主审计记录，并与工具层、workflow 层的执行记录关联。 + +### 9.9.2 必须支持 + +- 按 `incident_id` 查询 +- 按操作人查询 +- 按动作类型查询 +- 按时间范围查询 +- 导出审计结果 + +### 9.9.3 必须记录内容 + +- 操作人 +- 资源对象 +- 操作类型 +- 请求摘要 +- 结果摘要 +- 时间 +- trace 关联信息 + +## 9.10 Dashboard 与 KPI + +### 9.10.1 MVP 范围 + +平台层需要提供最基础的运营指标视图。 + +### 9.10.2 建议指标 + +- Incident 数量趋势 +- MTTA +- MTTR +- RCA 可用率 +- 动作执行成功率 +- 审批通过率 +- 自动恢复率 + +### 9.10.3 目标用户 + +- 运维负责人 +- 团队负责人 +- 项目管理者 + +## 10. 页面与信息架构建议 + +## 10.1 首批页面建议 + +- Incident List +- Incident Detail +- Action Review Panel +- Audit Center +- Dashboard + +### 10.2 页面组织原则 + +- Incident 是主导航中心 +- RCA 和动作展示贴着 Incident 展开 +- 审批和执行入口贴着动作展开 +- 审计与 Dashboard 属于辅助管理视角 + +## 11. 与 `workflow` 的接口要求 + +### 11.1 触发诊断 + +平台需要能向 `aiops-workflow` 发起诊断请求。 + +建议接口语义： + +- `POST /api/v1/incidents/{incident_id}/diagnose` + +### 11.2 查询任务结果 + +平台需要支持异步拿回任务结果。 + +建议接口语义： + +- `GET /api/v1/ai/tasks/{task_id}` + +### 11.3 平台侧处理要求 + +- 平台负责把 workflow 返回结果落库 +- 平台负责把 workflow 返回结果映射到页面对象 +- 平台负责把关键结果写入 Timeline + +## 12. 与 `tools` 的接口要求 + +### 12.1 查询类能力 + +平台可在必要时通过平台代理方式调用工具层，但不建议平台散落直接调用底层系统。 + +### 12.2 执行类能力 + +平台需要通过 `aiops-tools` 发起执行请求，并接收结构化结果。 + +建议接口语义： + +- `POST /api/v1/incidents/{incident_id}/actions/{action_id}/execute` + +### 12.3 平台侧处理要求 + +- 校验审批状态 +- 校验执行条件 +- 接收执行结果 +- 写入 Timeline 和审计 + +## 13. 非功能要求 + +### 13.1 安全性 + +- 高风险动作必须审批 +- 审计日志完整留痕 +- 权限分层明确 + +### 13.2 可用性 + +- Incident 主流程高可用 +- 查询与展示路径稳定 +- 关键详情页响应可接受 + +### 13.3 可维护性 + +- 业务对象清晰 +- 与 workflow/tools 边界清晰 +- 平台逻辑不要下沉到工具层或 AI 层 + +### 13.4 可扩展性 + +- 可增加更多 Dashboard 视图 +- 可增加更多审批规则 +- 可增加更多动作类型与展示模块 + +## 14. 分阶段实施建议 + +### Phase 1 + +- Incident API +- Incident 状态机 +- Incident List / Detail 基础页 +- RCA 展示卡 +- Timeline + +### Phase 2 + +- 动作建议展示 +- 执行控制台 +- 基础审批流 +- 基础审计中心 + +### Phase 3 + +- Dashboard +- 更强的筛选与检索 +- 更强的审批与审计能力 +- 和 Postmortem / Knowledge 回流联动 + +## 15. 推荐的仓库内文档与资产结构 + +如果后续 `aiops-platform` 独立成仓，可参考如下结构： + +```text +platform/ + AIOps_Platform_Requirements.md + pages/ + api-contracts/ + state-machine/ + approval/ + audit/ +``` + +## 16. 结论 + +`aiops-platform` 的本质不是一个“展示层前端 + 普通后端 API”，而是整个系统的业务主控中枢。 + +如果 `aiops-workflow` 负责“如何做诊断”，`aiops-tools` 负责“如何安全地查和做”，那么 `aiops-platform` 负责的就是： + +- 事件如何进入主流程 +- 状态如何被维护 +- RCA 如何被承接和展示 +- 动作如何被审批和执行 +- 所有结果如何进入时间线与审计 + +因此，平台层的第一优先级不是做最复杂的 AI 管理后台，而是先把以下主链路做稳： + +- Incident +- 状态机 +- RCA 承接 +- 动作审批执行 +- Timeline +- Audit + +只有这条业务主链路稳住，workflow 和 tools 的价值才能真正落地。 diff --git a/tools/AIOps_Tools_Requirements.md b/tools/AIOps_Tools_Requirements.md new file mode 100644 index 0000000..e06e863 --- /dev/null +++ b/tools/AIOps_Tools_Requirements.md @@ -0,0 +1,660 @@ +# AIOps Tools Requirements + +## 1. 文档目标 + +本文档用于定义 `aiops-tools` 项目的职责边界、MVP 范围、核心能力、输入输出契约与非功能要求。 + +本文档重点回答以下问题： + +1. `aiops-tools` 在整体 AIOps 架构中的定位是什么。 +2. 为什么 `aiops-tools` 必须作为独立项目域存在。 +3. MVP 阶段必须先做哪些查询与执行能力。 +4. 如何保证工具调用和执行动作在安全、审计、幂等、超时控制下运行。 + +本文档与 `aiops-platform`、`aiops-workflow` 配套阅读，三者共同构成当前阶段建议的项目边界。 + +## 2. 项目定位 + +### 2.1 核心定义 + +`aiops-tools` 负责“如何安全地查询数据、如何安全地执行动作”。 + +它不是 Incident 主控层，也不是诊断编排层，而是位于 `aiops-workflow` 与真实生产系统之间的安全工具与执行网关层。 + +其核心职责是： + +- 向 `aiops-workflow` 暴露标准化查询工具。 +- 向 `aiops-platform` 暴露受控执行能力。 +- 对接真实外部系统，如 Prometheus、Loki/ELK、K8s API、Ansible、变更系统。 +- 提供鉴权、限流、超时、重试、幂等、审计打点、回滚入口等治理能力。 + +### 2.2 不负责的事情 + +`aiops-tools` 明确不负责： + +- 持有 `Incident` 主状态 +- 页面展示 +- 审批流程编排 +- 最终 RCA 推理逻辑 +- 结构化诊断工作流编排 +- 直接决定某个建议动作是否应该执行 + +### 2.3 为什么这一层必须独立 + +如果把工具查询和动作执行直接塞进 `platform` 或 `workflow`，会带来几个问题： + +- `workflow` 直接接触生产执行能力，安全边界失控 +- `platform` 直接耦合多种底层系统协议，后续替换和扩展困难 +- 查询和执行能力缺少统一治理，审计和幂等难以标准化 + +因此，`aiops-tools` 的价值不只是“工具集合”，而是“统一安全网关”。 + +## 3. 目标调用方与使用场景 + +### 3.1 直接调用方 + +- `aiops-workflow` +- `aiops-platform` + +### 3.2 典型调用场景 + +#### 场景一：诊断阶段查询证据 + +- `aiops-workflow` 调用 `query_metrics` +- `aiops-workflow` 调用 `query_logs` +- `aiops-workflow` 调用 `query_k8s` +- `aiops-workflow` 调用 `query_changes` + +目标是收集指标、日志、资源状态和近期变更，形成证据链。 + +#### 场景二：平台执行低风险动作 + +- `aiops-platform` 对通过审批或命中低风险策略的动作调用 `execute_action` + +目标是通过统一执行网关触发真正动作，而不是让平台自己直接操作生产环境。 + +#### 场景三：审计与回放 + +- `aiops-platform` 或内部审计任务查询工具执行记录、执行结果、失败原因、重试轨迹 + +### 3.3 主要使用者 + +- 后端工程师：对接平台与 workflow 的工具调用接口 +- AI 工程师：让 workflow 稳定调用标准化工具 +- 运维/平台工程师：维护外部系统连接、凭证、执行器和治理策略 +- 安全/审计角色：核查调用记录、执行记录和失败原因 + +## 4. MVP 成功标准 + +MVP 阶段，`aiops-tools` 至少应达到以下结果： + +1. 查询类工具可稳定供 `aiops-workflow` 调用。 +2. 执行类工具可在受控条件下供 `aiops-platform` 调用。 +3. 每次查询和执行都能留下结构化审计记录。 +4. 超时、失败、重试、幂等等基础可靠性能力具备。 +5. 不允许绕过平台审批直接执行生产动作。 + +建议的 MVP 指标： + +| 指标 | 说明 | MVP 目标 | +| --- | --- | --- | +| Tool success rate | 工具调用成功率 | 高于 95% | +| Query latency P95 | 查询类工具 P95 时延 | 可观测且稳定 | +| Execute latency P95 | 执行类工具 P95 时延 | 可观测且稳定 | +| Audit completeness | 调用审计完整率 | 100% | +| Idempotency correctness | 幂等请求不重复执行 | 100% | +| Unauthorized execute rate | 未授权执行通过率 | 0 | + +## 5. 范围边界 + +### 5.1 MVP 必须范围 + +- `query_metrics` +- `query_logs` +- `query_k8s` +- `query_changes` +- `execute_action` +- 统一工具调用协议 +- 统一执行请求协议 +- 鉴权 +- 限流 +- 超时控制 +- 重试策略 +- 幂等控制 +- 审计打点 +- 回滚入口定义 + +### 5.2 MVP 可选增强 + +- `query_topology` +- `query_cmdb` +- `query_deployments` +- 更丰富的执行器类型 +- 细粒度配额控制 +- 多环境多集群路由 + +### 5.3 明确不在 MVP + +- Incident 状态管理 +- 审批流引擎 +- 复杂图形化工具编排界面 +- 自主推理和 RCA 生成 +- 完整 CMDB 平台替代 +- 全量 ITSM 功能替代 + +## 6. 核心设计原则 + +- 查询与执行严格分离 +- 工具调用协议统一 +- 执行必须受控 +- 默认最小权限 +- 失败必须可追踪 +- 所有动作可审计 +- 高风险动作不由工具层自行放行 + +特别强调： + +- `query_*` 允许被 `aiops-workflow` 直接调用 +- `execute_action` 不允许被 `aiops-workflow` 直接绕过平台调用 +- 即使是低风险自动动作，也必须由 `aiops-platform` 发起最终执行请求 + +## 7. 核心对象模型 + +建议 `aiops-tools` 至少围绕以下对象建模： + +| 对象 | 说明 | 关键字段 | +| --- | --- | --- | +| `ToolDefinition` | 工具定义 | name, category, owner, enabled | +| `ToolContract` | 工具入参出参契约 | input_schema, output_schema, error_schema | +| `ToolCall` | 一次工具调用记录 | call_id, tool_name, caller, status | +| `ToolCredential` | 外部系统凭证引用 | credential_id, target_system, scope | +| `ExecutionAction` | 一次执行动作定义 | action_name, risk, executor_type | +| `ExecutionRequest` | 执行请求实例 | request_id, action_name, operator, idem_key | +| `ExecutionResult` | 执行结果 | status, output, error, started_at, finished_at | +| `RollbackPlan` | 回滚入口定义 | rollback_type, rollback_ref, rollback_hint | +| `AuditRecord` | 工具审计记录 | actor, target, operation, result | +| `RateLimitPolicy` | 限流策略 | caller_type, qps, burst | +| `RetryPolicy` | 重试策略 | max_retries, retryable_errors, backoff | + +## 8. MVP 功能需求 + +## 8.1 Query Tools 总体要求 + +### 8.1.1 能力目标 + +查询类工具负责把底层异构系统查询能力标准化暴露给 `aiops-workflow`。 + +### 8.1.2 通用要求 + +所有查询类工具必须支持： + +- 统一请求结构 +- 统一响应结构 +- 超时控制 +- 权限校验 +- 调用审计 +- 错误码规范 +- 调用 trace 关联 + +### 8.1.3 通用响应要求 + +查询工具返回的数据不应该只是一段原始文本，而应至少包含： + +- `status` +- `summary` +- `raw_ref` 或 `query_ref` +- `duration_ms` +- `data` + +## 8.2 `query_metrics` + +### 8.2.1 目标 + +对 Prometheus 等指标系统提供统一查询能力。 + +### 8.2.2 输入建议 + +- `query` +- `start` +- `end` +- `step` +- `env` +- `cluster` + +### 8.2.3 输出建议 + +- 序列数量 +- 点位数量 +- 结果摘要 +- 原始查询引用 + +### 8.2.4 MVP 验收标准 + +1. 能完成基础时序查询。 +2. 能返回结构化摘要。 +3. 超时和空结果可区分。 + +## 8.3 `query_logs` + +### 8.3.1 目标 + +对 Loki / ELK / OpenSearch 等日志系统提供统一查询能力。 + +### 8.3.2 输入建议 + +- `query` +- `start` +- `end` +- `limit` +- `service` +- `env` + +### 8.3.3 输出建议 + +- 命中数量 +- 关键错误模式摘要 +- 样例日志片段 +- 原始查询引用 + +### 8.3.4 MVP 验收标准 + +1. 能按时间窗口查询日志。 +2. 能控制返回数量，避免输出过大。 +3. 能对空结果、权限失败、查询失败做区分。 + +## 8.4 `query_k8s` + +### 8.4.1 目标 + +对 K8s 集群提供资源状态查询能力。 + +### 8.4.2 输入建议 + +- `cluster` +- `namespace` +- `resource_type` +- `resource_name` +- `selector` + +### 8.4.3 输出建议 + +- 资源摘要 +- 当前状态 +- 关键异常信息 +- 事件摘要 + +### 8.4.4 MVP 验收标准 + +1. 可查询 Pod / Deployment / Node 等基础资源。 +2. 返回结果不暴露过量底层细节给上层。 +3. 能稳定提供适合诊断使用的结构化摘要。 + +## 8.5 `query_changes` + +### 8.5.1 目标 + +查询近期变更记录，用于辅助根因分析。 + +### 8.5.2 变更来源建议 + +- CI/CD 发布记录 +- 配置中心变更 +- Git 提交或发布流水线 +- 工单或变更系统 + +### 8.5.3 输出建议 + +- 变更列表 +- 变更时间 +- 变更类型 +- 变更摘要 +- 关联服务 + +### 8.5.4 MVP 验收标准 + +1. 能按时间窗口返回近期变更。 +2. 能按服务或环境过滤。 +3. 返回结构适合 workflow 直接消费。 + +## 8.6 `execute_action` + +### 8.6.1 目标 + +提供统一受控执行网关，对接 Ansible、K8s API、脚本执行器等真实动作入口。 + +### 8.6.2 关键原则 + +- 工具层执行，不代表工具层做决策 +- 工具层接收的是已通过平台策略校验的执行请求 +- 工具层必须校验请求合法性、幂等性、权限和执行条件 + +### 8.6.3 MVP 支持的动作类型建议 + +- 重启 Pod +- 扩容 Deployment +- 回滚 Deployment +- 执行白名单脚本 +- 调用预定义 Ansible Playbook + +### 8.6.4 请求字段建议 + +- `request_id` +- `incident_id` +- `action_name` +- `action_params` +- `risk` +- `approval_token` 或等价审批校验信息 +- `idempotency_key` +- `operator` + +### 8.6.5 输出字段建议 + +- `status` +- `executor_type` +- `execution_id` +- `started_at` +- `finished_at` +- `result_summary` +- `rollback_hint` + +### 8.6.6 MVP 验收标准 + +1. 执行动作必须经过显式请求。 +2. 同一 `idempotency_key` 不重复执行。 +3. 执行结果必须有结构化返回。 +4. 失败时能返回明确原因和回滚入口提示。 + +## 8.7 鉴权与授权 + +### 8.7.1 目标 + +确保不是任何调用方都可以任意使用所有工具。 + +### 8.7.2 必须能力 + +- 调用方身份识别 +- 工具级权限控制 +- 动作级权限控制 +- 环境级权限控制 +- 生产环境额外保护 + +### 8.7.3 原则 + +- `aiops-workflow` 默认只能调查询类工具 +- `aiops-platform` 才能发起执行类请求 +- 高风险执行请求必须有平台侧审批上下文 + +## 8.8 限流与配额控制 + +### 8.8.1 必须能力 + +- 调用方限流 +- 工具级限流 +- 突发流量保护 +- 重查询防护 + +### 8.8.2 设计价值 + +如果没有限流，诊断工作流在告警风暴下可能把底层 Prometheus / Loki / K8s API 一起打挂。 + +## 8.9 超时、重试与熔断 + +### 8.9.1 必须能力 + +- 每个工具可配置超时 +- 可配置重试次数 +- 区分可重试错误和不可重试错误 +- 下游故障时快速失败 + +### 8.9.2 原则 + +- 查询类工具允许有限重试 +- 执行类工具重试要非常谨慎，必须结合幂等键 + +## 8.10 幂等控制 + +### 8.10.1 为什么必须做 + +执行类动作如果没有幂等控制，可能因为重试、网络抖动或平台重复提交导致重复操作生产环境。 + +### 8.10.2 必须能力 + +- `idempotency_key` +- 幂等窗口 +- 重复请求识别 +- 幂等结果返回 + +### 8.10.3 验收标准 + +1. 重复提交同一执行请求不会造成重复执行。 +2. 调用方可以拿到第一次执行结果或明确的幂等命中结果。 + +## 8.11 审计与可追踪性 + +### 8.11.1 必须记录的内容 + +- 谁调用了哪个工具 +- 调用了哪个目标系统 +- 请求参数摘要 +- 执行或查询结果摘要 +- 错误信息 +- 开始时间 / 结束时间 +- trace id / incident id / task id + +### 8.11.2 边界说明 + +`aiops-tools` 记录工具层审计，`aiops-platform` 记录业务主审计。 +两者需要能通过 `incident_id`、`request_id`、`trace_id` 关联。 + +## 8.12 回滚入口 + +### 8.12.1 目标 + +工具层至少要给平台一个明确的“如何回滚”入口，而不是执行后只返回成功或失败。 + +### 8.12.2 MVP 形式 + +- 返回回滚建议 +- 返回回滚命令引用 +- 返回回滚 playbook 引用 + +### 8.12.3 注意事项 + +- 工具层可以提供回滚入口定义 +- 是否自动回滚、何时回滚，仍由平台或策略层决定 + +## 9. 统一接口与契约建议 + +## 9.1 Query 接口建议 + +建议所有查询类工具通过统一模式暴露，例如： + +- `POST /api/v1/tools/query_metrics` +- `POST /api/v1/tools/query_logs` +- `POST /api/v1/tools/query_k8s` +- `POST /api/v1/tools/query_changes` + +统一返回结构建议： + +```json +{ + "request_id": "req-001", + "tool_name": "query_metrics", + "status": "ok", + "summary": "p95 latency 从 220ms 升至 2.1s", + "data": {}, + "duration_ms": 328 +} +``` + +## 9.2 Execute 接口建议 + +建议执行类能力采用统一入口： + +- `POST /api/v1/tools/execute_action` + +统一返回结构建议： + +```json +{ + "request_id": "exec-001", + "execution_id": "run-001", + "status": "accepted", + "executor_type": "k8s", + "result_summary": "deployment/order-service scale requested", + "rollback_hint": "scale down deployment/order-service" +} +``` + +## 9.3 错误码建议 + +建议至少定义以下错误码： + +| code | 含义 | 说明 | +| --- | --- | --- | +| `TOOL_UNAUTHORIZED` | 无权限访问工具 | 权限校验失败 | +| `TOOL_TIMEOUT` | 工具调用超时 | 查询或执行超时 | +| `TOOL_RATE_LIMITED` | 触发限流 | 调用频率过高 | +| `TOOL_DOWNSTREAM_ERROR` | 下游系统异常 | Prometheus/Loki/K8s 等异常 | +| `EXECUTION_NOT_ALLOWED` | 不允许执行 | 平台上下文或风险约束不满足 | +| `IDEMPOTENCY_CONFLICT` | 幂等冲突 | 重复执行请求 | +| `ROLLBACK_UNAVAILABLE` | 无回滚入口 | 动作未提供回滚方案 | + +## 10. 适配层设计要求 + +## 10.1 指标适配层 + +- 适配 Prometheus / VictoriaMetrics 等指标系统 +- 屏蔽底层差异，统一输出结构 + +## 10.2 日志适配层 + +- 适配 Loki / ELK / OpenSearch +- 屏蔽不同查询语言差异 + +## 10.3 K8s 适配层 + +- 适配多集群访问 +- 对资源对象做统一摘要化输出 + +## 10.4 执行器适配层 + +- 适配 K8s API +- 适配 Ansible +- 适配预定义脚本执行器 + +## 10.5 设计原则 + +- 上层不直接接触底层协议细节 +- 工具契约稳定优先于底层实现灵活性 + +## 11. 非功能要求 + +### 11.1 安全性 + +- 凭证统一管理，禁止硬编码 +- 最小权限原则 +- 生产环境与测试环境权限隔离 +- 执行能力与查询能力权限隔离 + +### 11.2 可靠性 + +- 关键工具调用可观测 +- 下游异常时有降级路径 +- 查询失败不应拖垮整体系统 + +### 11.3 可维护性 + +- 新增一个工具适配器不应影响现有契约 +- 配置与代码职责清晰 +- 工具元数据和契约文档化 + +### 11.4 可扩展性 + +- 允许后续增加更多查询工具 +- 允许新增执行器而不破坏统一执行入口 + +## 12. 部署与实现建议 + +### 12.1 当前实现建议 + +结合主架构文档，当前阶段适合将 `aiops-tools` 实现为 Python 服务。 + +适合的原因： + +- 便于与 AI / workflow 生态结合 +- 便于快速对接 Prometheus / K8s / Ansible 等基础设施 +- 便于实现鉴权、重试、超时、幂等等中间件能力 + +### 12.2 当前部署建议 + +- 作为独立服务部署 +- 对外暴露统一 HTTP API +- 凭证和外部系统连接配置独立管理 + +### 12.3 不建议的实现方式 + +- 让 workflow 直接调用底层系统 SDK +- 让平台直接散落调用不同外部系统 +- 查询和执行接口各自为政，没有统一治理 + +## 13. 分阶段实施建议 + +### Phase 1 + +- 打通 `query_metrics` +- 打通 `query_logs` +- 打通 `query_k8s` +- 建立统一 tool contract +- 建立基础审计与超时控制 + +### Phase 2 + +- 打通 `query_changes` +- 打通 `execute_action` +- 建立幂等控制与重试策略 +- 接入基础回滚入口 + +### Phase 3 + +- 增加更多连接器 +- 增加更细粒度限流和权限策略 +- 补齐多环境多集群治理 + +## 14. 推荐的仓库内文档与资产结构 + +如果后续 `aiops-tools` 独立成仓，可参考如下结构： + +```text +tools/ + AIOps_Tools_Requirements.md + contracts/ + adapters/ + executors/ + policies/ + examples/ +``` + +## 15. 结论 + +`aiops-tools` 的本质不是一个简单的“工具箱”，而是整个 AIOps 架构中的安全与协议隔离层。 + +如果 `aiops-platform` 解决的是“事件如何流转”， +`aiops-workflow` 解决的是“诊断如何形成”， +那么 `aiops-tools` 解决的就是： + +- 数据如何安全地查 +- 动作如何安全地做 +- 真实系统如何被统一接入 + +因此，`aiops-tools` 的第一优先级不是堆很多工具，而是先把以下能力做稳： + +- 标准化查询接口 +- 统一执行网关 +- 鉴权 +- 超时 +- 重试 +- 幂等 +- 审计 + +只有这层稳定，平台和 workflow 才能在上层安心演进。