Understand-Anything YAML 语言上下文片段解析：yaml.md 如何引导 LLM 把 YAML 文件映射进知识图谱

/understand 技能在 Phase 4（架构识别）阶段会把 languages/<language-id>.md 提示片段注入 architecture-analyzer 子代理的 prompt。本文以 yaml.md 为主体，完整拆解这份 YAML 语言上下文片段定义的八项关键概念、七类文件模式、四条边模式与三种摘要风格，并结合仓库中的语言配置（yaml.ts）、YAML 解析器（yaml-parser.ts）与 agent 定义（architecture-analyzer.md、file-analyzer.md），说明这些提示文本最终如何落到 knowledge-graph.json 中的 config/service/pipeline/resource 节点与 configures/triggers/deploys/provisions 边上。

注入机制：yaml.md 在 /understand 流水线中的位置

SKILL.md 定义了七阶段流水线。Phase 1 SCAN 阶段由 project-scanner 子代理检测项目语言与框架；进入 Phase 4 ARCHITECTURE 后，主会话按规则拼装 architecture-analyzer 的 prompt，其中"Language context injection"一节的原文是：

For each language detected in Phase 1 (e.g., python, markdown, dockerfile, yaml, sql, terraform, graphql, protobuf, shell, html, css), read the file at ./languages/<language-id>.md and append its content after the base template under a ## Language Context header. … Include non-code language snippets — they provide edge patterns and summary styles for non-code files.

也就是说：只要项目里检测到 yaml，yaml.md 的全文就会被原样追加到 architecture-analyzer.md 基础模板之后，成为 LLM 划分架构层时的领域知识。它不是可执行代码，而是一份"语言知识卡"，教 LLM 三件事：

1. 读什么——YAML 文件的哪些语法结构值得关注（Key Concepts）；
2. 找什么文件——哪些命名模式的 YAML 文件对应容器、CI/CD、K8s 等基础设施语义（Notable File Patterns）；
3. 连什么边——YAML 文件与被它控制的代码之间应建立什么类型的关系边（Edge Patterns），以及产出的 summary 应长什么样（Summary Style）。

Key Concepts：八项关键概念及其对图谱构建的意义

原文档的 Key Concepts 一节列出了八个概念，这里逐项展开，并对照源码说明它们为什么重要。

概念	说明	对图谱构建的意义
缩进嵌套	基于空白的层级结构，只用空格、禁止 Tab	YAML 的"结构"就是缩进。YAMLConfigParser 只提取顶层 key 作为 section，正是利用了顶层 key 零缩进这一特征
锚点与别名	&anchor 定义可复用块，*anchor 引用它	K8s / CI 配置常用锚点去重，识别别名有助于把展开后的内容归因到原始定义处
合并键	<<: *anchor 把锚点内容合并进当前 mapping	GitHub Actions 的 defaults、K8s 的公共 spec 常依赖它，理解合并语义才能准确总结文件
多行字符串	字面块 | 保留换行，折叠块 > 合并行	脚本内联（CI 的 run: 字段、Terraform 注解）多为多行字符串，是 pipeline 语义的主要载体
文档分隔符	--- 开始新文档、... 结束一个（多文档流）	K8s 清单与 CloudFormation 常用 --- 拼接多个资源为单文件，解析器必须按文档流理解
标签与类型	!!str、!!int、!!bool 显式类型；自定义标签用于应用内建类型	显式类型声明影响值的语义解释（如把 "true" 当字符串还是布尔）
流式风格	类 JSON 的行内语法 {key: value}、[item1, item2]	紧凑写法出现在 compose/K8s 的 ports、env 等字段中，影响顶层 key 定位的正则匹配
环境变量替换	${VAR} 模式，常见于 docker-compose 与 CI 配置	说明值在分析时可能是"未定"的，总结时应描述"引用了环境变量"而非断言具体值

这八项概念在运行时并非装饰：yaml-parser.ts 的注释明确提到 GitHub Actions 中 on 是 YAML 1.1 保留字，常写作带引号的 "on": push，因此解析器在定位顶层 key 时同时匹配普通与加引号的写法（见下文）。可以说 Key Concepts 一节与解析器的边界处理相互印证。

Notable File Patterns：七类标志性 YAML 文件及其识别依据

原文档列出的七类文件模式，恰好覆盖了一个典型全栈项目的全部基础设施面：

文件模式	语义	仓库中的识别依据
docker-compose.yml / docker-compose.yaml	多容器应用定义	docker-compose.ts 以 filenames 精确匹配 docker-compose.yml、compose.yml 等文件名（而非扩展名），概念表含 services、networks、volumes、ports、depends_on、healthchecks
.github/workflows/*.yml	GitHub Actions CI/CD 工作流	github-actions.ts 的 filePatterns.config 为 .github/workflows/*.yml，概念含 workflows、jobs、steps、triggers、matrix strategy
.gitlab-ci.yml	GitLab CI/CD 流水线	architecture-analyzer.md 的目录模式表中 .gitlab 归为 ci-cd，文件模式表中 .gitlab-ci.yml、Jenkinsfile 归为 ci-cd
kubernetes/*.yaml / k8s/*.yaml	Kubernetes 资源清单	kubernetes.ts 的 filePatterns.config 为 k8s/*.yaml、kubernetes/*.yaml，概念含 deployments、services、pods、ingress、namespaces
*.config.yaml	应用配置文件	兜底模式，归为 config 节点
mkdocs.yml	MkDocs 文档站配置	文档构建配置，通常落入文档/构建层
serverless.yml	Serverless Framework 配置	函数计算部署定义

这里有一个值得注意的实现细节：kubernetes.ts 中的 TODO 注释说明，Kubernetes 清单没有独特扩展名或文件名，"检测需要基于内容或路径模式的启发式（例如检查 YAML 中的 apiVersion/kind 字段，或匹配 k8s/、kubernetes/、deploy/ 路径）。当前这些文件会按扩展名（.yaml/.yml）匹配到 yamlConfig"。也就是说，从源码结构看，当前版本里一个 deploy/xxx.yaml 的 K8s 清单在语言识别阶段会被归为 yaml；yaml.md 片段的作用正在于此——它告诉 LLM"即使语言是 yaml，看到 kubernetes/ 路径或 apiVersion/kind 字段就应按 K8s 语义理解，并给出 service/resource 节点与 deploys/provisions 边"，弥补了确定性检测的不足。

Edge Patterns：YAML 文件的四条边规则及其权重

原文档 Edge Patterns 一节的核心命题是：YAML 不是孤立文件，它"作用于"代码。四条边模式原文如下：

• YAML 配置文件 configures 它所控制的代码模块（例如数据库配置影响数据层）
• CI/CD YAML 文件 triggers 构建与部署流水线
• docker-compose YAML deploys 服务，并 depends_on Dockerfile
• Kubernetes YAML deploys 并 provisions 应用服务

这四条不是孤立的口号，它们在 file-analyzer.md 的"Edges for non-code files"边表中都有严格对应，每条边都有规定权重：

边类型	触发条件（file-analyzer 原文摘要）	权重
configures	配置文件影响某个代码文件或模块（如 tsconfig.json 配置 TS 编译、.env 配置运行时）	0.6
triggers	CI/CD 配置触发流水线或部署（如 GitHub Actions 在 push main 时部署）	0.6
deploys	基础设施文件构建/部署代码（如 Dockerfile 拷贝并运行应用代码、K8s 清单部署服务）	0.7
depends_on	非代码文件依赖另一个文件（如 docker-compose 依赖 Dockerfile、CI 工作流依赖 Makefile 目标）	0.6
provisions	Terraform 资源/模块创建基础设施（如创建数据库、开通 VM）	0.7
serves	K8s Service/Deployment 暴露端点，或反向代理路由到服务	0.7

SKILL.md 的"Edge Weight Conventions"参考表给出了同一套权重（deploys 0.7、configures/triggers/depends_on 0.6、provisions/serves 0.5~0.7 档），保证 file-analyzer 产出的边与最终图谱的权重体系一致。file-analyzer 还配了专门的"Edge Signal Quick Reference"提示表，例如"Dockerfile COPY 自代码目录 → deploys 边指向代码入口"、"docker-compose 引用 Dockerfile → compose 到 Dockerfile 的 depends_on"、"CI 配置运行测试命令 → CI 配置到测试文件的 triggers"——这些正是 yaml.md 四条边模式在逐文件分析阶段的落地规则。

节点侧的映射同样与 yaml.md 呼应。file-analyzer 的"Node type mapping by fileCategory"规定 infra 类文件按内容细分为三类：Dockerfile、docker-compose、K8s 清单 → service 节点；.github/workflows/*、.gitlab-ci.yml、Jenkinsfile → pipeline 节点；Terraform、CloudFormation、Vagrant → resource 节点；应用配置类 YAML → config 节点。此外，结构提取脚本对非代码文件还会输出 services（Dockerfile/compose 的每个 stage/service）、steps（CI 配置中的每个 job/step）、resources（Terraform/CloudFormation/K8s 资源）数组，file-analyzer 被要求为其中显著项生成 service:<path>:<name>、step:<path>:<name>、resource:<path>:<name> 子节点，而不是只产出一个父文件节点就打住。

Summary Style：三种摘要句式模板

原文档最后给出三句可复用的摘要范式：

• "Docker Compose configuration defining N services with networking, volumes, and health checks."
• "GitHub Actions workflow running tests on push and deploying to production on merge to main."
• "Kubernetes deployment manifest with N replicas, resource limits, and liveness probes."

这三个模板的共性是：一句话 = 文件角色 + 可数事实（N 个服务/副本）+ 关键机制（网络、卷、健康检查、触发条件、探针）。file-analyzer 对 summary 的要求与之对齐：1~2 句、"描述配置所控制的东西"（Config files: describe what the config controls）、禁止空话（"Bad: The utils file contains utility functions."），并要求标签使用 documentation、configuration、infrastructure、ci-cd、deployment、containerization、orchestration 等受控词表——例如 docker-compose.* 应打 orchestration、infrastructure 标签，.github/workflows/* 应打 ci-cd、deployment 标签。这样写出的 summary 最终会进入 knowledge-graph.json 的节点，供 dashboard 展示与 /understand-explain、/understand-chat 等技能消费。

源码纵深：从 yamlConfig 到 YAMLConfigParser 的确定性底座

提示片段负责"教 LLM 判断"，而仓库中另有两层确定性代码负责"先把事实算出来"，两者构成同一链路的上下游。

语言配置层：yamlConfig 与四个 YAML 变体

yaml.ts 定义了基础语言配置：

export const yamlConfig = {
  id: "yaml",
  displayName: "YAML",
  extensions: [".yaml", ".yml"],
  concepts: ["mappings", "sequences", "anchors", "aliases", "multi-document", "tags"],
  filePatterns: {
    entryPoints: [],
    barrels: [],
    tests: [],
    config: ["*.yaml", "*.yml"],
  },
} satisfies LanguageConfig;

注意 concepts 数组（mappings、sequences、anchors、aliases、multi-document、tags）与 yaml.md Key Concepts 中的"锚点与别名、文档分隔符"一一对应——语言配置给出机器可读的概念清单，md 片段给出人/LLM 可读的详细解释。同一 configs/index.ts 中还有四个 YAML 变体配置（dockerComposeConfig、kubernetesConfig、githubActionsConfig、openapiConfig），其中 docker-compose 与 openapi 靠文件名匹配（如 openapi.yaml、swagger.yaml），github-actions 与 kubernetes 靠路径 glob 匹配，这解释了为什么 yaml.md 的 Notable File Patterns 要按目录形态（.github/workflows/、kubernetes/）描述：它对应的就是这些配置的匹配依据。

解析器层：顶层 key 提取的三种分支

YAMLConfigParser 实现 AnalyzerPlugin，其 languages 数组声明为 ["yaml", "kubernetes", "docker-compose", "github-actions", "openapi"]——注释解释了原因：若不列出这些 YAML 风味格式，语言注册器打上这些 id 的文件会落入"没有匹配解析器"分支，丢失全部结构提取。解析逻辑有三个分支，恰好对应 yaml.md 提到的多文档流、流式风格与保留字引号：

1. 普通 mapping 根：用 yaml 库解析后取顶层 key，再回原文用正则 ^["']?<key>["']?\s*: 定位行号（兼容 GitHub Actions 的 "on": push），最后按相邻 key 修正每个 section 的 lineRange 终点；
2. 数组根（CloudFormation 片段、K8s List 文档等）：为每个数组项生成一个 section，命名优先取项的 name、id、kind 字段，取不到才用 [i] 下标——这正是 K8s 清单以 kind 命名的由来；
3. 解析失败回退：对形如 ^(\w[\w-]*)\s*: 的行做正则提取，保证格式略乱的 YAML 也能拿到顶层 key。

解析器只提取顶层 key、不深入嵌套，这与 yaml.md 的分工一致：确定性层给出"这个文件有哪些顶层 section（services、networks、jobs…）"的骨架事实，语义层（LLM 按 yaml.md 的指引）负责判断"这些 section 意味着什么、连什么边"。

架构层：architecture-analyzer 如何消费这些信号

Phase 4 中，architecture-analyzer 先运行确定性脚本计算目录分组、跨类别边矩阵（如 config -> file: 5 (configures)、service -> file: 2 (deploys)）、部署拓扑（hasDockerfile/hasCompose/hasK8s/hasCI）等，再做语义分层。其中 architecture-analyzer.md 内置的目录模式表与 yaml.md 的 Notable File Patterns 高度重合：.github/.gitlab/.circleci → ci-cd；k8s/kubernetes/helm/charts/terraform/docker → infrastructure；文件级模式 docker-compose.* → infrastructure、.github/workflows/* 与 .gitlab-ci.yml → ci-cd。非代码层的分层提示也直接给出结论：Dockerfile/docker-compose/K8s 清单/Terraform → layer:infrastructure，工作流文件 → layer:ci-cd，*.yaml 应用配置 → layer:config（小项目可合并）。于是完整链条是：Phase 1 检测语言 → Phase 2 file-analyzer 按边表产出 config:/service:/pipeline:/resource: 节点与 configures/triggers/deploys/provisions 边 → Phase 4 architecture-analyzer 在 yaml.md 片段指引下把它们归入 Infrastructure/CI-CD/Config 层 → Phase 7 落盘 knowledge-graph.json。

实操验证：在自己的项目里观察这份片段的效果

在任意含 YAML 基础设施的项目根目录运行 /understand（完整流程见 SKILL.md 的七阶段说明），产出位于项目数据目录 $UA_DIR/knowledge-graph.json（.ua/，或已存在时沿用旧目录 .understand-anything/）。可以按下面三步验证 yaml.md 片段的作用：

1. 看节点类型分布：统计节点中 type 为 config、service、pipeline、resource 的条目，应能看到 config:docker-compose.yml、pipeline:.github/workflows/ci.yml 这类 ID（前缀规则见 file-analyzer 的"Node Types and ID Conventions"表）；
2. 看边类型：过滤 type 为 configures/triggers/deploys/provisions 的边，确认源节点全部是 YAML 文件节点，目标指向代码文件或 Dockerfile，且 weight 符合 0.6/0.7 约定；
3. 看摘要风格：检查这些 YAML 节点的 summary 是否遵循"角色 + N 个可数事实 + 关键机制"句式，tags 是否命中 ci-cd、orchestration、infrastructure 等受控词表。

如果项目里 K8s 清单位于 deploy/ 等非 kubernetes/ 路径下，从源码结构看它们大概率以 yaml 语言身份进入分析（kubernetes.ts 的 TODO 已注明内容级检测尚待实现），此时 yaml.md 注入的上下文就是 LLM 把它们识别为 service/resource 节点的主要依据。

小结

yaml.md 篇幅不长，但它是 Understand-Anything 把"非代码文件纳入知识图谱"这一设计在 YAML 维度的完整知识契约：Key Concepts 教 LLM 读懂语法，Notable File Patterns 教它认出基础设施文件，Edge Patterns 加 Summary Style 教它产出符合 schema 的节点与边。与 yamlConfig、YAMLConfigParser 的确定性提取、file-analyzer 的边表权重、architecture-analyzer 的目录模式表配合后，YAML 配置文件不再是一堆游离的 config 节点，而是带上 configures/triggers/deploys/provisions 语义关系、归属 Infrastructure/CI-CD 层的图谱公民——这正是项目"graphs that teach"口号在基础设施面落地的方式。