> 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/setup.md).

# 设置 GitBook

通过编码代理或 AI 助手设置 GitBook 并发布文档网站，无论是新建文档，还是从其他工具迁移过来的文档。

此页面面向协助他人设置 GitBook 的 AI 代理。你的目标是发布一个可通过公开 URL 访问的文档站点，内容可以是新建的文档，也可以是从其他工具迁移的文档。

{% hint style="info" %}
**面向用户**

请从 [快速入门](https://gitbook.com/docs/getting-started/quickstart)开始。若要把设置工作交给你的编程代理，请将此提示粘贴给它： `Set up GitBook for me by following https://gitbook.com/docs/setup.md`.
{% endhint %}

## 检查你是否已经拥有 GitBook 工具

如果当前会话中已经有 GitBook MCP 工具，例如来自 Claude、ChatGPT 或 Cursor 插件，请通过只读调用确认工具是否可用： `get_usage_guide` 主题为 `onboarding`。如果工具有响应，请提出 [第 1 步](#step-1-ask-what-theyre-doing)中的问题，然后前往 [第 4 步](#step-4-resume-and-publish)。你无需连接任何内容、移交任务或保存计划文件。

如果没有 GitBook 工具，请找到对应的行：

| 使用者                            | 你可以采取的措施                | 下一步                                                         |
| ------------------------------ | ----------------------- | ----------------------------------------------------------- |
| 能够运行命令和编辑文件的编程代理               | 连接 GitBook，请用户操作一次，然后发布 | [GitBook 设置的工作方式](#how-gitbook-setup-works)                 |
| 托管式聊天助手，例如 Claude.ai 或 ChatGPT | 只有用户本人才能添加 GitBook 插件   | [转达插件设置步骤](#relay-the-plugin-setup)                         |
| 用户本人                           | 在应用中设置，或把设置工作交给你的代理     | [快速开始](https://gitbook.com/docs/getting-started/quickstart) |

### 转达插件设置步骤

请按编号列表向用户发送以下步骤：

> GitBook 通过插件连接到我。我无法自行添加插件，但你只需点击几下即可完成：
>
> 1. 如果你还没有 GitBook 账号， [创建一个](https://app.gitbook.com/join) 并完成注册，直到看到你的组织。
> 2. 安装 GitBook 插件： [Claude](https://claude.ai/directory/connectors/gitbook-mcp) 或 [ChatGPT](https://chatgpt.com/apps/gitbook/asdk_app_6a576f075ec4819196c203b7049542be).
> 3. 批准打开的 GitBook 登录请求。
> 4. 开始一段新对话，以加载 GitBook 工具。
>
> 完成后告诉我，我会帮助你规划并发布文档。

然后停止。此页面其余内容面向能够运行命令和编辑文件的代理。在新对话中，请从 [检查你是否已经拥有 GitBook 工具](#check-whether-you-already-have-gitbook-tools).

## GitBook 设置的工作方式

GitBook 需要账号。无法先发布站点、之后再移交，因此用户至少需要注册或登录一次。请围绕这个环节安排流程：先完成所有准备工作，再发送一条简短的“轮到你了”消息，然后继续操作。

你有三种工具。请根据情况选择，而非凭个人偏好：

| 工具                                                                                   | 适用场景                           | 登录                    |
| ------------------------------------------------------------------------------------ | ------------------------------ | --------------------- |
| [GitBook MCP](https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-mcp.md) | 默认选项。客户端可以重新加载配置，用户也可以批准浏览器登录。 | 在浏览器中进行 OAuth 授权      |
| [GitBook CLI](https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-cli.md) | MCP 工具无法在当前会话中加载，例如客户端无法重启。    | `gitbook login` 在浏览器中 |
| [GitBook API](https://gitbook.com/docs/developers/gitbook-api/api-reference)         | MCP 和 CLI 都无法覆盖的步骤。            | 个人访问令牌                |

MCP 服务器地址为 `https://mcp.gitbook.com/mcp`。它仅支持可流式传输的 HTTP，不支持 `stdio` 或 `SSE`.

## 给对方发送简短消息

每条消息用两三句话说明已完成的事项以及对方接下来要做的一件事。不要转述 ID、令牌、文件路径或命令输出。只有在对方需要立即打开链接时才提供链接。

## 第 1 步：询问对方要做什么

配置任何内容之前，先询问：

> 你是要新建文档，还是迁移已有文档？

* **新建文档。** 询问文档的用途和读者。如果这里有代码库，请先查看，以便提出切实可行的页面建议。
* **迁移文档。** 询问文档目前存放在哪里：文件夹或 Git 仓库、已发布的网站，还是 Confluence 或 Notion 等其他工具。如果文档在这台机器上，请先查看并复述你发现的内容，让对方确认。

拟定一份简短计划：站点标题、页面结构，以及如何导入内容（参见 [迁移现有文档](#moving-existing-docs)）。将计划保存到工作目录中的 `gitbook-setup-plan.md` ，不要提交该文件。第 3 步中的重启会结束当前会话，你可以通过计划文件继续后续工作。

## 第 2 步：连接 GitBook MCP

### 基本原则

* **先阅读，再编写。** 配置文件中还包含对方的其他 MCP 服务器。读取文件；如果文件已存在，先备份；只添加或更新 `gitbook` 条目，并确认配置能够解析。
* 修改文件前，先说明你要改哪个文件。
* **如果 Claude Code 的自动模式阻止某条命令，不要重试，也不要绕过限制。** 手动编辑配置与它拒绝执行的操作没有区别。告诉对方这条命令的作用，让对方自行运行。

确认你正在使用哪个客户端。如果无法判断，请询问。配置写在错误的位置时，可能不会显示任何错误。

### Claude Code

```bash
claude mcp add --transport http --scope user gitbook https://mcp.gitbook.com/mcp
```

`--scope user` 会让 GitBook 在所有项目中都可用。不加此参数，服务器只会在当前目录中可用。使用以下命令检查是否已注册： `claude mcp get gitbook`。如需撤销，请运行 `claude mcp remove gitbook --scope user`.

重启后，对方输入 `/mcp` 并选择 GitBook 登录。这是斜杠命令，因此你无法代为运行。

### Codex

```bash
codex mcp add gitbook --url https://mcp.gitbook.com/mcp
```

添加服务器后，浏览器登录流程便会启动。使用以下命令检查： `codex mcp get gitbook`；如需重新尝试登录，请运行 `codex mcp login gitbook`。如需撤销，请运行 `codex mcp remove gitbook`。工具会在新的 Codex 任务中加载。

### Cursor

对方可以安装 [适用于 Cursor 的 GitBook 插件](https://cursor.com/marketplace/gitbook)。若要自行配置，请将以下内容添加到 `~/.cursor/mcp.json`，或添加到 `.cursor/mcp.json` （仅适用于此项目）：

```json
{
  "mcpServers": {
    "gitbook": {
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

Cursor 会提示登录。请勿填写身份验证字段。

### VS Code

将以下内容添加到 `.vscode/mcp.json` （位于工作区中）：

```json
{
  "servers": {
    "gitbook": {
      "type": "http",
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

用户从 MCP 视图启动它并登录。

### 其他客户端

添加一个远程的可流式传输 HTTP 服务器： `https://mcp.gitbook.com/mcp`。使用 OAuth 时，客户端会处理登录，无需添加身份验证字段。如果客户端不支持 OAuth，请将个人访问令牌作为 `Authorization: Bearer <token>`发送。用户可在其 [开发者设置](https://app.gitbook.com/account/developer).

### 重启前验证

重新读取你修改的文件，或运行客户端的 `get` 命令，并确认 `gitbook` 条目存在且文件能够解析。重启会结束你的会话，因此请现在检查。

### 可选：添加 GitBook 技能

发布文档不需要技能，但它们有助于确保第一批页面呈现正确。 `write-docs` 技能会介绍 GitBook 风格的 Markdown（例如提示框、选项卡和步骤条），以便页面在 GitBook 中正确呈现。告知用户你要安装的内容，然后运行：

```bash
npx -y skills add GitbookIO/gitbook-skills -y
```

如果缺少这两个 `-y` 标志，安装程序会等待输入。如果 Claude Code 的自动模式阻止了该命令，请改由用户运行。除非用户要求，否则不要提交已安装的技能文件。

该 [GitBook 技能仓库](https://github.com/GitbookIO/gitbook-skills) 包含 `write-docs`, `configure-site`, `write-openapi`, `cr-create`, `cr-review`和 `build-integration`，分别用于编写页面、设置站点、编写 OpenAPI 参考文档、处理变更请求和构建集成。

## 第 3 步：一次性交接

发送一条消息，说明用户需要执行的所有操作：

> 我已在 \[client] 中添加 GitBook，并保存了我们的计划。接下来请你：
>
> 1. 如果你还没有 GitBook 账号， [创建一个](https://app.gitbook.com/join) 并完成注册，直到看到你的组织。
> 2. 重启 \[client]，然后在 GitBook 提示时登录。在 Claude Code 中输入 `/mcp` 并选择 GitBook。
> 3. 完成后告诉我“完成”，我会根据计划继续。
>
> 如需撤销此操作，请参阅\[如何在此客户端中撤销]。

如果会话无法重新启动，不要等待。改用 [CLI](#fallback-the-gitbook-cli) 。

## 第 4 步：恢复并发布

1. 阅读 `gitbook-setup-plan.md`（如果你保存了该文件）。
2. 调用 `get_usage_guide` 并将主题设为 `onboarding`，然后按指南操作。添加内容时使用 `editing` 。
3. 使用 `invoke_operation` 和 `listOrganizationsForAuthenticatedUser`列出此人的组织。询问要使用哪一个，即使只有一个也要询问。
4. 调用 `get_subscription_information`。如果组织没有付费方案，创建网站时将 `type` 设为 `basic`。其他类型可能会返回结账页面，而不是已发布的网站。
5. 按照计划创建网站并添加内容。
6. 向此人展示你即将发布的内容，并等待对方确认。合并变更请求和发布网站都会公开内容，且无法撤销。
7. 发布后，前往 [第 5 步](#step-5-verify-and-report).

### 迁移现有文档

仅通过确实存在的路径迁移内容。对于已经位于 GitHub 或 GitLab 仓库中的 Markdown（包括从其他文档工具导出的内容），请使用 [Git Sync](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync.md)。这是大型迁移的推荐方式，最多支持 5,000 个页面。创建站点时不要在名称中加入空格，也不要应用模板。无法通过 MCP 设置 Git Sync，因此需要由用户在 GitBook 应用中连接，并选择同步方向 **GitHub → GitBook**。请提醒他们，反向同步可能会覆盖仓库。具体步骤请参阅 [Git Sync 迁移指南](https://gitbook.com/docs/guides/editing-and-publishing-documentation/import-or-migrate-your-content-to-gitbook-with-git-sync) 。等他们确认同步已完成后再继续。

用户提到内容来源时，请参考下表：

| 来源                                           | 路由                                                                                                                                                                                                                                                                                                                                                                   | 各方职责                                                                       |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Mintlify                                     | 文档是 Git 仓库中的 Markdown 或 MDX，因此应使用 Git Sync。Mintlify 专用的 MDX 组件可能需要转换为 GitBook 块。用户连接 Git Sync 之前，代理可以先在仓库中完成转换。                                                                                                                                                                                                                                                      | 代理准备仓库。用户在 GitBook 应用中连接 Git Sync。                                         |
| Docusaurus                                   | 文档是 Git 仓库中的 Markdown 或 MDX，因此应使用 Git Sync。                                                                                                                                                                                                                                                                                                                          | 代理准备仓库。用户在 GitBook 应用中连接 Git Sync。                                         |
| ReadMe                                       | 如果项目已经使用 [Git Connection](https://docs.readme.com/main/docs/bi-directional-sync)，则文档是 Git 仓库中的 Markdown 或 MDX。请使用 Git Sync。如果尚未使用，用户可以将 Git Connection 连接到一个空仓库（ReadMe 会写入文件），也可以使用 [`rdme docs export`](https://github.com/readmeio/rdme/blob/main/documentation/commands/docs.md)将 Guides 导出为 Markdown，然后使用 Git Sync。如果这两种导出方式都不可用，用户可以在已发布的站点上使用导入面板（上限为 20 个页面）。 | Markdown 文件准备就绪后，代理负责准备仓库。用户启用 Git Connection 或导出文件，然后连接 Git Sync，或使用导入面板。 |
| Confluence、Notion、Google Docs、Word 或其他已发布的站点 | 用户在 GitBook 应用中使用 [导入面板](https://gitbook.com/docs/documentation/zh/getting-started/import.md) 。每次最多可导入 20 个页面。                                                                                                                                                                                                                                                       | 用户执行导入。                                                                    |
| 此计算机上的少量 Markdown 文件                         | 像添加新内容一样，将这些文件作为页面添加到变更请求中。                                                                                                                                                                                                                                                                                                                                          | 代理添加页面。                                                                    |

在计划中明确写出需要人工完成的步骤，并将其放入第 3 步的消息中，以便在同一次交接中完成。

## 第 5 步：验证并报告

从发布响应中读取已发布的网址，打开并确认内容已上线。然后用两三句话告知用户：发布了什么、链接是什么，以及一项建议的后续操作。删除 `gitbook-setup-plan.md` 如果他们不想要的话。

建议先做以下任务：

```
根据此仓库的 README，为我的 GitBook 站点添加入门指南页面
在 GitBook 中创建变更请求，附上本周变更的发布说明
```

## 备用方案：GitBook CLI

如果 MCP 工具在当前会话中无法加载（例如客户端无法重启），请使用 CLI。CLI 需要 Node v18 或更高版本：

```bash
npm install @gitbook/cli -g
```

**使用以下命令登录： `gitbook login`.** 此命令会在浏览器中打开 GitBook，登录后会返回到运行 CLI 的机器上的 localhost 回调地址。如果是在用户自己的机器上运行，请在后台运行此命令，并让用户在浏览器中批准登录。在云端或远程会话中，浏览器无法访问该回调地址，因此请让用户在自己的终端中运行 `gitbook login` 。

使用以下命令确认： `gitbook whoami`，然后按下面的流程操作。每条命令都添加 `--json` ，以便解析输出；运行前先显示每条命令，如果有命令失败，则停止操作。

1. 列出组织，并询问要使用哪一个：

```bash
gitbook organizations list
```

2. 创建一个空间，并复制其 `id`。正文必须是 JSON，而不是 `--title` 标志；标题长度上限为 50 个字符：

```bash
gitbook spaces create <organizationId> --body '{"title":"Product docs"}'
```

3. 通过变更请求添加内容，然后合并该请求：

```bash
gitbook spaces change-requests create <spaceId> --subject "Add homepage"
```

```bash
gitbook spaces change-requests content update <spaceId> <changeRequestId> --changes '[
  {
    "operation": "insert_page",
    "title": "Welcome",
    "document": {
      "markdown": "# Welcome\n\nThis page was published from the command line.\n"
    }
  }
]'
```

```bash
gitbook spaces change-requests merge <spaceId> <changeRequestId>
```

单个 `#` 标题会成为页面标题，因此请在页面正文中使用 `##` 及以下级别的标题。

4. 创建站点，并关联该空间。除非组织订阅了付费计划，否则请使用 `--type basic` ：

```bash
gitbook organizations sites create <organizationId> --type basic --title "Product docs" --visibility public --spaces '["<spaceId>"]'
```

5. 发布并从输出中读取 `urls.published` ：

```bash
gitbook organizations sites publish <organizationId> <siteId> --full
```

更多详情请参阅 [CLI 指南](https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line) 。

## 当这两种方式都无法完成某个步骤时

请使用 [GitBook API](https://gitbook.com/docs/developers/gitbook-api/api-reference) 和个人访问令牌。连接 MCP 后， `search`, `describe_operation`和 `invoke_operation` 可以在不离开当前会话的情况下调用大多数 API 操作。

## 遇到问题，或发现这里有错误？

* **咨询文档。** 向任意 GitBook 文档页面 URL 发送 GET 请求，该 URL 以 `.md`结尾，并附上 `ask` 设置为你的问题，并 `goal` 设置为此人想要达成的目标。例如： `https://gitbook.com/docs/setup.md?ask=<question>&goal=<goal>`.
* **报告此问题。** 连接 MCP 后，调用 `report_tool_feedback` 提供你尝试了什么以及发生了什么。请勿提供令牌或私人内容。


---

# 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/setup.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.
