> 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 代理：** 代理会读取你的样式指南，并将其视为它在撰写、编辑或审阅内容时必须遵循的唯一权威来源。它会覆盖代理自身的默认设置和通用写作约定。 ### GitBook 代理如何使用你的样式指南 GitBook 代理会在每次任务中将样式指南的首页完整加载到上下文中，因此该页面始终主导它的工作。它只会在需要时通过目录读取其他页面。 **把你的主要规则放在首页。** 把你希望强制执行的每条规则都放在那里，并使用其他页面补充代理在相关时可调用的细节。你的编辑始终优先：修改规则后，代理会遵循你的版本；删除规则后，代理就不再执行它。 样式指南是代理唯一的规则来源。如果你的样式指南提到了上游指南——例如 Google 或 Microsoft 的指南——并把它们作为基础，那么这种提及只是给人类读者看的背景信息，不是给代理的指令。若某个约定对你很重要，就把它写下来。 #### 可执行规则与指导建议 样式指南将内容分为两个层级，区别在于规则是否带有编号 ID： * **编号规则** （例如 `G-10` 或 `MS-9`）属于可执行层级。代理会直接标记这些规则的违规，并引用 ID，因此你可以把任何标记追溯到触发它的具体规则。 * **无编号指导** ——例如语气描述——属于判断层级。代理在撰写时会应用它，并将其作为建议供人工审阅，但不会把它标记为违规。 要添加一条可执行规则，请为它分配当前最高编号之后的下一个编号，无论该规则位于何处。切勿重新编号或重复使用 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 模板） * 你的产品名称和文档使命 * 谁阅读和撰写你的文档，以及该指南覆盖什么内容 * 你的产品名、功能名，以及你团队争论过的任何术语，加入词汇表 * 负责人、审查周期，以及如何提出更改 * 决策日志中的第一条记录 没有提示标记的内容都已预填，可直接使用。你尚未填写的占位规则是不生效的——在你用真实内容替换占位符之前，代理不会执行它们。 #### 上传文件 如果你已经在其他工具中维护样式指南，可以导入它，而不是从模板开始： 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`。对于更大的网站，请分别导入更小的子路径。 ### 样式指南中应包含什么 当样式指南能记录那些容易出错、或者在团队中不一致的决策时，它最有用。模板共享相同的结构，而每个部分都解决不同类型的风格争议： * **简介：** 该指南的用途以及你的文档的用途。带有明确目的的指南会得到维护；没有目的的指南会被弃置。 * **受众与范围：** 谁阅读你的文档、谁撰写它们，以及该指南覆盖什么。半数风格争议其实都是伪装成风格争议的受众争议；在这里一次解决它们。 * **语气与风格：** 你如何称呼读者，以及你的正式程度或亲切程度；还包括任何可机械检查内容的可执行规则，例如标点和缩写。 * **词汇表：** 你的产品名称、确切大小写、首选术语，以及已确定的术语争议。只记录团队讨论过的术语；条目保持简洁。 * **语法与机制：** 句子层面的默认设置，如人称、时态和语态。例外列的重要性不亚于规则本身：它能防止代理误标合法文本。 * **格式：** 标题大小写、界面元素、链接、代码，以及何时使用列表、步骤器、提示和其他块。 * **写作流程：** 步骤格式、祈使动词、每步一个动作。 * **错误消息和失败状态：** 针对读者最紧张时刻的语气规则。可选；如果你的文档不包含错误文本，就删除这一部分。 * **无障碍写作** 以及 **包容性语言：** 大多数团队都会按原样采用的、几乎普适且可检查的规则。 * **内容类型和模板：** 你的页面类型，这样作者和代理就知道页面应遵循哪种结构。许多团队使用像 [Diátaxis](https://diataxis.fr/). * **负责人和更新：** 负责人、审查周期，以及如何提出更改。没有人负责的指南会逐渐变成虚构。 * **决策日志：** 你的组织记忆。更改一条规则就会改变代理执行的内容；日志会记住原因，因此已达成共识的争议仍能保持已达成共识。在这里记录所有与基础指南不同的有意偏离。 ### 编辑你的样式指南 编辑样式指南的方式与你编辑文档其他部分的方式相同： * **在 GitBook 中：** 在变更请求中进行修改，然后在准备好后合并。 * **使用 Git 同步：** 如果样式指南已同步到 GitHub 或 GitLab，就在仓库中以 Markdown 形式编辑。 要打开你的样式指南，请使用 **风格指南** 位于你网站侧边栏中的条目，或 **编辑** 中的操作 **设置 → 样式指南**. ### 跨网站共享样式指南 样式指南属于你的组织，因此多个网站可以依赖同一个样式指南——编辑代理会在所有地方应用相同的写作规则，你所有的文档也会遵循统一的语气。 创建样式指南后，GitBook 会提出将其链接到你组织中尚未拥有样式指南的其他网站。你也可以在设置网站时附加一个已有的样式指南——共享或分叉的，如前所述。 要查看你组织中的所有样式指南以及每个指南被哪些网站使用，请打开 **样式指南** 组织侧边栏中的条目。 #### 分离样式指南 若要停止某个网站使用其样式指南，请打开 **设置 → 样式指南** 并点击 **分离**。分离不会删除样式指南——它可能仍被其他网站使用。如果没有其他网站引用它，GitBook 会提供将其永久删除。 ### 让你的样式指南发挥作用 有了样式指南之后，请让 GitBook 代理检查你现有的文档，并使其符合样式指南。从那时起，代理每次撰写、编辑或审阅内容时都会检查是否遵循你的样式指南——对带编号规则的违规使用其 ID 进行标记，并把无编号指导作为供人工审阅的建议。 对你的更改进行样式指南审查主要有两种方式： #### 在请求审查前先审查页面 在编辑页面时，你可以让代理根据你的样式指南检查该页面——在“改进”菜单中使用 **按样式指南检查一致性** ，或者在聊天中提出。代理会审查页面并留下总结其发现的评论。 #### 在变更请求上请求样式指南审查 当你的网站有样式指南时，GitBook 代理会作为建议审阅者出现在你的变更请求中，并标记为 **样式指南审查**: 1. 在你的变更请求中，点击 **请求审查**. 2. 为你的更改添加标题和描述——或者点击 **生成** 让代理根据你的更改来写它们。 3. 在 **审阅者**，点击 **Request** 旁边的 **GitBook Agent** 让它对该变更请求执行样式指南审查。你可以同时添加人工审阅者，或者保持列表为空以通知你组织中的所有审阅者。 代理会根据样式指南审查你的更改，如果发现违规，就会在变更请求上要求修改，并引用产生每个标记的规则。 ### 代理如何执行你的样式指南 当 GitBook 代理使用你的样式指南时，它的任务是确保符合你的规则——而不是进行通用写作优化。它的设计目标是精确、保守且一致：同一内容在同一样式指南下进行检查，始终会得到相同的结果。 #### 你的样式指南是唯一的规则来源 除非规则写在你的样式指南中，否则代理绝不会应用来自上游指南、来自对优秀文体的一般认知，或来自它所知道的任何样式指南中的规则。 代理还会尊重你规则写法中的一些特性： * **占位规则不生效。** 模板页面包含方括号中的占位文本，例如 `[产品名称]` 或 `[添加一条规则]`。其内容仍是占位文本的规则还不算真正的规则——代理不会执行它。如果你的样式指南大部分都是占位符，代理会告诉你它大多尚未填充，并且执行仅限于你已完成的规则，而不会把部分完成的内容当作全面通过。 * **会尊重例外。** 许多规则都带有例外（“在行为主体未知时，被动语态是可以接受的”）。落入已列出例外范围的文本不属于违规。 * **明确规则即使没有 ID 也算数。** 如果你写了一条没有编号 ID 的规则，但它读起来是明确、可检查的指令（“绝不要使用分号”），代理也会执行它，并用一段简短引用而不是 ID 来引用它。 #### 当代理审查 在样式指南审查期间——无论是页面还是变更请求——代理会标记问题，但不会更改任何内容。每个标记都包含： * **规则：** 来自你样式指南的规则 ID（例如 `G-10`），或者如果该规则没有 ID，则提供一段简短引用。 * **位置：** 问题发生的标题或行，以及有问题的文本。 * **问题：** 说明违规的一句话。 * **修复：** 可直接粘贴的修正文本。 审查最多限制为 **每次 5 个标记**。如果问题更多，代理会报告优先级最高的 5 个，并在末尾用一行说明还有其他问题，同时给出数量。标记按类别排序——首先是用词和术语，然后是格式和标点，再然后是语法，最后是流程——在同一类别内则按页面顺序。 无编号指导——语气、风格和结构建议——绝不会显示为标记。最多情况下，代理会在每次审查中附上一条合并的“值得人工看一下”的备注，涵盖所有判断层级的内容。 #### 当代理编辑时 当你让代理修正内容或使其符合样式指南时，它会在修复明确无歧义的地方直接应用带编号规则。当一条规则有两种都可辩护的结果时，代理会保持文本不变，并将其列为建议，而不是猜测。 编辑后，代理会按规则 ID 输出一份更改摘要，并附带数量——例如，“G-7：将‘click on’替换为‘click’，共 6 处。”判断层级的建议会在末尾单独列成一个简短清单。 #### 代理永远不会触碰什么 无论是审查还是编辑，代理都不会标记或更改以下内容： * 代码块、行内代码、命令输出，或 API 和产品标识符中的内容 * 直接引用和被引用材料 * 被规则自身例外条款排除的文本 * 内容的含义或事实 * 仅由不在你的样式指南中的规则覆盖的任何内容 #### 一致性 代理会按规则原文执行，即使它可能“不同意”——它绝不会为了适配内容而弱化、强化或重新解释规则。如果一条规则按原文有歧义，代理会按字面意思应用，并在供人工审阅的备注中指出歧义，而不是擅自推断意图。而且，如果你的网站没有配置样式指南，代理不会退回到一般判断——它会改为提供帮助你创建一个样式指南。 ### 样式指南与自定义指令 样式指南是对你可以给 GitBook 代理提供的网站级自定义指令的补充。自定义指令是简短、针对单个网站的说明；样式指南则是你写作规则的完整共享文档。 --- # 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.