creating-experiments

创建实验

本技能将带你完成创建新 A/B 测试实验的流程：先了解项目，再按 3 步流程操作，最后报告草稿。

核心原则：先创建草稿，再迭代细节

快速将实验创建为草稿，然后再迭代指标和配置。 用户可以立即看到具体的草稿并进行完善。 根据项目事实选择设置，而不是向用户提问，并说明哪些选择是推测。 分桶方式是个例外：无法根据事实决定，因此请在创建实验前询问。

步骤 0：了解项目

正确的分桶方式、指标和运行时间取决于项目：谁会看到页面、哪些 SDK 会评估标志，以及指标事件发生的频率。 在配置任何内容之前，先阅读这些信息。

1. 根据请求，推断目标（表示某人触达变更的事件，页面通常为 $pageview）和一个候选指标事件。 使用 read-data-schema 确认二者都存在。不要向用户询问你可以查到的事件名称。 对于页面，也要读取目标事件中 $host 和 $pathname 的 event_property_values。 响应会对值进行采样，而不是列出全部值，因此要据此了解项目记录值的格式（是否带尾部斜杠、是否带 www. 前缀、大小写形式），而不是将其视为某个值不存在的证据。 精确筛选条件必须符合该格式：如果每个页面浏览事件的路径都是 /pricing/，那么 /pricing 将无法匹配任何内容；如果主机名是 www.example.com，那么 example.com 将无法匹配任何内容。

2. 如果 experiment-setup-context 工具可用，请调用一次，并传入 target_event 和 metric_event。 对于 Web 界面，请添加包含精确 $host 的 target_properties。 如果界面只有一个页面，也请添加精确的 $pathname。 target_url_contains 会对 $current_url 进行子字符串匹配。 裸域名会匹配任何包含该域名的主机，包括 notexample.com；而首页路径会匹配其下的每个页面。 这两种情况都会高估流量和曝光率。 对于跨多个页面的界面，请保留精确的 $host，并在 target_url_contains 中仅填写路径片段。 如果候选指标只统计该事件的部分发生次数，请在同一次调用中添加 metric_properties。 传入 previous_experiments_limit: 5。查看先例时，5 个实验已足够；默认值 10 会让响应量大约翻倍，却不会带来更多有用信息。 如果该工具不可用，请跳过并将以下所有选择都视为最佳推测。切勿调用你看不到的工具。

   每个筛选条件都需要包含 type（event 或 person）、key、operator 和 value。 调用时若使用 flag_evaluates_to 运算符，将会收到一个指出该运算符的 400 错误。 对于单个域名的首页：

   {
     "target_event": "$pageview",
     "target_properties": [
       { "key": "$host", "type": "event", "operator": "exact", "value": ["www.example.com"] },
       { "key": "$pathname", "type": "event", "operator": "exact", "value": ["/"] }
     ],
     "metric_event": "your_conversion_event",
     "previous_experiments_limit": 5
   }
   

3. 根据结果应用 references/setup-decisions.md。该文件会将每项事实对应到一个选择（分桶方式、标志评估位置、曝光、主要指标、运行时间、先例），并对应到摘要中的一个等级。

4. 将这些选择带入步骤 1 到 3。

只有在某项选择“尚未决定”且用户仍在对话中时，才询问用户。 如果用户表示暂时离开，或要求不提问直接提供草稿，请使用默认值做出决定，并在报告中列出未决事项。

3 步创建流程

步骤 1：我们要测试什么？

调用 experiment-create 前，先收集以下信息：

• 实验名称——描述性名称；尽可能根据上下文推断
• 假设——你预期会发生什么（填入 description）
• 功能标志键——使用 kebab-case。除非用户指定现有标志，否则推断一个新键。 功能标志会自动创建——不要单独创建。唯一的例外是按设备 ID 分桶，这是 experiment-create 无法设置的（参见 configuring-experiment-rollout 中的方案）。
• 类型——留空（内部默认值为 "product"）。"web" 值专用于通过浏览器中的 PostHog 工具栏以可视化方式配置的无代码实验；无法通过 MCP 进行有效控制。如果用户要求创建 无代码/工具栏实验，请引导他们使用 PostHog UI，而不是在此处创建。

如果用户提供的信息足以推断这些内容，就不要追问，直接继续。

步骤 2：谁会看到哪个变体？

这涉及发布配置。

询问任何发布相关问题前，请先加载 configuring-experiment-rollout。 歧义消除措辞、建议和回答后的分支都在其中——不要自行拟定发布问题，也不要假定你记得的某个示例适用于用户当前的情况。

关键决策点（configuring-experiment-rollout 中有详细说明）：

• 变体分配（变体数量及各自的百分比）
• 整体发布百分比（所有用户中有多少比例会进入实验）
• 分桶方式，以及是否跨身份验证步骤保留功能标志——由用户选择，因为项目事实无法决定

如果用户没有提及发布细节，则使用默认值：对照组/测试组各占 50%，发布比例为 100%。

步骤 3：如何衡量影响？

这涉及分析和指标。请加载 configuring-experiment-analytics 技能获取指导。 该技能的第一步会检查是否有现成的共享指标可供复用，然后才会新建指标—— 不要重复创建项目中已经配置好的指标。

创建时不要配置指标。 指标不会传入 experiment-create，而是在之后通过 experiment-update 添加。这样创建调用会更轻量。

用户预先指定指标时，先确认收到，并在创建后立即添加。如果用户没有指定，则根据假设（步骤 0）推断主要指标，并在创建后添加；同时说明该指标是推断得出的。

如果步骤 0 得出了运行时间估算值，请将其作为 running_time_calculation 传给 experiment-create，以便将计划存储在实验中。

如何创建

使用以下参数调用 experiment-create：

{
  "name": "Descriptive experiment name",
  "feature_flag_key": "kebab-case-key",
  "description": "Hypothesis: [what you expect to happen]",
  "feature_flag": {
    "filters": {
      "multivariate": {
        "variants": [
          { "key": "control", "name": "Control", "rollout_percentage": 50 },
          { "key": "test", "name": "Test", "rollout_percentage": 50 }
        ]
      },
      "groups": [{ "properties": [], "rollout_percentage": 100 }]
    }
  }
}

标志配置应放在 feature_flag 对象中，使用标志自身的筛选器结构（而非已弃用的 parameters 键）。 其中有两个不同的百分比，请勿混淆：

• filters.multivariate.variants[].rollout_percentage 表示进入实验的用户如何分配到各个变体中（总和必须为 100，建议平均分配）。
• filters.groups[0].rollout_percentage 是总体门槛：所有用户中有多少比例会进入实验（0-100，默认为 100）。

关键细节：

• 变体至少 2 个，最多 20 个。不要求使用特定的变体键 — 分析基线默认使用键为 "control" 的变体（如果存在），否则使用第一个变体（可通过 stats_config.baseline_variant_key 覆盖）。通常将基线的键设为 "control"，除非用户要求使用特定键。
• 如果省略 filters.groups[0].rollout_percentage，默认值为 100。
• 分桶和 ensure_experience_continuity：默认按用户 ID 分桶，并省略 ensure_experience_continuity，以采用团队的持久性默认设置。报告步骤 0 中该场景的身份构成，以及按设备 ID 分桶或设置持久性各自需要什么，然后在调用前让用户选择。按设备 ID 分桶需要先创建标志，因此不能等草稿创建后再选择。身份构成并不能决定该选项：请参阅 configuring-experiment-rollout 中的“登录时的分桶与持久性”。
• 统计设置遵循团队默认值（方法、置信水平）。仅在用户要求使用其他方法时设置 stats_config。

创建后

1. 将草稿分成三组报告，方便用户快速查看：

   • 已确认：选择及其依据（“已关联共享指标‘注册’，它会按人员统计注册事件，符合你的要求”）。
   • 建议选择，请核对：选择、依据，以及哪些情况会改变该选择（“选择漏斗指标，因为你最近的四个实验都以这种方式衡量转化；如果你想改为按用户计数，请告诉我”）。
   • 尚未决定：缺少的信息以及如何确定（“该标志也会在你的服务器上进行本地评估；请确认服务器和浏览器使用相同的 distinct ID”）。

   还要说明哪些内容无法读取：缺少工具，或某个部分的状态不是 ok。

2. 始终显示实验 URL。 experiment-create 响应包含 _posthogUrl — 始终显示此链接，方便用户在 UI 中查看和配置实验。

3. 提醒用户在代码中实现功能标志。 链接到实验页面，并说“按此处所示实现标志” — 实验详情页会显示适用于用户 SDK 的实现代码片段。

4. 如果尚未配置指标，则引导用户完成配置 — 加载 configuring-experiment-analytics 技能。

5. 只有用户提出要求时才启动 — 创建操作到草稿为止。启动后，功能标志会对真实用户生效，因此切勿在用户未主动要求时调用 experiment-launch。

相关技能

• configuring-experiment-rollout — 变体分配、发布百分比以及哪些用户会看到测试
• configuring-experiment-analytics — 曝光条件及主要/次要指标
• managing-experiment-lifecycle — 实验创建后的启动、暂停、发布和结束