experiment-analyze

experiment-analyze

获取结果，仅当缓存数据超过 24 小时，或用户想查看不同的阶段／维度切分时才刷新快照，然后进行解读。由于包含条件轮询循环和统计解读，这是目录中最复杂的技能——请放慢速度，仔细执行每个步骤。

所有 API 调用都通过内置辅助脚本完成：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。它需要 GB_API_KEY——请在 shell 中设置，或通过 /growthbook:gb-setup 写入 ~/.config/growthbook/.env。如果未设置或无效，gb-call 的错误消息会指引你返回 /growthbook:gb-setup。此技能还会在轮询调用之间使用 sleep。

工作流

1. 在一次调用中获取结果和实验元数据。 /results 会返回 { experiment, result }——这与 GrowthBook UI 结果视图使用的载荷相同，因此无需单独调用获取元数据。

   如果用户提供的是名称而不是 ID（“结账测试”），请先解析——q 会匹配名称、跟踪键、描述和假设：

   gb-call GET '/api/v1/experiments?q=checkout&sortBy=dateUpdated&sortOrder=desc&limit=10'
   

   如果有多个实验都可能符合，请列出候选项并让用户选择——不要猜测。

   gb-call GET /api/v1/experiments/<experiment-id>/results
   # or, when the user asks for a specific phase / dimension cut:
   gb-call GET '/api/v1/experiments/<experiment-id>/results?phase=1&dimension=exp:country'
   

   phase 和 dimension 查询参数会筛选出使用这些设置创建的最新快照；若要查看默认的“效果如何”视图，则两者都省略。

   从 experiment 中获取：

   • status——running 或 stopped 都可以进行分析。如果是 draft，则没有结果可供解读；请告知用户。
   • type——如果为 "multi-armed-bandit"，则停止并告知用户，此技能针对标准 A/B 测试。多臂老虎机的报告方式不同（每个实验组的概率、动态流量分配），不应使用标准的胜出／落败框架解读。
   • settings.statsEngine——"bayesian"（默认值）或 "frequentist"。此设置决定下文的指标解读步骤。
   • regressionAdjustmentEnabled（CUPED）和 sequentialTestingEnabled——会影响要报告的内容。

   从 result 中获取：

   • id——快照 ID；如果需要刷新，则在步骤 3 中使用。
   • dateUpdated——创建此快照时的 ISO 时间戳，用于在步骤 2 中检查数据是否过期。
   • 各实验组的指标数据本身（提升估计值、区间、样本量）——供步骤 4 解读。

   如果响应报错 "No results found for that experiment"，则说明实验已启动，但尚不存在快照（自动刷新尚未运行，或你筛选的阶段／维度从未生成过快照）。跳过步骤 2，直接进入步骤 3。

2. 决定是否刷新。 根据 result.dateUpdated 分支处理：

   • 快照创建时间不到 24 小时，且现有快照符合用户要求的阶段／维度 → 跳过步骤 3，进入步骤 4。
   • 快照创建时间超过 24 小时，或用户明确要求生成新快照 → 执行步骤 3。

   默认情况下，服务每 6 小时自动刷新一次快照（EXPERIMENT_REFRESH_FREQUENCY），因此不到 24 小时的数据通常近期至少刷新过一次。24 小时的门槛有意设得较为保守——如果数据没有变化，就不要浪费快照计算预算。

3. 触发新快照、轮询，然后重新获取结果。

   3a. POST 创建快照。 可选的请求体字段用于决定计算内容；请传入与步骤 1 中用户要求相同的 phase／dimension：

   • phase（整数，从 0 开始索引）：如果实验有多个阶段，可指定某个阶段——例如，实验已扩大流量后，重新分析扩大流量前的阶段。默认为最新阶段。
   • dimension（字符串）：按维度拆分结果。内置选项："pre:date"、"pre:activation"。对于已配置的 Unit Dimension，请使用其 ID（例如 "dim_abc123"）。对于 Experiment Dimension，请加上 "exp:" 前缀（例如 "exp:country"）。

   echo '{}' | gb-call POST /api/v1/experiments/<experiment-id>/snapshot -
   # or with phase + dimension:
   echo '{"phase": 1, "dimension": "exp:country"}' \
     | gb-call POST /api/v1/experiments/<experiment-id>/snapshot -
   

   响应为 { snapshot: { id, experiment, status } }。请获取 snapshot.id。

   3b. 轮询等待完成。 快照创建是异步的：

   for i in $(seq 1 60); do
     gb-call GET /api/v1/snapshots/<snapshot-id>
     # Parse snapshot.status. Stop when it is "success" or "error".
     sleep 5
   done
   

   将循环限制为 60 次迭代（5 分钟）。如果到时仍未完成，请停止轮询，并告知用户快照仍在生成中 — 他们可以几分钟后重试此技能。不要无限循环。

   3c. 使用 3a 中相同的阶段／维度参数重新获取结果，然后重新捕获步骤 1 中列出的字段：

   gb-call GET '/api/v1/experiments/<experiment-id>/results'
   # or, if 3a passed phase/dimension:
   gb-call GET '/api/v1/experiments/<experiment-id>/results?phase=1&dimension=exp:country'
   

4. 先运行数据质量检查，再进行解读。 GrowthBook 会显示六项健康检查；任何一项失败都会影响结果的解读。请醒目地指出失败项 — 不要将它们埋没在内容中。

   数据质量检查（按顺序）：

   • SRM（样本比例不匹配）。 实际流量分配与配置的分配比例之间的差异。若检查失败，则下游结果无效 — 请醒目说明这一点，并暂停解读，直到用户了解偏差风险。常见原因：机器人流量、广告拦截器阻止客户端跟踪、实验期间定向条件发生变化、激活指标偏差。
   • 多重曝光。 被分配到多个变体的用户。比率较低（<1%）通常没问题；比率较高则表明可能未配置固定分桶，或哈希属性不稳定。
   • 最低数据阈值。 每项指标的最低要求（按指标配置）。如果某项指标低于其阈值，则该指标的结果尚不可信。
   • 变体 ID 不匹配。 曝光数据报告的变体 ID 与实验中配置的变体不匹配。这表明存在跟踪／配置错误。
   • 异常提升。 每项指标的提升幅度超过配置的异常阈值。这不代表结果有误，但如此大的真实提升并不常见 — 通常是跟踪或指标定义问题。
   • 护栏指标。 文档将其列在数据质量检查下，因为护栏检查失败意味着必须停止发布。请逐项检查：是否有任何指标出现退化？即使护栏指标上的退化不具统计显著性，也值得指出。注意：按设计，护栏指标不应用多重比较校正。

   效力检查。 实验是否达到或接近预期样本量？如果远未达到（例如，<50% 的计划样本量），请提醒用户结论仍是推测性的 — 尤其是在频率学引擎上，反复查看结果会更显著地提高假阳性率。贝叶斯结果更能抵御反复查看的影响，但达到计划样本量仍有益。

   主要指标 — 根据统计引擎分支处理：

   • 贝叶斯（settings.statsEngine === "bayesian"，默认值）： 报告获胜概率（根据数据和先验，处理组胜过对照组的概率）以及相对提升分布（点估计 + 可信区间）。GrowthBook 将 >95% 的获胜概率视为强烈的正向信号；<5% 则视为强烈的负向信号；其余情况均为不确定。不要编造 p 值。
   • 频率学（settings.statsEngine === "frequentist"）： 报告提升点估计、95% 置信区间，以及置信区间是否跨越零。如果 regressionAdjustmentEnabled 为 true（CUPED），点估计可能与原始均值不同；置信区间通常更窄。如果 sequentialTestingEnabled 为 true，则置信区间会有意加宽，以便安全地反复查看结果 — 请指出这一点，避免用户将其与非序贯置信区间进行比较。

   次要指标。 请呈现，但要注明其局限 — 这些指标仅用于探索；在频率学引擎上存在多重比较风险（GrowthBook 仅在该引擎上应用校正；在贝叶斯引擎上，隐式校正来自先验）。如果主要指标没有变化，不要宣称“我们在 X 指标上获胜”。

   维度（用户提出要求时）。 如果快照是在指定 dimension 的情况下生成的，结果端点会返回各维度的细分数据。请指出显著的差异，但不要为了寻找结果而反复筛选 — 维度分析会增加比较次数。

5. 呈现结果。 使用以下格式（不适用的行可省略）：

   ## Experiment: <name> (<id>)
   - Status: <running|stopped>
   - Type: <standard|multi-armed-bandit>
   - Stats engine: <bayesian|frequentist>
   - Adjustments: <CUPED on/off, sequential testing on/off>
   - Phase: <phase name or index>
   - Dimension: <none | dimension id used>
   - Sample size: <total users> across N variations
   - Snapshot timestamp: <when this snapshot ran>
   
   ### Data-quality checks
   - SRM: <pass / fail with detail>
   - Multiple Exposures: <pass / rate>
   - Minimum Data Thresholds: <met / not met, per metric>
   - Variation ID Mismatch: <pass / fail>
   - Suspicious Uplift: <none / per-metric flags>
   
   ### Primary metric: <name>
   - Variation 0 (Control): <baseline value>
   - Variation 1 (Treatment): <value>
   - **Bayesian:** Chance to Win <X%>, relative lift <±Y%>, 95% CrI [a, b]
   - **Frequentist:** lift <±Y%>, 95% CI [a, b]<note if CIs are sequential>
   - Verdict: <won / lost / inconclusive>
   
   ### Guardrails
   - <metric>: <safe / regressed by Y%>
   
   ### Secondary metrics
   - <metric>: <lift / no movement> <multiple-comparison caveat if frequentist>
   
   ### Recommendation
   <one paragraph: ship, kill, extend, or investigate>
   

6. 提供实验链接，然后建议下一步。 始终提供直接 UI 链接，以便用户查看实时结果、维度细分，以及 /results 未返回的历史快照：

   View in GrowthBook: <host>/experiment/<exp_id>
   

   将 GB_API_URL 中的 api. 替换为 app.，以推导出 <host>（符合 experiment-launch 的约定；使用默认云主机时，会得到 https://app.growthbook.io）。

   然后根据第 1 步中的 experiment.status 建议下一步操作：

   • running 且结果明确 → 建议使用选定的变体执行 experiment-stop。
   • running 且结果尚不明确 → 建议等待或延长实验。
   • stopped → 指引用户通过 flag-targeting 清理标志，以更新或移除关联标志上的 experiment-ref 规则。

注意事项

• 六项数据质量检查都必须在解读之前完成。 SRM、多次曝光、最低数据阈值、变体 ID 不匹配、可疑提升和护栏。任何一项检查失败，都会改变结果的解读方式（或决定是否应解读结果）。不要把这些检查埋在主要指标标题之下。
• 根据 settings.statsEngine 分支解读。 贝叶斯（默认）报告获胜概率和可信区间；频率学派报告提升幅度和置信区间。不要编造 API 未返回的 p 值，也不要把贝叶斯结果称为“95% CI”（它是可信区间，不是置信区间）。
• 多重比较校正仅适用于频率学派，且不包括护栏。 报告次要指标时，注明校正状态。贝叶斯方法中，先验会提供隐式收缩；不会应用校正。
• CUPED 和序贯检验会改变置信区间的解读方式。 如果 regressionAdjustmentEnabled 为 true，点估计可能与原始均值不同，置信区间通常也会更窄。如果 sequentialTestingEnabled 为 true，置信区间会有意设得更宽——请说明这一点，以免用户将其与非序贯结果混为一谈。
• 不要窥视数据后就做决定。 统计功效不足的实验，其中期数据会有较大噪声。频率学派的窥视会提高假阳性率；贝叶斯方法更稳健，但达到计划样本量仍然有益。
• 多臂老虎机不在范围内。 type === "multi-armed-bandit" 会报告各臂的概率并动态重新分配流量。请停止处理，并告知用户在 UI 中查看多臂老虎机结果。
• 激活指标偏差会伪装成“SRM 通过”。 如果实验使用的激活指标受变体差异下游影响（例如变体会影响注册完成率时使用“已完成注册”），整体分流看起来可能正常，但激活用户群体却存在偏差。仪表板会显示这一点；如果在元数据中发现这种模式，请指出。
• 不要把次要指标提升为主要指标。 如果主要指标没有变化，实验就没有变化——次要指标仅供探索。
• 轮询有上限。 60 次迭代 × 5 秒 = 5 分钟。如果快照届时仍未完成，就停止并报告。不要持续运行数小时。
• 快照时间戳很重要。 报告结果时，务必展示 result.dateUpdated——第 2 步会据此判断是否需要刷新，用户也会据此判断低流量实验是否有进展。快照过期很常见；不要隐瞒。
• 24 小时是刻意设定的上限，不是自动刷新周期。 服务默认每 6 小时自动刷新一次，因此，快照在 24 小时以内时，几乎总是至少刷新过一次。此技能设置 24 小时门槛，为用户提供实用且保守的时间窗口，同时避免对尚未变化的数据进行快照计算。不要把门槛降到“任何一分钟前的数据”——这会让繁忙组织持续触及每分钟 60 次请求的限制。
• 注意速率限制。 正常情况下只需调用一次 /results。最糟情况下（没有快照或快照已过期 + 轮询 60 次 + 重新获取）约需 63 次调用，分布在 5 分钟内（约每分钟 13 次），远低于每分钟 60 次。如果同一组织中有多位用户同时调用此功能，仍可能触及限制——如果 gb-call 返回 429，请明确指出。
• 只读。 此技能绝不会停止或修改实验。用户想要采取操作时，应转交给 experiment-stop。
• q 不接受否定符和运算符，传入后会返回 400。 列表端点的 q 参数接受应用的搜索语法（status:running tag:checkout 加自由文本），但会拒绝 !、~、^、>、<、=。仅发送普通的 field:value 标记和自由文本。
• 按名称解析时，用 bandits 而非 type 过滤多臂老虎机。 响应中的 type 字段（standard / multi-armed-bandit）不是列表查询参数；传入 type= 会返回 400。使用 bandits=false 将多臂老虎机排除在候选项之外，因为此技能会在遇到它们时停止处理。（implementationType 属于不同维度——关联变更类型。）

使用的端点

• GET /api/v1/experiments?q=<text> — 当用户只提供名称或关键词时，解析实验 ID。q 会匹配名称、跟踪键、描述和假设；搭配 sortBy=dateUpdated&sortOrder=desc，可优先显示进行中的实验。
• GET /api/v1/experiments/<id>/results — 主要入口；返回 { experiment, result }，因此步骤 1 可通过一次调用获取元数据、状态和快照时间戳（result.dateUpdated）。接受 phase / dimension 查询参数。
• POST /api/v1/experiments/<id>/snapshot — 当结果超过 24 小时，或用户需要缓存快照未涵盖的阶段/维度数据时，触发新快照。请求体接受 phase（整数）和 dimension（字符串）。
• GET /api/v1/snapshots/<snapshot-id> — 轮询快照是否完成（间隔 5 秒，最多 60 次）。返回 { snapshot: { id, experiment, status } }。

后续交接

• experiment-stop — 用户准备根据明确的结果采取行动时使用。
• flag-targeting — 停止实验并选出胜出方案后，如果存在关联标志，需要更新或移除其 experiment-ref 规则。
• experiment-brainstorm — 根据过往实验结果，为下一轮测试构思方案。
• experiment-statistics（发布后）— 用于深入探讨 CUPED、序贯检验、多重比较和维度分析。