# 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`
这条链路做稳定、做可审计、做可回归。