| name | byted-volcengine-topology-analyzer |
| description | 基于已有拓扑数据回答资源影响面、上下游链路、业务归属和变更波及范围。只要用户在问某个节点或资源变更会影响什么应用、入口出口、上下游链路、归属业务，或者想梳理某个 ECS/CLB/EIP/安全组/VPC/子网/EBS 的依赖关系时，都应该使用这个 skill；即使用户没有明确提到 topology，也要主动触发。 |
拓扑影响分析 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：
直接向下找 ECSecs：
直接回溯它的上游入口链路，同时列出它所属的 security_group/subnet/vpc/ebs
5. 变更摘要要明确是启发式推断
如果用户明确在问“做某个变更会怎样”，优先使用脚本返回的 change_assessment：
risk_level：作为变更风险等级summary_lines：作为简洁结论risk_reasons：作为为什么有风险validation_checklist：作为变更前后校验项rollback_suggestions：作为回滚建议
不要把这些启发式风险提示说成“绝对事实”。要明确说这是基于当前静态拓扑和变更关键词的推断。
回答结构
优先按这个顺序组织回答：
结论：
- 命中的节点是 ...
- 当前可确认直接影响到 ...
关联关系：
- 直接关联资源: ...
- 所属业务: ...
- 候选排序: 如果存在多命中，列出前 2~3 个候选及命中原因
影响链路：
- 链路 1: EIP -> CLB -> server_group -> ECS
- 链路 2: ...
变更风险：
- 风险等级: high / critical / ...
- 风险提示: ...
- 校验建议: ...
- 回滚建议: ...
判断说明：
- 这是基于当前静态拓扑数据的推断
- 如果要做变更前确认，建议继续核对运行时配置和白名单规则
示例问题
示例 1
用户：
安全组 sg-3vai4r386pnuo1w7k94e5s09v 如果放开 80 端口，会影响什么应用？
回答重点：
- 命中
security_group
- 找到归属这个安全组的 ECS
- 回溯到
EIP -> CLB -> server_group -> ECS 或 EIP -> ECS
- 明确说明这是“受影响入口链路”而不是“确定业务名”
- 给出风险等级、校验建议和回滚建议
示例 2
用户：
14.103.24.61 这个入口 IP 背后挂了哪些资源？
回答重点：
- 识别 IP 可能匹配到
EIP 或相关资源元数据
- 列出 CLB、后端服务器组、ECS
- 按拓扑顺序描述链路
- 如果存在多候选，要展示候选排序并解释为何优先选第一项
示例 3
用户：
i-yek807xukgk36d6jug0q 这个 ECS 属于哪个业务，和哪些网络资源有关？
回答重点：
- 返回所属业务
- 列出安全组、子网、VPC、EBS
- 列出对应入口链路
示例 4
用户：
帮我全局查一下名为 ECS 的节点，先按最可能的候选排序给我看。
回答重点：
- 触发跨业务检索
- 先展示候选排序、命中原因和业务归属
- 如果高分候选不唯一，先请用户确认具体目标节点
兜底规则
- 如果脚本查不到节点，要明确说“当前拓扑数据里没有命中该节点”
- 如果能命中节点但没有完整入口链路，不要硬编，直接说明“仅定位到基础设施层”
- 如果用户在问实时状态，而当前数据只是静态拓扑，要提醒这是基于快照/拓扑的分析结果
- 如果用户的问题本质是评估某个变更，但没有明确 node，先追问目标资源，不要泛泛而谈
