Gemini CLI string-reviewer Skill 解析：终端 Agent 的 UX 文案审查规范与实践

本文为 Gemini CLI 仓库内置的工作区技能（Agent Skill）string-reviewer 撰写技术解析。该技能定义了一套面向终端产品的用户可见文案（user-facing strings）审查体系，覆盖语音原则、可扫描性检查清单、术语表与设置项命名规范。读完后，你将理解如何基于 SKILL.md 结构组织一个文案审查技能，掌握其"确定性清晰度、遥测优先、一步恢复"等核心写作原则，并能复用其固定输出格式对任意 CLI 项目的 UI 文案做系统性审计。

技能定位：一个只审查、不擅改的 UX 文案审核员

string-reviewer 是 Gemini CLI 仓库自带的工作区技能（workspace skill），完整定义位于 SKILL.md。技能采用标准的 frontmatter + 正文结构，frontmatter 中声明了两个字段：

---
name: string-reviewer
description: >
  Use this skill when asked to review text and user-facing strings within the codebase. It ensures that these strings follow rules on clarity,
  usefulness, brevity and style.
---

其中 description 字段决定了技能的触发条件：当用户要求"审查代码库中的文本和用户可见字符串"时，Gemini 会匹配该描述并激活这个技能。这与 Agent Skills 的整体生命周期一致——docs/cli/skills.md 描述了发现（Discovery）、激活（Activation）、同意（Consent）、注入（Injection）、执行（Execution）五阶段流程：会话开始时 CLI 扫描各发现层级，仅将技能的 name 与 description 注入系统提示词；当模型判断任务匹配时调用 activate_skill 工具（详见 docs/tools/activate-skill.md），经用户确认后，SKILL.md 正文才进入对话历史。

技能正文第一节的角色与边界定义非常克制：

• 角色：以"资深 UX 写作者（Senior UX Writer）"身份工作，查找过长、不清晰或不一致的用户可见字符串，范围包括内联文本（inline text）、错误消息（error messages）及其他面向用户的文本。
• 硬性行为边界：未经用户批准不得自动修改任何字符串。技能只能提出修改建议（suggest），除非用户明确要求，否则不允许直接重写。这一条把技能的输出形态锁定为"审计意见"而非"自动补丁"，对审查类技能的设计很有参考价值。

源码视角：这个技能是如何被加载和发现的

从源码结构看，技能的发现与解析逻辑集中在 skillLoader.ts 与 skillManager.ts：

• loadSkillsFromDir 使用 glob 模式 SKILL.md 和 */SKILL.md 扫描目录，因此 string-reviewer 必须位于 .gemini/skills/ 下的独立子目录中才能被发现；
• loadSkillFromFile 用 FRONTMATTER_REGEX 匹配 --- 包裹的 frontmatter，先尝试 YAML 解析，失败时回退到支持多行缩进描述符的简单 key-value 解析器，并把正文（match[2]）作为 body 保存——这正是"延迟披露"机制：只有技能被激活，body 才进入上下文；
• discoverSkills 按"内置 → 扩展 → 用户 → 工作区"的优先级合并同名技能，string-reviewer 位于工作区目录 .gemini/skills/，拥有最高优先级，但前提是工作区被标记为受信任（trusted）。用户也可以通过 /skills disable string-reviewer、/skills list 等命令或 gemini skills 终端命令管理它的启用状态。

五条核心语音原则：确定性清晰优于寒暄

技能正文的 "Core voice principles" 一节给出了 Gemini CLI 文案体系的总纲。原文的表述是："系统优先确定性清晰而非对话式寒暄——提供遥测而非礼节，确保用户保有绝对掌控权"（We provide telemetry, not etiquette）。具体拆解为五条：

1. 确定性清晰（Deterministic clarity）：严格区分"确定性的系统/服务状态"（如 Cloud Billing、IAM、系统本身）与"概率性的 AI 分析"（Gemini 的输出）。系统状态用确定性语言，模型推断用概率性语言。
2. 系统透明性（System transparency）：用主动式技术遥测替换 "Loading..." 这类空转占位。例如 "Tracing stack traces..."。状态更新（status updates）控制在 5 个单词以内。
3. 前置可执行性（Front-loaded actionability）：始终采用 [目标] + [动作]（[Goal] + [Action]）模式，把意图放在句首，让用户从左到右扫读时一眼看到目的。
4. Agent 式错误恢复（Agentic error recovery）：每个错误都必须是一个"转折点"（pivot point），失败信息要搭配一键恢复命令或建议提示词（suggested prompt）。
5. 上下文谦逊（Contextual humility）：免责声明和"小心"类警告只保留给 P0（破坏性/不可逆）任务。原文点名了"warning-fatigue"（警告疲劳）——警告泛滥等于没有警告。

写作检查清单：四类可执行审计规则

技能的 "The writing checklist" 是实际执行审查时的主操作手册，分为四个子模块，每条规则都可直接判定违规。

身份与语音（Identity and voice）

• 消除 "I"：删除所有第一人称代词（I、me、my、mine）；
• 主语归属：AI 一律称 Gemini，基础设施一律称 the system 或 the CLI；
• 主动语态：确保执行动作的主语（Gemini 或 system）明确；
• 所有权规则（Ownership rule）：执行（doing）归属 system，分析（thinking）归属 Gemini——这条规则与前述"确定性清晰"原则互相咬合：系统做的操作是确定的，模型的分析是概率的。

结构可扫描性（Structural scannability）

• Skip test（跳过测试）：句子的前 3 个词是否描述了用户的意图？不能，就重写；
• 目标优先句式：模板为 [To Accomplish X] + [Do Y]；
• 5 词规则：状态更新和加载态不得超过 5 个词；
• 遥测优于礼节：删掉礼貌填充语（"Please wait"、"Thank you"、"Certainly"），替换为原始数据或进度指示；
• 微状态循环（Micro-state cycles）：耗时超过 3 秒的任务，循环展示具体子状态（如 "Parsing logs... ➔ Identifying patterns..."）以体现推进感。

技术准确性与谦逊（Technical accuracy and humility）

• 动词信号检查（Verb signal check）：描述系统状态/基础设施用确定性动词（is、will、must）；描述 AI 输出用概率性动词（suggests、appears、may、identifies）；
• 禁止 100% 断言：绝不把绝对确定性归因于模型生成的内容；
• 精度优先：用技术指标（latency、tokens、compute）替代模糊的 "speed" 或 "cost"；
• 指令性警告：每条警告必须附带具体纠正动作，原文示例为 "Perform a dry-run first" 或 "Review line 42"。

Agent 式错误恢复（Agentic error recovery）

• 一步规则（The one-step rule）：每条错误信息恰好搭配一条即时修复路径（命令、链接或提示词）——"恰好一条"是为了避免把决策成本推回给用户；
• 人先于机（Human-first）：先给人类可读的解释，再给出机器错误码（如 404、500）；
• 建议提示词（Suggested prompts）：给出可复制/点击的具体文本，原文示例为 Ask Gemini: "Explain this port error."。

术语表约束：references/word-list.md

检查清单之后，技能要求所有术语与项目术语表对齐。SKILL.md 中原文的相对链接 ./references/word-list.md 在仓库中的实际位置是 word-list.md，它把词表分为三档，规则粒度细到具体词形：

推荐用词（Preferred），每条都给出了使用场景：

推荐词	规则说明
create	用户创建或设置某物时使用
allow	表示"已获准执行某动作"，替代 may
canceled	用单 l 拼写，不用 cancelled
configure	指改变特性属性的过程，即使只是开关特性
delete	动作具有破坏性时使用
enable	仅用于"把特性/API 打开"的二元操作；其余场景用 "turn on/turn off"
key combination / key sequence	同时按下的多键 / 依次按下的多键
modify / update	"内容已变更"用 modify，"获取最新版本"用 update
remove	从整体中移出但不销毁该项
set up / setup	动词用 set up，名词或形容词用 setup
show / hide	成对使用
sign in / sign out	动词用 sign in、sign out；名词用 sign-in、sign-out
want	替代 like 或 would like

禁用词（Don't use）：etc.（系列不完整时改用 "such as" 引入）、hostname（改为 host name）、in order to（过于正式，通常用 "Before you can"）、one or more（尽量给出具体数量，不确定时用 "at least one"）、全部 log in / log on / login / logout / log out 变体、like / would you like（改写为不指涉用户情绪状态的表述）。

谨慎使用（Use with caution）：避免把 leverage 当动词（被视为无实义的 buzzword）；避免用 once 当 "after" 的同义词；不用 e.g.（用 example、such as、like、for example，短语后必须跟逗号）；i.e. 除非空间所迫一律改用 "that is"；disable 与 enable 对称地只用于二元操作，不可用的 UI 元素用 "dimmed" 而非 "disabled"；please 只在请用户做不便之事时使用；really 只用于确认用户极不可能执行的动作（"Do you really want to..."）。

审查流程的约定是：如果某个字符串使用了标记为 "do not use" 或 "use with caution" 的词，必须基于推荐词给出修正。

设置项命名规范：references/settings.md 与 settingsSchema.ts

SKILL.md 中有一个明确的触发条件：只要修改了 settingsSchema.ts，就必须确认其中的 label 和 description 遵循专门的设置项指南（原文相对链接 ./references/settings.md，仓库实际路径为 settings.md）。该指南针对设置界面这类高密度文本，提出了三条命名规则：

1. 名词先行标注（Noun-First Labeling）：label 必须以设置对象的主体名词开头而非动作，让用户扫读时按功能定位。规则形式为 [名词] [属性/动作]。原文示例：Show line numbers 简化为 Line numbers。
2. 正向布尔逻辑（Positive Boolean Logic）：消灭双重否定。布尔值应表示特性的"存在"而非"缺席"。规则：把 Disable {feature} 或 Hide {feature} 改为 {Feature} enabled 或直接用 {Feature}。原文示例：把 "Disable auto update" 改成 "Auto update"。实现层面要求在配置加载器中反转布尔值，使 true 恒等于 On。
3. 动词剥离（Verb Stripping）：删掉冗余的前导动词（"Enable"、"Use"、"Display"、"Show"），除非该动词是特定技术名词的一部分。原文示例：Enable prompt completion 改为 Prompt completion。

值得注意的是，仓库中被审查对象之一的 packages/cli/src/config/settingsSchema.ts 是一个 3600 余行的 TypeScript 模式定义文件，其中每个设置项都带有 description 等人类可读字段——这些字段正是 string-reviewer 在设置项变更场景下的审计对象，且文件头部注释要求修改设置后运行 npm run docs:settings 重新生成文档，说明文案一致性是该项目流程化的质量环节。

固定输出格式：让审查结果可机器核对

技能的最后一节 "Output format" 对审查输出的形态做了封闭约束：建议修改时必须使用如下列表格式呈现，且不允许在列表之外给出建议（原文强调 "Do not provide suggestions outside of this list"）：

1. **{理由/违反的原则}**
  - ❌ "{错误表述}"
  - ✅ `"{修正表述}"`

这个格式有三个工程价值：

• 每条建议强制绑定一条已声明的原则（Rationale/Principle Violated），使审查结论可回溯到上文的原则体系，而不是自由发挥；
• 错误与修正成对出现且位置固定（❌/✅），方便用户在代码评审中逐条 accept/reject；
• 封闭的列表结构天然抑制"附带一堆额外建议"的输出膨胀，与"未经批准不得自动修改"的边界约束形成闭环。

小结：从一份技能文档看 CLI 产品文案工程

string-reviewer 的价值不在于某一条具体词规，而在于它把"终端 AI 产品应该怎么说"固化为一套可被 Agent 执行、可被逐条判定的规范：

• 角色层面：只建议、不擅改，把修改决策权留给人；
• 原则层面：确定性系统状态与概率性 AI 输出在动词上严格分流，用遥测替代寒暄，用 5 词上限约束状态更新，用"一步规则"约束错误消息；
• 执行层面：术语表分三档（推荐/禁用/谨慎）精确到词形，设置项命名遵循名词先行、正向布尔、动词剥离；
• 输出层面：固定 原则 → ❌ → ✅ 的封闭格式。

结合 docs/cli/skills.md 与 skillLoader.ts 的渐进披露机制可以看出，这类技能是"按需加载的专家流程"：平时只占 name + description 的极小上下文，激活后才注入完整检查清单与参考文档（references/ 目录下的词表与设置指南属于技能目录内的捆绑资源，激活后模型可读取）。对于维护任何面向终端用户产品的团队，这套"原则 + 检查清单 + 术语表 + 固定输出格式"的技能组织方式，是一个可以直接借鉴的文案治理模板。