# Byted Volcengine Topology Change Impact

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

- Skill: `bytedance/byted-volcengine-topology-change-impact` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bytedance/byted-volcengine-topology-change-impact`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bytedance/byted-volcengine-topology-change-impact/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bytedance (https://skillmd.com/u/bytedance)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/bytedance/byted-volcengine-topology-change-impact

---


# 变更风险分析 Skill

## 能力定位

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

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

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

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

## 输入前提

默认在当前工作区寻找：

```text
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 自带的脚本：

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

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

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

```bash
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. 不同变更类型的解释口径

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

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

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

## 推荐输出结构

优先使用这个模板：

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

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

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

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

## 示例场景

### 示例 1

用户：

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

回答重点：

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

### 示例 2

用户：

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

回答重点：

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

### 示例 3

用户：

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

回答重点：

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

## 兜底规则

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