Understand-Anything /understand 繁体中文输出指南：zh-TW.md 语言指导文件与多语言知识图谱生成机制

本篇围绕 Understand-Anything 插件中 understand/skills/understand/locales/zh-TW.md 这一繁体中文输出指南展开：它规定了 /understand 技能在生成繁体中文知识图谱内容时，标签命名、节点摘要、技术术语与架构层级名称应遵循的具体约定。读完本文，你可以完整掌握该文件的四条核心约定（标签、摘要、术语、层级），并理解它如何被技能管线在架构分析阶段注入到 LLM 提示词中、--language zh-TW 参数如何解析与持久化、首次运行的语言自动检测与确认门槛是如何工作的。

一、locale 文件在 /understand 管线中的位置

zh-TW.md 不是一个独立使用的文档，而是 /understand 技能多语言输出机制中的一个"输出语言指导文件"。它与技能主文件 SKILL.md 同级的 locales/ 目录并列存放，同目录还有 en.md、zh.md（简体中文）、ja.md、ko.md、ru.md 等语言文件，结构一致：都包含标签约定、摘要风格、技术术语、层级名称四部分。

技能管线对它的消费方式在 SKILL.md 中有明确定义，注入发生在第 4 阶段（ARCHITECTURE）构建提示词模板时：

1. 语言指令（Language directive）：Phase 0 第 3.6 步确定 $OUTPUT_LANGUAGE 后，会生成一段模板化的语言指令，要求"所有文本内容（summaries, descriptions, tags, titles, languageNotes, languageLesson）用指定语言生成，在保持技术准确性的同时使用地道的母语表达，无标准翻译的技术术语保留英文"。该指令会随每个子代理派发（扫描、文件分析、架构分析、导览构建）注入。
2. locale 文件注入：Phase 4 第 4 步"Output locale injection"规定——当 $OUTPUT_LANGUAGE 不是 en 时，读取 ./locales/<language-code>.md（繁体中文即 ./locales/zh-TW.md），将其内容追加在框架附录之后、置于 ## Output Language Guidelines 标题下，"为标签命名约定、摘要风格和层级名称翻译提供语言特定的指导"。若指定语言没有对应的 locale 文件，则静默跳过——此时 $LANGUAGE_DIRECTIVE 仍然生效，输出语言不受影响，只是缺少这份精细化的约定。

也就是说，zh-TW.md 是一份"提示词增强材料"：它本身不执行任何代码，而是让 LLM 在生成繁体中文的节点标签、摘要和层级名称时，遵循一套与简体中文（zh.md）、日文（ja.md）平行但用字不同的规范，避免在繁体输出中混入简体用字（如"层"与"層"、"配置"与"設定"、"文件"与"檔案"）。

二、zh-TW 标签约定：模式到推荐标签的映射

zh-TW.md 的核心是一张"文件模式 → 推荐标签"映射表，指导分析器为不同类别的文件打标签。完整约定如下：

模式	推薦標籤
入口檔案	入口點, barrel, 匯出 或 entry-point
工具函數	工具函數, helpers, common 或 utility
API處理器	api-handler, 控制器, 端點
資料模型	資料模型, entity, schema 或 data-model
測試檔案	測試, 單元測試, test
設定檔	設定, 建構系統, settings 或 configuration
基礎架構	基礎架構, 部署, 容器化 或 infrastructure
文件	文件, 指南, 參考 或 documentation

与简体中文版本 zh.md 对照可以看出差异点：入口"文件"→"檔案"、"配置"→"設定"、"构建"→"建構"、"数据"→"資料"、"测试"→"測試"、"文档"→"文件"。这些用字差异正是 locale 文件存在的意义——两种中文各自使用符合本地习惯的术语体系。

混合策略：文件同时规定，通用技术术语保留英文（如 middleware、api-handler），描述性标签可使用繁體中文。这保证了标签在图谱中既能被非中文读者理解，又对繁体中文使用者自然。

三、摘要风格：1-2 句主动语态，描述目的与作用

zh-TW.md 对节点摘要（summary）的要求有三条：

1. 用繁體中文撰寫 1-2 句摘要；
2. 描述檔案的目的和作用（而非罗列内容物）；
3. 使用主動語態（"提供..."、"處理..."、"管理..."），避免重複檔名。

文档给出的正反示例：

• 好："提供日期格式化和字串清洗工具函數，被 API 層廣泛使用。"
• 差："utils 檔案包含工具函數。"

差的示例违反了"避免重复文件名"（直接复述 utils）与"描述目的和作用"两条规则；好的示例用主动语态说明文件提供什么能力、被谁消费。这些摘要最终写入 knowledge-graph.json 的节点 summary 字段，是 Dashboard 中节点卡片与搜索结果的主要信息来源。

四、技术术语保留清单与层级名称约定

4.1 保留英文的技术术语

以下术语建议保留英文（暂无标准翻译）：

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

这与 LANGUAGE_DIRECTIVE 的兜底规则一致（"Keep technical terms in English when no standard translation exists"），等于把全局规则细化为一份具体清单。

4.2 层级（Layer）名称

架构层级名称推荐用繁體中文：

• API 層、服務層、資料層、UI 層
• 基礎架構、設定、文件
• 工具層、中介軟體層、測試層

也可以整体保留英文（API Layer、Service Layer、Data Layer），"根據團隊習慣"。

这条约定直接对应管线中架构分析的产出。子代理定义 architecture-analyzer.md 中的 "Language directive" 一节明确要求：当派发提示包含语言指令时，层的 name 要翻译成指定语言（示例正是 "API 层"、"服务层"、"基础设施层"），层的 description 用指定语言的自然表达撰写，"在适当时保留既定英文术语（如 CI/CD、ORM、REST API 在某些语言中可保留不译）"。Phase 4 随后将 layers.json 归一化为 {id, name, description, nodeIds} 结构——其中 id 采用 layer:<kebab-case-name> 约定，与语言无关，保证同一层在增量更新间可稳定追踪，而 name/description 才是 locale 文件直接影响的文本字段。

五、--language 的解析链与 config.json 持久化

zh-TW.md 何时被触发，取决于 SKILL.md Phase 0 第 3.6 步"Language configuration"的解析逻辑。完整解析链按优先级从高到低为：

1. 显式 --language <lang> 标志：接受 ISO 639-1 代码（zh、ja、ko、en、es、fr、de 等）或友好名称（chinese、japanese、korean、english、spanish 等），友好名称会先映射到 ISO 代码；区域变体如 zh-TW、zh-HK、zh-CN、pt-BR 原样保留。命中时把 {"outputLanguage": "<lang>"} 合并写入 $UA_DIR/config.json（数据目录为项目根下的 .ua/，若已存在旧的 .understand-anything/ 则沿用），供后续所有阶段使用。
2. 已存储的偏好：未传 --language 时，若 config.json 已有 outputLanguage 字段，直接沿用，不再询问。
3. 首次运行检测（既无标志也无存储值）：推断用户对话的主导语言为 $DETECTED_LANG。若为 en 或无法确定，静默设为 en 继续；若不是 en，则在分析开始前做一次确认——告知用户检测到的语言，用户按回车/"yes"接受，或输入其他语言代码/名称覆盖。非交互（headless/CI）场景下不阻塞，直接使用检测值并打印一行提示。
4. 持久化：无论走哪条分支，解析出的 $OUTPUT_LANGUAGE（含 en）都写入 config.json，保证该项目的确认门槛至多触发一次。

这一机制的完整设计依据见 语言自动检测设计文档，其中明确了设计动机（用户全程用中文对话却拿到英文图谱，付完整次分析的成本才发现语言不对）与边界情况表：

场景	行为
检测不确定 / 语言混杂	按 en 处理，静默继续，绝不为猜测而阻塞
非交互调用（headless/CI）	回退使用 $DETECTED_LANG 并打印一行提示，永不硬阻塞
自动更新钩子（auto-update hook）	不受影响——该路径不复用语言解析
检测到语言有 locales/<lang>.md	已在 Phase 4 接线，直接生效
检测到语言没有 locale 文件	静默跳过，LANGUAGE_DIRECTIVE 兜底

README 中的"Localized output"一节也确认了 --language 的影响范围：知识图谱中的节点摘要与描述、Dashboard UI 的标签/按钮/工具提示、以及导览（guided tour）说明；当前支持的输出语言为 en（默认）、zh、zh-TW、ja、ko、ru。Dashboard 端的繁体中文界面资源对应 zh-TW.ts——即 zh-TW.md 规范"图谱内容"，zh-TW.ts 规范"界面文案"，两者共同构成繁体中文输出体验。

六、实战用法与可验证行为

典型使用流程（在项目根目录、已安装 Understand-Anything 插件的前提下）：

# 显式指定繁体中文输出，一次全量分析
/understand --language zh-TW

# 之后任何增量重跑都会沿用 zh-TW（读取 .ua/config.json 的 outputLanguage）
/understand

# 覆盖已有偏好：切回英文或其他语言
/understand --language en

可以验证的行为：

1. 注入点可查：分析过程在 Phase 4（[Phase 4/7] Identifying architectural layers...）派发架构分析子代理时，提示词末尾会依次出现语言上下文（languages/<lang>.md）、框架附录（frameworks/<framework>.md）和 ## Output Language Guidelines 标题下的 zh-TW.md 全文。
2. 偏好持久化可查：运行结束后 .ua/config.json 中出现 "outputLanguage": "zh-TW"；同项目再次运行不再弹确认。
3. 输出形态可查：最终 .ua/knowledge-graph.json 中，繁体运行产出的节点 summary/tags 与层 name/description 使用繁体用字（"資料層"、"設定"），而术语清单中的 middleware、ORM 等保持英文；层 id 始终为 layer:<kebab-case> 形式，与语言无关。
4. 静默降级可查：对一个没有 locale 文件的支持语言（如 es）运行 --language es，管线不会报错——按 Phase 4 的 "skip silently" 规则，仅 LANGUAGE_DIRECTIVE 生效。

七、小结

zh-TW.md 以不足百行的篇幅，用"标签映射表 + 摘要风格规则 + 英文术语清单 + 层级名称清单"四个维度，把"生成一份地道的繁体中文知识图谱"这件事约束成了可执行、可对照、可跨运行保持一致的规范。它依赖 SKILL.md 的语言解析链（标志 > 存储偏好 > 首次检测 > 英文默认）决定何时生效，依赖 architecture-analyzer.md 等子代理的语言指令消费其内容，并借助 config.json 持久化保证同一项目内语言偏好的一致性。理解这条"约定文件 → 提示词注入 → 图谱文本字段 → Dashboard 展示"的链路，即可掌握 Understand-Anything 多语言输出的完整机制，也便于在其他语言 locale 文件（如为简体中文、日文做同样四段式规范）上复用同一套方法论。