Understand-Anything HTML 语言上下文提示详解：语义标记、文件模式与知识图谱边如何协同工作
本文解析 Understand-Anything 中 understand-anything-plugin/skills/understand/languages/html.md 这份 HTML 语言上下文提示片段：它是 /understand 技能在架构分析阶段注入给 LLM 的领域先验，规定了 HTML 文件应关注的核心概念、典型文件模式、知识图谱边类型和摘要写作风格。读完本文，你能理解这份提示如何与核心包的 HTML 语言配置、扫描器的扩展名映射共同作用，使 HTML 页面在代码知识图谱中被正确分类、连线并生成可读的节点摘要。
1. 语言上下文提示在 /understand 流水线中的角色
html.md 不是给人阅读的文档，而是一段"提示词片段"（Prompt Snippet）。它的定位可以从 SKILL.md 的 Phase 4（ARCHITECTURE）阶段确认：当架构分析代理的提示模板构建完成后，技能会"为 Phase 1 检测到的每种语言读取 ./languages/<language-id>.md 文件，并将其内容追加到基础模板之后的 ## Language Context 标题之下"，其中明确列举了 html 在受支持语言之列，并强调"包含非代码语言片段——它们为非代码文件提供边模式和摘要风格"（见 SKILL.md）。
这意味着 html.md 中每一节都有明确的功能对应：
- Key Concepts：告诉分析代理"判断一个 HTML 文件时该看什么"；
- Notable File Patterns：帮助识别哪些 HTML 文件扮演入口、模板等角色；
- Edge Patterns：规定 HTML 节点在图谱中应连出哪些类型的边；
- Summary Style：约束最终写进
knowledge-graph.json的节点摘要措辞。
如果某种检测到的语言没有对应片段文件，技能会静默跳过并继续——所以对 HTML 而言，这份片段就是分析代理理解"HTML 文件长什么样、该怎么连线"的唯一结构化先验。
2. Key Concepts：提示为 HTML 文件划定的九类关注点
原文档的 Key Concepts 一节的完整内容如下，逐条展开说明其分析含义：
| 关注点 | 原文档内容 | 对图谱分析的含义 |
|---|---|---|
| 语义元素 | <main>、<nav>、<header>、<footer>、<article>、<section> 用于构建有意义的结构 |
用于判断页面是"结构化文档"还是无语义标签堆砌，影响摘要中对页面角色的描述 |
| 文档结构 | <!DOCTYPE html>、<html>、<head>、<body> 构成页面骨架 |
识别完整的 HTML 文档，而非片段或模板文件 |
| 表单 | <form>、<input>、<select>、<textarea> 用于带验证属性的用户数据采集 |
有表单的页面（登录页、设置页）在摘要中应体现"数据采集"职责 |
| 可访问性 | aria-* 属性、role、alt 文本与语义标记 |
提示代理关注无障碍实现，是摘要中值得点出的质量特征 |
| Meta 标签 | <meta> 用于 viewport、charset、description、Open Graph 与 SEO 元数据 |
SPA 外壳页与营销落地页的区分依据之一 |
| 脚本与样式加载 | <script>、<link>、<style> 引入 JavaScript 与 CSS |
这是 Edge Patterns 中 depends_on 边的来源，见第 4 节 |
| Data 属性 | data-* 自定义属性用于存储元素级数据 |
常见于组件化页面与数据驱动视图，帮助识别"视图壳"型文件 |
| 模板语法 | 框架特定模板语法（Jinja/Django 的 {{ }}、ERB 的 <%= %>） |
用于把"服务端渲染模板"与静态 HTML 区分开 |
| Web Components | <template>、<slot>、Custom Elements 实现封装的可复用组件 |
识别前端组件化 HTML，与框架组件建立 related 关联 |
值得注意的是，这九个关注点与核心包中的 HTML 语言配置在概念上互相呼应。html.ts 中定义的 htmlConfig 的 concepts 字段为：
concepts: ["elements", "attributes", "semantic tags", "forms", "meta tags", "scripts", "stylesheets", "accessibility"],
从源码结构看，concepts 由 LanguageConfigSchema 定义为字符串数组，是语言配置的一部分；提示片段（Markdown 侧）与语言配置（TypeScript 侧）共同构成"同一语言的两份先验"：一份供 LLM 在分析阶段阅读，一份供确定性的文件识别与结构提取阶段使用。
3. Notable File Patterns：HTML 文件的五种典型角色
原文档 Notable File Patterns 一节列出五种模式，逐一结合仓库内事实展开：
3.1 index.html — 应用入口点或 SPA 外壳
原文档描述为 "Application entry point or SPA shell"。这一模式同时被核心包代码确认：html.ts 的 filePatterns.entryPoints 明确配置为 ["index.html"]，即注册表在判定"某文件是语言入口"时，index.html 是 HTML 唯一的入口模式，barrels/tests/config 均为空数组——这与 HTML 没有 barrel 导出、没有测试约定、没有配置文件的语言特性一致。
3.2 *.html / *.htm — 静态 HTML 页面
双扩展名同样在仓库中有一致的映射证据：scan-project.mjs 的扩展名到语言映射表中 .html 与 .htm 都归到 html 语言；而在文件分类维度上，scan-project.mjs 又把 .html 归入 markup 类别。这两张表说明扫描阶段先做"语言识别"、再做"文件类别识别"，而提示片段中的扩展名模式与它们保持同构。
3.3 templates/**/*.html — 服务端模板文件
原文档指出这是 Django、Jinja2、Go templates 的服务端模板目录。这类文件的关键判别特征是第 2 节提到的模板语法（{{ }}、<%= %>）。配合 SKILL.md 中 Phase 4 的"框架附录注入"机制——检测到 Django 等框架时会追加 ./frameworks/<framework-id-lowercase>.md——模板文件还能获得框架级上下文，两者叠加后分析代理才能正确判断"这是一份用模板继承的服务端页面"。
3.4 public/index.html — SPA 根文档
React、Vue 等 SPA 的根文档通常位于 public/ 目录，只包含 viewport meta、样式引入和一个挂载点。这正是原文档 Summary Style 第一条示例描述的场景（见第 6 节）。
3.5 *.ejs / *.hbs / *.pug — 模板引擎文件
这一条把视野从纯 HTML 扩展到其他模板引擎产物。从提示设计角度看，它提醒分析代理：模板文件即使扩展名不是 .html，其"HTML 页面"语义与连线方式应与 HTML 保持一致。
4. Edge Patterns：HTML 节点的四条连边规则
Edge Patterns 是这份片段中操作性最强的部分，它把 HTML 文件的行为翻译为图谱边的规则。原文档四条边模式为：
- HTML 文件通过
<script>与<link>标签depends_on其引入的 JavaScript 与 CSS 文件； - 模板 HTML 文件
depends_on渲染它的服务端代码； - HTML 入口点是构建系统与 Web 服务器的
deploys目标； - HTML 文件与它渲染的组件或路由
related。
这些边类型并非片段自行发明，而是在分析代理的边类型词汇表中有正式定义。file-analyzer.md 将 depends_on 定义为"文件在运行时依赖另一个项目文件（比 imports 更宽——包括动态 require、懒加载）"，方向为 forward、权重 0.6；file-analyzer.md 将 deploys 定义为"基础设施文件构建/部署代码"，方向 forward、权重 0.7。也就是说，html.md 的 Edge Patterns 是用具体文件特征（<script> 标签、构建系统入口）去实例化这套通用边词汇表。
从源码结构看，HTML 在确定性的结构提取阶段没有专门的解析器：extract-structure.mjs 注册的是 tree-sitter 插件加非代码解析器（dockerfile、env、graphql、json、makefile、markdown、protobuf、shell、sql、terraform、toml、yaml），plugins/parsers/ 目录下没有 HTML 解析器，HTML 也没有配置 tree-sitter 语法。可以推断：HTML 文件的标签级结构（谁引入谁）主要依赖 LLM 分析阶段结合这份提示片段来完成连边，而不是由确定性脚本产出——这正是 Edge Patterns 一节存在价值最大的地方，它承担了"确定性解析缺位"时的连线先验。
第 1 条规则（<script>/<link> → depends_on）还依赖另一个确定性环节：extract-import-map.mjs 生成的 import map 会作为跨批次边验证的输入传给组装评审代理（见 SKILL.md 中 "Import map for cross-batch edge verification" 的派发模板）。当 HTML 引用的 JS/CSS 分属不同分析批次时，这条 import map 是防止跨批 depends_on 边丢失的兜底证据。
5. 语言如何被检测到：从扩展名映射到注册表
提示片段被注入的前提是"Phase 1 检测到了 html 语言"。这条检测链在仓库中是确定的：
- 扫描阶段：scan-project.mjs 将
.html/.htm映射为语言html； - 注册表阶段：核心包的 LanguageRegistry 的
getForFile()先按文件名精确匹配、再按扩展名回退查找。由于 htmlConfig 声明的extensions: [".html", ".htm"]且没有filenames字段，任何以这两个扩展名结尾的文件都会命中 HTML 配置； - 注入阶段：SKILL.md Phase 4 按检测到的语言 id 读取
./languages/html.md并追加进提示。
三处对"html"的命名完全一致（语言 id html、片段文件名 html.md、配置 id: "html"），这是提示片段能被静默发现（file does not exist 时才跳过）的命名契约。
6. Summary Style：节点摘要的三条风格样例
原文档 Summary Style 一节给出三条引用样例，它们约束了写入 knowledge-graph.json 的 HTML 节点摘要写法：
"Single-page application shell with viewport meta, CSS reset, and React root mount point."
"Server-rendered template with navigation, content area, and footer using Django template inheritance."
"Static landing page with responsive layout, form, and third-party script integrations."
三条样例分别对应第 3 节的三种典型角色：SPA 外壳（public/index.html）、服务端模板（templates/**/*.html）、静态落地页（*.html）。它们的共同写法特征是：
- 单句、无主语堆砌：直接以"页面角色 + 关键元素"成句；
- 点出可验证的技术特征：viewport meta、CSS reset、模板继承、第三方脚本——而不是泛泛说"一个网页"；
- 与 Notable File Patterns 的角色一一对应：摘要风格与文件模式互相印证，让下游（架构分层、搜索、问答）能仅凭摘要区分三类 HTML。
这套风格不是孤立的 HTML 约定。从源码结构看，--language <lang> 参数还会把 locales/ 下的语言指引（如 zh.md）注入提示，规定不同输出语言下摘要风格与标签命名习惯（见 SKILL.md 的 Output locale injection），因此这三条英文样例同时充当了"摘要信息密度"的基线参照。
7. 实操路径：在真实项目中观察 HTML 上下文生效
要在自己项目中验证这份片段的实际效果，适用前提与步骤如下：
- 环境前提：需要 Node.js ≥ 22 与 pnpm ≥ 10（SKILL.md 在 pnpm 缺失时给出的报错提示），且插件已构建出
packages/core/dist/； - 运行分析：在含 HTML 文件的项目中执行
/understand。若项目含 React/Vue 的public/index.html或 Django 的templates/，Phase 1 会检测到html（以及可能的框架），Phase 4 构建架构提示时自动追加本文分析的片段内容； - 验证产物：分析完成后，项目数据目录
.ua/（已存在.understand-anything/的项目沿用旧目录）中的knowledge-graph.json里，HTML 节点应具备：摘要符合第 6 节风格、depends_on边指向其引入的 JS/CSS、入口 HTML 与构建/部署文件之间存在deploys边。
若某次分析后 HTML 节点的摘要明显不符上述风格（例如只写"HTML file"），可以从两个方向排查：检测阶段是否遗漏了 html 语言（对照 scan-project 的扩展名映射），以及架构阶段提示是否包含了 ## Language Context 段——前者由确定性脚本保证，后者由 SKILL.md 的注入步骤保证。
8. 小结
html.md 用不到 40 行完成了三件事：为 HTML 文件定义九个分析关注点（Key Concepts）、五种角色判定（Notable File Patterns）和四条连边规则（Edge Patterns），并用三条样例锚定摘要风格。它不产出任何确定性的结构数据——HTML 的确定性侧由 html.ts 的扩展名与入口配置、scan-project.mjs 的语言/类别映射、LanguageRegistry 的文件识别共同承担；片段的价值在于把这些确定性事实"翻译"成 LLM 在架构分析与摘要生成阶段可以直接执行的先验，使 HTML 页面在知识图谱中既有正确的边，又有可被检索和问答利用的摘要。
相关内容推荐
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0626
Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。Python00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比，它在复杂编程和长程任务上的表现显著提升。Jinja00- GLM-5.3-FlashGLM-5.3-Flash (320B-A18B)，是GLM-5系列的首个原生多模态模型。320B总参数，能力超过GLM-5.2Jinja00
Spark-X2.5-4BSpark-X2.5-4B 旨在让强大的 AI 更实用、更高效、更易获得。在广泛日常任务中表现强劲，涵盖对话、写作、翻译、推理、编码、工具调用以及智能体工作流，并在同等规模的开源模型中取得领先成绩。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00- Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色，涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流，并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00
热门内容推荐
最新内容推荐
项目优选
kernel
pytorch
kernel
leetcode
ops-transformer
docs
jiuwenswarmcann-learning-hubops-nn
openGauss-server