Understand-Anything 多语言知识图谱输出：ko.md 韩语语言指南及其注入机制详解

在 Understand-Anything 的 /understand 分析流水线中，ko.md 是韩语（ko）输出的语言指南文件，与同目录下的 en.md、zh.md、ja.md 等文件构成 locales 体系。当你用 --language ko（或 korean）生成知识图谱时，它会在架构分析阶段被注入到子代理提示词中，约束节点标签命名、1-2 句摘要的写作风格、技术术语的英译策略以及层级（Layer）名称的韩文化。读完本文，你将掌握这份指南的全部规则条目、它在七阶段流水线中的注入时机，以及背后的配置持久化与实现链路。

韩语指南的完整规则：标签、摘要、术语与层级名

ko.md 共四节，逐节拆解如下。

1. 태그 명명 규칙（标签命名规则）

规则是“使用韩语标签或英文通用技术术语”，并给出了一张八行的模式映射表：

模式	推荐标签
入口文件	진입점, 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

表格后面还定义了混合策略（혼합 전략）：通用技术术语保留英文（如 middleware、api-handler），描述性标签则允许使用韩语。

对比同系列的 en.md 可以清楚看到本地化的差异：英文指南要求标签统一为小写连字符形式（entry-point、utility、api-handler…），而韩语指南在每一行中都多给了一个韩文选项（如 진입점、유틸리티、데이터모델）。这意味着韩语图谱中的 tags 字段可能同时出现韩文与英文两种形态，下游做标签检索或过滤时需要考虑这种双语共存。

2. 요약 스타일（摘要写作风格）

摘要要求用 1-2 句韩语撰写，且满足三条约束：

• 说明文件的目的（목적）与角色（역할）；
• 使用主动语态（“제공하는...”“처리하는...”“관리하는...”）；
• 避免重复文件名。

文档给出了对照示例：

• 好：「API 레이어 전체에서 사용되는 날짜 포맷 및 문자열 정제 헬퍼 함수를 제공.」（提供在 API 层整体中使用的日期格式与字符串清洗辅助函数。）
• 差：「utils 파일에는 유틸리티 함수가 포함되어 있습니다.」（utils 文件包含工具函数。）

这与 en.md 中的 "Provides date formatting and string sanitization helpers used across the API layer." / "The utils file contains utility functions." 是同一套正反例的韩文化版本。摘要最终会写入知识图谱中每个节点的 summary 字段——这一点在 SKILL.md 的 Phase 6 内联校验脚本中可以得到印证：缺少 summary 的节点会被记为 issue（Node[i] '<id>' missing summary），而 tags 为空同样被视为缺失字段。也就是说，ko.md 约束的这两类文本字段在流水线末尾是被强制校验的必备字段，不是可选装饰。

3. 기술 용어（技术术语保留清单）

以下术语无标准韩译，要求保持英文原文：

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

这份清单与 SKILL.md 中语言指令模板（$LANGUAGE_DIRECTIVE）的要求互相呼应：「Keep technical terms in English when no standard translation exists (e.g., "middleware", "hook", "barrel")」——即全局指令给出原则，ko.md 给出该语言的具体清单。

4. 레이어 이름（层级名称）

使用韩语层级名：

• API 레이어、서비스 레이어、데이터 레이어、UI 레이어
• 인프라、설정、문서
• 유틸리티 레이어、미들웨어 레이어、테스트 레이어

同时允许按团队习惯保留英文（API Layer、Service Layer、Data Layer）。层级名对应知识图谱 layers[] 数组中每个层级的 name 字段——该字段的生成者正是 architecture-analyzer 子代理，其代理定义 architecture-analyzer.md 中的 Language directive 一节明确写道：当派发提示中包含语言指令时，层级的 name 要翻译成指定语言（如「API 层」「서비스 레이어」），description 用目标语言的自然措辞撰写，同时「在有适当性时保留既定英文术语（如 CI/CD、ORM、REST API 可不译）」——这条约束与 ko.md 的术语清单完全对齐。

ko.md 在流水线中的注入机制

ko.md 本身不是被用户直接加载的文件，而是由 SKILL.md 定义的 /understand 技能在运行时按需读取的「提示词插件」。完整链路分为三步：

第一步：--language 解析与语言偏好持久化

/understand 的选项解析（SKILL.md Phase 0 的 3.6 小节）：

• --language <lang> 接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese、korean、english…），友好名会经映射表归一化为 ISO 代码，如 korean → ko；地区变体（zh-TW、zh-HK、pt-BR 等）原样保留。
• 若显式传入 --language，则把 {"outputLanguage": "<lang>"} 合并写入项目数据目录（.ua/ 或已存在的旧版 .understand-anything/）下的 config.json，并在整个流程中作为 $OUTPUT_LANGUAGE 使用。
• 若未传入，则已存储的偏好优先：config.json 中的 outputLanguage 字段生效，避免每次增量更新重新询问。
• 首次运行且无偏好时，会从用户对话中推断主导语言；非英文时确认一次，非交互环境则直接使用并打印一行提示；最终解析结果（包括 en）都会持久化，同一项目不会再重复询问。

config.json 的默认值在 core 包中有明确实现：persistence/index.ts 中 DEFAULT_CONFIG: ProjectConfig = { autoUpdate: false, outputLanguage: "en" }，loadConfig() 在文件缺失或 JSON 解析失败时均回退到该默认配置。outputLanguage 字段则定义在 types.ts 的 ProjectConfig 中。

第二步：$LANGUAGE_DIRECTIVE 注入到各阶段子代理

解析出的 $OUTPUT_LANGUAGE 会生成一段语言指令模板（存为 $LANGUAGE_DIRECTIVE），并在四个阶段追加到子代理派发提示词中：

• Phase 1 SCAN（project-scanner，见 project-scanner.md）
• Phase 2 ANALYZE（file-analyzer，见 file-analyzer.md）
• Phase 4 ARCHITECTURE（architecture-analyzer，见 architecture-analyzer.md）
• Phase 5 TOUR（tour-builder，见 tour-builder.md）

第三步：Phase 4 的 locale 文件注入（ko.md 的入口）

SKILL.md Phase 4（ARCHITECTURE）定义了提示词的三层上下文拼装，locale 注入是第三层：

1. 语言上下文注入：对 Phase 1 检测到的每种语言，读取 languages/ 子目录下对应的 languages/<language-id>.md（如 python、yaml、dockerfile），追加在 ## Language Context 标题下；
2. 框架附录注入：对检测到的每个框架，读取 frameworks/<framework-id-lowercase>.md（如 Django 对应 frameworks/django.md），完整内容追加在语言上下文之后；
3. 输出 locale 注入：当且仅当 $OUTPUT_LANGUAGE 不是 en 时，读取 ./locales/<language-code>.md（例如 ./locales/zh.md、./locales/ja.md、./locales/ko.md），内容追加在框架附录之后、## Output Language Guidelines 标题下。该节明确说明其作用是「提供语言特定的标签命名约定、摘要风格与层级名翻译指导」。

两个工程细节值得注意：

• 静默降级：若指定语言没有对应的 locale 文件（当前 locales 目录实际只有 en、ja、ko、ru、zh、zh-TW 六个文件），流水线静默跳过注入，$LANGUAGE_DIRECTIVE 仍然生效——即目标语言输出不会因此中断，只是失去该语言的细粒度风格约束。
• 仅非英文才注入 locale 文件：英文输出直接依赖 $LANGUAGE_DIRECTIVE 与 en.md 的约定默认行为；而韩语等非英文输出则是「全局指令 + ko.md 细则」双保险。

指南约束的落点：图谱 JSON 中的哪些字段

把 ko.md 的四节规则映射回 SKILL.md 末尾的 KnowledgeGraph Schema，可以精确看出每条规则作用于哪个字段：

ko.md 规则节	作用字段	校验位置
标签命名规则	节点的 tags[]	Phase 6 内联校验：tags 缺失即 issue
摘要风格	节点的 summary	Phase 6 内联校验：summary 缺失即 issue
术语保留清单	summary、description、languageNotes、languageLesson 等全部文本字段	由 $LANGUAGE_DIRECTIVE 全局约束
层级名称	layers[] 的 name 与 description	Phase 6 校验：layer 必须有 id、name、description、nodeIds 四字段，且每个文件级节点必须恰好属于一个 layer

Phase 6 的内联校验脚本（SKILL.md 中完整的 Node.js 单文件脚本）还会检查每个 layer/tour 步骤引用的 nodeIds 是否真实存在、文件级节点是否都落在某个 layer 中、孤儿节点仅记 warning。这保证了即使摘要被韩文化、层级名被本地化，图谱的结构完整性（节点引用闭合、层级全覆盖）依然由确定性代码兜底。

韩语输出的端到端消费链

语言设置并不止于图谱文本本身，它还贯穿到仪表盘展示：

• 从源码结构看，dashboard 的 App.tsx 会读取 config.json 的 outputLanguage 字段（config?.outputLanguage 存在时写入 state），默认 "en"；
• 该值传入 I18nContext.tsx 的 I18nProvider，经 resolveLocaleKey() 解析后选择对应 locale 文案表，驱动 dashboard UI 自身的国际化（dashboard 支持 en、ja、ko、ru、zh、zh-TW 六套界面文案，见 locales/index.ts 及同目录下的 ko.ts 等文件）。

也就是说，outputLanguage: "ko" 会产生两层效果：图谱内容（摘要、标签、层级名、tour 文本）按 ko.md 的指南生成韩语，dashboard 界面也切换为韩语。viewer 侧的 viewer.mjs 在读取不到 config 时同样返回 { autoUpdate: false, outputLanguage: "en" } 作为默认值，行为与 core 包保持一致。

实操要点与适用前提

• 启用方式：/understand --language ko（或 --language korean）；偏好写入 $UA_DIR/config.json 后，后续增量更新自动沿用，无需重复指定；
• 生效范围：summary、description、tags、title、languageNotes、languageLesson 六类文本字段（$LANGUAGE_DIRECTIVE 原文列举），层级名由 Phase 4 按 ko.md 的层级名清单本地化；
• 术语边界：middleware、hook、barrel、ORM、CI/CD 等无标准韩译的词一律保留英文，不要硬译；
• 摘要边界：1-2 句、主动语态、描述目的与角色、不复述文件名——这四条是韩语摘要的最小合格标准，正反例直接以 ko.md 中的两句为准；
• 降级前提：locales 目录目前仅覆盖六种语言，es、fr、de 等虽被 --language 接受，但没有对应 locale 文件时会静默跳过细则注入，仅靠全局语言指令生成输出。

参考文件汇总：ko.md（本文主体）、SKILL.md（注入机制与校验脚本）、architecture-analyzer.md（层级名翻译约束）、persistence/index.ts（outputLanguage 默认值与读写）、I18nContext.tsx（dashboard 语言消费）。