infrahub-importing-data

CSV/TSV 导入 Infrahub 对象

概述

为将用户提供的 CSV 或 TSV 输入（单个文件、文件夹中的多个文件，或任意组合）转换为 infrahubctl object load 可接受的 Infrahub 对象 YAML 提供专家指导。此技能搭起了从“我有一份电子表格”到“这些对象已存在于可供审查的分支中”的桥梁。

此技能严格依赖实时架构。如果 CSV 列在架构中没有对应项，它会停止，列出有问题的列，并引导用户前往 infrahub-managing-schemas，单独做出架构决策。它绝不会建议添加属性、下拉选项或进行任何其他架构编辑，也绝不会直接写入默认分支。

项目上下文

现有架构文件： !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -10

现有对象文件： !find . -name "*.yml" -path "*/objects/*" 2>/dev/null | head -10

.infrahub.yml（如果存在）： !find . -maxdepth 2 -name ".infrahub.yml" 2>/dev/null | head -1

工作树中的候选 CSV/TSV 输入： !find . -maxdepth 3 \( -name "*.csv" -o -name "*.tsv" \) 2>/dev/null | head -10

如果调用时提供了参数（例如，/infrahub:importing-data inventory.csv），则将第一个参数视为输入文件或文件夹；将其余参数视为要包含的其他路径。

适用场景

• 用户提供一个或多个 CSV 或 TSV 文件，并希望将数据导入 Infrahub。
• 输入数据已反规范化——单张工作表混合了多种类型，需要将其拆分到正确的架构节点，并按正确的加载顺序处理。
• CSV 包含看起来像下拉选项标签的列（例如，Status: Active），需要输出选项名称（例如，active）。
• CSV 中每个子项都重复列出父类型的行，而这些子项应作为组件子项内联到父项中。
• 接口格式的名称（eth0..eth47）按顺序出现，并且需要合并范围后再输出。
• 用户希望为每个导入值添加来源标记。

不适用场景

• 输入是 infrahubctl dump 导出的 LDJSON 转储。请使用 infrahubctl load；它读取的是另一种格式，不适用于 CSV。两者都是顶层命令；没有 import 或 export 命令组。这些技能用于区分二者，避免混淆。
• 用户需要更改架构。此技能对架构只读。请转交给 infrahub-managing-schemas。
• 用户需要将 Infrahub 中的数据导出为 CSV。通过 infrahubctl object get -o csv 已可导出单一类型；未来的配套技能将涵盖多类型导出。
• 输入是 JSON、XLSX、Parquet 或其他非 CSV 格式。v1 仅支持 CSV 和 TSV。

规则类别

优先级	类别	前缀	描述
CRITICAL	工作流	workflow-	架构内省、配置文件样本、失败即关闭的门控、预先访谈、自检、预检闭环、优先使用分支、验证错误映射
HIGH	输入	inputs-	文件／文件夹／列表规范化、CSV 方言检测、同类型合并
CRITICAL	映射	mapping-	列 → 属性、值强制转换、空值／null 处理、下拉标签 → 名称、引用 HFID 检测
HIGH	拆分	decomposition-	将反规范化 CSV 拆分到多种类型
MEDIUM	范围	range-	接口格式检测与合并
LOW	来源标记	lineage-	导入时可选添加来源／所有者标记
LOW	输出	outputs-	文件级格式注意事项（来源注释）

此技能依赖的架构功能

此技能生成的对象 YAML 符合目标架构的实际形态。如果架构缺少 CSV 所需的功能，加载就会失败——因此，此技能会预先检查这些功能，并在发现问题时升级处理，而不是悄悄绕过。

如果 CSV 包含……	架构必须……	参见
指向另一种类型的引用列	在目标节点上定义 human_friendly_id；HFID 的长度决定引用是标量还是列表形式	../infrahub-managing-schemas/rules/display-human-friendly-id.md
Dropdown 列的标签样式值（Active 而非 active）	将 Dropdown 的 choices 声明为同时包含 name 和 label 的对象；生成器会写入 name，并从架构读取 label	../infrahub-managing-schemas/rules/attribute-defaults-and-types.md
带有各子项列的重复父行	将 Component（父项）和 Parent（子项）关系配对，并使用相同标识符；同时在子项侧设置 optional: false	../infrahub-managing-schemas/rules/relationship-component-parent.md
找不到明显架构归属的列	通过 infrahub-managing-schemas 扩展——此技能会拒绝继续，并移交处理	../infrahub-managing-schemas/SKILL.md

如果用户要加载的数据缺少上述任何一项，这属于架构迁移，而不是导入修复。此技能会停止并说明原因。

工作流

按顺序执行以下 14 个步骤。编号至关重要——前面的步骤决定后续步骤能否继续。

1. 将输入规范化为扁平文件列表。 接受单个路径、目录（递归扫描 *.csv / *.tsv）或列表，并在分析前解析为扁平列表。对于每个文件，先检测 CSV 方言（分隔符、编码、BOM、换行符），再读取行。请阅读 rules/inputs-file-folder-list.md 和 rules/inputs-csv-dialect.md。

2. 发现架构——只读。 按优先级尝试各数据源，遇到第一个能返回 CSV 所需类型的数据源后即停止：

   1. MCP 服务——与 infrahub-analyzing-data 使用相同的接口；可查看已部署状态，包括分支专属的 Dropdown 选项和 HFID。
   2. infrahubctl schema export --branch <name>——MCP 未连接时，使用已配置的服务进行 CLI 导出。
   3. /api/schema?branch=<name> REST 端点——infrahubctl 不可用或指向其他服务时，直接通过 HTTP 获取。
   4. 仓库中的本地 schemas/*.yml——最后的备选方案；本地文件可能滞后于已部署状态，因此必须在第 11 步通过服务端验证来发现差异。

   记录所用的数据源，以便用户了解映射的权威程度。切勿建议修改架构。 请阅读 rules/workflow-introspect-first.md。

3. 分析每个文件。 读取表头和样例行（默认为 20 行；如需检测 Dropdown、范围或反规范化，则读取更多行）。记录列数据形态、每列不同值的数量、样例值和序列模式。请阅读 rules/workflow-profile-sample.md。

4. 按文件生成映射草案，使用 reference.md 中的 启发式规则：

   • **列 → 属性：**先精确匹配名称， 再进行 snake_case 往返转换，然后模糊匹配显示标签， 最后去除单位（(GB)、(MHz)） ——超出这些范围的情况交由访谈处理。 阅读 rules/mapping-column-to-attribute.md。
   • **值强制转换：**Boolean / Number / DateTime / JSON 属性类型在输出前需要 显式进行类型强制转换。阅读 rules/mapping-value-coercion.md。
   • **空单元格：**根据 schema 的 optional 和 default_value 声明，决定省略还是失败。阅读 rules/mapping-empty-and-null.md。
   • **下拉列：**根据 schema 构建标签→名称 查找表并进行转换。阅读 rules/mapping-dropdown-label-to-name.md。
   • **引用列：**通过名称与关系匹配， 并根据值的形态与目标类型的 HFID 进行匹配，以检测引用列。阅读 rules/mapping-reference-and-hfid.md。
   • **范围列：**合并连续的接口样式序列。阅读 rules/range-detection.md。
   • **反规范化列：**检测重复的父级分组，并将输入拆分到 多种类型中。阅读 rules/decomposition-denormalized-csv.md。
   • **多个输入中的同一种类型：**合并为一个带编号的输出文件，按 HFID 去重，并在访谈中指出冲突。阅读 rules/inputs-merge-same-kind.md。

5. **失败即关闭关卡。**如果任何列没有对应的 schema， **立即停止。**生成结构化报告，列出未映射的列和已检查的 类型，提示用户查看 infrahub-managing-schemas，然后退出。不进行部分写入。阅读 rules/workflow-fail-closed-on-unmapped-columns.md。

6. **预先访谈。**在写入任何文件之前，将所有剩余的 歧义汇总为一轮多选问题。阅读 rules/workflow-up-front-interview.md。

7. **确认并锁定映射。**在写入第一个文件之前，回显完整计划 （目标文件、类型、列绑定、分支名称、血缘信息选择加入）。

8. 将对象 YAML 输出到本地工作目录（默认为 ./output_dir/）。 每个文件都符合 managing-objects 封装格式： apiVersion: infrahub.app/v1、kind: Object、 spec.kind、spec.data。文件按加载顺序编号 （NN_<kind-plural>.yml）。每个文件开头都包含一条溯源注释，其中注明 源 CSV 文件 + sha256 + 输出时间戳。 参阅 ../infrahub-managing-objects/rules/format-structure.md 中的格式规则、 ../infrahub-managing-objects/rules/organization-load-order.md 中的文件命名约定，以及 rules/outputs-provenance-comment.md 中的注释格式。

9. **根据 managing-objects 进行自检。**重新阅读列出的 managing-objects 规则，并逐条检查输出是否符合。仅限本地操作——不使用 CLI、 不连接服务、不创建分支。完成修正后再继续。阅读 rules/workflow-self-check-against-managing-objects.md。

10. 预检引用闭包。 遍历输出中的每一条 关系引用，并验证目标能够解析到上游文件中的 某一行，或是由内省捕获到的实际对象。 孤儿引用在任何分支被触及之前即失败关闭。请阅读 rules/workflow-pre-flight-closure.md。

11. 创建分支。 只有在自检和预检闭包 通过之后，才运行 infrahubctl branch create <name>（默认 csv-import-YYYYMMDD-HHMM，用户可在 访谈中覆盖）。最后执行此操作可避免 一次性分支出现在分支列表中。请阅读 rules/workflow-branch-before-load.md。

12. 在分支上执行服务端校验： infrahubctl object validate ./output_dir/ --branch <name>。可捕获本地检查无法发现的 模式解析错误（kind 不在模式中、属性名拼写错误、 引用目标缺失）。出错时，将诊断信息 翻译回源 CSV 单元格，并请用户 修正输入——不要手动编辑输出的 YAML。请阅读 rules/workflow-validate-error-mapping.md。

13. 在分支上加载：infrahubctl object load ./output_dir/ --branch <name>。对象 加载跨文件不是事务性的——如果 20 个文件中的第 17 个失败，文件 1–16 已经位于 该分支上。分支优先的设计意味着你 丢弃该分支并使用新的分支名重新运行； 你永远不需要手动清理部分状态。

14. 移交。 告知用户分支已 准备好供审查、已运行的 validate/load 命令， 以及如何在 UI 中打开提议的 变更。不要自动合并。

支持性参考

• examples.md — 8 个可直接使用的 CSV 模式：扁平列表、反规范化拆分、 父带子、下拉标签规范化、 范围折叠、谱系标记、失败关闭 报告、合并 + 去重
• reference.md — 启发式 顺序、文件信封提醒、HFID 决策 矩阵、文件命名约定
• rules/ — 按 类别前缀划分的各个规则；请从 rules/_sections.md 开始
• ../infrahub-managing-objects/SKILL.md — 每个输出文件都必须遵循的消费端规则 （信封、值映射、组件、 范围、加载顺序、分支优先）
• ../infrahub-analyzing-data/SKILL.md — 用于实时模式 发现的 MCP 内省模式
• ../infrahub-managing-schemas/SKILL.md — 当某一列没有模式归属时的逃生通道
• ../infrahub-common/metadata-lineage.md — 值元数据语义（source 仅为谱系； 锁定需要 owner + is_protected）
• ../infrahub-common/rules/workflow-branch-for-crud.md — 模式写入和对象写入共同继承的 共享分支优先规则
• ../infrahub-common/rules/connectivity-server-check.md — 在工作流中任何依赖服务的命令之前，使用 infrahubctl info 验证服务是否可达
• ../infrahub-common/rules/connectivity-python-environment.md — 检测项目的 Python 环境前缀 （uv run / poetry run），用于所有 infrahubctl 调用
• ../infrahub-common/rules/workflow-information-priority.md -- 技能内容优先；如何在真正存在缺口时 查阅 docs.infrahub.app（例如删除节点）