@thinkingai/ae-cli 6.0.33 → 6.0.35

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

@@ -2,7 +2,7 @@
 
 Use to cancel an async capability-gateway query or export by `run_id`.
 
-Do not use for MCP query cancellation by `request_id`; use `analysis +cancel_query`.
+This is the only analysis-query cancellation command exposed by ae-cli. Cancellation is bound to the capability-gateway `run_id`; ae-cli does not expose MCP `request_id` cancellation.
 
 Command:
 
@@ -13,3 +13,5 @@ ae-cli analysis query cancel --run-id <run_id> [--reason <reason>]
 Input sends `run_id` and optional `reason`.
 
 Output is the gateway envelope. `data` contains the cancellation result.
+
+Typical workflow: submit an async export, preserve its `run_id`, inspect that run, and call this command only when that same run no longer needs to continue. Do not substitute a lifecycle `request_id` for `run_id`.

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

@@ -0,0 +1,34 @@
+# analysis query-cluster list
+
+List physical query-routing clusters accessible to the current account in one project.
+
+## Terminology boundary
+
+Both product concepts contain the English word `cluster`, but they are different:
+
+- 查询集群 / 数据集群 / 部署集群: physical data-routing locations used by `GLOBAL` and `SLAVE`. This command lists these.
+- 用户分群 / 人群包: saved user-membership assets. Use `analysis user-cluster list` for these.
+
+Never use a 用户分群 ID as `--slave-cluster-id`, and never answer a user-segment inventory question with this command.
+
+## Purpose
+
+Use this capability before routing a report, dashboard, or ad-hoc query when the request mentions all clusters, a country/region, a game server, shard, site, market, or deployment. Do not call it for ordinary queries with no physical routing intent; omission preserves the query surface's documented default.
+
+## Command
+
+```bash
+ae-cli analysis query-cluster list --project-id <project_id>
+```
+
+The snake_case output contains `current_cluster`, accessible `slave_clusters`, and `permissions.allowed_cluster_query_params`. `permissions.can_query_global` is authoritative for `GLOBAL`; only returned `slave_clusters[].cluster_id` values may be used for `SLAVE`.
+
+## Typical workflow
+
+1. Resolve the project and call `analysis query-cluster list`.
+2. Match an explicit region/server request only against returned cluster ID, name, and description.
+3. Use `--cluster-query-scope GLOBAL` only for explicit cross-cluster aggregation, or use `--cluster-query-scope SLAVE --slave-cluster-id <id>` for one matched physical slave cluster.
+4. Run/export through `report-data`, `dashboard-report-data`, or `adhoc`.
+5. For synchronous runs, verify `actual_cluster_query_scope`, `actual_slave_cluster_id`, and `cluster_query_scope_source` in the result. For exports, verify the submitted route and successful run before consuming the artifact; report-data artifacts contain report rows rather than route metadata. If permissions reject the route, report `allowed_cluster_query_params`; do not fall back silently.
+
+Surface defaults differ: report-data and ad-hoc omit scope to query the current self cluster; dashboard-report-data omits scope to follow the saved dashboard configuration.

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

@@ -8,6 +8,7 @@ Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md) first. T
 
 ```bash
 ae-cli analysis query create-result-cluster \
+  --project-id <project_id> \
   --query-context-id <sync_preview_query_context_id> \
   [--source '{"report_id":1001}'] \
   --coordinate '<merged returned row/column/metric coordinate>' \
@@ -19,6 +20,7 @@ ae-cli analysis query create-result-cluster \
 
 ## Input rules
 
+- `--project-id` must be the project used by the synchronous preview and must match the project stored by `query_context_id`.
 - `--query-context-id`, `--source`, and all coordinate fragments must come from the same synchronous `adhoc run`, `report-data run`, or `dashboard-report-data run` response.
 - Match the desired visible row and column in `source.drilldown.row_options`/`column_options`, select the correct metric option, and shallow-merge only their `coordinate` fragments.
 - Never pass `target_id`, raw QP, display-only dates, option presentation fields, or data from an export/download. Exports do not create query contexts.

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

@@ -16,14 +16,18 @@ Input sends `project_id`, `report_name`, `model_type`, `definition`, optional `r
 
 Output is the gateway envelope. `data` contains the created `report_id`, creation status, normalized `model_type`, AI QP `definition`, and optional resolution warnings.
 
+Report creation and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. No report is created on this failure; select an exact returned candidate or ask the user before retrying.
+
 ## SQL dynamic parameter shortest path
 
 When a SQL report contains a `${...}` placeholder, define its saved default in the same AI-facing `definition`. Example:
 
 ```bash
-ae-cli analysis report create --project-id <project_id> --report-name "Recent SQL" --model-type sql --definition '{"sql":"select * from events where ${PartDate:ds} limit 100","params":[{"name":"ds","type":"part_date","recent_day":"1-7"}]}'
+ae-cli analysis report create --project-id <project_id> --report-name "Recent SQL" --model-type sql --definition '{"sql":"select * from events where ${PartDate:ds} limit 100","params":[{"name":"ds","type":"part_date","recent_day":"1-7","use_timezone":true}]}'
 ```
 
+`use_timezone` is an optional boolean definition field only for `part_date`; it defaults to `false`. `true` makes that parameter use the query's effective timezone. It is a saved definition field, so change it through report create/update `--definition`, never through report-data `--sql-params`.
+
 After creation, keep the `report_id` returned by this exact create response. To verify the report, query the saved default first with `analysis report-data run` and omit `--sql-params`; then make one second query with a value-only `--sql-params` override. Do not rebuild internal `sqlViewParams` or guess an ID.
 
 After any successful report create, call `analysis-meta asset url-get` with that returned `report_id` and output its `markdown_link`.

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

@@ -2,6 +2,8 @@
 
 Submit saved report data as a downloadable async artifact. It covers the 12 analysis report models from `ai_models.md` plus tag report data; tags are report-data only and are not ad-hoc `model_type` values.
 
+Typical closed loop: verify saved report definition -> resolve exact filter values and physical query route when needed -> submit export -> preserve the returned run/artifact pair -> inspect to a successful terminal state -> download and verify artifact content.
+
 Before adding overrides, call `analysis report get` for every report. The model matrix is the same as `report-data run`: SQL accepts only saved `definition.params` names through `--sql-params`; non-SQL analysis models accept filters/group/time overrides; tag executes its saved definition. Never put generic overrides and `--sql-params` in one homogeneous-model request.
 
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `export` command instead of `report-data run`.
@@ -16,9 +18,14 @@ ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001
 
 # SQL report
 ae-cli analysis report-data export --project-id <project_id> --report-ids '[2001]' --sql-params '[{"name":"platform","value":"ios"}]' --artifact-format jsonl
+
+# Global cross-cluster export for a supported non-SQL report
+ae-cli analysis report-data export --project-id <project_id> --report-ids '[1001]' --cluster-query-scope GLOBAL --artifact-format jsonl
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, artifact `format`, and `timeout_seconds`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Resolve allowed physical routes with `analysis query-cluster list`; SQL reports reject `GLOBAL`. Async export has no inline row limit. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`.
+
+The downloaded report-data artifact contains report rows and per-report markers, not `actual_cluster_query_scope` metadata. Therefore resolve an allowed route first, keep the submitted scope/ID with the run record, and do not infer route from row contents.
 
 Timezone contract is identical to `report-data run`: omit `--zone-offset` to match the current user's report UI timezone (falling back to the project default); use an enabled integer from `-12` through `14` for a fixed UTC offset; use `--zone-offset 99` for local-time mode, where rows are not converted to one fixed UTC offset. `99` is a mode identifier, not `UTC+99`, and the option is not persisted.
 
@@ -26,7 +33,7 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; every name must exist in every target SQL report's `definition.params`. Time fields require a saved `part_date` or time parameter. Send only override values; do not send definition fields such as `type`, `options`, or `use_timezone`.
 
 Mixed-model export batches are best-effort rather than rejected only for being mixed. Prefer one model per overridden export because artifact formats cannot surface submission-time warnings as prominently as inline `meta.warnings`.
 

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

@@ -2,6 +2,8 @@
 
 Execute bounded inline data from one or more saved reports.
 
+Typical closed loop: discover a saved report -> verify its definition -> resolve any unknown exact filter value with `analysis filter-value list` -> optionally resolve a physical route with `analysis query-cluster list` -> run -> inspect actual scope and warnings -> use the returned synchronous query context for drilldown.
+
 Routing: read [`analysis_data_retrieval.md`](analysis_data_retrieval.md) before choosing this `run` command instead of `report-data export`.
 
 Do not use this command for full, unknown-size, larger than 1000-row, or long-running report data; use `report-data export`.
@@ -27,9 +29,12 @@ ae-cli analysis report-data run --project-id <project_id> --report-ids '[2001]'
 
 # Explicit local-time mode (not UTC+99)
 ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --zone-offset 99 --limit 20
+
+# One physical slave query cluster
+ae-cli analysis report-data run --project-id <project_id> --report-ids '[1001]' --cluster-query-scope SLAVE --slave-cluster-id jp --limit 20
 ```
 
-Input sends `project_id`, `report_ids`, optional `request_id`, `filters`, `group_by`, `sql_params`, `start_time`, `end_time`, `time_granularity`, `zone_offset`, `use_cache`, `limit`, and `timeout_seconds`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180. The routing rule lives in [`analysis_data_retrieval.md`](analysis_data_retrieval.md).
+Input also accepts optional `cluster_query_scope` and conditional `slave_cluster_id`. Omit both for current-self data. Use `GLOBAL` only for explicit cross-cluster aggregation; use `SLAVE` with exactly one ID returned by `analysis query-cluster list`. SQL reports reject `GLOBAL`. Control defaults: `--limit` default 100 / max 1000, `--timeout-seconds` default 120 / max 180.
 
 Timezone contract:
 
@@ -42,7 +47,7 @@ Override model:
 
 - `filters`: AI-facing intent object `{relation:"and|or", items:[{field:{name,type?}, operator, values?}]}`. `field.type` supports `event_property`, `user_property`, `cluster`, and `tag`; omit it only when the field name is unambiguous. Use field names from `analysis report get` definition output or metadata commands. Do not pass raw QP fields such as `taFilters`, `junctionKind`, `columnName`, `tableType`, or `selectType`.
 - `group-by`: AI-facing intent array `[{field:{name,type?}}]`. Use the same field model as report definitions. Do not pass raw `TaGroupByVo`. Time granularity is controlled by `--time-granularity`, not by `--group-by`.
-- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields.
+- `sql-params`: SQL report dynamic parameter value overrides. First read `analysis report get`; saved SQL params are exposed as AI-facing `definition.params`. Every name must exist in every target SQL report because one batch shares the override. Send only override values for existing parameter names: `[{"name":"platform","value":"ios"}]`, `[{"name":"server_id","operator":"contains","value":"s1"}]`, `[{"name":"level","operator":"eq","values":["42"]}]`, `[{"name":"amount","operator":"between","values":["10","20"]}]`, `[{"name":"part_date","start_time":"2026-07-01 00:00:00","end_time":"2026-07-09 23:59:59"}]`, or `[{"name":"part_date","recent_day":"1-7"}]`. Time fields require a saved `part_date` or time parameter. Operators `eq`/`in`, `neq`/`not_in`, and `between` use `values`; comparison/like/contains operators use single `value`. Do not send definition fields such as `type`, `options`, or `use_timezone`; change them through report update.
 
 A homogeneous SQL request that includes `filters`, `group_by`, `start_time`, `end_time`, or `time_granularity` fails with `INVALID_OVERRIDE_FOR_MODEL`. A homogeneous non-SQL request with `sql_params` also fails. Mixed-model batches are best-effort: data still returns and `meta.warnings[]` uses `OVERRIDE_IGNORED_FOR_MODEL`, `model_type`, `report_ids`, and `ignored_fields` to identify fields that did not apply. Do not discard these warnings.
 
@@ -50,6 +55,6 @@ For a newly created or updated dynamic SQL report, omit `--sql-params` to execut
 
 Output is the gateway envelope. `data` contains bounded inline report result items plus `query_context_id` and `sources[]`. Each source includes `effective_zone_offset`, the timezone value actually used for that query. When `zone_offset` is omitted, this is the resolved current-user timezone when available, otherwise the project default; when `zone_offset` is explicit, this is its resolved effective value. `sources[].drilldown` is present when the returned preview exposes follow-up actions. Each source is evaluated independently; SQL and other unsupported models have no actions.
 
-An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error. Mixed batches keep successful items and return `meta.partial`, counts, and per-report `meta.failures` for partial-result handling.
+`meta.actual_cluster_query_scope`, optional `meta.actual_slave_cluster_id`, and `meta.cluster_query_scope_source` describe the actual physical route. Verify them before comparing or drilling down. An empty batch or report result with no rows is a successful query: it means the requested time range has no data. The command fails only when every returned report entry contains an explicit execution error.
 
 Read [`analysis_drilldown_contract.md`](analysis_drilldown_contract.md). Select only returned row/column/metric options and call only the advertised event, entity, or result-cluster action. Do not pass raw QP.

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

@@ -12,12 +12,14 @@ ae-cli analysis report get --project-id <project_id> --report-id <report_id>
 
 Input sends `project_id` and `report_id`.
 
+This command reads saved definition metadata and deliberately has no `--use-cache` option. Cache selection applies to `report-data run/export`, not to definition reads.
+
 Output is the gateway envelope. `data` contains `version`, `model_type`, `definition`, report metadata, and dashboard membership in snake_case. Use `data.version` as `--report-version` when updating the same report. Raw frontend `events`, `event_view`, `visual_view`, and raw QP are not returned.
 
 For a saved non-SQL report with a time granularity, `data.definition` returns the agent-facing `time_particle_size` spelling, such as `day`, `hour`, or `total`; internal `T0` through `T9` codes must never leak. If `time_particle_size` is absent, the saved definition has no readable granularity. Do not infer a granularity from the number of result rows; execute the saved report as-is or use an explicit ad-hoc definition when the user requires a specific granularity.
 
 This read is mandatory before applying report-data overrides. Branch on `data.model_type`:
 
-- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter.
+- `sql`: only `--sql-params` is valid. Every override name must already exist in `data.definition.params`; time values may be overridden only through a saved `part_date` or time parameter. A saved PartDate definition exposes boolean `use_timezone` (default `false`); it is definition metadata and cannot be overridden by report-data.
 - non-SQL analysis models: use `--filters`, `--group-by`, `--start-time`, `--end-time`, or `--time-granularity`; do not send `--sql-params`.
 - `tag`: report-data executes the saved tag definition. For a different tag view, use `analysis history-tag-data run/export`.

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

@@ -17,6 +17,10 @@ Input sends `project_id`, `report_id`, `version` from CLI `--report-version`, an
 
 Output is the gateway envelope. `data` contains update status, `report_id`, and the normalized AI QP definition when a definition was updated.
 
+When a definition is supplied, update and its `--validate` / `--dry-run` paths use the same compiler contract. `AI_QP_COMPILE_FAILED` preserves `meta.compile_status`, full `meta.errors[]` (including `code`, `candidates`, and `suggestions`), `meta.resolved`, and `meta.warnings`. The report is not changed on this failure; resolve the ambiguity before retrying.
+
 For the shortest safe update, read the current `version` exactly once with `analysis report get` immediately before the write; do not reuse a version from an older list or conversation turn. If a SQL dynamic parameter definition changed, query the saved default before applying an override so default persistence and override behavior are verified separately.
 
+For a SQL `part_date` parameter, `use_timezone` is a boolean saved definition field with default `false`. Change it only by submitting the complete updated `definition`; report-data `--sql-params` is value-only and must not contain `use_timezone`.
+
 After a successful update, call `analysis-meta asset url-get` with the updated `report_id` and output its `markdown_link`.

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

@@ -9,9 +9,9 @@ Before constructing `--events` / `--filter`, validate the available events and p
 Command:
 
 ```bash
-ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"eventName":"purchase"}]'
-ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"eventName":"add_to_cart"}]' --filter '{}' --override true
-ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo --event-desc demo --events '[{"event_name":"purchase"}]'
+ae-cli analysis-meta virtual-event create --project-id <project_id> --event-name ta@demo2 --event-desc demo --remark demo --events '[{"event_name":"add_to_cart","filter":{"relation":"and","items":[{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}]' --override true
+ae-cli analysis-meta virtual-event create --project-id <project_id> --override false --payload '{"event_name":"ta@qualified_purchase","event_desc":"Qualified purchase","rule":{"events":[...],"filter":{...}}}'
 ae-cli analysis-meta virtual-event create --dry-run
 ```
 
@@ -19,7 +19,7 @@ Capability id: `metadata.virtual_event.create`.
 
 Input sends `project_id`, `override`, and `payload`. When typed flags are used, ae-cli builds `payload` from `event_name`, `event_desc`, `remark`, and `rule.events/filter`.
 
-Output is a successful gateway envelope with no business data. Read back with `virtual-event get` when the created event ID is known.
+Output data contains `v_event_id` and `event_name`. Use the returned `v_event_id` for `virtual-event get` or `virtual-event delete`.
 
 ## Parameters
 | Parameter | Required | Description |
@@ -30,11 +30,12 @@ Output is a successful gateway envelope with no business data. Read back with `v
 | `--event-name` | No | Virtual event name. Must start with `ta@`. Required when `--payload` is omitted. |
 | `--event-desc` | No | Virtual event display name. Required when `--payload` is omitted. |
 | `--remark` | No | Optional virtual event remark. |
-| `--events` | No | JSON array of events to combine. Required when `--payload` is omitted. |
-| `--filter` | No | Optional global filter JSON. Referenced properties must come from `analysis-meta property list`. |
+| `--events` | No | JSON array of `{event_name,event_desc?,filter?}`. Each filter uses `{relation:'and|or',items:[{field:{name,type?},operator,values?}]}`. Required when `--payload` is omitted. |
+| `--filter` | No | Optional global AI-facing filter with the same `relation/items` shape. Raw `taFilters`, `junctionKind`, and `calcuSymbol` are rejected. Referenced properties must come from `analysis-meta property list`. |
 
 ## Decision Rules
 - `events` / `filter` must not be handwritten by intuition alone; they must match real metadata in the same project.
+- Use snake_case `event_name`; do not pass the legacy `eventName` spelling.
 - Before calling `event list` / `property list`, read the corresponding reference documents.
 - For first validation, pass only required typed parameters: `--project-id`, `--event-name`, `--event-desc`, and `--events`.
 - Use `--payload` only when an exact virtual-event rule DTO is already available.

package/skills/ae-analysis-global/SKILL.md

@@ -1,53 +1,36 @@
 ---
 name: ae-analysis-global
 version: 1.0.0
-description: "Use when AE/TE analysis requests mention query/current/service/deployment clusters, current cluster (当前集群), cluster info (集群信息/有哪些集群), global or multi-cluster data, all clusters/all servers, GLOBAL/SLAVE, list_query_clusters, cluster_query_scope, slave_cluster_id, country/region/server/shard/site/market routing, sw_cfg_enable_global_query, or when cluster may mean query cluster rather than audience/user segment."
+description: "Use when AE/TE analysis requests mention query/current/service/deployment clusters, current cluster (当前集群), cluster info (集群信息/有哪些集群), global or multi-cluster data, all clusters/all servers, GLOBAL/SLAVE, query-cluster, cluster_query_scope, slave_cluster_id, country/region/server/shard/site/market routing, or when cluster may mean query cluster rather than audience/user segment."
 ---
 
 # ae-analysis-global
 
 
-Load this skill based on user intent first. After loading, run `ae-cli config cluster-mode status`; the status gates whether these overlay rules apply, not whether this skill should be loaded.
+This is a terminology and routing overlay for `ae-analysis`. Read the base command reference [`../ae-analysis/references/query_cluster_list.md`](../ae-analysis/references/query_cluster_list.md) before composing the inventory command. Server output, not a local CLI feature switch, is authoritative for whether global query is enabled and which routes the account may use.
 
-This is an overlay for `ae-analysis`. First use the normal `ae-analysis` rules and matching command references. Apply the rules below only when local multi-cluster mode is enabled (`ae-cli config cluster-mode status`):
-
-```bash
-ae-cli config cluster-mode status
-```
-
-The result must contain:
-
-```json
-{"sw_cfg_enable_global_query": true}
-```
-
-If the mode is not enabled, do not use this overlay.
-
-For commands added only by this overlay, read this skill's matching reference file before composing commands. Example: `+list_query_clusters` -> `references/list_query_clusters.md`.
-
-Every command accepts `--host <url>` to override the active AE host, and it may be placed after the subcommand (e.g. `ae-cli analysis +list_query_clusters --project_id <id> --host <url>`). Host selection is independent of `--cluster_query_scope`: `--host` chooses which AE instance to call, while `--cluster_query_scope` / `--slave_cluster_id` choose which cluster within global mode.
+Every command accepts `--host <url>` to override the active AE host. Host selection is independent of `--cluster-query-scope`: `--host` chooses the AE instance, while `--cluster-query-scope` / `--slave-cluster-id` choose a physical query route inside that instance.
 
 **CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, open the user reply with a short ⚠️ version warning and **quote the `npm i -g` / `npx skills add` (or update-cluster) lines verbatim**, then present the business result. Soft tip; `ok: true` can still carry the notice. (Also covered by `ae-analysis` Global Rules when both skills are loaded.)
 
 ## Routing Rules
 
-- In this overlay, **query cluster / service cluster / deployment cluster** means multi-cluster routing for analysis queries. **audience/user segment cluster** means user membership assets under `analysis user-cluster`.
-- If the user asks for cluster inventory or cluster info, call `ae-cli analysis +list_query_clusters --project_id <project_id>`. Localized examples include "集群信息" and "有哪些集群".
+- In this overlay, **查询集群 / 数据集群 / 部署集群** means physical multi-cluster routing for analysis queries. **用户分群 / 人群包** means user-membership assets under `analysis user-cluster`.
+- If the user asks for query-cluster inventory or cluster info, call `ae-cli analysis query-cluster list --project-id <project_id>`. Localized examples include "查询集群信息" and "有哪些数据集群".
 - Do not answer query-cluster inventory questions with `ae-cli analysis user-cluster list` unless the user explicitly asks for audience clusters, cohorts, segments, user membership, or cluster definitions.
-- If the user mentions country, region, server, shard, site, market, or deployment area semantics, call `ae-cli analysis +list_query_clusters --project_id <project_id>` before choosing query scope.
-- Match slave cluster intent only against `slaveClusters[].clusterId`, `slaveClusters[].clusterName`, and `slaveClusters[].clusterDesc` returned by `+list_query_clusters`.
-- Unified ad-hoc gateway commands (`analysis adhoc run/export`) do not expose `cluster_query_scope`. If the user explicitly needs global/slave ad-hoc analysis, state that the new ad-hoc gateway contract does not support cluster routing yet and stop instead of adding hidden flags or removed ad-hoc commands.
-- Report/dashboard data gateway commands (`analysis report-data run/export`, `analysis dashboard-report-data run/export`) also do not expose `cluster_query_scope`; do not add hidden cluster flags to them.
-- Use `--cluster_query_scope GLOBAL` only when the user clearly asks for global, all clusters, all servers, or cross-cluster aggregated data, and `permissions.canQueryGlobal=true`.
-- If the user does not express global or slave-cluster intent, omit `--cluster_query_scope`.
-- If requested global/slave scope is not allowed, explain `permissions.allowedClusterQueryParams` instead of guessing forbidden parameters.
-- For SQL model analysis, never pass `cluster_query_scope`; SQL model analysis only supports the current self cluster in the current gateway contract.
+- If the user mentions country, region, server, shard, site, market, or deployment area semantics, call `analysis query-cluster list` before choosing query scope.
+- Match slave intent only against returned `slave_clusters[].cluster_id`, `cluster_name`, and `cluster_desc`.
+- Report-data, dashboard-report-data, and ad-hoc run/export expose `--cluster-query-scope GLOBAL|SLAVE`; `SLAVE` requires `--slave-cluster-id`.
+- Use `GLOBAL` only when the user clearly asks for all clusters/servers or cross-cluster aggregation and `permissions.can_query_global=true`.
+- If the user does not express global or slave-cluster intent, omit the flag. Report/ad-hoc then use current self; dashboard follows its saved configuration.
+- If a requested route is not allowed, explain `permissions.allowed_cluster_query_params` instead of silently falling back.
+- SQL and attribution ad-hoc analysis do not support `GLOBAL`; SQL report/dashboard data also reject effective `GLOBAL`. Use an allowed `SLAVE` or current-self route.
 
 ## Response Wording
 
-- For `+list_query_clusters`, call the result "query clusters" and summarize `currentCluster`, `slaveClusters`, and `permissions.allowedClusterQueryParams`.
+- For `analysis query-cluster list`, call the result "查询集群" or "query clusters" and summarize `current_cluster`, `slave_clusters`, and `permissions.allowed_cluster_query_params`.
 - For `analysis user-cluster list`, call the result "audience clusters" or "user segments"; do not call those results query clusters.
 
-## Commands Added By Multi-Cluster Mode
+## Query-cluster command
 
-- `ae-cli analysis +list_query_clusters --project_id <project_id>`
+- `ae-cli analysis query-cluster list --project-id <project_id>`

package/skills/ae-community/SKILL.md

@@ -42,7 +42,7 @@ Safety constraints:
 - 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 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.
 
-**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), `analysis_common` (common), `operation` (operations).
+**Community** commands use the domain `community` (this skill). Other AE domains include: `analysis` (analysis and audience), `analysis_meta` (metadata), and `operation` (operations).
 
 ---
 

package/skills/ae-data-integration-helper/SKILL.md

@@ -25,7 +25,7 @@ description: "Answers questions about ThinkingData SDK integration and usage, in
 | 事件格式 | Event Format | Event name + properties structure |
 | 属性类型 | Property Type | String / Number / Boolean / Date / Array |
 | 数据校验 | Data Validation | Verify event format & property types |
-| 公共服务端属性 | Super Property | Properties attached to all events |
+| 公共事件属性 | Super Property | Properties attached to all events. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
 | 可更新事件 | Updatable Event | Event whose properties can be updated after creation |
 | 首次事件校验 | First Event Check | Validate an event's first occurrence |
 | 自动采集 | Auto-track | Auto-collected events (app install, start, page view, etc.) |
@@ -151,8 +151,9 @@ After reading relevant documentation, output in the following format:
 (If no sourceUrl, provide local .md file path)
 ```
 
-**⚠️ Information Accuracy Rules**:
+**⚠️ Terminology Rules**:
 - **Only output what is in the documentation**. Do NOT speculate, imagine, or fill in defaults.
+- **Never translate "Super Property" as "超级属性"** — the correct AE Chinese term is "公共事件属性" or "公共属性". This applies to all user-facing output: headings, step descriptions, code comments, examples, etc.
 - For uncertain information (e.g., data delay times, specific limit values), **do NOT fabricate**.
 - If the document has no direct answer but allows inference: mark under "Source Document" as "Synthesized inference; recommend verification".
 - If the documentation truly does not cover the question, fall back to Step 4. Do NOT force an answer.

package/skills/ae-data-integration-helper/references/sdk_usage_notes.md

@@ -1,6 +1,6 @@
 # SDK Usage Notes
 
-> **Terminology**: 上报模式 = upload mode | 缓存上报 = batch/buffered upload | 批量上报策略 = batch upload strategy | 上报失败处理 = upload failure handling | 属性类型 = property type | 预置属性 = preset property (`#` prefix) | 自定义属性 = custom property | 时间校准 = time calibration | 自动采集事件 = auto-track event | 数据加密 = data encryption | LoggerConsumer = writes events to local log files (recommended for production) | BatchConsumer = uploads events in batches with retry | DebugConsumer = debug-only consumer (NOT for production) | 公共属性 = super property | 动态公共属性 = dynamic super property | 多端上报 = multi-platform tracking | 用户割裂 = user fragmentation | 时区偏移 = timezone offset (`#zone_offset`)
+> **Terminology**: 上报模式 = upload mode | 缓存上报 = batch/buffered upload | 批量上报策略 = batch upload strategy | 上报失败处理 = upload failure handling | 属性类型 = property type | 预置属性 = preset property (`#` prefix) | 自定义属性 = custom property | 时间校准 = time calibration | 自动采集事件 = auto-track event | 数据加密 = data encryption | LoggerConsumer = writes events to local log files (recommended for production) | BatchConsumer = uploads events in batches with retry | DebugConsumer = debug-only consumer (NOT for production) | 公共属性 = super property (公共事件属性; never "超级属性") | 动态公共属性 = dynamic super property | 多端上报 = multi-platform tracking | 用户割裂 = user fragmentation | 时区偏移 = timezone offset (`#zone_offset`)
 
 # 一、客户端 SDK
 

package/skills/ae-dataops/SKILL.md

@@ -182,7 +182,8 @@ Detailed datasource, metadata browsing, sync solution, execution, and monitoring
 
 Key constraints:
 - Generate `sourceConfig`, `sinkConfig`, `channelConfig`, and `fieldsMapping` from the reference templates; do not invent keys.
-- `+save_sync_solution` is not a partial patch: call `+get_sync_detail --withParams true` first, then submit complete configs.
+- MySQL Source read partitioning uses `sourceConfig.splitColumn`; `fieldsMapping.shardingKey` is column metadata and must not be used for it.
+- `+save_sync_solution` is not a partial patch: call `+get_sync_detail --withParams true` first, then submit complete configs. `syncName` is accepted for compatibility but ignored.
 - Preset repository sync uses `te_etl@TASK_ENGINE_TRINO` and requires gateway configuration.
 - Use `+list_sync_runs` to get `taskId` before stopping a running sync.
 

package/skills/ae-dataops/references/dataops-integration.md

@@ -88,7 +88,7 @@ ae-cli dataops_integration +add_sync_solution --spaceCode "${spaceCode}" \
   --syncName "MySQL to Preset Repository Sync" \
   --srcComponent "MySQL" --srcDatasourceId "${mysqlDatasourceId}" \
   --sinkComponent "te_etl" --sinkDatasourceId "te_etl@TASK_ENGINE_TRINO" \
-  --sourceConfig '{"component":"MySQL","datasourceId":"xxx","database":"test","tablePath":"users"}' \
+  --sourceConfig '{"component":"MySQL","datasourceId":"xxx","database":"test","tablePath":"users","batchSize":1000}' \
   --sinkConfig '{"component":"te_etl","datasourceId":"te_etl@TASK_ENGINE_TRINO","database":"","tablePath":"ods_users_mysql","tableType":"PHYSICAL_TABLE","bizClassify":"CURRENT","dbBizType":"TASK_ENV_DB","authedSpace":"","partitionKeys":[],"dataSaveMode":1,"batchSize":20000}' \
   --channelConfig '{"limitType":"0","gatewayConfig":{"engineFlag":"TASK_ENGINE_TRINO","companyId":1,"appDefinition":"APP_GAIA","bizFlag":"BIZ_GAIA_TASK_RELEASE","repoCode":"te_etl","spaceCode":"default"}}' \
   --fieldsMapping '{"mapping":[{"source":{"name":"id","type":"int","manual":false,"partitionKey":false,"primaryKey":false,"shardingKey":false,"sortingKey":false,"upsertKey":false},"target":{"name":"id","type":"int","manual":false,"partitionKey":false,"primaryKey":false,"shardingKey":false,"sortingKey":false,"upsertKey":false}}]}'
@@ -148,17 +148,86 @@ ae-cli dataops_integration +stop_sync_solution --spaceCode "${spaceCode}" \
 }
 ```
 
-### Non-Preset Repository (e.g., MySQL)
+### MySQL table source without filter
 
 ```json
 {
   "component": "MySQL",
-  "datasourceId": "ds-uuid-xxx",
-  "database": "test",
-  "tablePath": "users"
+  "datasourceId": "ds-id",
+  "database": "demo",
+  "tablePath": "orders",
+  "batchSize": 1000
 }
 ```
 
+### MySQL table source with splitColumn
+
+```json
+{
+  "component": "MySQL",
+  "datasourceId": "ds-id",
+  "database": "demo",
+  "tablePath": "orders",
+  "splitColumn": "id",
+  "batchSize": 1000
+}
+```
+
+### MySQL table source with whereCondition
+
+```json
+{
+  "component": "MySQL",
+  "datasourceId": "ds-id",
+  "database": "demo",
+  "tablePath": "orders",
+  "whereCondition": "WHERE created_at >= '2026-07-01'",
+  "batchSize": 1000
+}
+```
+
+### MySQL custom query source
+
+```json
+{
+  "component": "MySQL",
+  "datasourceId": "ds-id",
+  "query": "SELECT id, amount FROM orders",
+  "batchSize": 1000
+}
+```
+
+Use exactly one mode. Table mode requires `database` and `tablePath` and may include
+non-empty `splitColumn` and `whereCondition`. Query mode requires non-empty `query`
+and must not include table-only fields. `batchSize` must be an integer from `1000` to
+`10000`; omit it to use the backend default `1000`.
+
+The GUI may send `readType` (`1=table`, `2=query`) and `hasCondition` (`0=off`, `1=on`).
+They are optional for CLI calls. Prefer the canonical templates above. In table mode,
+`hasCondition=1` requires a non-empty `whereCondition`.
+
+MySQL Source read partitioning uses `sourceConfig.splitColumn`;
+`fieldsMapping.shardingKey` is column metadata and must not be used for it.
+
+### MySQL sink target
+
+```json
+{
+  "component": "MySQL",
+  "datasourceId": "ds-id",
+  "database": "demo",
+  "tablePath": "orders",
+  "dataSaveMode": 2,
+  "batchSize": 1000
+}
+```
+
+MySQL Sink requires non-empty `database` and `tablePath` and must not contain a
+`query` key. `dataSaveMode` must be a JSON integer: `1=append`, `2=overwrite`,
+`3=upsert`; omit it to use default `2`. `batchSize` must be a JSON integer from
+`1000` to `10000`; omit it to use default `1000`. Strings, enum names, decimals,
+booleans, `null`, and out-of-range values are rejected.
+
 ### channelConfig (must include gatewayConfig when source or target involves preset repository)
 
 ```json
@@ -246,7 +315,7 @@ ae-cli dataops_integration +stop_sync_solution --spaceCode "${spaceCode}" \
 - **Datasource table structure**: `+get_table_structure` requires `--spaceCode`, `--datasourceId`, `--database`, and `--tablePath`; `--catalog` and `--env` are optional, and `--env` defaults to `DEV`. It returns `columns` and `partitionColumns`.
 - **Sync solution list**: `+list_sync_solutions` requires only `--spaceCode`. It returns sync metadata including `syncId`, `syncName`, source/sink datasource and table fields, last execution/schedule status codes, owner, remark, and timestamps.
 - **Sync detail**: `+get_sync_detail` requires `--spaceCode` and `--syncId`; `--withParams` is optional and defaults to `false`. It returns source, sink, field mapping, last execution/schedule status, owner, and `nextAction`; `withParams=true` also returns `usedParams`.
-- **Sync update**: `+save_sync_solution` requires `--spaceCode`, `--syncId`, `--sourceConfig`, and `--sinkConfig`; `--syncName`, `--channelConfig`, `--fieldsMapping`, and `--remark` are optional. Passing `--syncName` renames the sync solution; omit it to keep the current name. `sourceConfig` and `sinkConfig` must be complete JSON strings from `+get_sync_detail --withParams true`; pass complete `channelConfig` and `fieldsMapping` when keeping or updating them.
+- **Sync update**: `+save_sync_solution` requires `--spaceCode`, `--syncId`, `--sourceConfig`, and `--sinkConfig`; `--syncName`, `--channelConfig`, `--fieldsMapping`, and `--remark` are optional. `syncName` is accepted for compatibility but ignored; the current name is preserved. `sourceConfig` and `sinkConfig` must be complete JSON strings from `+get_sync_detail --withParams true`; pass complete `channelConfig` and `fieldsMapping` when keeping or updating them.
 - **Sync runs**: `+list_sync_runs` requires `--spaceCode` and `--syncId`; `--limit` is optional and defaults to `20`. It returns `runs`, `returnedCount`, `limit`, and `nextAction`; each run includes `taskId`, `execType`, `status`, `execTime`, `channelMode`, and `submitter`.
 - **Stop sync run**: `+stop_sync_solution` requires `--spaceCode`, `--syncId`, and `--taskId`. Use `taskId` from `+list_sync_runs` for an active run. It returns `action`, `result` with `execStatus`, `syncId`, and `taskId`, and top-level `status`.