Understand-Anything 日本語出力ガイドライン解析：knowledge-graph.json 的标签命名、摘要风格与层名规则

Understand-Anything 的 /understand 技能在为代码库生成知识图谱时，可以通过 --language 参数选择图谱文本内容的输出语言。understand-anything-plugin/skills/understand/locales/ja.md 正是面向日语输出的语言指引文件，它规定了日语模式下节点标签（tags）、文件摘要（summary）和架构层名（layer names）的命名与书写规则。读完后，你将了解这份指引如何被注入 LLM 提示词、四条规则各自的设计动机，以及如何通过源码验证其生效路径。

ja.md 在 /understand 管线中的位置

/understand 技能的完整流程定义在 SKILL.md 中。语言相关逻辑分布在两个阶段：

阶段 0（Pre-flight）：语言配置解析。 --language <lang> 选项接受 ISO 639-1 代码或友好名称，并在 SKILL.md 中声明了支持范围：

• japanese → ja 等友好名到 ISO 代码的归一化映射；
• zh-TW、zh-HK 等地域变体原样保留；
• 未指定 --language 时，优先读取数据目录中 config.json 的 outputLanguage 字段（持久化偏好），否则首次运行时探测用户会话语言，并在非英语时向用户确认一次；
• 最终语言写入 config.json，保证同一项目的增量更新语言一致。

解析完成后，主会话构造一条语言指令模板（SKILL.md），随子代理分派注入后续各阶段：

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").

阶段 4（Architecture）：locale 指引文件注入。 这是 ja.md 真正被读取和使用的地方。SKILL.md 第 4 步规定：

Output locale injection: If $OUTPUT_LANGUAGE is NOT en (English), read the locale guidance file at ./locales/<language-code>.md (e.g., ./locales/zh.md, ./locales/ja.md, ./locales/ko.md) and append its content after the framework addendums under a ## Output Language Guidelines header. This provides language-specific guidance for tag naming conventions, summary style, and layer name translations. If the locale file does not exist for the specified language, skip silently — the $LANGUAGE_DIRECTIVE still applies.

也就是说，当 $OUTPUT_LANGUAGE 为 ja 且不是英语时，架构分析阶段会把 ja.md 的全文追加到 architecture-analyzer 代理提示词的 ## Output Language Guidelines 标题下。若对应语言的 locale 文件不存在，则静默跳过、仅依赖语言指令模板生效——这是一种"指引可选、指令兜底"的降级设计。locales 目录下与 ja.md 并列的还有 en.md、zh.md、zh-TW.md、ko.md、ru.md。

规则一：标签命名约定（タグの命名規則）

ja.md 给出的核心原则是：使用日语标签，或使用英文通用技术术语。完整推荐标签表如下（原文继承）：

模式	推荐标签
入口点	入口点, barrel, exports 或 entry-point
工具函数	ユーティリティ, helpers, utility
API 处理器	api-handler, controller, endpoint
数据模型	データモデル, entity, schema 或 data-model
测试文件	テスト, unit-test, test
配置文件	設定, build-system, configuration
基础设施	インフラ, deployment, infrastructure
文档	ドキュメント, guide, documentation

表中有一个值得注意的设计取舍：结构性/角色性术语（barrel、api-handler、controller、entity、schema、unit-test 等）统一保留英文，而领域描述性术语（入口点、ユーティリティ、データモデル、設定、インフラ、ドキュメント）使用日语。这与中文 locale zh.md 的"混合策略"完全一致，也与英语基准版 en.md 的"全小写连字符英文标签"形成对照——日语版是"角色词英文 + 描述词日语"的折中方案。

ja.md 对这一混合策略的原文表述是：

混合戦略： 一般的な技術用語は英語を保持（middleware, api-handlerなど）、説明用タグは日本語を使用可能。

之所以这样规定，与标签在管线中的实际用途有关：标签随文件节点写入 knowledge-graph.json（节点必备字段 tags，缺失会被阶段 6 的确定性校验标记为 issue），并被架构分析阶段作为分层依据之一。在 architecture-analyzer.md 的输入示例中可以看到，节点以 tags: ["api-handler"] 这类短标签参与结构分析；SKILL.md 也明确要求阶段 4 的分发提示词携带每个文件节点的 tags。保留英文短标签可以保证跨语言图谱中标签集合的可比对性，而描述性日语标签则让日本用户在浏览图谱时获得母语化的语义提示。

规则二：摘要风格（サマリーのスタイル）

ja.md 要求用日语撰写 1–2 句摘要，并给出三条硬性约束：

• 描述文件的目的（目的）与角色（役割）；
• 使用主动语态（能動態），如「提供する...」「処理する...」「管理する...」；
• 避免重复文件名（ファイル名の繰り返しを避ける）。

原文的对比示例：

• 良い（好）："API層全体で使用される日付フォーマットと文字列サニタイズのヘルパー関数を提供。"
• 悪い（差）："utilsファイルにはユーティリティ関数が含まれています。"

"差"示例的问题在于它只是把文件名翻译成了日语（"utils 文件里包含工具函数"），没有回答"这个文件为什么存在、承担什么职责"；"好"示例则用主动句说明职责与影响面。这条规则与 SKILL.md 阶段 6 的校验逻辑闭环：内联验证脚本会检查每个节点的 summary 是否存在，缺失摘要的节点会被记入 issues（见 SKILL.md 中的 Node[...] missing summary 检查），因此摘要不仅是展示层内容，也是图谱合法性的必备字段。

规则三：保留英文的技术术语

ja.md 明确列出在无标准翻译时应保持英文的术语：

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

这份清单与语言指令模板中的兜底规则（"Keep technical terms in English when no standard translation exists"）互相呼应：即使 locale 文件被静默跳过，术语保留策略依然生效。清单本身与 en.md 和 zh.md 中的同类清单高度一致，说明各语言指引共享同一套"术语白名单"设计，只是描述文字和目标语摘要分别本地化。

规则四：层名（レイヤー名）

架构层名同样采用"日语优先、英文可选"的双轨制。日语层名推荐集合：

• API層, サービス層, データ層, UI層
• インフラ, 設定, ドキュメント
• ユーティリティ層, ミドルウェア層, テスト層

ja.md 同时允许按团队惯例保留英文层名（API Layer, Service Layer, Data Layer）。这一点在管线实现上是有约束的：阶段 4 完成后，层名会被归一化为固定四字段结构（SKILL.md）：

[
  {
    "id": "layer:<kebab-case-name>",
    "name": "<layer name>",
    "description": "<what belongs in this layer>",
    "nodeIds": ["file:src/App.tsx", "config:tsconfig.json", "document:README.md"]
  }
]

注意 id 字段使用 layer:<kebab-case-name> 约定——即使 name 是日语 API層，id 仍会被归一化（缺失时合成）为 kebab-case 形式，这保证了节点 ID 体系与展示名称解耦：层名可以放心日语化，而图谱内部标识保持 ASCII 稳定。阶段 6 的验证还会检查每个 layers[*].nodeIds 引用都存在于合并后的节点集合中。

日语输出的端到端验证路径

把 ja.md 的规则放回整条管线，可以确认其影响面覆盖图谱文本内容的四个部分（summaries、descriptions、tags、titles，以及 tour 的 languageNotes/languageLesson）：

1. 文件摘要由阶段 2 的 file-analyzer 子代理按语言指令生成，随后经 merge-batch-graphs.py 合并归一化；
2. 标签随节点贯穿阶段 2 → 阶段 4，并作为分层证据被 architecture-analyzer 消费；
3. 层名与层描述在阶段 4 生成时同时应用 ja.md 的层名规则；
4. tour 步骤文本由阶段 5 的 tour-builder 按语言指令生成。

在展示层，仪表盘同样支持日语界面：packages/dashboard/src/locales/index.ts 的 resolveLocaleKey 会把 ja 和友好名 japanese 归一化到 ja locale，并提供 en 兜底。这与技能侧的语言归一化是两套独立机制——前者决定仪表盘 UI 文案语言，后者（$OUTPUT_LANGUAGE）决定图谱数据本身的语言，两者可以组合出"日语图谱 + 日语界面"的完整体验。

实践：启用日语图谱输出

在支持 /understand 技能的环境中（Claude Code、Codex、Cursor 等，技能定义见 SKILL.md），最小用法是：

/understand --language ja

执行效果：

• japanese 或 ja 均会被归一化，偏好写入项目数据目录（.ua/ 或存量项目遗留的 .understand-anything/）下的 config.json（{"outputLanguage": "ja"}），后续增量更新自动沿用；
• 阶段 4 架构分析时，主会话读取 locales/ja.md 并注入 ## Output Language Guidelines；
• 产出的 knowledge-graph.json 中，摘要与层名为日语、技术术语标签保留英文。

需要说明的适用边界：locale 文件仅在 $OUTPUT_LANGUAGE 非英语时注入；若某语言没有对应的 locale 文件（例如 es），流程会静默跳过文件注入，仅靠语言指令模板约束输出，不会报错。

小结

understand-anything-plugin/skills/understand/locales/ja.md 是 Understand-Anything 多语言图谱输出机制中的日语配置件：它用四组规则——标签混合命名表、主动语态摘要风格、英文术语白名单、双轨层名——约束 LLM 生成的图谱文本，保证日语知识图谱在本地化与工程一致性之间取得平衡。其设计价值在于：展示层名称（层名、摘要）完整日语化以提升可读性，而标识层（节点 ID、角色标签、技术术语）保持英文以维持图谱结构与跨语言比对的可预测性。结合 SKILL.md 的阶段 0 语言配置和阶段 4 locale 注入逻辑，可以完整验证这条规则链从命令行参数到 knowledge-graph.json 的最终落地路径。