/byted-volcengine-topology-change-impact

name: byted-volcengine-topology-change-impact
description: 面向代码变更、配置变更、扩容缩容、网络策略调整、入口切换等场景做变更风险分析。只要用户在问“这个变更风险有多大”“这个变更会影响什么”“上下游会波及哪些服务/资源”之类的问题，就应该使用这个 skill；即使用户只给了自然语言变更说明，也要主动尝试结合 topology.json 推断影响范围，并输出风险结论与文字化的上下游影响描述。

变更风险分析 Skill

能力定位

这个 Skill 负责把“变更描述”转成一份可执行的静态风险分析结果。

• 输入通常是自然语言变更单，也可以是简短的代码/配置变更说明
• 分析基础是已有的 `topology.json`，不是运行时监控或实时健康状态
• 关注三类结果：风险等级、影响范围、上下游影响描述
• 第一版优先覆盖“服务/组件”和“云资源”两类对象

这个 Skill 不直接构建拓扑；如果当前工作区还没有 `business_topologies/<business>/topology.json`，应先使用 `topology-graph-builder` 生成底层数据。

**依赖**：本 Skill 只需要 `topology-graph-builder` 生成的 `topology.json` 作为数据输入。同时依赖 `references/risk_assessment_rules.md` 中的指南进行风险推断。

输入前提

默认在当前工作区寻找：

business_topologies/
  <business>/
    topology.json
    topology.md

如果工作区中存在 `.trae/business_topologies/`，也可以直接复用。

静态风险分析的前提是：用户至少提供下面两类信息中的大部分。

• 变更动作：例如“修改配置”“开放 80 端口”“把副本数从 4 缩到 2”“切换入口 CLB”
• 变更对象：例如服务名、组件名、ECS、CLB、EIP、安全组、子网、VPC

如果用户只说“帮我评估这个变更”，但没有说明目标对象，要先追问。

标准流程

1. 提炼变更卡片

先把用户输入整理成一张简化的变更卡片：

• `change_type`：代码变更 / 配置变更 / 扩容 / 缩容 / 网络策略 / 入口切换 / 其他
• `target`：目标服务、组件或云资源
• `action`：新增 / 删除 / 修改 / 替换 / 放开 / 收紧 / 扩 / 缩
• `scope`：如果用户给了业务、环境、地域，要一并带上
• `assumption`：缺失信息要显式标记为假设

如果用户给的是代码变更或配置变更，但没有直接出现资源 ID，要先抽取最可能的服务名、组件名、应用名、网关名、配置项名或资源关键词，再去拓扑里做候选匹配。

2. 优先用脚本做结构化分析

不要直接肉眼扫 `topology.json`。优先执行当前 Skill 自带的脚本：

python3 ./skills/byted-volcengine-topology-change-impact/scripts/change_risk_from_topology.py \
  --node "<target>" \
  --output markdown

其中 `--node` 是变更目标。脚本只负责查询出结构化的拓扑数据和受影响的 ECS。

如果用户已经明确给了业务：

python3 ./skills/byted-volcengine-topology-change-impact/scripts/change_risk_from_topology.py \
  --business "<business>" \
  --node "<target>" \
  --output markdown

脚本内部直接读取 `topology.json` 进行节点匹配和图分析，自动拿到：

• 命中目标和基础信息
• 受影响的下游 ECS
• 关联资源和入口链路
• 文字化的上下游结构描述

3. 阅读指南并由大模型推断风险

**核心要求**：脚本不会输出任何“风险等级”或“风险结论”。你（大模型）必须： 1. 阅读本 skill 目录下的 `references/risk_assessment_rules.md`。 2. 结合用户的原始变更描述（动作）和脚本输出的结构化数据（受影响资源），基于指南中的原则，**自主推理出本次变更的风险等级、风险结论和影响边界**。

4. 多候选时先控风险

如果返回多个候选：

• `id:exact`、`public_ip:exact` 这类高置信命中，可以以第一候选为主继续分析
• 如果只是 `name:fuzzy`、`metadata:fuzzy`，先把候选列表给用户确认
• 如果服务名和资源名混在一起，要明确说明“当前是基于拓扑字段和元数据做静态匹配”

不要在低置信命中下直接下结论。

回答原则

1. 先结论，再证据

回答至少覆盖下面几块：

• 变更对象命中结果
• 风险等级、风险结论和核心原因
• 直接影响对象
• 上游入口链路
• 下游承载或关联资源
• 文字化的上下游影响描述

2. 区分确定影响与潜在影响

用下面三层口径组织：

• `直接影响`：目标节点 1 跳关联、或可明确推断受影响的 ECS / 入口链路
• `潜在影响`：同局部拓扑中 2 跳内可达，但无法静态确认一定受影响
• `待确认项`：缺少业务边界、环境信息或运行时数据的部分

3. 不虚构服务名

如果拓扑里只能确认到基础设施资源，就老实写：

• 当前只能定位到 `EIP/CLB/ECS/安全组/子网/VPC`
• 未发现明确的应用名或服务字段
• 建议用户补充服务映射关系

4. 描述要服务于决策

输出文字描述时：

• 必须明确写出变更目标节点
• 要尽量把“上游入口 -> 中间转发 -> 受影响 ECS”的链路顺序说清楚
• 如果目标本身不是入口资源，要额外说明它与受影响节点之间的关系
• 节点表述优先用 `type:id`，必要时再补 `name`

5. 风险结论必须参考指南

必须严格按照 `references/risk_assessment_rules.md` 中定义的标准来输出 `critical / high / medium / low`，并把级别翻译成风险判断（包含风险结论、影响边界、置信说明）。

6. 不同变更类型的解释口径

拓扑并不能直接告诉你"哪一行代码会调用谁"，所以需要用下面的口径来解释：

• 如果用户给的是代码变更：把它理解为"该服务或组件的行为变化"，重点看该节点所在的入口链路、依赖链路和承载节点
• 如果用户给的是配置变更：把它理解为"路由、连接、访问控制、实例规模或入口策略变化"
• 如果用户给的是扩容缩容：优先分析流量入口、后端承载节点和冗余度变化

结论里要明确写出：这是"基于静态拓扑的影响推断"，不是运行时调用链。

推荐输出结构

优先使用这个模板：

结论：
- 变更对象：...
- 风险等级：critical / high / medium / low
- 风险结论：...
- 核心判断：...
- 影响边界：...
- 置信说明：...

影响范围：
- 直接影响：...
- 潜在影响：...
- 待确认项：...

上下游影响描述：
- 上游入口链路：...
- 中间转发/依赖层：...
- 受影响承载节点：...
- 与目标直接关联的资源：...

判断说明：
- 本次分析基于静态 topology.json 推断
- 不代表运行时调用链或实时健康状态

示例场景

示例 1

用户：

把 payment-api 这个服务的副本数从 4 缩到 2，帮我分析影响面，并说明它的上下游影响链路。

回答重点：

• 先尝试用 `payment-api` 作为节点关键词命中拓扑
• 如果命中的是 CLB / ECS / server_group，也可以继续分析
• 输出缩容风险、风险结论、流量承载变化和入口链路
• 给出文字化的上下游影响描述

示例 2

用户：

安全组 sg-xxx 要开放 443 端口，这个变更会波及哪些上下游资源？

回答重点：

• 命中安全组
• 找到受影响 ECS
• 回溯入口链路
• 输出风险等级、风险结论、验证项、回滚建议和文字化影响描述

示例 3

用户：

我要把公网入口从老 CLB 切到新 CLB，先帮我做一次变更风险分析。

回答重点：

• 抽取“入口切换”动作
• 分析 CLB 背后的后端服务器组和 ECS
• 强调健康检查、灰度验证、回切预案和执行窗口建议

兜底规则

• 如果当前没有 `topology.json`，明确提示先运行 `topology-graph-builder`
• 如果命中不到目标节点，直接说明未命中，并给出建议的补充信息
• 如果只有模糊命中，先输出候选排序，不要强行给风险结论
• 如果用户问的是“当前是不是已经故障”，要提醒这里只做静态风险分析