> 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/build-your-style-guide.md).

# 构建你的风格指南

选择一个起点，填写模板，并编写 GitBook Agent 可以执行的规则。

大多数团队从模板开始，并将风格指南保存在单个页面上。本页介绍如何选择起点、填写模板，以及撰写 GitBook Agent 可以强制执行的规则。

要设置样式指南，你需要该站点的管理员权限。

## 选择起点

首先，点击 **风格指南** ，然后点击 **设置**。然后选择一种开始方式：

| 起点          | 在以下情况下选择它                                                          |
| ----------- | ------------------------------------------------------------------ |
| **模板**      | 你还没有风格指南。                                                          |
| **现有的风格指南** | 组织中的其他站点已在使用你想要的风格指南。请参阅 [使用现有风格指南](#use-an-existing-style-guide). |
| **导入**      | 你在其他工具中维护风格指南，或将其发布在网上。请参阅 [导入风格指南](#import-a-style-guide).        |

GitBook 提供三种模板：

<table><thead><tr><th width="204.75390625">模板</th><th>最适合</th></tr></thead><tbody><tr><td><strong>入门模板</strong></td><td>从零开始定义你自己的语气和规则。每个部分都会说明该写什么，你自己撰写这些规则。</td></tr><tr><td><strong>Google 风格指南</strong></td><td>为开发者受众撰写清晰、准确且专业的内容。生成自 Google 开发者文档风格指南。</td></tr><tr><td><strong>Microsoft 风格指南</strong></td><td>面向广泛受众的温暖、简洁、有人情味的写作风格，包括不熟悉技术的读者。基于 Microsoft Writing Style Guide 生成。</td></tr></tbody></table>

Google 和 Microsoft 模板附带来自其源指南的可执行规则，涵盖语气、词汇表、语法、格式、流程、无障碍写作和包容性语言。模板中的一切都可由你编辑。

{% hint style="info" %}
当源指南发生变化时，GitBook 会更新其模板。更新只会应用于新的风格指南。你已经创建的风格指南不会改变。
{% endhint %}

## 填写模板

每个模板都是单页的，按语气和语调、词汇表、语法、格式和流程等部分组织。每个部分都会解释该部分应包含什么。删除任何你不需要的部分。

每个模板都会用 **需要你填写** 提示标出必须自定义的部分。在运行首次检查前，请逐项完成。它们通常包括：

* 模板所反映的基础指南版本的快照日期（Google 和 Microsoft 模板）
* 你的产品名称和文档使命
* 谁阅读和编写你的文档，以及该指南涵盖什么
* 你的产品名称、功能名称以及团队有争议的术语，添加到词汇表中
* 负责人、审查频率，以及如何提出更改
* 决策记录中的第一条条目，记录你的团队为何确定某条规则或为何偏离基础指南

所有没有提示的内容都已可直接使用。仍包含占位文本的规则在你填写之前不会生效。

## 编写 Agent 可以强制执行的规则

GitBook Agent 会强制执行带编号 ID 的规则，以及“绝不使用分号”这类明确规则。对于其他内容（例如对文风的描述），它会将其视为指导，并仅作为建议提供。详情请参阅 [GitBook Agent 如何强制执行风格指南](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide/how-gitbook-agent-enforces-your-style-guide.md#which-rules-the-agent-enforces).

模板会以表格形式编写规则，包含 ID、规则、双方示例以及任何例外：

| ID    | 规则    | 要做             | 不要做            | 例外                                  |
| ----- | ----- | -------------- | -------------- | ----------------------------------- |
| SG-12 | 使用现在时 | ✅ “命令会创建一个文件。” | ❌ “命令将创建一个文件。” | 用于实际上发生在未来的事件的将来时（“对 v2 的支持将于三月结束”） |

在编写或编辑规则时：

* **为每条要强制执行的规则分配一个 ID。** 无论规则位于何处，都使用当前最大编号之后的下一个编号。切勿重新编号或重复使用 ID，因为以往的标记和决策日志都会引用该 ID。
* **每个 ID 只对应一条规则。** 每条规则只检查一项内容，这样生成的标记才便于处理。
* **列出例外情况。** 对于符合规则例外情况的文本，Agent 不会标记。
* **将可检查的指导转化为规则。** 将文风描述保留为指导，并将所有可检查的内容（例如“正文中不得使用感叹号”）写成带编号的规则。
* **替换所有占位符。** 如果规则中仍包含方括号括起的文本，例如 `[Product name]`，就不会被强制执行。

{% hint style="info" %}
Starter 模板为 ID 使用 `SG-` 前缀。你可以更改前缀，但开始使用指南后就应保持一致。
{% endhint %}

## 将你的主要规则放在第一页

一页对大多数风格指南来说已经足够。GitBook Agent 会在每个任务中加载第一页，因此那里的规则始终适用。

如果你的风格指南变得很长，就把某一主题的详细规则，例如很长的词汇表或你的内容类型，移到它自己的页面，并配上清晰的标题。Agent 在任务涉及该主题时会读取该页面。将核心规则保留在第一页。

## 使用现有风格指南

如果你所在组织已经在其他站点上使用风格指南，它们会与使用它们的站点一起显示在设置屏幕顶部。选择其中一个后，你可以：

* **直接使用：** 与使用该指南的其他站点共享。所做的修改会应用到所有使用该指南的站点。
* **创建分支：** 为此站点创建一个副本，命名为 `Style guide - {site name}`，之后即可独立修改。

## 导入风格指南

要导入你保存在其他工具中的风格指南：

1. 在设置页面中，点击 **上传文件**.
2. 将你的 Markdown、HTML、DOCX 或 ZIP 文件拖放到此处，或浏览选择它们。
3. 你也可以启用 **使用 AI 优化导入内容** 以清理导入的内容。
4. 点击 **开始导入**.

要导入在线发布的风格指南：

1. 在设置页面中，点击 **从 URL 导入**.
2. 输入该风格指南的链接。
3. 你也可以启用 **使用 AI 优化导入内容** 以清理导入的内容。

GitBook 会导入你输入的 URL 下所有公开页面，最多 200 个页面。例如，导入 `website.com/docs/` 会包含 `website.com/docs/article` 但不包括 `website.com/other-parent/page`。对于更大型的网站，请分别导入较小的子路径。

导入的风格指南通常跨越多个页面，并且存在没有 ID 的规则。在运行首次检查之前：

1. 将核心规则移到第一页。
2. 为你希望强制执行的每条规则分配一个 ID，并为整个指南使用同一个前缀。
3. 记下你从另一份指南中依赖的任何规则。Agent 只会强制执行写在你风格指南中的内容。

## 在首次检查之前

你的风格指南在以下情况下就准备好了：

* 每个 **需要你提供输入** 部分已填写，且没有规则仍包含占位文本。
* 你的产品名称和已确定的术语都已列入词汇表。
* 你希望强制执行的每条规则都有 ID。
* 你的核心规则位于第一页。

然后 [根据你的风格指南检查内容](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide/check-content-against-your-style-guide.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide/build-your-style-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
