byted-volcengine-topology-analyzer

Topology Impact Analysis Skill

Capability Positioning

This Skill is not responsible for building the underlying data, but rather consumes existing topology data to answer questions related to impact scope, ownership relationships, upstream and downstream links, and change blast radius.

• Locate the target node, for example sg-xxx、eip-xxx、clb-xxx、i-xxx, IP, resource name
• Infer directly associated resources, affected ECS instances, and entry links based on the structured topology
• When the user provides a change description, generate a risk summary and validation suggestions based on the static topology
• In multi-candidate or multi-business scenarios, first provide a ranking of candidates, then decide whether user confirmation is needed

Input Prerequisites

This Skill by default consumes the business topology data deposited by the basic asset/topology construction process.

• Default search directory:
  • under the current workspace business_topologies/
• Directory structure convention: ··· 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

If the business is known:

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

If the user has provided a change description:

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

3. Clarify first when there is ambiguity

If the script returns multiple matches:

• Prioritize looking at match_score and match_reasons
• If it is a high-confidence hit such as id:exact、public_ip:exact , you may answer based mainly on the first candidate
• If it is only name:fuzzy or metadata:fuzzy, do not arbitrarily pick one; first ask the user to confirm
• If multiple businesses all have a node with the same name, list the candidate businesses, node types, scores, and hit reasons together

4. Read only when needed topology.md

In these scenarios, additionally read the corresponding topology.md：

• The link needs to be explained in a more colloquial way
• Want to confirm whether the external entry link is consistent with the structured result
• The user wants to see an answer closer to a manually written summary

Answering Principles

1. Layer first, then draw conclusions

When answering, distinguish these three layers:

• Directly associated: resources connected to the target node by 1 hop
• Direct impact: ECS instances or entry links that can be clearly inferred to be affected by a change to that node
• Potential association: resources reachable within 2 hops in the same local topology, but for which it cannot be directly asserted that they will definitely be affected

2. Links are primarily based on resource ID

• When outputting links, by default use resource id as the primary basis, to avoid misjudgment caused by duplicate instance names
• If human-readable information needs to be added, namemay be attached, but do not use name to replace id

3. Do not fabricate application names out of thin air

This data may not explicitly store an "application name." Therefore:

• If a link such as EIP -> CLB/ALB -> server_group -> ECS exists, express it as "the application entry link inferred based on the topology"
• Do not fabricate business system names, service names, or domain names out of thin air
• If only the ECS can be located, clearly say "currently only the affected compute node can be confirmed; no higher-level application name field was found"

4. Use different inference methods for different resource types

• security_group、subnet、vpc、ebs: First find the ECS directly owned by or attached to it, then continue tracing upward along the ingress path
• eip、clb、alb、natgateway、server_group: Directly look downward for ECS
• ecs: Directly trace back its upstream ingress path, and also list the security_group/subnet/vpc/ebs

5. Change summaries must clearly state that they are heuristic inferences

If the user is explicitly asking "what would happen if I make a certain change", prioritize using what the script returns as the change_assessment：

• risk_level: as the change risk level
• summary_lines: as the concise conclusion
• risk_reasons: as the reason why there is risk
• validation_checklist: as the pre- and post-change verification items
• rollback_suggestions: as the rollback recommendation

Do not present these heuristic risk warnings as "absolute facts". Clearly state that this is an inference based on the current static topology and change keywords.

Answer structure

Prefer to organize answers in this order:

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

关联关系：
- 直接关联资源: ...
- 所属业务: ...
- 候选排序: 如果存在多命中，列出前 2~3 个候选及命中原因

影响链路：
- 链路 1: EIP -> CLB -> server_group -> ECS
- 链路 2: ...

变更风险：
- 风险等级: high / critical / ...
- 风险提示: ...
- 校验建议: ...
- 回滚建议: ...

判断说明：
- 这是基于当前静态拓扑数据的推断
- 如果要做变更前确认，建议继续核对运行时配置和白名单规则

Example questions

Example 1

User:

安全组 sg-3vai4r386pnuo1w7k94e5s09v 如果放开 80 端口，会影响什么应用？

Answer focus:

• Hit security_group
• Find the ECS that belongs to this security group
• Trace back to EIP -> CLB -> server_group -> ECS or EIP -> ECS
• Clearly state that this is an "affected ingress path" rather than a "confirmed business name"
• Give the risk level, verification recommendations, and rollback recommendations

Example 2

User:

14.103.24.61 这个入口 IP 背后挂了哪些资源？

Answer focus:

• Identify that the IP may match EIP or related resource metadata
• List the CLB, backend server group, and ECS
• Describe the path in topological order
• If there are multiple candidates, show the candidate ranking and explain why the first item is preferred

Example 3

User:

i-yek807xukgk36d6jug0q 这个 ECS 属于哪个业务，和哪些网络资源有关？

Answer focus:

• Return the business it belongs to
• List the security group, subnet, VPC, and EBS
• List the corresponding ingress path

Example 4

User:

帮我全局查一下名为 ECS 的节点，先按最可能的候选排序给我看。

Answer focus:

• Trigger cross-business retrieval
• First show the candidate ranking, the reason for the match, and the business ownership
• If the high-scoring candidates are not unique, first ask the user to confirm the specific target node

Fallback rules

• If the script cannot find the node, clearly state "the current topology data does not contain a match for this node"
• If the node can be matched but there is no complete ingress path, do not fabricate one; directly state "only located to the infrastructure layer"
• If the user is asking about real-time status, but the current data is only static topology, remind them that this analysis result is based on a snapshot/topology
• If the user's question is essentially evaluating a certain change, but no node is specified, first ask for the target resource; do not speak in generalities