@thinkingai/ae-cli 6.0.30 → 6.0.31

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

@@ -1,58 +0,0 @@
-# analysis +query_bi_panel_data (query BI panel data)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **BI panel management**
-
-## Use Cases
-- Query released BI panel chart data as one-dimensional `columns` + `rows`.
-- Query BI panel summary content as `markdown` + paged `blocks`.
-- Apply dashboard-level parameter controls, dashboard-level permission controls, and page chart filter controls using the schema returned by `+get_bi_panel_detail`.
-
-## Mandatory Prerequisite
-Call `+get_bi_panel_detail` first unless you already have verified `pageKey`, queryable `chartIds`, returned columns, and control schemas for the same `project_id`, `panel_id`, host, and released version.
-
-## Command
-```bash
-ae-cli analysis +query_bi_panel_data --project_id <project_id> --panel_id <panel_id> --page_key <page_key> --result_type charts
-ae-cli analysis +query_bi_panel_data --project_id <project_id> --panel_id <panel_id> --page_key <page_key> --result_type charts --chart_ids '["chart_city"]' --columns '["city","height"]' --row_limit 50 --row_offset 0
-ae-cli analysis +query_bi_panel_data --project_id <project_id> --panel_id <panel_id> --page_key summary --result_type summary --block_limit 20 --block_offset 0
-ae-cli analysis +query_bi_panel_data --project_id <project_id> --panel_id <panel_id> --page_key <page_key> --result_type charts --request_id mcp_1234567890abcdef1234567890abcdef --chart_filter_controls '[{"controlId":"chart_filter_city","value":["上海市","北京市"]}]'
-ae-cli analysis +query_bi_panel_data --project_id <project_id> --panel_id <panel_id> --page_key <page_key> --result_type charts --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--panel_id` | Yes | BI panel ID returned by `+list_bi_panels` |
-| `--page_key` | Yes | Page key returned by `+get_bi_panel_detail` |
-| `--result_type` | Yes | `charts` or `summary` |
-| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
-| `--chart_ids` | No | JSON array of chart IDs when `result_type=charts`. If omitted, all queryable charts on the page are queried. |
-| `--parameter_controls` | No | JSON array of dashboard-level parameter control overrides. Each item has `controlId` and one scalar `value`. |
-| `--permission_controls` | No | JSON array of dashboard-level permission control values. Each item has `controlId` and `value`; `value` may be one scalar or an array. |
-| `--chart_filter_controls` | No | JSON array of page chart filter control values. Each item has `controlId` and `value`; `value` may be one scalar or an array and applies only to bound charts. |
-| `--columns` | No | Optional returned columns for chart data. Must match columns returned by `+get_bi_panel_detail`. |
-| `--row_limit` | No | Chart row limit. Default: 50, maximum: 10000. |
-| `--row_offset` | No | Chart row offset. Default: 0. |
-| `--block_limit` | No | Summary block limit. Default: 20, maximum: 10000. |
-| `--block_offset` | No | Summary block offset. Default: 0. |
-| `--use_cache` | No | Whether to use cache. Default: true. |
-| `--timeout_minutes` | No | Query timeout in minutes. Default: 3, minimum: 1, maximum: 10. |
-
-## Control Rules
-- `parameter_controls` accept one scalar value only. Arrays are invalid.
-- `permission_controls` accept one scalar value or an array. `allowedValues` from detail are hints only; real data permission is enforced by the BI query path.
-- `chart_filter_controls` accept one scalar value or an array regardless of UI single/multi-select setting. They apply only to `boundChartIds`.
-- PageCharts filter components that have no passed value and no default do not add a filter.
-- Do not pass internal fields such as `paramList`, `permissionFilters`, `visualCfg`, `whereList`, `whereValues`, `field`, `columnName`, `userId`, or `openId`.
-
-## Decision Rules
-- For charts, omit `--chart_ids` on the first run to query all queryable charts on the page.
-- Explicitly querying a non-queryable filter component returns a chart-level unsupported result.
-- Use `--columns`, `--row_limit`, and `--row_offset` to reduce response size.
-- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
-
-## Recommended Chaining
-- `+list_bi_panels` -> `+get_bi_panel_detail` -> `+query_bi_panel_data`

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

@@ -1,35 +0,0 @@
-# analysis +query_dashboard_detail (read dashboard structure)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Dashboard Management**
-
-## Use Cases
-- Get detailed information about a specific dashboard including:
-- Associated reports (IDs, names, types, and metadata)
-- Dashboard notes (IDs, titles, descriptions)
-- Share members (userId, userName, permissions)
-- Get detailed information about a specific dashboard including: - Associated reports (IDs, names, types, and metadata) - Dashboard notes (IDs, titles, descriptions) - Share members (userId, userName, permissions)
-
-## Commands
-```bash
-ae-cli analysis +query_dashboard_detail --project_id <project_id> --dashboard_id 1
-ae-cli analysis +query_dashboard_detail --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--dashboard_id` / `-d` | Yes | Dashboard ID |
-
-## Decision Rules
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--dashboard_id`) and add optional parameters after confirming the chain works.
-- 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`, `--dashboard_id`).
-- If the query times out or the result is abnormal, first reduce the time range/grouping dimensions, then split the query to locate the issue.
-
-## Recommended Chaining
-- +list_dashboards -> +query_dashboard_detail -> +query_dashboard_report_data

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

@@ -1,63 +0,0 @@
-# analysis +query_dashboard_report_data (Batch Query Dashboard Report Data)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Dashboard management**
-
-## Use Cases
-- Precondition helper: call `+get_filter_schema` to get the structure before using this tool.
-- When constructing `filters`, you must supplement it with real event/property metadata from the project.
-- Query analysis data for one or more reports in a dashboard. Returns actual analysis results without the dashboard definition. Supports additional filters and time range overrides.
-- Query analysis data for one or more reports in a dashboard.
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--filters`, you must first read and follow these reference documents:
-  - [`./get_filter_schema.md`](./get_filter_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate the final `filters` until the documentation review and prerequisite command calls are complete.
-
-## Prerequisite call chain (required for constructing filters)
-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>`.
-3. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>`.
-4. Build `filters` from the schema + metadata, then call `+query_dashboard_report_data`.
-
-## Command
-```bash
-ae-cli analysis +query_dashboard_report_data --project_id <project_id> --dashboard_id 1
-ae-cli analysis +query_dashboard_report_data --project_id <project_id> --dashboard_id 1 --filters '{}' --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --use_cache true --report_ids '[1001]' --request_id mcp_ffffffffffffffffffffffffffffffff --timeout_minutes 8
-ae-cli analysis +query_dashboard_report_data --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--dashboard_id` / `-d` | Yes | Dashboard ID |
-| `--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`. |
-| `--start_date` | No | Optional start date. Format: yyyy-MM-dd |
-| `--end_date` | No | Optional end date. Format: yyyy-MM-dd |
-| `--time_granularity` | No | Optional time granularity used to override the report default. Supported values: minute, minute5, minute10, hour, day, week, month, quarter, year, total. |
-| `--use_cache` | No | Whether to use cache. Default: true |
-| `--report_ids` | No | Optional list of report IDs. If omitted, all reports in the dashboard are queried. |
-| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
-| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
-
-## Decision Rules
-- `filters` cannot be written from experience alone: it must satisfy both the filter schema and the project metadata constraints.
-- Before calling `list_events` / `list_properties`, you must first study the corresponding reference documents.
-- On the first run, include all required parameters (`--project_id`, `--dashboard_id`, `--request_id`) and add optional parameters after confirming the path works.
-- Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--report_ids '[]'`) to avoid shell escaping issues.
-- When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
-- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
-- 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`, `--dashboard_id`, `--request_id`).
-- If `Invalid JSON` appears, first check the filter schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
-- If the query times out or results are abnormal, first narrow the time range / grouping dimensions, then split the subqueries to locate the issue.
-
-## Recommended chaining
-- +get_filter_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_dashboard_report_data
-- +list_dashboards -> +query_dashboard_detail -> +query_dashboard_report_data

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

@@ -1,63 +0,0 @@
-# analysis +query_entity_details (query entity details)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Entity Detail Queries**
-
-## Use Cases
-- When building `definition`, first obtain the cluster schema and supplement it with the project's real event/property metadata.
-- Query entity detail data. Returns user detail results based on the entity ID and cluster definition, and supports display properties, sorting, and result limits.
-- Query entity detail data.
-
-## Mandatory Prerequisites (MUST)
-- Before building `--definition` / `--properties`, you must first read and follow the following 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 generate final `definition` / `properties` until the above docs have been read and the prerequisite commands have been called.
-
-## Prerequisite Call Chain (required for building 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`) based on the schema and metadata, then call `+query_entity_details`.
-
-## Commands
-```bash
-ae-cli analysis +query_entity_details --project_id <project_id> --definition '{}'
-ae-cli analysis +query_entity_details --project_id <project_id> --entity_id 1001 --definition '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true --request_id mcp_eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --timeout_minutes 8
-ae-cli analysis +query_entity_details --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                                                                                                                                                                                               |
-| `--use_cache` | No | Whether to use cache. Default: true                                                                                                                                                                                                     |
-| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
-| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
-
-## Decision Rules
-- `definition` / `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, include all required parameters (`--project_id`, `--definition`, `--request_id`) and add optional parameters after confirming the chain works.
-- Wrap JSON parameters in single quotes (for example `--definition '{}'`, `--properties '{}'`) to avoid shell escaping issues.
-- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
-- 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`, `--definition`, `--request_id`).
-- If `Invalid JSON` appears, first check the required schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
-- If the query times out or the result is abnormal, first reduce the time range/grouping dimensions, then split the query to locate the issue.
-
-## Recommended Chaining
-- +get_cluster_definition_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_entity_details
-- +query_entity_details -> +query_event_details -> +build_event_details_sql

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

@@ -1,66 +0,0 @@
-# analysis +query_event_details (Query Event Details)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Event detail queries**
-
-## Use Cases
-- When constructing `filters` / `properties`, you must first obtain the filter schema and the project metadata for real events/properties.
-- Query event detail data. Supports time range, filters, display properties, sorting, and result limits.
-- Time can be specified via `--relative_date_range` OR (`--start_time` AND `--end_time`).
-
-## Mandatory prerequisites (MUST)
-- Before constructing `--filters` / `--properties`, you must first read and follow these reference documents:
-  - [`./get_filter_schema.md`](./get_filter_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate the final `filters` / `properties` until the documentation review and prerequisite command calls are complete.
-
-## Prerequisite call chain (required for constructing 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 the available event names.
-3. Read `list_properties.md`, then call `ae-cli analysis_meta +list_properties --project_id <project_id>` to get the available properties.
-4. Build `filters` / `properties` from the schema + metadata, then call `+query_event_details`.
-
-## Command
-```bash
-ae-cli analysis +query_event_details --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 +query_event_details --project_id <project_id> --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true --request_id mcp_dddddddddddddddddddddddddddddddd --timeout_minutes 8
-ae-cli analysis +query_event_details --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. Required if not using relative_date_range. |
-| `--end_time` | No | End time. Format: yyyy-MM-dd HH:mm:ss. Required if not using relative_date_range. |
-| `--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: 1000 |
-| `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
-| `--use_cache` | No | Whether to use cache. Default: true |
-| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
-| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
-
-## Decision Rules
-- `filters` / `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, include all required parameters (`--project_id`, `--event_name`, `--request_id`) and add optional parameters after confirming the path works.
-- Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--properties '{}'`) to avoid shell escaping issues.
-- When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
-- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
-- 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`, `--event_name`).
-- If `Invalid JSON` appears, first check the filter schema required fields, then verify whether the event/property names come from metadata query results for the same `project_id`.
-- If the query times out or results are abnormal, first narrow the time range / grouping dimensions, then split the subqueries to locate the issue.
-
-## Recommended chaining
-- +get_filter_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_event_details
-- +query_entity_details -> +query_event_details -> +build_event_details_sql

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

@@ -1,99 +0,0 @@
-# analysis +query_report_data (query data by report)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Report Management**
-
-## Use Cases
-- Prerequisite helper: first call `+get_filter_schema` to get the structure, then call this tool.
-- Prerequisite helper: first call `+get_groupby_schema` to get the structure, then call this tool.
-- When building `filters` / `group_by`, you must supplement the project's real event/property metadata.
-- Query analysis data for one or more reports. Returns chart values, trend results, and similar data, but not report definitions. Supports extra filters, group-by settings, and time range overrides.
-- Query analysis data for one or more reports.
-
-## Mandatory Prerequisites (MUST)
-- Before building `--filters` / `--group_by`, you must first read and follow the following reference docs:
-  - [`./get_filter_schema.md`](./get_filter_schema.md)
-  - [`./get_groupby_schema.md`](./get_groupby_schema.md)
-  - [`./list_events.md`](./list_events.md)
-  - [`./list_properties.md`](./list_properties.md)
-- Do not generate final `filters` / `group_by` until the above docs have been read and the prerequisite commands have been called.
-
-## Prerequisite Call Chain (required for building filters/group_by)
-1. Read `get_filter_schema.md`, then call `ae-cli analysis +get_filter_schema` to get the filter structure.
-2. Read `get_groupby_schema.md`, then call `ae-cli analysis +get_groupby_schema` to get the grouping 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 `filters` / `group_by` based on the schema and metadata, then call `+query_report_data`.
-
-## Commands
-```bash
-ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]'
-ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --filters '{}' --group_by '[]' --request_id mcp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --use_cache true --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --timeout_minutes 8
-# SQL-model report: override its dynamic parameters (${Selector}/${Time}/${Text}) by paramName
-ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --sql_params '[{"paramName":"selector1","paramExpress":"<selectorName>"},{"paramName":"time2","startTime":"2026-01-01 00:00:00","endTime":"2026-06-30 23:59:59"}]'
-ae-cli analysis +query_report_data --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--report_ids` | Yes | List of report IDs |
-| `--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`. |
-| `--group_by` | No | Optional group-by JSON array. If provided, MUST follow `+get_groupby_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--request_id` | Yes | Required unique request ID used for tracking and cancellation. Generate it before starting the query. It must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. `requestId` is not auto-generated for MCP query tools because the caller must know it before the response for proactive cleanup. If omitted or blank, the backend returns `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`. The response `metadata.requestId` echoes the supplied requestId and can also be passed to `cancel_query(requestId)` when the query is no longer needed. |
-| `--use_cache` | No | Whether to use cache. Default: true |
-| `--start_date` | No | Optional start date in yyyy-MM-dd format |
-| `--end_date` | No | Optional end date in yyyy-MM-dd format |
-| `--time_granularity` | No | Optional time granularity used to override the report default. Supported values: minute, minute5, minute10, hour, day, week, month, quarter, year, total. |
-| `--timeout_minutes` | No | Query timeout in minutes. If the query exceeds this time, it will be cancelled automatically. 30 minutes if omitted. |
-| `--sql_params` | No | Optional override for a SQL-model report's dynamic parameters (the `${...}` placeholders embedded in the report SQL). JSON array of params matched by `paramName`. Only listed params are overridden; omitted params keep the report's saved defaults. Ignored for non-SQL reports. Different from `--filters`: see the SQL report dynamic parameters section below. |
-
-## SQL report dynamic parameters (`--sql_params`)
-- Applies ONLY to SQL-model reports (`reportModel: sql` in `+get_report_definition`). Such reports may embed `${...}` placeholders of 6 paramTypes — `Variable`, `PartDate`, `Time`, `Number`, `Text`, `Selector` — whose default values are saved in the report's `eventView.sqlViewParams`.
-- `--sql_params` overrides those values by `paramName`; the backend merges them into the report's `sqlViewParams` before running the SQL. Omitting `--sql_params` keeps the report defaults (backward compatible).
-- `--sql_params` is NOT the same as `--filters`: `--filters` adds a post-query WHERE filter on the SQL result columns (using real field names), while `--sql_params` changes the report's own dynamic parameters before the SQL runs. To adjust a report's selectors/time parameters, use `--sql_params`, not `--filters`.
-- Workflow: `+get_report_definition` -> read `events.sqlVoParams` (each param's `paramName`, `paramType`, and for Selector the allowed `selectorItems` names) -> build the override array -> `+query_report_data --sql_params '[...]'`.
-- Override shape by `paramType` (read each param's current `quota`/`paramExpress`/`startTime`/`endTime` and the VO's `variableType`/`selectorItems` from `+get_report_definition`):
-  - `Selector` — `{"paramName":"selector1","paramExpress":"<selectorName>"}`; `<selectorName>` must be one of the VO's `selectorItems`. No `quota`.
-  - `Variable` — no `quota`; override `paramExpress` only. Quoting depends on the VO's `variableType`: a custom (`Normal`) variable is substituted verbatim, so include the quotes exactly as shown in the definition (e.g. `"paramExpress":"'2025-12-31'"`); a `TimeSelect` variable takes a bare value (the backend quotes it). `variableType` itself is a report-design property in `events.sqlVoParams` and is NOT changed by `--sql_params` (only the value is); the resulting SQL is the same regardless of `variableType` as long as the value is supplied with the right quoting.
-  - `Text` — `quota` (operator) + `paramExpress`; supports all 12 operators in the table below. Setting only `paramExpress` while leaving the no-value default `quota` (e.g. `C04`) does NOT filter.
-  - `Number` — `quota` (operator) + `paramExpress`; 9 numeric operators: `C00` IN / `C01` NOT IN / `C06` BETWEEN (array); `C02` < / `C03` > / `C020` <= / `C030` >= (single, numeric string); `C04` IS NOT NULL / `C05` IS NULL (no value). No LIKE/CONTAIN for numbers. E.g. `{"paramName":"num1","quota":"C06","paramExpress":["10","20"]}`.
-  - `Time` — `quota` (operator) + time fields (NOT recentDay): `C020` <= (uses `endTime`) / `C030` >= (uses `startTime`) / `C06` BETWEEN by datetime (`startTime`+`endTime`) / `C060` BETWEEN by date (`startTime`+`endTime`) / `C04` IS NOT NULL / `C05` IS NULL (no value). To only change the range keep the report's range `quota` and set `startTime`+`endTime`; to change the operator also set `quota`.
-  - `PartDate` — a date range; set `startTime`+`endTime`: `{"paramName":"date1","startTime":"yyyy-MM-dd HH:mm:ss","endTime":"yyyy-MM-dd HH:mm:ss"}`.
-
-  `quota` operators (Text = all; Number = the non-LIKE subset; Time = comparison/range/null subset using time fields):
-
-  | quota | operator | value |
-  |---|---|---|
-  | `C00` | IN | array `paramExpress` |
-  | `C01` | NOT IN | array `paramExpress` |
-  | `C06` | BETWEEN / 区间 | array `[min,max]` (Time: `startTime`+`endTime`) |
-  | `C060` | BETWEEN by date / 日期区间 (Time only) | `startTime`+`endTime` |
-  | `C02` / `C03` | `<` / `>` | single `paramExpress` |
-  | `C020` / `C030` | `<=` / `>=` | single `paramExpress` (Time: `endTime` / `startTime`) |
-  | `C30` / `C31` | LIKE / NOT LIKE (Text only) | single `paramExpress` |
-  | `C300` | CONTAIN (`LIKE '%v%'`, Text only) | single `paramExpress` |
-  | `C04` / `C05` | IS NOT NULL / IS NULL | no value (`C04` empty default = no filter) |
-
-- An unknown `paramName` (not present in the report) or malformed JSON returns an error.
-
-## Decision Rules
-- `filters` / `group_by` 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, include all required parameters (`--project_id`, `--report_ids`, `--request_id`) and add optional parameters after confirming the chain works.
-- Generate and pass `--request_id` before starting any cancelable query; it is required. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. Omitted or blank IDs return `REQUEST_ID_REQUIRED`; invalid format returns `INVALID_REQUEST_ID`.
-- Wrap JSON parameters in single quotes (for example `--report_ids '{}'`, `--filters '{}'`) 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`, `--report_ids`, `--request_id`).
-- If `Invalid JSON` appears, first check the required schema fields, then verify that the event name/property name comes from metadata queried in the same `project_id`.
-- If the query times out or the result is abnormal, first reduce the time range/grouping dimensions, then split the query to locate the issue.
-
-## Recommended Chaining
-- +get_filter_schema -> +get_groupby_schema -> analysis_meta +list_events -> analysis_meta +list_properties -> +query_report_data
-- (SQL-model report, override dynamic params) +get_report_definition -> +query_report_data --sql_params '[...]'
-- +list_reports -> +get_report_definition -> +query_report_data

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

@@ -1,31 +0,0 @@
-# analysis_audience +refresh_cluster (Trigger Cluster Recompute)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Cluster Management**
-
-## Use Cases
-- Trigger cluster recomputation and submit an asynchronous refresh task.
-
-## Commands
-```bash
-ae-cli analysis_audience +refresh_cluster --project_id <project_id> --cluster_name demo
-ae-cli analysis_audience +refresh_cluster --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--cluster_name` | Yes | Cluster name |
-
-## Decision Rules
-- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`) and add optional parameters after confirming the path works.
-- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep confirmation prompts by default; for automation scenarios, reevaluate whether to use `--yes`.
-
-## Next Step on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`).
-
-## Recommended Chain
-- +list_clusters -> +get_clusters_by_name -> +update_cluster

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

@@ -1,31 +0,0 @@
-# analysis_audience +refresh_tag (Trigger Tag Recompute)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Tag Management**
-
-## Use Cases
-- Trigger tag recomputation and submit an asynchronous refresh task.
-
-## Commands
-```bash
-ae-cli analysis_audience +refresh_tag --project_id <project_id> --tag_name demo
-ae-cli analysis_audience +refresh_tag --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--tag_name` | Yes | Tag name |
-
-## Decision Rules
-- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--tag_name`) and add optional parameters after confirming the path works.
-- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep confirmation prompts by default; for automation scenarios, reevaluate whether to use `--yes`.
-
-## Next Step on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--tag_name`).
-
-## Recommended Chain
-- +list_tags -> +get_tags_by_name -> +update_tag

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

@@ -1,24 +0,0 @@
-# analysis-meta super-metadata import
-
-Use when the user needs to pre-import and confirm-import super event and super property configuration.
-
-Do not use this command for unrelated analysis queries, ad-hoc query construction, or MCP metadata discovery when an existing specialized command already fits the user's request.
-
-Command:
-
-```bash
-ae-cli analysis-meta super-metadata import --project-id <project_id> --payload '{}'
-ae-cli analysis-meta super-metadata import --dry-run
-```
-
-Capability id: `metadata.super_metadata.import`.
-
-Input sends `project_id`, `payload`.
-
-Output is the gateway envelope. `data` contains the common-service capability result.
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` | Yes | Numeric project ID. |
-| `--payload` | No | Optional capability payload JSON. |

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

@@ -1,61 +0,0 @@
-# analysis_audience +update_cluster (Update Cluster)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Cluster Management**
-
-## Use Cases
-- Prerequisite helper: first call `+get_cluster_definition_schema` to get the structure, then supplement it with the project's real metadata (events and properties).
-- When updating `definition`, metadata must be verified in the same session and `project_id`: first definition update in this session must call `analysis_meta +list_events` and `analysis_meta +list_properties`; later updates should reuse session-verified results first.
-- Update a user cluster definition. Supports updating the display name, remark, type, or definition. Updating only the display name or remark does not trigger recomputation.
-
-## Required Prerequisites (MUST only when updating definition)
-- If this request includes `--definition`, 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 submit a new `definition` until the above docs have been read and metadata has been verified: first definition update in this session for the same `project_id` must run metadata commands; if session-verified metadata already exists, reuse it first.
-
-## Prerequisite Call Chain (run only when updating definition)
-1. First determine `--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 obtain the structure progressively. Start with base mode; request `examples` only if base is insufficient; request `full` only for complex, ambiguous, or repeatedly failing definition updates.
-3. Read `list_events.md`. If this is the first definition update in the current session for this `project_id` (or metadata is not yet verified), call `ae-cli analysis_meta +list_events --project_id <project_id>`; otherwise, reuse the session-verified event metadata first.
-4. Read `list_properties.md`. If this is the first definition update in the current session for this `project_id` (or metadata is not yet verified), call `ae-cli analysis_meta +list_properties --project_id <project_id>`; otherwise, reuse the session-verified property metadata first.
-5. Build the new `definition` based on the schema + metadata, then run `+update_cluster`.
-
-## Commands
-```bash
-ae-cli analysis_audience +update_cluster --project_id <project_id> --cluster_name demo --display_name "Demo v2"
-ae-cli analysis_audience +update_cluster --project_id <project_id> --cluster_name demo --type condition --definition '{}' --zone_offset 8
-ae-cli analysis_audience +update_cluster --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--cluster_name` | Yes | Cluster name |
-| `--display_name` | No | New cluster display name. Length: 1-80 |
-| `--remark` | No | New cluster remark |
-| `--type` | No | New cluster type. Supported values: condition and sql. It is recommended to provide this when updating the definition. |
-| `--definition` | No | New cluster definition JSON. If provided, MUST call `+get_cluster_definition_schema` first, then fill valid event/property names from metadata verified in the same `project_id` (first definition update queries `analysis_meta` metadata commands; later updates in the same session should reuse verified results first). |
-| `--zone_offset` | No | Optional time zone offset for cluster computation. Valid range: -12 to 14 (supports decimals like 5.5). |
-
-## Decision Rules
-- If you are not updating `definition` (only updating `display_name`/`remark`), you can skip the schema and metadata prerequisite chain.
-- When updating `definition`, it cannot be written from experience alone; it must satisfy both the schema structure and the project's real metadata.
-- Use progressive schema loading: base first, examples only when needed, full only as a last resort. Do not request full schema for simple cluster updates when the intent is clear.
-- Before calling `list_events` / `list_properties`, you must first read the corresponding reference docs. Query metadata on the first definition update in this session for the same `project_id`; after that, prefer reusing session-verified metadata.
-- For the first execution, it is recommended to pass only the required parameters (`--project_id`, `--cluster_name`) and add optional parameters after confirming the path works.
-- Wrap JSON parameters in single quotes (e.g. `--definition '{}'`) to avoid shell escaping issues.
-- When troubleshooting across projects, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep confirmation prompts by default; for automation scenarios, reevaluate whether to use `--yes`.
-
-## Next Step on Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill the gap (focus on `--project_id`, `--cluster_name`).
-- If `Invalid JSON` appears, first check whether a schema-required field is missing, then verify whether event/property names come from the same `project_id`'s metadata query results.
-- If the result after writing is not as expected, immediately re-read the corresponding list/get interfaces and compare before and after.
-
-## Recommended Chain
-- +get_cluster_definition_schema -> (first definition update or refresh) analysis_meta +list_events -> analysis_meta +list_properties -> +update_cluster
-- +list_clusters -> +get_clusters_by_name -> +update_cluster

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

@@ -1,45 +0,0 @@
-# analysis +update_dashboard (update dashboard)
-
-> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
-
-Domain: **Dashboard Management**
-
-## Use Cases
-- Update dashboard metadata. Supports three operations (all optional):
-- (1) Rename dashboard
-- (2) Add associated reports (append mode)
-- (3) Replace share members (full replacement mode)
-- Important constraints:
-- Before replacing share members: call query_dashboard_detail first
-- When managing members: call list_project_users to get valid userId mappings
-- Update dashboard metadata.
-
-## Commands
-```bash
-ae-cli analysis +update_dashboard --project_id <project_id> --dashboard_id 1
-ae-cli analysis +update_dashboard --project_id <project_id> --dashboard_id 1 --dashboard_name demo --report_ids '[1001]' --member_authorities '{"1001":"READ"}'
-ae-cli analysis +update_dashboard --dry-run
-```
-
-## Parameters
-| Parameter | Required | Description |
-|---|---|---|
-| `--project_id` / `-p` | Yes | Project ID |
-| `--dashboard_id` / `-d` | Yes | Dashboard ID |
-| `--dashboard_name` | No | New dashboard name. If provided, updates the dashboard name. |
-| `--report_ids` | No | List of report IDs to associate with the dashboard. Reports not already associated will be added (append mode, not a full replacement). |
-| `--member_authorities` | No | Map of member userId to permissions (READ, EDIT, MAINTAIN). Full replacement mode — existing members not in this map will be removed. |
-
-## Decision Rules
-- For the first run, it is recommended to pass only the required parameters (`--project_id`, `--dashboard_id`) and add optional parameters after confirming the chain works.
-- Wrap JSON parameters in single quotes (for example `--report_ids '{}'`, `--member_authorities '{}'`) to avoid shell escaping issues.
-- For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
-- Write operations keep the confirmation prompt by default; evaluate whether to use `--yes` only for automation scenarios.
-
-## Next Step After Failure
-- If required parameters are missing, fall back to the smallest runnable command and fill them in (focus on `--project_id`, `--dashboard_id`).
-- If `Invalid JSON` appears, first validate with the smallest JSON structure (for example `{}` or `[]`), then add fields gradually.
-- If the result after writing is not as expected, immediately reread the corresponding list/get interface and compare before and after.
-
-## Recommended Chaining
-- +list_dashboards -> +query_dashboard_detail -> +query_dashboard_report_data