Understand-Anything CSS 语言提示词片段解析：让样式表文件进入知识图谱的分析框架

本文解析 Understand-Anything 插件中 understand 技能内置的 CSS 语言提示词片段（language prompt snippet）。该文件是 /understand 分析流水线在架构分析阶段注入给 LLM 子代理的领域上下文，直接决定了 CSS/SCSS/Less 文件在生成的知识图谱中被赋予哪些关键概念、文件模式、边类型与摘要风格。读完后你将理解：样式表文件是如何从 Phase 1 的语言检测一路走到 Phase 4 的架构层划分，以及这份片段中每一条 Edge Pattern 如何映射为 knowledge-graph.json 中可验证的图边。

一、这个文件是什么：语言提示词片段在流水线中的位置

css.md 位于 understand 技能的 languages/ 子目录下，与 html.md、typescript.md、python.md 等 20 余个片段并列。它不是可执行代码，而是一份结构化的提示词模板，固定包含四个小节：

1. Key Concepts — 该语言的核心概念清单，用于校准 LLM 在生成节点摘要、languageNotes 时的术语与关注点；
2. Notable File Patterns — 值得特别注意的文件命名/路径模式，用于识别文件在项目中承担的角色；
3. Edge Patterns — 该类文件与其他文件之间应产生哪些语义边（related、depends_on 等）；
4. Summary Style — 期望的节点摘要文风示例。

它在流水线中的消费点有明确出处。SKILL.md 的 Phase 4（ARCHITECTURE）规定：

对 Phase 1 检测到的每种语言（例如 python、markdown、dockerfile、yaml、sql、terraform、graphql、protobuf、shell、html、css），读取 ./languages/<language-id>.md（例如 ./languages/python.md）并在基础模板之后以 ## Language Context 标题追加其内容。若某检测到的语言不存在对应文件，则静默跳过。包含非代码语言的片段——它们为提供非代码文件的边模式与摘要风格。

也就是说：只有当 Phase 1 扫描在目标项目中检测到 css 语言时，这份片段才会被加载，并随 architecture-analyzer.md 的基础提示词一起下发给架构分析子代理，影响其对 CSS 文件的层归属判断（例如归入 UI 层还是配置层）与节点摘要生成。

CSS 语言是如何被检测到的

Phase 1 的文件扫描由 scan-project.mjs 完成。其中的扩展名映射表将以下四个扩展名统一归入 css 语言 ID（scan-project.mjs）：

// Markup / docs
'.html': 'html',
'.htm': 'html',
'.css': 'css',
'.scss': 'css',
'.sass': 'css',
'.less': 'css',
'.md': 'markdown',

注意一个值得记录的细节：技能侧的扫描器识别 .css、.scss、.sass、.less 四个扩展名；而 core 包中的语言注册配置 css.ts 仅声明了 [".css", ".scss", ".less"]：

export const cssConfig = {
  id: "css",
  displayName: "CSS",
  extensions: [".css", ".scss", ".less"],
  concepts: ["selectors", "properties", "media queries", "flexbox", "grid", "variables", "animations", "specificity"],
  filePatterns: {
    entryPoints: [],
    barrels: [],
    tests: [],
    config: [],
  },
} satisfies LanguageConfig;

从源码结构看，scan-project.mjs 文件头部的注释（约 L100-L107）明确了两者的关系：core 配置与扫描器约定偶有分歧时，project-scanner 的用户侧契约优先。因此 .sass 文件在技能流水线中同样会被视为 CSS 语言文件，这正是片段中 Key Concepts 覆盖 Sass 特性（@use、@mixin 等）的原因。

core 包侧的语言解析则由 LanguageRegistry 承担：getForFile 先按文件名精确匹配，再回退到扩展名匹配（小写归一化）。CSS 配置中 filePatterns 的四个字段（entryPoints/barrels/tests/config）均为空数组——这与 CSS 作为声明式样式语言的性质一致：它没有"入口文件"或"桶文件"这类编程概念，因此扫描器不会对样式表执行导入图解析，样式表文件间的关系完全依赖本文解析的 Edge Patterns 语义规则来建立。

二、Key Concepts：十个概念如何校准 LLM 对样式文件的理解

片段的第一节列举了十个核心概念。它们并非装饰性清单，而是 Phase 4 注入后 LLM 生成 summary、tags、languageNotes 时的领域知识锚点。逐条展开：

概念	片段原文要点	对图谱产物的影响
Selectors（选择器）	元素、类（.name）、ID（#name）、属性（[attr]）、伪类（:hover）五种定位方式	摘要中识别文件针对的是哪些组件/页面
Specificity（层叠优先级）	内联 > ID > 类 > 元素 的级联优先级决定规则胜负	判断样式文件是否可能"覆盖"其他文件
Box Model（盒模型）	margin、border、padding、content 四维度控制元素尺寸	尺寸/布局类样式的摘要关键词
Flexbox	display: flex 配合 justify-content、align-items 做一维布局	识别一维布局工具类样式
Grid	display: grid 配合 grid-template-columns/rows 做二维布局	识别网格布局（常见于仪表盘类页面）
Custom Properties（自定义属性）	--name: value 定义、var(--name) 引用的可复用设计令牌	这是"设计令牌/变量文件"被独立成节点的关键信号
Media Queries	@media (max-width: ...) 实现响应式断点	摘要中量化断点数量（见 Summary Style 示例"across 3 breakpoints"）
SCSS/Sass 特性	嵌套、$variables、@mixin、@include、@extend、@use、@forward	决定 depends_on 边是否成立（@use 即 import 语义）
CSS Modules	*.module.css 的局部作用域类名，防止全局样式冲突	决定该类文件与组件文件之间 related 边的指向
Cascade Layers	@layer 显式控制级联顺序	识别样式优先级治理文件

这十个概念可以归纳为三类职责：级联与优先级（Specificity、Cascade Layers）、布局体系（Box Model、Flexbox、Grid）、工程化机制（Custom Properties、SCSS 模块系统、CSS Modules）。LLM 在被注入此清单后，对一个 styles/dashboard.module.css 的摘要会更可能落在"CSS Modules 作用域样式，配合 Flexbox/Grid 布局"而非泛泛的"样式文件"。

三、Notable File Patterns：七类文件命名模式的图谱含义

片段第二节列出七种"值得注意的文件模式"。这些模式的作用是让 LLM 在 Phase 2 生成节点摘要、Phase 4 做层归属时，能从文件名本身推断出文件在样式体系中的角色：

模式	含义（片段原文）	推断出的角色
*.css	标准 CSS 样式表	常规样式节点
*.scss / *.sass	Sass/SCSS 预处理器文件	可能含 @use 依赖图，需解析 partial
*.less	Less 预处理器文件	同上（Less 变体）
*.module.css / *.module.scss	CSS Modules（作用域样式）	与具体组件强绑定，摘要应提及所属组件
globals.css / reset.css / normalize.css	全局基础样式	高 fan-in 的"基础设施型"样式节点
tailwind.config.js	Tailwind CSS 配置（虽然是 JS 文件）	原子类工具链的配置节点
variables.scss / _variables.scss	设计令牌定义	被众多样式表 related 引用的中心节点

其中两个模式尤其体现"文件命名即语义"的推断逻辑：

• globals.css / reset.css / normalize.css：这三个固定文件名在约定俗成之外几乎没有歧义——全局基础样式。它们在图谱中通常呈现高入度（很多页面/组件样式受其约束），architecture-analyzer 在 Phase 4 的结构性脚本会计算每个文件的 fan-in/fan-out（见 architecture-analyzer.md 的"Import Adjacency Matrix"要求），而片段提示 LLM 在摘要中显式写出"global base styles"，方便下游层划分把这类文件归入样式/基础设施层。
• _variables.scss 下划线前缀：这是 Sass 的 partial 约定（_ 开头、不单独编译）。片段在 Edge Patterns 中专门为此约定给出了 depends_on 规则（下一节详述），两处内容互为表里：文件模式节负责"认得出"，边模式节负责"连得对"。

四、Edge Patterns：四条语义边规则如何落成知识图谱

第三节是本片段中最具图谱工程价值的部分——它规定了 CSS 相关节点之间应当产生哪些边类型。逐条解析并与 Understand-Anything 的图模式对照：

1. related：CSS 文件与其导入的 HTML/组件文件

CSS 文件 related 于导入其做样式所用的 HTML 或组件文件。

例如 src/components/Header.tsx 中 import './Header.module.css'，则图谱中应存在 file:src/components/Header.module.css —related→ file:src/components/Header.tsx。related 属于 SKILL.md 图模式中的 Semantic（语义）类别，与 similar_to 并列，默认权重 0.5。这条边是"无静态导入可解析"场景下的兜底语义连接——由于 CSS 的 filePatterns 中无 entryPoints/barrels 配置，core 包的导入图解析对样式表返回空数组，这类连接只能由 LLM 依据片段规则补全。

2. depends_on：SCSS partial 与主样式表的编译依赖

SCSS partial 文件（_*.scss）被 @use 它的主样式表 depends_on（依赖）。

方向语义要注意：主样式表依赖 partial，即 styles/_mixins.scss 提供声明，main.scss 通过 @use 'mixins' 消费。depends_on 属于 Dependencies 类别边，约定权重 0.6，高于 related 的 0.5——这与依赖强于泛化关联的语义一致。这条规则让 SCSS 项目的 @use 拓扑（通常是 _partial.scss → main.scss → 构建产物）得以在图谱中还原。

3. related：变量定义文件与所有引用它的样式表

CSS 变量定义文件 related 于所有引用这些变量的样式表。

这对应 Key Concepts 中的 Custom Properties：variables.scss 定义 --color-primary，各页面样式表以 var(--color-primary) 消费。由于 var() 引用在纯文本层面难以通过静态解析穷举，这条规则把"设计令牌 → 消费方"的扇出关系交给 LLM 按语义补全。对使用者而言，这使"改一个设计令牌会影响哪些样式表"这类问题可以在图谱上以邻接查询的方式回答。

4. related：CSS Modules 与导入它的组件文件

CSS Modules related 于导入它的组件文件。

这是规则 1 在 CSS Modules 场景下的特化：*.module.css 的作用域类名保证了"该样式文件只服务该组件"的强绑定，摘要与边都应直指具体组件。

这四条规则共同点：没有任何一条使用 imports 或 calls 这类强静态边，全部落在 related（0.5）与 depends_on（0.6）两个语义权重档上。从源码结构看，这是刻意的——CSS 的依赖链（尤其 var() 与选择器匹配）本质上是运行时级联语义，无法用编译期导入解析表达，于是流水线选择让 LLM 依据片段规则输出语义边，再由 merge-batch-graphs.py 做去重与悬挂边清理（合并脚本会按 (source, target, type) 去重并丢弃指向缺失节点的边）。

五、Summary Style：三条示例摘要体现的写作规范

第四节给出三条示范摘要，它们规定了样式表节点 summary 字段的期望文风——一句话、声明式、包含具体机制与量化细节：

"Global stylesheet defining CSS custom properties for the design system color palette and typography."

"Responsive layout styles with flexbox and grid for the dashboard page across 3 breakpoints."

"SCSS partial defining shared mixins for spacing, shadows, and media query breakpoints."

三条示例恰好各覆盖一节：第一条对应全局变量文件（模式 5 + 规则 3），第二条对应页面级布局样式（Flexbox/Grid + Media Queries 概念，注意 "across 3 breakpoints" 的量化写法），第三条对应 SCSS partial（@use 依赖来源，即规则 2 的供给侧）。这种"一文件一角色、摘要即定位"的风格保证仪表盘上浏览图谱时，节点摘要本身就能回答"这个样式文件是干什么的、管哪些机制"，无需点开源文件。

六、一次完整的 CSS 文件分析链路

把上述证据串起来，一个 styles/main.scss 文件在 /understand 流水线中的完整链路是：

1. Phase 1（SCAN）：scan-project.mjs 的扩展名表把 .scss 归入 css 语言，scan-result.json 中记录该文件的行数、fileCategory 与语言标签；
2. Phase 4（ARCHITECTURE）：SKILL.md 检测到 css 语言后读取 languages/css.md，以 ## Language Context 注入 architecture-analyzer 提示词；LLM 依据 Notable File Patterns 识别该文件是主样式表（而非 partial），依据 Key Concepts 在摘要中提及 Flexbox/Grid/断点等实际机制；
3. 边生成：file-analyzer 在 Phase 2 依据 Edge Patterns 输出 related/depends_on 边，摘要遵循 Summary Style 文风；
4. 合并与校验：merge-batch-graphs 按 (source, target, type) 去重边、丢弃悬挂边；Phase 6 的内联校验脚本（SKILL.md 中的 ua-inline-validate.cjs）检查每个节点具备 id/type/name/summary/tags、每条边两端节点存在、每个文件节点至少属于一个层——片段中 Summary Style 的要求正是"节点必有 summary/tags"这条硬校验在生成侧的预防性约束。

七、适用范围与限制

• 适用前提：该片段仅在目标项目被 Phase 1 检测到 CSS 系文件（.css/.scss/.sass/.less）时才会被加载；纯后端项目不会触发。
• 性质定位：它是 LLM 提示词而非解析器——样式表间的级联关系、var() 消费方集合均依赖 LLM 语义判断，而非确定性静态分析；确定性部分（扩展名识别、@use 之外的导入图）由 core 包与扫描脚本承担，且 core 配置与扫描器在 .sass 支持上的差异以扫描器为准。
• 可对照的兄弟文档：languages/ 目录下 html.md 采用完全相同的四节结构，其 Edge Patterns（HTML depends_on 其 <script>/<link> 引入的资源）与本文的 CSS 规则互补，两者共同覆盖前端文件的语义连接。

综上，css.md 以不到四十行的篇幅完成了三件事：为 LLM 注入 CSS 领域的十个概念锚点、七种文件角色识别规则、四条语义边输出规范，使样式表这类"无导入图可言"的文件也能以带摘要、带语义边、带层归属的节点形式进入 knowledge-graph.json，最终在交互式仪表盘中被搜索、导航与提问。