@thinkingai/ae-cli 6.0.34 → 6.0.36

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

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage MCP: config items, flows, channel settings, task data query, and management"
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, and task management. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task."
 ---
 
 # ae-engage
@@ -43,6 +43,27 @@ Typical use cases include:
 - Querying config items and strategies, copying templates, and managing strategy status
 - Querying flow lists, node schemas, and flow reports, and saving or managing flows
 
+## Keyword Routing
+
+When the user mentions a product term below (including common Chinese UI labels), open the listed reference(s) first — do not guess commands or IDs.
+
+| Keyword | Product meaning | CLI domain | Primary reference | Related references |
+|---|---|---|---|---|
+| **Config center** | Engage scene management / config center overview | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-config-channel.md`, `channel-mgmt.md`, `scene-strategy.md`, `scene-template.md`; L3 reports: `config-item-trigger-report.md`, `config-item-analysis-report.md`, `config-item-strategy-comparison.md` |
+| **Scene config** | Same as config center; params, groups, metrics, channels, strategies, and templates under a config item | `engage-scene` | `references/scene-config-item.md` | Same as above; params/groups/metrics: `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md` |
+| **Config item** | A single config item in the config center | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-strategy.md`, `scene-template.md` |
+| **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md`, `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
+| **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
+| **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience QP: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — **用户满足** `filts[0]` + **用户行为** `filts[1]` two-block mix QP; preflight props (stop + list if missing); examples A/B/C; template: `scene-template.md` |
+| **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
+| **Template** | Strategy templates under a config item | `engage-scene` | `references/scene-template.md` | `scene-config-param.md` (template fields reference `paramId`); enable via `template update` then `template update-status` before strategy create |
+
+**Easy to confuse:**
+
+- **Push channel** → `ae-cli engage-setting channel …` (Hermes push channel settings)
+- **Config channel** → `ae-cli engage-scene config-channel …` (config-center channels; see `channel-mgmt.md`)
+- Flow / Task canvas nodes use `channelId` from **push channels**; config items bind `channel_id` from **config channels**
+
 ## Parameter Conventions
 
 - Use regular flags for simple parameters, for example `--project-id`, `--task-id`, and `--flow-uuid`
@@ -230,6 +251,8 @@ ae-cli engage-scene config-metric update-rule --project-id <project_id> --metric
 ae-cli engage-scene config-metric batch-delete --project-id <project_id> --config-id <config_id> --metric-ids '[1,2]' --yes
 
 # Config channel list / get / create / update / update-status / delete / query-log
+# User params: verify each customsParamList columnName via ae-analysis property list/get first; then use user:<prop_name>
+# Strategy custom audience: scene-strategy-audience.md — mix QP filts[0]=用户满足, filts[1]=用户行为; strategy predict for 预估人数
 # Workflows: references/channel-mgmt.md · schema: references/scene-config-channel.md
 ae-cli engage-scene config-channel list --project-id <project_id> [--channel-type 0|1]
 ae-cli engage-scene config-channel get --project-id <project_id> --channel-id <channel_id>
@@ -243,6 +266,7 @@ ae-cli engage-scene config-channel query-log --project-id <project_id> --channel
 ae-cli engage-scene strategy create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","strategyName":"s1"}'
 ae-cli engage-scene strategy update --project-id <project_id> --payload '{"strategyUuid":"uuid-1"}'
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
+ae-cli engage-scene strategy predict --project-id <project_id> --qp '<mix QP string>' --zone-offset 8 [--strategy-uuid <uuid>]
 ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> --strategy-ids '["s1"]'
 
 # Template list / get / create / update / update-status / delete
@@ -412,7 +436,8 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/scene-config-metric.md` (`engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}`)
 - `references/scene-config-channel.md` (`engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}`)
 - `references/channel-mgmt.md` (config channel management workflows)
-- `references/scene-strategy.md` (`engage-scene.strategy.{list,get,create,update,log,batch-copy,manage}`)
+- `references/scene-strategy.md` (`engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}`)
+- `references/scene-strategy-audience.md` (custom audience mix QP: 用户满足/用户行为 two-block layout, preflight, worked examples A/B/C)
 - `references/scene-template.md` (`engage-scene.template.{list,get,copy,create,update,update-status,delete}`)
 - `references/config-item-trigger-report.md` (`engage-scene.report.config-item-trigger`, L3)
 - `references/config-item-analysis-report.md` (`engage-scene.report.config-item-analysis`, L3)
@@ -486,11 +511,13 @@ For task draft creation or update, use this workflow:
 
 1. `ae-cli engage-setting channel list --project-id <projectId>`
 2. `ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`
-3. If the guide says QP-derived fields are needed, create the audience with `analysis user-cluster create`, then read its server-authored definition with `analysis user-cluster get`
+3. If the guide says QP-derived fields are needed (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`), call:
+   `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>`
+   Use the returned skill text to build those fields. For existing-cluster audiences (`targetClusterType=2`), use `analysis user-cluster get` instead of hand-writing QP.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 
 `engage-task task build-save-guide` is a read-only helper. It returns scenario-specific required fields, channel content schema, unsupported combinations, examples, and a handoff template for `save_task`.
 
-`engage-task task save` only saves a draft. It does not submit approval, does not start sending, and does not trigger task execution. If `req.taskId` is omitted it creates a new draft; if `req.taskId` is present it updates an existing draft. Update mode only supports draft tasks, and omitted fields can inherit from the existing draft before validation.
+`engage-task task save` creates or updates a task configuration. It does not submit approval, does not start sending, and does not trigger task execution. If `req.taskId` is omitted it creates a new draft; if `req.taskId` is present it updates an existing **draft or paused** task. Update mode rejects running/ended tasks with `invalid_status`. Omitted fields inherit from the existing task before validation (partial rename/update is supported).
 
-Audience creation is not a fixed preflight step. Use direct `analysis user-cluster create` only when the guide requires a condition audience, and prefer the returned `cluster_name`/`clusterKey`. If the Engage schema explicitly requires QP-derived fields such as `targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`, read the saved server-authored definition with `analysis user-cluster get`; never assemble raw QP manually.
+Audience creation is not a fixed preflight step. When the guide requires QP-derived fields (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, `completionIndicatorDef.event`), call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` first and follow the returned skill definition; do not assemble raw QP manually. For existing-cluster audiences, use `analysis user-cluster get` to copy server-authored definitions when appropriate.

package/skills/ae-engage/references/activity-topic.md

@@ -48,10 +48,14 @@ Topic-level audience uses `topicClusterKey` / `topicQp`; do **not** pass task-le
 
 | Value | Required | Notes |
 |---|---|---|
-| `1` (custom) | `topicQp` | Valid condition JSON object string (not `{}`). |
+| `1` (custom) | `topicQp` | Valid condition JSON object string (not `{}`). Use mix QP with `totalCFilter` (and optional `totalOutCFilter`). |
 | `2` (existed) | `topicClusterKey` | From an existing user cluster. |
 | `3` (all) | — | **Not supported for activity topics** → `TOPIC_TARGET_CLUSTER_TYPE_UNSUPPORTED`. Use standalone `engage-activity task create` for all-users. |
 
+**`triggerMixQpVersion`:** For custom audience (`targetClusterType=1`) with mix QP (`totalCFilter` / `totalInCFilter`), set `"4.4"`. UI theme edit parses conditions only when this is `4.4`; missing/blank values make target-user filters render empty. Capability create/update/copy default blank to `"4.4"` (same as UI and standalone task MCP).
+
+Task-level extra conditions go in `taskQp` as mix QP under **`totalCFilter` only** (user attrs and/or events). Do not put task-owned conditions in `totalInCFilter` — that key is reserved for topic→task merge (topic `totalCFilter` is copied into task cluster `totalInCFilter` on save).
+
 ### Trigger (`triggerType`)
 
 | Value | Required | Notes |
@@ -60,6 +64,35 @@ Topic-level audience uses `topicClusterKey` / `topicQp`; do **not** pass task-le
 | `1` (schedule repeat) | `startDate`, `endDate`, `triggerCrontab` | |
 | `2` (manual) | — | **Not supported for activity topics** (UI only offers 0/1). Using it without `endDate` causes `CAPABILITY_EXECUTION_FAILED`. |
 
+## Create Topic Orchestration
+
+Use this workflow when a topic has a shared audience plus one or more task-level audience splits, message variants, or completion goals.
+
+1. **Separate the intent before building the payload.** Record the parent activity, topic-level shared audience, task-level extra audience for each task, schedule, channel, message content, and completion goal/window as distinct fields. A completion goal is not an audience condition unless the user explicitly says so.
+2. **Resolve the parent activity.** Use `activity list|get` to verify the exact `activityId`, editable status, activity dates, and timezone. For a repeated topic, keep `startDate` and `endDate` inside the activity period and interpret the cron in the activity timezone.
+3. **Resolve a real channel.** Query `engage-setting channel list`, then inspect the selected channel before composing content. If several enabled channels match and the user has not specified a provider or an already-confirmed project default, ask which one to use instead of choosing an arbitrary ID.
+4. **Read the channel content contract.** Call `engage-task task build-save-guide` with the known trigger, audience, channel type, and `channelId`. Build every `groupContentList[].contentList[].content` item from `fieldRules.channelContentSchema`; do not infer App Push keys or parameter types from memory.
+5. **Prepare audience and completion inputs.** Resolve real event/property metadata and categorical values through the applicable Analysis workflow. Put the shared condition in `topicQp` or `topicClusterKey`, and only task-specific conditions in each `taskQp`. For a rolling condition such as "recent N days" that must be evaluated for future repeated sends, prefer a custom QP; use an existing cluster only after confirming that its refresh semantics match the send cadence. Build the completion goal separately in `completionIndicatorDef`.
+6. **Build one native `TopicAddDTO`.** Keep nested payload keys in camelCase. Ensure `tasks` is non-empty, `frequencyLimits` and QP fields are JSON strings where documented, each task has channel content, and Android/iOS or other variants map to the correct task audience and message.
+7. **Validate the complex payload.** Run `topic create ... --validate` while correcting the nested payload. Inspect `normalized_input` and confirm that the schedule, audience boundaries, message variants, and completion window retain the intended semantics. After `valid=true`, execute the same payload directly; do not add a redundant dry-run by default.
+8. **Create exactly once.** Run `topic create` with the validated payload. A successful response only reports `data.success`; it does not provide enough evidence to declare the whole orchestration complete.
+9. **Resolve IDs and verify the saved topic.** Call `activity info-list` for the parent activity, match the new topic and tasks by their names, then call `topic get` with the returned `topicId`. Verify the channel, dates, cron, topic audience, each task audience, content, completion goal, and draft status. For custom audiences, confirm that the saved task QP keeps task-owned conditions in `totalCFilter` and the shared topic condition appears only through the topic-to-task merge.
+10. **Verify generated audiences before reporting completion.** Read the generated topic/task cluster keys with the applicable cluster query and wait for terminal computation state. Require `refresh_status=success`, `progress=100`, `real_available=1`, and `cluster_valid=1`. A zero-user result may be valid, but reconcile it with the discovered categorical values and business expectation. If computation fails, correct only the verified cause and re-check; do not retry an unchanged request or report the topic as fully ready.
+
+Recommended command order:
+
+```text
+activity list/get
+-> channel list/get
+-> task build-save-guide
+-> prepare topic audience, task audiences, content, and completion goal
+-> topic create --validate
+-> topic create
+-> activity info-list
+-> topic get
+-> generated audience status checks
+```
+
 ## Output
 
 - `get`: `data.topic` (includes `topicClusterKey` for topic audience).

package/skills/ae-engage/references/add-channel.md

@@ -1,9 +1,8 @@
 # ae-engage engage-setting channel create
 
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel create`
 
-Create a new Engage channel.
-
-Mapped command: `ae-cli engage-setting channel create`
+Create a new Engage push channel.
 
 ## Flags
 

package/skills/ae-engage/references/build-task-save-guide.md

@@ -14,11 +14,25 @@ Use this sequence when creating or updating a task draft:
 
 1. Query channels with `ae-cli engage-setting channel list --project-id <projectId>`.
 2. Call `ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`.
-3. If the guide says an audience or QP-derived fields are required, create the audience directly and read it back:
+3. If the guide says QP-derived fields are required, fetch the skill definition first:
 
 ```bash
-ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
-ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
+ae-cli engage-setting query cluster-qp-skill --project-id <projectId>
+# optional selectors:
+ae-cli engage-setting query cluster-qp-skill --project-id <projectId> --response-mode full --condition-subtype all
+```
+
+Use the returned `skill` text to build:
+
+- `targetConfig.qp`
+- `triggerConfig.triggerRule` (required for `triggerType=3/4/5`)
+- `clientConfig.clientQp`
+- `completionIndicatorDef.event`
+
+For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
+
+```bash
+ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cluster_name>"]'
 ```
 
 4. Build the final grouped `save_task.req`.

package/skills/ae-engage/references/channel-detail.md

@@ -1,9 +1,8 @@
 # ae-engage engage-setting channel get
 
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel get`
 
-Query the details of a single Engage channel.
-
-Mapped command: `ae-cli engage-setting channel get`
+Query the details of a single Engage push channel.
 
 ## Response shape
 

package/skills/ae-engage/references/channel-list.md

@@ -1,11 +1,8 @@
 # ae-engage engage-setting channel list
 
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel list`
 
-Query the list of Engage channels in a project.
-
-Mapped command: `ae-cli engage-setting channel list`
-
-## Response shape
+Query the list of Engage push channels in a project.
 
 The result is `{ data: { items, total } }`. Channel fields recursively use snake_case, for
 example `data.items[].channel_id`, `data.items[].channel_status`, and `data.items[].channel_type`.

package/skills/ae-engage/references/channel-mgmt.md

@@ -1,6 +1,6 @@
 # Config channel management workflows
 
-> Commands: `ae-cli engage-scene config-channel …` · See [`scene-config-channel.md`](scene-config-channel.md) for flags, `config` JSON shape, and capability ids.
+> Trigger keywords: config center, config channel · Commands: `ae-cli engage-scene config-channel …` · See [`scene-config-channel.md`](scene-config-channel.md) for flags, `config` JSON shape, and capability ids.
 
 Use for AE Engage **config center channel management**: Webhook (`channel_type=0`) and client (`channel_type=1`) config channels — list, get, create, update, copy, enable/disable, operation log, and delete.
 
@@ -12,6 +12,8 @@ Use for AE Engage **config center channel management**: Webhook (`channel_type=0
 4. `channel_status`: **1 = enabled**, **2 = disabled**.
 5. Writes require explicit user intent; `delete` is high-risk — confirm, then `--yes`.
 6. Before changing Webhook URL, auth, or parameter definitions on an enabled channel, disable it first.
+7. In `config.customsParamList` (**user params**), every `columnName` must be prefixed with `user:` and point to a real user property, e.g. `user:#account_id`. `envParamList` entries do not use this prefix.
+8. Before create/update, use the **ae-analysis** skill to verify each intended user property exists (`analysis-meta property list --scope user`, then `property get` for exact match). Never invent `columnName` values.
 
 ## Permissions
 
@@ -44,18 +46,31 @@ Parse `data.channel.config` for URL, auth, user params, and env params.
 
 Webhook requires `channel_name` and `config.url`. Optional: `testUrl`, auth, user params, env params.
 
+**Preflight (user params):** for each intended `customsParamList[].columnName`, discover and verify the user property via ae-analysis first:
+
+```bash
+ae-cli analysis-meta property list --project-id <pid> --scope user --query <keyword> \
+  --fields '["prop_name","prop_desc","select_type"]' --limit 50
+ae-cli analysis-meta property get --project-id <pid> --table-type user --prop-name <prop_name>
+# → use columnName "user:" + prop_name, e.g. user:#account_id
+```
+
+Then create the channel:
+
 ```bash
 ae-cli engage-scene config-channel create \
   --project-id <pid> \
   --channel-name '<name>' \
   --channel-type 0 \
-  --config '{"url":"https://...","testUrl":"","authConfig":{"enable":false},"customsParamList":[{"key":"uid","columnName":"#account_id","defaultValue":"","systemIdParam":false}],"envParamList":[]}'
+  --config '{"url":"https://...","testUrl":"","authConfig":{"enable":false},"customsParamList":[{"key":"uid","columnName":"user:#account_id","defaultValue":"","systemIdParam":false}],"envParamList":[]}'
 ```
 
 Returns `data.channel_id`. Created channels start **enabled**.
 
 ### 4. Update
 
+Re-verify any new or changed `customsParamList[].columnName` with `analysis-meta property list/get` (ae-analysis skill) before building `--config`.
+
 ```bash
 ae-cli engage-scene config-channel get --project-id <pid> --channel-id <id>
 # If channel_status=1 and changing URL / auth / param definitions:

package/skills/ae-engage/references/channel-test-send.md

@@ -1,6 +1,6 @@
 # engage-setting channel test-send
 
-> Capability id: `engage-setting.channel.test-send` · Domain: `engage`.
+> Trigger keywords: push channel · Capability id: `engage-setting.channel.test-send` · Domain: `engage`.
 
 ## Command
 

package/skills/ae-engage/references/channel-update-config.md

@@ -1,6 +1,6 @@
 # engage-setting channel update-config
 
-> Capability id: `engage-setting.channel.update-config` · Domain: `engage`.
+> Trigger keywords: push channel · Capability id: `engage-setting.channel.update-config` · Domain: `engage`.
 
 ## Command
 

package/skills/ae-engage/references/delete-channel.md

@@ -1,9 +1,8 @@
 # ae-engage engage-setting channel delete
 
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel delete`
 
-Delete an Engage channel.
-
-Mapped command: `ae-cli engage-setting channel delete`
+Delete an Engage push channel.
 
 ## Flags
 

package/skills/ae-engage/references/save-flow.md

@@ -33,8 +33,8 @@ You still organize user requirements into an intermediate intent first, then map
 ## 2. Workflow
 
 1. Identify the flow intent from the user input and produce a unified intent JSON.
-2. Build a semantic condition request from `ae-analysis/references/user_cluster_models.md`, create the audience directly with `analysis user-cluster create`, and prefer its `cluster_name`/`clusterKey`. Read the saved server-authored definition with `analysis user-cluster get` only when an Engage node schema explicitly requires QP-derived fields; never assemble raw QP.
-3. Run `ae-cli engage-setting channel list --project-id <projectId>` to get the available channels and match real `channel_id` values for touchpoint nodes. For `webhook_push`, also run `ae-cli engage-setting channel get` and use `data.item.config.params_list` to build request field `contentList`.
+2. Build a semantic condition request from `ae-analysis/references/user_cluster_models.md`, create the audience directly with `analysis user-cluster create`, and prefer its `cluster_name`/`clusterKey`. When node schema requires QP-derived fields (`targetClusterQp`, `triggerRule`, etc.), call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` first; never assemble raw QP manually.
+3. Run `ae-cli engage-setting channel list --project-id <projectId>` to get the available channels and match real `channelId` values for touchpoint nodes. For `webhook_push`, also run `ae-cli engage-setting channel get` and use `data.item.config.params_list` to build request field `contentList` (camelCase; snake_case aliases are normalized during validate).
 4. Query `ae-cli engage-flow node-config schema --project-id <project_id> --node-type <type>` before constructing each non-trivial node config, then run `ae-cli engage-flow node-config validate --project-id <project_id> --node-type <type> --operation-mode save_flow --config '<config-json-string>'` before placing the config into `nodes` or `nodeConfigs`.
 5. Map the intent JSON to `nodes` and `edges` (compact form, see §7 / §8).
 6. `build` → resolve any `need_input` slot → `preview` → `commit`, then verify with `engage-flow flow get`.
@@ -460,7 +460,10 @@ The CLI injects `projectId` into both the top level and `req`; you do not write
 
 `need_input` is a **soft prompt**, not a hard error:
 
-- **`data.result.errors` empty + `data.result.next_slot` present** → server needs one more node config (trigger / channel / targetCluster). Answer with request fields `operation=build` + `draftId` + `expectedVersion` + `slotAnswer`. If response `next_slot.target_node_id` is present, request `slotAnswer.nodeConfig` may contain only `config`; otherwise include `nodeId` or `id`.
+- **`data.result.errors` empty + `data.result.next_slot` present** → server needs one more node config (trigger / channel / targetCluster). Answer with request fields `operation=build` + `draftId` + `expectedVersion` + `slotAnswer`. If response `next_slot.target_node_id` is present, request `slotAnswer.nodeConfig` may contain only `config`; otherwise include `nodeId` or `id`. **`slotAnswer.nodeConfig.config` merges into the existing node config** — send only the fields you are adding or changing, not the full config.
+- For existing-cluster entry nodes (`targetUserType=2`), use `targetClusterName` or `clusterId` alias.
+- For custom audiences, call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` before filling `targetClusterQp`.
+- For `event_trigger`, `endDate` must be **strictly earlier than** `flowEndDate`.
 - **`data.result.errors` non-empty** → hard validation failure. Fix `nodes`/`edges` and `build` again (a new `data.result.draft_id` is issued; the stale draft is cleaned by TTL).
 
 ### 11.3 Minimal Working Example