@thinkingai/ae-cli 6.0.30 → 6.0.32

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

@@ -1,62 +0,0 @@
-# analysis +build_attribution_analysis_qp (Build Attribution Analysis QP)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model Analysis**
-
-## Use Cases
-- Build a validated attribution-analysis QP from structured attribution intent.
-- Attribution analysis assigns conversion credit to touchpoint events that preceded a target conversion event.
-- Use in the mandatory builder flow before `+query_adhoc --model_type attribution`.
-- This command builds QP only and does not execute the analysis query.
-
-## JSON Rules
-- CLI flags use snake_case, but JSON object keys use camelCase.
-- `--attribution` is a JSON object. Required fields: `targetEvent`, `targetAggregation`, `attributionEvents` (array), `attributionModel`, `window`.
-- `attributionModel` values: `first`=First Touch, `last`=Last Touch, `linear`=Equal credit.
-- `window.unit`: day / hour / minute. `window.value`: 0=same day.
-- Wrap JSON in single quotes in shell commands.
-
-## Command Syntax
-```bash
-ae-cli analysis +build_attribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --attribution '<attribution_json>'
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
-| `--time_range` | Yes | Time range JSON |
-| `--attribution` | Yes | Attribution intent JSON |
-
-## JSON Shape
-`--attribution` object:
-```json
-{
-  "targetEvent": "purchase",
-  "targetAggregation": "A101",
-  "attributionEvents": [{"event": "click_ad"}, {"event": "view_product"}],
-  "attributionModel": "last",
-  "window": {"value": 7, "unit": "day"}
-}
-```
-
-Optional fields in `--attribution`:
-- `targetProperty`: required when targetAggregation is property-based (A103/A104/A106/A107/A108 etc.)
-- `directConversion`: include direct conversions without touchpoints. Defaults to true.
-- `filters`: global filters array
-- `relation`: filter relation (and / or)
-
-## Examples
-```bash
-ae-cli analysis +build_attribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":30}' --attribution '{"targetEvent":"purchase","targetAggregation":"A101","attributionEvents":[{"event":"click_ad"}],"attributionModel":"last","window":{"value":7,"unit":"day"}}'
-```
-
-## Decision Rules
-- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
-- After successful build (`status=generated`), call `+query_adhoc --model_type attribution --qp '<response.qp>'`.
-- If non-generated status, stop and ask user to clarify.
-
-## Recommended Chain
-- `+build_attribution_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type attribution --qp '<response.qp>'`

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

@@ -1,62 +0,0 @@
-# analysis_audience +build_cluster_definition (Build Cluster Definition)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Cluster Management**
-
-## Use Cases
-
-- Build a cluster definition JSON from structured intent. Call this before `+create_cluster` or `+update_cluster` to generate the `definition` field.
-- For type=condition, event and property names are resolved from project metadata — do not guess.
-- For type=sql, pass the SQL string directly.
-- On success, pass the returned definition to `+create_cluster` or `+update_cluster`.
-
-## Required Prerequisites (MUST)
-
-- Before calling this command, you must first read and follow these reference docs:
-  - [`./get_cluster_definition_schema.md`](./get_cluster_definition_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not construct `--conditions` / `--include_filter` / `--exclude_filter` until the schema has been read and metadata has been verified for the same `project_id`.
-
-## Commands
-
-```bash
-ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type condition --conditions '{}'
-ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type condition --conditions '{}' --include_filter '{}' --exclude_filter '{}'
-ae-cli analysis_audience +build_cluster_definition --project_id <project_id> --type sql --sql 'SELECT "#user_id" FROM ...'
-ae-cli analysis_audience +build_cluster_definition --dry-run
-```
-
-## Parameters
-
-| Parameter             | Required | Description                                                                                                                           |
-| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project_id` / `-p` | Yes      | Project ID                                                                                                                            |
-| `--authenticated_only` | No | Resolve only authenticated assets while building the definition. |
-| `--type`              | Yes      | Cluster type. Supported values: `condition`, `sql`                                                                                    |
-| `--conditions`        | No       | For type=condition: main condition group JSON (required when type=condition). See `+get_cluster_definition_schema` for the structure. |
-| `--include_filter`    | No       | For type=condition: global include condition group JSON.                                                                              |
-| `--exclude_filter`    | No       | For type=condition: global exclude condition group JSON.                                                                              |
-| `--sql`               | No       | For type=sql: SQL query returning a single column named `#user_id`.                                                                   |
-
-## Decision Rules
-- Use `--authenticated_only true` when the definition should only resolve authenticated events/properties/metrics/clusters/tags.
-
-- Determine `--type` first, then pass the corresponding parameters.
-- For type=condition, `--conditions` is effectively required; `--include_filter` and `--exclude_filter` are optional global filters.
-- For type=sql, only `--sql` is needed; condition-related parameters are ignored.
-- Event and property names in condition JSON must come from session-verified metadata (`analysis_meta +list_events` / `+list_properties` for the same `project_id`).
-- Do not guess event or property names — always verify against real metadata first.
-- Wrap JSON parameters in single quotes (e.g. `--conditions '{}'`) to avoid shell escaping issues.
-- Run `--dry-run` first to inspect the request mapping before making the actual call.
-
-## Next Step on Failure
-
-- If required parameters are missing, check that `--project_id` and `--type` are provided.
-- If the returned definition is rejected by `+create_cluster` or `+update_cluster`, re-read `+get_cluster_definition_schema` with `--response_mode examples` and verify metadata names again.
-
-## Recommended Chain
-
-- `+get_cluster_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_cluster_definition` → `+create_cluster`
-- `+get_cluster_definition_schema` → (first build/update in session or refresh) `analysis_meta +list_events` → `analysis_meta +list_properties` → `+build_cluster_definition` → `+update_cluster`

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

@@ -1,67 +0,0 @@
-# analysis +build_distribution_analysis_qp (Build Distribution Analysis QP)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Model Analysis**
-
-## Use Cases
-- Build a validated distribution-analysis QP from structured distribution metrics.
-- Distribution analysis shows how a metric value is distributed across users or events.
-- Use in the mandatory builder flow before `+query_adhoc --model_type distribution`.
-- This command builds QP only and does not execute the analysis query.
-
-## JSON Rules
-- CLI flags use snake_case, but JSON object keys use camelCase.
-- `--distribution_metrics` is a JSON array. Each item requires `event` and `aggregation`.
-- Distribution-specific aggregations: `A200`=count, `A201`=active-days, `A202`=active-hours.
-- Standard aggregations requiring `property`: A103=sum, A104=avg, A106=max, A107=min, A117=median, A119=percentile.
-- Wrap JSON in single quotes in shell commands.
-
-## Command Syntax
-```bash
-ae-cli analysis +build_distribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --distribution_metrics '<metrics_json>'
-ae-cli analysis +build_distribution_analysis_qp --project_id <project_id> --time_range '<time_range_json>' --distribution_metrics '<metrics_json>' --time_particle_size day --groups '<groups_json>' --filters '<filters_json>' --relation and
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
-| `--time_range` | Yes | Time range JSON |
-| `--distribution_metrics` | Yes | Distribution metrics JSON array |
-| `--time_particle_size` | No | Time granularity. Allowed values: day, week, month, total. Defaults to day. |
-| `--groups` | No | Optional group-by dimensions JSON array |
-| `--filters` | No | Optional global filters JSON array |
-| `--relation` | No | Filter relation. Supported values: and, or. Default: and. |
-
-## JSON Shape
-`--distribution_metrics` array:
-```json
-[{"event":"login","aggregation":"A200"}]
-```
-
-Each metric item fields:
-- `event` (required): event name
-- `aggregation` (required): aggregation code
-- `property` (optional): required for property-based aggregations
-- `percentile` (optional): percentile value, e.g. 90 for P90. Required when aggregation=A119.
-- `intervalType` (optional): def (auto, default) / user_defined (custom) / discrete (raw value)
-- `quotaIntervalArr` (optional): custom bucket boundaries, e.g. [100,1000,10000]. Required when intervalType=user_defined.
-- `filters` (optional): metric-level filters
-- `relation` (optional): filter relation for metric-level filters
-
-## Examples
-```bash
-ae-cli analysis +build_distribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --distribution_metrics '[{"event":"login","aggregation":"A200"}]'
-
-ae-cli analysis +build_distribution_analysis_qp --project_id 3137 --time_range '{"mode":"previous","unit":"day","value":7}' --distribution_metrics '[{"event":"purchase","aggregation":"A103","property":"amount"}]'
-```
-
-## Decision Rules
-- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
-- After successful build (`status=generated`), call `+query_adhoc --model_type distribution --qp '<response.qp>'`.
-- If non-generated status, stop and ask user to clarify.
-
-## Recommended Chain
-- `+build_distribution_analysis_qp` -> if `status=generated` -> `+query_adhoc --model_type distribution --qp '<response.qp>'`

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

@@ -1,58 +0,0 @@
-# analysis +build_entity_details_sql (Generate Entity Details SQL)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Entity details SQL queries**
-
-## Use Cases
-- When constructing `definition`, you must first obtain the cluster schema and fill in the project event/property metadata.
-- Build the SQL for an entity details query. The parameters are the same as `+query_entity_details`, but the tool returns SQL instead of query results.
-- Build the SQL for an entity details query.
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--definition` / `--properties`, you must first read and follow these reference documents:
-  - [`./get_cluster_definition_schema.md`](./get_cluster_definition_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate the final `definition` / `properties` until the documentation review and prerequisite command calls are complete.
-
-## Prerequisite call chain (required for constructing definition/properties)
-1. First confirm the cluster type (condition / sql).
-2. Read `get_cluster_definition_schema.md`, then call `ae-cli analysis_audience +get_cluster_definition_schema --cluster_type <condition|sql>` to get the structure.
-3. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>`.
-4. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>`.
-5. Build `definition` (and optional `properties`) from the schema + metadata, then call `+build_entity_details_sql`.
-
-## Command
-```bash
-ae-cli analysis +build_entity_details_sql --project_id <project_id> --definition '{}'
-ae-cli analysis +build_entity_details_sql --project_id <project_id> --entity_id 1001 --definition '{}' --properties '{}' --sort_by time --sort_order desc --limit 100 --zone_offset 8
-ae-cli analysis +build_entity_details_sql --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--entity_id` | No | Optional entity ID used in multi-entity scenarios. If omitted, the default user entity is used. |
-| `--definition` | Yes | Cluster definition JSON. MUST call `+get_cluster_definition_schema` first, then fill valid event/property names from `analysis_meta +list_events` / `analysis_meta +list_properties` in the same `project_id`. |
-| `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--sort_by` | No | Optional sort field |
-| `--sort_order` | No | Optional sort order. Supported values: asc and desc |
-| `--limit` | No | Optional result limit. Default: 1000, maximum: 10000 |
-| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
-
-## Decision Rules
-- `definition` / `properties` cannot be written from experience alone: they must satisfy both the schema structure and the project metadata constraints.
-- Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
-- On the first run, start with only the required parameters (`--project_id`, `--definition`) and add optional parameters after confirming the path works.
-- Wrap JSON parameters in single quotes (for example `--definition '{}'`, `--properties '{}'`) to avoid shell escaping issues.
-- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-
-## Next Steps on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in first (focus on `--project_id` and `--definition`).
-- If `Invalid JSON` appears, first check the schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
-
-## Recommended chaining
-- +get_cluster_definition_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +build_entity_details_sql
-- +query_entity_details -> +query_event_details -> +build_event_details_sql

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

@@ -1,134 +0,0 @@
-# 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 the `event` builder in the ten-model guided QP builder set.
-- 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 |
-| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
-| `--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
-- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
-- 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_event_details_sql.md

@@ -1,61 +0,0 @@
-# analysis +build_event_details_sql (generate event detail SQL)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Event Detail SQL Queries**
-
-## Use Cases
-- When building `filters` / `properties`, first obtain the filter schema and the project's real event/property metadata.
-- Build the SQL for an event details query. The parameters are the same as `+query_event_details`, but the tool returns SQL instead of query results.
-- Build the SQL for an event details query.
-
-## Mandatory Prerequisites (MUST)
-- Before building `--filters` / `--properties`, you must first read and follow the following reference docs:
-  - [`./get_filter_schema.md`](./get_filter_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate final `filters` / `properties` until the above docs have been read and the prerequisite commands have been called.
-
-## Prerequisite Call Chain (required for filters/properties)
-1. Read `get_filter_schema.md`, then call `ae-cli analysis +get_filter_schema` to get the filter structure.
-2. Read `list_events.md`, then call `ae-cli analysis_meta +list_events --project_id <project_id>` to confirm available event names.
-3. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>` to get available properties.
-4. Build `filters` / `properties` based on the schema and metadata, then call `+build_event_details_sql`.
-
-## Commands
-```bash
-ae-cli analysis +build_event_details_sql --project_id <project_id> --event_name login --start_time '2026-04-08 00:00:00' --end_time '2026-04-08 23:59:59'
-ae-cli analysis +build_event_details_sql --project_id <project_id> --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 100 --zone_offset 8
-ae-cli analysis +build_event_details_sql --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--event_name` | Yes | Event name |
-| `--start_time` | No | Start time. Format: yyyy-MM-dd HH:mm:ss |
-| `--end_time` | No | End time. Format: yyyy-MM-dd HH:mm:ss |
-| `--relative_date_range` | No | Optional relative date range in m-n format. For example, 0-7 means the most recent 7 days including today. Use either this field or start_time/end_time. |
-| `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--sort_by` | No | Optional sort field |
-| `--sort_order` | No | Optional sort order. Supported values: asc and desc |
-| `--limit` | No | Optional result limit. Default: 100 |
-| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
-
-## Decision Rules
-- `filters` / `properties` cannot be written by hand based on experience alone: they must satisfy both the schema structure and the project's real metadata.
-- `list_events` / `list_properties` must be learned from the corresponding reference docs before calling them.
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--event_name`) and add optional parameters after confirming the chain works.
-- Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--properties '{}'`) to avoid shell escaping issues.
-- When dates/time ranges are involved, validate with a short range first and then expand gradually.
-- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-
-## Next Step After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--event_name`).
-- If `Invalid JSON` appears, first check the required filter schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
-
-## Recommended Chaining
-- +get_filter_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +build_event_details_sql
-- +query_entity_details -> +query_event_details -> +build_event_details_sql

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

@@ -1,145 +0,0 @@
-# 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 the `funnel` builder in the ten-model guided QP builder set.
-- 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 |
-| `--authenticated_only` | No | Resolve only authenticated assets while building the QP. Do not pass this flag to `+query_adhoc`. |
-| `--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
-- Use `--authenticated_only true` only when the user explicitly wants authenticated assets; do not add this flag to `+query_adhoc`.
-- 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>'`