byted-volcengine-topology-analyzer

拓扑影响分析 Skill

能力定位

这个 Skill 不是负责构建底层数据，而是消费已有拓扑数据，回答与影响面、归属关系、上下游链路和变更波及范围相关的问题。

• 定位目标节点，例如 sg-xxx、eip-xxx、clb-xxx、i-xxx、IP、资源名
• 基于结构化拓扑推断直接关联资源、受影响 ECS 和入口链路
• 在用户给出变更描述时，生成基于静态拓扑的风险摘要和校验建议
• 在多候选或多业务场景下，先给出候选排序，再决定是否需要用户确认

输入前提

这个 Skill 默认消费由基础资产/拓扑构建流程沉淀出来的业务拓扑数据。

• 默认查找目录：
  • 当前工作空间下的 business_topologies/
• 目录结构约定： ··· business_topologies/ / topology.json topology.md

- 结构化拓扑数据：`topology.json`
- 人工可读拓扑摘要：`topology.md`
- 当前图关系语义：
  - `attached_to`：A 绑定到 B
  - `has`：A 拥有 B
  - `contains`：A 包含 B
  - `belongs_to`：A 归属 B

如果用户没有显式指定 `--root`，脚本会优先在这两个默认目录里自动发现业务拓扑数据。

如果用户在问“实时状态”或“当前是否健康”，要明确提醒：这里回答的是基于静态拓扑数据的推断，不是运行时状态。

## 标准流程

### 1. 先提取查询要素

优先识别这些信息：

- 节点标识：资源 ID、IP、名称、关键词
- 业务范围：用户是否已经给出明确业务
- 问题类型：影响面、归属关系、上下游链路、入口出口、直接关联
- 变更动作：例如放开端口、删除规则、切换入口、修改子网

如果用户已经给了业务名，就在查询时带上 `--business`，减少歧义。

### 2. 先跑脚本拿结构化结果

优先使用脚本，不要直接凭肉眼扫 JSON：

```bash
python3 <byted-volcengine-topology-analyzer-skill>/scripts/analyze_topology.py \
  --node "<node-id-or-keyword>" \
  --output json

如果已知业务：

python3 <byted-volcengine-topology-analyzer-skill>/scripts/analyze_topology.py \
  --business "<business>" \
  --node "<node-id-or-keyword>" \
  --output json

如果用户给出了变更描述：

python3 <byted-volcengine-topology-analyzer-skill>/scripts/analyze_topology.py \
  --business "<business>" \
  --node "<node-id-or-keyword>" \
  --change "<change-description>" \
  --output json

3. 有歧义时先澄清

如果脚本返回多个匹配：

• 优先看 match_score 和 match_reasons
• 如果是 id:exact、public_ip:exact 这类高置信命中，可以以第一候选为主回答
• 如果只是 name:fuzzy 或 metadata:fuzzy，不要擅自选一个，先让用户确认
• 如果多个业务里都有同名节点，要把候选业务、节点类型、得分和命中原因一起列出来

4. 需要时再读 topology.md

在这些场景下补读对应业务下的 topology.md：

• 需要把链路解释得更口语化
• 想确认外部入口链路是否和结构化结果一致
• 用户想看一个更接近人工总结的回答

回答原则

1. 先分层，再下结论

回答时区分这三层：

• 直接关联：与目标节点 1 跳相连的资源
• 直接影响：能明确推断会受该节点变更影响的 ECS 或入口链路
• 潜在关联：在同一局部拓扑中 2 跳内可达，但不能直接断言一定受影响的资源

2. 链路以资源 ID 为主

• 输出链路时默认以资源 id 为主，避免实例名称重复导致误判
• 若需要补充人工可读信息，可以附带 name，但不要用 name 替代 id

3. 不要凭空虚构应用名

这个数据里未必显式存了“应用名”。因此：

• 如果存在 EIP -> CLB/ALB -> server_group -> ECS 这类链路，就表述为“基于拓扑推断出的应用入口链路”
• 不要凭空虚构业务系统名、服务名、域名
• 如果只能定位到 ECS，就明确说“当前只能确认受影响的计算节点，未发现更上层应用名字段”

4. 对不同资源类型使用不同推断方式

• security_group、subnet、vpc、ebs： 先找直接归属或挂载到它的 ECS，再继续向上追溯入口链路
• eip、clb、alb、natgateway、server_group： 直接向下找 ECS
• ecs： 直接回溯它的上游入口链路，同时列出它所属的 security_group/subnet/vpc/ebs

5. 变更摘要要明确是启发式推断

如果用户明确在问“做某个变更会怎样”，优先使用脚本返回的 change_assessment：

• risk_level：作为变更风险等级
• summary_lines：作为简洁结论
• risk_reasons：作为为什么有风险
• validation_checklist：作为变更前后校验项
• rollback_suggestions：作为回滚建议

不要把这些启发式风险提示说成“绝对事实”。要明确说这是基于当前静态拓扑和变更关键词的推断。

回答结构

优先按这个顺序组织回答：

结论：
- 命中的节点是 ...
- 当前可确认直接影响到 ...