> 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）风格一致。 风格指南包含你团队的写作规则和惯例。它是关于你网站内容应如何撰写的唯一事实来源——包括语气和风格、术语、格式以及结构。 风格指南面向两个受众： * **你的团队：** 撰写者和审阅者都有一个共同参考，了解应如何写作，因此无论是谁编辑，文档都能保持一致。 * **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 形式编辑。 要打开你的风格指南，请使用你网站侧边栏中的 **风格指南** 条目，或在 **编辑** 中的 **设置 → 风格指南**. ### 在站点之间共享风格指南 风格指南属于你的组织，因此多个站点可以依赖同一个指南——编辑代理会在所有地方应用相同的写作规则，你的所有文档也会保持统一的风格。 创建风格指南后，GitBook 会提供将其链接到你组织中尚未拥有风格指南的其他站点。你也可以在设置站点时附加现有风格指南——共享或分叉的都可以，如前所述。 要查看你组织中的每个风格指南以及各自被哪些站点使用，请打开组织侧边栏中的 **风格指南** 条目。 #### 解除风格指南关联 要停止某个站点使用其风格指南，请打开 **设置 → 风格指南** 并点击 **解除关联**。解除关联会保留该风格指南——它仍可能被其他站点使用。如果没有其他站点引用它，GitBook 会提供永久删除它。 ### 让你的风格指南发挥作用 有了风格指南之后，你可以让 GitBook Agent 对现有文档进行一次检查，使其与风格指南保持一致。从那时起，Agent 每次撰写、编辑或审阅内容时都会检查是否遵守你的风格指南——对带编号规则的违规会用其 ID 标记，而对无编号指导则作为人工审阅建议提供。 对你的更改运行风格指南审查主要有两种方式： #### 在请求审查之前先审查页面 在处理页面时，你可以让 Agent 根据你的风格指南检查该页面——在“改进”菜单中使用 **根据风格指南检查一致性** ，或在聊天中提出。Agent 会审查页面并留下总结其发现的评论。 #### 在变更请求上请求风格指南审查 当你的站点有风格指南时，GitBook Agent 会作为建议审阅者出现在你的变更请求中，并标记为 **风格指南审查**: 1. 在你的变更请求中，点击 **请求审查**. 2. 为你的更改添加标题和说明——或者点击 **生成** 让 Agent 根据你的更改来撰写它们。 3. 下方 **审阅者**下，点击 **Request** 旁边 **GitBook 代理** ，让它对该变更请求进行风格指南审查。你可以同时添加人工审阅者，或者将列表留空以通知你组织中的所有审阅者。 Agent 会根据风格指南审查你的更改，如果发现违规，就会在变更请求上请求修改，并引用产生每个标记的规则。 #### 在整个站点运行风格指南检查 如果你想检查的是现有内容而不是变更，请从风格指南本身运行一个 **风格指南检查** 。一次检查会根据你的规则审查一个空间中的每一页，并将它发现的问题修复到一个变更请求中供你审阅。 1. 打开你的风格指南并点击 **运行检查**. 2. 选择要检查的空间。一次最多可以检查三个空间。 3. 审阅并合并 GitBook Agent 为每个空间打开的变更请求。 GitBook Agent 会为每个空间打开一个变更请求，并逐页处理其内容。如果检查修复了某些问题，其变更请求会标记为可供审阅；如果什么也没发现，其变更请求会被归档，因此你不会留下一个空草稿。 该 **检查** 选项卡会按站点自身结构列出站点的各个空间，并显示每个空间检查的状态：变更请求的状态、检查运行时的加载指示器、上次运行时间，以及一个 **自风格指南编辑以来** 徽章，表示你在检查后修改了指南。点击某一行即可打开其变更请求。 一个空间同一时间只有一个检查变更请求。如果在某个空间的检查仍然打开时再次运行检查，它会更新该变更请求，而不是打开另一个；Agent 会按当前状态检查页面。只有在前一个变更请求被合并或归档之后，才会打开新的变更请求。 ### Agent 如何执行你的风格指南 当 GitBook Agent 使用你的风格指南时，它的工作是遵守你的规则，而不是改善一般写作。它的设计目标是精准、保守且一致：同一内容在同一风格指南下检查，始终会产生相同的结果。 #### 你的风格指南是唯一的规则来源 除非规则写在你的风格指南中，否则 Agent 永远不会应用来自上游指南、来自对良好风格的一般认知，或来自它所知任何风格指南的规则。 Agent 还会尊重关于你规则写法的几件事： * **占位规则处于未激活状态。** 模板页面包含类似 `[产品名称]` 或 `[添加规则]`的方括号占位文本。其内容仍然只是占位文本的规则还不算真正的规则——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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.