@thinkingai/ae-cli 1.0.28 → 6.0.16

package/skills/ae-generate-tracking-code/references/autotrack-enum.md

@@ -0,0 +1,183 @@
+# Auto-track Event Enum Reference
+
+> **Terminology**: 自动采集事件 = auto-track event | 枚举值 = enum value | 上报事件名 = reported event name | bit = bit flag | SDK 初始化后开启 = enable after SDK init | 猜测 = guess (prohibited — always lookup from this table)
+
+> Used by `snippet-delivery.md` / `client-sdk-insert.md` when generating auto-track event switch code.
+> **Must copy from wiki docs directly** — do not guess enum values.
+
+---
+
+## Unity SDK（v3.x）— `TDAutoTrackEventType`
+
+| 枚举值 | 上报事件名 | bit |
+|---|---|---|
+| `TDAutoTrackEventType.None` | (禁用) | `0` |
+| `TDAutoTrackEventType.AppStart` | `ta_app_start` | `1 << 0` |
+| `TDAutoTrackEventType.AppEnd` | `ta_app_end` | `1 << 1` |
+| `TDAutoTrackEventType.AppCrash` | `ta_app_crash` | `1 << 4` |
+| `TDAutoTrackEventType.AppInstall` | `ta_app_install` | `1 << 5` |
+| `TDAutoTrackEventType.AppSceneLoad` | `ta_scene_loaded` | `1 << 6` |
+| `TDAutoTrackEventType.AppSceneUnload` | `ta_scene_unloaded` | `1 << 7` |
+| `TDAutoTrackEventType.All` | 全部 | OR 组合 |
+
+**微信小游戏特殊映射**：
+
+| 枚举值 | 上报事件名 |
+|---|---|
+| `TDAutoTrackEventType.AppStart` | `ta_mg_show` |
+| `TDAutoTrackEventType.AppEnd` | `ta_mg_hide` |
+| `TDAutoTrackEventType.AppInstall` | `ta_mg_launch` |
+
+**代码示例**（从 wiki 直接复制）：
+
+```csharp
+// 开启全部自动采集事件
+TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);
+
+// 开启启动和关闭事件的自动采集
+TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);
+```
+
+---
+
+## Android SDK — `TDAnalytics.TDAutoTrackEventType`
+
+| 枚举值 | 上报事件名 |
+|---|---|
+| `TDAnalytics.TDAutoTrackEventType.APP_START` | `ta_app_start` |
+| `TDAnalytics.TDAutoTrackEventType.APP_END` | `ta_app_end` |
+| `TDAnalytics.TDAutoTrackEventType.APP_INSTALL` | `ta_app_install` |
+| `TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN` | `ta_app_view` |
+| `TDAnalytics.TDAutoTrackEventType.APP_CLICK` | `ta_app_click` |
+| `TDAnalytics.TDAutoTrackEventType.APP_CRASH` | `ta_app_crash` |
+
+**代码示例**（从 wiki 直接复制）：
+
+```java
+TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
+    | TDAnalytics.TDAutoTrackEventType.APP_INSTALL | TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN
+    | TDAnalytics.TDAutoTrackEventType.APP_CLICK | TDAnalytics.TDAutoTrackEventType.APP_CRASH);
+```
+
+---
+
+## iOS SDK — `TDAutoTrackEventType`
+
+**⚠️ iOS 枚举名与 Android/Unity 不同，必须使用 iOS SDK 实际的驼峰命名，不得照搬 Android 的 `APP_START` 下划线格式。**
+
+| Objective-C 枚举值 | Swift 枚举值 | 上报事件名 |
+|---|---|---|
+| `TDAutoTrackEventTypeAppStart` | `.appStart` | `ta_app_start` |
+| `TDAutoTrackEventTypeAppEnd` | `.appEnd` | `ta_app_end` |
+| `TDAutoTrackEventTypeAppInstall` | `.appInstall` | `ta_app_install` |
+| `TDAutoTrackEventTypeAppViewScreen` | `.appViewScreen` | `ta_app_view` |
+| `TDAutoTrackEventTypeAppClick` | `.appClick` | `ta_app_click` |
+| `TDAutoTrackEventTypeAppCrash` | `.appCrash` | `ta_app_crash` |
+
+**快捷枚举（开启全部）**：
+
+| Objective-C | Swift |
+|---|---|
+| `TDAutoTrackEventTypeAll` | `.all` |
+
+**Objective-C 代码示例**（从 wiki 直接复制）：
+
+```objc
+// 开启全部自动采集事件（快捷方式）
+[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll];
+
+// 或逐个开启
+[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAppInstall
+    | TDAutoTrackEventTypeAppStart
+    | TDAutoTrackEventTypeAppEnd
+    | TDAutoTrackEventTypeAppViewScreen
+    | TDAutoTrackEventTypeAppClick
+    | TDAutoTrackEventTypeAppCrash];
+```
+
+**Swift 代码示例**：
+
+```swift
+// 开启全部自动采集事件（快捷方式）
+TDAnalytics.enableAutoTrack(.all)
+
+// 或逐个开启
+TDAnalytics.enableAutoTrack([.appStart, .appEnd, .appInstall, .appViewScreen, .appClick, .appCrash])
+```
+
+---
+
+## JavaScript SDK（H5）— `autoTrack` 配置对象
+
+| 配置项 | 说明 |
+|---|---|
+| `autoTrack.pageShow` | 页面显示（对应 `ta_page_show`） |
+| `autoTrack.pageHide` | 页面隐藏（对应 `ta_page_hide`） |
+| `autoTrack.appHide` | App 隐藏（微信小程序） |
+
+**代码示例**（从 wiki 直接复制）：
+
+```js
+import ta from "thinkingdata-browser";
+ta.init({
+  appId: "YOUR_APP_ID",
+  serverUrl: "https://YOUR_SERVER_URL/sync_js",
+  autoTrack: {
+    pageShow: true,
+    pageHide: true,
+  }
+});
+```
+
+**单独开启**（调用 quick）：
+
+```js
+ta.quick("autoTrack");
+```
+
+---
+
+## 微信小程序 SDK — `autoTrack` 配置对象
+
+| 配置项 | 说明 |
+|---|---|
+| `autoTrack.mpLaunch` | 初始化（`ta_mp_launch`） |
+| `autoTrack.mpShow` | 启动（`ta_mp_show`） |
+| `autoTrack.mpHide` | 隐藏（`ta_mp_hide`） |
+| `autoTrack.mpView` | 页面浏览（`ta_mp_view`） |
+| `autoTrack.mpShare` | 转发（`ta_mp_share`） |
+| `autoTrack.mpClick` | 点击（`ta_mp_click`） |
+| `autoTrack.addFavorite` | 收藏（`ta_add_favorite`） |
+
+---
+
+## OpenHarmony SDK — `TDAutoTrackEventType`
+
+| 枚举值 | 上报事件名 |
+|---|---|
+| `TDAutoTrackEventType.APP_START` | `ta_app_start` |
+| `TDAutoTrackEventType.APP_END` | `ta_app_end` |
+| `TDAutoTrackEventType.APP_INSTALL` | `ta_app_install` |
+| `TDAutoTrackEventType.APP_VIEW_SCREEN` | `ta_app_view` |
+| `TDAutoTrackEventType.APP_CLICK` | `ta_app_click` |
+| `TDAutoTrackEventType.APP_CRASH` | `ta_app_crash` |
+
+**代码示例**（从 wiki 直接复制）：
+
+```typescript
+TDAnalytics.enableAutoTrack(context,
+  TDAutoTrackEventType.APP_START | TDAutoTrackEventType.APP_INSTALL
+  | TDAutoTrackEventType.APP_END | TDAutoTrackEventType.APP_VIEW_SCREEN
+  | TDAutoTrackEventType.APP_CLICK | TDAutoTrackEventType.APP_CRASH
+);
+```
+
+---
+
+## Cocos2d-x / CocosCreator / LayaAir / Unreal
+
+游戏引擎 SDK 的自动采集枚举值请直接读取对应 wiki 文档：
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced/automatic-event-tracking.md`
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance/automatic-event-tracking.md`
+- `~/.ae-cli/wiki/te-docs/raw/客户端-sdk/游戏引擎/layaair/进阶指南/自动采集.md`
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced/automatic-event-tracking.md`

package/skills/ae-generate-tracking-code/references/client-sdk-insert.md

@@ -0,0 +1,202 @@
+# Mode A — Client SDK Code Insertion
+
+> **Terminology**: 客户端 SDK = client SDK | 代码插入 = code insertion/injection | 前置检查 = pre-check | 集成方式 = integration method | 埋点 = tracking/event tracking | 业务触发点 = business trigger point | 公共属性 = super property | 用户属性 = user property | 自动采集事件 = auto-track event | 插入位置预览 = insertion site preview | 语言风格校验 = language style check
+
+## ⚠️ Mandatory Pre-checks (do not skip)
+
+**Before inserting code, execute in the following order. Each step must be completed before proceeding to the next:**
+
+### Stage 0: Read SDK Main Document (must complete, never skip)
+
+1. **Read `references/sdk-index.md`** to find the SDK's main document path
+2. **Read the SDK main document's "Integrate SDK" section** to understand:
+   - **npm package name** (e.g. `thinkingdata-browser`, `@thinkingdata/react-native-sdk`)
+   - **import/require statement** syntax
+   - **All integration methods** (e.g. JS SDK has npm / CDN sync / CDN async)
+3. Choose integration method based on project characteristics:
+   - Has `package.json` + build tool → npm integration
+   - Plain HTML / no build tool → CDN method
+4. Read `~/.ae-cli/wiki/te-docs/synthesis/sdk-selection.md` to confirm appType's npm package name and init signature
+5. Read the corresponding cheatsheet (e.g. `js-sdk-cheatsheet.md`) for additional details
+
+**⚠️ Prohibited**: Skipping Stage 0 and writing code directly, guessing integration methods, using unverified CDN URLs
+
+### Stage 0 Mid-point Language Identification (do not skip)
+
+When reading the SDK main document, if it uses multi-language tab format (e.g. `::: el-tab-pane label=Java` / `label=Kotlin` or ` ```java` / ` ```kotlin`), **must confirm the language for the current task**:
+
+- Android docs: identify `label=Java` vs `label=Kotlin` code blocks
+- iOS docs: identify `label=Objective-C` vs `label=Swift` code blocks
+- Other multi-language docs: same principle
+
+**⚠️ Prohibited**: Copying code examples without confirming language, mixing code snippets from different languages.
+
+### Stage 0.5: SDK Integration Confirmation (must execute after Stage 0)
+
+Based on the integration method chosen in Step 3, confirm with user whether SDK is already integrated:
+
+**Integration methods that require code changes (npm / Gradle / CocoaPods / Maven / pip / go get, etc.)**:
+
+```
+Project detected using <integration-method>. Configuration file changes needed to add dependencies.
+
+Should I modify the config file directly to add SDK dependencies?
+- yes → Edit the config file (e.g. package.json / build.gradle / Podfile), then proceed to Stage 1
+- no → Reference the docs below to complete SDK integration, then reply yes to continue
+
+Documentation: <wiki doc path>
+```
+
+- User `yes` → Execute Edit on config file, then proceed to Stage 1
+- User `no` → Display doc path, pause and wait for user completion
+
+**Integration methods that don't require code changes (CDN script tag / UnityPackage / manual file placement, etc.)**:
+
+```
+Project uses <integration-method>. No config file changes needed.
+
+Please reference the docs below to complete SDK integration, then reply yes to continue.
+
+Documentation: <wiki doc path>
+```
+
+Wait for user confirmation, then proceed to Stage 1.
+
+---
+
+## Stage 1: Explore
+1. Grep entry points: `src/main.*`, `src/App.*`, `pages/_app.*`, `index.html`
+2. Grep existing tracking: `ta\.track|thinkingdata|TA\.init|// @tracking`
+3. Grep routing: `react-router|vue-router|next/router`
+4. Grep user state: `(handleLogin|onLogin|signIn|doLogin)` / `(handleLogout|signOut)`
+5. **Grep business trigger points** (finding where to insert track() calls — the correct insertion sites):
+   - Button/click: `(onClick|handleClick|onTap|@click|\.click\()`
+   - Form submit: `(onSubmit|handleSubmit|onFormSubmit)`
+   - Page entry: `(onMounted|onShow|onLoad|componentDidMount|useEffect.*\[.*\])`
+   - Purchase/payment: `(onPurchase|handlePurchase|doPurchase|payOrder)`
+   - Search: `(onSearch|handleSearch|doSearch)`
+   - Custom events: `(emit|trigger|dispatch|sendEvent)`
+- Astro-specific:
+  - Entry: `src/middleware.ts` (SSR middleware, suitable for page_view), `src/layouts/*.astro` (global layout for init), `astro.config.mjs` (integrations)
+  - Client components: `<script>` blocks in `*.astro` files, React/Vue island components with `client:*` directives
+- **For each business trigger found, record its file:line and business meaning** for Stage 2 mapping
+
+## Stage 2: Insertion Plan (markdown table)
+
+**Platform filtering**:
+- xlsx "Platform" value `客户端` / `client` → `platform: "client"` (client-only collection)
+- xlsx "Platform" value `客户端,服务端` / `client,server` → `platform: "both"` (both platforms)
+- xlsx "Platform" value `服务端` / `server` → `platform: "server"` (server-only, do NOT generate in client)
+- Only insert events where `platform === "client"` or `platform === "both"`
+
+**⚠️ Auto-track event handling**:
+- Auto-track events (e.g. `ta_page_view`, `ta_app_crash`, etc.) are automatically collected by the SDK, **do NOT manually insert track() code for them**
+- However, you MUST **enable the corresponding auto-track switch** after SDK initialization for them to take effect
+- ⚠️ **MUST read `references/autotrack-enum.md`** first to look up correct enum values before writing code; never guess (e.g. Unity's `AppStart` ≠ `APP_START`)
+- Mark which auto-track events need to be enabled in the insertion plan for user confirmation in Stage 3
+
+```
+## SDK Initialization
+- File: <path>:<line>
+- Code: init(...) with appId/SERVER_URL
+
+## Auto-track Event Switches (if needed)
+- Enum values: check `references/autotrack-enum.md`, do not guess
+- File: <path>:<line>
+- enableAutoTrack({...}) or quick("autoTrack")
+
+## Super Properties
+- File: <path>:<line>
+- setSuperProperties({...})
+
+## User Properties
+- File: <path>:<line>
+- user_set / user_setOnce / user_add
+
+## Event Group: <tag>
+- <event_name>: <file>:<line> [Business action: <business meaning>]
+  Insertion rationale: <why insert here, e.g. "called after user clicks pay button">
+- ...
+```
+
+**⚠️ Business action mapping is the core of the insertion plan**:
+- Every event must be mapped to a concrete business action (e.g. "user clicks login button", "order submit success callback")
+- Business actions must come from Stage 1 exploration results, never guess
+- If no business trigger point is found for an event, mark it in the plan as `⚠️ No trigger point found; manual confirmation needed`
+
+**⚠️ After Stage 2, MUST show the "Insertion Site Preview"** for user to confirm each event's insertion point matches business expectations:
+
+```
+## Insertion Site Preview
+
+| Event | File Location | Business Action | Confirm |
+|---|---|---|---|
+| payment_success | src/pages/Pay.jsx:42 | User clicks "Confirm Payment" button | ok / change |
+| user_login | src/pages/Login.jsx:28 | User clicks "Login" button | ok / change |
+```
+
+- User `ok` → proceed to Stage 3
+- User says "change" → remap specific events to correct business trigger points
+- **Do not skip this preview and go directly to Stage 3**
+
+After showing, ask user `ok` to enter Stage 3, or "go back to event X to remap".
+
+## Stage 3: Batched Edit
+- Batch 1: SDK init + super properties
+- Batch 2: User properties
+- Batch 3..N: Grouped by `event_tag`
+- Each batch: use Edit tool; print file list + added line count after completion, ask `ok / undo`
+- `undo` → reverse Edit to rollback the batch
+
+## Stage 3.5: ⚠️ Language Style Check (do not skip)
+
+After each batch Edit, perform language style checks on modified files:
+
+| Language | Check Rules |
+|---|---|
+| **Kotlin** | File must not contain `;` (trailing semicolons); fix immediately if found |
+| **Java** | Every statement must end with `;`; fix immediately if missing |
+| **Swift** | Do not use `var` for optional types — use `let` + `?`; do not use `@objc` unless necessary |
+| **Objective-C** | Method calls must use `[self method]` syntax — no `.` calls; must use `nil`, not `null` |
+
+**If language style errors are found**:
+1. Immediately replace with correct syntax
+2. Note in the batch confirmation: `⚠️ Auto-corrected: <error description> → <correct syntax>`
+
+## Stage 4: Summary
+- Print all modified files + newly added events per file
+- Suggest user consider running Mode F (debug)
+
+## Code Style
+- Singleton: create `src/lib/tracking.ts` (if not exists), export `ta` singleton
+- Prefix each track call with `// @tracking <event_name>` comment
+- Do NOT add try/catch
+- Event names / property names strictly from plan, do not modify
+- Astro: SDK init goes in `<script>` block of `src/layouts/BaseLayout.astro`; page_view uses middleware or `Astro.url.pathname` listener
+
+## Pre-check
+- `git status --porcelain` not empty → refuse, prompt user to commit/stash first
+
+## Stage 5: Verification Steps (insert mode only)
+
+**⚠️ Insert mode: debug is off by default. Do not guide user to the Debug page to view data.**
+
+### Verification Steps
+1. **Integrate SDK** (follow steps based on integration method)
+   - **npm / package manager** (JavaScript/React Native/Flutter/uni-app): Run `npm install` or equivalent to install SDK
+   - **Build tool integration** (Unity/Unreal): Add SDK dependency via Package Manager or Epic Games Launcher
+   - **Dependency management** (Android/iOS): Add SDK dependency in `build.gradle` / `Podfile`
+   - **Manual download** (Web H5/Mini-program/Game engine, etc.): Download SDK files and place in project directory
+
+   Reference the official docs in `references/sdk-index.md` for each SDK
+
+2. **Open AE Real-time Data page** (NOT the Debug page)
+   - `https://<host>/#/data/realtime`
+   - Since debug mode is off, data goes through the normal upload pipeline — only the real-time data page can show it
+
+3. **Trigger events by interacting with the app** and check if data appears
+
+### Pre-launch Checklist
+- [ ] Confirm `debug: false` or no debug field in config
+- [ ] SDK correctly integrated (dependencies added / files placed)
+- [ ] Real-time data page shows event uploads

package/skills/ae-generate-tracking-code/references/datax-config.md

@@ -0,0 +1,43 @@
+# Mode D — DataX job.json
+
+> **Terminology**: 数据源类型 = data source type | 连接信息 = connection info | 库表名 = database/table name | 查询条件 = query condition | reader 插件 = reader plugin | columnMapping = column-to-property mapping | push_url = TE receiver URL
+
+## Ask User
+1. Data source type (MySQL / Oracle / PostgreSQL / OSS / HDFS / Other)
+2. Connection info / database & table names / query conditions (or file path)
+
+## Deliverable
+`.ae-cli/output/datax-job.json`:
+
+```json
+{
+  "job": {
+    "content": [{
+      "reader": {
+        "name": "<mysqlreader|oraclereader|...>",
+        "parameter": { "connection": [ { "jdbcUrl": ["<TODO>"], "table": ["<TODO>"] } ], "username": "<TODO>", "password": "<TODO>", "column": ["*"] }
+      },
+      "writer": {
+        "name": "tewriter",
+        "parameter": {
+          "push_url": "<SERVER_URL>",
+          "appid": "<appId>",
+          "eventName": "<from plan>",
+          "columnMapping": { "<db_col>": "<te_prop>" }
+        }
+      }
+    }],
+    "setting": { "speed": { "channel": 2 } }
+  }
+}
+```
+
+`.ae-cli/output/datax-README.md`:
+- Launch: `python datax.py datax-job.json`
+- Prerequisite: DataX runtime environment
+- `<TODO>` checklist
+
+## Generation Steps
+1. Determine the reader plugin name
+2. Fill `eventName` + `columnMapping` using the first event from plan (or user-specified event)
+3. Write both files

package/skills/ae-generate-tracking-code/references/debug-script.md

@@ -0,0 +1,102 @@
+# Mode F — Debug / Validation Script
+
+> **Terminology**: 校验脚本 = validation/debug script | 设备绑定 = device binding | Debug 模式 = debug mode | TDDebugConsumer = debug mode consumer (validates data format, does NOT persist to production) | 实时调试 = real-time debugging | 代表业务事件 = representative business events | SDK 日志打印 = SDK log printing
+
+## Deliverable
+`te-debug.<ext>` single file; used to quickly verify SDK configuration is correct.
+
+---
+
+## Debug Mode Verification
+
+When using debug mode, you must add the debug device ID in AE Admin before data will appear on the AE **Debug Data** page.
+
+### Verification Steps
+
+| Step | Action |
+|---|---|
+| 1 | Add debug device ID in AE Admin: Tracking Management → Debug Data → Add Device |
+| 2 | Run debug script to send test events |
+| 3 | Open AE Debug page: `https://<host>/#/data/debug` |
+| 4 | Filter by `distinct_id` or `device_id` to view uploaded data |
+
+### Common Notes for Client and Server SDKs
+
+- Both use **TDDebugConsumer** (or the platform's equivalent debug mode API)
+- Both require adding device ID in AE Admin to view data on the Debug page
+- On validation failure, the SDK prints error logs or throws exceptions (behavior varies by language)
+
+---
+
+## Debug Mode API by Platform
+
+### Client SDK
+
+| SDK | Debug Mode API | Reference Doc |
+|---|---|---|
+| Unity SDK | `TDConfig config = new TDConfig(appId, serverUrl); config.mode = TDMode.DEBUG; TDAnalytics.Init(config);` | `data-ingestion-guide/client-sdk/game-engine/unity/unity-advanced/debugging-and-logging.md` |
+| Android SDK | `TDConfig config = new TDConfig(this, serverUrl, appId); config.setMode(TDConfig.Mode.DEBUG); TDAnalytics.init(this, config);` | `data-ingestion-guide/client-sdk/android/android-advanced/debugging-and-logging.md` |
+| iOS SDK | `TDConfig *config = [[TDConfig alloc] initWithAppId:appId serverUrl:serverUrl]; config.mode = TDModeDebug; [TDAnalytics startWithConfig:config];` | `data-ingestion-guide/client-sdk/ios/ios-advanced/debugging-and-logging.md` |
+| JavaScript SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `data-ingestion-guide/client-sdk/javascript/javascript-advanced/debugging-and-logging.md` |
+| Mini Program SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `客户端-sdk/小程序小游戏/进阶指南/实时调试.md` |
+| CocosCreator | See doc | `data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance/debugging-and-logging.md` |
+| Cocos2d-x | See doc | `data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced/debugging-and-logging.md` |
+| Unreal SDK | See doc | `data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced/debugging-and-logging.md` |
+| Flutter SDK | See doc | `data-ingestion-guide/client-sdk/cross-platform/flutter/flutter-advanced/debugging-and-logging.md` |
+| React Native | See doc | `data-ingestion-guide/client-sdk/cross-platform/react-native/reactnative-advanced/debugging-and-logging.md` |
+
+### Server SDK
+
+| Language | DebugConsumer API | Reference Doc |
+|---|---|---|
+| Java | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/java/java-advanced/debugging-and-logging.md` |
+| Python | `TDDebugConsumer(serverUrl, appId, device_id="...")` | `data-ingestion-guide/server-sdk/python/python-advanced/debugging-and-logging.md` |
+| Go | `NewDebugConsumerWithDeviceId(serverUrl, appId, false, deviceId)` | `data-ingestion-guide/server-sdk/golang/golang-advanced/debugging-and-logging.md` |
+| Node.js | `ThinkingData.initWithDebugMode(appId, serverUrl, { deviceId: "..." })` | `data-ingestion-guide/server-sdk/nodejs/nodejs-advanced/debugging-and-logging.md` |
+| PHP | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/php/php-advanced/debugging-and-logging.md` |
+| Ruby | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/ruby/ruby-advanced/debugging-and-logging.md` |
+| Erlang | `tddebug_consumer:new(ServerUrl, AppId, DeviceId)` | `data-ingestion-guide/server-sdk/erlang/erlang-advanced/debugging-and-logging.md` |
+| Lua | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/lua/lua-advanced/debugging-and-logging.md` |
+| C | `td_debug_consumer_new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/c/c-advanced/debugging-and-logging.md` |
+
+---
+
+## Skill Generation Checkpoints
+
+When generating a debug script, the skill must:
+
+1. **First read the corresponding SDK's "Real-time Debug" doc** (see reference doc paths below) to confirm the SDK's debug mode API and usage (the table above is an index reference only; actual usage may differ)
+2. Use the corresponding platform's **TDDebugConsumer** or debug mode API
+3. Set `deviceId` (e.g. `claude-test-device`) for AE Admin device registration
+4. Read `SERVER_URL` and `appId` from plan (NOT web host)
+5. Pick 3 representative business events from plan (if object array properties exist, construct them fully)
+6. Recommend enabling SDK log printing (for easier troubleshooting)
+7. File name must match class name (e.g. Unity: `TEDebugScript.cs`)
+
+### Post-delivery Prompt
+
+**Platform filtering notes**:
+- xlsx "Platform" column values map to `platform` field:
+  - `客户端` / `client` → `platform: "client"`
+  - `服务端` / `server` → `platform: "server"`
+  - `客户端,服务端` / `client,server` → `platform: "both"`
+- Client debug script: only include events where `platform === "client"` or `platform === "both"`
+- Server debug script: only include events where `platform === "server"` or `platform === "both"`
+- If xlsx has no platform column: include all events (backward compatible)
+
+```
+Verification steps:
+1. Add debug device ID in AE Admin: Tracking Management → Debug Data → Add Device (enter deviceId)
+2. Run debug script
+3. Open AE Debug page: https://<host>/#/data/debug
+4. Filter by distinct_id or device_id to view uploaded data
+5. Check event property structure correctness (especially object array properties)
+```
+
+### Reference Doc Paths
+
+All SDK debug/logging docs are located at:
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/<sdk>/<sdk>-advanced/debugging-and-logging.md`
+- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/server-sdk/<language>/<language>-advanced/debugging-and-logging.md`
+
+For zh-CN only SDKs (Mini Program, LayaAir, etc.), refer to sdk-index.md for exact paths.