Understand-Anything 中的 Terraform 语言提示片段：让 LLM 看懂 IaC 代码并生成知识图谱

Understand-Anything 是一个把代码库转化为交互式知识图谱的工具，它通过 LLM 子代理逐批分析文件，产出 knowledge-graph.json 供仪表盘浏览。对于基础设施即代码（IaC）仓库而言，Terraform 配置文件的理解质量直接决定了图谱中资源、变量与模块之间关系是否正确。本文基于 Terraform 语言提示片段（下称"提示片段"）展开，完整覆盖其核心概念、文件模式、边模式与摘要风格四大板块，并结合仓库源码说明这些片段是如何被注入 LLM 提示词、以及其中的边类型如何被图谱 schema 校验的。

读完本文，你将掌握：Terraform 在 Understand-Anything 流水线中的定位（语言 ID、文件扩展名、节点类型）、提示片段四个板块的完整内容与用途，以及 provisions、depends_on、deploys、configures 等 Terraform 专属边类型在 边类型 schema 中的定义与别名归一化机制。

提示片段在 /understand 流水线中的位置

Terraform 提示片段并不是一份独立的用户文档，而是 /understand 技能执行 Phase 4（ARCHITECTURE，识别架构分层）阶段注入给 architecture-analyzer 子代理的上下文素材。根据 SKILL.md 的说明：

Language context injection: For each language detected in Phase 1 (e.g., python, markdown, …, terraform, …), read the file at ./languages/<language-id>.md … and append its content after the base template under a ## Language Context header. If the file does not exist for a detected language, skip it silently.

即：Phase 1 扫描项目时若检测到 Terraform 语言（语言 ID 为 terraform），技能会自动读取与本 SKILL.md 同目录下的 languages/terraform.md，将其全文追加到架构分析器提示词的 ## Language Context 标题之下。值得注意的是，SKILL.md 明确要求"Include non-code language snippets — they provide edge patterns and summary styles for non-code files"——Terraform 属于典型的"非代码语言"，这类片段的核心价值就是提供边模式（Edge Patterns）和摘要风格（Summary Style），弥补 LLM 对 .tf 文件语义关系的判断能力。

语言 ID 是如何被检测到的

提示片段的加载依赖语言 ID 与文件名一一对应（terraform.md ↔ ID terraform）。这一 ID 由 语言注册表配置 定义：

export const terraformConfig = {
  id: "terraform",
  displayName: "Terraform",
  extensions: [".tf", ".tfvars"],
  concepts: ["resources", "data sources", "variables", "outputs", "modules", "providers", "state", "workspaces"],
  filePatterns: {
    entryPoints: ["main.tf"],
    barrels: [],
    tests: [],
    config: ["terraform.tfvars", "variables.tf"],
  },
} satisfies LanguageConfig;

从源码结构看，该配置完成了三件事：

1. 扩展名识别：.tf 与 .tfvars 是 Terraform 的判定依据，对应 StrictLanguageConfigSchema 中"至少一个扩展名或文件名"的必填约束；
2. 概念词表：concepts 字段列出了 resources、data sources、variables、outputs、modules、providers、state、workspaces 八个概念——与提示片段"Key Concepts"板块高度呼应，二者共同构成 LLM 分析 Terraform 文件时的领域知识底料；
3. 文件模式约定：main.tf 被登记为入口点（entryPoint），variables.tf 与 terraform.tfvars 被登记为配置文件（config）。这与提示片段"File Patterns"板块中 main.tf 的地位一致，可推断在架构分层时 main.tf 更容易被识别为基础设施层的锚点文件。

配套的 扫描脚本 顶部注释也声明其语言清单与 packages/core/src/languages/configs/* 保持同步，保证 Phase 1 扫描与 Phase 4 语言上下文注入使用同一套语言 ID。

Key Concepts：提示片段如何教 LLM 理解 Terraform

提示片段的第一板块"Key Concepts"以 10 条要点概括了 Terraform 的领域模型。完整继承如下，每条概念都会在架构分析时作为提示词的一部分直接参与 LLM 推理：

概念	要点（原文语义）
Declarative Infrastructure	声明式基础设施：定义期望状态，Terraform 计算并应用 diff
Providers	连接云 API（AWS、GCP、Azure、Kubernetes 等）的插件
Resources	resource "type" "name" 块，声明基础设施组件
Data Sources	data "type" "name" 块，读取已有基础设施状态
Variables	variable 块，用默认值与校验来参数化配置
Outputs	output 块，暴露值供跨模块引用或人工消费
Modules	可复用、可组合的基础设施包，自带 variables 与 outputs
State Management	.tfstate 文件跟踪真实资源映射（切勿提交到 git）
Workspaces	隔离的状态环境，从同一份代码管理 dev/staging/prod
Plan and Apply	terraform plan 预览变更，terraform apply 执行变更

这 10 条概念与语言注册表配置中的 concepts 数组互为补充：注册表提供压缩版词表用于机器检测，提示片段提供面向 LLM 的完整语义描述。其中"State Management"条目明确提示 .tfstate 不应提交 git——这意味着在真实分析场景中，若 .understandignore 或 --exclude 排除了状态目录，图谱就不会把状态文件误识别为资源节点。

Notable File Patterns：约定俗成的文件名约定

第二板块列出了 Terraform 项目的标准文件布局，LLM 依据这些约定判断每个 .tf 文件的角色：

• main.tf — 主资源定义
• variables.tf — 输入变量声明（含类型与默认值）
• outputs.tf — 输出值定义
• providers.tf — Provider 配置与版本约束
• backend.tf — 远程状态后端配置（S3、GCS 等）
• modules/**/*.tf — 可复用基础设施模块
• *.tfvars — 面向不同环境的变量值文件
• terraform.lock.hcl — Provider 版本锁文件

这份清单与核心包配置形成交叉印证：filePatterns.entryPoints 登记了 main.tf，filePatterns.config 登记了 variables.tf（配置清单中的 terraform.tfvars 也覆盖 .tfvars 家族）。可以推断，当架构分析器处理一个典型的 infra/ 目录时，main.tf 会因"入口"身份获得更高的层级判定权重，而 variables.tf/outputs.tf 则会被归为参数化辅助文件，这与提示片段中"Variables/Outputs"概念板块的分工描述是一致的。

Edge Patterns：Terraform 文件之间的四类关系边

第三板块"Edge Patterns"是整份提示片段中技术密度最高的部分——它直接规定 Terraform 文件之间应当产生哪四种语义边：

1. Terraform 文件 provisions 其自身定义的基础设施资源；
2. 模块引用在 Terraform 文件之间创建 depends_on 边；
3. Terraform 通过引用容器镜像或部署目标来 deploys 应用代码；
4. 变量文件 configures 它所参数化的 Terraform 模块。

这四条边类型并非凭空约定，它们在核心 schema 中都有正式定义。schema.ts 的 EdgeTypeSchema 将边类型分为若干组，其中基础设施组为：

"deploys", "serves", "provisions", "triggers",               // Infrastructure

依赖组中则包含 depends_on、configures（见 types.ts 中 EdgeType 的同一分组注释）。此外 schema 还内置了一套别名归一化表，把 LLM 可能生成的近义边类型自动改写为标准值，例如：

• creates → provisions
• uses / requires → depends_on
• describes → documents、exposes → serves

Schema 测试 中的两个用例锁定了这一行为：一个用例验证 deploys、serves、migrates、documents、provisions、routes、defines_schema、triggers 全部通过校验；另一个用例验证 creates: "provisions" 等别名会被自动纠正。这保证了即使 LLM 在分析 Terraform 文件时写出 creates 而非 provisions，合并进 assembled-graph.json 的边仍然会落到标准类型上。

边在 file-analyzer 中的落地位置

值得说明的是，"Edge Patterns"板块的受众与"Language Context"注入并不完全重合。Phase 2 中真正逐文件产出节点的 file-analyzer 代理 自带一套完整的边类型表，其中与 Terraform 直接相关的定义包括：

• 节点类型：*.tf、*.tfvars 等非代码基础设施文件被归类为 resource 节点（fileCategory 为 infra），这是 provisions 边的源端节点；
• 边类型：configures（配置/变量文件作用于模块，权重 0.6）、deploys（基础设施文件构建/部署代码，权重 0.7）、depends_on（运行时依赖，权重 0.6）；
• 标签约定：*.tf 文件被赋予 infrastructure、deployment 标签。

提示片段中的 "Edge Patterns" 板块正是对这些通用规则在 Terraform 语境下的具象化：它告诉 LLM"模块引用 → depends_on"、"变量文件 → configures 模块"，把抽象的边类型表映射到 .tf 文件的具体场景上。两个来源叠加，构成了 Terraform 文件从节点分类、标签、到关系边的完整判定链。

Summary Style：三段式摘要模板

第四板块"Summary Style"给出了 Terraform 文件节点摘要（summary 字段）的三个示范句式，要求摘要遵循"用途 + 数量 + 具体资源"的写法：

"Terraform configuration provisioning N AWS resources including VPC, ECS cluster, and RDS instance."

"Infrastructure module defining a reusable Kubernetes namespace with RBAC and network policies."

"Variable definitions for N environment-specific settings (region, instance type, scaling)."

这三条示例恰好对应了文件模式的三种典型角色：main.tf 式的资源定义文件（第一句，呼应 provisions 边）、modules/**/*.tf 式的模块文件（第二句，呼应"Modules"概念）、*.tfvars 式的变量定义（第三句，呼应 configures 边）。file-analyzer 对 Infra 文件的通用要求是"Describe what gets deployed/built"，而这里的模板进一步把要求收窄到"provisioning N 个 X 云资源，包括…"——数量与具体资源名的组合，使得摘要在仪表盘 ProjectOverview 或节点信息面板中具备可直接检索的信息量。

从注入到成图：一份 .tf 文件走过的完整链路

把前述各环串联起来，一份 Terraform 文件在 Understand-Anything 中的处理链路如下（各环节均有仓库内对应物，可按路径查阅）：

1. 扫描：scan-project.mjs 依据语言注册表（含 terraform.ts）识别 .tf/.tfvars 为 terraform 语言，产出 fileCategory: infra 的文件清单与 scan-result.json；
2. 分批：compute-batches.mjs 生成 batches.json，Terraform 文件按其所在批次分派给 file-analyzer 子代理；
3. 分析：file-analyzer 按 代理定义 为每个 .tf 文件创建 resource: 节点，按权重表产出 provisions/configures/depends_on/deploys 边；
4. 合并：merge-batch-graphs.py 归一化节点 ID 与复杂度、去重并丢弃悬空边；边类型则经由 schema.ts 的别名表完成最后兜底（如 creates → provisions）；
5. 架构分层：Phase 4 的 architecture-analyzer 在提示词中注入本提示片段全文（## Language Context），据此把 Terraform 文件归入基础设施层并写出符合 Summary Style 的摘要；
6. 成图：最终汇入 $UA_DIR/knowledge-graph.json，在 dashboard 中呈现为可搜索、可导航的交互图谱。

小结

Terraform 语言提示片段 的篇幅不长，但四个板块各司其职：Key Concepts 提供领域语义，File Patterns 提供文件名到角色的映射，Edge Patterns 规定 provisions/depends_on/deploys/configures 四类关系边，Summary Style 约束节点摘要的句式与信息密度。它的生效机制则由 SKILL.md 的 Phase 4 语言上下文注入驱动，并由 核心语言注册表、边类型 schema 及其 测试用例 在机器层面完成校验与归一化。对以 Terraform 管理基础设施的团队而言，理解这套片段机制意味着：你看到的每一个 resource: 节点与每一条 IaC 关系边，背后都有明确的检测规则、提示词依据和 schema 兜底，而非 LLM 的自由发挥。