为 GitBook 构建、开发与发布集成时：用 CLI…

当任务涉及 GitBook integrations 平台（gitbook new、createIntegration、gitbook-manifest.yaml、gitbook dev、发布或市场提交）时使用。

适用场景

解决思路

1. 在编码前先按 GitBook 集成心智模型设计：集成是 GitBook 运行时执行的小型 TypeScript 应用，不是注入页面的脚本，也不是用户服务器上的代码。
2. 实现组件时把渲染当作在 GitBook 后端运行：render 服务端执行并返回 ContentKit 标记；不要依赖客户端 React 树或 DOM，UI 更新通过 action → 新 state → 重新渲染。
3. 不要尝试向站点注入 JavaScript；site:script:inject 和 site:script:cookies 仅限 GitBook 内部。若需求是加 script 标签，尽早说明支持路径是自定义块、webframe、事件。
4. 本地开发时不要打开开发服务器端口；用 gitbook dev 把已安装集成的流量代理到本机，并在 app.gitbook.com 内操作集成。
5. 用 gitbook new 脚手架项目，生成 gitbook-manifest.yaml、.gitbook-dev.yaml、package.json、src/index.tsx。
6. 在入口文件默认导出 createIntegration({ fetch, components, events })，入口文件由 manifest 的 script 指向。
7. 用 createComponent 定义组件：设置 componentId、initialState、action reducer、render 函数。
8. 在 action reducer 中按 action.action 分支返回新 state。
9. 在 render 中返回 ContentKit 标记，例如 block、button 等。
10. 在 events 中为 space_content_updated 等事件编写处理器。
11. 让自定义块出现在编辑器插入面板（⌘ + /）：同时在 createComponent 的 componentId 和 manifest 的 blocks: 条目中声明相同 id；只做一半会导致块不显示。
12. 配置 gitbook-manifest.yaml 的必需字段：name（全局唯一，使用命名空间如 acme-changelog）、title、description、organization（org id 或 subdomain）、visibility、scopes、script。
13. 只请求代码实际使用的 scopes，因为安装者会看到它们。
14. 在 manifest 中声明 blocks、安装者可见的 configurations（账户级和站点级属性 schema，渲染为设置表单）、secrets（如 CLIENT_ID: ${{ env.CLIENT_ID }}，发布时加载；用 dotenv-cli 让 gitbook publish 看到 .env）。
15. 编辑 manifest 超出基础时读 references/manifest.md 获取完整字段、scope 列表、配置属性类型。
16. 遵循开发循环顺序：先发布，再本地开发。
17. 准备环境：Node 18+；从 https://app.gitbook.com/account/developer 获取 personal access token；运行 npm install @gitbook/cli -g，然后 gitbook auth（或 gitbook auth --token=<token>）。
18. 若 token 需要粘贴到对话中，将其导出到环境，绝不回显或提交。
19. 脚手架：运行 gitbook new <dir>，按提示输入 name、title、organization、scopes。
20. 首次发布：在项目根运行 gitbook publish，注册集成（默认 private）并打印安装链接。
21. 安装：通过打印的链接把集成安装到至少一个 space 或 site；未安装前本地开发不工作。
22. 本地开发：运行 gitbook dev 启动代理，已安装集成的所有流量由本地代码服务而非已发布版本；在 GitBook 编辑器中交互，不在服务器 URL。
23. 本地开发时 UI 改动后刷新浏览器；禁用浏览器缓存以更顺畅；根据代码运行位置在浏览器控制台或终端查看日志，检查两者。
24. 想更新托管版本时重新运行 gitbook publish；用 gitbook unpublish <name> 移除集成。
25. 需要 CLI 命令参考时（包括 gitbook whoami、gitbook openapi publish）读 references/manifest.md。
26. 编写事件处理器、OAuth 流程或接触 context.environment 时读 references/runtime.md。
27. 入站 HTTP：用 fetch 处理集成公共端点的请求，使用标准 Fetch API 的 Request/Response；出站 HTTP 也用普通 fetch。
28. 事件：在 events 中映射 installation_setup、space_installation_setup、space_view、ui_render、space_content_updated、space_visibility_updated、space_gitsync_started、space_gitsync_completed 到处理器；某些事件需要匹配 scopes。
29. 环境：使用 context.environment 获取 apiEndpoint、apiTokens、安装信息（space、status、每个安装的 configuration 值）、secrets、公共 URL（environment.integration.urls.publicEndpoint）。
30. OAuth：使用固定模式——配置 button 类型属性，其 callback_url 路由到 fetch 处理器中的 createOAuthHandler({...})，client id/secret 从 secrets 读取；不要手写重定向/令牌交换。
31. 从集成内部调用 GitBook API：用 context.api（已认证的 @gitbook/api 客户端），不要用原始 token 自建客户端。
32. ContentKit 使用：render 可返回布局（block、vstack、hstack、divider）、展示（box、card、text、image、markdown）、交互元素（button、textinput、select、switch、checkbox、radio、codeblock、webframe、modal）。
33. 交互实现：输入绑定值到 state key；按钮派发 actions；action reducer 返回新 state；GitBook 重新渲染。
34. 编写比简单按钮复杂的组件前读 references/contentkit.md，获取完整 prop 表及难猜模式：动态 state 绑定实时预览、webframe postMessage 通信、modal 的 returnValue、用 @editor.node.updateProps 持久化 props、通过 @link.unfurl + urlUnfurl manifest 模式解链、块的 markdown 代码块序列化。
35. 发布可见性：manifest 的 visibility 控制范围——private（默认）仅所属组织成员可安装，适合内部工具，开发期间保持；unlisted 任何组织可通过共享安装链接安装，适合特定客户或 beta；public 任何人可安装，提交集成市场前必需（市场是单独审核流程，见 GitBook 的 submit your app for review 文档）。
36. 更改 visibility 后重新运行 gitbook publish。
37. 建议 public 前检查 manifest 可展示性：icon、summary（Markdown，≤2048 字符）、previewImages（1600×800）、categories、externalLinks。
38. 新项目用 CLI 脚手架而非手写，因为 gitbook new 会正确配置 manifest、TypeScript 配置、@gitbook/runtime 版本。
39. 组件异常时追踪块 id 链：manifest blocks[].id ↔ componentId。
40. 保持 secrets 不写在 manifest 文件中——始终用 ${{ env.X }} 间接引用，绝不写字面值。
41. 判断是否该用集成：当用户目标是从 GitBook 外部做内容或站点自动化（脚本调 REST API、CI 管道）时，集成可能是错误工具，普通 API + personal token 更简单；集成在代码必须运行在 GitBook 内部时才有价值：块、配置 UI、事件响应、代表安装者 OAuth。
42. 参考文件：references/manifest.md 覆盖每个 gitbook-manifest.yaml 字段、所有 scopes、配置属性类型、secrets、CLI 命令参考、安装/配置流程；references/runtime.md 覆盖 createIntegration/createComponent/createOAuthHandler 签名、事件目录、context.environment 形状、HTTP 进出；references/contentkit.md 覆盖完整组件参考、props、内置 actions、交互配方（动态绑定、webframe、modals、解链、markdown 序列化）。

适用边界 · 注意事项

• 需要向站点注入 JavaScript 时：不支持；site:script:inject 和 site:script:cookies 仅 GitBook 内部使用。
• 只想从 GitBook 外部做内容或站点自动化（脚本调 REST API、CI 管道）时：普通 API + personal token 更简单。
• 任务只是创建或重构文档站点、撰写页面内容时：应分别用 configure-site 和 write-docs。