gemini-cli 字符串评审技能术语规范：word-list.md 中的产品级用词规则全解

本文以 gemini-cli 仓库内置 string-reviewer 技能的核心参考文档 word-list.md 为主体，完整拆解该术语表（word list）中“推荐词、禁用词、慎用词”三档共 29 条用词规则的来龙去脉，并结合 技能加载源码 与 真实 UI 字符串 等仓库证据，说明这套规范如何被 Agent 实际执行、如何落地到 CLI 的用户可见文案中。读完后，你既能掌握一份可直接复用的终端产品文案术语表，也能理解 gemini-cli 如何通过 Skill 机制把文案风格约束变成可自动执行的评审流程。

string-reviewer 技能与术语表在项目中的定位

gemini-cli 仓库在 .gemini/skills/string-reviewer 目录下内置了一个名为 string-reviewer 的技能，其 SKILL.md 的 frontmatter 明确写着：当被要求评审代码库中的文本和用户可见字符串时，使用该技能确保字符串在清晰度、实用性、简洁性和风格上符合规则。技能由三部分组成：

文件	职责
SKILL.md	技能入口：定义“资深 UX 写作者”角色、五大声音原则（确定性清晰、系统透明、动作前置、代理式错误恢复、语境谦逊）与评审输出格式
word-list.md	本文主体：统一术语表，分“Preferred（推荐）/ Don't use（禁用）/ Use with caution（慎用）”三档
settings.md	针对 settingsSchema.ts 中设置项标签的专项规范（名词开头、正向布尔逻辑、去动词化）

SKILL.md 中与术语表直接相关的指令是：所有术语必须与项目的 word list 保持一致；若某字符串使用了标记为“do not use”或“use with caution”的术语，评审者必须基于推荐词给出修改建议。也就是说，word-list.md 不是普通的风格备忘，而是 Agent 执行术语一致性检查时的“判罚依据”。

技能本身只包含指令与参考文档，不包含可执行脚本，属于典型的“提示词型技能”。它的加载由 skillLoader.ts 负责：loadSkillsFromDir 会在给定目录中用 glob 匹配 SKILL.md 与 */SKILL.md 两类路径（skillLoader.ts#L127），这正是 .gemini/skills/string-reviewer/SKILL.md 能被项目级发现的原因；随后 loadSkillFromFile 解析 frontmatter 中的 name 与 description（支持 YAML 解析失败时回退到逐行解析，见 skillLoader.ts#L34-L61），将正文作为 body 注入。因此 word-list.md 这类 references/ 下的文档不会被单独索引，而是由 SKILL.md 的正文以相对路径链接、由 Agent 在执行时按需读取——SKILL.md 中 [word list](https://gitcode.com/GitHub_Trending/gemi/gemini-cli/blob/3c311beac2e78336816dd4a123db39743f9fbf85/.gemini/skills/string-reviewer/references/word-list.md?utm_source=gitcode_repo_files) 这类链接即为此设计。

推荐词（Preferred）：16 条优先使用的动词与名词规则

word-list.md 的第一档规则全部以“Use X”形式给出，要求评审时优先采用以下写法：

1. create：用户“创建或搭建某物”时用 create。
2. allow：表示“已授予执行某操作的权限”时用 allow，替代 may。
3. canceled：单 l 拼写，不用 cancelled。
4. configure：指代“修改某功能属性”的过程，即使包含开启/关闭该功能也用 configure。
5. delete：当动作具有破坏性（销毁数据）时用 delete。
6. enable：仅用于“打开某功能或 API”的开关型（binary）操作；其他非开关场景改用 “turn on / turn off”。
7. key combination：指“同时按下多个键”（如快捷键）。
8. key sequence：指“按顺序先后按下多个键”。
9. modify：指“某物已发生变化”，与“获取最新版本”的动作区分开。
10. remove：当动作只是“把某项从更大的整体中取出”但不销毁该项本身时用 remove。
11. set up：作动词时用分写的 set up；作名词或形容词时用合写的 setup。
12. show：展示/隐藏语义用 show，并总体与 hide 配对使用。
13. sign in / sign out：作动词用分写的 sign in、sign out；作名词或形容词用带连字符的 sign-in / sign-out。
14. update：表示“获取某物的最新版本”。
15. want：替代 like 或 would like，用于表达用户意图。

这组规则的内在逻辑值得注意：它把“状态变更动词”做了精细切分——enable/disable 只留给二态开关（第 6 条与慎用档第 5 条呼应），delete/remove 按“是否销毁”切分（第 5、10 条），modify/update 按“内容变了还是版本变了”切分（第 9、14 条），set up/setup 按词性切分（第 11 条）。评审时违反任何一条都应给出替换建议。

推荐词在仓库代码中有真实对应物。例如认证对话框中的按钮文案就是规则 13 的直接体现——AuthDialog.tsx#L47 中的选项标签为 Sign in with Google，用的是分写的动词式 “Sign in”，与术语表要求完全一致；其测试 AuthDialog.test.tsx 也把 defaults to Sign in with Google 作为断言文案。

禁用词（Don't use）：6 条一票否决规则

第二档规则全部以 “Don't use” 开头，评审命中即应直接修正：

1. etc.：冗余，表达列举不完整时改用 “such as” 引入。
2. hostname：不用合成词，写 “host name”。
3. in order to：过于正式，UI 文本中 “Before you can” 通常更好。
4. one or more：应尽量给出确定数量；数量为 1 及以上但不确定时用 “at least one”；用户必须选择 1 及以上时同样用 “at least one”。
5. log in / log on / login / logout / log out：全部禁用（对应规则 13 的 sign in / sign out 体系）。
6. like / would you like：用 want 替代；更好的做法是整句重构，不再描述用户的情绪状态，而是直接说明系统需要什么。

第 5 条与推荐档第 13 条构成完整的“登录/登出”术语闭环：仓库中 Sign in with Google 的写法说明禁用档规则并非纸面要求，而是与现有代码文案互相印证。

慎用词（Use with caution）：7 条需逐条权衡的规则

第三档规则介于推荐与禁用之间，要求评审者结合语境判断并给出理由：

1. leverage：尽量避免，尤其不要作动词使用——它被视为除 “use” 之外几乎毫无信息量的 buzzword。
2. once：避免把 once 用作 “after” 的同义词；这种用法后接的通常是完成时态动词。
3. e.g.：不用 e.g.，改用 “example”、“such as”、“like” 或 “for example”；该短语（指替代写法）后总应跟逗号。
4. i.e.：除非排版空间实在受限，否则不用 i.e.，改用 “that is”。
5. disable：仅用于关闭功能或 API 的开关型操作；非开关场景改用 “turn on / turn off”；对不可用的 UI 元素，用 “dimmed” 而非 “disabled”。
6. please：只在请求用户做不方便的事时使用，常规流程的指令性步骤中不加 please。
7. really：在 “Do you really want to...” 这类结构中慎用；因其加重决策分量，只应用于用户极小概率会执行的动作确认。

第 5 条与推荐档第 6 条共同界定了 enable/disable 的唯一合法用法，也解释了为什么术语表要同时出现这两条：enable 管“开”，disable 管“关”，其余场景一律落到 turn on / turn off。

术语表如何与技能流程、设置项规范协同

word-list.md 的评审结果并非孤立存在，而是嵌入 SKILL.md 定义的整体工作流：

• 只建议、不擅改：SKILL.md 明确要求“未经用户批准不得自动修改字符串，只能给出建议”，因此术语表的每条命中都会以建议形式呈现。
• 固定输出格式：所有修改建议必须使用如下列表格式（来自 SKILL.md#L91-L99）：

1. **{Rationale/Principle Violated}**
  - ❌ "{incorrect phrase}"
  - ✅ `"{corrected phrase}"`

• 与声音原则叠加检查：除了术语一致性，同一字符串还会被“5 词状态更新规则”“目标 + 动作句式”“错误必须配一条恢复路径”等原则共同审计，术语表负责其中“用词”这一维度。
• 设置项专项规则：当 settingsSchema.ts 被修改时，标签与描述还需额外满足 settings.md 的三条规则——名词开头（Show line numbers → Line numbers）、正向布尔（Disable auto update → Auto update，并在配置加载器中反转布尔值使 true 恒等于 On）、去冗余动词（Enable prompt completion → Prompt completion）。这可以视为 word-list 术语哲学（精确、简洁、正向表达）在“设置标签”这一特定场景的强化版。

在 gemini-cli 中使用这套术语规范的实操路径

结合技能加载机制，使用方式如下：

1. 确认技能已就位：项目级技能目录为 .gemini/skills/（从 memory.ts 中 '.gemini/skills' 的路径常量可见项目级与全局 ~/.gemini/skills 两级目录划分），本仓库已在 string-reviewer 目录 内置该技能；技能发现依赖目录下的 SKILL.md 文件及其 frontmatter（name + description，见 skillLoader.ts#L41-L61）。
2. 触发评审：在会话中明确请求，例如“使用 string-reviewer 技能评审这段新增的错误文案”。技能描述（frontmatter 中 “Use this skill when asked to review text and user-facing strings”）会被加载进上下文，Agent 据此加载 SKILL.md 正文，并按需读取 references 下的 word-list.md。
3. 核对结果：输出的每条建议应能对应到 word-list 的具体条款（Preferred/Don't use/Use with caution 中的哪一条），且严格遵循上文固定的 “❌/✅” 列表格式；超出该格式的建议属于技能未正确执行。
4. 边界提醒：该技能面向英文用户可见文案；术语表中的规则（如 canceled 单 l、set up 分写）都是英语语境下的约定，中文文案评审不应机械套用。

小结

word-list.md 用 29 条规则把“好文案”翻译成了可判定、可执行的检查项：16 条推荐词划定了动词与名词的标准用法，6 条禁用词给出一票否决项，7 条慎用词保留了语境判断空间。配合 SKILL.md 的角色设定、输出格式约束与 settings.md 的设置项专项规则，它构成了 gemini-cli 内建的一整套“Agent 可执行的文案风格治理”——而这背后由 skillLoader.ts 的技能发现与 frontmatter 解析机制保证 .gemini/skills 下的每个技能都能被项目自动装载。对任何需要约束终端产品文案一致性的团队，这套“frontmatter 技能 + references 术语表”的结构本身也值得参考。