面向广泛受众，温暖、简单、有人情味的写作——包括不是技术专家的读者。基于 Microsoft Writing Style Guide 生成。
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 形式编辑。
要打开你的样式指南，请使用你网站侧边栏中的 **Styleguide** 条目，或使用 **编辑** 操作，位于 **设置 → 样式指南**.
### 在网站之间共享样式指南
样式指南属于你的组织，因此多个网站可以共用同一个——编辑 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 提供的网站级自定义指令的补充。自定义指令是简短的网站特定说明；样式指南则是完整、共享的写作规则文档。
---
# 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/creating-content/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.