ae-tracking 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.2.0 (2026-05-17)
+
+### Overview
+
+v0.2.0 adds a new `data-integration-helper` skill, improves code generation flexibility with Excel-only workflows, and refines SDK integration.
+
+### Features
+
+**generate-tracking-code skill**:
+- Support generating tracking code from Excel alone (without a full tracking plan)
+- Tracking plan Excel now includes `采集端` (collection platform) column
+- Code generation parses the `采集端` column to determine client/server/both event types
+- Optimized SDK package import process
+
+**data-integration-helper skill** (new):
+- Q&A support for ThinkingData SDK integration and usage questions
+- Covers LogBus2 data import tool usage
+- Trigger keywords: 怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus
+
+### Dependencies
+
+- Node.js ≥ 20
+- exceljs, undici, commander
+
 ## 0.1.0 (2026-05-11)
 
 ### Overview

package/dist/src/cli/init.js

@@ -2,7 +2,7 @@ import { mkdir, readlink, lstat, unlink, symlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getPackageRoot } from './package-root.js';
 import { getClaudeSkillsDir, getTeTrackingDir } from './home.js';
-const SKILL_NAMES = ['generate-tracking-plan', 'generate-tracking-code'];
+const SKILL_NAMES = ['generate-tracking-plan', 'generate-tracking-code', 'data-integration-helper'];
 async function linkTarget(path) {
     try {
         const s = await lstat(path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ae-tracking",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AE (AgenticEngine) tracking-plan agent with Claude Code skills",
   "private": false,
   "type": "module",

package/skills/data-integration-helper/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: data-integration-helper
+description: 回答 ThinkingData SDK 接入与使用问题，包括 LogBus2 数据导入工具的使用。触发词：怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus。
+---
+
+# data-integration-assistant
+
+## 何时触发
+
+用户提问涉及以下内容时触发：
+- **接入前准备工作**：
+  - 用户识别规则（distinct_id / account_id / 访客 ID / 登录 ID）
+  - 数据规则（事件格式 / 属性类型 / 校验）
+  - 预置属性与系统字段（#device_id / #time 等）
+- **客户端 SDK 接入**：Android / iOS / JavaScript / Unity / OpenHarmony / 小程序 等
+- **服务端 SDK 接入**：Java / Python / Go / Node.js / PHP / C# 等
+- **数据导入**：LogBus2 / RESTful API / DataX
+- **进阶数据类型**：可更新事件 / 首次事件校验
+- **自动采集**：页面浏览 / 控件点击 / App 启动等自动事件
+- **实时调试**：debug 模式 / 设备绑定 / 数据校验
+- **合规 / 隐私**：GDPR / 隐私声明 / SDK 信息收集规则
+- **API 使用**：init / track / user_set / LoggerConsumer 等
+- **配置参数**：debug 模式 / 数据校验 / 重试策略
+- **报错排查**：上报失败 / 数据没到 / 格式错误
+
+**不触发**：generate-tracking-plan / generate-tracking-code 的对话内答疑（那些 skill 有自己的流程）
+
+## 工作流程
+
+### Step 1: 解析问题
+
+从用户提问中提取：
+- **主题分类**：
+  - 接入前准备：用户识别 / 数据规则 / 预置属性
+  - 客户端 SDK：Android / iOS / JavaScript / Unity / OpenHarmony / 小程序 等
+  - 服务端 SDK：Java / Python / Go / Node.js / PHP / C# 等
+  - 数据导入：LogBus2 / RESTful API / DataX
+  - 进阶数据类型：可更新事件 / 首次事件校验
+  - 自动采集：页面浏览 / 控件点击 / App 启动
+  - 实时调试：debug 模式 / 设备绑定 / 数据校验
+  - 合规：GDPR / 隐私声明 / SDK 信息收集规则
+- **主题类型**：接入方式 / API 调用 / 配置 / 部署 / 报错 / 日志
+
+### Step 1.5: 信息收集
+
+**⚠️ 关键原则：问题模糊时，先收集信息再解答，不要发散回答。**
+
+如果用户描述的问题涉及但不限于以下场景，**必须先收集关键信息**再继续：
+
+| 场景 | 必须收集的信息 |
+|------|--------------|
+| "数据没到" / "看不到数据" / "上报成功但后台没有" | 上报方式（SDK / LogBus / HTTP）、数据类型（事件 / 用户属性）、具体现象（完全没数据 / 部分没数据） |
+| "报错" 类问题 | 完整报错信息、复现步骤 |
+| "接不上" / "无法上报" | 使用的平台/语言、错误现象 |
+| "如何实现 X" | 使用的平台/语言、X 的具体含义 |
+
+**先问再答**，例如：
+- "数据日志显示成功但系统看不到 — 你用的是 SDK、LogBus 还是 HTTP 上报？"
+- "接不上 — 你用的是什么语言/平台？报错信息能贴一下吗？"
+
+### Step 2: 查找相关文档
+
+**优先查 FAQ 文档**（快速定位具体问题）：
+1. 读 `skills/data-integration-helper/references/` 对应 FAQ（如 `android_sdk_faq.md`、`logbus2_guide.md` 等）
+2. FAQ 文档覆盖具体排查问题、代码示例、参数表、最佳实践
+
+**FAQ 无答案时查 wiki**（获取框架性和权威内容）：
+1. 读 `wiki/te-docs/index.md` 定位文档路径
+2. 优先读 `wiki/te-docs/synthesis/` 下的概览文档
+3. 细节 API 查 `wiki/te-docs/raw/` 对应主文档
+
+**常用 FAQ 文档**：
+- `references/android_sdk_faq.md` — Android SDK 接入与常见问题
+- `references/ios_sdk_faq.md` — iOS SDK 接入与常见问题
+- `references/java_sdk_faq.md` — Java SDK 接入与常见问题
+- `references/logbus2_guide.md` — LogBus2 完整配置指南
+- `references/sdk_usage_notes.md` — 客户端/服务端 SDK 使用注意事项
+- `references/restful_api_notes.md` — RESTful API 使用注意事项
+- 完整列表见 `references/index.md`
+
+### Step 3: 读取并总结
+
+读相关文档后，按以下格式输出：
+
+```
+## <主题>（<平台>）
+
+### 简要说明
+<1-2 句话说明>
+
+### 集成/使用步骤
+1. <步骤 1>
+2. <步骤 2>
+...
+
+### 代码示例
+```<语言>
+<代码>
+```
+
+### 注意事项
+- <注意点 1>
+- <注意点 2>
+
+### 原始文档
+<优先提供 wiki 文档的 sourceUrl，如 https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=xxx>
+（若无 sourceUrl，则提供本地 md 文件路径）
+```
+
+**⚠️ 信息准确性原则**：
+- **只输出文档中有的内容**，不要推测、想象、默认填充
+- 不确定的信息（如数据延迟时间、具体限制数值等）**不要捏造**
+- 如文档无直接答案，但可推断：在"原始文档"中标注"综合推断，建议验证"
+- 如果文档确实没有覆盖这个问题，走 Step 4 兜底，不要硬撑
+
+### Step 4: 兜底
+
+若 FAQ 和 wiki 均无相关内容：
+- 提供官方在线文档链接：https://docs-v2.thinkingdata.cn
+- 可选：提示可运行 `te-wiki-synthesize` skill 生成新的合成文档
+
+## 示例对话
+
+**用户**：distinct_id 是什么？怎么用？
+
+**Agent**：
+1. 读 `references/index.md` 找到用户识别规则文档路径
+2. 若有 `sdk_usage_notes.md` 或 wiki 对应章节，先读
+3. 按 Step 3 格式输出
+
+**用户**：LogBus2 怎么配置？
+
+**Agent**：
+1. 读 `references/logbus2_guide.md`
+2. 按 Step 3 格式输出
+
+**用户**：Java SDK 丢数怎么办？
+
+**Agent**：
+1. 读 `references/java_sdk_faq.md` 的"LoggerConsumer 丢数风险"章节
+2. 按 Step 3 格式输出
+
+**用户**：Android SDK 怎么接入？
+
+**Agent**：
+1. 读 `references/android_sdk_faq.md` 或 `wiki/te-docs/index.md` 找到 Android SDK 路径
+2. 读对应章节
+3. 按 Step 3 格式输出
+
+```
+## Android SDK 接入
+
+### 简要说明
+Android SDK 支持 Gradle 和手动 AAR 两种集成方式，推荐 Gradle。
+
+### 集成步骤（Gradle）
+1. 在项目级 `build.gradle` 添加 mavenCentral：
+   ```groovy
+   repositories { mavenCentral() }
+   ```
+2. 在模块级 `build.gradle` 添加依赖：
+   ```groovy
+   dependencies {
+       implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
+   }
+   ```
+3. 初始化 SDK：
+   ```java
+   TDAnalytics.init(this, SERVER_URL, APPID);
+   ```
+
+### 原始文档
+wiki/te-docs/raw/接入指南/客户端-sdk/android.md
+```
+
+**用户**：Android SDK 怎么开启实时调试？
+
+**Agent**：
+1. 读 `wiki/te-docs/raw/接入指南/客户端-sdk/android/进阶指南/实时调试.md`
+2. 按 Step 3 格式输出
+
+## 内部参考
+
+**FAQ 文档**（优先查询）：
+- `references/index.md` — 所有 FAQ 文档索引
+- `references/android_sdk_faq.md` — Android SDK FAQ
+- `references/logbus2_guide.md` — LogBus2 完整指南
+- `references/sdk_usage_notes.md` — SDK 使用注意事项
+
+**wiki 文档**（FAQ 无答案时查询）：
+- `wiki/te-docs/index.md` — 所有 wiki 文档目录
+- `wiki/te-docs/schema.md` — wiki 布局说明
+- `wiki/te-docs/raw/接入前准备工作/用户识别规则.md` — 用户识别规则
+- `wiki/te-docs/raw/接入前准备工作/数据规则.md` — 数据规则
+- `wiki/te-docs/raw/接入前准备工作/预置属性与系统字段.md` — 预置属性
+- `wiki/te-docs/raw/进阶数据类型/可更新事件.md` — 可更新事件
+- `wiki/te-docs/raw/进阶数据类型/首次事件校验.md` — 首次事件校验
+- `wiki/te-docs/raw/接入指南/数据导入/logbus2-使用指南.md` — LogBus2

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

@@ -0,0 +1,179 @@
+---
+title: "Android SDK FAQ"
+code: "android_sdk_faq"
+source: "Feishu MCP"
+doc_id: "wikcnVrL8nNo5bwytvIVde3MT8e"
+fetched_at: "2026-04-20T17:29:37Z"
+---
+
+# 集成 SDK
+## 集成方式
+- Android SDK 支持自动集成 gradle 和 手动集成 aar 两种接入方式。
+### gradle 方式导入
+- 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖
+```json
+buildscript {
+    repositories {
+        jcenter()
+        mavenCentral()
+    }
+}
+```
+
+- 在 `Module` 工程目录下的 `build.gradle`文件中添加依赖项：
+```java
+dependencies {
+    implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:2.8.3'
+}
+```
+
+### 本地 aar 导入
+参见官方文档。
+
+## 兼容性说明
+- Android SDK 兼容最低版本 Android 4.0
+  - `minSdkVersion 14`
+
+# 初始化
+## 推荐初始化位置
+- 建议在用户同意隐私协议后再进行 SDK 初始化，详见 ThinkingData 官方文档中的《合规指南》部分。
+```json
+// 根据隐私协议判断是否开启数据采集
+if (授权隐私政策) {
+    TDAnalytics.init(this, APPID, SERVER_URL);
+}
+```
+
+## 初始化方式一：其它配置默认，只需要传入 APPID 和 SERVER_URL 就可以
+```java
+// 在主线程中初始化 SDK
+TDAnalytics.init(this, APPID, SERVER_URL);
+```
+
+## 初始化方式二：根据 config 自定义一些参数配置
+- 模式设置
+  - config.setMode(TDConfig.TDMode.NORMAL);
+  - config.setMode(TDConfig.TDMode.DEBUG);
+  - config.setMode(TDConfig.TDMode.DEBUG_ONLY);
+- 模式时区设置
+  - config.setDefaultTimeZone(TimeZone.getDefault());
+- 是否开启多进程
+  - config.setMutiprocess(true);
+- 是否开启加密
+  - config.enableEncrypt(true)
+```java
+TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
+TDAnalytics.init(config);
+```
+
+# 上报模式
+## NORMAL
+- 在 Normal 模式下，数据会首先进入缓存，之后根据配置的上报规则进行批量上报，上报成功后数据会入库。
+
+## DEBUG
+- 在 Debug 模式下，数据会立即逐条上报。上报成功后数据会入库。
+- 如果上报失败，SDK 会采取降级处理，将 Debug 模式降级为 Normal 模式并且将失败数据缓存到本地。
+- 需要在应用程序中配置设备白名单。
+
+## DEBUG_ONLY
+- 在 DebugOnly 模式下，数据会立即逐条上报并且数据不会入库，如果上报失败，数据就会丢失。
+- 没有配置白名单不会自动切换到 NORMAL 模式。
+
+> 注意：
+> - 在正式上线时，建议避免使用 debug 或 debug_only 模式
+> - debug 模式下如果没有 TE 后台配置白名单会切换成 NORMAL 模式
+> - debug_only 不会自动切换成 NORMAL 模式
+
+# 上报策略
+- normal 模式默认 30 秒或者 30 条满足上报一次，TE 项目管理可以设置修改
+- debug / debug_only 模式事件会立即上报
+- 手动调用 flush() 接口，会立即上报缓存数据
+- 自动采集事件会立刻上报
+- 每个请求上限为 50 条数据
+
+# 缓存机制
+- 非 debug、debug_only 模式，数据会先缓存本地数据库，然后按策略发送
+- 默认本地缓存条数 1 万条，超过就会开始丢弃前面的数据
+- SDK 2.8.2 版本之前默认缓存 15 天，2.8.2 开始默认缓存 10 天
+- 可通过 ta_public_config.xml 配置缓存天数和条数
+
+# 自动采集
+## ta_app_install
+### 触发条件以及时机
+- 开启了 install 事件自动采集
+- 初始化 SDK 时判断 firstInstallTime
+
+## ta_app_start
+### 触发条件以及时机
+- 开启了 ta_app_start 事件自动采集
+- App 启动或者 App 从后台回到前台
+
+## ta_app_end
+### 触发条件以及时机
+- 开启了 end 事件自动采集
+- App 退出或者切换到后台，或者闪退
+
+## ta_app_crash
+### 触发条件以及时机
+- 开启了 crash 事件的自动采集
+- App 闪退的时候触发
+
+## ta_app_view
+### 触发条件以及时机
+- 开启了 view 事件的自动采集
+- Activity 或者 fragment 的页面显示的时候
+
+## ta_app_click
+### 触发条件以及时机
+- 开启了 click 事件的自动采集
+- 点击页面的控件
+- 需要接入全埋点插件
+
+# 预置属性
+## 设备 ID #device_id
+- 获取 AndroidID 或者随机生成的
+- 什么情况下会变：应用多开、拿不到 androidId 并卸载重装、刷机或更换包名
+
+## 模拟器 #simulator
+- 根据 Android 的 SystemProperties 来判断
+
+## 内存 #ram
+- 获取的是可用内存和总内存大小
+
+## 运营商 #carrier
+- 部分应用市场反馈安全检测存在未申请权限获取运营商的情况，可屏蔽该字段
+
+## 网络类型 #network_type
+- 事件发生时无网络则为 NULL
+
+## 访客 ID #distinct_id
+- 默认系统 UUID 方式生成，存本地
+- 卸载重装会变
+
+# 公共属性
+## 静态公共属性
+- 方法名 setSuperProperties
+- 把设置的属性存在本地 SharedPreferences
+
+## 动态公共属性
+- 方法名 setDynamicSuperPropertiesTracker
+- 每次 track 的时候会带上这个回调回来的属性
+
+# 数据加密
+- 默认是先 gzip 然后 base64 处理
+- 2.8.0 开始也可以选择开启非对称加密
+- 加密只对 normal 模式生效
+
+# 通用问题
+## 数据上报失败
+- 检查上报地址和 appid 是否正确
+  - {上报地址}/check_appid?appid={appid} 返回 0 表示正常
+- 服务异常
+  - {上报地址}/health_check 返回 ok 表示正常
+
+## 部分用户没有事件上报
+- 查看上报地址是否使用 https 协议，安卓 9.0 以上默认不支持 http
+- 初始化 SDK 是否有逻辑判断，有情况没有初始化
+
+# 已知问题
+详见文档完整内容。

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

@@ -0,0 +1,83 @@
+项目编译需要安装 `cmake`、`make`，建议使用较新的稳定版本。静态库编译时的目标架构必须和项目编译时采用的架构保持一致，例如 `ARM` 或 `x86_64`。当前仓库 `master` 分支默认要求 `CMake 3.12` 及以上版本。需要特别注意：SDK 对 C 标准的兼容性是按 Consumer 区分的，不是所有模式都统一兼容同一个 C 标准。
+
+## 一、源码编译
+
+本次源码编译环境采用：CentOS 9.7（x86_64）Make 4.3（x86_64）CMake 3.26.5（x86_64）
+
+### 下载项目
+
+```shell
+git clone https://github.com/ThinkingDataAnalytics/c-sdk.git
+```
+
+### 修改 CMakeLists.txt 文件
+
+进入项目文件夹后，按实际需要修改 `CMakeLists.txt`。当前仓库中包含四种 Consumer 的编译配置，但默认只启用了 `logging_consumer`；其他 Consumer 配置块默认是注释状态。
+
+生产环境建议一次只保留一种 Consumer 配置，避免生成多个模式的库文件后在接入时发生混淆。
+
+当前 `master` 分支中各 Consumer 对应的 C 标准和依赖如下：
+
+| Consumer | 当前脚本中的 C 标准 | 额外依赖 | 说明 |
+|----------|---------------------|----------|------|
+| `logging_consumer` | Windows/非 Windows 都是 `C89` | Windows 需要 `pcre` | 默认启用，正式环境推荐 |
+| `batch_consumer` | Windows/非 Windows 都是 `C99` | `curl` | 适合中小流量场景 |
+| `debug_consumer` | Windows/非 Windows 都是 `C99` | `curl` | 仅用于调试，不建议生产使用 |
+| `async_batch_consumer` | Windows 是 `C99`；非 Windows 是 `C89` | `curl`，非 Windows 还需要 `pthread` | 历史异步直传模式 |
+
+因此，"最新版 SDK 兼容 `C89`"这句话只适用于默认的 `logging_consumer`，不能直接推广到所有 Consumer。
+
+### 生成 Makefile 文件
+
+`CMakeLists.txt` 修改完成后，在项目根目录执行如下命令。命令成功后会生成 `Makefile`。
+
+```shell
+cmake CMakeLists.txt
+```
+
+### 生成静态库文件
+
+在 `Makefile` 同级目录执行如下命令：
+
+```shell
+make
+```
+
+需要注意：
+
+- 默认情况下，只会生成当前启用的 Consumer 对应静态库。
+- 如果手动把四段 Consumer 配置全部打开，理论上会生成四个静态库文件，但生产环境不建议这样做。
+- 当前仓库中的典型库文件命名如下：
+  - `libthinkingdata.a`：写日志文件模式，对应 `logging_consumer`
+  - `libthinkingDataAsyncBatch.a`：异步上报模式，对应 `async_batch_consumer`
+  - `libthinkingDataBatch.a`：批量上报模式，对应 `batch_consumer`
+  - `libthinkingDataDebug.a`：调试上报模式，对应 `debug_consumer`
+
+## 二、常见问题
+
+### 编译 c-sdk 源码报错：curl/curl.h: No such file or directory
+
+原因：除 `logging_consumer` 之外，其余直传类 Consumer 都依赖第三方库 `curl`；如果系统中未安装 curl 开发库，就会报这个错误。
+
+解决：CentOS 系统安装 curl 开发库：`sudo yum install libcurl-devel`
+
+### 项目链接静态库报错：lib/libthinkingDataBatch.a(http_client.c.o): In function `ta_http_post`:
+
+原因：`batch_consumer`、`debug_consumer`、`async_batch_consumer` 都会链接 `curl`；如果业务项目链接阶段没有显式带上 `curl`，就会出现相关符号找不到的问题。
+
+解决：项目编译时用 `-l` 指定链接 `curl`，例如：`gcc demo.c -o demo -lcurl`
+
+### 使用 AsyncBatchConsumer 模式项目编译报错：/usr/bin/ld: lib/libthinkingDataAsyncBatch.a(async_batch_consumer.c.o): undefined reference to symbol 'pthread_create@@GLIBC_2.2.5'
+
+原因：`AsyncBatchConsumer` 为异步上报模式，非 Windows 环境下除了 `curl` 之外还依赖 `pthread`。如果业务项目链接时没有显式链接线程库，就会报这个错误。
+
+解决：项目编译时同时指定 `curl` 和 `pthread`，例如：`gcc demo.c -o demo -lcurl -lpthread`
+
+### 到底该如何理解 C 标准兼容性？
+
+如果你是新项目接入方，可以按下面的方式理解：
+
+1. 如果使用默认推荐的 `logging_consumer`，当前仓库脚本按 `C89` 编译。
+2. 如果使用 `batch_consumer` 或 `debug_consumer`，当前仓库脚本按 `C99` 编译。
+3. 如果使用 `async_batch_consumer`，当前仓库脚本在不同平台上的 C 标准配置并不完全一致，不能简单概括为统一兼容 `C89` 或统一兼容 `C99`。
+4. 所以在文档、FAQ 或客户答复中，更准确的表述应当是"兼容性与所选 Consumer 有关"，不要直接笼统写成"整个 SDK 统一兼容 `C89`"。