ae-data-integration-helper

ae-data-integration-helper

对话语言：本文档使用英文编写，但所有面向用户的输出都必须使用用户输入的语言。 用户输入中文 → 回复中文；用户输入英文 → 回复英文；用户输入日文 → 回复日文。 如果不确定，默认使用英文。 这适用于所有输出：标题、步骤说明、代码注释、示例等。 ⚠️ 重要：许多参考文档（FAQ、wiki）使用中文。阅读中文资料并为使用英文或日文的用户作答时，必须将内容翻译成用户使用的语言。源文档的语言并不是用户使用的语言。切勿仅仅因为 wiki 页面使用中文，就向英文用户输出中文。请使用上方术语表准确映射术语。 请勿将本文档中的中文原文直接复制到英文或日文回复中。

术语表

中文	English	Notes
埋点 / 数据上报	Tracking / Data Ingestion	将事件数据发送到 AE
用户识别规则	User Identification Rule	distinct_id / account_id 映射
访客 ID	Visitor ID / Guest ID	登录前的匿名用户
登录 ID	Login ID / Account ID	登录后的已识别用户
预置属性	Preset Property	#device_id、#time、#ip 等
系统字段	System Field	AE 内置的、以 # 为前缀的字段
事件格式	Event Format	事件名称 + 属性结构
属性类型	Property Type	String / Number / Boolean / Date / Array
数据校验	Data Validation	验证事件格式和属性类型
公共事件属性	Super Property	附加到所有事件的属性。⚠️ AE 的正确中文术语是“公共事件属性”或“公共属性”。切勿将 “Super Property” 翻译为“超级属性”——这不是有效的 AE 术语。
可更新事件	Updatable Event	创建后仍可更新其属性的事件
首次事件校验	First Event Check	验证事件首次发生的情况
自动采集	Auto-track	自动采集的事件（应用安装、启动、页面浏览等）
实时调试	Real-time Debug / Debug Mode	设备绑定 + 实时数据校验
合规 / 隐私	Compliance / Privacy	GDPR、隐私政策、SDK 数据采集规则
数据导入	Data Import	LogBus2 / RESTful API / DataX
缓存上报	Batch Upload / Buffered Upload	在本地缓存事件，然后分批上传
重试策略	Retry Strategy	自动重新上传失败的数据
数据加密	Data Encryption	上传前加密事件数据
时间校准	Time Calibration	将设备时间与服务器时间同步
多端上报	Multi-platform Tracking	从多个客户端或服务上报事件
用户割裂	User Fragmentation	同一用户被拆分为多个 AE 用户档案
上报模式	Upload Mode	Normal / Debug / Debug_Only
LoggerConsumer	LoggerConsumer	将事件写入本地日志文件的服务端 SDK 消费者
BatchConsumer	BatchConsumer	分批上传事件的服务端 SDK 消费者
DebugConsumer	DebugConsumer	用于调试模式的服务端 SDK 消费者（不用于生产环境）

触发时机

用户询问以下内容时触发：

• 数据接入前准备：
  • 用户识别规则（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
• 高级数据类型：可更新事件 / 首次事件校验
• 自动采集：页面浏览 / 按钮点击 / 应用启动等
• 实时调试：调试模式 / 设备绑定 / 数据校验
• 合规 / 隐私：GDPR / 隐私政策 / SDK 数据采集规则
• API 使用：init / track / user_set / LoggerConsumer 等
• 配置：调试模式 / 数据校验 / 重试策略
• 故障排查：上传失败 / 数据缺失 / 格式错误

不要触发：在 ae-generate-tracking-plan 或 ae-generate-tracking-code 会话中进行的内嵌问答（这些技能有自己的工作流）。离线本地文件导入（CSV / Excel / JSONL → AE）和飞书表格 URL 导入由 ae-data-integration 技能负责——请将这些请求转交给该技能，而不要回答 LogBus / RESTful 相关内容。

工作流

步骤 1：解析问题

从用户的查询中提取：

• 主题类别：
  • 数据接入前准备：用户识别 / 数据规则 / 预置属性
  • 客户端 SDK：Android / iOS / JavaScript / Unity / OpenHarmony / 小程序等
  • 服务端 SDK：Java / Python / Go / Node.js / PHP / C# 等
  • 数据导入：LogBus2 / RESTful API / DataX
  • 高级数据类型：可更新事件 / 首次事件校验
  • 自动采集：页面浏览 / 按钮点击 / 应用启动
  • 实时调试：调试模式 / 设备绑定 / 数据校验
  • 合规：GDPR / 隐私政策 / SDK 数据采集规则
• 查询类型：集成方式 / API 使用 / 配置 / 部署 / 错误 / 日志

步骤 1.5：收集信息

⚠️ 核心原则：问题含糊时，应先收集信息，再作答。不要猜测或长篇赘述。

如果用户的问题涉及以下任一情况，请先收集关键信息，再继续处理：

情况	必须收集的信息
“没有显示数据” / “看不到数据” / “上传成功但仪表板中没有数据”	上传方式（SDK / LogBus / HTTP）、数据类型（事件 / 用户属性）、具体症状（完全没有数据 / 仅部分数据）
“错误” / “失败”类问题	完整错误消息、复现步骤
“无法连接” / “无法上传”	使用的平台 / 语言、错误症状
“如何实现 X”	使用的平台 / 语言、X 具体指什么

先询问，再回答。示例：

• “数据日志显示成功，但仪表板中没有数据——您使用的是 SDK、LogBus 还是 HTTP 上传？”
• “无法连接——您使用的是哪种语言 / 平台？可以提供错误消息吗？”

步骤 2：查找相关文档

优先查阅 FAQ 文档（快速查找特定问题）：

1. 阅读 skills/ae-data-integration-helper/references/ 中对应的 FAQ（例如，android_sdk_faq.md、logbus2_guide.md 等）
2. FAQ 文档涵盖特定问题排查、代码示例、参数表和最佳实践

FAQ 中没有答案时查阅 wiki（获取框架级和权威内容）：

1. 阅读 ~/.ae-cli/wiki/te-docs/index.md，查找文档路径
2. 优先查阅 ~/.ae-cli/wiki/te-docs/synthesis/ 下的概览文档
3. 如需详细的 API 参考，请查阅 ~/.ae-cli/wiki/te-docs/raw/ 下对应的主文档

常用 FAQ 文档：

• references/android_sdk_faq.md — Android SDK 集成与 FAQ
• references/ios_sdk_faq.md — iOS SDK 集成与 FAQ
• references/java_sdk_faq.md — Java SDK 集成与 FAQ
• references/logbus2_guide.md — LogBus2 完整配置指南
• references/sdk_usage_notes.md — 客户端/服务端 SDK 使用说明
• 完整列表：参见 references/index.md

步骤 3：阅读并总结

阅读相关文档后，按以下格式输出：

## <Topic> (<Platform>)

### Summary
<1-2 sentence description>

### Integration / Usage Steps
1. <Step 1>
2. <Step 2>
...

### Code Example
```<language>
<code>

注意事项 / 限制

• <注意事项 1>
• <注意事项 2>

来源文档

<优先提供 wiki 文档的 sourceUrl。语言规则：

• 用户使用中文交流 → 提供中文文档（lan=zh-CN）
• 用户使用其他语言交流 → 提供英文文档（lan=en-US）
• 仅支持中文的 SDK（小程序 / OpenHarmony / Cocos2d-Lua / LayaAir / Egret）→ 仅提供中文 示例：https://docs-v2.thinkingdata.cn/?version=v6.0&lan=en-US&code=xxx> （如果没有 sourceUrl，请提供本地 .md 文件路径）

**⚠️ Terminology Rules**:
- **Only output what is in the documentation**. Do NOT speculate, imagine, or fill in defaults.
- **Never translate "Super Property" as "超级属性"** — the correct AE Chinese term is "公共事件属性" or "公共属性". This applies to all user-facing output: headings, step descriptions, code comments, examples, etc.
- For uncertain information (e.g., data delay times, specific limit values), **do NOT fabricate**.
- If the document has no direct answer but allows inference: mark under "Source Document" as "Synthesized inference; recommend verification".
- If the documentation truly does not cover the question, fall back to Step 4. Do NOT force an answer.

### Step 4: Fallback

If neither FAQ nor wiki has relevant content:
- Provide the official online documentation link: https://docs-v2.thinkingdata.cn
- Optionally suggest running the `te-wiki-synthesize` skill to generate a new synthesis document.

## Example Conversations

**User**: What is distinct_id and how do I use it?

**Agent**:
1. Read `references/index.md` to find user identification rule document paths
2. If `sdk_usage_notes.md` or wiki has relevant sections, read those first
3. Output in the Step 3 format

**User**: How do I configure LogBus2?

**Agent**:
1. Read `references/logbus2_guide.md`
2. Output in the Step 3 format

**User**: Java SDK is losing data — what should I do?

**Agent**:
1. Read `references/java_sdk_faq.md`, section on "LoggerConsumer data loss risks"
2. Output in the Step 3 format

**User**: How do I integrate the Android SDK?

**Agent**:
1. Read `references/android_sdk_faq.md` or `~/.ae-cli/wiki/te-docs/index.md` to find Android SDK path
2. Read the relevant sections
3. Output in the Step 3 format

Android SDK 集成

概述

Android SDK 支持通过 Gradle 和手动集成 AAR。推荐使用 Gradle。

集成步骤（Gradle）

1. 在项目级 build.gradle 中添加 mavenCentral：

   repositories { mavenCentral() }
   

2. 在模块级 build.gradle 中添加依赖：

   dependencies {
       implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.3.6'
   }
   

3. 初始化 SDK：

   TDAnalytics.init(this, SERVER_URL, APPID);
   

来源文档

~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android.md

**User**: How do I enable real-time debugging for Android SDK?

**Agent**:
1. Read `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/client-sdk/android/android-advanced/debugging-and-logging.md`
2. Output in the Step 3 format

## Internal Reference

**FAQ Documents** (check first):
- `references/index.md` — All FAQ document index
- `references/android_sdk_faq.md` — Android SDK FAQ
- `references/logbus2_guide.md` — LogBus2 complete guide
- `references/sdk_usage_notes.md` — SDK usage notes

**Wiki Documents** (check when FAQ has no answer):
- `~/.ae-cli/wiki/te-docs/index.md` — All wiki document index
- `~/.ae-cli/wiki/te-docs/schema.md` — Wiki layout description
- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/user-identification-rules.md` — User Identification Rules
- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/data-rules.md` — Data Rules
- `~/.ae-cli/wiki/te-docs/raw/preparations-before-data-ingestion/preset-properties-and-system-fields.md` — Preset Properties
- `~/.ae-cli/wiki/te-docs/raw/advanced-data-type/updated-event.md` — Updatable Event
- `~/.ae-cli/wiki/te-docs/raw/advanced-data-type/first-event-check.md` — First Event Check
- `~/.ae-cli/wiki/te-docs/raw/data-ingestion-guide/data-import-tools/logbus2-user-guide.md` — LogBus2