@thinkingai/ae-cli 1.0.28 → 6.0.16

package/skills/ae-generate-tracking-code/references/snippet-delivery.md

@@ -0,0 +1,394 @@
+# Snippet Output Mode
+
+> **Terminology**: 片段/代码片段 = snippet/code snippet | 产物 = deliverable/output | markdown 响应 = markdown response | 初始化 = initialization | 公共属性 = super property | 用户属性 = user property | 事件组 = event group | 触发时机 = trigger timing | 验证步骤 = verification steps | 设备绑定 = device binding | 自动采集事件 = auto-track event | 占位值 = placeholder value | 属性类型 = property type
+
+## Deliverables
+
+Two outputs:
+1. **Markdown response**: code snippets grouped by platform (for reading)
+2. **Code files**: `.ae-cli/output/<platform>-sdk.<ext>` (for copy-paste use)
+
+---
+
+## Markdown Response Structure
+
+### 0. Pre-checklist
+
+Show configuration info:
+```
+Configuration:
+- SDK type: <platform> (e.g. android / java / javascript)
+- SERVER_URL: <user-provided ingestion URL>
+- appId: <user-provided APP_ID>
+- User identity: account_id=<field>, distinct_id=<strategy>
+```
+
+### 1. SDK Initialization Snippet
+
+```
+## <Platform> SDK Initialization
+
+```<lang>
+// Copy to your entry file
+<init code with SERVER_URL / appId>
+```
+
+### 1.1 Auto-track Event Enablement (if needed)
+
+**Important**: Auto-track events (e.g. page view, button click) are disabled by default after SDK init.
+You must call the corresponding API to **enable** them after or during initialization.
+
+⚠️ **Must read `references/autotrack-enum.md` first** to look up the correct enum values and names for the target SDK.
+**Do not write auto-track code without checking the enum table** — wrong enum names will cause runtime errors.
+
+```
+## Auto-track Event Switches
+
+```<lang>
+// Add auto-track switches based on selected SDK type
+<autoTrackEnable code>
+```
+```
+
+### 2. Super Properties Snippet
+
+```
+## Super Properties
+
+```<lang>
+// Call after SDK init
+<setSuperProperties code>
+```
+```
+
+### 3. User Properties Snippet
+
+```
+## User Properties
+
+```<lang>
+// Call after user login
+<user_set / user_setOnce code>
+```
+```
+
+### 4. By Event Group
+
+```
+## Event Group: <tag>
+
+### <event_name>
+Trigger: <event_desc>
+
+```<lang>
+// Place at <trigger location>
+ta.track('<event_name>', {
+    <prop_name>: <sample value>,
+    ...
+});
+```
+```
+
+Show each event individually, each as its own block for easy copying.
+
+### 5. Verification Steps (snippet mode only)
+
+```
+## Verification Steps
+
+1. **Integrate SDK** (follow steps based on integration method)
+   - **npm / package manager**: Run `npm install` or equivalent to install SDK
+   - **Build tool integration**: Add SDK dependency via Package Manager or Epic Games Launcher
+   - **Dependency management**: Add SDK dependency in `build.gradle` / `Podfile`
+   - **Manual download**: Download SDK files and place in project directory
+
+   Reference the official docs in `references/sdk-index.md` for each SDK
+
+2. **Debug mode device binding** (AE Debug requires device ID to be added first)
+   - Get device ID: DeviceId printed in console after SDK init, or call SDK's getDeviceId method
+   - Add device: AE Admin → Tracking Management → Debug Mode → Add Device → paste device ID
+
+3. **Trigger events by interacting with the app** and view data in AE Debug page
+```
+
+---
+
+## Code File Generation
+
+### File Path Rules
+
+| Platform | File Path |
+|---|---|
+| Client android (java) | `.ae-cli/output/android-sdk-java.java` |
+| Client android (kotlin) | `.ae-cli/output/android-sdk-kotlin.kt` |
+| Client ios (objc) | `.ae-cli/output/ios-sdk-objectivec.m` |
+| Client ios (swift) | `.ae-cli/output/ios-sdk-swift.swift` |
+| Client openharmony | `.ae-cli/output/openharmony-sdk.ets` |
+| Client javascript | `.ae-cli/output/javascript-sdk.js` |
+| Client miniprogram | `.ae-cli/output/miniprogram-sdk.js` |
+| Client unity | `.ae-cli/output/unity-sdk.cs` |
+| Server java | `.ae-cli/output/java-sdk.java` |
+| Server python | `.ae-cli/output/python-sdk.py` |
+| Server go | `.ae-cli/output/go-sdk.go` |
+| Server nodejs | `.ae-cli/output/nodejs-sdk.ts` |
+| Server php | `.ae-cli/output/php-sdk.php` |
+
+**Multi-language platform output rules**:
+- Android SDK: if Java + Kotlin selected, generate two files (android-sdk-java.java and android-sdk-kotlin.kt)
+- iOS SDK: if Objective-C + Swift selected, generate two files (ios-sdk-objectivec.m and ios-sdk-swift.swift)
+
+### File Content Structure
+
+```<ext>
+/**
+ * AE Tracking Code Snippet - <Platform>
+ *
+ * Usage:
+ * 1. Copy SDK initialization code to entry file
+ * 2. Copy super properties code after init
+ * 3. Copy event code to corresponding trigger locations
+ *
+ * Configuration:
+ * - SERVER_URL: <data ingestion URL>
+ * - APPID: <APP_ID>
+ */
+
+// ==================== SDK Initialization ====================
+<init code>
+
+// ==================== Super Properties ====================
+<setSuperProperties code>
+
+// ==================== User Properties ====================
+<user_set code>
+
+// ==================== Event Group: <tag> ====================
+// <event_name> - <event_desc>
+<track code>
+
+// ... other events
+```
+
+### README File
+
+Generate `.ae-cli/output/README.md`:
+
+```
+# AE Tracking Code Snippets
+
+## File List
+
+| File | Description |
+|---|---|
+| <platform>-sdk.<ext> | SDK initialization + event call code |
+| daemon.json | LogBus2 configuration (server-side only) |
+
+## Usage Steps
+
+### Client
+
+1. Copy SDK initialization code to entry file
+2. Configure SERVER_URL and appId
+3. Copy event code to corresponding trigger locations
+
+### Server
+
+1. Copy LoggerConsumer code to project
+2. Configure log file path
+3. **Download LogBus2**: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US (download link in "二、Download LogBus2" section)
+4. Copy daemon.json to LogBus2 conf/ directory
+5. Start LogBus2: `./logbus start`
+
+## LogBus2 Official Documentation
+
+| Document | Link |
+|---|---|
+| User Guide | https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US |
+
+Note: LogBus v1 is deprecated. Please use LogBus2.
+
+## Verification
+
+Run `te-debug.<ext>` and open AE Debug page to verify data upload.
+
+### Debug Mode Device Binding (snippet mode only)
+
+AE Debug mode requires the device ID to be added in AE Admin before data can be viewed:
+
+1. **Get device ID** (choose one):
+   - Client logs: DeviceId printed after SDK initialization
+   - Code: `ta.getDeviceId()` to get current device ID
+
+2. **Add device in AE Admin**:
+   - Path: AE Admin → Tracking Management → Debug Mode → Add Device
+   - Paste device ID and confirm
+
+3. **Verify data**:
+   - Trigger events by interacting with the app
+   - View data uploads on AE Debug page
+```
+
+---
+
+## Generation Workflow
+
+### ⚠️ Mandatory Pre-checks (do not skip)
+
+**Before generating code, execute in the following order. Each step must be completed before proceeding to the next:**
+
+#### Step 0: Read SDK Main Document
+
+1. **Read `references/sdk-index.md`** to find the SDK's main document path
+2. **Read the SDK main document**, must include these sections:
+   - **Integrate SDK** section (npm package name / CDN URL / integration methods)
+   - **Initialization** section (init API signature and example code)
+   - **Track** section (event upload API and examples)
+   - **User Properties** section (user_set / user_setOnce / user_add API)
+
+3. **⚠️ Do not skip Step 0** — even if you've generated code for the same platform before, must re-read latest docs every time
+
+#### Step 1: Read Config from Plan
+
+1. Read `meta.user_identity` from plan (user identity config)
+2. **Read event list from plan, filter by platform**:
+   - Client snippet: only read events where `platform === "client"` or `platform === "both"`
+     - xlsx "Platform" column: `客户端` or `client` → `platform: "client"`
+     - xlsx "Platform" column: `客户端,服务端` or `client,server` → `platform: "both"`
+   - Server snippet: only read events where `platform === "server"` or `platform === "both"`
+     - xlsx "Platform" column: `服务端` or `server` → `platform: "server"`
+     - xlsx "Platform" column: `客户端,服务端` or `client,server` → `platform: "both"`
+   - If event has no platform field (legacy xlsx without this column): read all events (backward compatible)
+3. Read user property list from plan (user properties have no platform field; generate for both sides)
+
+#### Step 2: Copy Wiki Code Examples
+
+**Must directly copy code examples from the wiki main document read in Step 0**, do not manually write:
+
+- **Initialization code**: directly copy the complete code block from wiki doc (including import statements, package names, init parameters)
+- **⚠️ Strict language matching**:
+  - User chose **Java** → only copy code from `::: el-tab-pane label=Java` or ` ```java` blocks
+  - User chose **Kotlin** → only copy code from `::: el-tab-pane label=Kotlin` or ` ```kotlin` blocks
+  - User chose **Objective-C** → only copy code from `::: el-tab-pane label=Objective-C` or ` ```objc` blocks
+  - User chose **Swift** → only copy code from `::: el-tab-pane label=Swift` or ` ```swift` blocks
+  - **Prohibited**: copying from Java block into Kotlin file, or vice versa
+  - **Prohibited**: copying from Objective-C block into Swift file, or vice versa
+  - If wiki doc uses el-tabs format, first confirm the current language tab, then switch to correct tab to copy
+- **Auto-track code**: ⚠️ **Must read `references/autotrack-enum.md` first** to look up the correct enum names and values for the target SDK, then copy the `EnableAutoTrack` call example from wiki. **Do not guess enum names or omit enum values**
+- **Event track code**: property names and event names from plan, structure directly reused from wiki examples
+- **User property code**: directly copy API call style from wiki doc
+- **Super property code**: directly copy setSuperProperties call style from wiki doc
+
+#### Step 3: Generate Code Snippets
+
+Generate code snippets (markdown + files)
+
+#### Step 3.5: ⚠️ Language Style Check (do not skip)
+
+After generation, perform language style checks on each output file:
+
+| Language | Check Rules |
+|---|---|
+| **Kotlin** | File must not contain `;` (trailing semicolons); fix immediately and inform user 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 response: `⚠️ Auto-corrected: <error description> → <correct syntax>`
+
+#### Step 4: Server-side Additional Processing
+
+1. Additionally generate `daemon.json` for server-side
+2. **Must always provide LogBus2 official documentation link**
+
+---
+
+## Code Style
+
+- Event names / property names strictly from plan, do not modify
+- Add comment above each code block describing trigger timing
+- Do NOT add try/catch
+- User identity calls: `login()` / `identify()` generated based on `meta.user_identity`
+
+### Property Placeholder Value Rules (based on plan `type` field)
+
+When generating property value placeholders, **must select the correct type placeholder based on the property's `type` field in the plan**. Do not use string placeholders uniformly for all types:
+
+| plan `type` | Placeholder | Notes |
+|---|---|---|
+| `string` | `"\"<actual value>\""` | String placeholder |
+| `number` | `0` | Numeric placeholder (**`userAdd` must use numeric**; string causes runtime error) |
+| `bool` | `true` / `false` | Boolean placeholder (**do NOT use string `"\"<actual value>\""`**, type mismatch) |
+| `datetime` | `new Date()` / platform-specific syntax | Datetime placeholder |
+| `array_string` | `["example"]` | Array placeholder |
+| `array_row` | `[{"key":"example"}]` | Object array placeholder |
+
+**Platform-specific datetime placeholder syntax**:
+
+| Platform | Syntax |
+|---|---|
+| Android Java | `new Date()` |
+| Android Kotlin | `Date()` |
+| iOS Objective-C | `[NSDate date]` |
+| iOS Swift | `Date()` |
+| JavaScript | `new Date()` |
+| Java Server | `new Date()` |
+| Python | `datetime.datetime.now()` |
+| Go | `time.Now()` |
+| Node.js | `new Date()` |
+
+### ⚠️ Server SDK track() Parameter Order (varies by SDK; do not assume uniform ordering)
+
+For server-side SDK `track()` calls, **accountId and distinctId parameter positions differ across SDKs**. Generate code using each SDK's actual parameter order:
+
+| SDK | Positional Parameter Order | Recommended Approach |
+|---|---|---|
+| Java | `track(accountId, distinctId, eventName, properties)` | Positional ✅ |
+| Go | `Track(accountId, distinctId, eventName, properties)` | Positional ✅ |
+| **Python** | **`track(distinct_id, account_id, eventName, properties)`** — **distinct_id first** | **Prefer keyword args** ✅ |
+| Node.js | Single object param `{accountId, distinctId, event, ...}` | Object arg ✅ |
+
+**Python SDK strongly recommends keyword args** to avoid positional order confusion:
+```python
+te.track(account_id="<Account ID>", distinct_id="<Visitor ID>", event_name="order_create", properties={...})
+```
+
+Similarly, Python `user_set` / `user_setOnce` / `user_add` should use keyword args:
+```python
+te.user_set(account_id="<Account ID>", distinct_id="<Visitor ID>", properties={...})
+```
+
+### ⚠️ JavaScript SDK Examples (correct vs incorrect comparison)
+
+**Init code directly copied from wiki** (includes correct import and package name):
+
+```js
+// ✅ Correct: directly copied from wiki javascript.md
+import ta from "thinkingdata-browser";
+ta.init({
+  appId: "YOUR_APP_ID",
+  serverUrl: "https://YOUR_SERVER_URL/sync_js",
+  autoTrack: {
+    pageShow: true,
+    pageHide: true,
+  }
+});
+```
+
+**❌ Incorrect examples (absolutely prohibited)**:
+
+```js
+// ❌ Wrong: guessed package name and import syntax
+import TDAnalytics from "@thinkingdata/web-sdk";  // package name is wrong
+TDAnalytics.init({...});  // class name is wrong
+
+// ❌ Wrong: using generic variable names like te or analytics
+import te from "thinkingdata-browser";  // wiki has never used te
+te.init({...});
+```
+
+**Key points**:
+- npm package name: `thinkingdata-browser` (NOT `@thinkingdata/web-sdk`, NOT `thinkingdata`)
+- import variable name: `ta` (NOT `TDAnalytics`, NOT `te`)
+- init method: `ta.init({...})` (NOT `TDAnalytics.init()`)

package/skills/ae-generate-tracking-code/references/te-api.md

@@ -0,0 +1,181 @@
+# AE Plan Query API (captured 2026-04-15)
+
+## Endpoint
+
+- **Method**: GET
+- **URL**: `https://web-ta-demo.thinkingdata.cn/v1/ta/bury/manage/program/query?@t={timestamp}&projectId={projectId}`
+- **Auth**: header `authorization: bearer {token}` — token value read from `localStorage['ACCESS_TOKEN']` (JSON-encoded string) on the AE web app, also cached in `~/.ae-cli/tokens.json`
+- **Additional required headers**:
+  - `x-requested-with: XMLHttpRequest`
+  - `accept: application/json`
+- **Request body**: none (GET)
+
+### URL parameters
+
+| Param | Required | Notes |
+|---|---|---|
+| `@t` | yes (de-facto) | Unix timestamp ms — cache-buster; the server likely accepts any value |
+| `projectId` | yes | AE project ID, e.g. `1603` |
+
+---
+
+## Response shape (truncated to 2 events / 2 props each)
+
+```json
+{
+  "return_code": 0,
+  "return_message": "ok",
+  "showStackMessage": null,
+  "data": {
+    "projectId": 1603,
+    "createTime": "2026-04-15 15:45:17",
+
+    "events": [
+      {
+        "eventName": "admin_skill_review",
+        "displayName": "管理员审核",
+        "eventDesc": "管理员通过/驳回/归档 skill",
+        "eventTag": "admin",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17",
+        "hasReported": false,
+        "props": ["review_action", "review_reason", "skill_id", "skill_name"],
+        "propInfosOnEvent": [
+          { "name": "review_action", "hasReported": false },
+          { "name": "review_reason", "hasReported": false }
+        ]
+      },
+      {
+        "eventName": "page_view",
+        "displayName": "页面浏览",
+        "eventDesc": "任意页面打开",
+        "eventTag": "common",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17",
+        "hasReported": false
+        // props / propInfosOnEvent absent when event has no bound properties
+      }
+    ],
+
+    "eventProps": [
+      {
+        "name": "login_method",
+        "displayName": "登录方式",
+        "type": "string",
+        "desc": "feishu_sso",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17"
+        // NOTE: no hasReported field on eventProps items
+      },
+      {
+        "name": "session_duration_ms",
+        "displayName": "会话时长毫秒",
+        "type": "number",
+        "desc": "登出时本次会话累计时长",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17"
+      }
+    ],
+
+    "commonEventProps": [
+      {
+        "name": "is_embed",
+        "displayName": "是否嵌入模式",
+        "type": "bool",
+        "desc": "是否在 CRM iframe 嵌入中访问",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17",
+        "hasReported": false
+      },
+      {
+        "name": "page_name",
+        "displayName": "页面名称",
+        "type": "string",
+        "desc": "当前页面标识，如 home/submit/detail/admin",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17",
+        "hasReported": false
+      }
+    ],
+
+    "userProps": [
+      {
+        "name": "admin_review_count",
+        "displayName": "审核处理数",
+        "type": "number",
+        "desc": "管理员累计审核的 skill 数",
+        "updateType": "user_add",
+        "updateTypeName": "user_add",
+        "propTag": "",
+        "creator": "周津",
+        "createTime": "2026-04-15 15:45:17",
+        "lastUpdateAuth": "周津",
+        "lastUpdateTime": "2026-04-15 15:45:17",
+        "hasReported": false
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Field mapping to Draft
+
+The planned `normalize()` function assumes `data.event_properties[]`, `data.common_event_properties[]`, `data.user_properties[]`. **Reality differs** — see caveats below.
+
+| AE response field | Draft field (src/plan/types.ts) | Notes |
+|---|---|---|
+| `data.events[].eventName` | `events[].event_name` | camelCase → snake_case |
+| `data.events[].displayName` | `events[].display_name` | camelCase → snake_case |
+| `data.events[].eventDesc` | `events[].event_desc` | camelCase → snake_case |
+| `data.events[].eventTag` | `events[].event_tag` | camelCase → snake_case |
+| `data.events[].props[]` | `events[].properties[]` | array of property name strings |
+| `data.events[].propInfosOnEvent[]` | `events[].property_infos[]` | array of `{name, hasReported}` |
+| `data.eventProps[].name` | `event_properties[].name` | key rename: `eventProps` → `event_properties` |
+| `data.eventProps[].type` | `event_properties[].type` | same |
+| `data.eventProps[].displayName` | `event_properties[].display_name` | camelCase → snake_case |
+| `data.eventProps[].desc` | `event_properties[].description` | key rename |
+| `data.commonEventProps[].name` | `common_event_properties[].name` | key rename: `commonEventProps` → `common_event_properties` |
+| `data.userProps[].name` | `user_properties[].name` | key rename: `userProps` → `user_properties` |
+| `data.userProps[].updateType` | `user_properties[].update_type` | user property specific |
+| `data.userProps[].propTag` | `user_properties[].prop_tag` | user property specific |
+| `return_code` | — | top-level; `0` = success |
+| `return_message` | — | top-level; `"ok"` on success |
+
+---
+
+## Caveats
+
+1. **Key naming is camelCase throughout** — all field names in the response use camelCase (`eventName`, `displayName`, `eventProps`, etc.). The draft plan assumed snake_case keys like `event_name`. `normalize()` must do a full camelCase → snake_case conversion, or map fields explicitly.
+
+2. **Array key name mismatches vs plan assumption**:
+   - Response uses `eventProps` (not `event_properties`)
+   - Response uses `commonEventProps` (not `common_event_properties`)
+   - Response uses `userProps` (not `user_properties`)
+
+3. **`eventProps` are global, not scoped per event** — all event properties live in one flat `data.eventProps[]` array. Per-event bindings are in `data.events[].props` (name strings) and `data.events[].propInfosOnEvent` (`{name, hasReported}` objects). Events with no bound properties omit both `props` and `propInfosOnEvent` fields entirely.
+
+4. **`hasReported` field inconsistency** — `commonEventProps` and `userProps` items include `hasReported`; `eventProps` items do NOT include this field.
+
+5. **`@t` cache-buster** — the `@t` query param is a Unix timestamp in milliseconds. It appears to be required (the page always sends it) but likely just busts CDN/proxy caching. Use `Date.now()` when constructing requests.
+
+6. **No pagination observed** — the single request returns all 17 events, 21 event props, 6 common props, 9 user props in one shot. No pagination headers or page/limit params were observed.
+
+7. **`userProps[].updateType` and `updateTypeName`** — both fields are present on user properties (e.g., `"user_add"`). The xlsx schema's `更新方式` column maps to this.
+
+8. **`propTag`** — present on `userProps` items (maps to xlsx `属性标签` column), absent on event/common props.
+
+9. **`eventProps` lack `hasReported`** — unlike events and common/user props, individual event property definitions in `eventProps[]` do not carry `hasReported`. The flag does appear inside `propInfosOnEvent[]` on the event object itself.