ae-tracking 0.1.0 → 0.2.0

package/skills/data-integration-helper/references/sdk_log_guide.md

@@ -0,0 +1,314 @@
+# 查看客户端 SDK 日志
+
+# 一、背景
+
+在客户端 SDK 集成调试以及排查问题时，可以借助日志分析数据的采集和上报是否符合预期。本文介绍如何开启SDK日志，以及日志中的关键词和对应含义。
+
+### 原生客户端 SDK 上报机制
+
+首先我们简要介绍原生客户端 SDK 的上报机制，Android 和 iOS SDK 都会在本地数据库缓存数据并批量上报。本地缓存数据为了避免网络异常情况下丢失数据，批量上报为了避免频繁上报产生的系统和网络开销。当符合以下任一条件时，均会触发数据上报：
+
+- APP 切换到后台
+- 距上次数据上报时间间隔达到上报时间间隔（默认时间间隔为30秒，可以在 TE 修改）
+- 本地缓存数量达到上报的数量（默认上报的数量达到30条触发上报，可以在 TE 修改）
+
+因此，在调试过程中，如果没有满足触发数据上报的条件，数据仍然缓存在本地。
+
+### 数据日志打印
+
+对于一条数据，数据在本地存储时会打印一条日志，数据上报时又会打印一条日志，因此需要根据日志中的关键词区分日志的含义，不要误以为产生了重复数据。
+
+# 二、开启日志打印
+
+### iOS 3.0之前版本
+
+日志筛选字段"[THINKING]"
+
+**开启日志打印**
+
+```objectivec
+[ThinkingAnalyticsSDK setLogLevel:TDLoggingLevelDebug];
+```
+
+**初始化SDK**
+
+mode：表示SDK使用的模式
+
+```
+2024-02-01 11:36:47.862929+0800 TATest_iOS[32287:14658471] [THINKING] Thinking Analytics iOS SDK 2.8.4 instance initialized successfully with mode: NORMAL, APP ID: af6861d085e14b5c948662e1fcdce6ef, server url: https://receiver-ta-demo.thinkingdata.cn, device ID: 15F96974-CE32-44F5-9AD0-F259349FDAF2
+```
+
+**数据存储本地**（关键词：`[THINKING] queueing data`）
+
+```objectivec
+2022-10-25 17:30:29.270504+0800 TATest_iOS[85710:698131] [THINKING] queueing data:{
+  "properties" : {
+    "#os" : "iOS",
+    "#device_model" : "arm64",
+    ...
+  },
+  "#type" : "track",
+  "#uuid" : "DB2B97A5-183A-439E-B8B2-FE9AF77D7421",
+  "#distinct_id" : "E5ABB02F-EA10-47AC-AB6C-A8E47E55B4E9",
+  "#event_name" : "testA",
+  "#time" : "2022-10-25 14:30:29.256"
+}
+```
+
+**数据上报TA**（关键词：`[THINKING] flush success sendContent`）
+
+```objectivec
+2022-10-25 17:30:32.551796+0800 TATest_iOS[85710:698131] [THINKING] flush success sendContent---->:{
+  "#app_id" : "af6861d085e14b5c948662e1fcdce6ef",
+  "data" : [...],
+  "#flush_time" : 1666690232351
+}
+```
+
+**上报TA结果**（关键词：`flush success responseData`）
+
+code为0代表上传成功
+
+```objectivec
+2022-10-25 17:30:32.552237+0800 TATest_iOS[85710:698131] [THINKING] flush success responseData---->{
+  "code" : 0
+}
+```
+
+### iOS 3.0及之后版本
+
+日志筛选字段"[ThinkingData]"
+
+**开启日志打印**
+
+```objectivec
+[TDAnalytics enableLog:YES];
+```
+
+**初始化SDK**
+
+```
+2024-02-01 12:07:05.077926+0800 TATest_iOS[32411:14665745] [ThinkingData] [ThinkingData][Info] initialized successfully!
+ AppID: af6861d085e14b5c948662e1fcdce6ef 
+ ServerUrl: https://receiver-ta-demo.thinkingdata.cn 
+ Mode: Debug 
+ TimeZone: Local Time Zone (Asia/Shanghai (GMT+8) offset 28800) 
+ DeviceID: 15F96974-CE32-44F5-9AD0-F259349FDAF2 
+ Lib: iOS 
+ LibVersion: 3.0.0
+```
+
+**数据存储本地**（关键词：`[ThinkingData] [Info] Enqueue data`）
+
+```
+2023-09-05 14:27:44.721461+0800 TestTAiOS[41411:3781875] [ThinkingData] [Info] Enqueue data: {
+  "properties" : {...},
+  "#type" : "track",
+  "#uuid" : "0ECCD33B-8076-42A5-BA2B-89DE0773B84B",
+  "#distinct_id" : "51C6265F-8F03-461E-91D3-D0FFB11DFCFD_2",
+  "#event_name" : "iOS_001",
+  "#time" : "2023-09-05 14:27:44.719"
+}
+```
+
+**数据上报TA**（关键词：`[ThinkingData] [Debug] flush success sendContent`）
+
+```
+2023-09-05 14:28:14.834448+0800 TestTAiOS[41411:3782015] [ThinkingData] [Debug] flush success sendContent---->:{...}
+```
+
+**上报TA结果**
+
+- code为0代表上传成功
+- 打印了flush success responseData，就可以认为上报成功。只看response的状态码为200，不看返回内容中的code
+
+```
+2023-09-05 14:28:14.835774+0800 TestTAiOS[41411:3782015] [ThinkingData] [Debug] flush success responseData---->{
+  "code" : 0
+}
+```
+
+### Android 3.0之前版本
+
+日志筛选字段"ThinkingAnalytics"
+
+**开启日志打印**
+
+```java
+ThinkingAnalyticsSDK.enableTrackLog(true);
+```
+
+**初始化SDK**
+
+mode：表示SDK使用的模式
+
+```
+2024-04-09 13:39:23.458 12219-12219 ThinkingAnalyticsSDK cn.thinkingdata.android.demo I Thinking Analytics SDK 2.8.3 instance initialized successfully with mode: NORMAL, APP ID ends with: 3356, server url: https://receiver.ta.thinkingdata.cn/sync, device ID: d4d6419233102942
+```
+
+**数据存储本地**（关键词：`Data enqueued`）
+
+```
+2022-10-26 10:56:54.416 6445-6528/cn.thinkingdata.android.demo I/ThinkingAnalytics.DataHandle: Data enqueued(e6ef):
+    {
+        "#type": "track",
+        "#time": "2022-10-26 10:56:54.285",
+        "#distinct_id": "04af1a3d-56b2-4c8f-a54a-2b6f655b8286",
+        "#event_name": "testA",
+        ...
+    }
+```
+
+**数据上报TA及结果**（关键词：`upload message`）
+
+code为0代表上传成功
+
+```
+2022-10-26 10:56:54.637 6445-6526/cn.thinkingdata.android.demo I/ThinkingAnalytics.DataHandle: ret code: 0, upload message: {...}
+```
+
+### Android 3.0之后版本
+
+日志筛选字段"[ThinkingData]"
+
+**开启日志打印**
+
+```java
+TDAnalytics.enableLog(true);
+```
+
+**初始化SDK**
+
+```
+2024-04-09 13:48:02.088 13974-13974 ThinkingAnalyticsSDK cn.thinkingdata.android.demo I [ThinkingData] Info: ThinkingData SDK 3.0.2 initialize success with mode: NORMAL, APP ID ends with: 3df0, server url: https://receiver-ta-preview.thinkingdata.cn/sync
+```
+
+**数据存储本地**（关键词：`[ThinkingData] Info: Enqueue data`）
+
+```
+2023-09-14 10:09:52.461 15126-15163/com.example.tatest_android I/ThinkingAnalytics.DataHandle: [ThinkingData] Info: Enqueue data(e6ef):
+    {
+        "#type": "track",
+        "#time": "2023-09-14 10:09:52.445",
+        "#distinct_id": "b86de4eb-12b8-4ce4-924a-54cd12b5fa25",
+        "#event_name": "android_001",
+        ...
+    }
+```
+
+**数据上报TA**（关键词：`[ThinkingData] Debug: Send event, Request =`）
+
+```
+2023-09-14 10:09:52.688 15126-15162/com.example.tatest_android D/ThinkingAnalytics.DataHandle: [ThinkingData] Debug: Send event, Request = {...}
+```
+
+**上报TA结果**（关键词：`[ThinkingData] Debug: Send event, Response =`）
+
+code为0代表上传成功
+
+```
+2023-09-14 10:09:52.688 15126-15162/com.example.tatest_android D/ThinkingAnalytics.DataHandle: [ThinkingData] Debug: Send event, Response ={
+        "code": 0
+    }
+```
+
+### Unity 3.0之前版本
+
+**开启日志打印**
+
+注意：EnableLog 需要放在 StartThinkingAnalytics 之后调用
+
+```csharp
+ThinkingAnalyticsAPI.EnableLog(true);
+```
+
+**数据存储本地**（关键词：`Save event`）
+
+```
+[ThinkingEngine] (Unity_V2.6.0-beta.1) Save event: {...}
+```
+
+**数据上报TA**（关键词：`Post event`）
+
+```
+[ThinkingEngine] (Unity_V2.6.0-beta.1) Post event: {...}
+```
+
+**上报TA结果**
+
+code为0代表上传成功
+
+```
+[ThinkingEngine] (Unity_V2.6.0-beta.1) Response: {"code":0}
+```
+
+### Unity 3.0之后版本
+
+**开启日志打印**
+
+注意：EnableLog 需要放在 Init 之后调用。Unity的日志默认是开启的。
+
+```csharp
+TDAnalytics.EnableLog(true);
+```
+
+**数据存储本地**（关键词：`Enqueue data`）
+
+```
+[ThinkingData] Info: Enqueue data: {...}
+```
+
+**数据上报TA**（关键词：`Send event Request`）
+
+```
+[ThinkingData] Info: Send event Request: {...}
+```
+
+**上报TA结果**（关键词：`Send event Response`）
+
+- Normal模式，code为0代表上传成功
+- Debug模式，如果没有加白名单，"errorLevel":-1，提示加白名单
+- Debug模式，如果加了白名单，"errorLevel":0，表示上报成功
+
+### OpenHarmony
+
+日志筛选字段"[ThinkingData]"，但是由于打印字段有限制，所以一般不加筛选条件
+
+**开启日志打印**
+
+```
+TDAnalytics.enableLog(true);
+```
+
+**初始化SDK**
+
+```
+[ThinkingData] Info: ThinkingData SDK 1.3.3 initialize success with mode: NORMAL, APP ID ends with: e6ef, server url: https://receiver-ta-demo.thinkingdata.cn, device ID: ad6a69cf-3f2c-47ed-a6e9-4808e36cc61f
+```
+
+**数据存储本地**（关键词：`[ThinkingData] Info: Enqueue data`）
+
+```
+[ThinkingData] Info: Enqueue data : {...}
+```
+
+**数据上报TA**（关键词：`[ThinkingData] Info: Send event`）
+
+```
+[ThinkingData] Info: Send event, Request = {...}
+```
+
+**上报TA结果**（关键词：`[ThinkingData] Info: Response`）
+
+打印了Response，就可以认为上报成功。只看response的状态码为200，不看返回内容中的code
+
+```
+[ThinkingData] Info: Response :{"responseCode":200,...}
+```
+
+# 三、TE系统查询数据
+
+使用sql通过#device_id查询数据，这里数据最及时，实时数据也没这里及时
+
+1. 分析中选择SQL查询
+2. 解析事件表，where中添加#device_id

package/skills/data-integration-helper/references/sdk_usage_notes.md

@@ -0,0 +1,105 @@
+# SDK 使用注意事项
+
+# 一、客户端 SDK
+
+1. **上报模式**
+  - 生产环境请使用 `Normal` 模式；
+  - `Debug` 和 `Debug_Only` 模式仅用于测试阶段调试，请勿在生产环境和正式阶段使用；
+
+2. **缓存上报策略**
+  - Android、iOS 原生 SDK 以及底层调用 Android、iOS SDK 的游戏引擎 SDK 和跨平台 SDK，默认采用数据缓存和批量上报策略，上报时机默认 30条/30秒，即设备本地缓存达到 30 条数据或每隔 30 秒触发数据上报。可以在 TE Web "项目管理"页面调整上报频率，但如果上报过于频繁（比如 1条/1秒）会导致客户端系统 CPU、内存、网络等开销增加，引发设备过热、卡顿等问题。
+  - JS、小游戏/小程序 SDK 默认不开启本地缓存，数据会直接上报，也可以在 SDK 设置开启本地缓存和批量上报功能；
+  - 对原生SDK，在Normal模式下，调用`track()`方法不会立刻触发数据上报，会根据缓存上报策略上报；如果希望数据立刻上报，可以调用 `flush()` 方法触发。
+
+3. **上报失败处理**
+  - 对于开启本地缓存情况，上报失败的数据会在本地保存并在下次触发上报条件时重新上报；
+  - 如果未开启本地缓存，可以通过callback 对上报失败的情况自定义处理方式，避免数据丢失；
+
+4. **属性类型**
+  - 对于 TE 预置属性（比如 `#account_id`、`#time` 、`#ip` 等），属性类型是 TE 系统固定设置的，预置属性清单详见预置属性与系统字段。
+  - 对于自定义属性（除 TE 预置属性外的属性），属性类型是 TE 系统根据属性值自动识别的，第一条携带该属性的数据中的属性值决定了属性的类型；
+  - 如果上报数据中属性值与 TE 系统的属性类型不一致，系统会尝试强制转换，如果转换成功该属性会入库，如果转换失败**该属性会被丢弃**；
+  - 建议关注上报管理中的异常入库，及时识别异常数据和修复；如果对数据质量要求较高，也可以上传埋点方案，并参考项目数据处理规则设置数据处理规则，确保属性类型和预期一致；
+  - 元数据管理工具支持修改属性类型，需要注意，**修改类型后属性值会被清空置为NULL**。
+
+5. **时间校准**
+  - 建议开启时间校准功能，避免由于设备系统时间不准确导致数据时间偏差，影响后续分析；
+  - 客户端上报，TE 接收前10天至后3天时间范围的数据，超出时间范围的**数据会被丢弃**；
+  - 只需要在 SDK 初始化后做一次时间校准，不需要多次校准；
+  - 时间校准方式建议优先用服务器时间戳校准，如果失败再用 NTP 校准作为备选，不要同时使用两种方式校准。
+
+6. **自动采集事件**
+  - SDK 初始化后建议在完成时间校准后立刻开启自动采集，以及时生成 `ta_app_install` `ta_app_start`等自动采集事件，避免自动采集事件生成滞后；
+
+7. **敏感信息采集**
+  - 由于法律要求，通常需要向用户展示隐私协议并获取许可后才能初始化 TE SDK 开启数据采集，请遵循各国法律和各应用商店要求披露和采集敏感信息；
+  - Android SDK 会采集 `Android ID` 等信息，可以在配置文件中设置屏蔽。
+
+8. **关键数据上报**
+  - 付费、生成订单等关键数据建议从服务端上报，避免客户端上报延迟或丢失；
+  - 从客户端上报的重要数据，可以调用 `flush()` 立即触发上报。
+
+9. **数据加密**
+  - 客户端 SDK 支持开启数据加密
+  - 需要在 AE 集群配置密钥，具体配置流程请咨询客户成功人员；
+  - 客户端 SDK 示例（Android）：
+    ```kotlin
+    val config = TDConfig.getInstance(context, APP_ID, SERVER_URL)
+    config.enableEncrypt(1, "publicKey")  // 开启加密
+    ```
+
+10. **应用出海**
+  - 如果应用投放海外，建议 TE 集群就近部署，避免跨墙等原因影响数据上报；
+  - 如果应用全球投放，或数据需要从海外上报至部署在国内的 TE 集群，建议在应用主要投放地区就近部署一组或多组转接点，避免数据丢失和延迟；
+  - 对于 SAAS 客户，TE SAAS 已经在全球多地部署转接点，请使用 TE SAAS 的海外上报地址 `https://global-receiver-ta.thinkingdata.cn`。
+
+# 二、服务端 SDK
+
+1. **上报模式**
+  - 服务端SDK建议用LoggerConsumer配合Logbus上报，避免数据丢失；
+  - 如果用BatchConsumer需要处理上报失败返回的异常，部分SDK不返回异常，具体可参考[SDK代码](https://github.com/ThinkingDataAnalytics)；
+  - 正式环境不能使用DebugConsumer；
+
+2. **缓存上报策略**
+  - 由于性能原因，LoggerConsumer将数据批量写入文件，BatchConsumer将数据批量上报；
+  - BatchConsumer 调用 `track()`不会立刻触发上报，对需要立即上报的关键数据可以调用 `flush()` ；
+
+3. **上报失败处理**
+  - 对于网络波动导致的上报失败，BatchConsumer 会重试上报3次，3次失败后会抛弃数据并返回错误信息，需要自行处理错误，详见各SDK源码；
+  - 使用BatchConsumer如果网络长时间中断，当缓存数据数量大于缓存区上限时（batch*max_cache_size），会开始丢弃最早的数据，**导致缓存数据丢失**；
+
+4. **关闭SDK**
+  - 当程序退出需要关闭SDK，否则会**导致缓存数据丢失**；
+  - 服务器非正常重启导致SDK异常退出，会**导致缓存数据丢失**；
+  - 不同SDK关闭的方法不同，比如`close()`、`ta_free()`，详见SDK接口文档；
+
+5. **公共属性和动态公共属性**
+  - 公共属性的功能适合在客户端SDK采集用户级信息，服务端SDK不建议使用公共属性功能；
+
+6. **IP、国家、地区信息**
+  - TE 数据中的国家地区信息根据数据的ip信息解析，客户端上报 TE 会自动获取和存储IP信息，服务端上报需要在数据中添加"#ip"后 TE 才会处理；
+
+7. **多线程和多进程**
+  - 服务端SDK基本都支持多线程，`track()`方法中会做加锁处理，可以通过SDK源码确认；
+  - 对于多进程情况，如果使用 LoggerConsumer，每个进程的数据要写入独立文件或独立文件夹，如果写入同一个文件会**导致数据错乱**；
+
+8. **时区信息**
+  - 客户端SDK上报数据中会自动带有设备系统的时区信息，服务端SDK数据需要自行添加"#zone_offset"属性上报时区信息。
+
+# 三、多端上报
+
+多端上报场景下的常见问题和解决方案详见多端上报最佳实践。
+
+1. **用户 ID 一致**
+  - 从多端上报时，需要保证同一个用户数据 `#distinct_id`和 `#account_id` 一致，否则可能会**导致用户割裂**；
+  - 如果使用单账号多设备分析体系，需要保证数据的`#account_id`相同且数据中带有`#distinct_id`，避免出现用户被割裂为多个 TE 用户的情况；
+
+2. **多端时间对齐**
+  - 客户端SDK会上报时区偏移"#zone_offset"，默认取设备系统时区，部分SDK支持传参指定；
+  - 服务端SDK不会自动上报时区偏移"#zone_offset"，需要在properties中手动添加上报。
+
+3. **避免重复上报**
+  - 避免多端上报相同事件，导致数据重复
+
+4. **关键数据上报**
+  - 付费、生成订单等关键数据建议从服务端上报，避免客户端延迟或丢失。

package/skills/data-integration-helper/references/unity_sdk_faq.md

@@ -0,0 +1,115 @@
+---
+title: "Unity SDK FAQ"
+code: "unity_sdk_faq"
+source: "Feishu MCP"
+doc_id: "wikcnZ5YKmQd4b26mJQ2uiF6fvd"
+fetched_at: "2026-04-20T17:29:38Z"
+---
+
+> 本文主要针对 Unity 打包除 Android / iOS 之外平台的问题。Android / iOS 平台默认使用原生 SDK。
+
+# SDK 初始化
+## 推荐初始化 SDK 初始化位置
+- 建议在用户同意隐私协议后再进行 SDK 初始化
+
+## 初始化方式
+### 手动初始化
+```csharp
+using ThinkingData.Analytics;
+TDAnalytics.Init("APPID","SERVER");
+// 或通过 TDConfig 初始化
+TDConfig config = new TDConfig("APPID","SERVER");
+TDAnalytics.Init(config);
+```
+
+### 自动初始化
+- 添加 TDAnalytics 预置体，并设置 SDK 配置
+
+# 数据缓存机制
+## 存储位置
+- 通过 PlayerPrefs 存储，Mac OS X 上存储在 ~/Library/Preferences
+
+## 缓存限制
+- 没有限制缓存数据量上限，缓存数据没有过期删除策略
+
+# 数据上报策略
+## 触发数据上报场景
+- APP 切换到后台
+- 产生自动采集事件
+- 调用 flush() 接口
+- 缓存数据量达到阈值（默认 30 条）
+- 上报时间间隔超过阈值（默认 30 秒）
+- DEBUG / DEBUG_ONLY 模式下直接上报
+
+# 访客 ID（#distinct_id）
+## 设置访客 ID
+```csharp
+TDAnalytics.SetDistinctId("Thinker");
+```
+
+## 访客 ID 改变场景
+- 用户清除应用数据
+- 用户卸载重装或更换设备
+- 调用 SetDistinctId() 接口
+
+# 账号 ID（#account_id）
+## 设置账号 ID
+```csharp
+TDAnalytics.Login("TA");
+```
+
+# 设备 ID（#device_id）
+## 生成规则
+- UNITY_WEBGL：取 System.Guid.NewGuid().ToString("N")
+- 其它平台：取 SystemInfo.deviceUniqueIdentifier
+
+# Debug 模式
+## Normal，Debug，DebugOnly 模式区别
+
+| 模式 | 上报模式 | 数据入库 | 数据严格检查 | 数据加密 |
+|------|----------|----------|--------------|----------|
+| Normal | 批量上报 | 是 | 否 | 支持 |
+| Debug | 逐条上报 | 是 | 是 | 不支持 |
+| DebugOnly | 逐条上报 | 否 | 是 | 不支持 |
+
+# 自动采集事件
+## ta_app_install
+- 应用安装或卸载后重装时触发
+
+## ta_app_start
+- 应用程序获得焦点
+
+## ta_app_end
+- 应用程序失去焦点或退出
+
+## ta_app_crash
+- 监听到 UnhandledException 或 LogType.Error 等
+- 2.2.0 以上版本会默认采集 C# 异常
+
+## ta_scene_loaded / ta_scene_unloaded
+- 监听 SceneManager 的回调
+
+# 公共事件属性
+## 静态公共事件属性
+- setSuperProperties 方法，存在本地
+
+## 动态公共事件属性
+- 每次 track() 时调用回调函数获取当前值
+
+## 属性优先级
+- 用户自定义事件属性 > 动态公共事件属性 > 静态公共事件属性
+
+# 预置属性
+## #ip
+- TE 服务器获取 http 请求 header 中的 ip
+
+## #os
+- Unity WebGL 转的微信小游戏 #os 为 "other"
+
+# 异常问题
+详见文档完整内容。
+
+# 已知问题
+- 打包 iOS & Android 后 #zone_offset 缺失问题
+- 多个版本已知 bug 及修复版本
+详见文档完整内容。

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

@@ -19,11 +19,15 @@ description: 交互式将 AE 埋点方案落为用户项目代码、LogBus2 配
 |---|---|---|
 | AE projectId | `meta.project_id` | 有值 → 确认；无值 → 询问 |
 | AE web 地址 | `meta.host` | 有值 → 确认；无值 → 询问 |
+| **SERVER_URL** | `meta.server_url` | **必须询问**，数据上报地址，与 web 地址不同 |
+| **APP_ID** | `meta.app_id` | **必须询问**，来自 AE 后台「接入配置」 |
 | SDK 集成模式 | `meta.sdk_integration_mode` | 有值 → 直接使用 |
 | 客户端 SDK 类型 | `meta.client_platforms`（优先）或 `meta.client_sdk_type` | 有值 → 直接使用 |
 | 服务端语言 | `meta.server_language` | 有值 → 直接使用 |
 | 用户体系 | `meta.user_identity` | 有值 → 直接使用 |
 
+**注意**：`project_id` ≠ `APP_ID`，`host` ≠ `SERVER_URL`。即使 project_id 和 host 已有值，SERVER_URL 和 APP_ID 仍需单独询问。
+
 **多平台支持**：
 - 若 `client_platforms` 存在（数组），则为多平台场景，需为每个平台生成代码
 - 若只有 `client_sdk_type`，则为单平台（向后兼容）
@@ -43,12 +47,14 @@ description: 交互式将 AE 埋点方案落为用户项目代码、LogBus2 配
 - 用户 `yes` → 使用 draft 值
 - 用户输入新值 → 更新 draft.json 并使用新值
 
-### 需要询问的配置（如果 draft 中无值）
+### 需要询问的配置（必须逐项确认）
+
+**⚠️ 关键：SERVER_URL 和 APP_ID 是独立的配置项，即使 draft.json 中已有 project_id 和 host 也必须询问。`project_id` ≠ `APP_ID`，`host` ≠ `SERVER_URL`。**
 
 1. **SERVER_URL** — 数据上报地址（**与 web 地址不同**；请前往 AE 系统「项目管理」→「接入配置」→ 填写「公网地址」）
    - ⚠️ 「公网地址」需要填写过才会显示，如果没填过不会显示此字段
    - 解决方案：咨询运维获取地址，或**跳过此步骤**（代码中可暂时用 `SERVER_URL` 或 `PUSH_URL` 替代）
-2. **appId** — 请前往 AE 系统「项目管理」→「接入配置」→ 复制「APP_ID」
+2. **APP_ID** — 请前往 AE 系统「项目管理」→「接入配置」→ 复制「APP_ID」
 
 **host 处理**（可选）：
 - 如果需要从 AE fetch plan（无本地 draft.json）→ 询问 host
@@ -56,7 +62,19 @@ description: 交互式将 AE 埋点方案落为用户项目代码、LogBus2 配
 
 ### 如果只有 xlsx 文件（无 draft.json）
 
-用户直接提供 xlsx 埋点方案文件（通过 `ae-tracking code import-xlsx` 命令或放在 `.ae-tracking/draft.xlsx`），则进入此流程：
+首先检查是否同时存在 `.ae-tracking/draft.json` 和 `.ae-tracking/draft.xlsx`：
+
+**若两者都不存在** — 说明当前环境尚未生成过埋点方案。此时提醒用户两种选择：
+
+1. **是否需要先生成埋点方案？**
+   - 是 → 提示用户使用 `generate-tracking-plan` skill 生成埋点方案
+   - 附：埋点方案文档路径（飞书：https://www.feishu.cn/docx/Jt0VdhNB6oSJ4TxISs1cq2Ebnmg）
+
+2. **如果已有埋点方案**
+   - 提供 xlsx 文件路径，使用 `ae-tracking code import-xlsx` 命令导入
+   - 或将 xlsx 文件放到 `.ae-tracking/draft.xlsx` 后再执行
+
+**若存在 xlsx 文件**（用户通过 `ae-tracking code import-xlsx` 命令提供，或放在 `.ae-tracking/draft.xlsx`），则进入以下流程：
 
 **Step 1：解析 xlsx 文件**
 
@@ -259,13 +277,16 @@ ae-tracking plan fetch --project <projectId> --host <host> > .ae-tracking/remote
 
 提供快捷选项，简化交互：
 
-**选项 1：全都生成片段**
-- 所有端/平台都选择 `snippet`
-- 一次性输出 markdown + 多个代码文件 + LogBus2 配置
-- 无需指定项目路径
+**选项 1：一键生成（推荐）**
+- 所有端/平台都选择 `snippet`（代码片段）
+- 一次性生成所有代码文件到 `.ae-tracking/output/`
+- **无需指定项目路径**，直接给出可复制的代码
+- 适合快速获取代码参考、复制到项目中使用
 
-**选项 2：逐个选择**
-- 每个端/平台独立选择输出方式
+**选项 2：插入到项目**
+- 每个端/平台独立选择 `insert`（插入）或 `snippet`（片段）
+- **需要指定项目路径**，代码会写入你的项目目录
+- 适合已有项目、想让代码直接落到对应位置
 
 ### 2.3 逐个选择流程
 
@@ -510,7 +531,8 @@ TDAnalytics.track("user_login", new HashMap<String, Object>() {{
 
 ## 禁止
 
-- 任何 `insert` 执行前未跑 `git status` 检查
+- **任何 `insert` 执行前未跑 `git status` 检查（重要：必须先检查，有未提交改动则拒绝执行）**
+- 在 Phase 3 跳 reference 直接乱插
 - 在 Phase 3 跳 reference 直接乱插
 - 忽略 `// @tracking <event>` 注释的增量检测
 - 复用 web host 当 SERVER_URL（必须分开）
@@ -519,6 +541,7 @@ TDAnalytics.track("user_login", new HashMap<String, Object>() {{
 - 生成客户端代码时包含 `platform === "server"` 的专属事件
 - 生成服务端代码时包含 `platform === "client"` 的专属事件（除非 `platform === "both"`）
 - **跳过读 SDK 主文档直接凭猜测选集成方式** — 各 SDK 集成方式不同，必须先读 wiki 主文档的「集成 SDK」章节，根据项目特征（有/无构建工具）选择正确方式
+- **Stage 0.5 未完成就进入 Stage 1** — SDK 集成必须在插入代码前确认，否则生成的 track() 调用无法执行
 
 ---
 

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

@@ -9,6 +9,39 @@
 
 **禁止**：跳过 Stage 0 直接写代码、凭猜测选择集成方式、使用不确定的 CDN URL
 
+### Stage 0.5: SDK 集成确认（Stage 0 完成后必须执行）
+
+根据第 3 步选择的集成方式，向用户确认 SDK 是否已引入：
+
+**需要代码改动的集成方式（npm / Gradle / CocoaPods / Maven / pip / go get 等）**：
+
+```
+检测到项目使用 <集成方式>，需要修改配置文件添加依赖。
+
+是否需要我直接修改配置文件添加 SDK 依赖？
+- yes → Edit 修改配置文件（如 package.json / build.gradle / Podfile 等），完成后进入 Stage 1
+- no → 参考以下文档完成 SDK 引入，完成后回答 yes 继续
+
+文档：<wiki 文档路径>
+```
+
+- 用户 `yes` → 执行 Edit 修改配置文件，完成后进入 Stage 1
+- 用户 `no` → 显示文档路径，暂停等待用户完成
+
+**无需代码改动的集成方式（CDN script 标签 / UnityPackage / 手动放置文件等）**：
+
+```
+项目使用 <集成方式>，无需修改配置文件。
+
+请参考以下文档完成 SDK 引入，完成后回答 yes 继续。
+
+文档：<wiki 文档路径>
+```
+
+等待用户确认完成后，进入 Stage 1。
+
+---
+
 ## Stage 1: Explore
 1. Grep 入口：`src/main.*`、`src/App.*`、`pages/_app.*`、`index.html`
 2. Grep 现有埋点：`ta\.track|thinkingdata|TA\.init|// @tracking`