experiment-launch

experiment-launch

端到端启动 GrowthBook A/B 测试：以草稿状态创建实验，准备或复用功能标志，在全新的草稿修订版中添加实验引用规则，然后调用 /start 发布规则并将实验切换为运行状态。处理需要审批和启动前检查清单失败的情况。

所有 API 调用都通过捆绑的辅助脚本完成：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。它需要 GB_API_KEY——可在 shell 中设置，或通过 /growthbook:gb-setup 写入 ~/.config/growthbook/.env。如果缺失或无效，gb-call 的错误消息会提示使用 /growthbook:gb-setup。

必需输入

开始前，请从用户（或先前的技能输出）中收集以下信息。缺少时请询问。

• 功能标志名称 — kebab-case 键，正则表达式为 [a-zA-Z0-9_-]
• 实验名称 — 便于阅读的名称
• 变体 — {name, value} 数组，长度 ≥ 2。第一项为对照组。规则中的值会序列化为字符串（布尔值 → "false"/"true"，数字 → "42"，JSON → JSON 编码后的字符串）。
• 项目 ID（可选）— 将实验和标志固定到特定项目

可选输入

• 假设 — 可证伪；采用 if/then/because 格式
• 模板描述 — 与 /v1/experiment-templates 返回的 templateMetadata.name/description 匹配的英文描述。如果未提供描述且存在模板，请让用户选择一个或跳过。

如果不使用模板，还需收集以下信息（或在步骤 2 中交互式确定）：

• 数据源 — ID 或英文名称
• 哈希属性 — 随机化的单位（id、device_id 等）。必须与所选数据源中分配查询的 identifierType 相同。
• 分配查询 — ID 或英文名称；位于所选数据源的 assignmentQueries 中
• 目标指标 ID — 恰好一个（用于决定发布或终止的主要 KPI）
• 次要指标 ID — 辅助指标
• 护栏指标 ID — 不应出现退化的防御性指标

工作流

使用此清单跟踪进度。不得跳过或调整顺序。

- [ ] 1. Pick a template (or skip)
- [ ] 2. Resolve hash attribute → datasource → assignment query → metrics (no-template path only)
- [ ] 3. Create the experiment in draft
- [ ] 4. Create or reuse the feature flag
- [ ] 5. Add the experiment-ref rule on a fresh draft revision
- [ ] 6. Prompt user to QA the experiment and feature flag config
- [ ] 7. POST /start; branch to 7a (approval) or 7b (checklist) on 400
- [ ] 8. Report links and state

1. 选择模板（或跳过）

gb-call GET /api/v1/experiment-templates

• 没有模板 → 不使用模板继续；转到步骤 2。
• 有一个或多个模板 → 按 name — description 格式列出，并在末尾提供“跳过”选项。如果已提供模板描述，请根据 templateMetadata.name/description 预选最匹配的模板并确认。切勿虚构模板。

如果选择了模板，请记录：id（作为 templateId）、datasource、exposureQueryId、hashAttribute、goalMetrics、statsEngine、targeting。模板会注入这些信息；完全跳过步骤 2。

如果模板的 type 为 "multi-armed-bandit"，请暂停并向用户确认。老虎机测试与标准 A/B 测试的行为差异很大（动态流量分配、使用各组概率而非赢家/输家，以及不同的分析方式），而此技能的启动和分析假设是针对 type: "standard" 编写的。目前建议用户在界面中配置老虎机测试。

2. 解析哈希属性 → 数据源 → 分配查询 → 指标

仅适用于无模板路径。顺序很重要——先选择哈希属性，以免被困在无法基于该属性随机分配的某个数据源上。

2a. 选择哈希属性。 筛选出标记为哈希属性的属性：

gb-call GET /api/v1/attributes

显示 hashAttribute === true 且 archived !== true 的属性。请用户选择。如果筛选结果为空，请停止，并告知用户在 GrowthBook 的 Settings → Attributes 中将至少一个属性标记为哈希属性。

2b. 选择数据源。

gb-call GET /api/v1/data-sources

根据 dataSources[].name / id 解析英文名称或 ID。记录 DATASOURCE_ID 并保留完整对象——2c 会读取其中的 assignmentQueries。

2c. 选择分配查询。 筛选 dataSources[].assignmentQueries，仅保留 identifierType === HASH_ATTRIBUTE 的条目：

• 恰好匹配一项 → 自动选择；打印一行说明所选项。
• 未匹配到任何项 → 停止并提供三种解决方法：选择其他数据源（重新运行 2b）、更改哈希属性（重新运行 2a），或在 GrowthBook 中为 <HASH_ATTRIBUTE> 添加分配查询。
• 匹配两项或更多 → 将每项列为 name (identifierType=<value>) — <description>，并让用户选择。

如果 assignmentQueries 整体为空，请停止并告知用户先在 GrowthBook 中配置一项，然后再重新运行。

2d. 按数据源筛选并选择指标。 API 不接受来自与实验不同的数据源的指标：

gb-call GET '/api/v1/fact-metrics?datasourceId=<DATASOURCE_ID>&limit=100'
gb-call GET '/api/v1/metrics?datasourceId=<DATASOURCE_ID>&limit=100'

帮助用户选择：

• 目标指标（GOAL_METRIC_IDS）——理想情况下选择一个，最多两个；如果达到三个或更多，应提出异议，并将其余指标降为次要指标或护栏指标。
• 次要指标（SECONDARY_METRIC_IDS）——提供辅助背景信息。
• 护栏指标（GUARDRAIL_METRIC_IDS）——用于防范风险。如果用户未选择任何指标，应提出异议；每个实验都至少需要一个护栏指标。根据设计，护栏指标不参与多重比较校正。

3. 以草稿状态创建实验

将 trackingKey 设置为功能标志名称，以便 SDK 将曝光关联到该标志。每个变体都需要稳定的字符串 key（"0"、"1"……）和 name。变体值设在标志规则（步骤 5）上，而不是实验负载中。

模板路径——不要同时发送 datasourceId / assignmentQueryId；模板会提供这些字段，API 会拒绝这种组合。

{
  "templateId": "<from step 1>",
  "trackingKey": "<flag-name>",
  "name": "<experiment name>",
  "hypothesis": "<hypothesis>",
  "variations": [
    { "key": "0", "name": "Control" },
    { "key": "1", "name": "Treatment" }
  ],
  "project": "<project id, omit if org-wide>"
}

无模板路径——明确发送步骤 2 中的所有内容：

{
  "datasourceId": "<DATASOURCE_ID>",
  "assignmentQueryId": "<ASSIGNMENT_QUERY_ID>",
  "hashAttribute": "<HASH_ATTRIBUTE>",
  "trackingKey": "<flag-name>",
  "name": "<experiment name>",
  "hypothesis": "<hypothesis>",
  "variations": [
    {"key": "0", "name": "Control"},
    {"key": "1", "name": "Treatment"}
  ],
  "metrics": ["<GOAL_METRIC_ID>"],
  "secondaryMetrics": [<SECONDARY_METRIC_IDS as JSON array>],
  "guardrailMetrics": [<GUARDRAIL_METRIC_IDS as JSON array>],
  "project": "<project id, omit if org-wide>"
}

注意：

• metrics 是目标指标数组；按照单个目标指标的规则，该数组长度应始终为 1。
• 如果用户未选择 secondaryMetrics / guardrailMetrics，则完全省略这些字段。不要发送空数组。

然后发送 POST 请求：

echo '<payload-json>' | gb-call POST /api/v1/experiments -

从响应中记录：

• experiment.id——用于步骤 5 和 6。
• experiment.variations[].variationId——每个变体的字符串 ID（例如 var_abc123）。步骤 5 需要这些 ID；experiment-ref 规则必须提供它们。

4. 创建或复用功能标志

除非用户说该标志已存在，否则先尝试创建。该标志必须默认使用对照组值（变体 0 的值），并序列化为字符串。所有环境也都默认为关闭。

{
  "id": "<flag-name>",
  "valueType": "<boolean|string|number|json>",
  "defaultValue": "<control value as string>",
  "description": "Drives experiment: <experiment name> (<exp_id>)",
  "project": "<project id, omit if org-wide>"
}

echo '<payload-json>' | gb-call POST /api/v2/features -

• 成功 → 转到第 5 步。
• 409 Conflict（标志已存在）→ 继续执行下方的复用兼容性检查。

复用路径 — 获取并验证：

gb-call GET /api/v2/features/<flag-name>

根据响应执行以下兼容性检查。每行说明检查失败时的处理方式：

检查	失败时的处理
archived === false	停止。 告诉用户先在 UI 中取消归档该标志，然后再重新运行。
valueType 与实验的 <boolean|string|number|json> 匹配	停止。 显示这两个值；不要静默更改类型。
project 与实验的项目匹配（如果已设置）	停止。 复用其他项目的标志会导致实验路由错误。
defaultValue 等于对照组值（按字符串比较）	警告，但不要停止。实验规则会提供变体值；只有规则不匹配时才会应用现有默认值。询问“继续吗？”
尚未附加 type === "experiment-ref" 且 experimentId === <exp_id> 的现有规则	如果已存在 → 此实验已完成关联。跳过第 5 步，直接转到第 6 步。
同一环境中没有与其他_运行中_实验冲突的 experiment-ref 规则	警告，但不要停止。询问“此标志目前正在驱动实验 <other_id>；要在其旁边再添加一条规则吗？”

所有检查通过后，记录该标志的身份信息并继续第 5 步。此处不要修改现有标志——所有修改都通过第 5 步中的草稿修订完成。

5. 在新的草稿修订中添加 experiment-ref 规则

使用字面值 new，在一次调用中创建草稿并添加规则。路径段 new 是一个特殊值，可原子化地创建一个从当前生效修订分支出来的草稿。如果此功能有多个环境，请询问用户要在哪些环境中启用，并确保除了向这些环境添加规则外，此规则还会在这些环境中启用功能标志。

{
  "rule": {
    "type": "experiment-ref",
    "experimentId": "<exp_id from step 3>",
    "enabled": true,
    "allEnvironments": true,
    "variations": [
      {
        "value": "<variation 0 value as string>",
        "variationId": "<var_id from step 3, position 0>"
      },
      {
        "value": "<variation 1 value as string>",
        "variationId": "<var_id from step 3, position 1>"
      }
    ],
    "description": "Experiment: <experiment name>"
  }
}

echo '<payload-json>' | gb-call POST /api/v2/features/<flag-name>/revisions/new/rules -

variations[] 必须为每个实验变体包含一个条目，顺序与第 3 步相同。每个条目都必须包含 value（序列化为字符串）和 variationId（第 3 步中记录的字符串 ID）——v2 features 验证器要求提供 variationId，省略会返回 400。记录返回的 version，作为草稿修订的版本。

此处不要发布修订。第 7 步中的 /start 调用会在将实验切换为运行状态时自动发布草稿。

6. 在 /start 前暂停进行 QA

截至此处，草稿修订和实验都可以撤销；第 7 步的 /start 会发布规则，并将实验切换为运行状态。

如果用户似乎也想在代码库中嵌入功能标志，现在正是合适的时机。

暂停并展示 UI 链接，让用户在 GrowthBook UI 中 QA 标志默认值、规则的变体值，以及实验的定向和指标：

• 实验：<host>/experiment/<exp_id>
• 功能：<host>/features/<flag-name>（草稿修订 <version>）

按照第 8 步所述，将 GB_API_URL 中的 api. 替换为 app.，以推导出 <host>。在继续执行第 7 步之前，等待用户明确同意。

7. 启动实验

gb-call POST /api/v1/experiments/<exp_id>/start '{}'

/start 端点会在服务端执行两项操作：

1. 发布第 5 步中的功能草稿修订（publishPendingFeatureDraftsForExperiment）。
2. 执行组织的上线前检查清单。

任一操作都可能失败并返回 400。按以下方式处理：

• 响应正文以 "This revision requires approval before publishing" 开头 → 第 7a 步。
• 响应正文列出未完成的检查清单项 → 第 7b 步。
• 2xx → 第 8 步。

7a. 需要审批

实验和标志都已创建；只有规则修订仍处于草稿状态。暂停，并向用户提供三种明确的处理方式：

你的组织要求在此功能标志规则上线前进行审批，而在规则发布之前，/start 不会将实验切换为运行状态。<flag-name> 的修订 <version> 目前处于草稿状态。请选择一种方式：

A. 标准审核流程（推荐）——我现在会发起审核。由一名队友（不能是你，因为草稿是你创建的）在 GrowthBook UI 的 <host>/features/<flag-name> 页面批准，然后你重新运行我，我会从 /start 继续。

B. 组织级绕过——由管理员在 Settings → General → Approvals 中启用“REST API always bypasses approval requirements”。之后重新运行我。

C. 按令牌绕过——使用在此项目中具有 bypassApprovalChecks 权限的个人访问令牌（管理员或自定义角色）。更新 GB_API_KEY，然后重新运行我。

如果用户选择 A，请为草稿申请审核并停止：

echo '{"comment":"Auto-requested by experiment-launch for <exp_id>"}' \
  | gb-call POST /api/v2/features/<flag-name>/revisions/<version>/request-review -

不要自行尝试 submit-review——API 会拒绝对你创建的草稿进行自我审批。暂停并告知用户，审批完成后重新运行。

如果用户选择 B 或 C，请用一行说明后停止。现有草稿会在重试时获取新的权限并发布。

不要静默重试 /start、忽略错误，或为了绕过策略而丢弃并重新创建草稿。

7b. 检查清单未完成

REST API 不提供单独的 start-checklist 端点——/start 的失败响应正文是权威来源。解析该响应，并逐字展示未完成的项目：

上线前检查清单尚未完成。/start 调用返回：

<full error body>

请在 GrowthBook UI 的 <host>/experiment/<exp_id> 页面中修复所列项目，然后重新运行我——我会直接从 /start 继续。

只有在用户明确要求绕过时，才在请求正文中使用 {"skipChecklist": true} 重试 /start。切勿默认绕过；检查清单是刻意设置的阻碍。

8. 报告

输出摘要：

• 实验名称和 id
• 功能标志 ID 和已发布修订版本
• 使用的模板（名称 + id，如有）
• 随机化单位（hashAttribute）
• 变体及其值
• 上线前检查清单状态（应为 allRequiredComplete=true）
• 实验状态（正常执行 /start 后应为 running）
• UI 直达链接（将 GB_API_URL 中的 api. 替换为 app.，以推导出主机地址）：
  • 实验：<host>/experiment/<exp_id>
  • 功能：<host>/features/<flag-name>

护栏

• 最好只设一个目标指标，最多两个。 GrowthBook 的决策框架有意将目标指标设为复数，功效计算器最多支持五个，但每增加一个目标指标都会降低统计功效，并使上线／终止决策更复杂。目标指标达到三个或更多时应提出异议；其余指标降为次要指标。
• 至少设置一个护栏指标。 如果用户跳过护栏指标，应提出异议。
• hashAttribute 和 assignmentQuery.identifierType 必须匹配。 不匹配是确实存在且可以修复的错误；请在步骤 2c 中说明修复方法。
• 指标必须属于实验的数据源。 在步骤 2d 中，按 datasourceId 筛选 /v1/metrics 和 /v1/fact-metrics。
• 不要将 templateId 与 datasourceId／assignmentQueryId 混用。 模板路径会提供这些参数；无模板路径则需明确提供。混用会导致 400 错误。
• 标志默认值 = 对照值。 对于关联标志的实验，变体值在规则中是字符串——布尔值用 "false"／"true"，数字用 "42"，json 则用 JSON 编码文本。
• 谨慎复用。 复用现有标志前，务必先执行步骤 4 的兼容性检查。若将实验关联到 valueType 错误、project 错误或规则冲突的标志，会导致实验出错，或影响队友正在进行的测试。
• 不要手动发布修订版本。 步骤 5 中的草稿会在步骤 7 通过 /start 发布。不要单独调用发布端点。- 审批失败：不要自行批准。 API 会阻止你批准自己创建的草稿。请改为引导用户完成步骤 6a。
• 默认情况下不要绕过清单失败。 只有在用户明确选择后，才设置 skipChecklist: true。

使用的端点

• GET /api/v1/experiment-templates — 列出模板
• GET /api/v1/attributes — 筛选 hashAttribute=true
• GET /api/v1/data-sources — 选择数据源和分配查询
• GET /api/v1/fact-metrics?datasourceId=…、GET /api/v1/metrics?datasourceId=… — 选择目标／次要／护栏指标
• POST /api/v1/experiments — 创建实验草稿
• POST /api/v2/features — 创建关联的功能标志（不复用时）
• GET /api/v2/features/<id> — 获取标志，以进行复用兼容性检查
• POST /api/v2/features/<id>/revisions/new/rules — 原子地创建草稿并添加实验引用规则
• POST /api/v2/features/<id>/revisions/<version>/request-review — 仅用于步骤 6a 中的“请求审核”路径
• POST /api/v1/experiments/<id>/start — 发布草稿修订版本并启动实验。当用户明确选择绕过启动前清单时，请求正文可接受 {"skipChecklist": true}。失败响应会在正文中包含规范原因——没有单独的 start-checklist GET 请求可供查询。

后续流程

• experiment-design — 如果不存在规格，先返回此处。
• flag-search — 仅知道名称或描述时，用于查找现有标志 ID。
• experiment-analyze — 实验运行且累积了流量后使用。
• experiment-stop — 结果确定后使用。
• 手动创建指标 — 如果所需指标尚不存在，用户必须先在 GrowthBook UI 的 <host>/metrics（事实指标则为 <host>/fact-tables）中创建指标，然后重新运行此技能。目前还没有相应技能。