ae-experiment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ae-experiment

AE CLI (

ae-cli

) exposes Atlas AB Experiment capabilities through the

experiment

domain.

AE CLI (

ae-cli

) 通过

experiment

域开放Atlas AB实验的相关能力。

Global Rules

通用规则

Prefer
```
ae-cli experiment <command>
```
for Atlas AB Experiment work.
Use
```
--project-id
```
/
```
-p
```
for project-scoped commands.
Use
```
--req
```
JSON for complex save, status, and delete DTOs.
Do not invent experiment IDs, traffic layer IDs, bucket IDs, Feature keys, metric IDs, or payload field names.
Bind only metric IDs returned by
```
experiment metric list
```
; create and verify a missing metric before saving the experiment.
Read commands can run directly after IDs are verified.
Write commands require explicit user intent and normally keep the confirmation prompt. Use
```
--dry-run
```
before write calls when composing JSON.

Naming and response boundary:

CLI command segments and flags use kebab-case.
Outer Capability input and all response keys use snake_case.
Nested business DTOs passed through
```
--req
```
keep their native camelCase fields.
CRITICAL:
```
save build-guide
```
/
```
save validate
```
responses recursively snake_case
```
example_args.req
```
. Never copy those keys into
```
--req
```
. Use camelCase (
```
expName
```
,
```
metricId
```
, …). Authoritative names:
```
ae-cli capability inspect experiment.experiment.save
```
(or the matching final save id) →
```
input_schema.properties.req
```
.
```
save validate
```
```
valid: true
```
is not a final-save schema pass — snake_case
```
req
```
can still fail on
```
experiment … save
```
.
Audience QP is semantic at the CLI boundary: write
```
targeting.definitionRequest
```
; read
```
targeting.definition_request
```
. Never generate or submit
```
targetConfig
```
.
Metric QP is semantic at the CLI boundary: write
```
metricDefinition
```
; read
```
metric_definition
```
. Never generate or submit
```
metricConfig
```
,
```
calcType
```
, or
```
Axxx
```
codes.
For metric aggregations
```
sum
```
/
```
avg
```
/
```
max
```
/
```
distinct_count
```
,
```
metricDefinition.property
```
is required and must be a concrete available event property from Analysis metadata. Never create property aggregations without
```
property
```
(for example
```
metric_avg_no_property_*
```
).

Event-count aggregations

total_count

user_count

active_days

omit

property

Resolve event and property names with Analysis metadata before saving semantic definitions.
Lists return
```
data.items
```
and
```
data.total
```
; detail commands return
```
data.item
```
.
Readiness returns
```
data.readiness
```
; reports return
```
data.report
```
; save guides return
```
data.guide
```
; save dry-run validation returns
```
data.validation
```
; writes return
```
data.result
```
.
Query cancellation returns
```
data.success
```
.

处理Atlas AB实验相关工作时，优先使用
```
ae-cli experiment <command>
```
命令。
针对项目级命令，使用
```
--project-id
```
/
```
-p
```
参数。
复杂的保存、状态更新和删除操作，使用
```
--req
```
传入JSON格式的DTO。
不得自行编造实验ID、流量层ID、流量桶ID、Feature键、指标ID或负载字段名称。
仅绑定
```
experiment metric list
```
返回的指标ID；保存实验前，需先创建并验证缺失的指标。
确认ID无误后，可直接执行查询类命令。
写入类命令需要明确的用户意图，默认会显示确认提示。编写JSON参数时，执行写入操作前请先使用
```
--dry-run
```
进行预演。

命名与响应边界：

CLI命令段和参数采用kebab-case命名格式。
外部能力输入及所有响应键采用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
```
并不代表通过了最终保存的校验——snake_case格式的
```
req
```
仍可能在执行
```
experiment … save
```
时失败。
在CLI边界处，受众查询参数（QP）是语义化的：写入时使用
```
targeting.definitionRequest
```
；读取时使用
```
targeting.definition_request
```
。切勿生成或提交
```
targetConfig
```
。
在CLI边界处，指标查询参数（QP）是语义化的：写入时使用
```
metricDefinition
```
；读取时使用
```
metric_definition
```
。切勿生成或提交
```
metricConfig
```
、
```
calcType
```
或
```
Axxx
```
编码。
对于
```
sum
```
/
```
avg
```
/
```
max
```
/
```
distinct_count
```
这类指标聚合方式，
```
metricDefinition.property
```
是必填项，且必须是Analysis元数据中存在的具体事件属性。切勿在未指定
```
property
```
的情况下创建属性聚合（例如
```
metric_avg_no_property_*
```
）。
```
total_count
```
/
```
user_count
```
/
```
active_days
```
这类事件计数聚合方式无需指定
```
property
```
。
保存语义化定义前，需通过Analysis元数据确认事件和属性名称。
列表类命令返回
```
data.items
```
和
```
data.total
```
；详情类命令返回
```
data.item
```
。
就绪检查返回
```
data.readiness
```
；报告类返回
```
data.report
```
；保存指南返回
```
data.guide
```
；保存预演校验返回
```
data.validation
```
；写入类命令返回
```
data.result
```
。
查询取消操作返回
```
data.success
```
。

Typical Workflow

典型工作流程

Discover reusable assets:

```
experiment bucket list
```
```
experiment traffic-layer list
```
```
experiment feature list
```
```
experiment metric list
```

Create missing assets if needed:

experiment save build-guide --operation-mode save_metric

when save validation fails or req shape is unclear

experiment save validate --operation-mode save_metric --req '{...}'

before retrying a failed save

```
experiment traffic-layer save
```
```
experiment feature save
```
```
experiment metric save
```

Create or patch the experiment draft with
```
experiment experiment save
```
.
Check readiness with
```
experiment experiment ready-check
```
.
For a non-mutex traffic layer, run
```
experiment experiment conflict-check
```
before submit (needs
```
feature_key_list
```
from context or
```
experiment get
```
).
Move status with
```
experiment experiment manage
```
.

Query reports with

experiment report summary

experiment report sample-size

, and

experiment report metric-trend

If an experiment save returns

error_code: METRIC_NOT_FOUND

, list metrics for the same project. Create and verify the metric before retrying; never retry with another invented ID. Metric deletion returns

error_code: METRIC_IN_USE

while an active experiment binding exists.

发现可复用资源：

```
experiment bucket list
```
```
experiment traffic-layer list
```
```
experiment feature list
```
```
experiment metric list
```

如有需要，创建缺失的资源：

当保存校验失败或请求格式不明确时，执行
```
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
```

使用
```
experiment experiment save
```
创建或更新实验草稿。
通过
```
experiment experiment ready-check
```
检查实验就绪状态。
对于非互斥流量层，提交前需执行
```
experiment experiment conflict-check
```
（需要从上下文或
```
experiment get
```
获取
```
feature_key_list
```
）。
使用
```
experiment experiment manage
```
更新实验状态。

通过

experiment report summary

、

experiment report sample-size

和

experiment report metric-trend

查询实验报告。

如果实验保存操作返回

error_code: METRIC_NOT_FOUND

，请列出同一项目下的指标。创建并验证该指标后再重试；切勿使用自行编造的ID重试。当指标被活跃实验绑定时，删除指标会返回

error_code: METRIC_IN_USE

。

Parameter Conventions

参数约定

Experiment save payloads distinguish two allocation fields: experiment-level
```
req.allocation
```
(integer only; no decimals) and group-level
```
req.groups[].allocation
```
(integer only; sum must equal
100
exactly).

bash

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":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --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

Optional global parameters work as in other domains:

--host

--mcp-url

--format

--jq

--dry-run

, and

--yes

实验保存负载包含两个分配字段：实验级别的
```
req.allocation
```
（仅支持整数；不允许小数）和分组级别的
```
req.groups[].allocation
```
（仅支持整数；总和必须恰好等于100）。

bash

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":"login_users","metricName":"Login users","createType":"event","goalDirection":"up","metricDesc":"Users who logged in","metricDefinition":{"type":"event","event":"login","aggregation":"user_count"}}' --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

参考资料

Open the matching file in

references/

before using a command, especially for write operations and JSON payloads.

使用命令前，请打开

references/

目录下对应的文件，尤其是写入操作和JSON负载相关的命令。

Save Helpers

保存辅助工具

experiment save build-guide

experiment save validate

When a save command returns

next_tool: experiment.save.build-guide

, call the guide first, then

experiment save validate

, then retry the final save capability.

Read

save_build_guide.md

and

save_validate.md

before using these helpers. Rebuild

--req

in camelCase from

inspect

/ skill references; do not paste

example_args.req

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 experiment save

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

experiment experiment save

、

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

Traffic Layer and Buckets

流量层与流量桶相关命令

experiment traffic-layer save

experiment traffic-layer get

experiment traffic-layer list

experiment traffic-layer batch-delete

experiment bucket list

experiment traffic-layer save

、

experiment traffic-layer get

、

experiment traffic-layer list

、

experiment traffic-layer batch-delete

、

experiment bucket list

Reports

报告相关命令

experiment report summary

experiment report sample-size

experiment report metric-trend

capability run experiment.query.cancel

experiment report summary

、

experiment report sample-size

、

experiment report metric-trend

、

capability run experiment.query.cancel

Metric and Feature

指标与Feature相关命令

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 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