写作指南

在专门的写作指南空间中定义团队的写作规则，确保每位贡献者，无论是人还是 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 的唯一作用就是保持稳定。

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

创建风格指南

你可以从多个位置开始设置风格指南：

• 在你的网站仪表盘中，前往 工具，点击 风格指南，然后点击 设置.
• 打开 站点设置 → 风格指南 并在此进行设置。

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

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

首次打开风格指南时，GitBook 会显示一段简短介绍，说明你可以像编辑其他空间一样编辑它。

使用现有风格指南

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

• 按原样使用 ——与其他使用它的站点共享关联。编辑会应用到所有使用它的地方。
• 分叉它 ——为此站点创建一个专用副本（命名为 风格指南 - {site name}），你可以独立演进它。

选择模板

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

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

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

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

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

每个模板都会用 需要你填写 提示标出你必须自定义的部分。在风格指南可用之前，请先完成这些部分——它们通常包括：

• 模板所反映的基础指南版本快照日期（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 标记合法文本。
• 格式： 标题大小写、UI 元素、链接、代码，以及何时使用列表、步骤条、提示和其他块。
• 写作流程： 步骤格式、祈使动词、每步只做一件事。
• 错误消息和失败状态： 用于读者压力最大的时刻的语气规则。可选；如果你的文档不包含错误文本，就删除它。
• 无障碍写作 和 包容性语言： 几乎通用、可检查的规则，大多数团队都会按原文采用。
• 内容类型和模板： 你的页面类型，这样写作者和 Agent 就知道页面应遵循什么结构。许多团队使用类似 Diátaxis.
• 所有权与更新： 负责人、审查节奏，以及如何提出更改。没有负责人管理的指南会逐渐变成空谈。
• 决策日志： 你的组织记忆。修改一条规则会改变 Agent 执行的内容；日志会记录原因，因此已解决的争议仍保持已解决。在这里记录你对基础指南所做的每一次有意偏离。

编辑你的风格指南

风格指南本身就是一个空间，因此你编辑它的方式与编辑其他文档相同：

• 在 GitBook 中： 先在更改请求中进行修改，准备好后再合并。
• 使用 Git Sync： 如果风格指南空间已同步到 GitHub 或 GitLab，请在你的仓库中以 markdown 形式编辑。

要打开你的风格指南，请使用你网站侧边栏中的 风格指南 入口，或 编辑 操作中的 站点设置 → 风格指南.

跨站点共享风格指南

风格指南属于你的组织，因此多个站点可以依赖同一份风格指南——编辑 Agent 会在所有地方应用相同的写作规则，而你所有文档都会遵循统一的语气。

创建风格指南后，GitBook 会建议将其链接到你组织中尚未拥有风格指南的其他站点。你也可以在设置站点时附加现有风格指南——共享或分叉的，如前所述。

要查看你组织中的每一份风格指南以及哪些站点使用它，请打开组织侧边栏中的 风格指南 入口。

解除风格指南关联

要让某个站点停止使用其风格指南，请打开 站点设置 → 风格指南 并选择 解除关联。解除关联会保留该风格指南空间——它可能仍被其他站点使用。如果没有其他站点引用它，GitBook 会建议永久删除它。

让你的风格指南发挥作用

有了风格指南之后，要求 GitBook Agent 对你现有的文档进行一次检查，使其与风格指南保持一致。从那以后，Agent 每次写作、编辑或审校内容时都会检查是否遵守你的风格指南——对带编号规则的违规标注其 ID，并将无编号建议作为供人工审校的建议提出。

对你的更改运行风格指南审校主要有两种方式：

在请求审校前先审查页面

在处理页面时，你可以要求 Agent 将该页面与风格指南对照检查——在“改进”菜单中使用 检查与风格指南的一致性 ，或者直接在聊天中提出。Agent 会审查页面并留下评论，总结它发现的内容

在更改请求上请求风格指南审校

当你的站点有风格指南时，GitBook Agent 会作为更改请求的建议审校者出现，并带有标签 风格指南审校:

1. 在你的更改请求中，点击 请求审校.
2. 为你的更改添加标题和描述——或者点击 生成 让 Agent 根据你的更改来撰写它们。
3. 在 审校者，点击 中， 旁边的 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 提供的站点级自定义指令的补充。自定义指令是简短的、站点专属的指引；风格指南则是一份完整的、共享的写作规则文档。