gemini-cli 设置项文案规范：名词前置、正向布尔与动词精简的设计原则

在 gemini-cli 的仓库内置技能中，.gemini/skills/string-reviewer 负责审计所有面向用户的字符串，而它引用的设置项专项规范 settings.md 定义了三条核心规则：名词前置命名（Noun-First Labeling）、正向布尔逻辑（Positive Boolean Logic）、动词精简（Verb Stripping）。这三条规则直接约束 packages/cli/src/config/settingsSchema.ts 中数千个设置项的 label 与 description 写法，并经由 npm run docs:settings 自动渲染到用户可见的配置文档。读完本文，你可以理解终端 CLI 设置界面为什么这样命名、如何在自己的项目中落地同一套规则，以及 gemini-cli 如何用“配置加载器中翻转布尔值”这一实现细节保证 true 永远等于 On。

规范的位置：string-reviewer 技能如何引用它

settings.md 并非独立存在，而是 SKILL.md 的附属参考文件。该技能将 Agent 设定为资深 UX Writer，负责审查代码库中“过长、不清晰或不一致”的面向用户字符串，并明确“未经用户批准不得自动改动字符串，只能给出建议”。

SKILL.md 中的关键触发条件是：

If packages/cli/src/config/settingsSchema.ts is modified, confirm labels and descriptions specifically follow the unique Settings guidelines.

也就是说，settings.md 是针对设置项这一特殊场景的专属规则，与技能主文档中通用的写作清单（消除第一人称、目标前置、5 词以内状态更新等）以及术语表 word-list.md 形成三层结构：通用写作原则 → 术语一致性 → 设置项专项规则。术语表中同样与设置文案强相关，例如要求用 show 并与 hide 配对、sign in / sign out 作动词、避免 login / logout 等旧式表达。

规则一：名词前置命名（Noun-First Labeling）

原文档给出的规则与示例：

• 规则： [Noun] [Attribute/Action]
• 示例： Show line numbers 简化为 Line numbers

规则的目的是可扫描性（Scannability）：用户在设置列表里寻找的是“要改的功能”，而不是“要做的动作”。当所有 label 都以名词开头时，列表左侧形成一列主题词，用户可以直接按功能域（如 Line numbers、Banner、Footer）线性扫描，而不必为每个条目重复阅读动词。

从 settingsSchema.ts 的结构看，这个原则与文件组织方式天然契合：schema 按 General、Output、UI 等分类（category） 嵌套，每个 SettingDefinition 同时携带 label、category、description 字段（见该文件第 101–120 行的接口定义）。分类负责“大主题”，label 负责“条目主题”，两者都以名词承载，动作语义则留给描述与开关状态本身。

规则二：正向布尔逻辑（Positive Boolean Logic）

这是三条规则中唯一带实现要求的一条。原文档定义：

• 规则： 将 Disable {feature} 或 Hide {Feature} 替换为 {Feature} enabled 或直接用 {Feature}；
• 示例： Disable auto update 改为 Auto update；
• 实现： 在配置加载器中翻转布尔值，使 true 永远等于 On。

设计动机是认知减负（Cognitive Ease）：消除双重否定。用户面对 Disable auto update 勾选框时，需要完成两层推理——“勾上 = 不禁用 = 功能开启”；而 Auto update 只需一层。对 Agent 和脚本化配置（直接编辑 JSON 文件）而言，正向语义同样消除了 true 到底代表开还是关的歧义。

“实现：翻转布尔值”这条建议在 gemini-cli 中有真实的落地痕迹。当前 settingsSchema.ts 中确实仍残留一批旧风格 label，可作为规则演进前的对照样本：

现有 label	位置	按规则二改造后
Enable Auto Update	settingsSchema.ts#L258	Auto update
Enable Terminal Notifications	settingsSchema.ts#L276	Terminal notifications
Disable Loop Detection	settingsSchema.ts#L1124	Loop detection
Disable LLM Correction	settingsSchema.ts#L1763	LLM correction

这些残留说明该规范是增量演进的：旧条目保持向后兼容（JSON 键名与布尔语义不动，否则会破坏已有用户的 settings.json 配置），而 string-reviewer 技能正是在每次修改 schema 时被要求用新规则审查新增/变更的 label 与 description，防止风格继续发散。

对规则一和规则二而言，改造的正确顺序是先定名词短语，再去掉动作词：Show line numbers → Line numbers（规则一）与 Disable auto update → Auto update（规则二）殊途同归——label 只保留功能名词，开关状态由布尔值本身表达。

规则三：动词精简（Verb Stripping）

原文档定义：

• 规则： 除非动词是特定技术术语的一部分，否则删去 Enable、Use、Display、Show 等冗余的开头动词；
• 示例： Enable prompt completion 改为 Prompt completion。

这条规则与规则一互补：规则一约束“名词必须在前”，规则三约束“动词必须尽量不存在”。值得注意的是它保留了技术术语豁免——比如 settingsSchema.ts#L1743 的 Use Ripgrep 和 settingsSchema.ts#L2293 的 Use OSC 52 Paste 中，“Ripgrep”“OSC 52”是专有工具/协议名，label 需要动词才能成立语义。同样，术语表对 enable 的界定（仅用于“把某个功能或 API 打开”的二进制操作，其他场合用 turn on / turn off）也为豁免边界提供了配套约束。

规则如何闭环：从 schema 到文档的自动化链路

这三条规则的价值不只体现在 UI 层。settingsSchema.ts 文件开头的注释（第 7–10 行）写明：

After adding or updating settings, run npm run docs:settings to regenerate the settings reference in docs/get-started/configuration.md.

即 package.json 中的 docs:settings 脚本会执行 scripts/generate-settings-doc.ts，把 schema 里的 label/description 批量渲染进配置文档；另有一个 scripts/generate-settings-schema.ts 生成 JSON Schema，产物即 schemas/settings.schema.json，供编辑器和 CI 做校验。因此label 的命名质量会被放大到三个出口：交互式设置对话框（showInDialog 字段控制的条目）、自动生成的文档、以及机器可校验的 JSON Schema。这也解释了为何 string-reviewer 技能把 settings.md 列为“unique”规则——设置项文案的改动影响面比普通 UI 字符串更广，值得单独一套标准。

从测试侧看，packages/cli/src/config/settingsSchema.test.ts 所在目录下的 settingsSchema.test.ts、settings-validation.test.ts 等测试会校验 schema 结构的一致性与合法性；结合仓库内置技能体系，人工/Agent 审查（string-reviewer）与自动化测试形成两道互补的防线：前者管“说人话”，后者管“结构正确”。

如何在自己的项目中落地这三条规则

1. 命名阶段（写新设置项时）

   • 先写出功能名词短语（Line numbers、Terminal notifications）；
   • 检查是否残留 Enable / Disable / Show / Hide / Use 前缀，若有且非技术术语，删除之；
   • 布尔语义一律按“功能存在与否”定义，true = 开。

2. 实现阶段

   • 若迁移旧键，在配置加载器中集中做布尔翻转与键名映射，保证磁盘上的旧配置与新语义解耦（正是原文档 Implementation 一条的含义）；
   • 为 schema 文件加注释，要求新增/修改后重新生成文档与 JSON Schema。

3. 审查阶段

   • 参照 string-reviewer 的输出格式做人工审查——以 ❌ 原文 / ✅ 修正 的成对列表呈现，并标注违反了哪条原则：

   1. **Positive Boolean Logic**
     - ❌ "Disable auto update"
     - ✅ "Auto update"
   

   该格式定义在 SKILL.md 的 Output format 一节，保证审查结果可被逐条核对。

小结

settings.md 用不到三十行定义了设置项文案的三条硬规则：名词前置保证可扫描，正向布尔保证可理解，动词精简保证简短。它们之所以在 gemini-cli 中可持续生效，是因为有完整的支撑结构：SKILL.md 定义了“修改 schema 即触发专项审查”的纪律，word-list.md 统一了 show/hide、enable/disable 等词的边界，docs:settings 自动化链路则把 label 质量扩散到文档与 JSON Schema 两个下游出口。这套“规范 + 技能 + 自动化”的组合，是 CLI 项目治理用户可见文案的一个可直接借鉴的范式。