gb-setup

gb-setup

GrowthBook Agent Skills 的单技能入门指南。引导用户配置 GB_API_KEY，以及自托管环境中的 GB_API_URL 和 GB_APP_URL。验证凭据和可信应用源，然后使用 chmod 600 写入 ~/.config/growthbook/.env。

API 密钥是与 GrowthBook 用户关联的个人访问令牌（PAT），因此 API 会自动将写入类技能创建的任何功能开关或实验归属到该用户，无需单独配置所有者标识符。

如果未设置相应的环境变量，gb-call 会读取此文件，因此用户只需一次性配置，无需编辑 shell rc 文件。实际环境变量始终优先于文件中的值，这对于 CI 和临时覆盖很有用。

使用前，先根据当前客户端解析随附的辅助工具：在 Claude Code 插件中，它是 ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call；在独立的 Agent Skills 安装中，它是相对于此技能目录的 scripts/gb-call。将下面的 <gb-call> 替换为解析出的命令。

工作流

1. 检测当前状态。 检查已有的配置。除非用户想要更改，否则不要询问他们已经有的值。

   test -f ~/.config/growthbook/.env && echo "exists" || echo "missing"
   

   如果文件存在，使用 Read 工具读取，解析 KEY=value 行，并显示屏蔽后的摘要：

   I see existing config at ~/.config/growthbook/.env:
     GB_API_KEY = gb_pat_****wxyz   (last 4 shown)
     GB_API_URL = (not set — defaults to https://api.growthbook.io)
     GB_APP_URL = (not set — defaults to https://app.growthbook.io because the API URL uses GrowthBook Cloud)
   
   Want to keep these, update one, or start fresh?
   

   根据实际生效的 API 源说明未设置的 GB_APP_URL：如果 API 源是 GrowthBook Cloud，则默认为 https://app.growthbook.io；如果配置了自定义的自托管 GB_API_URL，则必须设置此项。

   还要说明 process.env 中的内容：如果用户设置了 shell 导出变量，它们会覆盖文件中的值。指出这一点（“你的 shell 环境中也设置了 GB_API_KEY；除非取消设置该 shell 变量，否则不会使用文件中的值。”）

2. 收集 GB_API_KEY（必填）。如果保留现有值，则跳过。否则，先显示聊天记录暴露风险提示，让用户知情后再决定：

   粘贴密钥前请注意：你在此聊天中输入的任何内容都可能由你的 Agent 客户端存储，并作为对话的一部分发送给你配置的模型提供商。此技能会在回复中屏蔽密钥，但无法追溯性地屏蔽你粘贴的值。如果你对此有所顾虑，请检查客户端的存储和保留设置。

   建议：为此插件生成新的 PAT，不要重复使用你的个人管理员令牌。这样，如果出现问题，你可以单独撤销它，而不会影响你对 API 的其他访问。

   然后询问：

   请粘贴个人访问令牌（PAT）或 Secret Key。获取地址：

   • Cloud：https://app.growthbook.io/account/personal-access-tokens
   • 自托管：https://<your-host>/account/personal-access-tokens

   PAT 以 gb_pat_ 开头；Secret Key 以 secret_ 开头。两者均可使用。

   获取后，后续步骤中绝不回显该值，除最后 4 个字符外，全部屏蔽。

3. 询问是否使用自托管（可选的 GB_API_URL 和 GB_APP_URL）。

   你使用的是 GrowthBook Cloud（api.growthbook.io）还是自托管实例？

   • Cloud → 跳过，不设置这两个 URL（gb-call 默认使用 https://api.growthbook.io 调用 API，并使用 https://app.growthbook.io 创建 UI 链接）。
   • 自托管 → 分别询问：
     • 存储为 GB_API_URL 的 API 源（例如，https://api.acme-internal.com）。
     • 存储为 GB_APP_URL、面向用户的 GrowthBook UI 源（例如，https://growthbook.acme-internal.com）。

   不要从一个源推导另一个源。自托管部署可能使用互不相关的主机名，也可能通过同一源提供 API 和 UI。

   接受之前，验证每个 URL 的格式：

   • 必须能解析为 URL（即 new URL(value) 不会抛出异常）。
   • 协议必须是 https://（拒绝 http://——通过明文传输的身份验证标头会泄露凭据；拒绝 file://、data:// 等）。
   • 主机名不能为空。
   • 不得包含用户名或密码。
   • 不得包含路径、查询参数或哈希——new URL(value).pathname 必须为 / 或空，且 search 和 hash 为空。像 https://api.acme.com/v1 这样的值会导致请求或链接被悄然路由到错误位置；应拒绝，并提示用户只填写源站。
   • 存储前去掉一个末尾斜杠。

   拒绝任何不符合这些检查的 URL，并返回到上一步重新询问；不要悄然强制转换。静默修正会让用户误以为系统“总能正常工作”，但有时输入值存在系统无法修正的错误。

4. 根据实时 API 进行验证。 将收集到的值设为临时环境变量，并调用一个轻量级的身份验证端点：

   GB_API_KEY='<value>' \
   GB_API_URL='<cloud default or self-hosted API origin>' \
   GB_APP_URL='<cloud default or self-hosted app origin>' \
     <gb-call> GET /api/v1/projects
   

   按以下方式解读结果：

   • 2xx → 凭据有效。继续。
   • 401 / 403 → “身份验证失败。API 密钥无效、已过期或已被撤销。请在 <url-from-step-2> 生成新的密钥，然后重试。”返回第 2 步。
   • growthbook.io 主机返回 404 → “从 api.growthbook.io 收到 404。如果你实际使用的是自托管版本，请将 GB_API_URL 设为你的 API 基础 URL。”返回第 3 步。
   • 网络错误 / DNS → “无法连接到 <host>。请检查 URL 和网络。”显示原始错误。

   验证通过前不要继续。如果用户遇到困难，请停止并让他们排查问题——不要写入损坏的配置。

   然后验证受信任的应用源站是否解析为预期值：

   GB_API_URL='<cloud default or self-hosted API origin>' \
   GB_APP_URL='<cloud default or self-hosted app origin>' \
     <gb-call> app-origin
   

   输出必须与预期的 UI 源站完全一致，且末尾不得有斜杠。如果不匹配，返回第 3 步。

5. 写入 ~/.config/growthbook/.env——顺序对安全性至关重要。

   创建目录，并先锁定其权限：

   mkdir -p ~/.config/growthbook
   chmod 700 ~/.config/growthbook
   

   目录的 0700（仅所有者可访问）权限可以保护文件，避免文件在下一步操作期间被系统上的其他用户读取。如果先写入文件再执行 chmod，文件会继承用户的 umask（通常为 0022 → 权限模式 0644，所有用户均可读取），从而产生安全窗口。锁定目录可关闭此窗口——无论文件权限如何，其他用户都无法访问 0700 目录中的文件。

   然后使用客户端的文件写入工具写入文件。格式为每行一个 KEY=value，不加引号（我们的值从不包含空格、= 或换行符）：

   GB_API_KEY=<value>
   GB_API_URL=<value or omit line>
   GB_APP_URL=<value or omit line>
   

   然后设置文件权限，作为双重保险：

   chmod 600 ~/.config/growthbook/.env
   

   0600 表示仅所有者可读写。目录权限设为 0700、文件权限设为 0600 后，系统上的其他用户都无法访问该密钥。

6. 报告。 告知用户：

   • 文件所在位置（~/.config/growthbook/.env）。
   • 文件包含的内容（遮盖 API 密钥，仅显示末尾 4 位）。
   • gb-call app-origin 返回的受信任 UI 源站。
   • 环境变量优先于文件，因此 CI / 单次覆盖仍可正常使用。
   • 重新运行 gb-setup 技能会更新该文件。
   • 他们接下来可能需要的内容：feature-flags 技能（flag-search 工作流），用于查看功能标志；或 experiments 技能（experiment-brainstorm 工作流），用于查看过去的结果。

安全防护

• 绝不要以明文回显 API 密钥。 始终屏蔽密钥，仅保留最后 4 个字符。技能的输出最终会显示在用户的终端和对话记录中。
• 在用户粘贴密钥前，先说明对话记录暴露风险。 在聊天中输入的值可能会被 Agent 客户端存储，并发送给已配置的模型提供商；技能无法事后将其删除。始终建议使用新创建、范围受限的 PAT，而不是重复使用管理员令牌。这并非过度谨慎——对于要求用户在对话界面中粘贴密钥的工作流，这是正确的处理方式。
• 撤销密钥的建议是切实有效的补救措施，不是脚注。 如果密钥曾经暴露，唯一有效的补救措施是在 <GB_APP_URL>/account/personal-access-tokens（或云端默认地址）撤销并轮换密钥。只要用户对旧密钥或共享密钥表示担忧，就应说明这一点。
• 写入文件前先将目录权限设为 0700；写入文件后再将文件权限设为 0600。 顺序很重要。Write 工具会继承用户的 umask，而在大多数系统中，文件会以 0644（所有用户可读）权限创建。先锁定目录，就能确保在 Write 和 chmod 之间的短暂窗口内，其他用户也无法访问文件。然后再通过 chmod 加固文件，作为纵深防御。两步都不可省略；跳过任何一步都会导致 PAT 泄露。
• 对于每个变量，环境变量的优先级都高于文件中的值。 如果某个值已在 process.env 中设置，gb-call 会忽略该变量在文件中的值。如果两者都已配置，应说明这一点，让用户了解实际生效的值。
• 通过真实端点验证，而不只是检查格式。 一个“看起来正确”但无法使用的令牌比没有令牌更糟糕——用户会以为自己已经完成配置。GET /api/v1/projects 请求轻量、需要身份验证，并且适用于所有套餐层级。
• 无需收集所有者标识符。 PAT 与 GrowthBook 用户关联，因此写入类技能（flag-create、experiment-launch）会让 API 自动将新建的标志和实验归属到令牌对应的用户。设置时不要询问邮箱或 userId。
• 不要去除行值开头的空白，但要去除末尾的空白。 PAT 不应包含任何空白；如果用户从剪贴板粘贴的内容末尾带有换行符，应将其去除。开头的空白不常见，因此提示用户而不是静默修正更安全。
• 不要写入不完整的文件。 如果验证失败，应立即停止，且不要触碰 ~/.config/growthbook/.env。用户可以重新运行设置；绝不要用错误配置覆盖可用配置。
• 去除两个 URL 末尾的斜杠。 gb-call 也会规范化 GB_APP_URL，但存储格式整洁的源站地址可以避免输出不一致和双斜杠问题。
• 不要根据 GB_API_URL 推断 GB_APP_URL。 api. → app. 的惯例并不适用于所有可自托管部署。应明确询问应用源站地址。
• 不要建议使用我们实际上并未使用的环境变量。 仅限 GB_API_KEY、GB_API_URL 和 GB_APP_URL。其他变量都属于范围蔓延，会让未来的贡献者感到困惑。

文件格式参考

~/.config/growthbook/.env：

GB_API_KEY=gb_pat_abc123def456
GB_API_URL=https://api.your-self-hosted.com
GB_APP_URL=https://growthbook.your-self-hosted.com

以 # 开头的行是注释。空行会被忽略。不需要加引号；值会从第一个 = 开始，原样读取至行尾。

使用的端点

• GET /api/v1/projects — 仅用于验证。请求轻量、需要身份验证，且适用于所有套餐层级。

后续衔接

• feature-flags 技能（flag-search 工作流）——设置完成后的自然首选调用（无需必填输入，可用于测试新配置）。
• experiments 技能（experiment-brainstorm 工作流）——如果组织中已有已停止的实验，可立即显示这些实验。
• 任何会发出配置相关错误的技能都会引导用户返回此处。