Understand-Anything 中文输出指南：为知识图谱生成高质量简体中文本地化内容

在把任意代码库转化为交互式知识图谱时，Understand-Anything 的全部文本产物——节点摘要、标签、层级名称、语言课（language lesson）——都交由 LLM 生成。若仅用一句"请用中文输出"的提示，往往得不到稳定的中文质量：标签中英文混杂、摘要平淡且反复复述文件名、层级名称时中时英。本指南讲解的正是插件内置的简体中文输出规范文档 locales/zh.md，它定义了标签约定、摘要风格、术语保留与层级命名规则，配合 --language zh 命令行选项，即可让整个图谱以自然、专业、符合开发者阅读习惯的简体中文呈现。阅读本文后，你将掌握 zh 语言指南的全部细则、它如何与七阶段分析流水线配合生效，以及从源码层面理解这一本地化机制的实现原理。

一、本地化文件在何处、何时被使用

该指南文件位于知识图谱技能的语言目录下：

understand-anything-plugin/skills/understand/locales/
├── en.md       # 英文输出指南
├── ja.md       # 日文输出指南
├── ko.md       # 韩文输出指南
├── ru.md       # 俄文输出指南
├── zh.md       # 简体中文输出指南（本文主体）
└── zh-TW.md    # 繁体中文输出指南

从目录结构与 SKILL.md 第 3.6 节 可以看到，这些语言文件只在生成非英文内容时才被读取：当输出语言 $OUTPUT_LANGUAGE 不是 en 时，SKILL.md 第 424 行 会在 Phase 4（架构分析）构造提示词时，把 ./locales/<language-code>.md（如 ./locales/zh.md）的内容附加到 agent 提示模板末尾的 ## Output Language Guidelines 标题之下。换言之，zh.md 不是一段供人阅读的说明，而是直接注入 LLM 提示词的规范片段。

需要说明的是：zh.md 只在输出语言设定为简体中文（zh，或 zh-CN 变体）时被注入；若输出为繁体中文（zh-TW），则注入的是 locales/zh-TW.md。若该语言文件不存在，流水线会静默跳过文件注入，仅靠通用的 $LANGUAGE_DIRECTIVE 指令兜底。

二、标签约定：中英搭配的分类词表

zh.md 首先给出了一套针对不同文件模式的推荐标签，这是决定知识图谱节点在 Dashboard 中能否被快速检索和聚合的基础。原文词表如下：

模式	推荐标签
入口文件	入口点, barrel, 导出 或 entry-point
工具函数	工具函数, helpers, common 或 utility
API处理器	api-handler, 控制器, 端点
数据模型	数据模型, entity, schema 或 data-model
测试文件	测试, 单元测试, test
配置文件	配置, 构建系统, settings 或 configuration
基础设施	基础设施, 部署, 容器化 或 infrastructure
文档	文档, 指南, 参考 或 documentation

每个模式给出多个候选，暗示"首选中文、必要时英文"的倾向。其中 entry-point、api-handler、data-model、infrastructure 这类带连字符的小写标签，与 locales/en.md 中推荐的英文标签风格完全一致，方便跨语言场景下保持一致的可检索性。

三、混合策略：技术词汇保留英文

zh.md 明确推荐一种混合策略：

通用技术术语保留英文（如 middleware, api-handler），描述性标签可使用中文。

这背后的工程原因是：标签（tags）是图谱节点上的结构化元数据，会被 search.ts 与 embedding-search.ts 用于语义检索。全中文直译 middleware 为"中间件"虽易读，却会丢失与英文源码术语的对应关系，降低检索命中率；而"描述性标签使用中文"则保证图谱浏览者对节点的第一印象是母语友好的。类似地，zh.md 列举了建议保留英文的技术术语白名单：

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

其中 ORM、REST API、CI/CD、CRUD 属于在中文技术社区中几乎不存在歧义的标准缩写，保留原样反而比生硬翻译（如"对象关系映射"）更符合中文开发者的阅读习惯。这套术语策略同时复现在 locales/zh-TW.md 的繁体版中（措辞为"通用技術術語保留英文"），说明它是整个中文语系输出的统一原则。

四、摘要风格：一句话说清"目的与作用"

zh.md 对每个节点的摘要（summary）写作提出了三条规范：

• 用中文撰写 1-2 句摘要；
• 描述文件的目的和作用；
• 使用主动语态（"提供…"、"处理…"、"管理…"）；
• 避免重复文件名。

并给出正反示例：

• 好："提供日期格式化和字符串清洗工具函数，被 API 层广泛使用。"
• 差："utils 文件包含工具函数。"

坏例子的典型问题正是复述文件名（utils）并用空洞的"包含"句式，既没有说明文件具体做什么，也没有点明其在项目中的位置。从数据模型看，types.ts 第 60 行 中 GraphNode.summary 是节点必需的字符串字段，同时这条规范也约束了 locales/zh.md 自身所称的"目的与作用"语义——这正是 Dashboard 的文件列表、搜索结果与学习面板中呈现给用户的默认文本。

五、层级名称：架构图层的中文命名

知识图谱的核心产物之一是 layers（架构分层）。zh.md 建议使用中文层级名称：

• API 层, 服务层, 数据层, UI 层
• 基础设施, 配置, 文档
• 工具层, 中间件层, 测试层

同时也允许按团队习惯保留英文（API Layer, Service Layer, Data Layer）。这套名称会直接写入最终知识图谱的 layers 数组。对照 types.ts 第 80-85 行 中 Layer 接口（id、name、description、nodeIds），Phase 4 架构分析要求每个 layer 必须有名称与描述，因此当使用中文输出时，API 层 这类中文名就是 name 字段的最终取值。值得注意：推荐的中文层级名采用 "API 层"（中文词 + 英文缩写 + 层）而非纯音译，与前述"通用技术术语保留英文"的混合策略一脉相承。

六、中文规范如何与语言选择流程联动

阅读 zh.md 时，容易忽略一个前提：它只有在用户请求中文输出时才会生效。完整链路在 SKILL.md Phase 0 第 3.6 节 定义，理解它才能正确使用 zh 指南：

1. 显式指定：执行 /understand --language zh（接受 ISO 639-1 代码，也接受 chinese 等友好名称），解析后把 {"outputLanguage": "zh"} 合并写入 $UA_DIR/config.json。
2. 存储偏好优先：若未传 --language，但 config.json 已存在 outputLanguage 字段，则直接采用，不再提示。
3. 首次自动检测：首次运行且无偏好时，推断会话主导语言；若判定非 en（如中文会话），会先向用户确认一次是否用该语言生成全部内容，确认后把结果持久化到 config.json，保证同一项目后续增量更新语言一致。
4. 指令模板：无论走哪条路径，最终都会生成一段 $LANGUAGE_DIRECTIVE，要求 summaries、descriptions、tags、titles、languageNotes、languageLesson 全部以目标语言产出——zh.md 的注入正是让这段宏观指令落到中文本地化细节上。

语言偏好被存进 types.ts 第 132-136 行 定义的 ProjectConfig.outputLanguage 字段，由 persistence 模块读写。这也是为什么同一个项目的增量更新不会在中英文之间反复横跳。

七、源码佐证：中文规范影响的字段与生成逻辑

zh.md 中的规则最终体现为知识图谱中三类文本字段，均可从源码中核实：

1. 节点摘要与标签（summary / tags / languageNotes） languageNotes 是 types.ts 第 63 行 中 GraphNode 的可选字段，用于记录该节点使用的语言特性（如 async/await、装饰器）。当以 zh 输出时，中文摘要与中文标签共同构成检索文本。搜索模块（search.ts、embedding-search.ts）会把 tags 与 summary 纳入匹配范围，因此 zh.md 对"描述性标签用中文、技术术语留英文"的折中，实际是在检索鲁棒性与可读性之间做平衡。

2. 语言课内容（languageLesson / concepts） 图谱的 tour 步骤可以携带一段语言课，向开发者讲解代码中的语言概念。analyzer/language-lesson.ts 是该机制的实现：detectLanguageConcepts()（第 69-93 行）基于节点 tags、summary、languageNotes 联合检测 12 个跨语言基础概念（async/await、middleware pattern、generics、decorators、dependency injection、observer pattern、singleton、type guards、higher-order functions、error handling、streams、concurrency），再叠加各语言配置中的专属概念；随后 buildLanguageLessonPrompt()（第 112-155 行）把这些概念连同节点关系列表交给 LLM，要求返回 JSON 格式的 languageNotes 与 concepts 解释。当输出语言为中文时，locales/zh.md 注入的摘要与术语规范会引导这段讲解以简体中文撰写。 Dashboard 中的 LearnPanel.tsx 与 NodeInfo.tsx 会渲染这些字段，供用户在浏览图谱时即时学习。

3. 生成入口的统一约束 此外，tour-generator.ts、llm-analyzer.ts 等生成器在产出 tour 与节点元数据时都会收到 $LANGUAGE_DIRECTIVE；zh.md 作为 Output Language Guidelines 被注入到 Phase 4 architecture-analyzer 的提示中，主要负责规范图层命名与描述的翻译口径（见第五节），而面向 file-analyzer / tour-builder 的语言约束则由同一份 $LANGUAGE_DIRECTIVE 承担。

八、简体中文 vs 繁体中文的差异

若读者面向港台地区用户，注意 zh-TW 有独立的 locales/zh-TW.md。它与简体版规则结构完全一致（标签约定表、混合策略、主动语态摘要、层级名称），但全部使用繁体措辞，例如：

• 标签示例为 入口點、匯出、資料模型、設定、檔案、單元測試、建構系統；
• 层级名使用 檔案層級 语义对应的"API 層, 服務層, 資料層, UI 層"（该文件保留 API 層/UI 層 混合写法）；
• 术语白名单与简体版相同（middleware, hook, barrel, entry-point 等）。

SKILL.md 明确指出 --language 支持 zh-TW、zh-HK、zh-CN 等区域变体并原样保留，因此繁体内容请使用 --language zh-TW 触发，而不是 zh。同样地，zh 与其子变体 zh-CN 之间目前共用简体指南（仓库未为 zh-CN 提供单独文件，系统会静默跳过不存在的 locale 文件，仅以语言指令模板兜底）。

九、给插件用户与图谱内容作者的实用建议

综合 zh.md 规则与实现机制，使用简体中文图谱时可遵循以下要点：

1. 触发方式：对目标代码库执行 understand <path> --language zh；或在首次运行自动检测到中文会话时直接确认。语言偏好会持久化到项目的 $UA_DIR/config.json（.ua/ 或旧版 .understand-anything/），无需每次重复传参。
2. 标签落地：入口文件优先取 入口点 或 entry-point，测试文件取 测试 或 单元测试，配置取 配置 或 configuration；middleware、REST API、hook 等术语一律保留英文，不要强行直译。
3. 摘要落地：坚持"目的 + 作用 + 主动语态 + 不复述文件名"的四要素模板。例如对一个 Express 中间件文件，可写"提供请求日志记录与错误拦截的中间件，挂在 API 层路由之前"，而非"这个文件是 middleware 文件"。
4. 层级落地：架构分层建议使用 API 层、服务层、数据层、基础设施、文档、工具层、测试层 等中文名，保持图谱纵向结构的一目了然。
5. 一致性验证：增量更新场景下，config.json 中持久化的 outputLanguage: "zh" 保证后续 /understand 运行沿用同一语言；若发现图谱内容语言错乱，检查 $UA_DIR/config.json 中是否存在旧的 outputLanguage 值，或改用 --language zh 显式覆盖。

小结

locales/zh.md 虽只是一份不到 50 行的规范文件，却在 Understand-Anything 的本地化机制中扮演"简体中文质量守门员"的角色：它定义了节点的标签词表与中英混合策略、主动语态的摘要写法、技术术语保留清单和架构层级的中文命名。配合 SKILL.md 的语言解析与持久化逻辑（--language zh / config.json 中的 outputLanguage）、Phase 4 的 Output Language Guidelines 注入，以及 core 包中 summary/languageNotes/concepts 等字段的实际生成链路，最终让"教你的代码"的交互式知识图谱真正以简体中文母语级质量呈现在开发者面前。