Understand-Anything 多语言知识图谱内容规范：详解英文输出指南 locales/en.md 的标签、摘要与层级命名约定

在 Understand-Anything 中，一个可交互的知识图谱由节点摘要（summary）、标签（tags）、层级名称（layer name）、导览步骤（tour step）等大量"文本化内容"构成。这些内容是否统一、规范，直接决定了图谱在 dashboard 可视化面板 中能否被顺畅浏览与检索。locales/en.md 正是这套体系在**英文（默认输出语言）**下的内容规范文件，它规定了标签命名、摘要写法、术语保留策略与层级命名规则。读完本文，你将理解这份规范被加载与生效的机制、每条规则的实践含义，以及如何与 zh.md、ja.md、ko.md 等其他语言文件协同，从而正确产出或评审多语言知识图谱内容。

一、locales 目录在整条流水线中的位置

1.1 规范文件是"内容生成代理"的输出准绳

Understand-Anything 的 /understand 技能把代码库分析拆成 7 个阶段（Phase 0～7），其中 Phase 1 SCAN、Phase 2 ANALYZE、Phase 4 ARCHITECTURE、Phase 5 TOUR 会分别派遣多个子代理，由它们撰写节点摘要、标签、层级定义与导览步骤。这些文本写入最终的 knowledge-graph.json，再驱动 dashboard 展示。

[locales/ 目录](https://gitcode.com/GitHub_Trending/un/Understand-Anything/blob/ba450c43425f3de6d43daf76526950ad8ca93536/understand-anything-plugin/skills/understand/locales?utm_source=gitcode_repo_files) 就存放各语言的"输出规范"，与 languages/（各语言的代码结构模式）和 frameworks/（框架模式）并列，位于 SKILL.md 的兄弟目录下。目前仓库中提供 7 份语言规范：

• en.md — 英文（默认，本次重点）
• zh.md（简体中文）、zh-TW.md（繁体中文）
• ja.md（日语）、ko.md（韩语）、ru.md（俄语）

所有语言文件共享完全一致的四段式骨架：Tag Conventions（标签约定）→ Summary Style（摘要风格）→ Technical Terms（技术术语）→ Layer Names（层级名称），这是可以逐文件对比验证的结构事实。

1.2 en.md 何时被"消费"：Phase 4 的语言注入机制

从 SKILL.md 的 Phase 4 可以看到精确的加载逻辑：

Output locale injection: If $OUTPUT_LANGUAGE is NOT en (English), read the locale guidance file at ./locales/<language-code>.md（如 ./locales/zh.md、./locales/ja.md、./locales/ko.md）and append its content after the framework addendums under a ## Output Language Guidelines header.

也就是说：当输出语言不是英文时，对应语言的规范文件会以 ## Output Language Guidelines 小节追加进 architecture-analyzer 的提示词中，为层级 name/description 的翻译与本地化提供依据（详见 architecture-analyzer.md 中关于 language directive 的段落）。若某语言没有对应 locale 文件，流水线会静默跳过，此时通用的 $LANGUAGE_DIRECTIVE（语言指令模板）仍然生效。

需要准确理解 en.md 的特殊地位：它定义了英文这一默认输出语言下的行为基线。SKILL 中所有内容生成代理在默认场景（未指定 --language、配置文件也未记录 outputLanguage）下都以英文产出，其质量标准与 en.md 一致；同时，en.md 的章节结构也是其余 6 个语言文件共同镜像的"母版"。当输出英文时，代理依靠内嵌的英文生成指令即可，其他语言文件则被显式注入以约束翻译行为。

二、Tag Conventions：标签约定（英文的核心规则）

en.md 规定英文标签一律采用小写加连字符形式（lowercase, hyphenated tags），并按文件职责归纳为 8 类常见模式。这张表是全文最具可操作性的部分，完整继承如下：

Pattern（模式）	Recommended Tags（推荐标签）
Entry point file（入口文件）	entry-point, barrel, exports
Utility functions（工具函数）	utility, helpers, common
API handlers（API 处理器）	api-handler, controller, endpoint
Data models（数据模型）	data-model, entity, schema
Test files（测试文件）	test, spec, unit-test
Configuration（配置）	configuration, build-system, settings
Infrastructure（基础设施）	infrastructure, deployment, containerization
Documentation（文档）	documentation, guide, reference

2.1 标签为什么重要：它落在图模型的哪个字段

标签不是可有可无的元信息。在核心包的数据类型定义 packages/core/src/types.ts 中，GraphNode 显式声明了：

export interface GraphNode {
  id: string;
  type: NodeType;
  name: string;
  filePath?: string;
  summary: string;
  tags: string[];
  complexity: "simple" | "moderate" | "complex";
  languageNotes?: string;
  ...
}

tags: string[] 是节点的必填字段之一，这与 Phase 6 的内联校验脚本 相呼应——校验器会检查每个节点 !n.tags || !n.tags.length 并记为 issue。换句话说，标签缺失会被当作图谱质量问题；规范化的标签词汇表（api-handler、configuration、documentation…）既保证了节点可被 dashboard 按职责类型过滤，也为跨项目的一致性检索提供了稳定的取值空间。

2.2 使用建议

• 优先从 8 类模式中选取最贴切的标签；同一模式内可再细分，例如 entry point 既可用宽泛的 entry-point，也可用体现"聚集再导出"语义的 barrel。
• 标签不追求描述性长句，它是机器消费为主的枚举型词汇；真正承担"人读"职责的是 summary。
• 对非代码文件（配置文件、文档、CI/CD、基础设施），同样有对应的推荐词（configuration、documentation、deployment、containerization），这与图谱中 config/document/pipeline/service 等节点类型（见 SKILL.md 节点类型表）互相配合：type 决定"它是什么"，tags 决定"它承担什么职责"。

三、Summary Style：摘要写作风格

摘要（summary）是用户在 dashboard 中阅读节点时最先接触的文本，en.md 为其制定了三条硬规则：

1. 写 1～2 句话，说明该文件的用途（purpose）与在项目中的角色（role）；
2. 使用主动语态，动词开头（"Provides…", "Handles…", "Manages…"）；
3. 避免复述文件名——不要把 "The utils file contains utility functions" 这类废话当作摘要。

规范给出了一组正反对照：

• ✅ Good: "Provides date formatting and string sanitization helpers used across the API layer."
• ❌ Bad: "The utils file contains utility functions."

这组规则的深层动机可以从图模型的约束反推：在 Phase 6 内联校验 中 summary 同样属于必填字段（缺失即 issue）。要让几百个节点的图谱"一瞥即懂"，摘要必须信息密度高、句式统一，主动语态恰好能迫使作者交代文件的对外职责，而不是复述显而易见的文件名。

实践要点：摘要应回答"这个文件为系统提供什么、被谁使用"，一句话讲清用途、必要时第二句话补充关键消费方或约束；避免以文件名为句子主语堆砌同义反复。

四、Technical Terms：技术术语的保留清单

为了在英文语境下保证术语精度，en.md 明确列出以下术语不做任何翻译、直接保留英文（no translation needed）：

• middleware, hook, barrel, entry-point
• ORM, REST API, CI/CD, CRUD
• singleton, factory, observer
• middleware, interceptor, guard

注意清单里 middleware 出现两次——这并非笔误，而是体现该词在架构模式（Phase 4 判断目录归属时的 middleware 分组）与通用术语两个维度都高频出现，规则制定者希望强制保持其原样。barrel、entry-point、hook 则直接对应代码生态中的既有概念（JS/TS 的 barrel 导出文件、Git hook、框架 hook），一旦本地化反而会增加理解成本。

这条规则在多语言输出时尤为重要：语言指令模板（$LANGUAGE_DIRECTIVE）同样声明"Keep technical terms in English when no standard translation exists"，en.md 清单正是这句指令在英文侧的具体化。以中文输出为例，zh.md 采用了"混合策略"：通用技术术语保留英文，描述性标签使用中文——例如 API 处理器推荐 api-handler、控制器、端点 三选一。

五、Layer Names：层级命名

层级（Layer）是知识图谱四大组成（nodes / edges / layers / tour）之一。在 packages/core/src/types.ts 中每个 Layer 需携带 id、name、description、nodeIds 四个字段，其中 name/description 是需要按输出语言本地化的文本。en.md 给出英文标准层级名：

• API Layer, Service Layer, Data Layer, UI Layer
• Infrastructure, Configuration, Documentation
• Utility Layer, Middleware Layer, Test Layer

这套命名与 architecture-analyzer.md 的产出约定一致（layer:api、layer:service、layer:data 等 kebab-case ID 对应的正是这些人类可读名称），也与 架构分析的结构模式表 中 api/service/data/ui/middleware/utility 等目录分组标签一一对应。也就是说：分组标签 → layer ID → layer 显示名是一条贯通的可追溯链。

六、横向对照：非英文 locale 如何处理同一套规则

en.md 的规则体系并非英文独享，其余 6 个语言文件在相同骨架下做了本地化适配，可逐份对比（locales 目录）：

维度	英文 en.md	简体中文 zh.md 示例	日语 ja.md 示例
标签语言	纯英文小写连字符	中文或英文混用	日文汉字或英文
推荐标签示例	entry-point	入口点, barrel, 导出	入口点, barrel, exports
摘要句式	主动语态英文	"提供…、处理…、管理…"	「提供する…」「処理する…」
层级名	API Layer	API 层, 服务层, 数据层	API層, サービス層, データ層

所有语言文件都反复强调同一条混合策略：没有标准译法的通用术语一律保留英文。例如 zh.md 列出 middleware、hook、barrel、entry-point、ORM、REST API、CI/CD、CRUD、singleton、factory、observer、interceptor、guard；ko.md、ru.md、zh-TW.md 也各自给出等价清单。这保证了无论输出语言如何切换，图谱中的关键技术概念始终指向同一含义，dashboard 检索与跨语言阅读不会因术语漂移而失准。

ru.md 还示范了标签的字母化处理（如 точка-входа、модель-данных、контейнеризация），说明标签语言可以跟随输出语言本地化，但技术标记（middleware、api-handler）仍保持英文原形。

七、输出语言如何被选中：en.md 生效的上游链路

要理解 en.md 规范在什么条件下成为"默认基线"，需要了解 /understand 的语言解析链路（对应 SKILL.md 步骤 3.6）：

1. --language <lang> 显式指定：接受 ISO 639-1 代码（zh、ja、ko、en…）或友好名（chinese、japanese…），支持 zh-TW、zh-HK 等区域变体；解析结果写入 $UA_DIR/config.json 的 outputLanguage 字段，保证增量更新时语言一致。
2. 无参数时读取存储偏好：config.json 中已有 outputLanguage 则直接采用，不再询问。
3. 首次运行自动检测：从用户对话推断主要语言；若为英文或无法置信判定，则静默回落到 en 并持久化——这保证了英文用户（核心受众）零打扰；若非英文，会先与用户确认一次再开始分析（详见设计文档 2026-06-03-language-auto-detection-design.md）。

关键事实：配置模型中确实存在该字段——packages/core/src/types.ts 的 ProjectConfig 声明了 autoUpdate: boolean 与可选 outputLanguage?: string。设计文档还指出，自动检测门控"每个项目最多触发一次"，因为解析结果一旦确定就会写入 config.json，后续运行直接命中第 2 步的存储偏好。

选定语言后，Phase 4 再依据 1.2 节的规则注入对应 locale 文件（非英文时），让 architecture-analyzer 用本地化语言书写层级 name/description。可见：语言选择链路决定 $OUTPUT_LANGUAGE，$OUTPUT_LANGUAGE 决定注入哪份 locale 规范，而英文默认行为始终以 en.md 规则为基线。

八、en.md 的实际应用场景与自查清单

8.1 适用场景

• 用户运行 /understand 且不指定 --language、项目无历史偏好时——图谱全部文本（节点摘要、标签、层级名、导览标题与描述、languageNotes、languageLesson）以英文产出，需符合 en.md 规范。
• 在 --language en 显式指定、或对话检测结果为英文时，同样适用。
• 维护 dashboard 英文界面的团队如需评审或人工补写图谱文本，en.md 是可直接引用的校对基准。

8.2 英文内容生成自查清单

依据 en.md 全文可提炼如下 checklist，供内容生成代理或人工审查使用：

• 标签：是否全部为小写连字符形式？是否落在 8 类模式对应的推荐取值内（api-handler / configuration / test …）？是否避免了大写、空格与自由发明？
• 摘要：是否 1～2 句？是否描述了 purpose 与 role？是否以 "Provides… / Handles… / Manages…" 式主动语态行文？是否把文件名换了个说法复述了一遍（应避免）？
• 术语：middleware、hook、barrel、entry-point、ORM、REST API、CI/CD、CRUD、singleton、factory、observer、interceptor、guard 是否保持英文原样？
• 层级名：是否采用标准英文名称（API Layer、Service Layer、Data Layer、UI Layer、Infrastructure、Configuration、Documentation、Utility Layer、Middleware Layer、Test Layer）？

8.3 如何核对产出是否正确落地

图谱产出后存放在项目数据目录 $UA_DIR/knowledge-graph.json（.ua/ 或历史遗留的 .understand-anything/）。可在其中核对：每个节点的 summary/tags 是否语言一致、是否符合规范；layers[].name 与 layers[].description 是否使用了标准层级命名；tour[].title/description/languageLesson 是否同语言。若发现语言混杂或术语被误译，可回到 SKILL.md 的语言指令模板 检查语言选择，或在下次运行时显式指定 --language en 重新生成。

九、延伸阅读：仓库内相关实现索引

若要继续深入这套语言规范体系的实现与测试，建议按以下路径阅读（均从仓库根目录出发）：

• 规范文件本身：locales/en.md 及其姊妹文件 zh.md、ja.md、ko.md、ru.md、zh-TW.md。
• 加载与注入逻辑：SKILL.md Phase 4 与语言解析步骤 3.6。
• 内容消费方的语言指令段：architecture-analyzer.md，其 Phase 2 要求把层级 name/description 按目标语言书写。
• 图模型字段定义：packages/core/src/types.ts（GraphNode.summary/tags、Layer.name/description、TourStep.languageLesson）与 ProjectConfig.outputLanguage。
• 多语言/自动检测背景：2026-06-03-language-auto-detection-design.md。

综上，locales/en.md 虽然只是一份结构精炼的规范文件，却在 Understand-Anything 的"代码 → 可探索知识图谱"流水线中承担着承上启下的作用：向上承接语言解析链路的默认设定，向下约束 Phase 2/4/5 各代理产出的文本质量，横向又为其余 6 种语言的本地化提供了统一母版。理解它，就理解了 Understand-Anything 多语言内容体系的最小完备单元。