| 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 步：获取故障拓扑上下文
围绕主告警节点获取上下游拓扑。优先级如下：
- 优先使用工作区中已存在且可复用的拓扑数据
- 如果现有拓扑不覆盖目标资源，调用
byted-volcengine-topology-builder
- 使用
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 补数失败
处理方式：
- 回退到已有拓扑和原始告警文本做保守判断
- 明确说明缺失的是哪类动态证据
- 下调根因候选的置信度
不适用场景
以下场景不要把这个 Skill 当成完整解决方案：
- 用户只想单独查一个监控指标
- 用户只想查询某个产品支持哪些 OpenAPI
- 用户只想构图，不关心告警归并和根因定位
- 缺少账号权限，导致拓扑、监控、API 都无法查询
- 用户明确要求执行预案，但当前未进入授权模式且没有自动执行能力
示例场景
监控平台连续产生多条告警：
- 域名 5xx 升高
- CLB 监听器后端异常个数 > 0
- 单台 ECS 探活失败
值班人员在群里补充：
- mysite 首页访问报错
- 发生时间与告警时间一致
建议处理顺序：
- 先提取域名、入口资源、实例 ID、监听器 ID 和时间窗
- 围绕主资源展开上下游拓扑
- 检查同拓扑内是否存在同步异常
- 区分根告警、派生告警和噪声告警
- 对最可能的根因候选排序
- 输出影响范围、优先处理节点和结构化诊断摘要
最终回答约束
使用这个 Skill 时，最终回答必须遵守以下约束：
- 先给结论，再给证据
- 明确区分“事实 / 推断 / 待确认”
- 不虚构业务名、域名、服务名
- 不把静态拓扑推断说成实时事实
- 不把时间接近但链路无关的告警强行归并
- 如果归并范围不完整，要明确承认边界
