写作风格指南
在专门的写作风格指南中定义团队的写作规则，并保持每位贡献者（无论是人类还是 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 的唯一作用就是保持稳定。
创建风格指南
你可以从两个位置开始设置风格指南：
在你的网站侧边栏中，在 改进下，点击 写作风格指南，然后点击 设置.
打开 设置 → 风格指南 并从那里进行设置。
然后选择一个起点（如下详述）：
重用你组织中的现有风格指南。
选择一个模板——入门、Google 或 Microsoft。
如果你已经有风格指南，可以上传文件或从 URL 导入。
当你第一次打开风格指南时，GitBook 会显示一段简短介绍，说明你可以像编辑其他内容一样编辑它。
使用现有风格指南
如果你的组织在其他地方已经有正在使用的风格指南，它们会显示在设置屏幕顶部，并附带使用它们的站点。选择其中一个后，你可以：
直接使用 ——将其与使用它的其他站点共享关联。编辑会应用到所有使用它的地方。
分叉 ——为这个站点创建一个专用副本（命名为
风格指南 - {site name}），你可以独立演进它。
选择一个模板
GitBook 提供三个可供起步的模板：
入门模板
从零开始定义你自己的语气和规则。每个部分都会解释这里应包含什么以及原因，并提供你自行填写的框架。
Google 风格指南
为开发者受众撰写清晰、准确且专业的内容。生成自 Google 开发者文档风格指南。
Microsoft 风格指南
为广泛受众撰写温暖、简洁、亲切的内容——包括不熟悉技术的读者。生成自 Microsoft 写作风格指南。
Google 和 Microsoft 模板已预先填充来自其源指南的可强制执行规则——涵盖语气、词汇表、语法、格式、流程、无障碍写作和包容性语言——并可直接使用。所有内容都可由你自行编辑：模板只是起点，不是契约。
自定义“需要你输入”部分
每个模板都会用 需要你输入 提示标记出你必须自定义的部分。在你的风格指南可供使用之前，请完成这些部分——它们通常包括：
模板所反映的基础指南版本的快照日期（Google 和 Microsoft 模板）
你的产品名称和文档使命
谁阅读和编写你的文档，以及该指南涵盖什么
你的产品名称、功能名称以及团队有争议的术语，添加到词汇表中
负责人、审查频率，以及如何提出更改
决策记录中的第一条记录
所有没有提示标记的内容都已预填并可直接使用。你尚未填写的占位规则处于未激活状态——在你用真实内容替换这些占位符之前，Agent 不会执行它们。
上传文件
如果你已经在其他工具中维护了风格指南，也可以导入它，而不是从模板开始：
在设置屏幕中，点击 上传文件.
拖放你的 Markdown、HTML、DOCX 或 ZIP 文件——或者浏览选择它们。
可选地，启用 使用 AI 增强导入 以自动优化和清理导入的内容。
点击 开始导入.
从 URL 导入
如果你的风格指南已在线发布，GitBook 可以直接导入：
在设置屏幕中，点击 从 URL 导入.
输入你想导入的文档链接。
可选地，启用 使用 AI 增强导入 以自动优化和清理导入的内容。
GitBook 会导入你输入的 URL 下的所有公开页面，最多 200 页。例如，如果你导入 website.com/docs/，它会包含 website.com/docs/article，但不包含 website.com/other-parent/page。对于更大的站点，请分别导入更小的子路径。
风格指南中应包含什么
当风格指南记录了那些团队里容易写错或不一致的决策时，它最有用。模板采用通用结构，每个部分都解决一类不同的风格争议：
介绍： 指南的用途以及你的文档用途。明确说明用途的指南会被维护；没有说明用途的会被弃置。
受众和范围： 谁阅读你的文档、谁编写它们，以及该指南涵盖什么。一半的风格争议其实都是伪装成风格争议的受众争议；在这里一次性解决它们。
语气和风格： 你如何称呼读者，以及你是正式还是亲切，再加上任何可机械检查内容的可强制执行规则，例如标点和缩写。
词汇表： 你的产品名称、准确大小写、首选术语，以及已解决的术语争议。只记录团队讨论过的术语；条目要简洁。
语法和机械规则： 句子级默认设置，如人称、时态和语态。例外列和规则列同样重要：它能防止 Agent 标记合法文本。
格式： 标题大小写、界面元素、链接、代码，以及何时使用列表、步骤器、提示和其他块。
写作流程： 步骤格式、祈使动词、每步一个动作。
错误消息和失败状态： 适用于读者压力最大的时刻的语气规则。可选；如果你的文档不包含错误文本，可以删除这一部分。
无障碍写作 和 包容性语言： 几乎通用、可检查的规则，大多数团队都会按原样采用。
内容类型和模板： 你的页面类型，让撰写者和 Agent 知道页面应遵循什么结构。许多团队会使用类似 Diátaxis.
所有权和更新： 负责人、审查频率，以及如何提出更改。没有负责人的指南会逐渐变成虚构。
决策记录： 你的机构记忆。更改一条规则会改变 Agent 执行什么；记录会记住原因，因此已解决的争议仍然保持解决。把每次有意偏离基础指南的情况都记录在这里。
编辑你的风格指南
你编辑风格指南的方式与编辑其余文档相同：
在 GitBook 中： 在变更请求中进行修改，然后在准备好时合并。
使用 Git Sync： 如果风格指南已同步到 GitHub 或 GitLab，请在仓库中以 Markdown 形式编辑。
要打开你的风格指南，请使用你网站侧边栏中的 风格指南 条目，或在 编辑 中的 设置 → 风格指南.
在站点之间共享风格指南
风格指南属于你的组织，因此多个站点可以依赖同一个指南——编辑代理会在所有地方应用相同的写作规则，你的所有文档也会保持统一的风格。
创建风格指南后，GitBook 会提供将其链接到你组织中尚未拥有风格指南的其他站点。你也可以在设置站点时附加现有风格指南——共享或分叉的都可以，如前所述。
要查看你组织中的每个风格指南以及各自被哪些站点使用，请打开组织侧边栏中的 风格指南 条目。
解除风格指南关联
要停止某个站点使用其风格指南，请打开 设置 → 风格指南 并点击 解除关联。解除关联会保留该风格指南——它仍可能被其他站点使用。如果没有其他站点引用它，GitBook 会提供永久删除它。
让你的风格指南发挥作用
有了风格指南之后，你可以让 GitBook Agent 对现有文档进行一次检查，使其与风格指南保持一致。从那时起，Agent 每次撰写、编辑或审阅内容时都会检查是否遵守你的风格指南——对带编号规则的违规会用其 ID 标记，而对无编号指导则作为人工审阅建议提供。
对你的更改运行风格指南审查主要有两种方式：
在请求审查之前先审查页面
在处理页面时，你可以让 Agent 根据你的风格指南检查该页面——在“改进”菜单中使用 根据风格指南检查一致性 ，或在聊天中提出。Agent 会审查页面并留下总结其发现的评论。
在变更请求上请求风格指南审查
当你的站点有风格指南时，GitBook Agent 会作为建议审阅者出现在你的变更请求中，并标记为 风格指南审查:
在你的变更请求中，点击 请求审查.
为你的更改添加标题和说明——或者点击 生成 让 Agent 根据你的更改来撰写它们。
下方 审阅者下，点击 Request 旁边 GitBook 代理 ，让它对该变更请求进行风格指南审查。你可以同时添加人工审阅者，或者将列表留空以通知你组织中的所有审阅者。
Agent 会根据风格指南审查你的更改，如果发现违规，就会在变更请求上请求修改，并引用产生每个标记的规则。
在整个站点运行风格指南检查
如果你想检查的是现有内容而不是变更，请从风格指南本身运行一个 风格指南检查 。一次检查会根据你的规则审查一个空间中的每一页，并将它发现的问题修复到一个变更请求中供你审阅。
打开你的风格指南并点击 运行检查.
选择要检查的空间。一次最多可以检查三个空间。
审阅并合并 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 的站点级自定义指令。自定义指令是简短、站点特定的说明；风格指南则是一份完整、共享的写作规则文档。
最后更新于
这有帮助吗？