> 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/how-gitbook-agent-enforces-your-style-guide.md).

# GitBook Agent 如何强制执行你的样式指南

GitBook Agent 如何读取你的风格指南，并在审查和编辑内容时应用其中的规则。

当 GitBook Agent 与你的风格指南配合工作时，它的任务是让内容遵循你的规则，而不是总体上提升写作。它被设计得精确而保守，并且每次检查同一内容时，都力求指出同样的问题。

## 代理会读取的内容

* **每项任务都读取第一页。** 每当 Agent 撰写、编辑或审阅内容时，都会完整加载风格指南的第一页。
* **相关时读取其他页面。** 在 Agent 撰写或审阅其他页面涵盖的内容（例如词表或内容类型）之前，它会根据目录读取相应页面。
* **除此之外，不读取任何内容。** 风格指南是 Agent 唯一的规则来源。它不会套用上游指南、有关良好文风的一般知识或任何其他风格指南中的规则。如果你的风格指南将 Google 或 Microsoft 的指南列为基础，Agent 会将其视为供人参考的背景资料，而不是规则。

你的编辑始终优先：修改规则，代理就遵循你的版本；删除规则，代理就停止强制执行。

## 代理会执行哪些规则

你如何编写规则，决定了代理会如何处理它：

| 你写的内容           | 示例            | 代理的行为                                                |
| --------------- | ------------- | ---------------------------------------------------- |
| 带编号 ID 的规则      | `G-11`：使用牛津逗号 | 标记违规，并引用 ID。编辑时会修正这些问题。                              |
| 没有 ID 的明确、可检查规则 | “永远不要使用分号。”   | 标记违规，并用简短引文引用该规则。编辑时会修正这些问题。                         |
| 指导              | 对你的语气和风格的描述   | 在撰写新文本时应用它。对于现有文本，它只作为建议提供，绝不会作为标记。                  |
| 仍是占位符的规则        | `[添加规则]`      | 在你替换占位符之前忽略它。如果你的风格指南大部分都是占位符，代理会告诉你，它的检查只涵盖你已完成的规则。 |

代理还会遵守每条规则的例外情况。属于已列出例外的文本，例如“在行动者未知时，被动语态是可以的”，不算违规。

如需了解如何编写 Agent 能够执行的规则，请参阅 [构建风格指南](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/styleguide/build-your-style-guide.md#write-rules-the-agent-can-enforce).

## 当 Agent 审查

在审查期间，代理会标记问题，但不会更改任何内容。每个标记都会说明规则、问题所在位置、问题是什么以及如何修复。例如：

| 部分       | 示例                               |
| -------- | -------------------------------- |
| 规则       | `G-10`：使用主动语态                    |
| Location | “轮换你的 API 密钥”： “系统每 90 天轮换一次密钥。” |
| 问题       | 在行动者已知的情况下使用了被动语态。               |
| 修复       | “系统每 90 天轮换一次密钥。”                |

代理每次大约标出五个标记，因此最重要的问题会排在前面。如果还有更多问题，它会说明并给出数量。标记按类别排序，顺序如下：措辞和术语、格式和标点、语法、以及流程。在同一类别内，它们按页面顺序排列。

指导内容绝不会作为标记出现。相反，代理每次最多添加一条简短的“值得人工查看”备注。

## 当 Agent 编辑时

当你要求代理修正内容或使其与你的风格指南保持一致时，只要修正是明确无歧义的，它就会在任何地方应用该规则。当某条规则允许两种合理结果时，代理会保持文本不变，并将其列为建议。

编辑后，代理会按规则汇总更改，并附上数量。例如：“G-7：将 'click on' 替换为 'click'，共 6 处。”基于指导内容的建议会在末尾以简短列表显示。

## 代理绝不会更改的内容

无论是在审查还是编辑中，Agent 都不会标记或更改：

* 代码块、行内代码、命令输出，或 API 和产品标识符中的内容
* 直接引语和引用材料
* 被规则例外情况豁免的文本
* 你内容的含义或事实

代理会按原文应用规则。它不会为了适配内容而弱化、加强或重新解释某条规则。如果某条规则有歧义，代理会按字面含义执行，并在其“值得人工查看”备注中提及该歧义。

## 没有风格指南时

如果你的网站没有风格指南，代理就不会进行风格审查。在变更请求中，它只会评论清晰、客观的问题，例如拼写错误、矛盾、错误的说明或未完成的部分。

## 风格指南和自定义指令

自定义指令是给 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 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/how-gitbook-agent-enforces-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.
