ae-tracking 0.1.0

package/skills/generate-tracking-code/SKILL.md

@@ -0,0 +1,551 @@
+---
+name: generate-tracking-code
+description: 交互式将 AE 埋点方案落为用户项目代码、LogBus2 配置或 debug 脚本。触发词：代码埋点、埋点代码、tracking code、埋点落地、logbus 配置、AE 上报代码。支持多端多平台独立选择输出方式（插入/片段），服务端默认 LoggerConsumer + LogBus2 架构。
+---
+
+# generate-tracking-code
+
+## 何时触发
+
+用户说"生成埋点代码 / 帮我做 web 端埋点 / 生成 logbus 配置 / 服务端上报代码" 时触发。支持多端多平台独立选择输出方式。
+
+## Phase 0 — Anchor（每个问题单独一条消息）
+
+### 前置：从 draft.json 读取已有配置
+
+首先检查 `.ae-tracking/draft.json` 是否存在，读取已有配置：
+
+| 配置项 | draft.json 字段 | 处理方式 |
+|---|---|---|
+| AE projectId | `meta.project_id` | 有值 → 确认；无值 → 询问 |
+| AE web 地址 | `meta.host` | 有值 → 确认；无值 → 询问 |
+| SDK 集成模式 | `meta.sdk_integration_mode` | 有值 → 直接使用 |
+| 客户端 SDK 类型 | `meta.client_platforms`（优先）或 `meta.client_sdk_type` | 有值 → 直接使用 |
+| 服务端语言 | `meta.server_language` | 有值 → 直接使用 |
+| 用户体系 | `meta.user_identity` | 有值 → 直接使用 |
+
+**多平台支持**：
+- 若 `client_platforms` 存在（数组），则为多平台场景，需为每个平台生成代码
+- 若只有 `client_sdk_type`，则为单平台（向后兼容）
+- 示例：`client_platforms: ["android", "openharmony"]` → 生成 Android + OpenHarmony 代码
+
+**开发语言支持**：
+- Android SDK：支持 Java / Kotlin（可生成两种代码）
+- iOS SDK：支持 Objective-C / Swift（可生成两种代码）
+- 其他 SDK：固定语言，无需选择
+
+**语言配置来源**：
+- 优先读取 `meta.client_platform_languages`（如 `{"android": ["java", "kotlin"]}`）
+- 若无配置，对于 Android/iOS 平台需追问用户选择
+
+**确认流程**：
+- 有值：问 **"确认使用 draft.json 中的配置：<值>？yes / 输入新值"**
+- 用户 `yes` → 使用 draft 值
+- 用户输入新值 → 更新 draft.json 并使用新值
+
+### 需要询问的配置（如果 draft 中无值）
+
+1. **SERVER_URL** — 数据上报地址（**与 web 地址不同**；请前往 AE 系统「项目管理」→「接入配置」→ 填写「公网地址」）
+   - ⚠️ 「公网地址」需要填写过才会显示，如果没填过不会显示此字段
+   - 解决方案：咨询运维获取地址，或**跳过此步骤**（代码中可暂时用 `SERVER_URL` 或 `PUSH_URL` 替代）
+2. **appId** — 请前往 AE 系统「项目管理」→「接入配置」→ 复制「APP_ID」
+
+**host 处理**（可选）：
+- 如果需要从 AE fetch plan（无本地 draft.json）→ 询问 host
+- 如果已有本地 draft.json → host 不必须，仅在验证阶段提示用户打开 AE Debug 页面
+
+### 如果只有 xlsx 文件（无 draft.json）
+
+用户直接提供 xlsx 埋点方案文件（通过 `ae-tracking code import-xlsx` 命令或放在 `.ae-tracking/draft.xlsx`），则进入此流程：
+
+**Step 1：解析 xlsx 文件**
+
+执行以下命令解析 xlsx：
+```bash
+ae-tracking code import-xlsx --xlsx <xlsx路径> --out .ae-tracking/draft.json
+```
+
+此命令会：
+1. 读取 xlsx 中的事件、事件属性、公共属性、用户属性
+2. 根据事件 `platform` 字段推断 `sdk_integration_mode`
+3. 输出 draft.json（meta 部分仅有 events 和 plan_name）
+
+**Step 2：从 xlsx 可推断的信息**
+
+| 字段 | 是否可推断 | 说明 |
+|---|---|---|
+| 事件列表 | ✅ | 从 `#事件数据` sheet |
+| 事件属性池 | ✅ | 从 `#事件数据` sheet |
+| 公共事件属性 | ✅ | 从 `#公共事件属性` sheet |
+| 用户属性 | ✅ | 从 `#用户数据` sheet |
+| sdk_integration_mode | ⚠️ 有限支持 | xlsx 的"采集端"列可推断（client/server/both），但若无该列则需询问 |
+| client_platforms | ❌ | 需询问用户选择 |
+| client_platform_languages | ❌ | 需询问用户选择（仅 Android/iOS） |
+| server_language | ❌ | 需询问用户选择（仅 sdk_integration_mode 含 server） |
+| user_identity | ❌ | 需询问用户选择 |
+| host / project_id | ❌ | 需询问或跳过 |
+
+**"采集端"列解析规则**：
+- 空值 / 无此列 → 无法推断 platform，默认生成客户端代码（向后兼容）
+- `客户端` / `client` → 仅客户端采集，解析为 `platform: "client"`
+- `服务端` / `server` → 仅服务端采集，解析为 `platform: "server"`
+- `客户端,服务端` / `client,server` / `服务端,客户端` / `server,client` → 两端都采集，解析为 `platform: "both"`
+
+**内部表示**：xlsx 中的 "采集端" 值经过 `ae-tracking code import-xlsx` 解析后，统一转为 `platform` 字段的内部值：
+- `client` → 客户端采集
+- `server` → 服务端采集
+- `both` → 两端都采集（xlsx 中是 "客户端,服务端" 或 "client,server"）
+
+**代码生成时的平台过滤**：
+- 客户端代码：只生成 `platform === "client"` 或 `platform === "both"` 的事件
+- 服务端代码：只生成 `platform === "server"` 或 `platform === "both"` 的事件
+- 若 xlsx 无 platform 列，客户端和服务端代码都会生成（向后兼容）
+
+**Step 3：询问缺失配置**
+
+按顺序依次询问，每项单独一条消息：
+
+1. **SDK 集成模式**：问 **"埋点通过客户端还是服务端上报？客户端 / 服务端 / 两者都有"**
+
+2. **客户端平台**（仅 sdk_integration_mode 含 client）：
+   问 **"这是什么平台的 App？"**
+   - Android / Android SDK
+   - iOS / iOS SDK
+   - OpenHarmony / OpenHarmony SDK
+   - Web / H5（JavaScript SDK）
+   - 微信小程序（小程序 SDK）
+   - 微信小游戏（小游戏 SDK）
+   - Unity 游戏（Unity SDK）
+   - Cocos 游戏（CocosCreator / Cocos2d-x / LayaAir）
+   - React Native / Flutter / uni-app
+   - 其他
+
+   → 用户选择后，**仅当选择 Android 或 iOS 时**，追问：
+   - Android → 问 **"开发语言是什么？Java / Kotlin / 两者都支持"**
+   - iOS → 问 **"开发语言是什么？Objective-C / Swift / 两者都支持"**
+
+3. **服务端语言**（仅 sdk_integration_mode 含 server）：
+   问 **"服务端语言是什么？"**
+   - Java
+   - Python
+   - Go
+   - Node.js
+   - PHP
+   - C# / .NET
+   - 其他
+
+4. **用户体系**：
+   - 账号 ID 来源：user_account / role_id / none
+   - 访客 ID 策略：auto / device_id / custom
+
+5. **SERVER_URL / APP_ID**（如已配置则跳过）
+
+**Step 4：合并配置并进入 Phase 1**
+
+将询问结果写入 `.ae-tracking/draft.json` 的 meta 部分，然后进入 Phase 1 执行。
+
+---
+
+### 如果无本地 plan 文件
+
+如果没有 `.ae-tracking/draft.json` 或 `.ae-tracking/remote-plan.json`，需要：
+
+1. **AE projectId** — 从 AE 后台获取
+2. **AE web 地址** — 用于 fetch plan
+3. 执行 `ae-tracking plan fetch` 获取埋点方案
+   
+   **追问规则**（根据集成模式确定需要生成代码的端/平台）：
+   
+   | 集成模式 | 需要生成的端/平台 |
+   |---|---|
+   | `client_only` | 1 个客户端平台（从 plan 读取 `client_sdk_type` 或询问） |
+   | `server_only` | 1 个服务端语言（从 plan 读取 `server_language` 或询问） |
+   | `both` | 客户端平台 + 服务端语言（两者都需要） |
+
+---
+
+### 端/平台定义
+
+**客户端平台**（对应客户端 SDK）：
+
+| plan 字段 | 平台 | SDK | 文档路径 |
+|---|---|---|---|
+| `android` | Android | Android SDK | `wiki/te-docs/raw/client/android/` |
+| `ios` | iOS | iOS SDK | `wiki/te-docs/raw/client/ios/` |
+| `openharmony` | OpenHarmony | OpenHarmony SDK | `wiki/te-docs/raw/client/openharmony/` |
+| `javascript` | Web / H5 | JavaScript SDK | `wiki/te-docs/raw/client/js/` |
+| `miniprogram` | 小程序 | 小程序 SDK | `wiki/te-docs/raw/client/miniprogram/` |
+| `unity` | Unity | Unity SDK | `wiki/te-docs/raw/client/unity/` |
+| `game_engine` | 游戏引擎 | Cocos / Laya / Unreal | 见 `references/sdk-index.md` |
+
+**服务端语言**（对应服务端 SDK）：
+
+| plan 字段 | 语言 | SDK | 文档路径 |
+|---|---|---|---|
+| `java` | Java | Java SDK | `wiki/te-docs/raw/server/java/` |
+| `python` | Python | Python SDK | `wiki/te-docs/raw/server/python/` |
+| `go` | Go | Go SDK | `wiki/te-docs/raw/server/go/` |
+| `nodejs` | Node.js | Node SDK | `wiki/te-docs/raw/server/node/` |
+| `php` | PHP | PHP SDK | `wiki/te-docs/raw/server/php/` |
+| `csharp` | C# | C# SDK | `wiki/te-docs/raw/server/csharp/` |
+
+---
+
+### 输出方式定义
+
+每个端/平台可选择两种输出方式：
+
+| 方式 | 说明 | 参数 | 产物 |
+|---|---|---|---|
+| **insert**（插入） | 直接 Edit 写入用户项目 | 需指定项目路径 | 代码写入指定目录 |
+| **snippet**（片段） | markdown 打印 + 生成代码文件 | 无需路径 | `.ae-tracking/output/<platform>-sdk.<ext>` |
+
+**服务端默认附加**：
+- LoggerConsumer 代码（插入或片段，根据选择）
+- LogBus2 配置文件（`.ae-tracking/output/daemon.json`）
+- 官方文档链接：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+**独立选项**：
+- `debug` — 校验脚本（生成测试上报代码）
+
+---
+
+## Phase 1 — Load plan
+
+```bash
+ae-tracking auth login --host <host>
+ae-tracking auth status
+ae-tracking plan fetch --project <projectId> --host <host> > .ae-tracking/remote-plan.json
+```
+
+失败降级：
+- AE 无法访问 → 问用户是否用 `.ae-tracking/draft.json`（本地已有 plan）
+- 两者都没有 → 终止，让用户先跑 `generate-tracking-plan`
+
+**读取 SDK 集成配置**：
+从 plan 文件中读取：
+- `meta.sdk_integration_mode` — SDK 集成模式
+- `meta.client_sdk_type` — 客户端 SDK 类型（如 `client_only` 或 `both`）
+- `meta.server_language` — 服务端开发语言（如 `server_only` 或 `both`）
+- `meta.user_identity` — 用户体系配置（用于生成 `login()` / `identify()` 调用）
+
+**确定需要生成代码的端/平台列表**：
+```
+端/平台列表 = {
+  client: [client_sdk_type]  // 如 ['android'] 或 ['javascript']
+  server: [server_language]  // 如 ['java'] 或 ['python']
+}
+```
+
+---
+
+## Phase 2 — Route mode（选择输出方式）
+
+### 2.1 展示端/平台列表
+
+根据 Phase 1 读取的配置，展示需要生成代码的端/平台：
+
+```
+需要生成代码的端/平台：
+
+客户端：
+- android（Android SDK）
+
+服务端：
+- java（Java SDK，默认 LoggerConsumer + LogBus2）
+```
+
+### 2.2 快捷选项
+
+提供快捷选项，简化交互：
+
+**选项 1：全都生成片段**
+- 所有端/平台都选择 `snippet`
+- 一次性输出 markdown + 多个代码文件 + LogBus2 配置
+- 无需指定项目路径
+
+**选项 2：逐个选择**
+- 每个端/平台独立选择输出方式
+
+### 2.3 逐个选择流程
+
+如果用户选择「逐个选择」，按端/平台顺序询问：
+
+**客户端平台询问**：
+```
+客户端 android 选择输出方式：
+1. insert（插入）— 需指定项目路径
+2. snippet（片段）— 无需路径，生成代码文件
+
+请选择：insert / snippet
+```
+
+- 选 `insert` → 问 **"项目路径是什么？（绝对路径）"**
+- 选 `snippet` → 无需额外参数
+
+**服务端语言询问**：
+```
+服务端 java 选择输出方式：
+1. insert（插入）— 需指定项目路径
+2. snippet（片段）— 无需路径，生成代码文件
+
+请选择：insert / snippet
+
+（默认附加：LoggerConsumer + LogBus2 配置 + 官方文档链接）
+```
+
+- 选 `insert` → 问 **"项目路径是什么？（绝对路径）"**
+- 选 `snippet` → 无需额外参数
+- 服务端无论选择哪种，都额外生成 `.ae-tracking/output/daemon.json`
+- **同步提供 LogBus2 官方文档链接**：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+### 2.4 独立选项
+
+在端/平台选择完成后，询问：
+
+**"是否需要生成 debug 校验脚本？yes / no"**
+
+- `yes` → 生成 `.ae-tracking/output/te-debug.<ext>`
+- `no` → 跳过
+
+### 2.5 汇总选择结果
+
+展示最终选择汇总：
+
+```
+输出方式汇总：
+
+客户端 android：snippet（片段）
+  产物：.ae-tracking/output/android-sdk.java
+
+服务端 java：snippet（片段）
+  产物：.ae-tracking/output/java-sdk.java
+         .ae-tracking/output/daemon.json
+
+LogBus2 官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+独立选项：debug
+  产物：te-debug.java
+
+确认？yes / no
+```
+
+---
+
+## Phase 3 — Execute（按端/平台执行）
+
+### 3.1 执行前检查
+
+Phase 3 开始前检查：
+```bash
+test -z "$(git status --porcelain)" || echo "uncommitted changes present"
+```
+
+**处理规则**：
+- 所有 `insert` 选择 → 必须检查 git 状态
+- 有未提交改动 → 拒绝执行所有 `insert`，提示用户先 commit/stash
+- `snippet` / `debug` → 无需检查（不写用户代码）
+
+### 3.2 按端/平台分发执行
+
+**事件平台过滤规则**（重要）：
+- xlsx "采集端" 列的值映射为 `platform` 字段：
+  - `客户端` / `client` → `platform: "client"`
+  - `服务端` / `server` → `platform: "server"`
+  - `客户端,服务端` / `client,server` → `platform: "both"`
+- 客户端代码：只生成 `platform === "client"` 或 `platform === "both"` 的事件
+- 服务端代码：只生成 `platform === "server"` 或 `platform === "both"` 的事件
+- 若 xlsx 无 platform 列（早期方案），则生成全部事件（向后兼容）
+- `platform === undefined`（xlsx 无此列）→ 两端代码都生成
+
+**客户端代码生成**：
+
+| 输出方式 | 执行流程 |
+|---|---|
+| `insert` | 读 `references/client-sdk-insert.md` → Explore 项目 → 制定插入计划 → Edit 写入 |
+| `snippet` | 读 `references/snippet-delivery.md` → markdown 打印 + 生成 `.ae-tracking/output/<platform>-sdk.<ext>` |
+
+**只生成 `platform === "client"` 或 `platform === "both"` 的事件**
+
+生成前必须读取 wiki 对应 SDK 文档（见 `references/sdk-index.md`）。
+
+---
+
+**服务端代码生成**：
+
+| 输出方式 | 执行流程 |
+|---|---|
+| `insert` | 读 `references/server-sdk-insert.md` → Explore 项目 → 制定插入计划 → Edit 写入 |
+| `snippet` | markdown 打印 + 生成 `.ae-tracking/output/<language>-sdk.<ext>` |
+
+**只生成 `platform === "server"` 或 `platform === "both"` 的事件**
+
+**服务端默认附加**：
+- 生成 LoggerConsumer 模式代码（写本地日志文件）
+- 生成 `.ae-tracking/output/daemon.json`（LogBus2 配置）
+- **同步提供 LogBus2 官方文档链接**：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+生成前必须读取 wiki 对应 SDK 文档（见 `references/sdk-index.md`）。
+
+---
+
+**独立选项执行**：
+
+| 选项 | 执行流程 |
+|---|---|
+| `debug` | 读 `references/debug-script.md` → 生成 `.ae-tracking/output/te-debug.<ext>` |
+
+---
+
+## Phase 4 — Deliver（产物展示）
+
+根据选择的输出方式展示产物：
+
+### 全都生成片段
+
+```
+产物清单：
+
+客户端：
+- .ae-tracking/output/android-sdk.java（Android SDK 代码片段）
+
+服务端：
+- .ae-tracking/output/java-sdk.java（Java SDK LoggerConsumer 代码）
+- .ae-tracking/output/daemon.json（LogBus2 配置）
+
+LogBus2 官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+独立选项：
+- .ae-tracking/output/te-debug.java（校验脚本）
+
+README：.ae-tracking/output/README.md（使用说明）
+```
+
+### 混合选择（部分 insert + 部分 snippet）
+
+```
+产物清单：
+
+客户端 android（insert）：
+- <项目路径>/src/main/java/.../TrackingHelper.java（SDK init + 事件调用）
+
+服务端 java（snippet）：
+- .ae-tracking/output/java-sdk.java（LoggerConsumer 代码片段）
+- .ae-tracking/output/daemon.json（LogBus2 配置）
+
+LogBus2 官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+
+独立选项：
+- .ae-tracking/output/te-debug.java（校验脚本）
+```
+
+### Markdown 代码片段展示
+
+对于所有 `snippet` 选择，在 markdown 响应中按端/平台分组展示：
+
+```
+## 客户端 Android
+
+### SDK 初始化
+```java
+TDAnalytics.init(this, SERVER_URL, APPID);
+```
+
+### 公共属性
+```java
+Map<String, Object> superProperties = new HashMap<>();
+superProperties.put("channel", "app_store");
+TDAnalytics.setSuperProperties(superProperties);
+```
+
+### 事件组：auth
+#### user_login
+```java
+TDAnalytics.track("user_login", new HashMap<String, Object>() {{
+    put("login_method", "phone");
+}});
+```
+...
+```
+
+---
+
+## Phase 5 — Validate hint
+
+根据选择的端/平台给出验证建议：
+
+### 验证步骤
+
+```
+验证步骤：
+1. 运行校验脚本：
+   - 客户端：运行 .ae-tracking/output/te-debug-client.<ext>
+   - 服务端：运行 .ae-tracking/output/te-debug-server.<ext>
+
+2. 打开 AE Debug 页面：
+   https://<host>/#/data/debug
+
+3. 筛选 distinct_id=claude-test 查看上报数据
+
+4. 如有 LogBus2：
+   - 将 daemon.json 复制到 LogBus2 的 conf/ 目录
+   - 启动：./logbus start
+   - 官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+```
+
+### 验证通过后
+
+- 提示用户 commit 改动（如有 `insert`）
+- 提示用户在代码中调用 `login()` / `identify()` 以关联用户 ID
+- 提示用户将 daemon.json 复制到 LogBus2 的 conf/ 目录
+
+### 验证失败
+
+- 让用户贴错误文案回来 debug
+- 检查 SERVER_URL / appId 是否正确
+- 检查网络连通性
+- 检查 LogBus2 配置文件格式
+
+---
+
+## 禁止
+
+- 任何 `insert` 执行前未跑 `git status` 检查
+- 在 Phase 3 跳 reference 直接乱插
+- 忽略 `// @tracking <event>` 注释的增量检测
+- 复用 web host 当 SERVER_URL（必须分开）
+- **使用 LogBus v1（已过时，只用 LogBus2）**
+- 生成 LogBus2 配置时未提供官方文档链接
+- 生成客户端代码时包含 `platform === "server"` 的专属事件
+- 生成服务端代码时包含 `platform === "client"` 的专属事件（除非 `platform === "both"`）
+- **跳过读 SDK 主文档直接凭猜测选集成方式** — 各 SDK 集成方式不同，必须先读 wiki 主文档的「集成 SDK」章节，根据项目特征（有/无构建工具）选择正确方式
+
+---
+
+## 内部参考
+
+所有输出方式的实际规则在 `references/*.md`。本 SKILL.md 只做 Phase 编排。
+
+**SDK 文档索引**：
+- `references/sdk-index.md` — 所有 SDK 的 wiki 文档路径索引（权威源）
+
+**输出方式参考**：
+- `references/client-sdk-insert.md` — 客户端代码插入流程
+- `references/snippet-delivery.md` — 代码片段生成流程
+- `references/server-sdk-insert.md` — 服务端代码插入流程（LoggerConsumer + LogBus2）
+- `references/logbus-config.md` — LogBus2 配置生成（含官方文档链接）
+- `references/debug-script.md` — 校验脚本生成
+
+**LogBus2 官方文档**（生成配置时必须同步提供）：
+- 使用指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation
+- 下载地址在官方文档「二、下载 LogBus2」章节中
+
+**wiki 目录结构**（见 `wiki/te-docs/schema.md`）：
+- `wiki/te-docs/raw/` — AE 官方文档镜像（只读，由 crawler 维护）
+- `wiki/te-docs/synthesis/` — LLM 合成的概览文档
+
+**生成代码时的文档读取顺序**：
+1. 读 `references/sdk-index.md` 找到对应 SDK 的文档路径
+2. 读 wiki 主文档（初始化、基础 API）
+3. 读 wiki 进阶指南（LoggerConsumer、用户属性等）
+4. 检查进阶指南下的子文档（如需要）

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

@@ -0,0 +1,92 @@
+# 模式 A — 客户端 SDK 代码插入
+
+## Stage 0: Wiki（必须完成，禁止跳过）
+1. 读 `references/sdk-index.md` 找到对应 SDK 的主文档路径
+2. **读 SDK 主文档的「集成 SDK」章节**，了解该 SDK 的所有集成方式（如 JS SDK 有 npm / CDN同步 / CDN异步 三种）
+3. 根据项目特征（有无 package.json / 构建工具 / 纯 HTML）选择对应的集成方式
+4. 读 `~/.ae-tracking/wiki/te-docs/synthesis/sdk-selection.md`，确认 appType 对应的 npm 包名与 init 签名
+5. 读对应 cheatsheet（如 `js-sdk-cheatsheet.md`）补充细节
+
+**禁止**：跳过 Stage 0 直接写代码、凭猜测选择集成方式、使用不确定的 CDN URL
+
+## Stage 1: Explore
+1. Grep 入口：`src/main.*`、`src/App.*`、`pages/_app.*`、`index.html`
+2. Grep 现有埋点：`ta\.track|thinkingdata|TA\.init|// @tracking`
+3. Grep 路由：`react-router|vue-router|next/router`
+4. Grep 用户态：`(handleLogin|onLogin|signIn|doLogin)` / `(handleLogout|signOut)`
+- Astro 专属：
+  - 入口：`src/middleware.ts`（SSR 中间件，适合 page_view）、`src/layouts/*.astro`（全局布局插 init）、`astro.config.mjs`（integrations）
+  - 客户端组件：`*.astro` 文件里 `<script>` 块、含 `client:*` 指令的 React/Vue island 组件
+
+## Stage 2: Insertion Plan（markdown 表格）
+
+**平台过滤**：
+- xlsx "采集端" 值为 `客户端` / `client` → `platform: "client"`（仅客户端采集）
+- xlsx "采集端" 值为 `客户端,服务端` / `client,server` → `platform: "both"`（两端都采集）
+- xlsx "采集端" 值为 `服务端` / `server` → `platform: "server"`（仅服务端采集，不在客户端生成）
+- 只插入 `platform === "client"` 或 `platform === "both"` 的事件
+
+```
+## SDK 初始化
+- 文件: <path>:<line>
+- 代码: init(...) with appId/SERVER_URL
+
+## 公共事件属性
+- 文件: <path>:<line>
+- setSuperProperties({...})
+
+## 用户属性
+- 文件: <path>:<line>
+- user_set / user_setOnce / user_add
+
+## 事件组: <tag>
+- <event_name>: <file>:<symbol>  或 SKIP (already present at file:line)
+- ...
+```
+
+展示后问用户 `ok` 进入 Stage 3，或 "回到事件 X 改映射"。
+
+## Stage 3: 分批 Edit
+- Batch 1: SDK init + 公共属性
+- Batch 2: 用户属性
+- Batch 3..N: 按 `event_tag` 分组
+- 每批用 Edit 工具；写完打印文件清单 + 新增行数，问 `ok / undo`
+- `undo` → 反向 Edit 回滚本批
+
+## Stage 4: 汇总
+- 打印所有改过的文件 + 每文件新增的事件列表
+- 提示用户考虑跑 F 模式
+
+## 代码风格
+- 单例：新建 `src/lib/tracking.ts`（若不存在），export `ta` 单例
+- 每个 track 调用前加 `// @tracking <event_name>` 注释
+- 不加 try/catch
+- 事件名 / 属性名严格来自 plan，不改
+- Astro：SDK init 放 `src/layouts/BaseLayout.astro` 的 `<script>` 块里；page_view 用 middleware 或 `Astro.url.pathname` 监听
+
+## 前置检查
+- `git status --porcelain` 非空 → 拒绝，提示用户先 commit/stash
+
+## Stage 5: 验证步骤（insert 模式专用）
+
+**⚠️ insert 模式 debug 默认关闭，不得引导用户到 Debug 页面查看数据**
+
+### 验证步骤
+1. **集成 SDK**（按集成方式选择对应步骤）
+   - **npm / 包管理器集成**（JavaScript/React Native/Flutter/uni-app）：执行 `npm install` 或对应包管理器命令安装 SDK
+   - **构建工具集成**（Unity/Unreal）：通过 Package Manager 或 Epic Games Launcher 添加 SDK 依赖
+   - **依赖管理集成**（Android/iOS）：在 `build.gradle` / `Podfile` 中添加 SDK 依赖
+   - **手动下载集成**（Web H5/小程序/游戏引擎等）：下载 SDK 文件并放置到项目对应目录
+
+   参考 `references/sdk-index.md` 中对应 SDK 的官方文档
+
+2. **打开 AE 实时数据页面**（非 Debug 页面）
+   - `https://<host>/#/data/realtime`
+   - 因为 debug 模式关闭，数据走正常上报流程，实时数据页面才能看到
+
+3. **操作应用触发事件**，查看是否有数据上报
+
+### 上线前检查清单
+- [ ] 确认 `debug: false` 或配置中无 debug 字段
+- [ ] SDK 已正确集成（依赖已添加 / 文件已放置）
+- [ ] 实时数据页面能看到事件上报

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

@@ -0,0 +1,41 @@
+# 模式 D — DataX job.json
+
+## 询问用户
+1. 数据源类型（MySQL / Oracle / PostgreSQL / OSS / HDFS / 其它）
+2. 连接信息 / 库表名 / 查询条件（或文件路径）
+
+## 产物
+`.ae-tracking/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-tracking/output/datax-README.md`:
+- 启动：`python datax.py datax-job.json`
+- 前置：DataX 运行环境
+- `<TODO>` 清单
+
+## 生成步骤
+1. 确定 reader 插件名
+2. 按 plan 的第一个事件（或用户指定事件）填 `eventName` + `columnMapping`
+3. 写两份文件