Understand-Anything 俄语知识图谱输出指南详解：locales/ru.md 如何驱动 --language ru 的原生化图谱内容

本文以 understand-anything-plugin/skills/understand/locales/ru.md 为核心，讲清 Understand-Anything 的 /understand 技能在生成俄语知识图谱内容时所遵循的完整约定：标签命名策略、摘要风格、技术术语保留规则与层级名称规范，并结合技能主流程 SKILL.md、各分析子代理定义与持久化代码，说明这份指南在七阶段分析管线中被加载、注入与落地的全链路。读完本文，你能独立使用 --language ru 生成俄语知识图谱，并理解每条语言约定背后的实现机制与回退行为。

一、ru.md 是什么：面向俄语输出的语言指导文件

ru.md 的开头自我定位非常明确——“本文件包含生成俄语知识图谱内容的语言建议”（Руководство по выводу на русском языке）。它不是一个独立功能模块，而是 Understand-Anything 多语言输出体系的俄语指导文件，与同一目录下的 en.md、zh.md、zh-TW.md、ja.md、ko.md 并列，共同构成 locales/ 子目录。

按照 README 的说明，/understand --language <lang> 支持的语言清单为 en（默认）、zh、zh-TW、ja、ko、ru，俄语是官方支持的目标输出语言之一。ru.md 中的每一条约定，最终都会作用到知识图谱 JSON（.ua/knowledge-graph.json）里的文本字段：节点 summary、tags、层级 name/description、导览 tour 的 title/description、项目描述以及 languageLesson 等。

二、标签约定（Соглашения по тегам）：完整策略表

ru.md 的第一部分规定：图谱节点标签使用俄语标签或通用的英文技术术语，并给出了八类文件的推荐标签对照表。这张表必须完整理解，因为它是 file-analyzer 子代理打标签的直接依据：

模式（Шаблон）	推荐标签
入口文件（Точка входа）	точка-входа、barrel、exports 或 entry-point
工具函数（Утилитарные функции）	утилиты、helpers、common 或 utility
API 处理器（API-обработчики）	api-handler、контроллер、endpoint
数据模型（Модели данных）	модель-данных、entity、schema 或 data-model
测试文件（Тестовые файлы）	тесты、unit-test、test
配置文件（Конфигурационные файлы）	конфигурация、build-system、settings 或 configuration
基础设施（Инфраструктура）	инфраструктура、deployment、контейнеризация 或 infrastructure
文档（Документация）	документация、руководство、documentation

表中体现的是 ru.md 明确声明的混合策略（Смешанная стратегия）：

• 通用技术术语保留英文，例如 middleware、api-handler——这些词在俄语开发社区没有被广泛接受的翻译，强行翻译反而降低检索性；
• 描述性标签可以写俄语，例如 точка-входа、утилиты、конфигурация。

这一混合策略并非俄语独有。对比同目录的 zh.md 和 ja.md 可以看到，中文、日语指南的结构与策略完全同构（同样的八行标签表、同样的“混合策略”段落），只是具体词条不同。这说明 ru.md 是 Understand-Anything 统一的多语言模板族的一员，而非孤立文件。

三、摘要风格（Стиль резюме）：目的、角色与主动语态

ru.md 第二部分规定摘要（summary）的写作方式：用俄语写 1–2 句话，并遵守三条规则：

1. 描述文件的目的（назначение）和角色（роль），而不是罗列文件内容；
2. 使用主动语态（“предоставляет…”提供…、“обрабатывает…”处理…、“управляет…”管理…）；
3. 避免重复文件名。

原文档给出了对照示例，值得逐字掌握：

• ✅ 好：«Предоставляет вспомогательные функции для форматирования дат и очистки строк, широко используемые на API-слое.» （提供日期格式化与字符串清洗的辅助函数，被 API 层广泛使用。）
• ❌ 差：«Файл utils содержит утилитарные функции.» （utils 文件包含工具函数。）

差例的问题有三：重复文件名、被动/静态描述（“содержит”包含）、没有说清楚“给谁用、用来做什么”。这个好/坏对照实际上定义了 Understand-Anything 对知识图谱节点 summary 的通用质量标准——summary 是“这个文件是干什么的”，而不是“这个文件里有什么”。file-analyzer 代理定义中的 Language directive 段落也印证了这一点：当派发提示中包含语言指令时，summary 用目标语言撰写，tags 在自然时本地化（如俄语 утилиты），通用技术术语（middleware、api-handler、test）保留英文，且要求“使用自然的、母语级别的措辞”。

四、技术术语（Технические термины）：必须保留英文的词表

ru.md 第三部分列出一张“不要翻译”清单——这些术语建议保留英文（原因：没有公认的俄语标准译法）：

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

这张清单的设计意图值得注意：它约束的不仅是摘要正文，还包括标签（第二部分表格中的 barrel、entry-point、unit-test 等英文标签正是这份清单的落地）和层级名称（下一节的 слой middleware）。这保证了即使图谱整体俄语化，架构分析中基于英文术语的交叉检索、图谱边的语义匹配（如 architecture-analyzer 的结构性分析）仍然有稳定锚点。

五、层级名称（Имена слоёв）：俄语层级或团队约定的英文层级

ru.md 第四部分规定架构层级（Phase 4 产物 layers）的命名方式，两种都被允许：

使用俄语层级名（推荐默认）：

• API-слой、сервисный слой、слой данных、UI-слой
• инфраструктура、конфигурация、документация
• утилитарный слой、слой middleware、тестовый слой

或按团队约定保留英文：

• API Layer、Service Layer、Data Layer

注意细节：слой middleware 是典型的混合形态——框架语是俄语（слой，层），术语保留英文（middleware）。architecture-analyzer 代理定义中的 Language directive 要求层级 name 翻译到目标语言、description 用目标语言的自然措辞撰写，并明确“当术语有既定英文形式时予以保留（如 CI/CD、ORM、REST API）”——与 ru.md 的术语清单完全对齐。层级结构本身（3–10 个层级、每个文件节点恰好归入一个层级）不受语言影响，受影响的只是 name 与 description 两个文本字段。

六、ru.md 在分析管线中的加载链路：从 --language ru 到提示词注入

下面结合 SKILL.md 的七阶段流程，说明这份 49 行的指南文件如何真正生效。

6.1 Phase 0：语言解析与持久化（3.6 步）

SKILL.md 的 Phase 0 第 3.6 步定义了 $OUTPUT_LANGUAGE 的完整解析逻辑，--language 参数接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese、russian 等），其友好名映射表中明确包含 russian → ru；区域变体（zh-TW、pt-BR 等）原样保留。决策顺序为：

1. 显式 --language ru（或 --language russian）优先：解析后把 {"outputLanguage": "ru"} 合并写入 $UA_DIR/config.json（即 .ua/config.json 或遗留的 .understand-anything/config.json），并设为 $OUTPUT_LANGUAGE；
2. 未指定时，已存储偏好优先：config.json 中已有 outputLanguage 字段则直接复用，保证增量更新的语言一致性；
3. 两者皆无时（首次运行）自动检测：推断用户对话的主语言。若检测非 en（例如用俄语对话），先向用户确认一次“是否以该语言生成全部内容”，用户按 Enter 接受或输入其他语言代码覆盖；非交互场景则直接使用检测值并打印一行提示。解析结果（包括 en）都会持久化，避免重复询问。

解析完成后，SKILL.md 会构造 $LANGUAGE_DIRECTIVE——一段注入到所有子代理派发提示中的模板：

Language directive: Generate all textual content (summaries, descriptions, tags, titles, languageNotes, languageLesson) in {language}. Maintain technical accuracy while using natural, native-level phrasing in the target language. Keep technical terms in English when no standard translation exists (e.g., "middleware", "hook", "barrel").

注意这条通用指令末尾的括号示例——middleware、hook、barrel——正是 ru.md 术语清单的前三项。通用指令给出底线规则，ru.md 则提供俄语的具体词表与风格细节，二者是“总则 + 细则”的关系。

6.2 Phase 4：locale 文件的条件注入

ru.md 被实际读取注入发生在 Phase 4（ARCHITECTURE） 构造 architecture-analyzer 提示词模板时，注入顺序为四层：

1. 语言上下文：对 Phase 1 检测到的每种源码语言（python、typescript 等），追加 languages/ 目录下对应文件；
2. 框架附录：对检测到的每个框架（如 Django），追加 frameworks/ 目录对应文件；
3. 输出语言指南：当且仅当 $OUTPUT_LANGUAGE 不是 en 时，读取 ./locales/<language-code>.md（俄语即 ./locales/ru.md），在 ## Output Language Guidelines 标题下追加在框架附录之后。SKILL.md 原文说明其作用是“提供标签命名约定、摘要风格与层级名称翻译的语言特定指导”——这恰好是 ru.md 的四个小节；
4. 兜底行为：若目标语言没有对应的 locale 文件，则静默跳过该注入，但 $LANGUAGE_DIRECTIVE 仍然生效——即语言输出不退化，只是少了一份细则。俄语因为存在 ru.md，能获得完整的细则级约束。

6.3 语言指令作用的子代理字段清单

$LANGUAGE_DIRECTIVE 被追加到多个子代理的派发提示中，ru.md 的约定随之下沉到具体字段：

子代理	受语言指令影响的字段	定义位置
project-scanner	项目 description（Phase 2 中综合叙述）	agents/project-scanner.md
file-analyzer	summary、tags（本地化或英文混合）、languageNotes	agents/file-analyzer.md
architecture-analyzer	层级 name、description	agents/architecture-analyzer.md
tour-builder	导览 title、description（教学性措辞）	agents/tour-builder.md

例如 architecture-analyzer 的定义中给出的示例是中文的 “API 层”“服务层”“基础设施层”，按同一规则在俄语下就应当产出 API-слой、сервисный слой、инфраструктура——正是 ru.md 第五节列出的词表。

七、语言偏好的持久化与 Dashboard 侧的俄语支持

语言偏好不是只在单次运行内存中流转，它有两处落地：

1. 项目级配置持久化。$UA_DIR/config.json 承载 outputLanguage 字段。核心包的默认配置为 { autoUpdate: false, outputLanguage: "en" }，类型定义见 packages/core/src/persistence/index.ts 与 packages/core/src/types.ts 中的 ProjectConfig 接口（outputLanguage?: string）。这意味着 ru 会被写入项目数据目录，之后的增量更新（只重分析变更文件）自动沿用俄语，无需每次传参。

2. Dashboard UI 的俄语界面。README 说明 --language 同时影响“Dashboard UI 的标签、按钮和工具提示”。在 Dashboard 前端，src/App.tsx 会从 config.json 读取 outputLanguage 并传给 I18nProvider；src/locales/index.ts 定义的语言键集合为 "en" | "zh" | "zh-TW" | "ja" | "ko" | "ru"，其归一化函数接受 ru、russian、ru-ru 三种写法并统一映射到 ru；完整词条见 src/locales/ru.ts。因此 /understand --language ru 之后打开 /understand-dashboard，图谱内容（summary、tags、层级、tour）与界面文案会是同一个俄语体系。

八、实操要点与适用边界

把上述机制汇总成可操作清单：

# 在 Claude Code / Codex / Cursor 等支持斜杠命令的平台上：
/understand --language ru
# 友好名称等价写法：
/understand --language russian

• 首次运行不带 --language：若你用俄语对话，/understand 会检测到并询问确认；确认后 ru 写入 .ua/config.json，此后该项目的所有增量运行（默认只重分析变更文件）都保持俄语输出。
• 切换语言：再次执行 /understand --language zh 即可覆盖存储偏好，配置会被合并更新，无需删除图谱。
• 增量更新的一致性：因为偏好持久化在 config.json，增量路径（Phase 2 的 changed-files 批次、Phase 4 的全量层级重算）会沿用已存储语言，新节点与旧节点的 summary 语言保持一致；architecture-analyzer 在增量时还会注入旧层级定义以维持命名一致性。
• 适用边界：
  • locale 注入仅在 $OUTPUT_LANGUAGE != en 时发生，且只覆盖 locales/ 中已存在的文件（当前为 en/zh/zh-TW/ja/ko/ru 六个文件）；指定其他语言时静默回退到 $LANGUAGE_DIRECTIVE 的通用约束；
  • ru.md 约束的是文本字段（summary、tags、层级与 tour 的文本），节点 ID（file:、function: 等前缀）、边类型（imports、calls 等 26 种）、权重等结构化数据不受语言影响，这保证了图谱可机读性与跨语言一致性。

九、小结

ru.md 虽然只有五个小节，却精准定义了 Understand-Anything 俄语输出的完整规范：八类节点的推荐标签表与英俄混合策略、1–2 句主动语态的摘要风格及好坏对照示例、十四项保留英文的技术术语清单、双语可选的层级命名法。它的生效路径由 SKILL.md 的 Phase 0（语言解析、友好名归一化、config.json 持久化）与 Phase 4（## Output Language Guidelines 条件注入）保证，并通过 $LANGUAGE_DIRECTIVE 细化到 file-analyzer、architecture-analyzer、tour-builder 等子代理的具体字段；持久层由 core 包的 ProjectConfig 支撑，呈现层由 Dashboard 的 ru 词条 配套。理解了这条“声明 → 解析 → 注入 → 持久化 → 呈现”的链路，你就可以在多语言团队中为俄语成员稳定交付一份标签规范、摘要地道、术语锚点统一的俄语知识图谱。