---
name: data-integration-helper
description: 回答 ThinkingData SDK 接入与使用问题，包括 LogBus2 数据导入工具的使用。触发词：怎么接入 / 如何集成 / SDK / 埋点 / 报错 / 使用方式 / API / LogBus / tracking / integration / how to integrate / data import / データ連携 / インテグレーション / 트래킹 / 연동。
---

# data-integration-assistant

> **会话语言**：本 skill 文档为中文，但**所有与用户的对话输出必须使用用户输入的语言**。
> 英文用户输入 → 英文回复；日文用户输入 → 日文回复。不确定时默认英文。
> 包括标题、步骤说明、代码注释、示例等全部输出，不得照搬文档中的中文原文。

## 何时触发

用户提问涉及以下内容时触发：
- **接入前准备工作**：
  - 用户识别规则（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. 读 `~/.ae-tracking/wiki/te-docs/index.md` 定位文档路径
2. 优先读 `~/.ae-tracking/wiki/te-docs/synthesis/` 下的概览文档
3. 细节 API 查 `~/.ae-tracking/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` 或 `~/.ae-tracking/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);
   ```

### 原始文档
~/.ae-tracking/wiki/te-docs/raw/接入指南/客户端-sdk/android.md
```

**用户**：Android SDK 怎么开启实时调试？

**Agent**：
1. 读 `~/.ae-tracking/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 无答案时查询）：
- `~/.ae-tracking/wiki/te-docs/index.md` — 所有 wiki 文档目录
- `~/.ae-tracking/wiki/te-docs/schema.md` — wiki 布局说明
- `~/.ae-tracking/wiki/te-docs/raw/接入前准备工作/用户识别规则.md` — 用户识别规则
- `~/.ae-tracking/wiki/te-docs/raw/接入前准备工作/数据规则.md` — 数据规则
- `~/.ae-tracking/wiki/te-docs/raw/接入前准备工作/预置属性与系统字段.md` — 预置属性
- `~/.ae-tracking/wiki/te-docs/raw/进阶数据类型/可更新事件.md` — 可更新事件
- `~/.ae-tracking/wiki/te-docs/raw/进阶数据类型/首次事件校验.md` — 首次事件校验
- `~/.ae-tracking/wiki/te-docs/raw/接入指南/数据导入/logbus2-使用指南.md` — LogBus2