Understand-Anything YAML 语言上下文片段解析：yaml.md 如何引导 LLM 把 YAML 文件映射进知识图谱
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
/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>.mdand append its content after the base template under a## Language Contextheader. …Include non-code language snippets— they provide edge patterns and summary styles for non-code files.
也就是说：只要项目里检测到yaml，yaml.md 的全文就会被原样追加到 architecture-analyzer.md 基础模板之后，成为 LLM 划分架构层时的领域知识。它不是可执行代码，而是一份"语言知识卡"，教 LLM 三件事：
- 读什么——YAML 文件的哪些语法结构值得关注（Key Concepts）；
- 找什么文件——哪些命名模式的 YAML 文件对应容器、CI/CD、K8s 等基础设施语义（Notable File Patterns）；
- 连什么边——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_onDockerfile- 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"参考表给出了同一套权重（deploys0.7、configures/triggers/depends_on0.6、provisions/serves0.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 提到的多文档流、流式风格与保留字引号：
- 普通 mapping 根：用
yaml库解析后取顶层 key，再回原文用正则^["']?<key>["']?\s*:定位行号（兼容 GitHub Actions 的"on": push），最后按相邻 key 修正每个 section 的lineRange终点； - 数组根（CloudFormation 片段、K8s
List文档等）：为每个数组项生成一个 section，命名优先取项的name、id、kind字段，取不到才用[i]下标——这正是 K8s 清单以kind命名的由来； - 解析失败回退：对形如
^(\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 片段的作用：
- 看节点类型分布：统计节点中
type为config、service、pipeline、resource的条目，应能看到config:docker-compose.yml、pipeline:.github/workflows/ci.yml这类 ID（前缀规则见 file-analyzer 的"Node Types and ID Conventions"表）； - 看边类型：过滤
type为configures/triggers/deploys/provisions的边，确认源节点全部是 YAML 文件节点，目标指向代码文件或 Dockerfile，且weight符合 0.6/0.7 约定； - 看摘要风格：检查这些 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"口号在基础设施面落地的方式。
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
