ae-tracking 0.1.0

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

@@ -0,0 +1,175 @@
+# 服务端代码插入流程（LoggerConsumer + LogBus2）
+
+## 架构说明
+
+服务端 SDK 推荐 LoggerConsumer + LogBus2 架构：
+
+```
+服务端代码 → LoggerConsumer → 本地日志文件（/data/ta_log/）
+                                    ↓
+                              LogBus2 进程 → AE 后台
+```
+
+**注意：LogBus v1 已过时，统一使用 LogBus2。**
+
+官方文档：
+- 使用指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+- 下载地址在官方文档「二、下载 LogBus2」章节中
+
+优势：
+- 数据可靠（本地日志持久化，不怕网络抖动）
+- 异步上报（不阻塞业务逻辑）
+- 批量上传（网络效率高）
+- 可控重试（LogBus2 配置重试策略）
+
+---
+
+## Stage 0: Wiki
+
+1. 读 `references/sdk-index.md` 找到服务端 SDK 的 wiki 路径
+2. 读 wiki 主文档（初始化、LoggerConsumer 配置）
+3. 读 wiki 进阶指南（用户属性、批量上报等）
+
+---
+
+## Stage 1: Explore
+
+1. Grep 入口：`src/main.*`、`App.*`、`Application.*`（Java）、`main.go`（Go）
+2. Grep 现有埋点：`TaAnalytics|TDAnalytics|thinkingdata|// @tracking`
+3. Grep 业务逻辑位置：`(createOrder|handlePayment|userRegister)` 等（根据 plan 事件）
+4. 确认日志目录：建议 `/data/ta_log/` 或 `/var/log/ae-tracking/`
+
+---
+
+## Stage 2: Insertion Plan（markdown 表格）
+
+**平台过滤**：
+- xlsx "采集端" 值为 `服务端` / `server` → `platform: "server"`（仅服务端采集）
+- xlsx "采集端" 值为 `客户端,服务端` / `client,server` → `platform: "both"`（两端都采集）
+- xlsx "采集端" 值为 `客户端` / `client` → `platform: "client"`（仅客户端采集，不在服务端生成）
+- 只插入 `platform === "server"` 或 `platform === "both"` 的事件
+
+```
+## SDK 初始化（LoggerConsumer）
+- 文件: <path>:<line>
+- 代码: TaAnalytics.init(new LoggerConsumer("/data/ta_log/"))
+
+## 公共事件属性
+- 文件: <path>:<line>
+- setSuperProperties({...})
+
+## 用户属性
+- 文件: <path>:<line>
+- user_set / user_setOnce / user_add
+
+## 事件组: <tag>
+- <event_name>: <file>:<symbol> 或 SKIP (already present)
+- ...
+
+## LogBus2 配置
+- 文件: <项目外的固定位置> `.ae-tracking/output/daemon.json`
+```
+
+展示后问用户 `ok` 进入 Stage 3，或 "回到事件 X 改映射"。
+
+---
+
+## Stage 3: 分批 Edit
+
+### Batch 1: SDK init（LoggerConsumer）
+
+```java
+// Java 示例
+TaAnalytics.init(new LoggerConsumer("/data/ta_log/")
+    .setRotateMode(LoggerConsumer.RotateMode.DAILY)
+    .setRotateSize(1024 * 1024 * 100)); // 100MB
+```
+
+写入位置：入口文件静态块 / main 函数开头
+
+### Batch 2: 公共属性 + 用户属性
+
+根据 `meta.user_identity` 生成：
+- `user_set` / `user_setOnce`：用户属性上报
+- `login()` 调用：用户登录时
+
+### Batch 3..N: 按 event_tag 分组的事件
+
+每个事件在对应业务逻辑位置插入 track 调用。
+
+每批用 Edit 工具；写完打印文件清单 + 新增行数，问 `ok / undo`。
+
+---
+
+## Stage 4: LogBus2 配置生成
+
+额外生成 `.ae-tracking/output/daemon.json`（不写入用户项目）：
+
+```json
+{
+  "datasource": [
+    {
+      "type": "file",
+      "file_patterns": [
+        "/data/ta_log/*.log"
+      ],
+      "app_id": "<appId>",
+      "unit_remove": "day",
+      "offset_remove": 7
+    }
+  ],
+  "push_url": "<SERVER_URL>"
+}
+```
+
+**同步提供官方文档**（方便客户下载和部署）：
+
+```
+LogBus2 官方文档：
+- 使用指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+- 下载地址在官方文档「二、下载 LogBus2」章节中
+
+注意：LogBus v1 已过时，请使用 LogBus2。
+```
+
+---
+
+## Stage 5: 汇总
+
+- 打印所有改过的文件 + 每文件新增的事件列表
+- 打印 LogBus2 配置文件路径（daemon.json）
+- **同步提供 LogBus2 官方文档链接**
+- 提示用户启动 LogBus2：
+  1. 将 `daemon.json` 复制到 LogBus2 的 `conf/` 目录
+  2. 执行 `./logbus start`
+- 提示用户考虑跑 debug 模式验证
+
+---
+
+## 代码风格
+
+- LoggerConsumer 单例：新建 `src/lib/TeTracking.java`（若不存在）
+- 每个 track 调用前加 `// @tracking <event_name>` 注释
+- 日志路径：`/data/ta_log/`（Linux）或 `C:\ta_log\`（Windows）
+- 不加 try/catch（LoggerConsumer 本身容错）
+- 事件名 / 属性名严格来自 plan，不改
+
+---
+
+## 前置检查
+
+- `git status --porcelain` 非空 → 拒绝，提示用户先 commit/stash
+
+---
+
+## 不同语言的 LoggerConsumer 配置
+
+| 语言 | LoggerConsumer 类 | 日志格式 |
+|---|---|---|
+| Java | `LoggerConsumer` | JSON line |
+| Python | `TaLoggerConsumer` | JSON line |
+| Go | `LoggerConsumer` | JSON line |
+| Node.js | `LoggerConsumer` | JSON line |
+| PHP | `TE_LoggerConsumer` | JSON line |
+
+详见 wiki 对应 SDK 文档。

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

@@ -0,0 +1,240 @@
+# snippet（片段）输出方式
+
+## 产物
+
+两种输出：
+1. **markdown 响应**：按端/平台分组展示代码片段（方便阅读）
+2. **代码文件**：`.ae-tracking/output/<platform>-sdk.<ext>`（方便复制使用）
+
+---
+
+## markdown 响应结构
+
+### 0. 前置 checklist
+
+展示配置信息：
+```
+配置信息：
+- SDK 类型：<platform>（如 android / java / javascript）
+- SERVER_URL：<用户提供的上报地址>
+- appId：<用户提供的 APP_ID>
+- 用户体系：account_id=<字段名>，distinct_id=<策略>
+```
+
+### 1. SDK 初始化片段
+
+```
+## <平台> SDK 初始化
+
+```<lang>
+// 复制到你的入口文件
+<init 代码 with SERVER_URL / appId>
+```
+```
+
+### 2. 公共属性片段
+
+```
+## 公共属性
+
+```<lang>
+// 在 SDK init 后调用
+<setSuperProperties 代码>
+```
+```
+
+### 3. 用户属性片段
+
+```
+## 用户属性
+
+```<lang>
+// 用户登录后调用
+<user_set / user_setOnce 代码>
+```
+```
+
+### 4. 按事件组
+
+```
+## 事件组：<tag>
+
+### <event_name>
+触发时机：<event_desc>
+
+```<lang>
+// 放到 <触发位置>
+ta.track('<event_name>', {
+    <prop_name>: <示例值>,
+    ...
+});
+```
+```
+
+逐事件展示，每个独立成 block，方便复制。
+
+### 5. 验证步骤（snippet 模式专用）
+
+```
+## 验证步骤
+
+1. **集成 SDK**（按集成方式选择对应步骤）
+   - **npm / 包管理器集成**：执行 `npm install` 或对应包管理器命令安装 SDK
+   - **构建工具集成**：通过 Package Manager 或 Epic Games Launcher 添加 SDK 依赖
+   - **依赖管理集成**：在 `build.gradle` / `Podfile` 中添加 SDK 依赖
+   - **手动下载集成**：下载 SDK 文件并放置到项目对应目录
+
+   参考 `references/sdk-index.md` 中对应 SDK 的官方文档
+
+2. **Debug 模式设备绑定**（AE Debug 需要先添加设备 ID）
+   - 获取设备 ID：SDK 初始化后控制台打印的 DeviceId，或调用 SDK 的获取设备 ID 方法
+   - 添加设备：AE 系统 → 埋点管理 → Debug 模式 → 添加设备 → 粘贴设备 ID
+
+3. **操作应用触发事件**，在 AE Debug 页面查看数据上报
+```
+
+---
+
+## 代码文件生成
+
+### 文件路径规则
+
+| 端/平台 | 文件路径 |
+|---|---|
+| 客户端 android (java) | `.ae-tracking/output/android-sdk-java.java` |
+| 客户端 android (kotlin) | `.ae-tracking/output/android-sdk-kotlin.kt` |
+| 客户端 ios (objc) | `.ae-tracking/output/ios-sdk-objectivec.m` |
+| 客户端 ios (swift) | `.ae-tracking/output/ios-sdk-swift.swift` |
+| 客户端 openharmony | `.ae-tracking/output/openharmony-sdk.ets` |
+| 客户端 javascript | `.ae-tracking/output/javascript-sdk.js` |
+| 客户端 miniprogram | `.ae-tracking/output/miniprogram-sdk.js` |
+| 客户端 unity | `.ae-tracking/output/unity-sdk.cs` |
+| 服务端 java | `.ae-tracking/output/java-sdk.java` |
+| 服务端 python | `.ae-tracking/output/python-sdk.py` |
+| 服务端 go | `.ae-tracking/output/go-sdk.go` |
+| 服务端 nodejs | `.ae-tracking/output/nodejs-sdk.ts` |
+| 服务端 php | `.ae-tracking/output/php-sdk.php` |
+
+**多语言平台输出规则**：
+- Android SDK：若选择 Java + Kotlin，生成两个文件（android-sdk-java.java 和 android-sdk-kotlin.kt）
+- iOS SDK：若选择 Objective-C + Swift，生成两个文件（ios-sdk-objectivec.m 和 ios-sdk-swift.swift）
+
+### 文件内容结构
+
+```<ext>
+/**
+ * AE 埋点代码片段 - <平台>
+ * 
+ * 使用说明：
+ * 1. 复制 SDK 初始化代码到入口文件
+ * 2. 复制公共属性代码到 init 后
+ * 3. 复制事件代码到对应触发位置
+ * 
+ * 配置：
+ * - SERVER_URL: <用户提供的地址>
+ * - appId: <用户提供的 ID>
+ */
+
+// ==================== SDK 初始化 ====================
+<init 代码>
+
+// ==================== 公共属性 ====================
+<setSuperProperties 代码>
+
+// ==================== 用户属性 ====================
+<user_set 代码>
+
+// ==================== 事件组：<tag> ====================
+// <event_name> - <event_desc>
+<track 代码>
+
+// ... 其他事件
+```
+
+### README 文件
+
+生成 `.ae-tracking/output/README.md`：
+
+```
+# AE 埋点代码片段
+
+## 文件清单
+
+| 文件 | 说明 |
+|---|---|
+| <platform>-sdk.<ext> | SDK 初始化 + 事件调用代码 |
+| daemon.json | LogBus2 配置（仅服务端） |
+
+## 使用步骤
+
+### 客户端
+
+1. 复制 SDK 初始化代码到入口文件
+2. 配置 SERVER_URL 和 appId
+3. 在对应触发位置复制事件代码
+
+### 服务端
+
+1. 复制 LoggerConsumer 代码到项目
+2. 配置日志文件路径
+3. **下载 LogBus2**：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation（下载地址在官方文档「二、下载 LogBus2」章节）
+4. 将 daemon.json 复制到 LogBus2 的 conf/ 目录
+5. 启动 LogBus2：`./logbus start`
+
+## LogBus2 官方文档
+
+| 文档 | 链接 |
+|---|---|
+| 使用指南 | https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation |
+
+注意：LogBus v1 已过时，请使用 LogBus2。
+
+## 验证
+
+运行 `te-debug.<ext>`，打开 AE Debug 页面验证数据上报。
+
+### Debug 模式设备绑定（仅 snippet 模式需要）
+
+AE Debug 模式需要先在 AE 系统添加设备 ID 才能查看数据：
+
+1. **获取设备 ID**（二选一）：
+   - 客户端日志：SDK 初始化后会打印设备 DeviceId
+   - 代码获取：`ta.getDeviceId()` 获取当前设备的设备 ID
+
+2. **在 AE 系统添加设备**：
+   - 路径：AE 系统 → 埋点管理 → Debug 模式 → 添加设备
+   - 粘贴设备 ID 并确认
+
+3. **验证数据**：
+   - 操作应用触发事件
+   - 在 AE Debug 页面查看数据上报
+```
+
+---
+
+## 生成流程
+
+1. 从 plan 读取 `meta.user_identity`（用户体系配置）
+2. **从 plan 读取事件列表，按 platform 筛选**：
+   - 客户端 snippet：只读 `platform === "client"` 或 `platform === "both"` 的事件
+     - xlsx 中 "采集端" 为 `客户端` 或 `client` → `platform: "client"`
+     - xlsx 中 "采集端" 为 `客户端,服务端` 或 `client,server` → `platform: "both"`
+   - 服务端 snippet：只读 `platform === "server"` 或 `platform === "both"` 的事件
+     - xlsx 中 "采集端" 为 `服务端` 或 `server` → `platform: "server"`
+     - xlsx 中 "采集端" 为 `客户端,服务端` 或 `client,server` → `platform: "both"`
+   - 若事件无 platform 字段（早期 xlsx 无此列），则读取全部事件（向后兼容）
+3. 从 plan 读取用户属性列表（用户属性无 platform 字段，两端都生成）
+4. **读 `references/sdk-index.md` 找到对应 SDK 主文档路径，读主文档的「集成 SDK」章节了解集成方式**
+5. 生成代码片段（markdown + 文件）
+6. 服务端额外生成 `daemon.json`
+7. **服务端额外生成时，必须同步提供 LogBus2 官方文档链接** 
+
+---
+
+## 代码风格
+
+- 事件名 / 属性名严格来自 plan，不改
+- 属性值用示例占位（如 `"<实际值>"`）
+- 每个代码块上方加注释说明触发时机
+- 不加 try/catch
+- 用户体系调用：`login()` / `identify()` 根据 `meta.user_identity` 生成

package/skills/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-tracking/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.