532 lines
13 KiB
Markdown
532 lines
13 KiB
Markdown
# AIOps Workflow Requirements
|
|
|
|
## 1. 文档目标
|
|
|
|
本文档用于定义 `aiops-workflow` 项目的职责边界、MVP 需求范围、核心对象模型、输入输出契约与实施优先级。
|
|
|
|
这份文档基于主架构文档中对三层项目域的划分，重点回答以下问题：
|
|
|
|
1. `aiops-workflow` 在整体 AIOps 架构中的定位是什么。
|
|
2. `aiops-workflow` 在 MVP 阶段必须交付哪些能力。
|
|
3. 它和 `aiops-platform`、`aiops-tools` 的边界如何清晰切开。
|
|
4. 如何保证 workflow 输出稳定、可解释、可评测、可演进。
|
|
|
|
本文档默认面向 `workflow-first` 路线，而不是 multi-agent 优先路线。
|
|
|
|
## 2. 项目定位
|
|
|
|
### 2.1 核心定义
|
|
|
|
`aiops-workflow` 负责“如何做诊断、如何组织证据、如何输出结构化 RCA 与建议”。
|
|
|
|
它不是平台主控层，也不是底层工具适配层，而是位于两者之间的智能工作流中枢。
|
|
|
|
其核心职责是：
|
|
|
|
- 接收 `aiops-platform` 提供的 Incident 上下文。
|
|
- 按既定 workflow 执行诊断、检索与推理。
|
|
- 调用 `aiops-tools` 暴露的查询类工具补齐证据。
|
|
- 输出平台可直接消费的结构化结果。
|
|
|
|
### 2.2 不负责的事情
|
|
|
|
`aiops-workflow` 明确不负责：
|
|
|
|
- 持有 `Incident` 主状态
|
|
- 审批流转
|
|
- 执行动作控制
|
|
- 页面展示
|
|
- 直接对生产环境进行写操作
|
|
- 直接耦合底层监控系统协议细节
|
|
|
|
### 2.3 核心设计原则
|
|
|
|
- Workflow 优先于 multi-agent
|
|
- 查询能力可以直接调用 tools
|
|
- 执行能力必须回到平台决策
|
|
- 输出必须结构化，不能只返回自由文本
|
|
- 所有 workflow 都要可版本化、可回放、可评测
|
|
|
|
## 3. 目标用户与调用方
|
|
|
|
### 3.1 直接调用方
|
|
|
|
- `aiops-platform`
|
|
- 后续可能的复盘任务调度器
|
|
- 评测回归任务调度器
|
|
|
|
### 3.2 主要使用者
|
|
|
|
- AI 工程师：维护 workflow、Prompt、Schema、评测集
|
|
- 平台后端工程师：对接调用契约与任务状态
|
|
- SRE / 运维专家：审核知识库、诊断逻辑、建议动作质量
|
|
|
|
## 4. MVP 成功标准
|
|
|
|
MVP 阶段，`aiops-workflow` 至少应达到以下结果：
|
|
|
|
1. 可稳定执行 `incident_diagnosis` 工作流。
|
|
2. 可调用 2-3 个查询类工具补齐证据。
|
|
3. 可返回统一格式的 `RCA Result` 与 `actions`。
|
|
4. 输出结果可被平台直接落库和展示。
|
|
5. 具备基础评测回归能力，避免工作流更新后质量失控。
|
|
|
|
建议的 MVP 指标：
|
|
|
|
| 指标 | 说明 | MVP 目标 |
|
|
| --- | --- | --- |
|
|
| Workflow 成功率 | 工作流执行完成率 | 高于 95% |
|
|
| Schema 合法率 | 输出满足平台 schema 的比例 | 高于 99% |
|
|
| 诊断 P95 时延 | 从触发到输出结果的时延 | 小于 60 秒 |
|
|
| 引证覆盖率 | 结果中包含有效 evidence 的比例 | 高于 90% |
|
|
| RCA Top1 准确率 | 在评测集上的首选结论命中率 | 持续追踪 |
|
|
|
|
## 5. 范围边界
|
|
|
|
### 5.1 MVP 必须范围
|
|
|
|
- Workflow 注册与版本管理
|
|
- `incident_diagnosis` 工作流
|
|
- `action_planning` 工作流
|
|
- 查询类工具编排
|
|
- RAG 检索策略基础能力
|
|
- 结构化输出 schema
|
|
- 任务状态查询
|
|
- 评测样例与回归检查
|
|
- 失败与降级策略
|
|
|
|
### 5.2 MVP 可选增强
|
|
|
|
- `postmortem_summary` 工作流
|
|
- Prompt 模板变量管理界面
|
|
- 多知识域检索重排
|
|
- 更细粒度的步骤级 tracing
|
|
|
|
### 5.3 明确不在 MVP
|
|
|
|
- Multi-agent 编排框架
|
|
- 执行类动作直连生产系统
|
|
- 复杂可视化管理后台
|
|
- 全自动根因图谱推理平台
|
|
- 训练/微调平台
|
|
|
|
## 6. 核心对象模型
|
|
|
|
建议 `aiops-workflow` 先围绕以下对象建模：
|
|
|
|
| 对象 | 说明 | 关键字段 |
|
|
| --- | --- | --- |
|
|
| `WorkflowDefinition` | 工作流定义 | id, name, purpose, owner |
|
|
| `WorkflowVersion` | 工作流版本 | version, status, schema_ref, prompt_refs |
|
|
| `SkillDefinition` | 可复用能力单元 | id, workflow_ref, input_schema, output_schema |
|
|
| `PromptAsset` | Prompt 模板资产 | id, version, variables, content |
|
|
| `KnowledgeCollection` | 知识集合 | id, source_type, tags, index_ref |
|
|
| `RetrievalPolicy` | 检索策略 | top_k, filters, rerank_policy |
|
|
| `ToolContract` | 工具调用契约 | tool_name, input_schema, output_schema |
|
|
| `WorkflowRun` | 一次工作流执行实例 | run_id, workflow_id, status, started_at |
|
|
| `WorkflowStepRun` | 步骤运行实例 | step_name, tool_name, status, duration_ms |
|
|
| `EvaluationCase` | 评测样例 | case_id, input, expected_output |
|
|
| `SchemaContract` | 输出契约 | fields, required, enum_constraints |
|
|
|
|
## 7. MVP 功能需求
|
|
|
|
## 7.1 Workflow Registry
|
|
|
|
### 7.1.1 能力目标
|
|
|
|
系统应能管理工作流定义与版本，而不是把 workflow 当成散乱脚本。
|
|
|
|
### 7.1.2 必须能力
|
|
|
|
- 注册 workflow
|
|
- 维护 workflow 名称、用途、负责人
|
|
- 管理版本状态
|
|
- draft
|
|
- active
|
|
- deprecated
|
|
- 记录 workflow 依赖的 Prompt、Schema、Knowledge、Tools
|
|
|
|
### 7.1.3 验收标准
|
|
|
|
1. 可查看某个 workflow 的当前生效版本。
|
|
2. 更新 workflow 时可保留历史版本。
|
|
3. 平台调用时可明确命中哪个版本。
|
|
|
|
## 7.2 `incident_diagnosis` 工作流
|
|
|
|
### 7.2.1 目标
|
|
|
|
这是 MVP 最核心的工作流，用于根据 Incident 上下文给出结构化诊断结果。
|
|
|
|
### 7.2.2 输入要求
|
|
|
|
最小输入建议包含：
|
|
|
|
- `incident_id`
|
|
- `title`
|
|
- `severity`
|
|
- `service`
|
|
- `env`
|
|
- `fingerprint`
|
|
- `time_window`
|
|
- `recent_changes`
|
|
- `related_incidents`
|
|
- `topology`
|
|
|
|
### 7.2.3 执行步骤
|
|
|
|
建议固定为以下链路：
|
|
|
|
1. 解析 Incident 上下文
|
|
2. 决定需要调用的查询工具
|
|
3. 调用 metrics / logs / k8s / changes 查询
|
|
4. 调用 RAG 补充 SOP 和历史案例
|
|
5. 汇总证据并生成候选结论
|
|
6. 输出结构化 RCA
|
|
|
|
### 7.2.4 输出要求
|
|
|
|
必须返回：
|
|
|
|
- `summary`
|
|
- `rca.conclusion`
|
|
- `rca.confidence`
|
|
- `rca.impact_scope`
|
|
- `rca.evidence[]`
|
|
- `actions[]`
|
|
|
|
### 7.2.5 验收标准
|
|
|
|
1. 输出必须满足平台约定 schema。
|
|
2. 结果中至少包含一条 evidence。
|
|
3. 低置信度时不能输出高风险自动执行模式。
|
|
|
|
## 7.3 `action_planning` 工作流
|
|
|
|
### 7.3.1 目标
|
|
|
|
根据已形成的 RCA 与上下文，给出可执行但受控的动作建议。
|
|
|
|
### 7.3.2 必须能力
|
|
|
|
- 根据 RCA 生成动作建议列表
|
|
- 为每个动作给出风险等级
|
|
- 为每个动作给出推荐模式
|
|
- `auto`
|
|
- `approval`
|
|
- `suggest_only`
|
|
- 提供回滚建议
|
|
|
|
### 7.3.3 约束
|
|
|
|
- 仅输出建议，不直接执行
|
|
- 不允许 workflow 自行持有执行凭证
|
|
- `confidence` 低于阈值时自动降级
|
|
|
|
### 7.3.4 验收标准
|
|
|
|
1. 每个动作都带 `risk` 和 `mode`。
|
|
2. 中高风险动作默认不能为 `auto`。
|
|
3. 建议动作可以被平台直接渲染展示。
|
|
|
|
## 7.4 `postmortem_summary` 工作流
|
|
|
|
### 7.4.1 目标
|
|
|
|
该工作流建议作为 P1 能力，用于在 Incident 关闭后生成复盘初稿。
|
|
|
|
### 7.4.2 建议输出
|
|
|
|
- Incident summary
|
|
- 关键时间点摘要
|
|
- 主要证据
|
|
- 初步改进建议
|
|
- 待人工确认的问题清单
|
|
|
|
### 7.4.3 MVP 处理方式
|
|
|
|
MVP 可先保留设计，不强制交付。
|
|
|
|
## 7.5 Prompt 资产管理
|
|
|
|
### 7.5.1 必须能力
|
|
|
|
- Prompt 版本化
|
|
- Prompt 与 workflow 绑定
|
|
- 变量占位支持
|
|
- 记录 Prompt 更新时间和负责人
|
|
|
|
### 7.5.2 设计要求
|
|
|
|
- Prompt 不应散落在代码或平台表单中不可追踪地修改
|
|
- Prompt 变更必须可回溯，并可在评测中验证
|
|
|
|
## 7.6 RAG 管理能力
|
|
|
|
### 7.6.1 范围
|
|
|
|
`aiops-workflow` 需要管理“如何检索”，不一定亲自实现底层向量数据库服务。
|
|
|
|
### 7.6.2 MVP 必须能力
|
|
|
|
- 管理知识集合引用
|
|
- 定义检索过滤条件
|
|
- 定义召回数量 `top_k`
|
|
- 定义是否进行 rerank
|
|
- 返回引用证据
|
|
|
|
### 7.6.3 知识来源建议
|
|
|
|
- SOP 文档
|
|
- 历史 Incident / Postmortem
|
|
- 变更处理手册
|
|
- 常见故障 FAQ
|
|
|
|
### 7.6.4 验收标准
|
|
|
|
1. workflow 输出中能引用知识来源。
|
|
2. 检索异常时可降级，不致使整体任务崩溃。
|
|
|
|
## 7.7 Tools 编排能力
|
|
|
|
### 7.7.1 必须支持的查询类工具
|
|
|
|
- `query_metrics`
|
|
- `query_logs`
|
|
- `query_k8s`
|
|
- `query_changes`
|
|
|
|
### 7.7.2 调用原则
|
|
|
|
- workflow 只调用标准化工具契约
|
|
- 不直接关心 Prometheus / Loki / K8s 原生协议差异
|
|
- 工具异常要回传为结构化错误
|
|
|
|
### 7.7.3 明确禁止
|
|
|
|
- 直接调用生产执行接口
|
|
- 绕过平台审批去执行变更
|
|
- 将 tool 返回的自由文本直接当最终结论
|
|
|
|
### 7.7.4 验收标准
|
|
|
|
1. tools 调用记录可关联到 workflow run。
|
|
2. tool 错误会降低置信度并触发降级逻辑。
|
|
|
|
## 7.8 输出 Schema 契约
|
|
|
|
### 7.8.1 必须能力
|
|
|
|
- 明确定义 output schema
|
|
- 校验 required 字段
|
|
- 校验枚举字段
|
|
- 拒绝不合法输出进入平台主链路
|
|
|
|
### 7.8.2 核心字段建议
|
|
|
|
```json
|
|
{
|
|
"summary": "数据库连接池耗尽导致 API 延迟升高",
|
|
"rca": {
|
|
"conclusion": "连接池配置与突发流量不匹配",
|
|
"confidence": 0.86,
|
|
"impact_scope": ["api-gateway", "order-service"],
|
|
"evidence": [
|
|
{"type": "metric", "ref": "promql://latency_p95"},
|
|
{"type": "log", "ref": "loki://timeout_errors"}
|
|
]
|
|
},
|
|
"actions": [
|
|
{
|
|
"name": "临时扩容 order-service",
|
|
"risk": "low",
|
|
"mode": "auto",
|
|
"rollback": "scale down deployment/order-service"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 7.8.3 验收标准
|
|
|
|
1. schema 校验失败时返回明确错误码。
|
|
2. 平台侧不需要解析自由文本才能使用结果。
|
|
|
|
## 7.9 运行态与任务管理
|
|
|
|
### 7.9.1 必须能力
|
|
|
|
- 异步任务运行
|
|
- 任务状态查询
|
|
- 步骤级状态展示
|
|
- 超时控制
|
|
- 取消任务
|
|
|
|
### 7.9.2 任务状态
|
|
|
|
- `queued`
|
|
- `running`
|
|
- `succeeded`
|
|
- `failed`
|
|
- `timeout`
|
|
|
|
### 7.9.3 验收标准
|
|
|
|
1. 平台可以查询任务当前状态。
|
|
2. 失败任务能返回失败原因。
|
|
3. 超时任务进入明确降级路径。
|
|
|
|
## 7.10 评测与回归能力
|
|
|
|
### 7.10.1 必须能力
|
|
|
|
- 保存评测样例
|
|
- 定义期望输出或期望结论
|
|
- workflow 更新后可批量回归
|
|
- 对比关键指标变化
|
|
|
|
### 7.10.2 核心评测维度
|
|
|
|
- RCA 是否正确
|
|
- evidence 是否充分
|
|
- schema 是否合法
|
|
- 动作建议是否越权
|
|
- 置信度是否异常偏高
|
|
|
|
### 7.10.3 验收标准
|
|
|
|
1. 每次重要 workflow 变更前后都能跑回归集。
|
|
2. 回归结果可沉淀为版本发布依据。
|
|
|
|
## 7.11 可观测性与审计
|
|
|
|
### 7.11.1 必须记录的信息
|
|
|
|
- workflow 名称与版本
|
|
- run_id
|
|
- 输入摘要
|
|
- tools 调用记录
|
|
- token / cost 使用量
|
|
- 执行耗时
|
|
- 输出摘要
|
|
- 错误信息
|
|
|
|
### 7.11.2 边界说明
|
|
|
|
`aiops-workflow` 可以记录 workflow 运行审计，但 Incident 主审计仍由 `aiops-platform` 持有。
|
|
|
|
## 7.12 失败与降级策略
|
|
|
|
### 7.12.1 必须实现
|
|
|
|
- LLM 超时降级
|
|
- tool 不可用降级
|
|
- 检索失败降级
|
|
- schema 不合法降级
|
|
|
|
### 7.12.2 建议行为
|
|
|
|
- 返回部分结果 + 低置信度标记
|
|
- 阻断自动动作建议
|
|
- 明确提示人工接管
|
|
|
|
### 7.12.3 错误码建议
|
|
|
|
- `AI_TIMEOUT`
|
|
- `TOOL_UNAVAILABLE`
|
|
- `SCHEMA_INVALID`
|
|
- `RAG_UNAVAILABLE`
|
|
- `WORKFLOW_FAILED`
|
|
|
|
## 7.13 安全要求
|
|
|
|
### 7.13.1 必须约束
|
|
|
|
- 不保存生产执行凭证
|
|
- 不直接调用写操作工具
|
|
- 不暴露敏感原始凭证到 Prompt
|
|
- 对输入上下文中的敏感字段进行最小化传递
|
|
|
|
### 7.13.2 合规要求
|
|
|
|
- workflow 运行日志可追踪
|
|
- Prompt 与知识来源可审计
|
|
- 结果生成过程可解释
|
|
|
|
## 8. 与平台的接口要求
|
|
|
|
### 8.1 诊断触发接口
|
|
|
|
- 平台触发 `incident_diagnosis`
|
|
- workflow 返回 `task_id`
|
|
- 平台异步查询结果
|
|
|
|
### 8.2 结果接口要求
|
|
|
|
成功结果必须包含：
|
|
|
|
- `task_id`
|
|
- `incident_id`
|
|
- `status`
|
|
- `summary`
|
|
- `rca`
|
|
- `actions`
|
|
|
|
### 8.3 会话追问能力
|
|
|
|
建议预留人工追问接口，用于平台详情页的补充诊断，但不应影响主 workflow 结果的结构化输出约束。
|
|
|
|
## 9. 推荐的仓库内文档与资产结构
|
|
|
|
如果后续 `aiops-workflow` 独立成仓，可参考如下结构：
|
|
|
|
```text
|
|
workflow/
|
|
AIOps_Workflow_Requirements.md
|
|
workflows/
|
|
incident_diagnosis/
|
|
action_planning/
|
|
postmortem_summary/
|
|
prompts/
|
|
schemas/
|
|
evals/
|
|
knowledge/
|
|
```
|
|
|
|
## 10. 分阶段实施建议
|
|
|
|
### Phase 1
|
|
|
|
- 打通 `incident_diagnosis`
|
|
- 接入 `query_metrics`、`query_logs`、`query_k8s`
|
|
- 固化结构化 RCA schema
|
|
|
|
### Phase 2
|
|
|
|
- 增加 `action_planning`
|
|
- 完善 RAG 引用质量
|
|
- 建立评测回归集
|
|
|
|
### Phase 3
|
|
|
|
- 增加 `postmortem_summary`
|
|
- 引入更细粒度版本治理
|
|
- 评估局部 agent 化是否有必要
|
|
|
|
## 11. 结论
|
|
|
|
`aiops-workflow` 在整个架构中的价值，不是“单独做一个 AI 服务”，
|
|
而是把诊断能力沉淀成稳定、可复用、可评测的 workflow 资产。
|
|
|
|
如果 `aiops-platform` 解决的是“事件怎么流转”，
|
|
`aiops-tools` 解决的是“数据怎么查、动作怎么控”，
|
|
那么 `aiops-workflow` 解决的就是：
|
|
|
|
- 证据如何组织
|
|
- 诊断如何形成
|
|
- 结果如何结构化输出
|
|
|
|
因此它的第一优先级不是做复杂 agent 协作，
|
|
而是先把 `incident_diagnosis -> evidence -> RCA -> actions`
|
|
这条链路做稳定、做可审计、做可回归。
|