@thinkingai/ae-cli 6.1.13 → 6.1.16

package/skills/ae-data-integration/references/ue-mapping.md

@@ -0,0 +1,142 @@
+# UE mapping contract
+
+The mapping version is `ae-local-data-mapping/v1`.
+
+Required structure:
+
+```json
+{
+  "version": "ae-local-data-mapping/v1",
+  "source": {
+    "sha256": "<source-sha256>",
+    "format": "csv",
+    "data_set": "$"
+  },
+  "mode": "track",
+  "confidence": "high",
+  "account_id_field": "user_id",
+  "time": {
+    "field": "event_time",
+    "format": "auto",
+    "source_timezone": "Asia/Shanghai"
+  },
+  "event_name_field": "event_name",
+  "properties": [
+    { "source": "amount", "target": "amount", "type": "number" }
+  ]
+}
+```
+
+Use `distinct_id_field` when no account field exists. `mixed` requires `record_type_field`. Track requires `event_name_field` or a reviewed `default_event_name`. `source.format` is one of `csv`, `tsv`, `json`, `jsonl`, `xls`, `xlsx`. For a multi-file template mapping, `source.sha256` may be the wildcard `*`.
+
+## Record types
+
+Every record carries a `#type`. `mode: 'mixed'` resolves the type per row via `record_type_field`; otherwise the mode fixes it (`track` or `user_set`). The `record_type_field` values are normalized case- and underscore-insensitively, with `event`→`track` and `user`/`userset`→`user_set` aliases.
+
+| `#type` | Meaning | Requires `#event_name` |
+| --- | --- | :---: |
+| `track` | Report an event into the event table | Yes |
+| `user_set` | Overwrite user properties (create if missing) | No |
+| `user_setOnce` | Initialize a property only when empty | No |
+| `user_add` | Increment numeric user properties | No |
+| `user_unset` | Clear user property values | No |
+| `user_del` | Delete the user from the user table | No |
+| `user_append` | Append elements to list properties | No |
+| `user_uniq_append` | Append elements with deduplication | No |
+
+## System fields
+
+Top-level `#` fields map from named source columns. The user confirms each mapping; never infer it from a column name alone — a `user_id` column can be either an anonymous or a login ID, and only the user knows which.
+
+| Field | Plain-language meaning | Required |
+| --- | --- | :---: |
+| `#distinct_id` | Anonymous visitor ID (device/cookie/visitor) — identifies unauthenticated traffic | At least one of `#distinct_id` / `#account_id` |
+| `#account_id` | Login/account ID (database `user_id`, phone, member ID) — identifies authenticated users | At least one of `#distinct_id` / `#account_id` |
+| `#time` | Event/profile occurrence time; AE bins data by it | Yes |
+| `#event_name` | What the user did (`purchase`, `login`) | Only for `track` |
+| `#ip` | Client IP; AE resolves geo from it | No |
+| `#uuid` | Short-window deduplication ID | No |
+
+`#zone_offset` is a preset property that tells AE the data's UTC offset (whole hours, -12..14) so `#time` is interpreted correctly. Unlike the fields above it lives **inside `properties`**, not at the top level. Provide it via `zone_offset_value` (a whole-hour integer such as `8` for UTC+8; an IANA name is also accepted and resolved to its offset at conversion time — sub-hour zones round to the nearest whole hour and DST zones reflect the offset then in effect, so historical data crossing a DST boundary should use `zone_offset_field`) or `zone_offset_field` (a source column carrying the offset per row); the two are mutually exclusive. Rows whose `zone_offset_field` value is missing or not an integer in -12..14 are quarantined.
+
+Mapping keys: `account_id_field`, `distinct_id_field`, `time.field`, `event_name_field` (or a reviewed `default_event_name`), `ip_field`, `uuid_field`. Inspect surfaces every identity-shaped column in `identity_candidates` (name, `account`/`distinct` kind, unique and missing ratios) so the agent can present all candidates for confirmation. When the required identity column is absent, use an explicit `account_id_value`/`distinct_id_value` placeholder or `random_pool` — a user decision, never invented.
+
+## Output record shape
+
+System fields sit at the top level; every mapped property is nested under `properties`.
+
+```json
+{ "#type": "track", "#time": "2026-08-10 10:00:00.000", "#account_id": "u-1", "#event_name": "purchase", "properties": { "amount": 99.9, "channel": "app" } }
+```
+
+```json
+{ "#type": "user_set", "#time": "2026-08-10 10:00:00.000", "#distinct_id": "d-1", "properties": { "user_level": 5, "user_tag": "vip" } }
+```
+
+`track` requires `#event_name`; user-profile types (`user_set`, `user_add`, …) do not.
+
+## Optional overlay fields
+
+All fields below are optional and are explicit user decisions — never invent them.
+
+| Field | Shape | Effect |
+| --- | --- | --- |
+| `time_format` | `string` (strptime pattern) | Overrides auto-detection for `time.field`; used for ambiguous US/EU dates |
+| `value_mapping` | `{ account_id? / distinct_id? / event_name? / record_type?: {original: replacement} }` | Exact-key replacement per system field (business-data keys map to AE-name values). A value with no matching key keeps its original text and fails validation, so confirm every distinct value is covered or excluded |
+| `account_id_value` / `distinct_id_value` | `string` | Fixed placeholder identity (≤128 chars). Applies to every row when the corresponding `*_field` is absent; when the field exists, fills only the rows whose column is empty |
+| `random_pool` | `{ account_ids?: string[], distinct_ids?: string[] }` | Synthesizes a random identity when the source field is absent |
+| `exclude_columns` | `string[]` | Source columns skipped when building properties |
+| `flatten_rules` | `{ outColumn: 'dot.path' }` | Nested flatten map. NDJSON/JSON paths are from the record root (`user_info.name`); CSV/TSV paths are `<column>.<cell-relative path>` into a JSON-encoded object cell (`user_profile.name`) — add the source column to `exclude_columns` when flattening it |
+| `headers` | `string[]` | User-confirmed column names for a headerless file; presence means the first row is data. Never use inspect's `col_1..col_N` placeholders — infer names from each column's values, confirm them with the user, then write them here |
+| `missing_time` | `'now'` | Fill a missing/empty `#time` with the current time, for user-profile rows only (explicit user decision; track rows are never filled) |
+| `ip_field` | `string` | Source column emitted as the top-level `#ip` system field (client IP; AE resolves geo) |
+| `uuid_field` | `string` | Source column emitted as the top-level `#uuid` system field (short-window deduplication ID) |
+| `zone_offset_value` | `number` (integer -12..14) or IANA `string` | Emits the fixed `#zone_offset` preset property inside `properties`. An IANA name resolves to its integer UTC offset |
+| `zone_offset_field` | `string` | Source column whose per-row integer value (-12..14) is emitted as `#zone_offset`; missing/non-integer rows are quarantined. Mutually exclusive with `zone_offset_value` |
+| `event_meta` | `{ <event-name>: { desc?: string, tag?: string } }` | Per-event business description and `event_tag` for the tracking plan, keyed by AE event name. Inferred from the data and user context; the user supplies anything not inferable — never leave them empty |
+
+Each `properties` entry may also carry `value_mapping` (per-property exact-key replacement), `transform` (one of `stringify`, `number`, `boolean`, `json`), `time_format` (only meaningful for `type: 'datetime'`), and `desc` (business description for the tracking plan; inferred, or user-provided when not inferable). Container columns (`object`/`list`) whose values arrive as JSON text — JSON-encoded CSV cells, or flattened NDJSON leaves — must set `transform: 'json'` so conversion parses the text back into a native object/array; it is a safe no-op when the value already arrived native.
+
+## Time formats
+
+Values with an explicit offset or `Z` are parsed by the JavaScript `Date` constructor (authoritative). Other values are matched against 21 formats; a `time_format` field overrides the match.
+
+| Category | Example | Auto-detected |
+| --- | --- | :---: |
+| Standard AE | `2024-01-15 10:30:00.123` / `2024-01-15 10:30:00` | Yes |
+| ISO 8601 | `2024-01-15T10:30:00` / with `.SSS` / with offset | Yes |
+| Unix epoch | `1705314600` (seconds) / `1705314600000` (milliseconds) | Yes |
+| Slash-separated | `2024/01/15 10:30:00` / `2024/01/15` | Yes |
+| Dot-separated | `2024.01.15 10:30:00` / `2024.01.15` | Yes |
+| Compact digits | `20240115103000` / `202401151030` / `20240115` | Yes |
+| English month names | `15 Jan 2024 10:30:00` / `January 15 2024 10:30:00` / `Jan 15 2024 10:30:00` | Yes |
+| Chinese date | `2024年1月15日` / `2024年1月15日 10:30:00` / `2024年1月15日 10时30分00秒` | Yes |
+| US format | `01/15/2024 10:30:00` (MM/DD/YYYY) | No — use `time_format` |
+| EU format | `15/01/2024 10:30:00` (DD/MM/YYYY) | No — use `time_format` |
+
+## Data rules
+
+- **Ingestion time window.** The receiver accepts event/profile times from 3 years before to 3 days after the server time; the CLI enforces this range. Client-side reporting has a tighter window (10 days before to 3 days after); historical data beyond the window needs AE support to extend it.
+- **Property type locking.** A property's type is locked on first receipt, and properties sharing a name across events are one property — later reports must use the same type. Values whose type mismatches the locked type are dropped silently, so review an inferred type before committing it.
+- **Quote stripping.** Paired single or double quotes around a cell value are stripped (`'user_001'` → `user_001`); a single-sided quote is kept as data (SQL exports often quote every value).
+- **Column name sanitization.** Recommended mapping auto-names properties: accents are stripped, camelCase is split to snake_case, everything is lowercased, and illegal characters become `_`; a digit-leading name is prefixed `field_`, and a name with nothing recognizable falls back to `field_N`. Review these targets — especially the `field_N` fallbacks — and rename before converting.
+- **Object sub-property keys.** Object and list-of-object keys follow the same naming rules as property names (lowercase snake_case, letter-leading, at most 50 chars, no `#`). A key that does not — for example a Chinese key inside a JSON cell such as `{"等级":"金牌"}` — quarantines the whole row, so confirm object keys before converting.
+
+## Review checklist
+
+- Source SHA-256 and data-set ID match the inspection result (or the mapping uses the `*` wildcard for multi-file).
+- Identity values remain strings and are at most 128 characters.
+- Source timezone is an IANA name derived from user/project context.
+- `#zone_offset`, when set, is a whole-hour integer in -12..14 (or an IANA name/column that resolves to one) and is emitted inside `properties`, never at the top level.
+- Event/property names are lowercase snake_case, begin with a letter, and are at most 50 characters.
+- Target property names are unique and do not collide with UE system fields.
+- Types are one of `string`, `number`, `boolean`, `datetime`, `list`, or `object`.
+- Text is at most 2 KB; numbers stay within -9E15..9E15.
+- Lists contain at most 500 strings (255 bytes each) or 500 objects.
+- Objects contain at most 100 legal sub-properties; nested values follow the same type limits.
+- A conversion rule does not hide a real type conflict.
+- Event/profile times fall within the receiver window: previous 3 years through next 3 days.
+- Do not fabricate UUIDs, identities, times, or events; `#ip`/`#uuid` map from named source columns only (`ip_field`/`uuid_field`).
+- `value_mapping`, `random_pool`, and fixed `account_id_value`/`distinct_id_value` came from an explicit user decision and match the actual distinct values/columns.
+
+`user_set` output for the same identity is ordered by time so receiver application order is deterministic. Conversion applies whole-row quarantine: any error on a row — identity, time, event, record type, or a single property (type coercion, size/limit) — drops the entire row. The row is written to `invalid.rows.jsonl` with its error codes, counted in `manifest.output.invalid_records`, and the manifest is blocked until reviewed. The failed rows are re-reportable without re-sending valid rows: fix the mapping, then run `convert --input-file <same-source> --mapping <fixed-mapping> --salvage-from <invalid.rows.jsonl>`. The salvage run re-processes only the listed row numbers against the same source, emits a `valid.ue.jsonl` containing only the newly fixed rows, and writes a new `invalid.rows.jsonl` with whatever still fails — so the loop repeats (feeding each round's `invalid.rows.jsonl` into the next `--salvage-from`) until no rows fail or the user stops.

package/skills/ae-data-integration/references/ue-routing.md

@@ -0,0 +1,35 @@
+# UE routing
+
+Use this reference after `data-integration inspect`.
+
+## Route to UE ingestion
+
+All of these must hold:
+
+- A real `#account_id` or `#distinct_id` source is present.
+- A real time column is parseable; no synthetic time is permitted.
+- The records are event facts or user-property snapshots rather than aggregates.
+- Field-level records can be represented without losing essential meaning.
+
+Classification order:
+
+1. A legal explicit `#type` wins (all eight record types — `track`, `user_set`, `user_setOnce`, `user_add`, `user_unset`, `user_del`, `user_append`, `user_uniq_append`).
+2. An event/action field implies `track`.
+3. Repeated users across a time series imply `track`; without an event field, propose a normalized file/Sheet name and require review.
+4. One row per user with snapshot-like fields implies `user_set`.
+5. Rows that mix track and user-profile facts in one file use `mixed` with a `record_type_field`; require explicit review.
+6. Low-confidence output is a proposal, never silent approval.
+
+Aggregated metrics, pivot tables, cross-tabs, model outputs, free-form documents, and records without real identity/time should normally use local analysis.
+
+## Route to local analysis
+
+Choose local analysis when:
+
+- The user wants insights, not project ingestion.
+- UE identity or time prerequisites are missing.
+- Each row is an aggregate rather than a user/event record.
+- Conversion would invent semantics or discard important structure.
+- The user declines an uncertain mapping or destination.
+
+Explain the reason briefly. Do not frame local analysis as an error.

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

@@ -62,7 +62,7 @@ Trigger when a user asks about:
 - **Configuration**: Debug mode / data validation / retry strategy
 - **Troubleshooting**: Upload failures / missing data / format errors
 
-**Do NOT trigger**: Inline Q&A within `ae-generate-tracking-plan` or `ae-generate-tracking-code` sessions (those skills have their own workflows).
+**Do NOT trigger**: Inline Q&A within `ae-generate-tracking-plan` or `ae-generate-tracking-code` sessions (those skills have their own workflows). Offline local-file import (CSV / Excel / JSONL → AE) is owned by the `ae-data-integration` skill — route those requests there instead of answering with LogBus / RESTful guidance.
 
 ## Workflow
 

package/skills/ae-dataops/SKILL.md

@@ -173,7 +173,7 @@ Detailed metadata browsing, SQL query, async download, and cancel workflows live
 Key constraints:
 - IDE is query-only; create/modify/delete tables with `dataops_datatable`.
 - Prefer `dataops_datatable +dict_search_tables` for table discovery unless raw engine metadata or schema browsing is required.
-- SQL query submission creates a download task; rows are not returned inline.
+- Submit exactly one read-only SQL query. It creates a platform-bounded download task; rows are not returned inline and the result is not an unlimited or full export.
 
 ---
 

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

@@ -61,7 +61,7 @@ ae-cli dataops_ide +search_tables --spaceCode "${spaceCode}" --searchKey "user"
 
 ## Workflow C: Execute SQL Query (Download-Centered Async Flow)
 
-Use this flow for SQL query execution. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly.
+Use this flow for exactly one read-only SQL query. Result rows are not returned through MCP/CLI; submit creates a Gaia download-center task directly. The query semantics are preserved, but the result remains platform-bounded; when present, `downloadRowLimit` reports that cap. This is not an unlimited or full export.
 
 ```bash
 # Step 1: Submit SQL and create a download task. Defaults: repoCode=te_etl, engineType=TASK_ENGINE_TRINO.
@@ -72,7 +72,7 @@ ae-cli dataops_ide +submit_sql_query --spaceCode "${spaceCode}" --repoCode "te_e
 # Step 2: Poll the download task status by spaceCode/downloadTaskId. Rows are not returned through MCP/CLI.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId}
 
-# Step 3: CLI-only local save after downloadStatus=SUCCESS. Use a .zip suffix.
+# Step 3: CLI-only streaming save after downloadStatus=SUCCESS. The target is replaced only after the stream completes.
 ae-cli dataops_ide +get_sql_query_status --spaceCode "${spaceCode}" --downloadTaskId ${downloadTaskId} --downloadTo "./result.zip"
 
 # (Optional) Cancel the download task.
@@ -104,8 +104,8 @@ ae-cli dataops_ide +cancel_sql_query --spaceCode "${spaceCode}" --downloadTaskId
 - **Table search**: `+search_tables` requires `--spaceCode` and `--searchKey`. `--connType`, `--repoCode`, and `--size` are optional and default to `SPACE`, `te_etl`, and `20`. It returns `items`, `searchKey`, `size`, `totalCount`, `tableCount`, `viewCount`, `returnedCount`, `hasMore`, and `nextAction`.
 - **Table detail**: `+ide_get_table_detail` requires `--spaceCode`, `--catalog`, `--schema`, and `--tableName`. `--connType`, `--repoCode`, `--engineType`, `--entityType`, and `--includeDdl` are optional and default to `SPACE`, `te_etl`, `TASK_ENGINE_TRINO`, auto-detect, and `false`. It returns identity, storage metadata, columns, partitions, partition keys, optional layout fields, and `tableDdl` only when requested.
 - **Schema info**: `+get_schema_info` requires `--spaceCode`, `--catalog`, and `--schema`. `--connType` and `--repoCode` are optional and default to `SPACE` and `te_etl`. It returns only `schema`, `tableNum`, and `viewNum`.
-- **SQL submit**: `+submit_sql_query` requires `--spaceCode` and `--sql`. `--repoCode` and `--engineType` are optional and default to `te_etl` and `TASK_ENGINE_TRINO`. On success it returns `requestId`, `spaceCode`, `repoCode`, `downloadTaskId`, `downloadStatus`, `downloadApi`, `downloadParams`, and `nextAction`; rows are never returned.
-- **SQL status**: `+get_sql_query_status` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. `--downloadTo` is CLI-only; after `downloadStatus=SUCCESS` it saves the result zip and adds `localFile`. It returns status/progress metadata, `nextAction`, `downloadApi`, and `downloadParams`; rows are never returned.
+- **SQL submit**: `+submit_sql_query` requires `--spaceCode` and exactly one read-only query in `--sql`. `--repoCode` and `--engineType` are optional and default to `te_etl` and `TASK_ENGINE_TRINO`. On success it returns task metadata and, when exposed by Gaia, `downloadRowLimit`; rows are never returned and the result remains platform-bounded.
+- **SQL status**: `+get_sql_query_status` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. `--downloadTo` is CLI-only; after `downloadStatus=SUCCESS` it streams the result zip to a temporary sibling file, publishes it only after completion, and adds `localFile`. It returns status/progress metadata, `nextAction`, `downloadApi`, and `downloadParams`; rows are never returned.
 - **SQL cancel**: `+cancel_sql_query` requires `--spaceCode` and `--downloadTaskId`. `--requestId` is optional trace-only. It returns cancellation request metadata such as `downloadCancelStatus`.
 - **engineType**: `TASK_ENGINE_TRINO` (default, interactive queries) | `TASK_ENGINE_STARROCKS` (high-concurrency analytics)
 - **entityType**: optional `TABLE` or `VIEW` hint. Omit it unless the target type must be forced.

package/skills/ae-engage/SKILL.md

@@ -55,7 +55,7 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md` (**Webhook vs Client differ**: `url` = HTTP vs scene key; custom params `user:` vs `user:`/`client:`), `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: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — semantic `definitionRequest` (Analysis condition shape); do not pass `targetClusterQp`/`qp`; preflight props (stop + list if missing); 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` |
+| **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-user-detail-export.md`, `task-indicator-user.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
 | **Operation activity** | Campaign activity management and delivery trends by activity, topic, or standalone task | `engage-activity` | `references/activity-activity.md` | `activity-data-detail.md`, `activity-topic.md`, `activity-task.md`, `activity-approval.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 |
 
@@ -178,11 +178,16 @@ ae-cli engage-task task submit-approval --project-id 1 --task-id task_123
 # Query task reports through the Hermes inline task-data capabilities
 ae-cli engage-task effect query --project-id 1 --task-id task_123 --start-time 2026-04-01 --end-time 2026-04-07 --metric-id-list '["metric_1"]'
 ae-cli engage-task data-detail query --project-id 1 --task-id task_123 --detail-type time --start-time 2026-04-01 --end-time 2026-04-07
+ae-cli engage-task indicator-user sql --project-id 1 --task-id task_123 --indicator main --start-time 2026-04-01 --end-time 2026-04-07
+ae-cli engage-task indicator-user run --project-id 1 --task-id task_123 --indicator secondary --secondary-index 1 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100
+ae-cli engage-task indicator-user export --project-id 1 --task-id task_123 --indicator metric --metric-id metric_1 --source metric --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv
 
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
 `references/task-metric-detail.md`, or `references/task-experiment-report.md` before invocation.
+Before using `engage-task indicator-user`, read `references/task-indicator-user.md`; its grouping,
+indicator, summary/detail, metric, experiment, and timezone flags have conditional compatibility rules.
 
 ### 3. config
 
@@ -214,6 +219,7 @@ ae-cli engage-flow version list --project-id 1 --flow-id flow_id_123
 ae-cli engage-flow flow update-remark --project-id 1 --flow-uuid flow_uuid_123 --flow-version-desc "Second version"
 ae-cli engage-task operation-log query --project-id 1 --task-id task_id_123
 ae-cli engage-task push-record query --project-id 1 --task-id task_id_123 --page-num 1 --page-size 20
+ae-cli engage-task user-detail export --project-id 1 --task-id task_id_123 --task-instance-id instance_123 --user-status fail --artifact-format csv
 ae-cli engage-task segment-list query --project-id 1 --task-id task_id_123
 ae-cli engage-task group list --project-id 1
 ae-cli engage-task metric list --project-id 1 --task-id task_id_123
@@ -502,6 +508,8 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/version-list.md` (`engage-flow.version.list`)
 - `references/flow-update-remark.md` (`ae-cli engage-flow flow update-remark`; capability `engage-flow.version.update-remark`)
 - `references/push-record-query.md` (`engage-task.push-record.query`)
+- `references/task-user-detail-export.md` (`engage-task user-detail export`; capability `engage-task.user-detail.export`)
+- `references/task-indicator-user.md` (`engage-task indicator-user {sql,run,export}`; capabilities `engage-task.indicator-user.{sql,run,export}`)
 - `references/segment-list-query.md` (`engage-task.segment-list.query`)
 - `references/group-list.md` (`engage-task.group.list`)
 - `references/task-delete.md` (`engage-task.task.delete`)
@@ -520,7 +528,7 @@ This split documentation structure is easier to extend later, because commands w
 
 ### task
 
-`operation-log query` / `push-record query` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task submit-approval` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` / `effect query` / `data-detail query` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
+`operation-log query` / `push-record query` / `user-detail export` / `indicator-user sql` / `indicator-user run` / `indicator-user export` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task submit-approval` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` / `effect query` / `data-detail query` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
 
 ### query
 

package/skills/ae-engage/references/flow-metric-user.md

@@ -109,7 +109,8 @@ ae-cli engage-query query cancel --run-id <run_id>
 ## Output shape
 
 - `run` returns `rows`, `total`, and `column_meta`.
-- `export` writes one row per matched user. The primary column is usually `#user_id`.
+- `export` writes one row per matched user with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
 
 ## Common mistakes
 

package/skills/ae-engage/references/flow-node-metric-user.md

@@ -113,7 +113,8 @@ ae-cli engage-query query cancel --run-id <run_id>
 ## Output shape
 
 - `run` returns `rows`, `total`, and `column_meta`.
-- `export` writes one row per matched user. The primary column is usually `#user_id`.
+- `export` writes one row per matched user with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
 
 ## Common mistakes
 

package/skills/ae-engage/references/flow-node-user.md

@@ -113,7 +113,8 @@ ae-cli engage-query query cancel --run-id <run_id>
 ## Output shape
 
 - `run` returns `rows`, `total`, and `column_meta`.
-- `export` writes one row per matched user. The primary column is usually `#user_id`.
+- `export` writes one row per matched user with `#user_id`, `#account_id`, and `#distinct_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
 
 ## Common mistakes
 

package/skills/ae-engage/references/task-indicator-user.md

@@ -0,0 +1,104 @@
+# engage-task indicator-user
+
+Build SQL, query inline users, or export the users behind an engagement-task report indicator.
+
+> Capability ids: `engage-task.indicator-user.sql`, `engage-task.indicator-user.run`, and `engage-task.indicator-user.export` · Domain: `engage` · Risk: read-only.
+
+## Commands
+
+```bash
+# Build and validate SQL without executing it
+ae-cli engage-task indicator-user sql \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator main \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
+
+# Query a bounded inline user list
+ae-cli engage-task indicator-user run \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator secondary \
+  --secondary-index 2 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100
+
+# Export a custom metric's users
+ae-cli engage-task indicator-user export \
+  --project-id 1 \
+  --task-id task_123 \
+  --indicator metric \
+  --metric-id metric_1 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv
+```
+
+Use `sql` to obtain the generated user-detail SQL, `run` for a small inline result, and `export` for a downloadable full result.
+
+## Required input
+
+All commands require `--project-id`, `--task-id`, `--indicator`, `--start-time`, and `--end-time`.
+
+Dates use `yyyy-MM-dd`, and the start date must not be later than the end date. The task must exist under the specified project.
+
+`--indicator` maps to the report population as follows:
+
+| Value | Report population | Usage note |
+|---|---|---|
+| `original_trigger` | Original triggered users | Triggered tasks only |
+| `plan` | Planned-delivery users | Task delivery funnel |
+| `actual_trigger` | Actual-trigger/actual-delivery users | Task delivery funnel |
+| `trigger_success` | Successfully triggered/delivered users | Task delivery funnel |
+| `view` | Users who produced the configured view event | Requires view-event data |
+| `click` | Users who produced the configured click event | Requires click-event data |
+| `main` | Main conversion-indicator users | Combine with `--retention-type` for converted/lost users |
+| `secondary` | Nth secondary conversion-indicator users | Requires `--secondary-index` |
+| `metric` | Users behind a configured custom metric | Requires `--metric-id` |
+| `click_activate` | Click activation users | Used in experiment activation reports |
+| `main_activate` | Main-indicator activation users | Used in experiment activation reports |
+| `secondary_activate` | Nth secondary-indicator activation users | Requires `--secondary-index`; used in experiment activation reports |
+
+## Conditional input
+
+- `secondary` and `secondary_activate` require `--secondary-index 1..10`. Other indicators reject this flag.
+- `metric` requires `--metric-id`; obtain the ID with `ae-cli engage-task metric list`. Other indicators reject this flag.
+- `main`, `secondary`, `main_activate`, and `secondary_activate` must reference a conversion indicator configured on the task.
+- `click_activate`, `main_activate`, and `secondary_activate` use `source=experiment` and `group-by=experiment`; explicitly supplied values must also be `experiment`. The task must have an activation event configured. `click_activate` additionally requires a click-event experiment.
+- Non-metric indicators grouped by experiment use `source=experiment`, and the task must be an experiment task. Metric indicators continue to use `source=metric`.
+- Explicit `--source experiment` always requires an experiment task, even with date, batch, or trigger grouping.
+- `--group-by experiment --is-summary false` requires `--exp-group-id`. The `plan` indicator never accepts `--exp-group-id`; when grouped by experiment, it supports summary queries only.
+- `--group-by batch` is supported only by non-triggered tasks. A non-summary batch segment requires `--task-instance-id`.
+- `--group-by trigger` and `original_trigger` are supported only by triggered tasks.
+- `--retention-type lost` supports `actual_trigger`, `trigger_success`, `view`, `click`, `main`, and `secondary`; it also supports `plan` for triggered tasks. It is rejected for `original_trigger`, `metric`, all activate indicators, and `plan` on non-triggered tasks.
+
+## Optional report context
+
+- `--group-by` selects `batch`, `date`, `trigger`, or `experiment`; it defaults to `experiment` for activate indicators and `date` otherwise.
+- `--is-summary` defaults to `true`. Set it to `false` when reproducing a drilled-down batch or experiment row.
+- `--retention-type` selects `retention` or `lost`; the default is `retention`. See the supported combinations above.
+- `--source` selects `task`, `experiment`, or `metric`. It defaults to `metric` for metric indicators, `experiment` for activate indicators or experiment grouping, and `task` otherwise.
+- `--task-instance-id` narrows a non-triggered task to one execution instance.
+- `--exp-group-id` narrows an experiment report to one group.
+- `--push-language-code`, `--user-time-zone`, and `--show-time-zone` reproduce the corresponding task-report filters. Copy their values from the report context when needed.
+- `--push-language-code` accepts `all`, `default`, `ar`, `az`, `bs`, `ca`, `zh-Hans`, `zh-Hant`, `hr`, `cs`, `da`, `nl`, `en`, `et`, `fi`, `fr`, `ka`, `bg`, `de`, `el`, `hi`, `he`, `hu`, `id`, `it`, `ja`, `ko`, `lv`, `lt`, `ms`, `nb`, `fa`, `pl`, `pt`, `pa`, `ro`, `ru`, `sr`, `sk`, `es`, `sv`, `th`, `tr`, `uk`, or `vi`.
+- `--user-time-zone` accepts `all` or a decimal offset from `-12` through `14` that exists in the task's execution details. An unavailable value is rejected instead of falling back to all users.
+- `--show-time-zone` accepts offsets from `-12` through `14`. Omit it or pass `99` to use the backend server's default time zone.
+
+## Execution input and output
+
+- `sql` returns `sql` and `indicator` and does not execute the query.
+- `run` accepts `--request-id`, `--limit`, and `--timeout-seconds`. The default limit is `100` and the maximum is `1000`; the default timeout is `120` seconds and the maximum is `180` seconds. It returns `#user_id`, `#account_id`, and `#distinct_id` for each user.
+- `export` accepts `--request-id`, `--artifact-format jsonl|csv`, and `--timeout-seconds`. The default format is `jsonl`; the maximum timeout is six hours. It returns `run_id` and `artifact_id`.
+- For cross-user data sources, `#account_id` and `#distinct_id` are empty strings.
+
+Use the query lifecycle commands to inspect and download an export:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download --artifact-id <artifact_id> --output ./task-indicator-users.csv.gz
+```
+
+`--artifact-format` controls the exported file. The global `--format json|table` only controls CLI display output.

package/skills/ae-engage/references/task-user-detail-export.md

@@ -0,0 +1,31 @@
+# engage-task user-detail export
+
+Export user details for one execution instance of a non-triggered engagement task.
+
+> Capability id: `engage-task.user-detail.export` · Domain: `engage` · Output: asynchronous artifact.
+
+```bash
+ae-cli engage-task user-detail export \
+  --project-id <project-id> \
+  --task-id <task-id> \
+  --task-instance-id <task-instance-id> \
+  --user-status fail \
+  --artifact-format csv
+```
+
+`--user-status` accepts English values only. The statuses below follow the task funnel from audience filtering to the final delivery result:
+
+1. `deduplicate` — users removed because the configured push ID is duplicated.
+2. `frequency_control` — users removed by the task-level frequency-control rules.
+3. `sample` — users excluded by experiment-layer sampling before planned delivery.
+4. `push_plan` — users retained in the planned-delivery population after deduplication, frequency control, and sampling.
+5. `fatigue_control` — planned users removed by channel-level fatigue-control rules.
+6. `push_actual` — users retained in the actual-delivery population after fatigue control.
+7. `exp_skip_push` — actual-delivery users intentionally not sent because their experiment control group is configured to skip delivery.
+8. `success` — users for whom delivery completed successfully.
+9. `fail` — users for whom delivery was attempted but failed. This is the default value.
+
+Use `--task-exec-detail-id` to narrow an instance to one execution detail. Triggered tasks are not supported in this version.
+Each artifact contains at most 1,000,000 rows, matching the Hermes task export safety boundary.
+
+The command returns `run_id` and `artifact_id`. Use `ae-cli engage-query run inspect` to inspect progress and `ae-cli engage-query artifact download` to download the completed artifact.

package/skills/ae-generate-tracking-plan/SKILL.md

@@ -21,7 +21,8 @@ description: "Interactive generation of an AE tracking plan and upload. Trigger
 | 埋点模板 | Tracking Plan Template | Pre-built industry/genre xlsx templates |
 | 方案名称 | Plan Name | User-facing plan identifier |
 | 应用场景 | Application Scenario | One-sentence description of what the app does |
-| 素材来源 | Source Material Type | prd / chat / codebase / template |
+| 素材来源 | Source Material Type | prd / chat / codebase / template / data |
+| 数据样本 / 文件画像 | Data Sample / File Profile | Column→property mapping source from an `ae-data-integration` inspect profile (`source_type: data`) |
 | 业务维度 | Business Dimension | Revenue model, core loop, functional entries, currency system |
 | 收入模型 | Revenue Model | IAA / IAP / mixed / subscription / commission |
 | 核心循环 | Core Loop | Core gameplay loop (e.g. "grind stages → earn coins → gacha for heroes") |
@@ -115,8 +116,9 @@ Choose your source material (up to 2):
 3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
 4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 5 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template
+6 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
 
-Reply with number(s), e.g. 1,5 or 4. Select up to 2.
+Reply with number(s), e.g. 1,5 or 4. Select up to 2 (option 6 is single-source).
 ```
 
 If in a sandbox environment, ask exactly:
@@ -128,8 +130,9 @@ Choose your source material (up to 2):
 2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
 3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
 4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
+5 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
 
-Reply with number(s), e.g. 1,4 or 3. Select up to 2.
+Reply with number(s), e.g. 1,4 or 3. Select up to 2 (option 5 is single-source).
 ```
 
 Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
@@ -153,8 +156,10 @@ Based on user selection, determine source material type and record to `meta.sour
 | Codebase only | `codebase` | Scan source code, extract events/properties from business logic |
 | Template only | `template` | Provide built-in template selection |
 | Existing plan only | `existing_plan` | Import xlsx as baseline (see "Modify Existing Tracking Plan Flow" below) |
+| Data sample only | `data` | Read the inspect profile (`ae-local-data-profile/v1`), map columns → events/properties (see "Data-path (source_type = data)" below) |
 | Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: existing_plan → template → codebase → prd → chat) |
 | Existing plan + Pre-built template | **NOT allowed** | Both provide event baselines; semantic conflict |
+| Data sample + any other | **NOT allowed** | Data sample is a standalone single-source path |
 
 **Follow-up questions** (ask in follow-up order defined in Multi-Source Combination Rules below):
 - Product doc → if not in a sandbox environment, ask exactly:
@@ -184,6 +189,7 @@ Based on user selection, determine source material type and record to `meta.sour
 - Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic
 - Pre-built template → display matching templates for user confirmation
 - Modify existing tracking plan → ask **"Please provide the xlsx file path of your existing tracking plan"**, then follow the flow below
+- Data sample → ask **"Please provide the path of the inspect profile JSON (or the run directory containing it)"**, then read the `ae-local-data-profile/v1` product and follow the "Data-path (source_type = data)" flow below
 
 **Modify Existing Tracking Plan Flow** (when user selects this option):
 
@@ -363,6 +369,49 @@ Use the baseline source's inference method as primary. Supplementary sources (es
 }
 ```
 
+### Data-path (source_type = data) — condensed single-gate flow
+
+When the user selects the **Data sample / file profile** option (`source_type = data`), the flow diverges from the standard 5-item anchor. This path **maps table columns → events/properties** instead of inventing events from business understanding, and uses a **single confirmation gate** instead of the 5-segment Refine loop.
+
+**What to skip** (only Item 1 — Application Scenario and Item 2 — Data sample are collected):
+
+- **Item 3 (SDK Integration Config)** → skip. `meta.sdk_integration_mode = "none"` (data ingested via RESTful / LogBus / DataX, no SDK). No SDK auto-track events are injected (Phase 1.4 already skips `none`).
+- **Item 4 (User Identity System)** → skip the visitor-ID strategy question. Derive `meta.user_identity` from the inspect profile's `identity_candidates` instead (e.g. a `distinct_id` / `account_id` column), `account_id_source: "user_account"` when an account column exists, otherwise `"none"`.
+- **Business Dimension confirmation** → skip. Mapping is driven by columns, not by revenue model / core loop. `meta.business_dimension` stays empty.
+
+**Draft construction (replaces Phase 1.1/1.2/1.3 for the data path)**:
+
+1. **Read the inspect profile**: the `ae-local-data-profile/v1` JSON product (columns / types / samples / UE eligibility / mapping confidence). If it is not present or is stale, re-run `ae-cli data-integration inspect` for the source file first.
+2. **Event model determination** (reuse UE routing): single-table single-event `track` / single-table multi-event (event-name column) / single-table `user_set` / mixed. The agent may propose **splitting one table into multiple events** (e.g. an ad table split by `campaign_type` into `ad_show` / `ad_click`); such proposals MUST be confirmed in the gate.
+3. **Column → property mapping draft**:
+   - Identify system columns first: time field, `distinct_id` / `account_id`, event-name column, user-property-name column.
+   - Map the remaining columns to event properties / user properties / super properties.
+   - Naming: `snake_case` event/property names + `display_name` + `desc` + `event_tag` (language follows the user's input).
+   - Type inference: CSV columns default to `string`; infer `number` / `bool` / `datetime` / enum from field name + value distribution + business doc/prompt priors. **Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate** (do not ask column-by-column beforehand).
+4. **Single confirmation gate** (replaces Phase 2, see below).
+5. **Merge with existing plan** (reuse Phase 4.1/4.2 conflict detection).
+6. **Persist**: `.ae-cli/draft.json` → xlsx → upload (`sdk_integration_mode = none`).
+
+**Single confirmation gate (one round, one summary table)**:
+
+Present ONE merged table covering all of the following in a single message, then wait for a single reply:
+
+- **Event list**: `event_name` / `display_name` / `desc` / `event_tag` / `platform`.
+- **Property list**: `name` / `display_name` / `type` / `desc` / `source`, with uncertain types highlighted (marked "to-confirm").
+- **Field scope**: default to plan-internal fields only; include a **full-import switch** for bringing all source columns in.
+- **Unrecognized / dirty data handling**: how unmapped columns, null values, and unparseable rows are treated.
+- **Same-name property type conflicts**: flagged inline in the gate (see Phase 4.2 Type A).
+
+User replies once: `ok` (accept all), or targeted edits — rename / retype / add / remove individual columns or events. After the gate is confirmed, jump to Phase 3 (project token) then Phase 4 (merge + upload); do NOT enter the 5-segment Refine loop.
+
+**dry-run mode**:
+
+When the user requests dry-run (or the caller passes `data-integration plan --dry-run`), produce the draft preview + column→property mapping summary ONLY:
+
+- Show the single confirmation gate table (events + properties + field scope + unrecognized-data handling) and the mapping result, but do NOT write `.ae-cli/draft.json`.
+- Do NOT generate xlsx, do NOT archive to `plans/`, do NOT upload to AE.
+- State explicitly that nothing was persisted; the user can approve a real run afterwards.
+
 ### Item 3 — SDK Integration Config (client + server combined)
 
 Ask: **"What is your client platform? (multi-select OK, e.g. Android + iOS) Will you integrate a server-side SDK?"**
@@ -822,6 +871,8 @@ AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<templ
 
 ## Phase 2 — Refine (5-segment loop)
 
+> **Data path (`source_type = data`)**: skip this 5-segment loop entirely — use the single confirmation gate defined in "Data-path (source_type = data)" instead.
+
 In order, one conversation round per segment:
 
 1. **sdk_config (SDK config + User identity, combined)** — Show SDK integration mode, platform/language, visitor ID strategy, account ID source, corresponding SDK calls

package/skills/ae-metadata/SKILL.md

@@ -83,4 +83,3 @@ ae-cli analysis input-file purpose list --project-id 1
 ## Related Skills
 
 - **`ae-analysis`**: `analysis-meta event get` / `analysis-meta property get` for detail, and `analysis-meta event list` / `analysis-meta property list` to discover names.
-- **Dev workflow**: `.cursor/skills/te-cli-capability-gateway` — inspect gateway schema when adding new metadata capabilities.

package/skills/ae-metadata/references/metadata_property_dimension_table_bind_existing.md

@@ -18,7 +18,7 @@ ae-cli metadata property bind-existing-dimension-table --project-id <project_id>
 | `--property-scope` | Yes | Property owner table, for example `event` or `user`. |
 | `--data-table-id` | Yes | Existing dimension data table ID. |
 | `--timestamp-join-format` | No | Timestamp join format. |
-| `--dict-columns` | No | Dictionary column names JSON array. |
+| `--dict-columns` | No | Dictionary column names JSON array. The CLI converts each string to the canonical `{"column_name":"..."}` object required by the capability. |
 
 ## Decision Rules