infrahub-analyzing-data

概述

针对实时 Infrahub 实例提供交互式数据分析方面的专家指导。 此技能使用 Infrahub MCP 服务按需查询、关联并分析基础设施数据， 回答涉及多种节点类型及其关系的运维问题。

对于任何形式为 *“Infrahub 当前掌握了关于 X 的哪些信息， 以及它与 Y 有什么关系？”*的问题，都可以使用此技能。

常见问题类型：

• 合规性——“所有设备都遵循命名约定吗？”
• 服务影响——“机架中的设备承载了哪些服务？”
• 维护窗口——“哪些设备当前处于维护窗口中，有哪些内容依赖它们？”
• 漂移检测——“哪些已实现设备与其拓扑设计不一致？”
• 容量——“哪些机架的占用率超过 80%？”
• 变更影响——“哪些 BGP 会话、服务和 IP 依赖此前缀？”
• 库存缺项——“哪些设备未记录平台或操作系统版本？”

对于会阻止拟议变更的自动化、由流水线强制执行的检查，请参阅 ../infrahub-managing-checks/SKILL.md。 对于以制品形式导出的可重复定期报告，请参阅 ../infrahub-managing-transforms/SKILL.md。

项目上下文

此技能在分叉的子 Agent 上下文中运行，无法查看父级对话。必须通过参数传入用户的问题。

• 如果调用时带有参数（例如 /infrahub:analyzing-data Which devices have no platform assigned?）， 则将参数视为要回答的问题。

• 如果调用时没有参数，请勿猜测、勿使用此文件中的任何示例问题，也勿继续执行。请立即返回：

  **错误：**未向 infrahub-analyzing-data 传入问题。此技能 在分叉的上下文中运行，必须通过参数提供用户的问题。请重新调用， 并附上问题，例如： Skill(skill="infrahub-analyzing-data", args="<the user's question>")。

适用场景

• 通过自然语言交互式回答运维问题
• 交叉引用两种或更多节点类型，以查找关系或缺项
• 执行变更前调查其影响范围
• 审核整个库存中的数据质量
• 为相关方生成一次性或按需报告
• 编写生成器或检查之前，探索架构结构和数据

工作原理

Infrahub MCP 服务提供的工具可让 Claude 直接查询 Infrahub 数据。 典型工作流：

1. 查询——使用 MCP 工具从 Infrahub 获取当前状态
2. 关联——将数据与策略或第二个数据集进行联接、比较或筛选
3. 分析——识别缺项、异常或关系
4. 报告——提供发现结果、背景信息和修复建议

规则类别

优先级	类别	前缀	描述
CRITICAL	MCP 工具	mcp-	可用的 Infrahub MCP 工具、调用模式、响应结构
CRITICAL	查询模式	query-	用于获取、筛选和遍历关系的 GraphQL 结构
HIGH	关联分析	correlation-	联接、比较并分析多个查询中的数据
HIGH	报告输出	reporting-	呈现发现结果：摘要、表格、逐对象详情、修复建议
MEDIUM	方法选择	approach-	何时使用 MCP 分析、InfrahubCheck 或 Transform

MCP 服务基础

连接 Infrahub MCP 服务（v1.1.7）后， Claude 可以调用以下工具。

读取：

• mcp__infrahub__get_nodes — 列出某一 类型的节点，支持筛选和分页（首选的类型化 读取方式）
• mcp__infrahub__search_nodes — 按部分子字符串 查找某一类型的节点
• mcp__infrahub__get_schema — 了解架构 类型及其筛选条件
• mcp__infrahub__query_graphql — 执行只读的 GraphQL 查询
• mcp__infrahub__get_session_info — 报告当前 会话分支和实例地址

写入（隔离在分支中 — 写入自动创建的 mcp/session-* 分支，绝不写入默认分支）：

• mcp__infrahub__node_upsert — 创建或更新 对象
• mcp__infrahub__node_delete — 删除对象
• mcp__infrahub__mutate_graphql — 执行 GraphQL 突变以进行复杂写入
• mcp__infrahub__propose_changes — 创建 Proposed Change 供人工审核
• mcp__infrahub__reset_session_branch — 重置或 切换当前会话分支

每个工具的完整签名（参数、示例、 响应结构）以及分支模型，请参阅 rules/mcp-tools.md — 在调用这些工具之前， 请先阅读该文件。

# Example: find all devices in an active
# maintenance window
query MaintenanceDevices {
  MaintenanceWindow(status__value: "active") {
    edges {
      node {
        name { value }
        start_time { value }
        end_time { value }
        devices {
          edges {
            node {
              name { value }
              role { value }
              site {
                node { name { value } }
              }
            }
          }
        }
      }
    }
  }
}

典型分析工作流

1. Understand the question
   → "Which services depend on devices currently
      in a maintenance window?"

2. Identify the node types involved
   → MaintenanceWindow, DcimDevice, Service
     (or equivalent in your schema)

3. Query current state
   → mcp__infrahub__get_nodes per kind (typed), or
     mcp__infrahub__query_graphql — one query
     per node type, or combined

4. Correlate the data
   → Join across node types, filter, count, diff

5. Report findings
   → Summarize with counts, list affected objects,
     suggest next steps

参考资料

• examples.md — 分析 模式（命名、VLAN、BGP、维护、 服务影响）
• ../infrahub-common/graphql-queries.md — GraphQL 查询编写参考
• ../infrahub-common/infrahub-yml-reference.md — .infrahub.yml 项目配置
• ../infrahub-managing-checks/SKILL.md — 自动化流水线检查（用于强制执行）
• ../infrahub-managing-transforms/SKILL.md — 用于定期报告制品的转换
• ../infrahub-common/rules/workflow-information-priority.md -- 先阅读 Skill 内容；遇到确实存在的信息缺口时（例如删除节点）， 再了解如何查阅 docs.infrahub.app
• rules/ — 按类别前缀组织的 各项规则