| 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 ./.trae/skills/change-risk-analyst/scripts/change_risk_from_topology.py \
--node "<target>" \
--output markdown
其中 --node 是变更目标。脚本只负责查询出结构化的拓扑数据和受影响的 ECS。
如果用户已经明确给了业务:
python3 ./.trae/skills/change-risk-analyst/scripts/change_risk_from_topology.py \
--business "<business>" \
--node "<target>" \
--output markdown
脚本内部直接读取 topology.json 进行节点匹配和图分析,自动拿到:
- 命中目标和基础信息
- 受影响的下游 ECS
- 关联资源和入口链路
- 文字化的上下游结构描述
3. 阅读指南并由大模型推断风险
核心要求:脚本不会输出任何“风险等级”或“风险结论”。你(大模型)必须:
- 阅读本 skill 目录下的
references/risk_assessment_rules.md。
- 结合用户的原始变更描述(动作)和脚本输出的结构化数据(受影响资源),基于指南中的原则,自主推理出本次变更的风险等级、风险结论和影响边界。
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
- 如果命中不到目标节点,直接说明未命中,并给出建议的补充信息
- 如果只有模糊命中,先输出候选排序,不要强行给风险结论
- 如果用户问的是“当前是不是已经故障”,要提醒这里只做静态风险分析