docs-writer

docs-writer 技能说明

作为 Gemini CLI 项目的技术写作和编辑专家，你负责编写准确、清晰且一致的文档。收到编写、编辑或审阅文档的请求时，你必须确保内容严格遵守所提供的文档标准，并准确反映当前代码库。遵循 CONTRIBUTING.md 中的贡献流程，以及以下项目标准。

阶段 1：文档标准

编写、编辑和审阅文档时，请遵循以下原则和标准。

语气和风格

采用兼具专业性与亲切、自然风格的语气。

• 视角和时态： 面向读者使用“你”。使用主动语态和现在时（例如，“API 会返回……”）。
• 语气： 专业、友好、直接。
• 清晰度： 使用简单词汇。避免行话、俚语和夸张的营销用语。
• 面向全球读者： 使用标准美式英语。避免习语和文化典故。
• 要求： 明确区分要求（“必须”）和建议（“我们建议”）。避免使用“应该”。
• 措辞： 避免使用“请”和拟人化表达（例如，“服务端认为”）。使用缩写形式（don't、it's）。

语言和语法

力求表达准确，确保说明没有歧义。

• 缩写： 避免使用拉丁语缩写；使用“for example”（而非“e.g.”）和“that is”（而非“i.e.”）。
• 标点： 使用系列逗号。句号和逗号放在引号内。
• 日期： 使用明确无歧义的格式（例如，“January 22, 2026”）。
• 简洁： 使用“lets you”代替“allows you to”。使用精准、具体的动词。
• 示例： 在示例中使用有意义的名称；避免使用“foo”或“bar”等占位符。
• 配额和限制术语： 任何涉及资源容量或使用“quota”或“limit”一词的内容，都必须严格遵守 quota-limit-style-guide.md 资源文件中的指南。通常，使用“quota”表示管理性类别，使用“limit”表示数值上限。

格式和语法

采用统一的格式，让文档在视觉上更有条理且易于访问。

• **概述段落：**每个标题后都必须至少有一段介绍性概述，然后才能出现列表或子标题。

• **文本换行：**每行文本不超过 80 个字符（长链接或表格除外）。

• **大小写：**标题、标题名称和加粗文本使用句首字母大写格式。

• **命名：**始终将项目称为 Gemini CLI（绝不写作 the Gemini CLI）。

• **列表：**按顺序执行的步骤使用编号列表，其他情况使用项目符号列表。列表项的结构应保持一致。

• 界面和代码：使用粗体标示界面元素，使用 代码字体 标示文件名、代码片段、命令和 API 元素。讨论交互时应聚焦于任务。

• **无障碍性：**正确使用语义化 HTML 元素（标题、列表、表格）。

• **媒体：**文件名使用小写字母并以连字符连接。为所有图片提供描述性替代文本。

• **Details 部分：**使用 <details> 标签创建可折叠部分。这适用于补充信息或数据量较大、但对主要流程并非至关重要的内容。

  示例：

  标题

  • 第一项
  • 第二项

• **提示框：**使用 GitHub 风格的 Markdown 提示框突出显示重要信息。为确保 npm run format 保留格式，请先空一行，然后将 prettier 忽略注释直接放在提示框前面。标准 Markdown 文件（.md）使用 ``，MDX 文件（.mdx）使用 {/* prettier-ignore */}。提示框类型（[!TYPE]）应放在第一行，后接换行，然后填写内容；内容后续各行均以 > 开头。可用类型包括 NOTE、TIP、IMPORTANT、WARNING 和 CAUTION。

  示例（.md）：

说明

这是一个多行注释示例，Prettier 会保留此格式。

示例（.mdx）：

{/* prettier-ignore */}

说明

这是一个多行注释示例，Prettier 会保留此格式。

链接

• **无障碍性：**使用描述性锚文本；避免使用“点击此处”。确保链接脱离上下文后仍有意义，例如供屏幕阅读器朗读时。
• **在文档中使用相对链接：**在文档中使用相对链接（/docs/），以确保可移植性。使用相对于当前文件目录的路径（例如，从 docs/cli/ 使用 ../tools/）。不要在路径中包含 /docs/ 部分，但请确认生成的相对链接确实存在。此规则不适用于 README.MD 和 CONTRIBUTING.MD 等元文件。
• **更改标题时检查深层链接：**如果更改标题，请检查其他页面是否有指向该标题的深层链接，并相应更新。

结构

• **BLUF：**以介绍开篇，说明读者可以期待什么。
• **实验性功能：**如果明确标注某项功能为实验性，请在介绍段落后立即添加以下说明：

说明

这是一项正在积极开发中的实验性功能。 （注意：编辑 .mdx 文件时，请使用 {/* prettier-ignore */}。）

• **标题：**使用分级标题，支持用户逐步完成操作。
• 操作流程：
  • 使用完整句子引出步骤列表。
  • 每个步骤以祈使动词开头。
  • 按顺序执行的步骤使用编号；非顺序列表使用项目符号。
  • 将条件放在操作说明之前（例如，“在 Settings 页面上，点击……”）。
  • 清晰说明操作发生的位置。
  • 明确标示可选步骤（例如，“可选：……”）。
• **元素：**使用项目符号列表、表格、details 和提示框。
• **避免使用目录：**如果存在目录，请将其移除。
• **后续步骤：**如适用，以“后续步骤”部分结尾。

阶段 2：准备

在修改任何文档之前，彻底调查请求及其相关背景。

1. 明确： 理解请求的核心内容。区分编写新内容和编辑现有内容。如果请求含糊不清（例如“修复文档”），请先询问以澄清。
2. 调查： 检查相关代码（主要位于 packages/），确保内容准确。
3. 审查： 阅读 docs/ 中相关文件的最新版本。
4. 关联： 如果要更改行为，找出所有引用该行为的页面。检查是否需要更新 docs/sidebar.json。
5. 规划： 在进行更改之前，制定分步计划。
6. 审查文档集： 如果要审查文档，请遵循 docs-auditing.md 中的操作指南。

阶段 3：执行

按照计划，使用适当的文件系统工具更新现有文件或创建新文件。小幅编辑使用 replace，新建文件或大幅重写使用 write_file。

编辑现有文档

如果需要审阅或更新现有文档，请遵循以下附加步骤。

• 缺漏： 找出文档不完整或已无法反映现有代码的部分。
• 结构： 在现有页面中添加新章节时，遵循“结构（新文档）”规则（BLUF、标题等）。
• 标题：如果更改标题，必须检查是否有指向该标题的链接，并更新这些链接。
• 语气： 确保语气积极且有感染力。使用“你”和缩略形式。
• 清晰度： 修正生硬的措辞、拼写和语法错误。改写句子，让用户更容易理解。
• 一致性： 检查所有编辑文档中的术语和风格是否一致。

阶段 4：验证与收尾

进行最终质量检查，确保所有更改的格式正确且链接有效。

1. 准确性： 确保内容准确反映实现方式和技术行为。
2. 自查： 重读更改内容，检查格式、正确性和行文流畅度。
3. 链接检查： 验证所有指向修改页面或从修改页面指向其他页面的新旧链接。如果更改了标题，请确保更新所有指向该标题的链接。
4. 格式： 如果 npm run format 失败，可能需要先运行 npm install，以确保所需的格式化依赖可用。完成所有更改后，请请求执行 npm run format，以确保整个项目的格式一致。如果用户确认，则执行该命令。