configure-site 是 gitbookio/gitbook-skills 下的一个技能，用途是端到端地创建和维护整个 GitBook 文档站点。它关注的是页面以外的一切：结构设计、仓库脚手架、GitBook API 和品牌定制。它与 write-docs 技能配合使用——本技能在需要生成或编辑页面内容时会调用 write-docs。
【与 GitBook 的交互方式】 驱动 GitBook 有多种途径：GitBook 的 MCP 服务器和 REST API。应先检查当前会话中实际可用的能力，并优先使用 MCP：如果 GitBook MCP 工具已经连接，就用它们处理其覆盖的所有事项（创建/配置站点、开启变更请求、起草和编辑内容、重构文档），而不是直接调用 API。不需要为此运行检测脚本，因为你已经知道自身可用的工具与 MCP 连接。“MCP 优先”针对的是传输方式，并不意味着绕过 Git Sync 处理内容。MCP 提供了一个变更请求内容推送工具 updateChangeRequestContent，但对接入 Git Sync 的空间，超出小型定点编辑的改动仍应优先通过在本地仓库中编辑文件、再由 Git Sync 带到 GitBook。变更请求推送（MCP 或 REST）适用于：空间没有接入 Git Sync、环境中没有本地检出、或改动足够小以至于开一个变更请求是合适的。
本技能中的步骤以结果而非某种传输方式描述，因此适用任何一种方式。如果连接了 GitBook MCP 工具，直接调用即可；如果走 REST API，各步骤的端点、请求体和预期响应见 references/api-cheatsheet.md。
GitBook MCP 是对上述能力的完整读写接口。如果尚未连接且任务足够大（完整站点构建、持续重构，而非一次性微调），可以提出设置：claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp（然后用 /mcp 完成 OAuth 登录，或追加 --header "Authorization: Bearer $GITBOOK_TOKEN" 跳过浏览器流程）。Codex 对应命令：codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp。注意这是与 GitBook 另一个只读的“已发布文档”MCP 不同的服务器。
REST API（https://api.gitbook.com/v1）是 MCP 未连接或 MCP 未覆盖时的回退方案，每个请求都需要 GITBOOK_TOKEN 作为 bearer 头。同一个个人访问令牌（来自 https://app.gitbook.com/account/developer）可作为两者的 bearer token；MCP 还支持 OAuth。
如果需要令牌，在会话开始时检查：
[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"
如果未设置，直接询问用户：告知其需要 GitBook 个人访问令牌，引导至 https://app.gitbook.com/account/developer 创建，请其将令牌粘贴到会话中，随即导出为环境变量（export GITBOOK_TOKEN=<pasted value>），不要在回复中重复该值。在确认令牌存在于环境之前，不要进行任何 API 调用。绝不要将令牌写入文件、回显或提交。
【根本约束】 最重要的一点：GitBook 几乎什么都能做，唯独不能通过 API 设置 Git Sync。授权 GitHub/GitLab、选择仓库、选择分支、选择初始同步方向都只能在界面中完成——REST API 与 MCP（对其的封装）都只能读取生成的 Git Sync 状态，无法设置。存在一个 API 操作 installGitSyncProviderOnTarget，但它仍需要账户连接（OAuth）步骤在应用中完成，且尚未通过 GitBook 的 MCP 服务器暴露，应视为暂不可用。
Git Sync 现在在站点级别配置，这是默认做法。一个连接（一个仓库、一个分支）覆盖整个站点；gitbook-docs.yaml 将每个空间映射到各自目录。按空间的 Git Sync 仍存在，但已是例外，仅在特定空间需要独立仓库或分支时使用。
因此最干净的端到端流程是：
- Claude 在本地以 monorepo 形式搭建 Git 仓库（每个空间一个目录），最好预先编写 gitbook-docs.yaml 映射每个空间到其目录，并在工具允许时推送远程
- Claude 创建站点、分区和能创建的空空间
- 用户在 GitBook 中完成一次简短、有脚本的界面步骤：将站点连接到仓库/分支并确认空间到目录的映射
- Claude 应用品牌与定制
【需事先收集的输入】 在开始脚手架前确认以下信息，缺失时用一个聚焦的问题询问，不要猜测：
- 组织：列出用户的组织并展示，请其按名称确认目标，保存 organizationId。
- 站点方案与可见性：默认 type: "ultimate"、公开可见，除非用户明确另行说明。免费层（type: basic）仅适用于明确低风险场景。
- 内容种子：常见形态包括现有 markdown 文件夹、若干笔记加竞品站点参考、仅需求描述、需重构的现有站点、从其他文档平台迁移。若站点含 API 参考内容，预先询问是否有 OpenAPI 规范——若有，API 参考空间就是一个 builtin:openapi SUMMARY 条目加每个资源一段概述 README。
- 品牌：至少主色（hex）；可选 logo URL、favicon、字体、页眉链接、页脚、主题预设；Ultimate 站点还可考虑 AI 助手起始提示。
- 站点结构：是分区而非站点空间。多空间站点需与用户明确规划分区列表，每个分区有标题、Font Awesome 图标名和描述。
- Git 远程偏好：GitHub、GitLab 或仅本地。先检查 gh 或 glab 是否安装。
- 站点形态：单空间或多空间。多空间站点用分区在导航中分组空间。站点空间仅用于翻译变体。
【构建前验证内容来源】 用户指定内容种子后，先验证能实际读取它：解析并复述来源，展示顶层内容请用户确认；若无法访问则停下说明；绝不用相似来源替代。
【状态改变操作的确认门槛】 站点创建、空间创建、添加分区、附加站点空间、定制更改都会创建或修改组织中所有人立即可见的对象，应视为重操作。规则是：任何状态改变前，先向用户展示一屏预览并取得明确“是”。删除等破坏性操作同样适用，且要求更明确。只读操作无需确认。
【变更请求推送后的两个链接】 当通过变更请求推送内容时，必须每次都向用户报告两个链接：变更请求的 diff/编辑器链接（urls.app），以及应用了该变更的站点预览链接。后者需要单独查找：站点 URL 位于 Site 对象（公开站点为 urls.published，否则 urls.preview），并需追加 /~/changes/<number>/，去掉 API 返回的末尾斜杠。这是一条硬性规则。
【设计站点结构】 在写任何文件或创建任何内容前，先确定结构并请用户过目。此步输出一个小计划，包含三部分：空间列表（每个连贯内容体一个空间，通常 1–4 个）；分区分组（若多空间）；每个空间的页面树（文件夹与页面，附一到两句摘要）。完整启发式方法见 references/site-structure-design.md。始终向用户展示计划并在脚手架前取得明确认可。