ae-experiment

ae-experiment

AE CLI（ae-cli）通过 experiment 域提供 Atlas AB Experiment 功能。

全局规则

• 进行 Atlas AB Experiment 相关操作时，优先使用 ae-cli experiment <command>。
• 项目范围的命令使用 --project-id / -p。
• 复杂的保存、状态和删除 DTO 使用 --req JSON。
• 不要臆造实验 ID、流量层 ID、分桶 ID、Feature 键、指标 ID 或负载字段名。
• 仅绑定 experiment metric list 返回的指标 ID；保存实验前，先创建并验证缺失的指标。
• 验证 ID 后即可直接运行读取命令。
• 写入命令需要用户明确授权，通常应保留确认提示。构造 JSON 时，先在写入调用前使用 --dry-run。

命名和响应边界：

• CLI 命令段和标志使用 kebab-case。
• 外层 Capability 输入和所有响应键使用 snake_case。
• 通过 --req 传递的嵌套业务 DTO 保留其原生 camelCase 字段。
• 关键： save build-guide / save validate 响应会递归地将 example_args.req 转换为 snake_case。切勿将这些键复制到 --req 中。应使用 camelCase（expName、metricId 等）。权威字段名请参阅：ae-cli capability inspect experiment.experiment.save（或相应的最终保存 ID）→ input_schema.properties.req。save validate 中 valid: true 并不表示最终保存的 Schema 校验通过——snake_case 的 req 仍可能导致 experiment … save 失败。
• 受众 QP 在 CLI 边界处采用语义化格式：写入时使用 targeting.definitionRequest；读取时使用 targeting.definition_request。切勿生成或提交 targetConfig。
• 指标 QP 在 CLI 边界处采用语义化格式：写入时使用 metricDefinition；读取时使用 metric_definition。切勿生成或提交 metricConfig、calcType 或 Axxx 代码。
• 事件属性比较应放在 metricDefinition.filters 中，格式为 {relation,items:[{field,operator,values}]}。切勿将比较字段直接放在 metricDefinition 上，也不要提交原始的 filts、calcuSymbol 或 ftv 字段。
• 对于 sum / avg / max / distinct_count 指标聚合，metricDefinition.property 为必填项，且必须是 Analysis 元数据中实际可用的事件属性。切勿创建缺少 property 的属性聚合（例如 metric_avg_no_property_*）。
• 预设事件聚合 total_count / user_count / active_days 不应包含 property。
• 实验指标创建不支持 avg_per_user / A105。
• 保存语义化定义前，使用 Analysis 元数据解析事件和属性名称。
• 列表返回 data.items 和 data.total；详情命令返回 data.item。
• 就绪状态返回 data.readiness；报告返回 data.report；保存指南返回 data.guide；保存试运行校验返回 data.validation；写入返回 data.result。
• 查询取消操作返回 data.success。

典型工作流

1. 查找可复用资产：
   • experiment bucket list
   • experiment traffic-layer list
   • experiment feature list
   • experiment metric list
2. 按需创建缺失的资产：
   • 当保存验证失败或请求结构不明确时，运行 experiment save build-guide --operation-mode save_metric
   • 重试失败的保存操作前，运行 experiment save validate --operation-mode save_metric --req '{...}'
   • experiment traffic-layer save
   • experiment feature save
   • experiment metric save
3. 使用 experiment experiment save 创建或修改实验草稿。 替换指标绑定或分配护栏角色时，使用 experiment experiment update-metrics。
4. 对于外部实验，改用 experiment external-experiment save-submit。此操作会直接提交，不使用 Features、流量层、流量分配、定向或实验周期。
5. 使用 experiment experiment ready-check 检查就绪状态。
6. 对于非互斥流量层，在提交前运行 experiment experiment conflict-check（需要从上下文或 experiment get 中获取 feature_key_list）。
7. 使用 experiment experiment manage 更改状态。
8. 使用 experiment report summary、experiment report sample-size 和 experiment report metric-trend 查询报告。

如果实验保存返回 error_code: METRIC_NOT_FOUND，请列出同一项目的指标。创建并验证该指标后再重试；切勿使用另一个虚构 ID 重试。存在有效的实验绑定时，删除指标会返回 error_code: METRIC_IN_USE。

参数约定

• 实验保存载荷区分两个流量分配字段：实验级别的 req.allocation（仅限整数；不能有小数）和组级别的 req.groups[].allocation（仅限整数；总和必须恰好等于 100）。
• 公开的实验指标角色为 primary、secondary 和 guardrail。内部的 observation 角色目前不可用于保存。Guardrail 是一种绑定角色；更新指标会替换完整的绑定列表。

ae-cli experiment experiment get --project-id 1 --exp-id exp_123
ae-cli experiment experiment save --project-id 1 --req '{"expName":"Demo"}' --dry-run
ae-cli experiment metric save --project-id 1 --req '{"metricId":"payment_gold_sum","metricName":"Payment gold sum","createType":"event","goalDirection":"up","metricDesc":"Gold sum for payments above 10","metricDefinition":{"type":"event","event":"payment","aggregation":"sum","property":"gold","filters":{"relation":"and","items":[{"field":"gold","operator":"gt","values":[10]}]}}}' --dry-run
ae-cli experiment report metric-trend --project-id 1 --exp-id exp_123 --metric-id metric_1 --start-time 2026-07-01 --end-time 2026-07-07

可选的全局参数与其他领域中的用法相同：--host、--mcp-url、--format、--jq、--dry-run 和 --yes。

参考资料

使用命令前，请先打开 references/ 中对应的文件，尤其是在执行写操作和处理 JSON 载荷时。

保存辅助工具

experiment save build-guide、experiment save validate

当保存命令返回 next_tool: experiment.save.build-guide 时，先调用指南，然后运行 experiment save validate，最后重试最终的保存功能。

使用这些辅助工具前，请先阅读 save_build_guide.md 和 save_validate.md。请根据 inspect / 技能参考资料，使用 camelCase 重新构建 --req；不要粘贴 example_args.req。

实验

experiment experiment save、experiment experiment update-metrics、experiment external-experiment save-submit、capability run experiment.experiment.save-submit、experiment experiment list、experiment experiment list-archived、experiment experiment get、experiment experiment ready-check、experiment experiment conflict-check、experiment experiment manage、experiment experiment update-group、experiment experiment batch-delete、experiment operation-log query

分配或替换指标角色前，请先阅读 manage_guardrail_metrics.md。

外部实验

experiment external-experiment save-submit

创建或更新外部实验前，请先阅读 save_submit_external_experiment.md。

流量层和流量桶

experiment traffic-layer save、experiment traffic-layer get、experiment traffic-layer list、experiment traffic-layer batch-delete、experiment bucket list

报告

experiment report summary、experiment report sample-size、experiment report metric-trend、capability run experiment.query.cancel

指标与功能

experiment metric save、experiment metric get、experiment metric list、experiment metric delete、experiment feature save、experiment feature update-status、experiment feature get、experiment feature list、experiment feature version-list、experiment feature operation-log query、experiment feature batch-delete、experiment feature whitelist list、experiment feature whitelist save、experiment feature whitelist update-status、experiment feature whitelist batch-delete

在查询或更改功能白名单规则之前，请先阅读 manage_feature_whitelist.md。