> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide.md). # 写作指南 样式指南承载着你团队的写作规则和约定。它是关于你网站内容应如何撰写的唯一事实来源——包括语气和风格、术语、格式以及结构。 样式指南服务于两个对象： * **你的团队：** 撰写者和审校者共享同一份写作参考，因此无论谁来编辑，文档都能保持一致。 * **GitBook Agent：** Agent 会读取你的样式指南，并将其视为在撰写、编辑或审查内容时必须遵循的唯一事实来源。它会覆盖 Agent 自身的默认设置和通用写作约定。 ### GitBook Agent 如何使用你的样式指南 GitBook Agent 会在每个任务中将样式指南的第一页完整载入上下文，因此该页始终主导其工作。它只会按需读取其他页面，使用目录来定位。 **把主要规则放在第一页。** 把你希望强制执行的所有规则都放在那里，并将更多细节放在 Agent 在相关时可以调入的附加页面中。你的编辑始终优先：修改一条规则，Agent 就遵循你的版本；删除一条规则，Agent 就停止执行它。 样式指南是 Agent 唯一的规则来源。如果你的样式指南提到一个上游指南——例如 Google 或 Microsoft 的指南——作为基础，那么这只是给人类读者的背景信息，而不是对 Agent 的指令。若某项约定对你很重要，就把它写下来。 #### 可执行规则与指导 样式指南会将内容分为两个层级，而区别就在于规则是否带有编号 ID： * **编号规则** （例如 `G-10` 或者 `MS-9`）属于可执行层级。Agent 会直接标记对它们的违规，并引用 ID，这样你就能把任何标记追溯到触发它的确切规则。 * **未编号指导** ——例如对语气的描述——属于判断层面。Agent 在撰写时会应用这些内容，并将其作为建议提供给人工审阅，但绝不会把它们标记为违规。 要添加一条可执行规则，请为它分配当前最高编号之后的下一个编号，无论该规则位于何处。切勿重排编号或重复使用 ID——过去的标记和你的决策记录都会引用它们。随着时间推移，编号可能不会与页面顺序一致；这很正常。ID 的唯一作用就是保持稳定。 {% hint style="info" %} 在入门模板中， `SG-` 前缀可以由你更改——但一旦开始使用该指南，就要保持稳定。 {% endhint %} ### 创建样式指南 你可以从两个位置开始设置样式指南： * 在网站侧边栏中，进入 **工具**，点击 **样式指南**，然后点击 **设置**. * 打开 **设置 → 样式指南** 并在那里进行设置。 然后选择一个起点（如下所述）： * 重用你组织中已有的样式指南。 * 选择一个模板——入门、Google 或 Microsoft。 * 如果你已经有样式指南，可以上传文件或从 URL 导入。 首次打开样式指南时，GitBook 会显示一段简短介绍，说明你可以像编辑其他内容一样编辑它。 #### 使用现有样式指南 如果你的组织已经在其他地方使用样式指南，它们会显示在设置屏幕顶部，并附带使用它们的网站。选择其中一个后，你可以： * **按原样使用** ——将其作为共享样式指南连接到使用它的其他网站。编辑会应用到所有使用它的地方。 * **分支复制** ——为该网站创建一个专用副本（命名为 `样式指南 - {site name}`），你可以独立演进它。 #### 选择模板 GitBook 提供三种可供起步的模板：
模板适用对象
入门模板从零开始定义你自己的语气和规则。每个部分都会解释那里应该包含什么以及原因，由你自行补充内容。
Google 样式指南面向开发者受众的清晰、准确、专业的写作。根据 Google 开发者文档样式指南生成。
Microsoft 样式指南面向广泛受众的温暖、简洁、有人情味的写作——包括非技术专家读者。根据 Microsoft 写作风格指南生成。
Google 和 Microsoft 模板已预先填入来自其源指南的可执行规则——涵盖语气、词汇表、语法、格式、流程、无障碍写作和包容性语言——并可直接按原样使用。所有内容都可由你编辑：模板只是起点，不是契约。 {% hint style="info" %} 当源指南发生变化时，GitBook 会审查并更新基础模板，因此模板会保持与其生成来源指南同步。 {% endhint %} **自定义“需要你补充”的部分** 每个模板都会用一个 **需要你补充** 提示标出你必须自定义的部分。在样式指南可正式使用之前，请完成这些部分——它们通常包括： * 模板所反映的基础指南版本的快照日期（Google 和 Microsoft 模板） * 你的产品名称和文档使命 * 谁阅读和撰写你的文档，以及该指南涵盖什么 * 你的产品名称、功能名称，以及团队争论过的任何术语，加入词汇表中 * 负责人、审查频率，以及如何提交修改建议 * 决策记录中的第一条条目 没有提示标记的内容都已预先填好，可以直接使用。你还未填写的占位规则处于非激活状态——在你用真实内容替换占位符之前，Agent 不会执行它们。 #### 上传文件 如果你已经在其他工具中维护样式指南，可以导入它，而不是从模板开始： 1. 在设置屏幕中，点击 **上传文件**. 2. 拖放你的 Markdown、HTML、DOCX 或 ZIP 文件，或者浏览选择它们。 3. 可选地，启用 **使用 AI 增强导入** 以自动优化并清理导入的内容。 4. 点击 **开始导入**. #### 从 URL 导入 如果你的样式指南已在线发布，GitBook 可以直接导入： 1. 在设置屏幕中，点击 **从 URL 导入**. 2. 输入你要导入的文档链接。 3. 可选地，启用 **使用 AI 增强导入** 以自动优化并清理导入的内容。 GitBook 会导入你输入的 URL 下所有公开页面，最多 200 页。例如，如果你导入 `website.com/docs/`，它会包含 `website.com/docs/article`，但不包含 `website.com/other-parent/page`。对于更大的站点，请分别导入更小的子路径。 ### 样式指南中应包含什么 当样式指南记录的是团队中容易出错或容易不一致的决策时，它最有价值。各模板采用相同结构，每个部分都会解决一种不同的风格争议： * **简介：** 该指南是做什么的，以及你的文档是做什么的。具有明确目的的指南会被持续维护；没有目的的会被弃用。 * **受众和范围：** 谁阅读你的文档、谁撰写它们，以及该指南涵盖什么。半数的风格争议其实都是伪装成风格争议的受众争议；在这里一次性解决。 * **语气和风格：** 你如何称呼读者，以及你有多正式或友好，再加上对可机械检查内容的可执行规则，例如标点和缩写。 * **词汇表：** 你的产品名称、精确大小写、首选术语，以及已解决的术语争议。只记录团队曾讨论过的术语；条目要简短。 * **语法和规则：** 针对人称、时态和语态的句子级默认设置。例外列与规则本身同样重要：它能防止 Agent 错误标记合法文本。 * **格式：** 标题大小写、界面元素、链接、代码，以及何时使用列表、步骤器、提示和其他区块。 * **写作流程：** 步骤格式、祈使动词、每步一项操作。 * **错误消息和失败状态：** 为读者最紧张的时刻制定语气规则。可选；如果你的文档不包含错误文本，可以删除这一部分。 * **无障碍写作** 并 **包容性语言：** 几乎通用、可检查的规则，大多数团队都会按原文采用。 * **内容类型和模板：** 你的页面类型，这样撰写者和 Agent 就知道页面应遵循哪种结构。许多团队会使用像 [Diátaxis](https://diataxis.fr/). * **这样的框架** 负责人和更新： * **决策记录：** 你的机构记忆。更改一条规则就会改变 Agent 执行的内容；记录会记住原因，因此已达成一致的争议不会再次被翻出。请在这里记录对基础指南的每一次有意偏离。 ### 编辑你的样式指南 你编辑样式指南的方式，与编辑文档其余部分的方式相同： * **在 GitBook 中：** 先在变更请求中进行修改，然后在准备好时合并。 * **使用 Git Sync：** 如果样式指南已同步到 GitHub 或 GitLab，请在仓库中以 Markdown 形式编辑。 要打开你的样式指南，请使用网站侧边栏中的 **样式指南** 条目，或 **编辑** 中的 **设置 → 样式指南**. ### 在网站之间共享样式指南 样式指南属于你的组织，因此多个网站可以共用同一个指南——编辑 Agent 会在各处应用相同的写作规则，而你的所有文档都会遵循统一的风格。 创建样式指南后，GitBook 会建议将其链接到你组织中尚未拥有样式指南的其他网站。你也可以在设置网站时，按前文所述附加一个现有样式指南——共享版或分支版都可以。 要查看你组织中的每个样式指南以及哪些网站在使用它，请打开组织侧边栏中的 **样式指南** 条目。 #### 解除样式指南关联 要停止某个网站使用其样式指南，请打开 **设置 → 样式指南** 并点击 **分离**。解除关联会保留该样式指南——它可能仍被其他网站使用。如果没有其他网站引用它，GitBook 会提供将其永久删除。 ### 让你的样式指南发挥作用 有了样式指南之后，请让 GitBook Agent 对你现有的文档进行一次检查，使其与样式指南保持一致。从那时起，Agent 会在每次撰写、编辑或审查内容时检查是否遵守你的样式指南——对编号规则的违规会标记其 ID，而将未编号指导作为建议供人工审阅。 在你的变更中运行样式指南审查主要有两种方式： #### 在请求审查前先审查页面 在编辑页面时，你可以让 Agent 根据样式指南检查该页面——在“改进”菜单中使用 **检查与样式指南的一致性** ，或者在聊天中提出。Agent 会审查页面并留下评论，总结它发现的问题。 #### 在变更请求上请求样式指南审查 当你的网站有样式指南时，GitBook Agent 会作为建议审阅者出现在你的变更请求中，并带有标签 **样式指南审查**: 1. 在你的变更请求中，点击 **请求审查**. 2. 为你的修改添加标题和说明——或者点击 **生成** 让 Agent 根据你的修改来写。 3. 在 **审阅者**，点击 **Request** 旁边的 **GitBook 代理** 让它对该变更请求执行样式指南审查。你可以同时添加人工审阅者，或者将列表留空以通知你组织中的所有审阅者。 Agent 会根据样式指南审查你的修改，如果发现违规，就会在变更请求上请求更改，并引用触发每个标记的规则。 ### Agent 如何执行你的样式指南 当 GitBook Agent 与你的样式指南配合工作时，它的任务是让内容符合你的规则——而不是做通用写作改进。它被设计得精确、保守且一致：同一内容在同一样式指南下进行检查，始终会得到相同结果。 #### 你的样式指南是唯一的规则来源 Agent 从不上游指南、通用写作知识或其所知的任何样式指南中套用规则，除非该规则写在你的样式指南里。 Agent 还会尊重关于规则写法的几点要求： * **占位规则处于非激活状态。** 模板页面包含带方括号的占位文本，例如 `[Product name]` 或者 `[Add a rule]`。如果某条规则的内容仍是占位文本，那它还不算真正的规则——Agent 不会执行它。如果你的样式指南大多是占位符，Agent 会告诉你它大部分尚未填写，并且执行仅限于你已完成的规则，而不会把部分完成的指南说成是完整无缺的。 * **例外会被尊重。** 许多规则都附带例外（“当施事者未知时，被动语态是可以的”）。落入列出例外范围内的文本不构成违规。 * **明确规则即使没有 ID 也算数。** 如果你写了一条没有编号 ID 的规则，但它读起来像一条明确、可检查的指令（“绝不要使用分号”），Agent 也会执行它，并用简短引文而不是 ID 来引用它。 #### 当 Agent 审查时 在样式指南审查期间——无论是页面还是变更请求——Agent 只会标记问题，不会更改任何内容。每个标记都包括： * **规则：** 来自你样式指南中的规则 ID（例如 `G-10`），如果没有 ID，则为规则的简短引文。 * **位置：** 问题出现的标题或行，以及有问题的文本。 * **问题：** 一句说明违规情况的话。 * **修正：** 可直接粘贴的更正后文本。 每轮审查上限为 **5 个标记**。如果还有更多问题，Agent 会报告优先级最高的 5 个，并以一行说明还有其他问题及其数量作结。标记会按类别排序——先是措辞和术语，其次是格式和标点，然后是语法，最后是流程——在同一类别中，则按页面顺序排序。 未编号指导——语气、风格和结构建议——绝不会作为标记出现。最多情况下，Agent 会在每轮末尾添加一条合并的“值得人工查看”的备注，涵盖判断层面的所有内容。 #### 当 Agent 编辑时 当你要求 Agent 修复内容或使其与你的样式指南一致时，它会在修正明确无歧义的地方直接应用编号规则。当一条规则有两种都说得通的结果时，Agent 会保持文本不变，并将其列为建议，而不是猜测。 编辑完成后，Agent 会按规则 ID 分组输出变更摘要，并附上数量——例如，“G-7：将‘click on’替换为‘click’，共 6 处。”判断层面的建议会在末尾单独列成一个简短列表。 #### Agent 绝不会触碰的内容 在审查和编辑中，Agent 绝不会标记或更改： * 代码块、行内代码、命令输出，或 API 和产品标识符中的内容 * 直接引用和被引用材料 * 被规则自身例外条款豁免的文本 * 内容的含义或事实 * 仅受不在你样式指南中的规则覆盖的任何内容 #### 一致性 Agent 会按原文执行规则，即使它可能“不同意”——它绝不会为了适配内容而弱化、强化或重新解释某条规则。如果某条规则按原文来说有歧义，Agent 会按字面理解执行，并在其人工审阅备注中指出该歧义，而不是擅自揣测意图。如果你的网站没有配置样式指南，Agent 不会退回到通用判断——它会转而提供帮助你创建一份样式指南。 ### 样式指南与自定义指令 样式指南是对你可以提供给 GitBook Agent 的站点级自定义指令的补充。自定义指令是简短、站点特定的说明；样式指南则是完整、共享的写作规则文档。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.