@thinkingai/ae-cli 1.0.15 → 1.0.20

package/skills/ae-analysis/SKILL.md

@@ -2,10 +2,6 @@
 name: ae-analysis
 version: 3.0.0
 description: "AE/TE/ThinkingEngine/ThinkingAI ae-cli manual for analysis-side tasks in the AE system or analysis platform: reports, dashboards, alerts, ad hoc analysis, drilldown, audience clusters, tags, tag members, metrics and metric definitions, events, properties, virtual events, virtual properties, metadata, project configuration, tracking plans, event tracking, mark times, project lists, and resource links. Use when the user asks to query, create, update, refresh, inspect, troubleshoot, govern, or manage these AE analysis assets. Must use ae-cli, read the matching references/<tool_name>.md command manual before composing commands, and never guess command names, flags, JSON payloads, project_id, resource IDs, or parameter formats."
-metadata:
-  requires:
-    bins: ["ae-cli"]
-  cliHelp: "ae-cli --help"
 ---
 
 # ae-analysis
@@ -19,39 +15,22 @@ metadata:
 
 AE CLI (`ae-cli`) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer `ae-cli` and this skill's reference docs over model memory.
 
-Authentication priority:
-1. `TE_TOKEN` environment variable.
-2. Cached token in `~/.ae-cli/tokens.json`, usually valid for 20 hours.
-3. macOS Chrome token extraction via `ae-cli auth login`.
-
-Useful authentication commands:
-
-```bash
-ae-cli auth login
-ae-cli auth status
-ae-cli auth logout
-```
-
 Global parameters:
 
 | Parameter | Description |
 |---|---|
-| `--host <host>` | Target AE host. Use when the environment is not the default host. |
-| `--format <json|table>` | Output format. Default is JSON. |
+| `--format <json\|table>` | Output format. Default is JSON. |
 | `--jq <expr>` | jq filter expression for JSON output. |
-| `--dry-run` | Preview the request without executing it. |
-| `--yes` | Skip confirmation for write operations. Use only when the user intent is explicit or automation requires it. |
 
 Output and errors:
 - Successful commands return machine-readable JSON by default.
 - Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
-- On auth/config errors, check `ae-cli auth status`, host configuration, and the target environment before retrying.
 
 Safety constraints:
 - Read commands can execute directly after required IDs and references are verified.
 - Write commands require explicit user intent and normally keep the confirmation prompt.
-- Use `--dry-run` before risky or complex writes.
-- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
+- Never invent command names, flags, JSON payloads, `project_id`, resource IDs, field names, event names, property names, metric definitions, or date formats. For builder-supported ad-hoc models (`event`, `retention`, `funnel`, `prop_analysis`), do not pre-discover metadata; pass the user's event/property/metric wording to the matching QP builder and let the builder resolve metadata or return clarification. For non-builder/manual workflows, read the matching command reference and discover real project metadata first.
+- **NEVER fabricate or guess resource names** (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.
 
 ## When to Use
 
@@ -109,9 +88,116 @@ Closed-loop check (must be explicit in result):
 - `+get_resource_url` called or skipped (no ID)
 - Link completion status
 
-## Tool Groups (69)
-
-### analysis (31)
+### C. FUZZY_SEARCH_FALLBACK
+
+For list commands with `--query` parameter (list_reports, list_dashboards, list_events, list_clusters, list_tags, list_alerts, list_metrics):
+
+1. **First attempt**: Use `--query` with user-provided keyword for fuzzy search
+2. **If no results found**, retry up to 2 more times with:
+   - Broader keywords (remove modifiers, use root words)
+   - Alternative terms or synonyms
+3. **After 3 failed fuzzy attempts**, fall back to full list (omit `--query`)
+4. **Present full list** to user and ask them to identify the target resource
+5. **Never proceed** with operations on non-existent resources
+
+**Example workflow:**
+- User asks: "Find active user report"
+- Attempt 1: `--query "active user"` → no results
+- Attempt 2: `--query "active"` → no results
+- Attempt 3: `--query "user"` → no results
+- Fallback: list all reports, show to user, ask for selection
+
+### D. QUERY_EXISTING_FIRST
+
+Before executing ad-hoc queries (`query_adhoc`), MUST check for existing reports/dashboards first:
+
+**Mandatory workflow for data queries:**
+
+1. **Identify user intent** - Extract what metrics/dimensions/filters the user wants
+2. **Search existing reports** - Use `list_reports --query <keyword>` to find matching reports
+3. **Search existing dashboards** - Use `list_dashboards --query <keyword>` to find matching dashboards
+4. **If found** - Use `query_report_data` or `query_dashboard_report_data` to get data from existing assets
+5. **If not found** - For QP builder-supported models (`event`, `retention`, `funnel`, `prop_analysis`), call the matching builder first and then call `query_adhoc` with builder `qp`; do not call schema or metadata tools between the report/dashboard miss and the builder. For all other `query_adhoc` models, use the legacy schema/metadata path.
+
+**Rationale:**
+- **Performance**: Existing reports are pre-computed and faster
+- **Consistency**: Reports have business-defined metrics and calibrated logic
+- **Resource efficiency**: Avoid redundant computation
+- **Permissions**: Users may have report access but not ad-hoc query permissions
+
+**Example:**
+- User: "Query active users in last 7 days"
+- Step 1: `list_reports --query "active user"` → found "DAU Active Users Report"
+- Step 2: `query_report_data --report_id <id>` → return data
+- ❌ WRONG: Directly use `query_adhoc` without checking existing reports
+
+**Exceptions (when ad-hoc is acceptable):**
+- User explicitly requests "ad-hoc query" or "ad-hoc analysis"
+- User wants custom filters/groupings not available in existing reports
+- User is exploring data for new insights (exploratory analysis)
+- No matching reports found after search + fallback
+
+### E. QP_BUILDER_SUPPORTED_MODELS_ONLY
+
+QP builder supports exactly four ad-hoc model types: `event`, `retention`, `funnel`, and `prop_analysis`.
+
+For these four model types, QP builder is mandatory before `query_adhoc`. Do not handcraft QP from `get_analysis_query_schema`, examples, or prior knowledge.
+
+1. `event` -> `+build_event_analysis_qp`
+2. `retention` -> `+build_retention_analysis_qp`
+3. `funnel` -> `+build_funnel_analysis_qp`
+4. `prop_analysis` -> `+build_prop_analysis_qp`
+
+Builder-supported model routing is:
+1. Search existing reports/dashboards if `QUERY_EXISTING_FIRST` applies.
+2. If no existing asset is used, read the matching builder reference.
+3. Call the matching builder with complete required parameters.
+4. Call `query_adhoc` only when builder returns `status=generated`.
+
+Do not insert metadata/schema calls between steps 2 and 3 for builder-supported models. Specifically, do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, `get_metric`, or `get_report_definition` to prepare the builder payload. The builder resolves event/property/metric metadata internally and returns `need_clarification` when it cannot.
+
+Event metric shortcut:
+- If the user asks to query a saved/business metric through event analysis, pass the metric name/display name/remark directly as an event metric target: `--metrics '[{"event":"<metric name>"}]'`.
+- Do not call `analysis_meta +list_metrics` or `analysis_meta +get_metric` first just to expand the metric definition.
+- If the user provides an explicit formula, pass the formula and dependencies to `+build_event_analysis_qp`; do not convert it by reading schema or metric metadata first.
+
+Metric result vs metric metadata:
+- "Query metric result/value/trend over a time range" is an ad-hoc analysis request. Use report/dashboard search first when applicable, then builder -> `query_adhoc`.
+- "Inspect/search/update/create metric definition" is metadata/governance. Only then use `analysis_meta +list_metrics`, `+get_metric`, `+create_metric`, or `+update_metric`.
+
+For all other `query_adhoc` model types (`distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, `sql`), QP builder is not supported. Use the legacy path: read `query_adhoc.md`, fetch schema/metadata as required, then construct QP manually according to the relevant schema.
+
+Execution rule:
+- If builder result `status=generated`, call `+query_adhoc` with the same `model_type` and the returned `qp`.
+- If builder returns non-generated status (`need_clarification`, `invalid_argument`, `unsupported_feature`, `validation_error`), stop and ask the user for clarification instead of calling `query_adhoc`.
+- Never bypass a failed builder by manually assembling QP for `event`, `retention`, `funnel`, or `prop_analysis`.
+
+Builder payload rules:
+- Before composing any builder JSON, read the matching builder reference doc. The builder references contain the required JSON shape and model-specific field differences.
+- CLI flag names use snake_case, but nested JSON keys use the service DTO field names in camelCase. Correct: `startTime`, `endTime`, `relationEventPropertyName`, `eventPropertyName`. Wrong: `start_date`, `start_time`, `relation_property`, `fieldName`.
+- Builder dry-run still requires the normal required flags. Do not run builder dry-run by itself.
+- Do not pass placeholder `{}` or `[]` for required nested structures except when intentionally checking CLI validation. Fill required inner fields before calling the command.
+- Use enum values exactly as documented. Examples: `mode=start_to_yesterday`, `operator=exists`, `relation=or`, `field.type=event_property`.
+- For `exists`, `not_exists`, `is_true`, and `is_false`, omit `values`. For `between`, provide exactly two values. For other value-based operators, provide a non-empty `values` array.
+- Builder tools do not execute the query and do not take `zone_offset`. Pass time zone to `+query_adhoc` with `--zone_offset` after the builder returns `status=generated`.
+- If the user's request lacks a required business element such as time range, event, metric, funnel window, property, or relation field, stop and ask for clarification. If the request supplies a name but it may be a metadata ambiguity, call the builder and let it return candidates. Do not invent names or handcraft QP.
+
+Supported builder chain:
+1. Read the builder reference for the target model.
+2. Build structured JSON from the user's request. Use user-provided event/property/metric names as-is; do not pre-query metadata for these names.
+3. Run the matching `+build_*_analysis_qp` command.
+4. If `status=generated`, call `+query_adhoc --model_type <same_model> --qp '<response.qp>'`.
+5. If status is not `generated`, report the structured error or ask the user for the missing information; do not continue to `query_adhoc`.
+
+Legacy query_adhoc chain:
+1. Use only for `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, or `sql`.
+2. Read `references/query_adhoc.md` and required schema/metadata references.
+3. Build QP manually from the documented schema and verified project metadata.
+4. Call `+query_adhoc`.
+
+## Tool Groups (73)
+
+### analysis (35)
 
 Alerts (5):
 - `+get_alert_definition_schema` ([doc](references/get_alert_definition_schema.md))
@@ -135,7 +221,11 @@ Reports and Dashboards (13):
 - `+create_public_access_link` ([doc](references/create_public_access_link.md))
 - `+update_public_access_link` ([doc](references/update_public_access_link.md))
 
-Model Analysis (6):
+Model Analysis (10):
+- `+build_event_analysis_qp` ([doc](references/build_event_analysis_qp.md))
+- `+build_retention_analysis_qp` ([doc](references/build_retention_analysis_qp.md))
+- `+build_funnel_analysis_qp` ([doc](references/build_funnel_analysis_qp.md))
+- `+build_prop_analysis_qp` ([doc](references/build_prop_analysis_qp.md))
 - `+query_adhoc` ([doc](references/query_adhoc.md))
 - `+drilldown_users` ([doc](references/drilldown_users.md))
 - `+drilldown_user_events` ([doc](references/drilldown_user_events.md))
@@ -226,4 +316,4 @@ npm run verify:analysis-common-tools
 
 ## Reference Docs
 
-See the unified `references/` directory (69 command docs total).
+See the unified `references/` directory (73 command docs total).

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