Understand-Anything 会话语言自动检测设计/understand的四级语言解析链与首跑确认门【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本文围绕 Understand-Anything 的设计文档 2026-06-03-language-auto-detection-design.md 展开讲解/understand技能如何在不改动任何代码与 Schema 的前提下通过重写SKILL.md的语言解析逻辑实现首次分析时自动检测用户会话语言、非英文才确认一次的输出语言决策机制。读完你可以完整理解其四级解析链flag 存储配置 会话检测 en兜底的设计动机、确认门confirmation gate的行为边界、全部边缘情形处理以及仓库中该方案落地后的真实源码位置SKILL.md、ProjectConfig类型、Dashboard 语言解析、locales/注入链。问题背景静默的en默认值代价高昂/understand会生成全部 LLM 撰写的内容——节点摘要、标签、层级名称、导览guided tours、语言注释等——而默认全部输出为英文。改动前的行为由 SKILL.md 第 3.6 步控制只有显式传入--language lang参数或.understand-anything/config.json中存有outputLanguage时才生效两者皆无则静默回落到英文- If --language is NOT specified: - Check config.json for outputLanguage. If present, use that. - If no stored preference, default to en (English).设计文档中记录的真实失败场景是一位全程用中文对话的用户运行了最简单的/understand命令拿到了一张全英文的知识图谱——而他只有在付完一整次分析的运行成本时间 token之后才发现语言不对只能带着--language zh重跑一遍。默认值既是静默的又是不可发现的语言决策在真正要紧的时刻没有任何提示浮出。这正是该设计的出发点在项目首次分析时从会话中推断用户的工作语言并在消耗分析预算之前确认它——同时保证英文用户项目核心受众行为完全不变、非交互式调用不被阻塞。目标与非目标目标首次分析时从会话推断用户语言并确认代价是改动面极小——纯提示词逻辑prompt-logic因为outputLanguage字段本已存在于ProjectConfig中见 types.ts// Project config (for auto-update opt-in and language preference) export interface ProjectConfig { autoUpdate: boolean; outputLanguage?: string; }非目标Non-Goals在设计文档中被明确列出划定了严格的边界不做并排双语输出——每张图谱仍是单语言不改动其他生成类技能understand-domain、understand-knowledge、understand-explain等它们目前完全忽略outputLanguage属于留给后续 PR 的已知缺口不改动自治自动更新钩子路径understand-anything-plugin/hooks/auto-update-prompt.md——它复用已有图谱、不解析语言检测逻辑在那里永远不会触发不做任何代码、Schema 或 TypeScript 改动。方案选型检测作为兜底而非菜单设计文档对比了三条路线最终选择了 (B)(A) 个人绕过永远手动传--language zh/ 手改配置对上游零价值否决(B) 在SKILL.md中检测作为兜底被选中最小 diff对非英文用户严格更好对英文用户完全不可见。检测逻辑插入解析链中、位于en默认值之前并由仅首跑、仅非英文的确认门把关(C) 每次运行都弹菜单重新引入摩擦也最容易被上游维护者否决。选择确认门而非静默应用检测值是为了显式性但被严格约束为绝不影响英文用户。值得强调的一个细节SKILL.md本身是一段由模型解释执行的提示词所以技能文档中写的是确认的意图一条指令而不是硬编码一个字面提示框——问题文本由模型在运行时自行渲染。同时SKILL.md的指令文本保持英文只有生成的内容才是目标语言。详细设计四级语言解析链这是对SKILL.md第 3.6 步if --language NOT specified分支的重写。优先级从高到低--language lang参数存在→ 通过既有的友好名映射表归一化持久化到config.json后使用。行为不变config.json中存在outputLanguage→ 直接使用。行为不变首跑既无参数又无配置→ 新增检测会话语言推断当前会话中用户消息的主导语言 →$DETECTED_LANGISO 639-1 码如zh、ja若$DETECTED_LANG为en、无法自信判定、或会话混合/含糊 → 置$OUTPUT_LANGUAGE en持久化无提示直接进行对核心受众精确保持现状若$DETECTED_LANG ≠ en→ 弹出下文确认门解析出$OUTPUT_LANGUAGE并持久化。所有分支最终都会把解析值写入config.json{outputLanguage: lang}合并进既有配置因此确认门每个项目至多触发一次。配套的友好名归一化映射在检测与覆盖两个环节共用输入形式归一化结果chinese/japanese/korean/english/spanish/french/german/portuguese/russian/arabiczh/ja/ko/en/es/fr/de/pt/ru/ar区域变体zh-TW、zh-HK、zh-CN、pt-BR等原样保留确认门只在非英文 尚未选择时出现确认门在任何流水线阶段运行之前展示指令要求模型做到三件事说明检测到的语言询问是否用它生成所有内容接受 Enter / yes / 检测到的语言码作为确认 →$OUTPUT_LANGUAGE $DETECTED_LANG接受任意其他语言码或友好名作为覆盖→ 经友好名映射归一化后使用。这一条同时充当逃生舱口——我用中文聊天但团队文档要英文的场景。边缘情形全覆盖设计文档为每种边缘情形给出了明确的已决行为不留模糊空间情形行为检测不确定 / 混合语言按en处理静默继续。绝不为猜测而阻塞。非交互式调用headless/CI无人应答回落到$DETECTED_LANG并打一行提示而非挂在确认门确认是尽力而为best-effort永远不是硬阻塞。自治自动更新钩子不受影响——该路径根本不解析语言。检测到的语言有locales/lang.md文件第 4 步已有注入逻辑无需改动。检测到的语言没有 locale 文件$LANGUAGE_DIRECTIVE仍然生效既有的静默跳过行为。仓库落地现状从设计到已实现的源码证据该设计已实现且可以在仓库中逐条对照验证。1.SKILL.md第 3.6 步的现行文本。SKILL.md 中的 Language configuration 小节与设计完全一致——Stored preference wins → Otherwise detect (first run only) → If$DETECTED_LANG≠en, confirm once → Persist 四步解析链已就位非交互降级skip the wait, use$DETECTED_LANG, and print a one-line notice instead of blocking也原样写入- If --language is NOT specified: - **Stored preference wins.** If $UA_DIR/config.json has an outputLanguage field, set $OUTPUT_LANGUAGE to it and skip the rest. - **Otherwise detect (first run only).** Infer the predominant language of the users conversation as an ISO 639-1 code ($DETECTED_LANG). If it is en or cannot be confidently determined, set $OUTPUT_LANGUAGEen and proceed silently — no prompt (English users see no change). - **If $DETECTED_LANG ≠ en, confirm once before analyzing:** ... - **Persist** the resolved $OUTPUT_LANGUAGE (including en) into config.json so it never re-prompts for this project.紧接其后的$LANGUAGE_DIRECTIVE模板L161-L164规定了语言指令的语义所有文本内容summaries、descriptions、tags、titles、languageNotes、languageLesson以目标语言生成保持母语级自然表达且无标准译法的术语保留英文如 middleware、hook、barrel。该模板被注入到多个阶段——项目扫描派发的 promptL251、逐批文件分析L310、架构分析L439与导览生成L516保证一次决策覆盖全流水线。2. 持久化层的既有支持。配置落盘并不需要新代码persistence/index.ts 中DEFAULT_CONFIG已内置outputLanguage: enpersistence.test.ts 验证了无配置文件时返回默认配置与配置损坏时回落到默认两个用例——这正是检测失败也绝不阻塞的底层保障即使config.json写坏了系统也只是回到en而不是抛错。另外注意 SKILL.md 第 1.7 步的数据目录解析若项目已有.understand-anything/目录则沿用否则使用新的.ua/目录配置始终写在$UA_DIR/config.json。3. Dashboard 侧的语言联动。--language参数同时影响 Dashboard UI 的文案。从 locales/index.ts 的resolveLocaleKey可以看到 UI 层支持的正是同一组语言键——en、zh、zh-TW、ja、ko、ru且做了大小写、下划线、区域码的归一化如zh-cn→zh未知值一律回落en。这与 README 中 Supported languages: en (default), zh, zh-TW, ja, ko, ru 的声明相互印证。4.locales/lang.md注入链。设计文档边缘情形表中已有 locale 文件则注入对应的是SKILL.md第 4 步的第 4 条L424当$OUTPUT_LANGUAGE不是en时读取./locales/language-code.md并以## Output Language Guidelines头附加到分析 agent 的 prompt 之后文件不存在则静默跳过。locales/zh.md 提供了具体的语言指导——标签中英混合策略通用术语保留英文、描述性标签可用中文、1-2 句摘要风格、术语保留清单middleware、ORM、singleton等、层级命名API 层、服务层或保留英文API Layer。locales/目录下还配有en.md、ja.md、ko.md、ru.md、zh-TW.md与 UI 侧支持的语言集合对齐。5. README 用户文档。设计要求的一句话说明已落在 README.md 的 Localized output 小节首跑且未传--language、未存语言时/understand会检测会话语言非英文则询问确认或覆盖英文会话不受影响选择写入.ua/config.json并在后续每次运行复用。验证策略五个手工场景与零回归不变量由于是提示词逻辑改动技能行为没有单元测试钩子——这与既有--language参数的验证方式一致。配套的实现计划 2026-06-03-language-auto-detection.md 定义了逐场景推演验证对编辑后的 3.6 步文本追踪确认产生的$OUTPUT_LANGUAGE与config.json写入正确#场景全新项目无config.json预期结果1中文会话运行/understand确认门出现 → 确认 →$OUTPUT_LANGUAGEzhconfig.json得到outputLanguage:zh2同项目重跑配置已含zh无确认门存储偏好优先生成zh3英文会话运行/understand无确认门$OUTPUT_LANGUAGEen英文输出无回归4全新项目传--language ja无确认门参数优先config.json得到outputLanguage:ja5检测到zh用户在确认门输入en$OUTPUT_LANGUAGEenconfig.json得到outputLanguage:en其中场景 3 承载了实现计划中标注的**零回归不变量**不存在任何代码路径会让纯英文会话 无参数/无配置产生提示。这是上游接受度最关键的一条性质。若想做真实冒烟测试在一个无.ua/config.json的临时仓库中用中文简短对话后运行/understand确认确认门出现、确认后config.json写入outputLanguage: zh完整分析跑太贵时可跳过场景推演已足够支撑 PR。改动面与上游风险控制设计文档的 Files Touched 清单精确到两个文件且再无其他文件——没有 Schema、代码或测试脚手架改动文件责任改动SKILL.md/understand技能提示词第 3.6 步解析$OUTPUT_LANGUAGE重写If --language is NOT specified子块为四级解析链主改动README.md用户文档 Localized output 小节增加一段首跑自动检测说明主要审查风险是任何新增的交互性。设计内置了三重缓解确认门仅首跑触发、仅非英文触发、非交互时优雅降级。PR 描述以此为核心主张英文用户零行为变化确认门只在会话非英文且尚未选择语言时才出现。小结这套语言自动检测的价值不在检测本身而在其工程化的克制它把整个语言决策收敛在SKILL.md第 3.6 步这一处用参数 配置 检测 兜底的优先级链保证显式意图永远压过启发式推断用每项目至多一次的持久化消除重复打扰用不确定即en、非交互即降级两条铁律保证检测永远不会成为阻塞点。对维护者而言这是一个零代码改动、只动提示词却完整修复了真实用户痛点的范例——检测、确认、覆盖、持久化四个环节的行为边界均可在 SKILL.md、types.ts、persistence/index.ts 与 locales/ 中逐条对照核实。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考