/byted-volcengine-rootcause-analyzer

name: byted-volcengine-rootcause-analyzer
description: 当监控平台、日志平台、值班对话或变更后异常暴露出某个资源、域名、IP 或业务现象时，围绕告警目标自动展开上下游拓扑，检查同一拓扑内的关联异常并归并根告警、派生告警和噪声告警，输出根因候选、影响范围和结构化诊断摘要。

告警根因定位与归并 Skill

能力定位

这个 Skill 是一个**面向故障场景的编排层**。它不把告警当作一条孤立事件处理，而是把告警、资源拓扑、同时间窗异常和运行时证据拼成一个完整的故障上下文。

它的职责是：

• 从告警文本、现象描述或值班对话中提取实例、域名、IP、产品类型、指标和时间窗
• 围绕目标资源自动展开上下游拓扑，形成当前故障上下文
• 检查同一拓扑内其他资源是否存在关联异常
• 区分根告警、派生告警和噪声告警，避免把一组相关告警分散处理
• 汇总拓扑事实、运行时状态、监控证据和 API 补数结果，给出根因候选排序
• 输出影响范围、优先处理节点、建议修复动作和可升级交接的结构化摘要

这个 Skill 的目标不是“解释某一条告警”，而是把**分散异常收敛成一条业务链路问题**，尽快逼近真正的故障源头。

当前边界

当前版本重点覆盖以下能力：

• 告警解析
• 资源识别
• 拓扑展开
• 同拓扑异常归并
• 根因候选排序
• 结构化故障摘要输出

以下能力可以作为未来扩展输入，但**当前不是必须步骤，也不能假设一定可用**：

• 近期变更
• 历史故障案例
• 知识库经验
• 授权执行预案并验证恢复

一句话区分：

• `byted-volcengine-rootcause-analyzer`：负责把“告警 + 拓扑 + 异常归并 + 证据”串成诊断结论
• 它不是统一告警平台，不是资源管理中心本体，也不是自动执行平台

依赖 Skill 及关系

这个 Skill 依赖以下四个已有 Skill：

1. `byted-volcengine-topology-builder`

职责：

• 采集火山引擎账号资产快照
• 构建 `topology.json`、`topology.md`、图文件等基础拓扑数据

边界：

• 只负责“把资源关系建出来”
• 不负责解释告警，不负责给出根因结论

适合什么时候调用：

• 当前没有覆盖目标资源的拓扑
• 已有拓扑过旧或缺失关键节点
• 需要从实例、监听器、EIP、VPC、安全组等资源补齐链路

2. `byted-volcengine-topology-analyzer`

职责：

• 基于已有拓扑定位目标节点
• 展开直接上下游、入口链路和受影响资源
• 给出静态影响面分析

边界：

• 只消费静态拓扑，不等于实时健康状态
• 不负责直接查询监控时序或 API 详情

适合什么时候调用：

• 已识别出主告警资源或候选资源
• 需要判断“这个资源在整条链路里影响谁、被谁依赖”

3. `byted-volcengine-cloudmonitor`

职责：

• 查询目标资源的监控时序
• 验证异常是否持续、放大或同步传播

边界：

• 只回答“指标怎么变”
• 不能单独替代拓扑归因

适合什么时候调用：

• 需要确认告警是否仍持续
• 需要验证同拓扑内多个资源是否在同时间窗同步异常
• 需要区分瞬时抖动与持续故障

4. `byted-volcengine-api-assistant`

职责：

• 识别产品 `ServiceCode`
• 搜索可用 OpenAPI
• 查询资源详情、配置和映射关系

边界：

• 它是补数能力，不是拓扑分析引擎
• 只在 OpenAPI 能力范围内工作

适合什么时候调用：

• 从告警文本无法直接判断资源类型
• 拓扑里缺少监听器、后端组、实例、转发规则映射
• 需要补充产品配置、绑定关系、健康检查详情

何时触发

当出现以下场景时，应主动触发这个 Skill：

• 监控平台产生单点告警
• 监控平台出现告警风暴，需要判断是否属于同一条链路问题
• 值班人员在会话中提交“某业务不可用”“某域名报错”“某接口超时”等现象
• 变更后短时间内出现可用性或性能异常
• 用户希望知道一组告警里哪条更接近根因、哪些只是派生结果

即使用户没有明确说“拓扑”或“告警归并”，只要问题本质是**围绕一个故障现象收敛上下游异常并定位真正根因**，就应该触发。

输入信息

优先从告警文本、日志摘录或自由描述中提取以下字段：

• 账号
• 告警策略
• 地域中文名
• 地域对应 Region ID
• 告警级别
• 项目
• 告警时间
• 时间窗
• 云产品
• 资源 ID
• 实例 ID
• 监听器 ID
• 域名
• IP
• 当前值
• 指标名称
• 业务现象描述
• 同一会话中出现的多条相关告警

如果文本里没有显式字段，也要继续识别：

• 产品别名
• 资源层级关键词
• 健康检查、连接数、状态码、超时、探活失败等指标语义
• 入口层、转发层、计算层、网络层等上下文词

如果缺少资源 ID，也允许从域名、IP 或现象描述反推候选资源，但最终回答必须显式标记不确定性。

标准执行流程

第 1 步：结构化输入

先把原始输入整理为结构化对象，例如：

{
  "account": "xx",
  "policy_name": "xx",
  "region_name": "华北2（北京）",
  "region_id": "cn-beijing",
  "severity": "严重",
  "project": "mysite",
  "alarm_time": "2026-05-09 17:26:11",
  "time_window": "alarm_time +/- 15m",
  "product": "clb",
  "resource_id": "clb-xxx",
  "instance_id": "",
  "listener_id": "lsn-xxx",
  "domain": "",
  "ip": "",
  "metric_name": "监听器/后端服务器异常个数",
  "current_value": "AVG(xxx)[1m]:1Count",
  "symptom": "",
  "related_alerts": []
}

如果某些字段缺失，要显式标记为“缺失信息”，不要自行脑补。

第 2 步：识别主告警节点

先判断这次故障的主起点更接近哪一层：

• 入口层：`domain`、`eip`、`clb`、`alb`、`listener`
• 转发层：`rule`、`server_group`
• 计算层：`ecs`
• 网络层：`security_group`、`subnet`、`vpc`
• 其他产品层：需要借助 API 进一步确认

判断原则：

• 告警中如果同时出现 `资源 ID`、`实例 ID`、`监听器 ID`，要区分“告警对象”和“潜在根因对象”
• 域名、入口告警通常只是入口层信号，不应直接等同于最终根因
• 如果是负载均衡类告警，必须继续追溯监听器、后端组和实例

第 3 步：获取故障拓扑上下文

围绕主告警节点获取上下游拓扑。优先级如下：

1. 优先使用工作区中已存在且可复用的拓扑数据 2. 如果现有拓扑不覆盖目标资源，调用 `byted-volcengine-topology-builder` 3. 使用 `byted-volcengine-topology-analyzer` 展开目标节点的上下游、入口链路和受影响资源

这一步的目标不是“画图展示”，而是为后续做告警归并建立一个可分析的故障上下文。

第 4 步：检查同拓扑内的关联异常

在已展开的拓扑范围内，检查同一时间窗内其他资源是否也有异常信号。

异常来源可以包括：

• 当前会话中提供的多条告警
• 同一资源链路上的其他监控指标
• 通过 `byted-volcengine-cloudmonitor` 查询到的同步异常
• 通过 API 补数拿到的异常状态字段

如果当前无法直接查询告警平台，则应退化为：

• 分析会话中已有的告警集合
• 分析当前主资源和上下游的实时状态
• 明确说明“当前无法完整拉取同时间窗所有告警”

第 5 步：归并告警并分类

拿到同拓扑异常后，至少要分成三类：

• `root_alert`：更接近链路收敛点，且能解释其他异常传播的告警
• `derived_alert`：由根问题向上游或下游传播形成的派生告警
• `noise_alert`：与当前主链路弱相关、证据不足或无法证明同源的告警

归并原则：

• 优先找多条异常路径最终汇聚的节点或资源层
• 优先找既有拓扑解释力、又有运行时异常证据的节点
• 不把单纯时间接近但链路无关的告警强行归为一组

第 6 步：按需补数和验证

当出现以下情况时，按需使用补充能力：

• 拓扑里有节点但关系不完整：调用 `byted-volcengine-api-assistant`
• 需要确认异常是否仍持续或是否同步放大：调用 `byted-volcengine-cloudmonitor`
• 无法从域名、IP 直接映射到资源：优先使用拓扑和 API 反推

使用原则：

• API 和监控是补证据，不替代拓扑上下文
• 没有证据时不要假装“已经归并完成”
• 归并失败时宁可保守，也不要把噪声告警误判为同根因

第 7 步：形成根因候选排序

综合以下证据后，再给出根因候选：

• 告警原文事实
• 拓扑中的位置与上下游关系
• 同拓扑内异常的聚集情况
• API 补数得到的资源详情和绑定关系
• 监控时序中的同步异常或持续异常

最终至少要回答：

• 哪个资源是本次故障分析的主节点
• 哪些告警被归并到同一问题
• 哪个节点最可能是根因，哪个只是传播结果
• 当前影响范围是什么
• 应优先处理哪个节点

根因判断原则

1. 不把最早出现的告警直接等同于根因

最早触发的告警不一定最接近故障源头，可能只是更敏感的入口信号。

2. 优先找链路收敛点

如果多条异常路径最终都汇聚到同一个资源、同一层组件或同一个资源组，应优先把它列为高置信候选根因。

3. 区分“原因”和“传播结果”

例如：

• 上游域名报错可能只是结果
• 入口负载均衡健康检查异常可能只是中间信号
• 某个后端实例、服务器组或网络边界异常更可能接近真正根因

4. 告警归并必须有证据

至少满足以下一项，才能高置信归并：

• 拓扑上存在明确依赖关系
• 同一时间窗出现同步异常
• API 或监控状态能互相印证

5. 根因候选必须带置信度

建议按以下级别表达：

• `confirmed`：有明确链路和运行时证据支撑
• `high`：拓扑与监控高度一致，但仍缺少少量细节
• `medium`：链路可达，但证据不够完整
• `low`：只能定位到某一层，无法确认唯一节点

回答结构

输出时优先使用以下结构：

结论：
- 当前最可能的根因候选是 ...
- 置信度是 ...
- 当前优先处理节点是 ...

告警归并结果：
- 主告警: ...
- 已归并的派生告警: ...
- 识别为噪声的告警: ...

拓扑与影响：
- 故障入口: ...
- 中间链路: ...
- 下游关键资源: ...
- 当前影响范围: ...

根因候选排序：
- 候选 1: ... | 证据: ...
- 候选 2: ... | 证据: ...
- 候选 3: ... | 证据: ...

事实 / 推断 / 待确认：
- 已确认事实: ...
- 高置信推断: ...
- 待确认项: ...

建议动作：
- 先处理 ...
- 再验证 ...
- 如需升级，交接摘要如下 ...

预期产出

使用这个 Skill 时，最终输出应尽量覆盖以下内容：

• 根因候选排序与证据链
• 告警归并结果与影响拓扑视图
• 当前故障影响范围、优先处理节点和建议修复动作
• 可用于升级交接的结构化诊断摘要

结构化诊断摘要要求

如果用户需要快速升级或交接，至少应给出：

• 故障标题
• 主要受影响业务或入口
• 当前主根因候选
• 已归并告警数量
• 当前影响范围
• 优先处理节点
• 已验证证据
• 待确认项
• 下一步建议动作

排查建议生成规则

排查建议至少覆盖三类内容：

1. 立即核查项

• 当前主根因候选是否仍持续异常
• 同拓扑内是否仍有更多资源同步异常
• 优先处理节点是否已经出现健康检查失败、状态异常或容量下降

2. 链路核查项

• 上游入口是否仍可达
• 中间转发、监听器、后端组或实例绑定关系是否异常
• 是否存在链路单点或冗余失效

3. 止血与交接项

• 是否可以绕过当前疑似故障节点
• 是否可以临时摘除异常节点或回切备用入口
• 如需升级，先交接主根因候选、影响范围和已验证证据

失败回退策略

情况 1：无法识别产品或资源

处理方式：

• 先从域名、IP、资源 ID、实例 ID 中反推候选资源
• 再调用 `byted-volcengine-api-assistant` 补产品与接口信息
• 若仍无法确认，明确标注“当前无法唯一定位资源类型”

情况 2：拓扑缺失或命中失败

处理方式：

• 调用 `byted-volcengine-topology-builder` 重新构建
• 若仍无命中，说明当前拓扑未覆盖目标资源
• 不要硬编上下游，直接说明链路证据不足

情况 3：无法完整拉取同时间窗告警

处理方式：

• 回退到会话中已有告警和当前实时证据做局部归并
• 明确说明“当前无法完整获取同时间窗所有告警，归并结果可能不完整”

情况 4：监控或 API 补数失败

处理方式：

• 回退