@thinkingai/ae-cli 1.0.30 → 6.0.16

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

@@ -26,7 +26,7 @@ Domain: **Dashboard management**
 ## Command
 ```bash
 ae-cli analysis +query_dashboard_report_data --project_id <project_id> --dashboard_id 1
-ae-cli analysis +query_dashboard_report_data --project_id <project_id> --dashboard_id 1 --filters '{}' --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --use_cache true --report_ids '[1001]'
+ae-cli analysis +query_dashboard_report_data --project_id <project_id> --dashboard_id 1 --filters '{}' --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --use_cache true --report_ids '[1001]' --request_id mcp_ffffffffffffffffffffffffffffffff --timeout_minutes 8
 ae-cli analysis +query_dashboard_report_data --dry-run
 ```
 
@@ -41,6 +41,8 @@ ae-cli analysis +query_dashboard_report_data --dry-run
 | `--time_granularity` | No | Optional time granularity used to override the report default. Supported values: minute, minute5, minute10, hour, day, week, month, quarter, year, total. |
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--report_ids` | No | Optional list of report IDs. If omitted, all reports in the dashboard are queried. |
+| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
 
 ## Decision Rules
 - `filters` cannot be written from experience alone: it must satisfy both the filter schema and the project metadata constraints.
@@ -48,6 +50,7 @@ ae-cli analysis +query_dashboard_report_data --dry-run
 - On the first run, start with only the required parameters (`--project_id`, `--dashboard_id`) and add optional parameters after confirming the path works.
 - Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--report_ids '[]'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
+- For long-running or cancelable queries, supply your own `--request_id` before starting so `+cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps on Failure

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

@@ -26,7 +26,7 @@ Domain: **Entity Detail Queries**
 ## Commands
 ```bash
 ae-cli analysis +query_entity_details --project_id <project_id> --definition '{}'
-ae-cli analysis +query_entity_details --project_id <project_id> --entity_id 1001 --definition '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true
+ae-cli analysis +query_entity_details --project_id <project_id> --entity_id 1001 --definition '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true --request_id mcp_eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --timeout_minutes 8
 ae-cli analysis +query_entity_details --dry-run
 ```
 
@@ -39,15 +39,18 @@ ae-cli analysis +query_entity_details --dry-run
 | `--properties` | No | Optional display properties JSON, for example `[{"columnName":"#user_id","tableType":"0"},{"columnName":"device_id","tableType":"0"}]`. If provided, property names should come from `analysis_meta +list_properties` in the same `project_id`. |
 | `--sort_by` | No | Optional sort field                                                                                                                                                                                                                     |
 | `--sort_order` | No | Optional sort order. Supported values: asc and desc                                                                                                                                                                                     |
-| `--limit` | No | Optional result limit. Default: 1000, maximum: 100000                                                                                                                                                                                         |
+| `--limit` | No | Optional result limit. Default: 1000, maximum: 10000                                                                                                                                                                                         |
 | `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8                                                                                                                                                                                               |
 | `--use_cache` | No | Whether to use cache. Default: true                                                                                                                                                                                                     |
+| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
 
 ## Decision Rules
 - `definition` / `properties` cannot be written by hand based on experience alone: they must satisfy both the schema structure and the project's real metadata.
 - `list_events` / `list_properties` must be learned from the corresponding reference docs before calling them.
 - For the first run, it is recommended to pass only the required parameters (`--project_id`, `--definition`) and add optional parameters after confirming the chain works.
 - Wrap JSON parameters in single quotes (for example `--definition '{}'`, `--properties '{}'`) to avoid shell escaping issues.
+- For long-running or cancelable queries, supply your own `--request_id` before starting so `+cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Step After Failure

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

@@ -25,7 +25,7 @@ Domain: **Event detail queries**
 ## Command
 ```bash
 ae-cli analysis +query_event_details --project_id <project_id> --event_name login --start_time '2026-04-08 00:00:00' --end_time '2026-04-08 23:59:59'
-ae-cli analysis +query_event_details --project_id <project_id> --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true
+ae-cli analysis +query_event_details --project_id <project_id> --event_name login --relative_date_range 0-7 --filters '{}' --properties '{}' --sort_by time --sort_order desc --limit 20 --zone_offset 8 --use_cache true --request_id mcp_dddddddddddddddddddddddddddddddd --timeout_minutes 8
 ae-cli analysis +query_event_details --dry-run
 ```
 
@@ -44,6 +44,8 @@ ae-cli analysis +query_event_details --dry-run
 | `--limit` | No | Optional result limit. Default: 1000 |
 | `--zone_offset` | No | Time zone offset. For example, UTC+8 is 8 |
 | `--use_cache` | No | Whether to use cache. Default: true |
+| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
+| `--timeout_minutes` | No | Query timeout in minutes. If omitted, 30 minutes is used. |
 
 ## Decision Rules
 - `filters` / `properties` cannot be written from experience alone: they must satisfy both the schema structure and the project metadata constraints.
@@ -51,6 +53,7 @@ ae-cli analysis +query_event_details --dry-run
 - On the first run, start with only the required parameters (`--project_id`, `--event_name`) and add optional parameters after confirming the path works.
 - Wrap JSON parameters in single quotes (for example `--filters '{}'`, `--properties '{}'`) to avoid shell escaping issues.
 - When dates/time ranges are involved, first verify with a short range, then gradually expand the range.
+- For long-running or cancelable queries, supply your own `--request_id` before starting so `+cancel_query` can cancel by the same ID if the caller or user stops waiting. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running; call `+cancel_query --request_id <same value>` with the preset ID. The auto-generated requestId is not available when the HTTP request fails before a response. The value must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`.
 - For cross-project troubleshooting, first confirm whether `--project_id` matches the current permissions and target environment.
 
 ## Next Steps on Failure

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

@@ -29,7 +29,7 @@ Domain: **Report Management**
 ## Commands
 ```bash
 ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]'
-ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --filters '{}' --group_by '[]' --request_id demo --use_cache true --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --timeout_minutes 8
+ae-cli analysis +query_report_data --project_id <project_id> --report_ids '[1001]' --filters '{}' --group_by '[]' --request_id mcp_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --use_cache true --start_date 2026-04-08 --end_date 2026-04-08 --time_granularity day --timeout_minutes 8
 ae-cli analysis +query_report_data --dry-run
 ```
 
@@ -40,7 +40,7 @@ ae-cli analysis +query_report_data --dry-run
 | `--report_ids` | Yes | List of report IDs |
 | `--filters` | No | Optional filter JSON. If provided, MUST follow `+get_filter_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
 | `--group_by` | No | Optional group-by JSON array. If provided, MUST follow `+get_groupby_schema`, and referenced fields must come from `analysis_meta +list_properties` in the same `project_id`. |
-| `--request_id` | No | Optional unique request ID. Generated automatically if omitted. |
+| `--request_id` | No | Optional unique request ID used for tracking and cancellation. If provided, it must use `mcp_<32 lowercase hex UUID>`, for example `mcp_0123456789abcdef0123456789abcdef`. For long-running or cancelable queries, provide this before starting the query so it can be cancelled later with `+cancel_query --request_id <same value>`, even if the caller stops waiting before the tool returns. If `fetch failed`, HTTP timeout, or caller timeout happens, the backend query may still be running. The auto-generated requestId is not available when the HTTP request fails before a response, so preset `requestId` is required for proactive cleanup. Generated automatically if omitted. The response `metadata.requestId` can also be passed to `cancel_query` when the query is no longer needed. |
 | `--use_cache` | No | Whether to use cache. Default: true |
 | `--start_date` | No | Optional start date in yyyy-MM-dd format |
 | `--end_date` | No | Optional end date in yyyy-MM-dd format |

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

@@ -1,12 +1,14 @@
 ---
 name: ae-analysis-global
 version: 1.0.0
-description: "Overlay rules for AE/TE analysis global multi-cluster mode. Use only when ae-cli config cluster-mode status reports sw_cfg_enable_global_query=true. This skill supplements ae-analysis; it does not replace it."
+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."
 ---
 
 # 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 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

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

@@ -0,0 +1,132 @@
+---
+name: ae-analysis-intent
+description: TE data analysis skill for metric checks, report/dashboard queries, SQL analysis, funnel/retention/path analysis, user drilldown, detail queries, anomaly diagnosis, and alert configuration. Trigger this skill whenever the user asks to check data, analyze trends, explain metric changes, or export evidence. Always use ae-cli first; only fall back to te-mcp when ae-cli has no matching capability or repeatedly fails for confirmed non-parameter reasons.
+---
+
+# TE Analysis Skill
+
+## Goals
+
+- Help users locate the correct data assets: events, properties, metrics, reports, dashboards, models.
+- Produce reproducible query results through command-driven execution first.
+- Provide trend interpretation, anomaly assessment, evidence, and actionable next steps.
+
+## Mandatory Rules
+
+1. **Tool priority**
+   - First priority: `ae-cli`.
+   - Second priority: `te-mcp`, only when ae-cli has no matching capability or repeatedly fails for confirmed non-parameter reasons.
+   - Builder validation errors, missing parameters, or `need_clarification` are not fallback reasons.
+
+2. **`project_id` gate**
+   - Confirm `project_id` before any project-scoped query.
+   - If the user does not provide it and no verified project context exists, ask first. Do not guess.
+
+3. **Ad-hoc analysis QP routing**
+   - For `event`, `retention`, `funnel`, and `prop_analysis`, use the matching QP builder first.
+   - Do not call `get_analysis_query_schema`, `list_events`, `list_properties`, `list_metrics`, or `get_metric` before these builders.
+   - Only call `query_adhoc` when the builder returns `status=generated`.
+   - If the builder returns `need_clarification`, `invalid_argument`, `unsupported_feature`, or `validation_error`, stop and ask/report the structured issue. Do not handcraft QP for these four models.
+   - For `distribution`, `attribution`, `heat_map`, `interval`, `path`, `rank_list`, and `sql`, use the legacy schema/metadata path before constructing QP.
+
+4. **Existing asset first**
+   - Before ad-hoc analysis, search existing reports/dashboards when the request could match a saved business asset.
+   - If a matching report/dashboard exists, query it instead of creating a redundant ad-hoc query.
+   - Skip this only when the user explicitly asks for custom ad-hoc exploration or the saved asset does not cover required filters/groupings.
+
+5. **Pre-check before write operations**
+   - For create/update actions, run with `--dry-run` first whenever possible.
+   - After a successful write, generate and return a resource link with `analysis_common +get_resource_url` when a resource ID is available.
+
+6. **Absolute contribution attribution**
+   - Mandatory: when attributing metric changes to dimensions, use absolute contribution decomposition. Do not judge the primary driver solely by relative change percentage.
+   - See `F. ABSOLUTE_CONTRIBUTION_ATTRIBUTION` in the `ae-analysis` skill for the full algorithm and workflow.
+   - Additive metrics: sort by `|delta_dim_i|`, not by `delta_dim_i / baseline`.
+   - Ratio metrics: separate rate effects from composition effects and report hierarchically.
+   - Self-check: verify that dimension contributions sum to approximately 100% before outputting.
+
+## Capability Routing Rules
+
+1. Check whether ae-cli has a matching command.
+2. If yes, execute with ae-cli.
+3. If ae-cli fails because of missing parameters, bad field types, bad time format, permissions, timeout, or invalid payload, fix and retry ae-cli first.
+4. Fall back to te-mcp only for command-not-found, not-supported/not-implemented, clear capability gap, or repeated non-parameter failures.
+5. When falling back, briefly state why ae-cli cannot satisfy the capability.
+
+## Common ae-cli Capability Map
+
+Command format:
+
+```bash
+ae-cli <service> +<command> [options]
+```
+
+### Project and resource
+
+- List projects: `ae-cli analysis_common +list_projects`
+- Generate resource link: `ae-cli analysis_common +get_resource_url -p <project_id> --resource_type <type> --resource_id <id>`
+
+### Metadata discovery
+
+- Event list: `ae-cli analysis_meta +list_events -p <project_id>`
+- Property list: `ae-cli analysis_meta +list_properties -p <project_id>`
+- Metric list: `ae-cli analysis_meta +list_metrics -p <project_id>`
+- Table columns: `ae-cli analysis +get_table_columns -p <project_id> --catalog hive --schema ta --table <table>`
+
+### Report/dashboard queries
+
+- Report list: `ae-cli analysis +list_reports -p <project_id>`
+- Report definition: `ae-cli analysis +get_report_definition -p <project_id> -r <report_id>`
+- Report data: `ae-cli analysis +query_report_data -p <project_id> --report_ids '[<report_id>]'`
+- Dashboard list: `ae-cli analysis +list_dashboards -p <project_id>`
+- Dashboard detail: `ae-cli analysis +query_dashboard_detail -p <project_id> -d <dashboard_id>`
+- Dashboard report data: `ae-cli analysis +query_dashboard_report_data -p <project_id> -d <dashboard_id>`
+
+### Ad-hoc analysis
+
+Builder-supported models:
+
+- Event QP builder: `ae-cli analysis +build_event_analysis_qp ...`
+- Retention QP builder: `ae-cli analysis +build_retention_analysis_qp ...`
+- Funnel QP builder: `ae-cli analysis +build_funnel_analysis_qp ...`
+- Property analysis QP builder: `ae-cli analysis +build_prop_analysis_qp ...`
+- Execute query: `ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<builder_qp>'`
+
+Legacy/manual models:
+
+- Schema: `ae-cli analysis +get_analysis_query_schema --model_type <distribution|attribution|heat_map|interval|path|rank_list|sql>`
+- Execute query: `ae-cli analysis +query_adhoc -p <project_id> --model_type <model_type> --qp '<manual_qp>'`
+
+### Drilldown and details
+
+- User drilldown: `ae-cli analysis +drilldown_users ...`
+- User event sequence: `ae-cli analysis +drilldown_user_events ...`
+- Entity details: `ae-cli analysis +query_entity_details ...`
+- Event details: `ae-cli analysis +query_event_details ...`
+
+## Standard Execution Flow
+
+1. Clarify scope: KPI, model type, time window, dimensions, filters, and comparison baseline.
+2. Confirm `project_id`.
+3. Search existing reports/dashboards if the request may map to a saved business asset.
+4. If a matching asset exists, query report/dashboard data.
+5. If no existing asset is used:
+   - `event` / `retention` / `funnel` / `prop_analysis`: builder -> `query_adhoc`
+   - `distribution` / `attribution` / `heat_map` / `interval` / `path` / `rank_list` / `sql`: schema/metadata -> handcrafted QP -> `query_adhoc`
+6. For anomalies, slice by channel/version/time/cohort first, then drill down to users and event chains when needed.
+   - Strictly apply absolute contribution decomposition: compute each dimension's absolute delta and contribution share, then sort by absolute delta magnitude.
+7. Return conclusion, key evidence, likely causes, limitations, and next actions.
+
+## Output Requirements
+
+- Put the core conclusion first.
+- Include key data points: time, dimension, metric, value, and comparison baseline.
+- Explain trend or anomaly causes with confidence level or validation needs.
+- Provide actionable next-step recommendations.
+- Do not dump raw tables only.
+- If data, definitions, or permissions are insufficient, explicitly state the limitation and ask for the missing input.
+- Attribution output requirements:
+  - State the metric's total change in absolute and percentage terms in the core conclusion.
+  - List dimension contributions sorted by absolute delta descending; each dimension shows dimension value, absolute delta, contribution share, and relative change.
+  - Focus the conclusion on dimensions with the largest contribution share, not the largest relative change.
+  - Self-check that all dimension contribution shares sum to approximately 100%; flag the result if deviation exceeds 5 percentage points.

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

@@ -0,0 +1,242 @@
+---
+name: ae-data-integration-helper
+description: Answers questions about ThinkingData SDK integration and usage, including the LogBus2 data import tool. Trigger words: 怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus / tracking / integration / how to integrate / data import / データ連携 / インテグレーション / 트래킹 / 연동.
+---
+
+# ae-data-integration-helper
+
+> **Conversation language**: This skill document is in English, but **all output to the user MUST be in the user's input language**.
+> Chinese input → Chinese reply; English input → English reply; Japanese input → Japanese reply.
+> If uncertain, default to English.
+> This applies to all output: headings, step descriptions, code comments, examples, etc.
+> **⚠️ CRITICAL: Many reference documents (FAQ, wiki) are in Chinese. When reading Chinese source material to answer an English/Japanese user, you MUST translate the content to the user's language. The source document's language is NOT the user's language. Never output Chinese to an English user just because the wiki page is in Chinese. Use the Terminology Glossary above to map terms accurately.**
+> Do NOT copy Chinese text verbatim from this document into English/Japanese replies.
+
+## Terminology Glossary
+
+| 中文 | English | Notes |
+|------|---------|-------|
+| 埋点 / 数据上报 | Tracking / Data Ingestion | Sending event data to TE |
+| 用户识别规则 | User Identification Rule | distinct_id / account_id mapping |
+| 访客 ID | Visitor ID / Guest ID | Anonymous user before login |
+| 登录 ID | Login ID / Account ID | Identified user after login |
+| 预置属性 | Preset Property | `#device_id`, `#time`, `#ip`, etc. |
+| 系统字段 | System Field | TE built-in fields prefixed with `#` |
+| 事件格式 | 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 |
+| 可更新事件 | 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.) |
+| 实时调试 | Real-time Debug / Debug Mode | Device binding + live data validation |
+| 合规 / 隐私 | Compliance / Privacy | GDPR, privacy policy, SDK data collection rules |
+| 数据导入 | Data Import | LogBus2 / RESTful API / DataX |
+| 缓存上报 | Batch Upload / Buffered Upload | Cache events locally, then upload in batches |
+| 重试策略 | Retry Strategy | Re-upload failed data automatically |
+| 数据加密 | Data Encryption | Encrypt event data before upload |
+| 时间校准 | Time Calibration | Sync device time with server time |
+| 多端上报 | Multi-platform Tracking | Report events from multiple clients/services |
+| 用户割裂 | User Fragmentation | Same user split into multiple TE user profiles |
+| 上报模式 | Upload Mode | Normal / Debug / Debug_Only |
+| LoggerConsumer | LoggerConsumer | Server SDK consumer that writes events to local log files |
+| BatchConsumer | BatchConsumer | Server SDK consumer that uploads events in batches |
+| DebugConsumer | DebugConsumer | Server SDK consumer for debug mode (not for production) |
+
+## When to Trigger
+
+Trigger when a user asks about:
+
+- **Pre-ingestion Preparation**:
+  - User identification rules (distinct_id / account_id / visitor ID / login ID)
+  - Data rules (event format / property types / validation)
+  - Preset properties & system fields (`#device_id`, `#time`, etc.)
+- **Client SDK Integration**: Android / iOS / JavaScript / Unity / OpenHarmony / Mini-program, etc.
+- **Server SDK Integration**: Java / Python / Go / Node.js / PHP / C#, etc.
+- **Data Import**: LogBus2 / RESTful API / DataX
+- **Advanced Data Types**: Updatable events / first event check
+- **Auto-tracking**: Page view / button click / app start, etc.
+- **Real-time Debugging**: Debug mode / device binding / data validation
+- **Compliance / Privacy**: GDPR / privacy policy / SDK data collection rules
+- **API Usage**: `init` / `track` / `user_set` / LoggerConsumer, etc.
+- **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).
+
+## Workflow
+
+### Step 1: Parse the Question
+
+Extract from the user's query:
+
+- **Topic category**:
+  - Pre-ingestion Prep: User identification / data rules / preset properties
+  - Client SDK: Android / iOS / JavaScript / Unity / OpenHarmony / Mini-program, etc.
+  - Server SDK: Java / Python / Go / Node.js / PHP / C#, etc.
+  - Data Import: LogBus2 / RESTful API / DataX
+  - Advanced Data Types: Updatable events / first event check
+  - Auto-tracking: Page view / button click / app start
+  - Real-time Debug: Debug mode / device binding / data validation
+  - Compliance: GDPR / privacy policy / SDK data collection rules
+- **Query type**: Integration method / API usage / configuration / deployment / error / logging
+
+### Step 1.5: Information Gathering
+
+**⚠️ Key principle: When the question is vague, gather information FIRST before answering. Do NOT guess or ramble.**
+
+If the user's question involves any of the following scenarios, **collect critical information before proceeding**:
+
+| Scenario | Must Collect |
+|----------|-------------|
+| "Data not showing up" / "Can't see data" / "Upload successful but nothing in the dashboard" | Upload method (SDK / LogBus / HTTP), data type (event / user property), specific symptom (no data at all / partial data) |
+| "Error" / "Failure" type questions | Full error message, reproduction steps |
+| "Can't connect" / "Unable to upload" | Platform/language used, error symptoms |
+| "How to implement X" | Platform/language used, what X specifically means |
+
+**Ask first, then answer**. Examples:
+- "Data logs show success but the dashboard shows nothing — are you using SDK, LogBus, or HTTP upload?"
+- "Can't connect — which language/platform are you using? Can you share the error message?"
+
+### Step 2: Find Relevant Documentation
+
+**Prefer FAQ documents first** (for quick lookup of specific issues):
+1. Read `skills/ae-data-integration-helper/references/` corresponding FAQ (e.g., `android_sdk_faq.md`, `logbus2_guide.md`, etc.)
+2. FAQ documents cover specific troubleshooting, code examples, parameter tables, and best practices
+
+**Check wiki when FAQ has no answer** (for framework-level and authoritative content):
+1. Read `~/.ae-cli/wiki/te-docs/index.md` to locate document paths
+2. Prefer overview documents under `~/.ae-cli/wiki/te-docs/synthesis/`
+3. For detailed API references, check the corresponding main document under `~/.ae-cli/wiki/te-docs/raw/`
+
+**Commonly used FAQ documents**:
+- `references/android_sdk_faq.md` — Android SDK integration & FAQ
+- `references/ios_sdk_faq.md` — iOS SDK integration & FAQ
+- `references/java_sdk_faq.md` — Java SDK integration & FAQ
+- `references/logbus2_guide.md` — LogBus2 complete configuration guide
+- `references/sdk_usage_notes.md` — Client/server SDK usage notes
+- `references/restful_api_notes.md` — RESTful API usage notes
+- Full list: see `references/index.md`
+
+### Step 3: Read & Summarize
+
+After reading relevant documentation, output in the following format:
+
+```
+## <Topic> (<Platform>)
+
+### Summary
+<1-2 sentence description>
+
+### Integration / Usage Steps
+1. <Step 1>
+2. <Step 2>
+...
+
+### Code Example
+```<language>
+<code>
+```
+
+### Notes / Caveats
+- <Note 1>
+- <Note 2>
+
+### Source Document
+<Prefer wiki document sourceUrl. Language rules:
+  - User interacts in Chinese → provide Chinese doc (lan=zh-CN)
+  - User interacts in other languages → provide English doc (lan=en-US)
+  - Chinese-only SDKs (Mini-program / OpenHarmony / Cocos2d-Lua / LayaAir / Egret) → Chinese only
+  Example: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=xxx>
+(If no sourceUrl, provide local .md file path)
+```
+
+**⚠️ Information Accuracy Rules**:
+- **Only output what is in the documentation**. Do NOT speculate, imagine, or fill in defaults.
+- 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.
+
+### Step 4: Fallback
+
+If neither FAQ nor wiki has relevant content:
+- Provide the official online documentation link: https://docs-v2.thinkingdata.cn
+- Optionally suggest running the `te-wiki-synthesize` skill to generate a new synthesis document.
+
+## Example Conversations
+
+**User**: What is distinct_id and how do I use it?
+
+**Agent**:
+1. Read `references/index.md` to find user identification rule document paths
+2. If `sdk_usage_notes.md` or wiki has relevant sections, read those first
+3. Output in the Step 3 format
+
+**User**: How do I configure LogBus2?
+
+**Agent**:
+1. Read `references/logbus2_guide.md`
+2. Output in the Step 3 format
+
+**User**: Java SDK is losing data — what should I do?
+
+**Agent**:
+1. Read `references/java_sdk_faq.md`, section on "LoggerConsumer data loss risks"
+2. Output in the Step 3 format
+
+**User**: How do I integrate the Android SDK?
+
+**Agent**:
+1. Read `references/android_sdk_faq.md` or `~/.ae-cli/wiki/te-docs/index.md` to find Android SDK path
+2. Read the relevant sections
+3. Output in the Step 3 format
+
+```
+## Android SDK Integration
+
+### Summary
+Android SDK supports both Gradle and manual AAR integration. Gradle is recommended.
+
+### Integration Steps (Gradle)
+1. Add mavenCentral to project-level `build.gradle`:
+   ```groovy
+   repositories { mavenCentral() }
+   ```
+2. Add dependency to module-level `build.gradle`:
+   ```groovy
+   dependencies {
+       implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
+   }
+   ```
+3. Initialize SDK:
+   ```java
+   TDAnalytics.init(this, SERVER_URL, APPID);
+   ```
+
+### Source Document
+~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md
+```
+
+**User**: How do I enable real-time debugging for Android SDK?
+
+**Agent**:
+1. Read `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/debugging-and-logging.md`
+2. Output in the Step 3 format
+
+## Internal Reference
+
+**FAQ Documents** (check first):
+- `references/index.md` — All FAQ document index
+- `references/android_sdk_faq.md` — Android SDK FAQ
+- `references/logbus2_guide.md` — LogBus2 complete guide
+- `references/sdk_usage_notes.md` — SDK usage notes
+
+**Wiki Documents** (check when FAQ has no answer):
+- `~/.ae-cli/wiki/te-docs/index.md` — All wiki document index
+- `~/.ae-cli/wiki/te-docs/schema.md` — Wiki layout description
+- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md` — User Identification Rules
+- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md` — Data Rules
+- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md` — Preset Properties
+- `~/.ae-cli/wiki/te-docs/raw/advanced-data-type/updated-event.md` — Updatable Event
+- `~/.ae-cli/wiki/te-docs/raw/advanced-data-type/first-event-check.md` — First Event Check
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md` — LogBus2