@thinkingai/ae-cli 6.1.9 → 6.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/{te-analysis-X222IRYR.js → te-analysis-ITKTO6JS.js} +461 -14
  3. package/dist/{te-analysis-IWQZO423.js → te-analysis-RAC67YYD.js} +461 -14
  4. package/package.json +2 -2
  5. package/skills/ae-analysis/references/command_index.md +5 -0
  6. package/skills/ae-analysis/references/debug_data_list.md +28 -0
  7. package/skills/ae-analysis/references/debug_device_add.md +23 -0
  8. package/skills/ae-analysis/references/debug_device_list.md +19 -0
  9. package/skills/ae-analysis/references/debug_device_select.md +22 -0
  10. package/skills/ae-analysis/references/plan_sync_display_names.md +28 -0
  11. package/skills/ae-generate-tracking-code/SKILL.md +22 -6
  12. package/skills/ae-generate-tracking-code/references/debug-script.md +46 -37
  13. package/skills/ae-generate-tracking-plan/SKILL.md +26 -1
package/skills/ae-analysis/references/debug_device_select.md ADDED
@@ -0,0 +1,22 @@
1
+ # tracking debug-device select
2
+
3
+ Use this command to select the active Debug device for the current CLI user.
4
+ Do not use it to create a missing device or retrieve Debug events.
5
+
6
+ Command:
7
+
8
+ ```bash
9
+ ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>
10
+ ```
11
+
12
+ Capability id: `tracking.debug_device.select`.
13
+
14
+ Input sends `project_id` and `device_id`. The device must come from `tracking debug-device list` or a successful `tracking debug-device add`.
15
+ The result confirms the selected device; follow it with `debug-data list` only after the reporting client has sent Debug data with the same ID.
16
+
17
+ ## Parameters
18
+
19
+ | Parameter | Required | Description |
20
+ | -------------- | -------- | ----------------------------------- |
21
+ | `--project-id` | Yes | Numeric AE project ID. |
22
+ | `--device-id` | Yes | Existing Debug device ID to select. |
package/skills/ae-analysis/references/plan_sync_display_names.md ADDED
@@ -0,0 +1,28 @@
1
+ # tracking plan sync-display-names
2
+
3
+ Use this local orchestration command after uploading a tracking plan, and rerun it after the first Debug or production data arrives.
4
+ Do not use it to rename metadata that already has a display name, create missing metadata, or replace the tracking-plan upload flow.
5
+
6
+ Command:
7
+
8
+ ```bash
9
+ ae-cli tracking plan sync-display-names \
10
+ --project-id <project_id> \
11
+ --draft <draft.json>
12
+ ```
13
+
14
+ The command reads localized `display_name` values from the local tracking-plan draft, lists the project's event, event-property, and user-property metadata, then calls `metadata.super_metadata.batch_edit` in bounded batches.
15
+
16
+ Safety and result rules:
17
+
18
+ - Only blank metadata display names are filled.
19
+ - Existing non-empty AE display names are never overwritten.
20
+ - `missing_in_metadata` means an event/property has not appeared in project metadata yet; rerun after data arrives.
21
+ - `missing_display_name_in_draft` means the draft is incomplete; add the localized display name, regenerate and validate the xlsx, then retry.
22
+
23
+ ## Parameters
24
+
25
+ | Parameter | Required | Description |
26
+ | -------------- | -------- | --------------------------------------------------------------------------------- |
27
+ | `--project-id` | Yes | Numeric AE project ID. |
28
+ | `--draft` | Yes | Local tracking-plan `draft.json` containing event/property `display_name` values. |
package/skills/ae-generate-tracking-code/SKILL.md CHANGED
@@ -105,7 +105,9 @@ First, check if `.ae-cli/draft.json` exists and read existing configuration:
105
105
 
106
106
  **host handling** (optional):
107
107
  - If you need to fetch plan from AE (no local draft.json) → ask for host
108
- - If local draft.json exists → host is not required; only hint user to open AE Debug page during validation phase
108
+ - If local draft.json exists → host is not required for code generation
109
+ - Before Debug validation, run `ae-cli config current` and confirm the active host matches the target AE environment; if it does not, run `ae-cli config set-host <AE_HOST>`
110
+ - Complete Debug validation with `ae-cli tracking debug-device` and `ae-cli tracking debug-data` by default; only hint the user to open the AE Debug page when those CLI capabilities are unavailable
109
111
 
110
112
  ### If only xlsx file exists (no draft.json)
111
113
 
@@ -605,16 +607,30 @@ Provide validation guidance based on selected platforms:
605
607
 
606
608
  ```
607
609
  Validation steps:
608
- 1. Run validation script:
610
+ 1. Confirm the active AE environment:
611
+ ae-cli config current
612
+
613
+ 2. List existing Debug devices:
614
+ ae-cli tracking debug-device list --project-id <project_id>
615
+
616
+ 3. Create the script's stable device ID if it is missing, then select it:
617
+ ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>
618
+ ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>
619
+
620
+ 4. Run validation script:
609
621
  - Client: run .ae-cli/output/te-debug-client.<ext>
610
622
  - Server: run .ae-cli/output/te-debug-server.<ext>
611
623
 
612
- 2. Open AE Debug page:
613
- https://<host>/#/data/debug
624
+ 5. Query the most recent hour of Debug data:
625
+ ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>
626
+
627
+ 6. Confirm has_data=true, then inspect event names, property structures, and error fields.
628
+ If needed, add --event-name <event_name> or --start-time "YYYY-MM-DD HH:mm:ss".
614
629
 
615
- 3. Filter by distinct_id=claude-test to view uploaded data
630
+ 7. Only if the CLI capability is unavailable, open the AE Debug page:
631
+ https://<host>/#/data/debug
616
632
 
617
- 4. For LogBus2:
633
+ 8. For LogBus2:
618
634
  - Copy daemon.json to LogBus2 conf/ directory
619
635
  - Start: ./logbus start
620
636
  - Official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
package/skills/ae-generate-tracking-code/references/debug-script.md CHANGED
@@ -3,28 +3,33 @@
3
3
  > **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
4
4
 
5
5
  ## Deliverable
6
+
6
7
  `te-debug.<ext>` single file; used to quickly verify SDK configuration is correct.
7
8
 
8
9
  ---
9
10
 
10
11
  ## Debug Mode Verification
11
12
 
12
- When using debug mode, you must add the debug device ID in AE Admin before data will appear on the AE **Debug Data** page.
13
+ When using debug mode, register and select the debug device with `ae-cli` before sending events. The Agent can then query the received Debug data directly, without asking the user to return to the AE page.
13
14
 
14
15
  ### Verification Steps
15
16
 
16
- | Step | Action |
17
- |---|---|
18
- | 1 | Add debug device ID in AE Admin: Tracking Management → Debug Data → Add Device |
19
- | 2 | Run debug script to send test events |
20
- | 3 | Open AE Debug page: `https://<host>/#/data/debug` |
21
- | 4 | Filter by `distinct_id` or `device_id` to view uploaded data |
17
+ | Step | Action |
18
+ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
19
+ | 1 | List devices: `ae-cli tracking debug-device list --project-id <project_id>` |
20
+ | 2 | Add the script's device ID when missing: `ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>` |
21
+ | 3 | Select it: `ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>` |
22
+ | 4 | Run the debug script to send test events |
23
+ | 5 | Query received data: `ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>` |
24
+ | 6 | If needed, filter one event with `--event-name <event_name>` or inspect it in AE at `https://<host>/#/data/debug` |
22
25
 
23
26
  ### Common Notes for Client and Server SDKs
24
27
 
25
28
  - Both use **TDDebugConsumer** (or the platform's equivalent debug mode API)
26
- - Both require adding device ID in AE Admin to view data on the Debug page
29
+ - Both require registering the same device ID with `ae-cli tracking debug-device add`
27
30
  - On validation failure, the SDK prints error logs or throws exceptions (behavior varies by language)
31
+ - `debug-data list` defaults to the most recent hour and returns `has_data`, `event_count`, `data_count`, and the raw Debug records
32
+ - Treat `has_data: true` as evidence that the receiver got Debug data; also inspect each record's error fields before declaring validation successful
28
33
 
29
34
  ---
30
35
 
@@ -32,32 +37,32 @@ When using debug mode, you must add the debug device ID in AE Admin before data
32
37
 
33
38
  ### Client SDK
34
39
 
35
- | SDK | Debug Mode API | Reference Doc |
36
- |---|---|---|
37
- | 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` |
38
- | 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` |
39
- | 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` |
40
- | JavaScript SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `data-ingestion-guide/client-sdk/javascript/javascript-advanced/debugging-and-logging.md` |
41
- | Mini Program SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `客户端-sdk/小程序小游戏/进阶指南/实时调试.md` |
42
- | CocosCreator | See doc | `data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance/debugging-and-logging.md` |
43
- | Cocos2d-x | See doc | `data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced/debugging-and-logging.md` |
44
- | Unreal SDK | See doc | `data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced/debugging-and-logging.md` |
45
- | Flutter SDK | See doc | `data-ingestion-guide/client-sdk/cross-platform/flutter/flutter-advanced/debugging-and-logging.md` |
46
- | React Native | See doc | `data-ingestion-guide/client-sdk/cross-platform/react-native/reactnative-advanced/debugging-and-logging.md` |
40
+ | SDK | Debug Mode API | Reference Doc |
41
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
42
+ | 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` |
43
+ | 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` |
44
+ | 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` |
45
+ | JavaScript SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `data-ingestion-guide/client-sdk/javascript/javascript-advanced/debugging-and-logging.md` |
46
+ | Mini Program SDK | `ta.init({ appId: appId, server_url: serverUrl, debug: true });` | `客户端-sdk/小程序小游戏/进阶指南/实时调试.md` |
47
+ | CocosCreator | See doc | `data-ingestion-guide/client-sdk/game-engine/cocoscreator/cocoscreator-advance/debugging-and-logging.md` |
48
+ | Cocos2d-x | See doc | `data-ingestion-guide/client-sdk/game-engine/cocos2d-x/cocos2d-x-advanced/debugging-and-logging.md` |
49
+ | Unreal SDK | See doc | `data-ingestion-guide/client-sdk/game-engine/unreal/unreal-advanced/debugging-and-logging.md` |
50
+ | Flutter SDK | See doc | `data-ingestion-guide/client-sdk/cross-platform/flutter/flutter-advanced/debugging-and-logging.md` |
51
+ | React Native | See doc | `data-ingestion-guide/client-sdk/cross-platform/react-native/reactnative-advanced/debugging-and-logging.md` |
47
52
 
48
53
  ### Server SDK
49
54
 
50
- | Language | DebugConsumer API | Reference Doc |
51
- |---|---|---|
52
- | Java | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/java/java-advanced/debugging-and-logging.md` |
53
- | Python | `TDDebugConsumer(serverUrl, appId, device_id="...")` | `data-ingestion-guide/server-sdk/python/python-advanced/debugging-and-logging.md` |
54
- | Go | `NewDebugConsumerWithDeviceId(serverUrl, appId, false, deviceId)` | `data-ingestion-guide/server-sdk/golang/golang-advanced/debugging-and-logging.md` |
55
- | Node.js | `ThinkingData.initWithDebugMode(appId, serverUrl, { deviceId: "..." })` | `data-ingestion-guide/server-sdk/nodejs/nodejs-advanced/debugging-and-logging.md` |
56
- | PHP | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/php/php-advanced/debugging-and-logging.md` |
57
- | Ruby | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/ruby/ruby-advanced/debugging-and-logging.md` |
58
- | Erlang | `tddebug_consumer:new(ServerUrl, AppId, DeviceId)` | `data-ingestion-guide/server-sdk/erlang/erlang-advanced/debugging-and-logging.md` |
59
- | Lua | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/lua/lua-advanced/debugging-and-logging.md` |
60
- | C | `td_debug_consumer_new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/c/c-advanced/debugging-and-logging.md` |
55
+ | Language | DebugConsumer API | Reference Doc |
56
+ | -------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
57
+ | Java | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/java/java-advanced/debugging-and-logging.md` |
58
+ | Python | `TDDebugConsumer(serverUrl, appId, device_id="...")` | `data-ingestion-guide/server-sdk/python/python-advanced/debugging-and-logging.md` |
59
+ | Go | `NewDebugConsumerWithDeviceId(serverUrl, appId, false, deviceId)` | `data-ingestion-guide/server-sdk/golang/golang-advanced/debugging-and-logging.md` |
60
+ | Node.js | `ThinkingData.initWithDebugMode(appId, serverUrl, { deviceId: "..." })` | `data-ingestion-guide/server-sdk/nodejs/nodejs-advanced/debugging-and-logging.md` |
61
+ | PHP | `new TDDebugConsumer(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/php/php-advanced/debugging-and-logging.md` |
62
+ | Ruby | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/ruby/ruby-advanced/debugging-and-logging.md` |
63
+ | Erlang | `tddebug_consumer:new(ServerUrl, AppId, DeviceId)` | `data-ingestion-guide/server-sdk/erlang/erlang-advanced/debugging-and-logging.md` |
64
+ | Lua | `TDDebugConsumer.new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/lua/lua-advanced/debugging-and-logging.md` |
65
+ | C | `td_debug_consumer_new(serverUrl, appId, deviceId)` | `data-ingestion-guide/server-sdk/c/c-advanced/debugging-and-logging.md` |
61
66
 
62
67
  ---
63
68
 
@@ -67,7 +72,7 @@ When generating a debug script, the skill must:
67
72
 
68
73
  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)
69
74
  2. Use the corresponding platform's **TDDebugConsumer** or debug mode API
70
- 3. Set `deviceId` (e.g. `claude-test-device`) for AE Admin device registration
75
+ 3. Set a stable `deviceId` (e.g. `agent-debug-<project_id>`) and register it with `ae-cli tracking debug-device add`
71
76
  4. Read `SERVER_URL` and `appId` from plan (NOT web host)
72
77
  5. Pick 3 representative business events from plan (if object array properties exist, construct them fully)
73
78
  6. Recommend enabling SDK log printing (for easier troubleshooting)
@@ -76,6 +81,7 @@ When generating a debug script, the skill must:
76
81
  ### Post-delivery Prompt
77
82
 
78
83
  **Platform filtering notes**:
84
+
79
85
  - xlsx "Platform" column values map to `platform` field:
80
86
  - `客户端` / `client` → `platform: "client"`
81
87
  - `服务端` / `server` → `platform: "server"`
@@ -86,16 +92,19 @@ When generating a debug script, the skill must:
86
92
 
87
93
  ```
88
94
  Verification steps:
89
- 1. Add debug device ID in AE Admin: Tracking Management → Debug Data → Add Device (enter deviceId)
90
- 2. Run debug script
91
- 3. Open AE Debug page: https://<host>/#/data/debug
92
- 4. Filter by distinct_id or device_id to view uploaded data
93
- 5. Check event property structure correctness (especially object array properties)
95
+ 1. Run `ae-cli tracking debug-device list --project-id <project_id>`.
96
+ 2. If needed, run `ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>`.
97
+ 3. Run `ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>`.
98
+ 4. Run the debug script.
99
+ 5. Run `ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>`.
100
+ 6. Confirm `has_data` is true and inspect error fields and event property structures.
101
+ 7. If no data appears, retry with an explicit `--start-time "YYYY-MM-DD HH:mm:ss"` and verify that the script reports the exact same device ID.
94
102
  ```
95
103
 
96
104
  ### Reference Doc Paths
97
105
 
98
106
  All SDK debug/logging docs are located at:
107
+
99
108
  - `~/.ae-cli/wiki/raw/data-ingestion-guide/client-sdk/<sdk>/<sdk>-advanced/debugging-and-logging.md`
100
109
  - `~/.ae-cli/wiki/raw/data-ingestion-guide/server-sdk/<language>/<language>-advanced/debugging-and-logging.md`
101
110
 
package/skills/ae-generate-tracking-plan/SKILL.md CHANGED
@@ -72,6 +72,8 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
72
72
  >
73
73
  > **Language rules**: For newly generated content, user-facing fields in draft.json (`display_name`, `event_desc`, `event_tag`,
74
74
  > property `display_name`, property `desc`, etc.) should be generated in the **user's input language**.
75
+ > Every event, event property, common event property, and user property must have a non-empty `display_name`.
76
+ > A canonical snake_case identifier is not a substitute for a user-facing display name.
75
77
  > For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,
76
78
  > CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
77
79
  > When a localized label is needed, inspect `src/tracking/i18n` and use the existing resource key/value; do not invent translations from the model.
@@ -969,6 +971,7 @@ User ok → **immediately execute archive command**, then proceed to Phase 3.
969
971
  - [ ] Do event/property names contain only letters, digits, and underscores (no Chinese, no spaces)?
970
972
  - [ ] Are there duplicate event names or synonymous events coexisting (e.g. `order_create` and `create_order`)?
971
973
  - [ ] Does the same property name map to multiple display names or types?
974
+ - [ ] Does every event, event property, common event property, and user property have a non-empty `display_name` in the user's language?
972
975
 
973
976
  ### Revenue Model Required Events Check
974
977
 
@@ -1251,6 +1254,26 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
1251
1254
 
1252
1255
  On successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`).
1253
1256
 
1257
+ Then read the uploaded plan back through ae-cli and synchronize its display names to any event/property metadata
1258
+ that already exists in the project:
1259
+
1260
+ ```bash
1261
+ AE_LANG=<user_lang> ae-cli tracking plan get --project-id <projectId> --host <host>
1262
+ AE_LANG=<user_lang> ae-cli tracking plan sync-display-names \
1263
+ --project-id <projectId> \
1264
+ --draft .ae-cli/draft.json \
1265
+ --host <host>
1266
+ ```
1267
+
1268
+ `sync-display-names` is intentionally safe to rerun:
1269
+
1270
+ - It fills only blank event/property metadata display names.
1271
+ - It never overwrites a non-empty display name already maintained in AE.
1272
+ - `missing_in_metadata` means that the event/property has not appeared in project metadata yet; it is not an upload failure.
1273
+ Report those names and rerun the same command after the first Debug or production data reaches AE.
1274
+ - `missing_display_name_in_draft` means the generated plan is incomplete. Add the missing localized `display_name`,
1275
+ regenerate/validate the xlsx, and rerun the upload/synchronization flow.
1276
+
1254
1277
  ---
1255
1278
 
1256
1279
  ### 4.4 Upload Failure Handling and Auto-fix
@@ -1289,7 +1312,9 @@ Fixed: Fixed object array sub-property inconsistency, Fixed display name duplica
1289
1312
 
1290
1313
  ### 4.5 Post-success Actions
1291
1314
 
1292
- After successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`)
1315
+ After successful upload and display-name synchronization, prompt user to verify in AE Admin. **Provide the full URL**
1316
+ (tracking plan page URL format: `https://<host>/#/data/plan`). Include a short synchronization summary:
1317
+ updated counts, preserved existing counts, and any names still missing from project metadata.
1293
1318
 
1294
1319
  **Ask about generating tracking code**:
1295
1320