@thinkingai/ae-cli 1.0.18 → 1.0.21

package/skills/ae-analysis/references/build_event_analysis_qp.md

@@ -0,0 +1,132 @@
+# analysis +build_event_analysis_qp (build event analysis qp)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated event-analysis QP from structured intent.
+- Use in the mandatory builder flow before `+query_adhoc --model_type event`.
+- This command builds QP only and does not execute the analysis query.
+- This is one of exactly four QP builders: `event`, `retention`, `funnel`, `prop_analysis`.
+- Use this builder for event-analysis ad hoc requests; do not manually build event QP through `+get_analysis_query_schema`.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase DTO names.
+- Correct nested keys: `startTime`, `endTime`, `timeRange`, `timeParticleSize`.
+- Wrong nested keys: `start_date`, `start_time`, `startDate` inside examples copied from other APIs.
+- Wrap JSON in single quotes in shell commands.
+- Do not run syntax examples with placeholder JSON. Fill `time_range` and `metrics` with valid nested fields before calling this command.
+- `--dry-run` still requires the same required flags as a real builder call. Never run this command as dry-run without `--project_id`, `--time_range`, and `--metrics`.
+- Do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, or `get_metric` before this builder for normal ad-hoc analysis. The builder resolves events, properties, and saved metric names internally.
+- Builder commands do not accept `zone_offset`; pass `--zone_offset` to `+query_adhoc` after the builder succeeds.
+- If the request misses `time_range` or `metrics`, stop and ask the user to clarify.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_event_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --metrics '<valid_metrics_json_array>'
+ae-cli analysis +build_event_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --metrics '<valid_metrics_json_array>' --time_particle_size day --groups '<valid_groups_json_array>' --filters '<valid_filters_json_array>' --relation and
+ae-cli analysis +build_event_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --metrics '<valid_metrics_json_array>' --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--time_range` | Yes | Event analysis time range JSON |
+| `--metrics` | Yes | Event metrics JSON array |
+| `--time_particle_size` | No | Time granularity. Default: total |
+| `--groups` | No | Group-by dimensions JSON array |
+| `--filters` | No | Global filters JSON array |
+| `--relation` | No | Filter relation. Supported values: and, or. Default: and |
+
+## JSON Shape
+`--time_range` object:
+```json
+{"mode":"start_to_yesterday","startTime":"2021-05-18"}
+```
+
+Time range fields:
+| Field | Required | Description |
+|---|---|---|
+| `mode` | Yes | `recent`, `previous`, `custom`, `start_to_today`, `start_to_yesterday` |
+| `unit` | For `recent`/`previous` | `day`, `week`, `month`, `quarter`, `year` |
+| `value` | For `recent`/`previous` | Unit count. `{"mode":"previous","unit":"day","value":1}` means yesterday. |
+| `startTime` | For `custom`/`start_to_*` | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+| `endTime` | For `custom` only | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+
+`--metrics` array:
+```json
+[{"event":"special_data","aggregation":"user_count"}]
+```
+
+Metric fields:
+| Field | Required | Description |
+|---|---|---|
+| `event` | Yes for regular metrics | Event display name, technical name, or remark |
+| `aggregation` | Yes for regular metrics | `total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `true_count`, `false_count`, `not_empty_count`, `empty_count`, `median`, `percentile`, `variance`, `stddev` |
+| `property` | Required for property aggregations | Required except for `total_count`, `user_count`, and `per_user_count` |
+| `percentile` | Required for `percentile` | Number such as `90` |
+| `filters` | No | Metric-level `FilterRequest[]` |
+| `relation` | No | Relation between metric filters: `and` or `or` |
+| `formula` | For formula metrics | Formula expression. Omit `aggregation` when using formula. |
+| `dependencies` | For formula metrics | Formula dependency array |
+
+Saved metric reference:
+- Event analysis builder can resolve a saved metric by name/display name/remark through the metric target field.
+- If the user asks to query an existing metric such as "战斗失败率" or gives a metric identifier/name that should be used as a saved metric, pass it as `{"event":"战斗失败率"}` and omit `aggregation`, `property`, `formula`, and `dependencies`.
+- Do not call `list_metrics` or `get_metric` first only to expand that saved metric. If the builder cannot resolve it, it will return `need_clarification` with candidates.
+
+Formula dependency object:
+```json
+{"alias":"starts","event":"battle_start","aggregation":"total_count"}
+```
+
+`--groups` array:
+```json
+[{"field":{"name":"账户ID","type":"event_property"}}]
+```
+
+`--filters` array:
+```json
+[{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"}]
+```
+
+Filter fields:
+| Field | Required | Description |
+|---|---|---|
+| `field.name` | Yes | Field display name, technical name, or remark |
+| `field.type` | Recommended | `event_property`, `user_property`, `cluster`, `tag`; omit only when metadata is unambiguous |
+| `operator` | Yes | `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `exists`, `not_exists`, `between`, `contains`, `not_contains`, `is_true`, `is_false`, `regex`, `not_regex`, `in_cluster`, `not_in_cluster` |
+| `values` | Depends | Omit for `exists`/`not_exists`/`is_true`/`is_false`; exactly two values for `between`; non-empty array for other value operators |
+
+## Examples
+Minimal event user count:
+```bash
+ae-cli analysis +build_event_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":1}' --metrics '[{"event":"special_data","aggregation":"user_count"}]'
+```
+
+Formula metric example:
+```bash
+ae-cli analysis +build_event_analysis_qp --project_id 3137 --time_range '{"mode":"start_to_yesterday","startTime":"2021-05-20"}' --metrics '[{"formula":"battle_lost.A100 / battle_start.A100","dependencies":[{"alias":"battle_lost","event":"battle_lose_rate","aggregation":"total_count"},{"alias":"battle_start","event":"battle_start","aggregation":"total_count"}]}]'
+```
+
+Saved metric by name:
+```bash
+ae-cli analysis +build_event_analysis_qp --project_id 3137 --time_range '{"mode":"custom","startTime":"2021-05-20","endTime":"2026-05-26"}' --metrics '[{"event":"战斗失败率"}]'
+```
+
+Global OR filters and event-property group:
+```bash
+ae-cli analysis +build_event_analysis_qp --project_id 3137 --time_range '{"mode":"start_to_yesterday","startTime":"2021-05-18"}' --metrics '[{"event":"special_data","aggregation":"user_count"}]' --filters '[{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"},{"field":{"name":"城市","type":"event_property"},"operator":"exists"}]' --relation or --groups '[{"field":{"name":"账户ID","type":"event_property"}}]'
+```
+
+## Decision Rules
+- After successful build, call `+query_adhoc --model_type event --qp '<response.qp>'`.
+- If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
+- Wrap JSON parameters in single quotes to avoid shell escaping issues.
+- Do not pre-query metrics or metadata. If the user provides a metric name, event name, property name, or formula, pass that structured intent to the builder and let it resolve.
+- If the user gave a time zone, keep it for `+query_adhoc --zone_offset`; do not put it in the builder JSON.
+
+## Recommended Chaining
+- `+build_event_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type event --qp '<response.qp>'`

package/skills/ae-analysis/references/build_funnel_analysis_qp.md

@@ -0,0 +1,143 @@
+# analysis +build_funnel_analysis_qp (build funnel analysis qp)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated funnel-analysis QP from structured intent.
+- Use in the mandatory builder flow before `+query_adhoc --model_type funnel`.
+- This command builds QP only and does not execute the analysis query.
+- This is one of exactly four QP builders: `event`, `retention`, `funnel`, `prop_analysis`.
+- Use this builder for funnel ad hoc requests; do not manually build funnel QP through `+get_analysis_query_schema`.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase DTO names.
+- Correct nested keys: `startTime`, `endTime`, `relationEventPropertyName`, `eventPropertyName`.
+- Funnel step filters are event-property-only and use `eventPropertyName`; they do not use the generic `field` object.
+- Funnel global filters and groups use the generic `field` object.
+- Do not run syntax examples with placeholder JSON. Fill `time_range` and `funnel` with valid nested fields before calling this command.
+- `--dry-run` still requires the same required flags as a real builder call. Never run this command as dry-run without `--project_id`, `--time_range`, and `--funnel`.
+- Do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, or `get_metric` before this builder for normal ad-hoc analysis. The builder resolves events and properties internally.
+- Builder commands do not accept `zone_offset`; pass `--zone_offset` to `+query_adhoc` after the builder succeeds.
+- If the request misses time range, at least two steps, or conversion window, stop and ask the user to clarify.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_funnel_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --funnel '<valid_funnel_json>'
+ae-cli analysis +build_funnel_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --funnel '<valid_funnel_json>' --relation and --time_particle_size day
+ae-cli analysis +build_funnel_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --funnel '<valid_funnel_json>' --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--time_range` | Yes | Funnel analysis time range JSON |
+| `--funnel` | Yes | Funnel intent JSON |
+| `--relation` | No | Top-level funnel filter relation. Supported values: and, or. Default: and |
+| `--time_particle_size` | No | Time granularity. Supported values: day, week, month |
+
+## JSON Shape
+`--time_range` object:
+```json
+{"mode":"start_to_yesterday","startTime":"2021-05-18"}
+```
+
+Time range fields:
+| Field | Required | Description |
+|---|---|---|
+| `mode` | Yes | `recent`, `previous`, `custom`, `start_to_today`, `start_to_yesterday` |
+| `unit` | For `recent`/`previous` | `day`, `week`, `month`, `quarter`, `year` |
+| `value` | For `recent`/`previous` | Unit count. `{"mode":"previous","unit":"day","value":1}` means yesterday. |
+| `startTime` | For `custom`/`start_to_*` | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+| `endTime` | For `custom` only | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+
+`--funnel` object:
+```json
+{
+  "steps":[
+    {"event":"special_data","filters":[{"eventPropertyName":"账户ID","operator":"exists"}]},
+    {"event":"商品购买","filters":[{"eventPropertyName":"账户ID","operator":"exists"},{"eventPropertyName":"城市","operator":"exists"}],"relation":"or"}
+  ],
+  "window":{"value":180,"unit":"day"},
+  "relationEventPropertyName":"账户ID",
+  "filters":[
+    {"field":{"name":"账户ID","type":"event_property"},"operator":"exists"},
+    {"field":{"name":"城市","type":"event_property"},"operator":"exists"}
+  ],
+  "groups":[{"field":{"name":"账户ID","type":"event_property"}}]
+}
+```
+
+Funnel fields:
+| Field | Required | Description |
+|---|---|---|
+| `steps` | Yes | At least two step objects |
+| `steps[].event` | Yes | Event display name, technical name, or remark |
+| `steps[].filters` | No | Step-level event-property filters. Use `eventPropertyName`, not `field`. |
+| `steps[].relation` | No | Relation between filters in this step: `and` or `or`. Default: `and`. |
+| `window.value` | Yes | Conversion window size. Must be greater than 0. |
+| `window.unit` | No | `second`, `minute`, `hour`, `day`, `week`, `month`. Default: `day`. |
+| `relationEventPropertyName` | No | Event property used as common relation property across all steps. Must resolve compatibly in every step event. |
+| `filters` | No | Global funnel filters using generic `FilterRequest[]` |
+| `groups` | No | Global group-by dimensions using generic `DimensionRequest[]` |
+
+Generic filter object for `funnel.filters`:
+```json
+{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"}
+```
+
+Step filter object for `steps[].filters`:
+```json
+{"eventPropertyName":"账户ID","operator":"exists"}
+```
+
+Group object:
+```json
+{"field":{"name":"账户ID","type":"event_property"}}
+```
+
+Field types for `funnel.filters` and `funnel.groups`:
+| Type | Meaning |
+|---|---|
+| `event_property` | Event property |
+| `user_property` | User property |
+| `cluster` | User cluster |
+| `tag` | User tag |
+
+Filter operator rules:
+| Operator | Values |
+|---|---|
+| `exists`, `not_exists`, `is_true`, `is_false` | Omit `values` |
+| `between` | Exactly two values |
+| `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `regex`, `not_regex` | Non-empty `values` array |
+| `in_cluster`, `not_in_cluster` | Cluster operator; values are not required by builder validation |
+
+## Examples
+Minimal two-step funnel:
+```bash
+ae-cli analysis +build_funnel_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":1}' --funnel '{"steps":[{"event":"special_data"},{"event":"商品购买"}],"window":{"value":180,"unit":"day"}}'
+```
+
+Complex funnel with relation property, step filters, global OR filters, and group:
+```bash
+ae-cli analysis +build_funnel_analysis_qp --project_id 3137 --time_range '{"mode":"start_to_yesterday","startTime":"2021-05-18"}' --funnel '{"steps":[{"event":"special_data","filters":[{"eventPropertyName":"账户ID","operator":"exists"}]},{"event":"商品购买","filters":[{"eventPropertyName":"账户ID","operator":"exists"},{"eventPropertyName":"城市","operator":"exists"}],"relation":"or"}],"window":{"value":180,"unit":"day"},"relationEventPropertyName":"账户ID","filters":[{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"},{"field":{"name":"城市","type":"event_property"},"operator":"exists"}],"groups":[{"field":{"name":"账户ID","type":"event_property"}}]}' --relation or
+```
+
+Then execute with UTC-11 after builder returns `status=generated`:
+```bash
+ae-cli analysis +query_adhoc --project_id 3137 --model_type funnel --qp '<response.qp>' --zone_offset -11
+```
+
+## Decision Rules
+- After successful build, call `+query_adhoc --model_type funnel --qp '<response.qp>'`.
+- If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
+- Wrap JSON parameters in single quotes to avoid shell escaping issues.
+- Do not pre-query metrics or metadata. Pass user-provided event/property names to the builder and let it resolve them.
+- Do not put global filter relation inside `funnel`; pass it as top-level CLI flag `--relation`.
+- If the user says "step 1 account ID group", builder cannot take a step index for groups; express it as `groups:[{"field":{"name":"账户ID","type":"event_property"}}]` and ask for clarification if that is ambiguous.
+- If the user gave a time zone, keep it for `+query_adhoc --zone_offset`; do not put it in the builder JSON.
+
+## Recommended Chaining
+- `+build_funnel_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type funnel --qp '<response.qp>'`

package/skills/ae-analysis/references/build_prop_analysis_qp.md

@@ -0,0 +1,122 @@
+# analysis +build_prop_analysis_qp (build property analysis qp)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated `prop_analysis` QP from structured intent.
+- Use in the mandatory builder flow before `+query_adhoc --model_type prop_analysis`.
+- This command builds QP only and does not execute the analysis query.
+- This is one of exactly four QP builders: `event`, `retention`, `funnel`, `prop_analysis`.
+- Use this builder for property-analysis ad hoc requests; do not manually build prop_analysis QP through `+get_analysis_query_schema`.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase DTO names.
+- `prop_analysis` does not use `time_range`; do not pass time range to this command.
+- `event_property` is not supported anywhere in `prop_analysis` fields.
+- Field types for `groups`, `filters`, and `userCrowds[].filters` are limited to `user_property`, `cluster`, and `tag`.
+- Do not run syntax examples with placeholder JSON. Fill `prop_analysis` with a valid metric and optional filters/groups before calling this command.
+- `--dry-run` still requires the same required flags as a real builder call. Never run this command as dry-run without `--project_id` and `--prop_analysis`.
+- Do not call `get_analysis_query_schema`, `list_properties`, `list_metrics`, or `get_metric` before this builder for normal ad-hoc analysis. The builder resolves user properties internally.
+- Builder commands do not accept `zone_offset`; pass `--zone_offset` to `+query_adhoc` after the builder succeeds if needed.
+- If the request misses the metric or asks for event properties, stop and ask the user to clarify.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_prop_analysis_qp --project_id <project_id> --prop_analysis '<valid_prop_analysis_json>'
+ae-cli analysis +build_prop_analysis_qp --project_id <project_id> --prop_analysis '<valid_prop_analysis_json>' --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--prop_analysis` | Yes | User property analysis intent JSON |
+
+## JSON Shape
+`--prop_analysis` object:
+```json
+{
+  "metric":{"aggregation":"user_count"},
+  "groups":[{"field":{"name":"城市","type":"user_property"}}],
+  "filters":[{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"}],
+  "relation":"and",
+  "userCrowds":[
+    {"name":"账户ID有值用户","filters":[{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"}]}
+  ]
+}
+```
+
+Prop analysis fields:
+| Field | Required | Description |
+|---|---|---|
+| `metric` | Yes | Single metric object |
+| `groups` | No | User property / cluster / tag group-by fields |
+| `filters` | No | User property / cluster / tag filters |
+| `relation` | No | Relation between top-level filters: `and` or `or`. Default: `and`. |
+| `userCrowds` | No | Optional user crowd comparisons |
+
+Metric fields:
+| Field | Required | Description |
+|---|---|---|
+| `aggregation` | Yes | `user_count`, `sum`, `avg`, `max`, `min`, `distinct_count`, `true_count`, `false_count`, `not_empty_count`, `empty_count`, `median`, `percentile`, `variance`, `stddev` |
+| `property` | Required except `user_count` | User property display name, technical name, or remark |
+
+Field object:
+```json
+{"name":"城市","type":"user_property"}
+```
+
+Allowed field types:
+| Type | Meaning |
+|---|---|
+| `user_property` | User property |
+| `cluster` | User cluster |
+| `tag` | User tag |
+
+Filter object:
+```json
+{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"}
+```
+
+User crowd object:
+```json
+{"name":"付费用户","filters":[{"field":{"name":"是否付费","type":"user_property"},"operator":"is_true"}],"relation":"and"}
+```
+
+Filter operator rules:
+| Operator | Values |
+|---|---|
+| `exists`, `not_exists`, `is_true`, `is_false` | Omit `values` |
+| `between` | Exactly two values |
+| `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `regex`, `not_regex` | Non-empty `values` array |
+| `in_cluster`, `not_in_cluster` | Cluster operator; values are not required by builder validation |
+
+## Examples
+Minimal user count:
+```bash
+ae-cli analysis +build_prop_analysis_qp --project_id 3137 --prop_analysis '{"metric":{"aggregation":"user_count"}}'
+```
+
+User property average grouped by city:
+```bash
+ae-cli analysis +build_prop_analysis_qp --project_id 3137 --prop_analysis '{"metric":{"aggregation":"avg","property":"余额"},"groups":[{"field":{"name":"城市","type":"user_property"}}],"filters":[{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"}]}'
+```
+
+User crowds with OR filter:
+```bash
+ae-cli analysis +build_prop_analysis_qp --project_id 3137 --prop_analysis '{"metric":{"aggregation":"user_count"},"filters":[{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"},{"field":{"name":"城市","type":"user_property"},"operator":"exists"}],"relation":"or","userCrowds":[{"name":"账户或城市有值","filters":[{"field":{"name":"账户ID","type":"user_property"},"operator":"exists"},{"field":{"name":"城市","type":"user_property"},"operator":"exists"}],"relation":"or"}]}'
+```
+
+## Decision Rules
+- After successful build, call `+query_adhoc --model_type prop_analysis --qp '<response.qp>'`.
+- If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
+- Wrap JSON parameters in single quotes to avoid shell escaping issues.
+- Do not pre-query metrics or metadata. Pass user-provided property names to the builder and let it resolve them.
+- Do not use `event_property` in prop_analysis. If the user asks for event property analysis, switch to event/funnel/retention builder or ask for clarification.
+- If `userCrowds` is used, at most one group dimension is supported.
+- If the user gave a time zone, keep it for `+query_adhoc --zone_offset`; do not put it in the builder JSON.
+
+## Recommended Chaining
+- `+build_prop_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type prop_analysis --qp '<response.qp>'`

package/skills/ae-analysis/references/build_retention_analysis_qp.md

@@ -0,0 +1,141 @@
+# analysis +build_retention_analysis_qp (build retention analysis qp)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Model Analysis**
+
+## Use Cases
+- Build a validated retention-analysis QP from structured intent.
+- Use in the mandatory builder flow before `+query_adhoc --model_type retention`.
+- This command builds QP only and does not execute the analysis query.
+- This is one of exactly four QP builders: `event`, `retention`, `funnel`, `prop_analysis`.
+- Use this builder for retention ad hoc requests; do not manually build retention QP through `+get_analysis_query_schema`.
+
+## JSON Rules
+- CLI flags use snake_case, but JSON object keys use camelCase DTO names.
+- Correct nested keys: `initialEvent`, `returnEvent`, `unitNum`, `rtnRateOrNum`, `relationEventPropertyName`, `initialFilters`, `returnFilters`, `initialFilterRelation`, `returnFilterRelation`.
+- Initial/return event filters are event-property-only and use `eventPropertyName`; they do not use the generic `field` object.
+- Retention global filters and groups use the generic `field` object.
+- Do not run syntax examples with placeholder JSON. Fill `time_range` and `retention` with valid nested fields before calling this command.
+- `--dry-run` still requires the same required flags as a real builder call. Never run this command as dry-run without `--project_id`, `--time_range`, and `--retention`.
+- Do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, or `get_metric` before this builder for normal ad-hoc analysis. The builder resolves events and properties internally.
+- Builder commands do not accept `zone_offset`; pass `--zone_offset` to `+query_adhoc` after the builder succeeds.
+- If the request misses time range, initial event, return event, or retention interval, stop and ask the user to clarify.
+
+## Command Syntax
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>'
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>' --relation and --time_particle_size day
+ae-cli analysis +build_retention_analysis_qp --project_id <project_id> --time_range '<valid_time_range_json>' --retention '<valid_retention_json>' --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--project_id` / `-p` | Yes | Project ID |
+| `--time_range` | Yes | Retention analysis time range JSON |
+| `--retention` | Yes | Retention intent JSON |
+| `--relation` | No | Top-level retention filter relation. Supported values: and, or. Default: and |
+| `--time_particle_size` | No | Time granularity. Supported values: day, week, month |
+
+## JSON Shape
+`--time_range` object:
+```json
+{"mode":"start_to_yesterday","startTime":"2021-05-18"}
+```
+
+Time range fields:
+| Field | Required | Description |
+|---|---|---|
+| `mode` | Yes | `recent`, `previous`, `custom`, `start_to_today`, `start_to_yesterday` |
+| `unit` | For `recent`/`previous` | `day`, `week`, `month`, `quarter`, `year` |
+| `value` | For `recent`/`previous` | Unit count. `{"mode":"previous","unit":"day","value":1}` means yesterday. |
+| `startTime` | For `custom`/`start_to_*` | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+| `endTime` | For `custom` only | `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss` |
+
+`--retention` object:
+```json
+{
+  "initialEvent":"注册",
+  "returnEvent":"商品购买",
+  "unitNum":7,
+  "statType":"retention",
+  "rtnRateOrNum":"R0",
+  "relationEventPropertyName":"账户ID",
+  "initialFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],
+  "returnFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],
+  "filters":[{"field":{"name":"城市","type":"event_property"},"operator":"exists"}],
+  "groups":[{"field":{"name":"渠道","type":"user_property"}}]
+}
+```
+
+Retention fields:
+| Field | Required | Description |
+|---|---|---|
+| `initialEvent` | Yes | Initial event display name, technical name, or remark |
+| `returnEvent` | Yes | Return event display name, technical name, or remark |
+| `unitNum` | Yes | Retention interval count, such as `1` for day-1 or `7` for day-7 |
+| `statType` | No | `retention` for retained users or `lost` for lost users |
+| `rtnRateOrNum` | No | `R0`, `rate`, or `retention` for rate; `R1`, `number`, or `count` for user count. Default: `R0`. |
+| `relationEventPropertyName` | No | Event property shared by initial event, return event, and simultaneous metrics |
+| `simultaneousMetrics` | No | Extra retention display metrics |
+| `groups` | No | Generic group-by dimensions |
+| `filters` | No | Generic retention filters |
+| `initialFilters` | No | Event-property-only filters for initial event |
+| `initialFilterRelation` | No | Relation for `initialFilters`: `and` or `or` |
+| `returnFilters` | No | Event-property-only filters for return event |
+| `returnFilterRelation` | No | Relation for `returnFilters`: `and` or `or` |
+
+Initial/return event filter object:
+```json
+{"eventPropertyName":"账户ID","operator":"exists"}
+```
+
+Generic filter object for `retention.filters`:
+```json
+{"field":{"name":"城市","type":"event_property"},"operator":"exists"}
+```
+
+Group object:
+```json
+{"field":{"name":"渠道","type":"user_property"}}
+```
+
+Metric object for `simultaneousMetrics`:
+```json
+{"event":"商品购买","aggregation":"user_count"}
+```
+
+Supported aggregations:
+`total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `true_count`, `false_count`, `not_empty_count`, `empty_count`, `median`, `percentile`, `variance`, `stddev`.
+
+Filter operator rules:
+| Operator | Values |
+|---|---|
+| `exists`, `not_exists`, `is_true`, `is_false` | Omit `values` |
+| `between` | Exactly two values |
+| `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `regex`, `not_regex` | Non-empty `values` array |
+| `in_cluster`, `not_in_cluster` | Cluster operator; values are not required by builder validation |
+
+## Examples
+Minimal day-7 retention:
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --retention '{"initialEvent":"注册","returnEvent":"商品购买","unitNum":7}'
+```
+
+Retention with relation property and event-level filters:
+```bash
+ae-cli analysis +build_retention_analysis_qp --project_id 3137 --time_range '{"mode":"start_to_yesterday","startTime":"2021-05-18"}' --retention '{"initialEvent":"special_data","returnEvent":"商品购买","unitNum":7,"relationEventPropertyName":"账户ID","initialFilters":[{"eventPropertyName":"账户ID","operator":"exists"}],"returnFilters":[{"eventPropertyName":"账户ID","operator":"exists"},{"eventPropertyName":"城市","operator":"exists"}],"returnFilterRelation":"or","filters":[{"field":{"name":"账户ID","type":"event_property"},"operator":"exists"},{"field":{"name":"城市","type":"event_property"},"operator":"exists"}],"groups":[{"field":{"name":"账户ID","type":"event_property"}}]}' --relation or --time_particle_size day
+```
+
+## Decision Rules
+- After successful build, call `+query_adhoc --model_type retention --qp '<response.qp>'`.
+- If build returns non-generated status, stop and ask user to clarify; do not call `+query_adhoc`.
+- Wrap JSON parameters in single quotes to avoid shell escaping issues.
+- Do not pre-query metrics or metadata. Pass user-provided event/property names to the builder and let it resolve them.
+- Do not put global filter relation inside `retention`; pass it as top-level CLI flag `--relation`.
+- For overall/totals retention, omit `--time_particle_size`; only set it when user asks for day/week/month breakdown.
+- If the user gave a time zone, keep it for `+query_adhoc --zone_offset`; do not put it in the builder JSON.
+
+## Recommended Chaining
+- `+build_retention_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type retention --qp '<response.qp>'`

package/skills/ae-analysis/references/get_analysis_query_schema.md

@@ -4,13 +4,22 @@
 
 Domain: **Model schema queries**
 
+> **CRITICAL - Builder-supported ad hoc models**
+>
+> Do **not** use this tool for natural-language ad hoc requests whose target model is `event`, `retention`, `funnel`, or `prop_analysis`.
+> For those four models, use the matching QP builder first:
+> `+build_event_analysis_qp`, `+build_retention_analysis_qp`, `+build_funnel_analysis_qp`, or `+build_prop_analysis_qp`, then `+query_adhoc`.
+>
+> If a builder returns `need_clarification`, `invalid_argument`, `unsupported_feature`, or `validation_error`, stop and ask the user or report the structured error. Do not fall back to this schema tool.
+
 > **CRITICAL - Step-by-Step Execution (BLOCKING)**
 >
+> This blocking sequence applies only to non-builder/manual model paths such as `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, or `sql`.
 > **You MUST execute these steps in order. Do NOT skip any step.**
 >
 > | Step | Command | When to proceed |
 > |------|---------|-----------------|
-> | **Step 1 (MANDATORY)** | `--model_type <type>` **without `--segments`** | Always execute first. Review result. |
+> | **Step 1 (MANUAL PATH ONLY)** | `--model_type <type>` **without `--segments`** | Execute first only for non-builder/manual models. Review result. |
 > | **Step 2 (OPTIONAL)** | Add `--segments 'filter_group'` | Only if Step 1 result lacks filter/groupBy structures AND you need them |
 > | **Step 3 (OPTIONAL)** | Add `--segments 'examples'` | Only if Step 1+2 insufficient for multi-metric, time comparison, formulas |
 >
@@ -19,26 +28,27 @@ Domain: **Model schema queries**
 
 ## Pre-call Checklist (Execute in Order)
 
+0. ✓ **Builder-supported model?** → If `event`/`retention`/`funnel`/`prop_analysis`, stop using this tool and use the matching builder.
 1. ✓ **Step 1 completed?** → Review core schema
 2. ✓ **Gap identified?** → Justify need (e.g., "need filter_group structure")
 3. ✓ **Justified?** → Call again with specific segment
 
-**Rule**: Uncertain → execute Step 1 first.
+**Rule**: For non-builder/manual models, uncertain → execute Step 1 first. For `event`, `retention`, `funnel`, or `prop_analysis`, uncertain → read the matching builder reference first.
 
 ## Command (Execute in Order)
 
 ```bash
-# Step 1: ALWAYS START HERE (no segments)
-ae-cli analysis +get_analysis_query_schema --model_type event
+# Step 1: start here only for non-builder/manual models (no segments)
+ae-cli analysis +get_analysis_query_schema --model_type distribution
 
 # Step 2: Only after Step 1, if filter/groupBy needed
-ae-cli analysis +get_analysis_query_schema --model_type event --segments 'filter_group' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --segments 'filter_group' --include_core false
 
 # Step 3: Only after Step 1/2, for complex scenarios
-ae-cli analysis +get_analysis_query_schema --model_type event --segments 'examples' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --segments 'examples' --include_core false
 
 # Follow-up request (already have core from earlier step in same session)
-ae-cli analysis +get_analysis_query_schema --model_type event --segments 'examples' --include_core false
+ae-cli analysis +get_analysis_query_schema --model_type distribution --segments 'examples' --include_core false
 ```
 
 ## Parameters
@@ -53,9 +63,10 @@ ae-cli analysis +get_analysis_query_schema --model_type event --segments 'exampl
 
 | 场景 | 参数 | 执行顺序 |
 |---|---|---|
-| 简单 | 不传 `--segments` | **Step 1** - 单事件、单指标、无过滤、无分组 |
-| 中等 | `--segments 'filter_group'` | **Step 2** - 有过滤或分组，需先完成 Step 1 |
-| 复杂 | `--segments 'examples'` | **Step 3** - 多指标、时间对比、自定义公式，需先完成 Step 1 |
+| Builder 支持模型 | 不适用 | `event`/`retention`/`funnel`/`prop_analysis` 禁止用此工具作为 QP 准备步骤，改用 builder |
+| 简单 | 不传 `--segments` | **Step 1** - 非 builder/manual 模型 |
+| 中等 | `--segments 'filter_group'` | **Step 2** - 非 builder/manual 模型，有过滤或分组，需先完成 Step 1 |
+| 复杂 | `--segments 'examples'` | **Step 3** - 非 builder/manual 模型，需先完成 Step 1 |
 
 ## Next Steps on Failure
-- Verify model type and segment compatibility (e.g., aggregatetype not for funnel/path/interval/sql)
+- Verify model type and segment compatibility (e.g., aggregatetype not for funnel/path/interval/sql)

package/skills/ae-analysis/references/get_metric.md

@@ -4,9 +4,13 @@
 
 Domain: **Metadata Query**
 
+## Constraints
+
+**Not a builder pre-step:** Do not call `+get_metric` before `+build_event_analysis_qp` for normal ad-hoc analysis. If the user asks to query a saved metric, pass the metric display/name/remark directly as `metrics:[{"event":"<metric name>"}]` to `+build_event_analysis_qp`. The builder resolves saved metrics internally. If it cannot resolve the metric, stop on the builder's structured error and ask for clarification.
+
 ## Use Cases
 - Get the definition details of a single metric. Returns the metric name, display name, remark, model type, linked events, and parameter definition without executing metric calculation.
-- Get the definition details of a single metric.
+- Use this command for metric metadata inspection, metric editing, auditing, or when the user explicitly asks for metric definition details. Do not use it merely to expand a saved metric before a builder-supported ad-hoc query.
 
 ## Commands
 ```bash
@@ -22,6 +26,7 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Decision Rules
 - For the first run, pass only the required parameters (`--project_id` and `--metric_id`) to confirm the path works, then add optional parameters.
+- For builder-supported ad-hoc analysis, do not read metric details first. Call the matching builder with the user's metric/event/property wording.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps After Failure
@@ -30,3 +35,4 @@ ae-cli analysis_meta +get_metric --dry-run
 
 ## Recommended Chaining
 - +get_metric -> +update_metric
+- For ad-hoc saved metric query: +build_event_analysis_qp -> +query_adhoc