LLM 中文使用者在 Skill / Rule / Agent 脚本中的语言权衡

文档角色：参考资产（Reference Asset）
版本：v1.1 — 2026-05-01（基于项目落地实现更新）
源文件：v1.0 写于 2026-04-28，是开发过程中的探索思路记录
对应正式实现：.trae/ 目录下的 skills/skill-language-policy/SKILL.md（语言政策）、skills/skill-stability-review/SKILL.md（稳定性审查）、rules/（执行路由与护栏）
适用场景：Codex、Trae、Cursor、Claude Code 等 agent / coding agent 工具

本文档最初写于开发过程中的思路记录。以下内容经过修订，各推荐已落地为正式 Skill/Rule 文件。本文档作为理解设计思路的参考资产，具体执行规则以正式 Skill/Rule 文件为准。

背景：为什么要平衡中英文？

问题起源

这个项目是一个中文开发者为自己构建的 Trae Agent 技能系统。所有用户交互自然使用中文，但整套系统的技术底座（CLI 命令、JSON 契约、API 接口、脚本语言、配置文件、Git 提交）本质上是英文的。这带来一个根本矛盾：

用户用中文思考和组织需求，但 agent 用英文技术栈执行。

最初的自然倾向是"既然用户是中文的，那所有内容都用中文"——把错误信息翻译成中文、把 JSON keys 考虑中文化、把 CLI 参数改成中文命名。但实际使用中很快暴露问题：

• 触发不稳定：纯英文 skill 的 trigger phrases 不匹配用户的中文表达，agent 绕过了该激活的 skill

• 执行不精确：纯中文的技术约束过于宽泛（如"保留格式"），agent 的解读与预期不一致

• 机器可读性下降：中文化后的 JSON keys、错误标识在日志检索和工具链中失效

• 跨平台兼容性问题：中文脚本名在 shell 调用、CI 流水线、包管理器中频繁出异常

重构中的认知修正

最关键的认知转变是：

Skill 是写给 agent 读的执行规程，不是写给终端用户读的使用说明书。

这意味着：

• 机器可读性优先于人的直觉可读性

• 技术接口（CLI/JSON/API）必须保持英文原样，只在外围加中文解释

• 中文主要用于触发匹配、用户汇报、业务意图描述

• 脚本的主错误信息保持英文，agent 负责在最终回复中翻译成中文

当前如何实现平衡

经过一次完整的项目重构，平衡策略已通过三层体系落地：

第一层：语言政策（顶层约束）

skills/skill-language-policy/SKILL.md 定义了正式的 English-Required Layers 和 Chinese-Retained Layers，按资产类型（trigger asset / execution contract / template asset / reference asset / human-oriented example）分别指定语言要求。这是所有 Skill 创建的约束基准。

关键规则：JSON keys、CLI flags、config keys、环境变量、API 名称、工具名、函数名、错误标识 → 强制英文；用户回复、触发词、进度汇报 → 可用中文。

第二层：稳定性审查（执行保障）

skills/skill-stability-review/SKILL.md 将语言平衡作为审查维度之一，纳入 Chinese User Fit Without Over-Localization 标准。检查项包括：

• 中文化是否侵入机器敏感层（JSON keys / CLI flags）

• 触发词是否包含中文自然表达 + 英文技术关键词

• 脚本错误是否保持英文稳定

• 中文文档处理是否明确编码、标点、空格、简繁体策略

审查层级优先级：agent 稳定执行 > Windows/Trae 可运行 > 中文用户自然沟通 > 文案统一。

第三层：三级沉淀路径（知识固化）

Knowledge 通过三级路径沉淀，越往上层越适合中文内容：

Core Memory（高频、轻量、自动注入）         → 中文为主，≤400 字符
    ↓ 模式重复 3+ 次
.trae/rules/ 规则（明确触发条件，alwaysApply） → 中英混合，技术约束英文
    ↓ 通用多步骤工作流
skills/ 技能包（完整执行契约）               → 中文触发 + 英文技术骨架

实际效果

当前 35 个 skill 全部采用"中英双语 description + 英文 section headings + 中文用户规则 + 英文技术约束"的混合结构，所有脚本文件均为英文命名，CLI/JSON 无中文化问题。这套平衡策略已在实践中稳定运行。

核心结论

对于中文使用者来说，创建 skill、rule、脚本和子 agent 时，最稳妥的方式不是纯中文，也不是纯英文，而是采用"中文意图 + 英文技术骨架 + 中英双语触发词"的混合策略。

推荐原则：

• 面向用户的回复、业务意图、文档处理要求：中文为主。

• 技术名词、API、CLI、包名、配置 key、函数名、变量名：英文为主。

• Skill / rule 的触发条件：中英双语。

• 脚本代码：英文命名，中文只放在测试样例、用户提示、文档说明中。

• 中文文档处理：明确编码、标点、空格、简繁体、专有名词、可回滚策略。

一句话总结：

让 LLM 用英文技术骨架稳定执行，用中文语义准确理解你的真实意图。

关于"LLM 是否先英文推理再翻译成中文"

"LLM 内部全用英文推理，最后再翻译成中文"这个说法不太准确。

更合理的理解是：

• 模型不是像人一样先写英文草稿再翻译。

• 它在中文、英文、代码、配置、命令、错误日志等多种文本上训练。

• 英文技术资料更多，所以涉及编程、API、框架、工具时，英文概念往往更稳定。

• 中文不会天然降低 LLM 的能力，但纯中文在技术约束上有时不如英文精确。

因此，中文并不是负担。真正需要权衡的是：

• 触发是否稳定；

• 执行是否精确；

• 维护是否方便；

• 是否能避免中文文档处理中的隐性歧义。

为什么不建议纯英文

纯英文 skill / rule 的问题是：如果你平时用中文向 agent 下达任务，触发条件可能不够贴近真实语境。

例如你说：

帮我清洗中文合同里的空格和标点。

但 skill 里只有：

Use this skill for legal document normalization.

模型可能仍然能理解，但缺少中文触发钩子，稳定性会下降。

更好的写法是：

当用户说"处理中文文档 / 清洗中文文本 / 修改合同 / 批量处理 docx"时触发。
Use this skill for Chinese document cleanup, DOCX batch processing, legal text normalization.

实际案例参考 skill-language-policy 的 description 字段，当前所有 skill 均已使用中英双语触发词。

为什么不建议纯中文

纯中文在业务表达上很自然，但在技术约束上可能不够精确。

例如：

保留格式。

这句话过于宽泛。对于 Word 文档处理，更精确的英文技术约束可能是：

Preserve paragraphs, runs, styles, tables, footnotes, comments, and document metadata unless explicitly asked to modify them.

因此：

• 业务规则可以中文写；

• 技术约束建议英文写；

• 两者并存最稳定。

此原则已被正式实现为 skill-language-policy 中的 English-Required Layers 和 Chinese-Retained Layers。

脚本处理中文文档时的常见歧义

以下 6 个歧义点已被融入 skill-stability-review 的 Chinese User Fit Without Over-Localization 审查标准中，此处保留原始分析供理解背景。

编码问题

旧系统导出的 .txt、.csv、日志文件可能不是 UTF-8，而是 GBK、GB18030、Big5 等编码。

建议规则：

When modifying existing Chinese text files, detect the source encoding first and preserve it when possible. Do not overwrite unknown-encoding files as UTF-8 unless explicitly requested.

标点问题

中文全角标点和英文半角标点经常混用。

例如：

• , 和 ，

• . 和 。

• () 和 （）

• : 和 ：

需要明确：

• 是统一为中文标点；

• 统一为英文标点；

• 还是保持原样。

建议规则：

Do not normalize Chinese and English punctuation unless the user explicitly asks for punctuation normalization.

空格问题

中文之间通常不加空格，但中文和英文、数字之间是否加空格属于风格选择。

例如：

• 使用GPT-5处理10个文件

• 使用 GPT-5 处理 10 个文件

建议规则：

Do not insert spaces between Chinese characters. For Chinese-English or Chinese-number boundaries, preserve the original spacing unless the user specifies a style guide.

专有名词问题

产品名、公司名、法律术语、英文缩写不应自动翻译。

例如：

• OpenAI Codex

• Trae

• API

• SaaS

• GDPR

• SLA

建议规则：

Do not translate proper nouns, product names, company names, legal terms, technical acronyms, or quoted text unless explicitly requested.

中文分词歧义

中文没有天然空格，正则脚本容易误伤。

例如：

• "研究生命起源"

• "研究生 命题"

对重要文档，脚本不应做过度语义改写。

建议规则：

Avoid semantic rewriting of Chinese text during batch processing. Prefer structural edits, formatting cleanup, and reversible transformations.

简繁体问题

不要默认进行简繁转换。

建议规则：

Preserve simplified or traditional Chinese script unless the user explicitly asks for conversion.

全局 Rule 推荐模板（已落地为正式 Skill）

⚠️ 此模板已被正式实现为 skills/skill-language-policy/SKILL.md，该文件是项目中语言政策的正式执行标准。以下保留原始设计模板供理解背景和设计思路。

原始模板如下（中英双语版本）：

## Chinese Language and Technical Naming Rules

When working with Chinese-speaking users:

- Respond to the user in Chinese unless they request another language.
- Use Chinese for user-facing explanations, summaries, document comments, and business intent.
- Use English for code identifiers, file names, CLI commands, package names, API names, config keys, environment variables, and error identifiers.
- For skills and rules, include both Chinese and English trigger phrases.
- Preserve original Chinese meaning, terminology, punctuation style, spacing style, and simplified/traditional script unless explicitly asked to normalize them.
- Use UTF-8 by default for new files.
- When modifying existing Chinese text files, detect and preserve the source encoding when possible.
- Do not translate proper nouns, product names, company names, legal terms, technical acronyms, or quoted text unless explicitly requested.
- Do not insert spaces between Chinese characters.
- For Chinese-English or Chinese-number boundaries, preserve the original spacing unless the user specifies a style guide.
- For Chinese document processing, prefer reversible transformations, backups, diffs, or reviewable patches before destructive edits.

## 中文语言与技术命名规则

处理中文用户任务时：

- 除非用户要求其他语言，否则默认用中文回复。
- 面向用户的解释、总结、文档批注、业务意图描述使用中文。
- 代码标识符、文件名、CLI 命令、包名、API 名称、配置 key、环境变量、错误标识使用英文。
- Skill 和 rule 的触发词应同时包含中文和英文。
- 除非用户明确要求，不要擅自改写中文语义、术语、标点风格、空格风格、简繁体。
- 新建文本文件默认使用 UTF-8。
- 修改已有中文文本文件时，应尽量检测并保留原始编码。
- 不要翻译专有名词、产品名、公司名、法律术语、技术缩写和引用文本，除非用户明确要求。
- 不要在中文字符之间插入空格。
- 中文与英文、数字之间是否加空格，应保持原文风格，除非用户提供风格要求。
- 处理中文文档时，优先使用可回滚、可审查的修改方式，例如备份、diff 或 patch。

子 Agent 的语言建议

给子 agent 写任务时，建议使用这种结构：

你是一个中文文档处理 agent。

Your role: Chinese document processing and formatting assistant.

任务目标：
- 清洗中文文档中的明显格式问题。
- 保留原文语义。
- 不翻译专有名词。
- 不改写法律、合同、技术术语。

Technical constraints:
- Use UTF-8 for newly created files.
- Preserve source encoding when modifying existing text files.
- Preserve DOCX structure, styles, tables, comments, and metadata unless explicitly requested.
- Report all transformations in Chinese.

这样既能让 agent 准确理解中文业务目标，也能让技术执行更稳定。

文件与代码命名建议

推荐：

process_chinese_docs.py
normalize_punctuation.ts
extract_docx_comments.js
chinese_document_cleanup.md

不太推荐：

处理中文文档.py
清洗标点.ts
提取批注.js

原因：

• 英文文件名和标识符在跨平台、脚本调用、包管理、CI/CD、日志检索中更稳定。

• 中文可以放在 README、注释、用户提示、测试样例中。

此原则已被严格执行：当前项目中所有脚本（image_tool.py、mineru_to_md.py、review_skills.py、quick_validate.py 等）均为英文命名。

最佳实践清单

• Skill 名称：中英混合或英文为主，中文补充。

• Trigger phrases：必须中英双语。

• 业务规则：中文为主。

• 技术规则：英文为主。

• 脚本代码：英文命名。

• 用户输出：中文。

• 文档处理：明确编码、标点、空格、简繁体、专有名词策略。

• 批量修改：优先生成 diff、备份或可审查报告。

• 涉及 API / CLI / 框架文档：保留英文技术关键词。

最终建议

中文开发者使用 agent 工具时，不需要刻意把所有 skill / rule 都写成英文。

最稳的方式是：

中文表达真实意图，
英文表达技术约束，
中英双语增强触发稳定性。

这不是额外负担，而是非常适合中文用户的 agent 工作方式。

落地实践记录：本次 Skill / Script 适配中遇到的问题与处理方法

以下内容来自一次实际的 Trae global skills 适配过程。这些经验教训已逐步被正式 Skill/Rule 覆盖，此处保留为历史参考和设计 rationale。

Issue 1：把"中文使用者"理解成"所有内容都要中文"

背景：最初曾试图将部分 skill 内容中文化，后来意识到 Skill 是给 agent 读的执行规程，不是给终端用户读的说明书。

处理：确立了"中文负责意图和沟通，英文负责接口和执行"的分工原则。

当前状态：✅ 已正式化为 skill-language-policy/SKILL.md → English-Required Layers 和 Chinese-Retained Layers。

Issue 2：Skill 文档适配了，但脚本没有同步适配

背景：只优化了 SKILL.md，但脚本仍存在 Unix shell 假设、错误退出码不可靠、路径示例不适合 Windows 等问题。

处理：意识到脚本是执行契约的一部分，必须同步检查脚本的 Windows 兼容性、退出码行为、输出格式。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Script Synchronization 和 Mandatory Downgrade Rules。

Issue 3：Unix-only 命令残留

背景：skill 和脚本中存在 export、cat <<EOF、sudo、chmod、rm -rf、~/...、/tmp/... 等高风险 Unix-only 模式。

处理：命令示例优先使用 PowerShell，环境变量用 $env: 写法，路径用 Windows 格式，多行字符串用 PowerShell here-string。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Windows And Trae Adaptation + Red Lines。

Issue 4：容器内部 Linux 命令被误判为 Windows 不适配

背景：MinerU 脚本中 Windows host 调用 Docker 容器，容器内部执行 docker exec <container> /bin/sh -lc "..."，其中包含 find、rm -rf 等 Linux 命令——它们看似 Unix-only 残留，实际是在容器内部执行。

处理：区分 host shell 和 container shell。Windows host 层用 PowerShell，Docker 容器层保留 POSIX 路径和命令。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Path conversion rules 规则："Container-side POSIX commands may be acceptable when clearly executed inside Docker"。

Issue 5：脚本错误信息是否应该中文化

背景：曾把脚本错误信息改为中文（如"解析 spec 失败"），后评估发现脚本错误首先服务于 agent 判断，过度中文化会降低错误类型识别稳定性。

处理：脚本主错误保持英文（Error parsing spec），可加可选中文补充字段（message_zh），agent 最终向用户汇报时翻译成中文。

当前状态：✅ 已正式化为 skill-language-policy/SKILL.md → English-Required Layers；以及 skill-stability-review/SKILL.md → Script Synchronization。

Issue 6：JSON keys、CLI 参数、错误标识被中文化会破坏稳定性

背景：曾考虑将 --input 改为 --输入目录 等方案，后评估发现会破坏工具链、日志检索和 agent 识别稳定性。

处理：JSON keys、CLI flags、config keys、环境变量、API 名称、包名、工具名、函数名、错误标识不翻译。必要时在外围加中文解释。

当前状态：✅ 已正式化为 skill-language-policy/SKILL.md → English-Required Layers。

Issue 7：Skill 触发边界不够明确，容易误触发

背景：仅写"Use this skill for X"不够稳定，中文用户表达更口语化，缺少中文触发词和负向边界时 agent 会误触发或漏触发。

处理：description 加入中文自然表达 + 英文技术关键词 + Do Not Use 边界。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Trigger And Boundary。

Issue 8：失败处理缺失会让 agent 自行猜测

背景：许多 skill 只写成功路径，没有失败路径，导致 agent 在工具不可用、路径错误时自行 improvisation。

处理：每个执行型 skill 都应有 Failure Handling，覆盖输入缺失、路径不存在、工具未安装、网络不可用、输出为空、部分成功/部分失败、是否可重试、何时停止并询问用户。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Agent Executability + Mandatory Downgrade Rules（缺少 Failure Handling 扣分）。

Issue 9：脚本 stdout / stderr 边界不清

背景：agent 执行脚本时，stdout 和 stderr 用途不明确，影响稳定性。

处理：stdout 输出机器可读结果（优先 JSON），stderr 输出进度和诊断信息，非零退出码表示失败。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Script Synchronization。MinerU 脚本（mineru_to_md.py）是符合此模式的参考实现。

Issue 10：Windows 路径与中文文件名的处理

背景：Windows + 中文用户的文件路径包含空格、中文、智能引号、WSL 路径混用等问题。

处理：PowerShell 示例中给路径加双引号，Python 脚本使用 pathlib.Path，批量文件优先用 --input-dir 或 --list-file。

当前状态：✅ 已正式化为 skill-stability-review/SKILL.md → Windows And Trae Adaptation（详细的路径转换规则）。

Issue 11：为了中文用户而牺牲脚本命名稳定性

背景：不建议把脚本文件、函数名、变量名改成中文。英文命名在跨平台、CI、日志检索、工具链中更稳定。

处理：中文可以放在用户提示、README / Skill 文档、测试样例、message_zh 字段、agent 最终回复中。

当前状态：✅ 已正式化为 skill-language-policy/SKILL.md → English-Required Layers。当前所有脚本文件均为英文命名。

Issue 12：语言分层规则

背景：需要为整个项目建立统一的语言分层规则，避免每次做语言决策时重新讨论。

处理：创建了以资产类型为基础的语言分层表。

当前状态：✅ 已正式化为 skill-language-policy/SKILL.md。以下是与该政策对齐的分层参考表：

Issue 13：最终检查清单

背景：需要一个可操作的检查清单，用于交付前的自我审查。

处理：以下清单已对齐当前项目实现，各项标准以正式 Skill/Rule 文件为准。

Trigger & 边界

• description 同时包含中文触发词和英文技术关键词

• 有明确 Do Not Use 负向边界

• 与相邻 skill 无显著重叠

Execution

• 有 Failure Handling，覆盖输入缺失、路径不存在、工具不可用、输出为空

• 工作流步骤有序、可执行

• 输入/输出接口明确

Windows & Trae 适配

• 命令示例使用 PowerShell（非 bash heredoc、export、sudo、chmod、host-side rm -rf）

• 路径示例适合 Windows（非 ~/...、/tmp/...）

• 区分 host shell 和 container shell

Script 稳定性

• 脚本文件名和函数名为英文

• JSON keys、CLI 参数、config keys 保持英文

• stdout 结构化（优先 JSON），stderr 仅承载诊断信息

• 失败时返回非零退出码

• 脚本与 SKILL.md 关于参数、输出路径、格式一致

中文适配

• 用户面向的回复、摘要使用中文

• 中文文档处理明确编码、标点、空格、简繁体、专有名词策略

• 不做未经请求的语义改写

最终原则

可以压缩成一句话：

中文负责意图和沟通，英文负责接口和执行，结构化输出负责稳定性。