写作风格指南

在专用风格指南中定义团队的写作规则，并确保每一位贡献者——无论是人还是 GitBook Agent——都保持一致。

样式指南承载着你团队的写作规则和约定。它是你网站内容应如何撰写的唯一权威来源——包括语气和风格、术语、格式和结构。

样式指南面向两个对象：

• 你的团队： 撰写者和审阅者共享同一个参考，知道该如何写作，因此无论是谁编辑，文档都能保持一致。
• GitBook 代理： 代理会读取你的样式指南，并将其视为它在撰写、编辑或审阅内容时必须遵循的唯一权威来源。它会覆盖代理自身的默认设置和通用写作约定。

GitBook 代理如何使用你的样式指南

GitBook 代理会在每次任务中将样式指南的首页完整加载到上下文中，因此该页面始终主导它的工作。它只会在需要时通过目录读取其他页面。

把你的主要规则放在首页。 把你希望强制执行的每条规则都放在那里，并使用其他页面补充代理在相关时可调用的细节。你的编辑始终优先：修改规则后，代理会遵循你的版本；删除规则后，代理就不再执行它。

样式指南是代理唯一的规则来源。如果你的样式指南提到了上游指南——例如 Google 或 Microsoft 的指南——并把它们作为基础，那么这种提及只是给人类读者看的背景信息，不是给代理的指令。若某个约定对你很重要，就把它写下来。

可执行规则与指导建议

样式指南将内容分为两个层级，区别在于规则是否带有编号 ID：

• 编号规则 （例如 G-10 或 MS-9）属于可执行层级。代理会直接标记这些规则的违规，并引用 ID，因此你可以把任何标记追溯到触发它的具体规则。
• 无编号指导 ——例如语气描述——属于判断层级。代理在撰写时会应用它，并将其作为建议供人工审阅，但不会把它标记为违规。

要添加一条可执行规则，请为它分配当前最高编号之后的下一个编号，无论该规则位于何处。切勿重新编号或重复使用 ID——过往标记和你的决策日志都引用它们。随着时间推移，编号未必会与页面顺序一致；这很正常。ID 的唯一作用就是保持稳定。

在入门模板中， SG- 前缀可以由你更改——但一旦开始使用该指南，就要保持稳定。

创建样式指南

你可以从两个位置开始设置样式指南：

• 在你网站的侧边栏中，进入 工具，点击 风格指南，然后点击 设置.
• 打开 设置 → 样式指南 并从那里进行设置。

然后选择一个起点（如下所述）：

• 复用你组织中已有的样式指南。
• 选择一个模板——入门、Google 或 Microsoft。
• 如果你已经有样式指南，可以上传文件或从 URL 导入。

第一次打开样式指南时，GitBook 会显示一个简短介绍，说明你可以像编辑其他内容一样编辑它。

使用已有样式指南

如果你的组织在其他地方已经有正在使用的样式指南，它们会显示在设置界面的顶部，并列出使用它们的网站。选择其中一个后，你可以：

• 按原样使用 ——将其作为共享样式指南附加给其他使用它的网站。编辑会应用到所有使用它的地方。
• 分叉 ——为该网站创建一个专用副本（命名为 样式指南 - {site name}），你可以独立演进它。

选择一个模板

GitBook 提供三种可供起步的模板：

模板	最适合
入门模板	从零定义你自己的语气和规则。每个部分都解释了应放什么内容以及原因，并提供你自行填写的框架。
Google 样式指南	面向开发者受众的清晰、精准、专业写作。基于 Google 开发者文档样式指南生成。
Microsoft 样式指南	面向广泛受众的温暖、简洁、有人情味的写作——包括非技术专家读者。基于 Microsoft 写作风格指南生成。

Google 和 Microsoft 模板预先填充了来自其源指南的可执行规则——涵盖语气、词汇表、语法、格式、流程、无障碍写作和包容性语言——可直接按原样使用。所有内容都可由你自行编辑：模板只是起点，不是合同。

当源指南发生变化时，GitBook 会审查并更新基础模板，因此模板会保持与其生成来源指南同步。

自定义“需要你填写”部分

每个模板都会用 需要你填写 提示标出你必须自定义的部分。在样式指南可投入使用之前，请逐一完成这些内容——通常包括：

• 模板所反映的基础指南版本的快照日期（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.
• 负责人和更新： 负责人、审查周期，以及如何提出更改。没有人负责的指南会逐渐变成虚构。
• 决策日志： 你的组织记忆。更改一条规则就会改变代理执行的内容；日志会记住原因，因此已达成共识的争议仍能保持已达成共识。在这里记录所有与基础指南不同的有意偏离。

编辑你的样式指南

编辑样式指南的方式与你编辑文档其他部分的方式相同：

• 在 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 代理提供的网站级自定义指令的补充。自定义指令是简短、针对单个网站的说明；样式指南则是你写作规则的完整共享文档。