@thinkingai/ae-cli 6.1.9 → 6.1.11

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

@@ -3,28 +3,33 @@
 > **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.
+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.
 
 ### 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 |
+| Step | Action                                                                                                                                             |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | List devices: `ae-cli tracking debug-device list --project-id <project_id>`                                                                        |
+| 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>` |
+| 3    | Select it: `ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>`                                                 |
+| 4    | Run the debug script to send test events                                                                                                           |
+| 5    | Query received data: `ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>`                                           |
+| 6    | If needed, filter one event with `--event-name <event_name>` or inspect it in AE at `https://<host>/#/data/debug`                                  |
 
 ### 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
+- Both require registering the same device ID with `ae-cli tracking debug-device add`
 - On validation failure, the SDK prints error logs or throws exceptions (behavior varies by language)
+- `debug-data list` defaults to the most recent hour and returns `has_data`, `event_count`, `data_count`, and the raw Debug records
+- Treat `has_data: true` as evidence that the receiver got Debug data; also inspect each record's error fields before declaring validation successful
 
 ---
 
@@ -32,32 +37,32 @@ When using debug mode, you must add the debug device ID in AE Admin before data
 
 ### 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` |
+| 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` |
+| 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`           |
 
 ---
 
@@ -67,7 +72,7 @@ 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
+3. Set a stable `deviceId` (e.g. `agent-debug-<project_id>`) and register it with `ae-cli tracking debug-device add`
 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)
@@ -76,6 +81,7 @@ When generating a debug script, the skill must:
 ### Post-delivery Prompt
 
 **Platform filtering notes**:
+
 - xlsx "Platform" column values map to `platform` field:
   - `客户端` / `client` → `platform: "client"`
   - `服务端` / `server` → `platform: "server"`
@@ -86,16 +92,19 @@ When generating a debug script, the skill must:
 
 ```
 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)
+1. Run `ae-cli tracking debug-device list --project-id <project_id>`.
+2. If needed, run `ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>`.
+3. Run `ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>`.
+4. Run the debug script.
+5. Run `ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>`.
+6. Confirm `has_data` is true and inspect error fields and event property structures.
+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.
 ```
 
 ### Reference Doc Paths
 
 All SDK debug/logging docs are located at:
+
 - `~/.ae-cli/wiki/raw/data-ingestion-guide/client-sdk/<sdk>/<sdk>-advanced/debugging-and-logging.md`
 - `~/.ae-cli/wiki/raw/data-ingestion-guide/server-sdk/<language>/<language>-advanced/debugging-and-logging.md`
 

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

@@ -72,6 +72,8 @@ Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
 > 
 > **Language rules**: For newly generated content, user-facing fields in draft.json (`display_name`, `event_desc`, `event_tag`,
 > property `display_name`, property `desc`, etc.) should be generated in the **user's input language**.
+> Every event, event property, common event property, and user property must have a non-empty `display_name`.
+> A canonical snake_case identifier is not a substitute for a user-facing display name.
 > For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,
 > CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.
 > 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.
 - [ ] Do event/property names contain only letters, digits, and underscores (no Chinese, no spaces)?
 - [ ] Are there duplicate event names or synonymous events coexisting (e.g. `order_create` and `create_order`)?
 - [ ] Does the same property name map to multiple display names or types?
+- [ ] Does every event, event property, common event property, and user property have a non-empty `display_name` in the user's language?
 
 ### Revenue Model Required Events Check
 
@@ -1251,6 +1254,26 @@ AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae
 
 On successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`).
 
+Then read the uploaded plan back through ae-cli and synchronize its display names to any event/property metadata
+that already exists in the project:
+
+```bash
+AE_LANG=<user_lang> ae-cli tracking plan get --project-id <projectId> --host <host>
+AE_LANG=<user_lang> ae-cli tracking plan sync-display-names \
+  --project-id <projectId> \
+  --draft .ae-cli/draft.json \
+  --host <host>
+```
+
+`sync-display-names` is intentionally safe to rerun:
+
+- It fills only blank event/property metadata display names.
+- It never overwrites a non-empty display name already maintained in AE.
+- `missing_in_metadata` means that the event/property has not appeared in project metadata yet; it is not an upload failure.
+  Report those names and rerun the same command after the first Debug or production data reaches AE.
+- `missing_display_name_in_draft` means the generated plan is incomplete. Add the missing localized `display_name`,
+  regenerate/validate the xlsx, and rerun the upload/synchronization flow.
+
 ---
 
 ### 4.4 Upload Failure Handling and Auto-fix
@@ -1289,7 +1312,9 @@ Fixed: Fixed object array sub-property inconsistency, Fixed display name duplica
 
 ### 4.5 Post-success Actions
 
-After successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`)
+After successful upload and display-name synchronization, prompt user to verify in AE Admin. **Provide the full URL**
+(tracking plan page URL format: `https://<host>/#/data/plan`). Include a short synchronization summary:
+updated counts, preserved existing counts, and any names still missing from project metadata.
 
 **Ask about generating tracking code**:
 

package/skills/ae-metadata/SKILL.md

@@ -53,7 +53,7 @@ ae-cli metadata property <dimension-table-action> [options]
 
 ## PROJECT_ID_GATE
 
-Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli analysis project info list` (or `ae-analysis` skill) to resolve `project_id`.
+Same rules as `ae-analysis`: reuse verified project context in one conversation; otherwise `ae-cli project info list` (or `ae-analysis` skill) to resolve `project_id`.
 
 ## Commands (10)
 

package/dist/config-BSSALXEN.js

@@ -1,128 +0,0 @@
-import {
-  GLOBAL_QUERY_CONFIG_KEY,
-  getAnalysisMappingPathForClusterMode,
-  getClusterInfoFilePath,
-  isGlobalQueryModeEnabled,
-  setGlobalQueryModeEnabled
-} from "./chunk-LCXU3AAT.js";
-import {
-  printError,
-  printOutput
-} from "./chunk-KTYR3U6D.js";
-import "./chunk-E7UXXHO3.js";
-import "./chunk-IR4ZLVPW.js";
-import {
-  addHost,
-  loadConfig,
-  normalizeUrl,
-  setActiveHost
-} from "./chunk-V6FR6WTW.js";
-import "./chunk-LYVNONC4.js";
-
-// src/commands/config.ts
-function registerConfig(program) {
-  const configCmd = program.command("config").description("AE host and environment configuration").action(() => {
-    printError("config", "Missing subcommand.", "Run: ae-cli config --help");
-    process.exit(1);
-  });
-  configCmd.command("list").description("List configured AE environments").action(async () => {
-    await printConfigList(program);
-  });
-  configCmd.command("current").description("Show the active AE environment").action(async () => {
-    await printCurrentConfig(program);
-  });
-  configCmd.command("use <env>").description("Switch active AE environment by exact URL or unique label").action(async (env) => {
-    await useConfigEnv(program, env);
-  });
-  configCmd.command("set-host <url>").description("Set the active AE host non-interactively (adds it if not already configured)").option("--label <label>", "Display label for this host (defaults to the host URL)").action(async (url, opts) => {
-    const normalized = normalizeUrl(url);
-    const label = opts.label || normalized;
-    addHost(normalized, label);
-    setActiveHost(normalized);
-    await printOutput({ activeHost: normalized, label }, program.opts().format || "json");
-  });
-  const clusterMode = configCmd.command("cluster-mode").description("Manage local multi-cluster analysis MCP mode").action(async () => {
-    await printClusterModeStatus(program);
-  });
-  clusterMode.command("status").description("Show local multi-cluster analysis MCP mode").action(async () => {
-    await printClusterModeStatus(program);
-  });
-  clusterMode.command("enable").description("Enable local multi-cluster analysis MCP mode").action(async () => {
-    setGlobalQueryModeEnabled(true);
-    await printClusterModeStatus(program);
-  });
-  clusterMode.command("disable").description("Disable local multi-cluster analysis MCP mode").action(async () => {
-    setGlobalQueryModeEnabled(false);
-    await printClusterModeStatus(program);
-  });
-}
-async function printClusterModeStatus(program) {
-  const enabled = isGlobalQueryModeEnabled();
-  await printOutput({
-    [GLOBAL_QUERY_CONFIG_KEY]: enabled,
-    path: getClusterInfoFilePath(),
-    analysisMappingPath: getAnalysisMappingPathForClusterMode(enabled)
-  }, program.opts().format || "json", program.opts().jq);
-}
-function readHostViews() {
-  const config = loadConfig();
-  const hosts = Object.entries(config.hosts).map(([url, entry]) => ({
-    url,
-    label: entry.label,
-    active: url === config.activeHost
-  }));
-  return { activeHost: config.activeHost, hosts };
-}
-async function printConfigList(program) {
-  const { activeHost, hosts } = readHostViews();
-  await printOutput({ activeHost, hosts }, program.opts().format || "json", program.opts().jq);
-}
-async function printCurrentConfig(program) {
-  const { activeHost, hosts } = readHostViews();
-  const current = hosts.find((h) => h.url === activeHost);
-  if (!current) {
-    failConfig("No active AE environment configured.", "Run: ae-cli config use <env> or ae-cli config list");
-    return;
-  }
-  await printOutput({ activeHost: current.url, label: current.label }, program.opts().format || "json", program.opts().jq);
-}
-async function useConfigEnv(program, env) {
-  const target = resolveHost(env);
-  if (target.status === "not-found") {
-    failConfig(
-      `No AE environment matched: ${env}`,
-      target.hosts.length > 0 ? `Available environments: ${formatHostOptions(target.hosts)}` : "Run: ae-cli config list"
-    );
-    return;
-  }
-  if (target.status === "duplicate-label") {
-    failConfig(
-      `Duplicate label: ${env}`,
-      `Rename duplicate labels first. Run: ae-cli config list \u2014 ${formatHostOptions(target.matches)}`
-    );
-    return;
-  }
-  setActiveHost(target.host.url);
-  await printOutput({ activeHost: target.host.url, label: target.host.label }, program.opts().format || "json", program.opts().jq);
-}
-function resolveHost(env) {
-  const raw = env.trim();
-  const selector = raw.startsWith("http://") || raw.startsWith("https://") ? normalizeUrl(raw) : raw;
-  const { hosts } = readHostViews();
-  const byUrl = hosts.find((h) => h.url === selector);
-  if (byUrl) return { status: "found", host: byUrl };
-  const byLabel = hosts.filter((h) => h.label === raw);
-  if (byLabel.length === 1) return { status: "found", host: byLabel[0] };
-  if (byLabel.length > 1) return { status: "duplicate-label", matches: byLabel };
-  return { status: "not-found", hosts };
-}
-function formatHostOptions(hosts) {
-  return hosts.map((h) => `${h.label} (${h.url})`).join(", ");
-}
-function failConfig(message, hint) {
-  printError("config", message, hint);
-  process.exitCode = 1;
-}
-export {
-  registerConfig
-};