launchdarkly-experiment-setup

LaunchDarkly 实验设置

你正在使用一项指导你在 LaunchDarkly 中设置并运行实验的技能。你的任务是设计实验，使用合适的指标、处理组和标志配置创建实验，开始收集数据，并在需要时在不同迭代之间调整设计，最后选出获胜方案并停止实验。在用户批准完整设计之前，绝不要创建指标或实验；在用户明确表示开始之前，绝不要启动迭代；除非用户提出要求，否则绝不要更改标志。请参阅“创建任何内容之前”，了解必需内容、建议和标签。请参阅工作流，了解如何收集信息并获得批准；参阅步骤 1，了解事件检查；参阅步骤 4，了解如何启动。

前提条件

此技能要求你在环境中配置远程托管的 LaunchDarkly MCP 服务。

必需的 MCP 工具：

• create-experiment — 使用初始迭代（假设、指标、处理组、标志配置）创建新实验。
• start-experiment-iteration — 开始收集实验当前草稿迭代的数据。
• get-experiment — 检查实验状态、处理组、指标和当前迭代。

可选的 MCP 工具：

• list-experiments — 浏览项目中的现有实验。
• update-experiment — 更新实验或其当前迭代的字段。此工具遵循 mutableFieldsByStatus，因此可编辑内容取决于迭代处于 not_started、running 还是 stopped 状态。被拒绝的输入会返回在 skipped 下。
• save-and-start-experiment-iteration — API 推荐的更改运行中实验的锁定字段的方式。此工具会停止当前迭代，使用提供的字段更新创建新草稿，并在一次调用中启动它。
• stop-experiment-iteration — 停止运行中的迭代。必须指定获胜方案：传入 winningTreatmentId（以及 winningReason）。如果没有任何变体表现更好，则选择基线／对照组作为获胜方案。
• list-metrics、create-metric、list-metric-events — 管理实验引用的指标。
• get-flag — 读取一个标志在某个环境中的定向配置：标志是否开启、规则投放的变体、关闭时使用的变体，以及该规则是否采用百分比逐步投放。
• list-flags — 按名称或键搜索项目中的标志。
• create-flag — 在项目中创建功能标志。除非开启，否则该标志在所有环境中均处于关闭状态。
• get-flag-status-across-envs — 读取标志在各环境中的状态（new、active、launched 或 inactive）。
• search-contexts — 按类型查找环境中存储的上下文，以了解正在使用哪些上下文类型。

核心概念

什么是实验？

LaunchDarkly 中的实验用于衡量功能标志变体对关键指标的影响。实验包括：

• 处理组：要进行比较的标志变体（对照组与测试组）。每个处理组都有一个 allocationPercent；所有处理组的值之和应为 100。
• 指标：要衡量的内容（转化率、延迟、收入等）。必须指定一个主要指标。
• 标志配置：驱动实验的定向规则的 flagKey、ruleId 和 flagConfigVersion。
• 迭代：单个数据收集周期。迭代创建时处于 not_started 状态，启动后变为 running，结束后变为 stopped。
• 留出组（可选）：项目级用户组，不纳入实验，用于测量基线（holdoutId）。

实验生命周期

1. 创建 实验及其首次迭代（create-experiment）。
2. 开始迭代以启动数据收集（start-experiment-iteration），仅在用户明确表示要开始后执行。
3. 监控数据累积过程中的结果（get-experiment）。
4. 如有需要，可在实验进行期间调整设计——通过调用 save-and-start-experiment-iteration 更改 treatments、metrics 或 methodology 等已锁定字段。该调用会停止当前迭代，创建包含更改的新草稿并启动它。此调用会启动数据收集，因此仅在用户明确表示要开始后执行。
5. 当确定胜出方案或有了明确结论时，停止迭代（stop-experiment-iteration）。
6. 发布胜出的变体。

核心原则

1. 指标优先：创建实验前，确保要引用的指标已存在。
2. 明确假设：每次迭代都需要用户提供一个 hypothesis 字符串。请参阅“创建任何内容之前”。
3. 设置合理的对照组：必须且只能有一个 treatment 设置 baseline: true。
4. 确保样本量充足：让迭代运行足够长的时间，以便作出决策。请参阅步骤 7。
5. 一次只改一项：每个实验只测试一个变量，以便明确归因。

创建任何内容之前

以下三项必须由用户提供。绝不要自行填写：

• 标记和变体：要测试哪个标记，以及哪些变体参与实验。
• 假设：用户预计会改善什么；如果知道，也要说明改善幅度。
• 主要指标：用于判定结果的唯一指标或漏斗。

如果缺少上述任一项，请留空，直到用户提供。它们会放在收集消息中。请参阅工作流。用户指定标记后，请查看步骤 2。

对照变体：这些变体中哪个是基线（baseline: true）。如果用户已指定，请使用该变体。如果用户未指定：

• 如果标记是全新的、目标规则采用百分比分流，或标记处于关闭状态且 get-flag-status-across-envs 报告该环境为 inactive，则询问用户并留空。标记是全新的，指它是在本次对话中创建的，或者 get-flag-status-across-envs 报告该环境为 new：该标记创建时间少于七天，且从未在该环境中评估过。百分比分流是指目标规则将流量分配到多个变体，而不是只投放一个变体。get-flag 会显示是哪种情况。inactive 表示该标记至少七天未被评估，因此当前没有人为用户投放关闭变体。
• 否则，提供一个建议。如果标记处于开启状态，建议使用目标规则当前投放的变体。如果标记处于关闭状态，建议使用其关闭变体。

随机化单位：实验执行随机化所依据的上下文类型。如果用户已指定，请使用该值。如果用户未指定，请针对此项目和环境调用 search-contexts。只有在 kind 为 user 时能返回上下文，并且筛选条件 kind notEquals "user" 返回 totalCount 为 0（即当前仅使用 user 这一上下文类型）时，才建议使用 user。如果无法使用 search-contexts、没有返回任何上下文，或存储了其他类型的上下文，请询问用户并留空。

在设计中，将每个建议值标注为建议项，并用一行说明理由，例如 对照（建议，用户当前看到的内容）：开始免费试用。用户可以在批准前更改任何建议。批准设计即表示接受设计中仍显示的建议。

用户未提及的设置可以使用 LaunchDarkly 的默认值。在设计中列出使用的每项默认值：

• 流量分配：在用户指定的变体之间均等设置 allocationPercent（两个变体即各占 50%）。这些值的总和必须为 100。
• 统计方法：LaunchDarkly 默认值（频率学派、序贯检验）。除非用户选择其他方法，否则不要发送 methodology。如果用户选择了其他方法，请发送该值，并在此处显示该方法，而不是默认值。贝叶斯选项为 methodology "bayesian"。
• 数据源：dataSource "launchdarkly"。
• 重新分配：canReshuffleTraffic true。

除非用户设置了 analysisConfig，否则将其留空，并在设计中说明这一点。随机化单位绝不属于这些默认值。

工作流

如果没有缺少任何信息，请跳过收集信息的消息，直接进入设计。否则，请先在一条消息中收集所有缺失信息，然后等待：

• 缺少标志及其变体、假设或主要指标时
• get-flag 找不到指定标志时：说明这一点，并在一条消息中提供三个选项：更正键（列出 list-flags 中相似的标志）；自行创建标志，然后告诉你继续；或由你创建标志。对于最后一个选项，根据他们的设计提出键、名称、类型和变体，说明该标志将以关闭状态创建，并等待明确的确认，然后再调用 create-flag。如果已安装 launchdarkly-flag-create，此步骤请遵循其中的说明。标志创建后，继续设置。除非他们选择该选项并批准详情，否则绝不创建标志。
• 根据上述规则应询问而不是建议时，缺少对照项或随机化单位时
• 新的主要指标尚未明确时，询问其类型（custom、pageview 或 click）、依据（事件键、URL 匹配或点击选择器）以及衡量方式（转化的单位占比、总次数或平均值）

收集信息时，可以调用 list-metrics 和 get-flag。不能调用 create-metric 和 create-experiment。

如果用户的措辞已经明确了其中任何一项，就不要询问。“发送了 cta-clicked 事件的用户占比”已经说明了衡量方式、类型和事件键。

只有在没有任何空缺时才展示设计。不得展示包含缺失值的设计。请包含上述收集的所有信息、其他处理方案、标志配置（flagKey、ruleId、flagConfigVersion），以及你采用的每项默认值。统计方法默认显示为 LaunchDarkly default (frequentist, sequential testing)；如果用户选择了方法，则显示他们的选择。为每个建议值标注。请参阅“创建任何内容之前”。

在此处停止，直到用户批准设计。

只有在用户明确批准已向其展示的完整设计后，才创建指标和实验。如果用户在看到设计后更改了任何内容，请展示更新后的设计，并再次征求确认。

步骤 1：准备指标

1. 使用 list-metrics 查找现有指标。用户会指定主要指标。
2. 如果该指标已存在，在设计评审中保留其名称和键。
3. 如果该指标不存在，未找到只意味着这是一个新指标。用户通常会指定指标名称，但不会指定其类型或事件键。设计前应收集这些信息。在用户说明类型，以及在自定义事件的情况下说明事件键之前：
   • 不要调用 list-metric-events。
   • 不要将指标名称或用户未提供的其他键作为事件键进行检查。
   • 不要将指标视为 pageview 或 click 来跳过流程检查。
   • 不要因尚未确定的事件而阻止创建。
4. 关于新指标的类型、依据和衡量方式，请参阅信息收集规则。
5. 用户说明新指标为 custom 并指定其事件键后，针对该事件键调用 list-metric-events。无论哪种情况，只要没有其他待补充项，就将该指标纳入设计。如果事件尚未传达到 LaunchDarkly，请在设计中警告：该环境尚未收到此事件。针对该环境，最多列出 list-metric-events 返回的 10 个自定义事件键，并优先列出与用户提供的键相似的键，以便于发现拼写错误。告知用户可以更正事件键；如果尚未部署跟踪，也可以按当前设置批准。如果用户更正了事件键，这属于变更：针对新键再次调用 list-metric-events，并根据审批规则展示更新后的设计。获得批准后，照常创建指标和实验，即使事件尚未到达也一样。
6. Pageview 和 click 指标没有自定义事件键。只有在用户说明类型为 pageview 或 click 后，才跳过 list-metric-events。
7. 将用户指定的主要指标作为 primarySingleMetricKey 或 primaryFunnelKey 传入。

目标	指标类型	示例键
转化	自定义转化	checkout-completed
性能	自定义数值	page-load-time-ms
互动	自定义转化	feature-clicked
收入	自定义数值	order-value

步骤 2：确定定向规则

你需要获取将用于驱动实验的标志规则的 ruleId 和当前 flagConfigVersion。对标志（或其特定环境的状态）使用 get-flag 查找这些值。Fallthrough 规则的 ID 是字符串 "fallthrough"。

步骤 3：创建实验

请参阅上述信息收集和审批规则，然后对新指标调用 create-metric，并调用 create-experiment。事件检查请参阅步骤 1。

调用 create-experiment。顶层字段描述实验；嵌套的 iteration 对象描述首个数据收集时间段。以下示例展示的是调用的结构，而不是可直接照搬的值。随机化单位请参阅创建前须知。

{
  "projectKey": "my-project",
  "environmentKey": "production",
  "key": "checkout-flow-v2-experiment",
  "name": "Checkout Flow v2 Experiment",
  "description": "Compare the redesigned checkout against the current flow.",
  "tags": ["growth", "checkout"],
  "iteration": {
    "hypothesis": "The redesigned checkout will lift completion rate by 3%.",
    "primarySingleMetricKey": "checkout-completed",
    "metrics": [
      { "key": "checkout-completed" },
      { "key": "checkout-time-seconds" }
    ],
    "treatments": [
      {
        "name": "Control",
        "baseline": true,
        "allocationPercent": 50,
        "parameters": [
          { "flagKey": "checkout-flow-v2", "variationId": "variation-a-id" }
        ]
      },
      {
        "name": "New Checkout",
        "baseline": false,
        "allocationPercent": 50,
        "parameters": [
          { "flagKey": "checkout-flow-v2", "variationId": "variation-b-id" }
        ]
      }
    ],
    "flags": {
      "checkout-flow-v2": {
        "ruleId": "fallthrough",
        "flagConfigVersion": 7
      }
    },
    "randomizationUnit": "user"
  }
}

除非用户选择了 methodology，否则不要提供该字段。用户选择后，将其设为对应的值（"bayesian"、"frequentist" 或 "export_only"）。

有用的可选顶层字段：

• holdoutId — 关联现有的留出组。
• dataSource — "launchdarkly"（默认值）、"snowflake" 或 "databricks"。
• methodology — 仅在用户选择时提供："bayesian"、"frequentist" 或 "export_only"。否则省略。LaunchDarkly 默认使用带序贯检验的频率学派方法。
• analysisConfig — 仅设置用户指定的字段。留空可保持启用序贯检验。

有用的可选迭代字段：

• attributes — 用于细分结果的上下文属性键数组（例如 ["country", "device"]）。
• covariateId — 用于分层抽样的协变量 CSV ID。
• canReshuffleTraffic — 默认为 true；设为 false 可在流量分配发生变化时，将用户锁定在其初始变体。

第 4 步：开始数据收集

创建实验后，迭代会处于 not_started 状态。只有在用户明确表示要开始后，才调用 start-experiment-iteration。对于任何其他会启动迭代的调用，也同样需要等待用户明确表示。

{
  "projectKey": "my-project",
  "environmentKey": "production",
  "experimentKey": "checkout-flow-v2-experiment"
}

开始前，API 要求：

• 已开启该标志，
• 迭代具有 randomizationUnit，并且
• 至少有一个 treatment 的 allocationPercent 非零。

如果主要指标是自定义事件，请在开始前立即再次调用 list-metric-events。如果事件已开始上报，在标志开启后即可正常开始。如果事件仍未上报，实验可以开始，但在事件上报前结果将保持为空，因此请询问用户是否仍要开始。

如果用户表示要开始时，该环境中的标志处于关闭状态，不要更改标志。告知用户必须在该环境中开启标志，并说明开启后会向该环境中的用户提供其各个变体。询问用户是想自行开启，还是让你代为开启；在用户明确回答前，等待，不要调用任何会更改标志的工具。标志开启后，再次调用 get-flag 以获取当前的 flagConfigVersion，更新草稿以使用该版本，并告知用户你已完成更新，然后再开始。

如果标志处于关闭状态且自定义事件仍未上报，请在同一条消息中一并提出标志相关问题和是否仍要开始的问题，并等待用户一次性回答。不要分开询问。

如果要在先前的迭代停止后重新开始，请传入 changeJustification。

第 5 步：验证

1. 用户要求你开始后，调用 get-experiment 并确认 currentIteration.status === "running"。
2. 检查 treatment 是否存在且分配比例符合预期。
3. 检查指标列表和主要指标。

第 6 步：在实验期间调整设计（如有需要）

迭代处于 running 状态时，大多数结构性字段（treatments、metrics、methodology、hypothesis……）都会锁定。可以通过以下两种方式进行更改：

• 运行期间进行轻量编辑 — update-experiment 会允许修改 running 状态下 mutableFieldsByStatus 许可的字段（通常仅为 name、description、maintainerId、tags 等元数据，以及追加 metrics/attributes）。被拒绝的字段会列在 skipped 下，并附有原因。
• 实质性设计更改 — 调用 save-and-start-experiment-iteration。此调用会停止当前迭代，创建一个应用了所提供字段更新的新草稿，并启动该草稿。输入与 update-experiment 相同，另加 changeJustification。由于更新会应用到新草稿，因此可变性会按照 not_started 状态进行检查。

save-and-start-experiment-iteration 会启动新迭代。展示更改内容，然后等待用户明确表示要开始后再调用。

示例：在一次调用中调换 treatment 的分配比例并添加一项指标。

{
  "projectKey": "my-project",
  "environmentKey": "production",
  "experimentKey": "checkout-flow-v2-experiment",
  "changeJustification": "Lowering control allocation now that variant looks safe.",
  "treatments": [
    {
      "name": "Control",
      "baseline": true,
      "allocationPercent": 30,
      "parameters": [{ "flagKey": "checkout-flow-v2", "variationId": "variation-a-id" }]
    },
    {
      "name": "New Checkout",
      "baseline": false,
      "allocationPercent": 70,
      "parameters": [{ "flagKey": "checkout-flow-v2", "variationId": "variation-b-id" }]
    }
  ],
  "metrics": [
    { "key": "checkout-completed" },
    { "key": "checkout-time-seconds" },
    { "key": "checkout-error-rate" }
  ]
}

步骤 7：停止迭代

当结果足以支持决策，或用户已做出决定时，停止迭代。对于频率学派实验，该决策依据是统计显著性。对于贝叶斯实验，依据是优于基线的概率或成为最佳方案的概率。只引用当前所用方法对应的统计量。必须有一个获胜处理组才能停止——LaunchDarkly 不允许在未宣布获胜者的情况下结束迭代。传入获胜处理组的 id（get-experiment 返回的每个处理组中的 _id）以及 winningReason。

如果实验结果不明确，或没有任何变体优于对照组，请宣布基线／对照处理组为获胜者，并在 winningReason 中说明原因（例如，“结果不明确——保留对照组”）。没有“停止但不指定获胜者”的选项。

{
  "projectKey": "my-project",
  "environmentKey": "production",
  "experimentKey": "checkout-flow-v2-experiment",
  "winningTreatmentId": "treat-002",
  "winningReason": "Two weeks of data, +4.1% lift on the primary metric."
}

在 winningReason 中注明决策统计量。频率学派：显著性，或说明结果不显著。贝叶斯：优于基线的概率或成为最佳方案的概率。频率学派实验中，不要引用贝叶斯概率或先验。

报告结果：

• 迭代已停止，并指定了 winningTreatmentId（若结果不明确，则指定对照组／基线）。
• 主要指标的提升幅度，以及当前所用方法对应的决策统计量。
• 后续步骤（发布获胜方案、回滚或开始后续迭代）。

边缘情况

情况	操作
新主要指标的类型或事件键未知	在检查事件前收集这些信息。参见步骤 1。
新指标是自定义事件，且用户指定了其事件键	如果该事件尚未到达，请在设计中警告；获得批准后仍创建指标。参见步骤 1。
缺少标志、变体、假设或主要指标	询问用户，并将其留空。参见创建前须知。
项目中不存在指定的标志	提议更正键值、让用户创建标志，或在用户批准详情后创建。否则绝不创建标志。参见收集规则。
用户未指定对照组，且规则要求询问	询问用户要使用哪个对照组；不要提出建议。参见创建前须知。
用户未指定对照组，且规则要求提出建议	提出对照组建议并标明。参见创建前须知。
用户未指定随机化单位	提议或询问随机化单位。参见创建前须知。
设计尚未获批	不要调用 create-metric 和 create-experiment。参见上文的收集与批准规则。
用户尚未表示要开始	将迭代保留在 not_started 状态。不要调用 start-experiment-iteration 和 save-and-start-experiment-iteration。
用户表示开始时标志处于关闭状态	不要更改标志；先询问用户。参见步骤 4。
标志没有可供比较的变体	仅在用户明确要求时添加变体。否则说明现有哪些变体并询问用户。
不知道标志的 ruleId／flagConfigVersion	使用 get-flag 或 get-flag-status-across-envs。兜底规则的 id 是字符串 "fallthrough"。
实验已存在	使用 list-experiments 查找；使用 get-experiment 查看详情。
实验进行期间需要更改已锁定的字段	使用 save-and-start-experiment-iteration（单次调用），而不是先停止再手动重新创建。
update-experiment 对某个字段返回 skipped	检查响应中的 currentStatus 和 allowedFields——该字段在当前迭代状态下不可修改。应先停止迭代，或使用 save-and-start-experiment-iteration。

不要做什么

• 不要自行填写必填项，也不要提供未标注为建议的建议。请参阅“开始创建前”。
• 不要在第 1 步要求之前调用 list-metric-events，也不要因为尚未收到事件而阻止创建。请参阅第 1 步。
• 在满足上述审批规则之前，不要调用 create-metric 或 create-experiment。
• 除非用户明确要求开始，否则不要调用 start-experiment-iteration 或 save-and-start-experiment-iteration。
• 除非用户明确要求，否则不要开启或关闭标志，也不要更改其定向设置。
• 除非用户提出要求并批准拟议的键、名称、类型和变体，否则不要创建标志。请参阅收集规则。
• 调用 create-experiment 时不要省略 iteration——它是必填项。
• 不要在多个 treatment 上设置 baseline: true。
• 所有 treatment 的 allocationPercent 值之和必须为 100。
• 当迭代处于 running 状态时，不要尝试通过 update-experiment 更改锁定的迭代字段——应改用 save-and-start-experiment-iteration。
• 不要提前停止迭代——请等待方法论支持的决策。请参阅第 7 步。
• 不要在没有谨慎设计对照组的情况下，同时对同一个标志运行多个实验。