ae-generate-tracking-code

ae-generate-tracking-code

对话语言：此技能文档使用英文，但所有面向用户的输出都必须使用用户输入的语言。 英文输入 → 英文回复；中文输入 → 中文回复；日文输入 → 日文回复。 如果无法确定，默认使用英文。 这适用于所有输出：章节标题、阶段名称、模板提示词、代码注释等。 ⚠️ 关键：许多参考文档（wiki SDK 文档、代码示例）包含中文内容。回答英文或日文用户的问题时，如果阅读了中文源材料，必须将标题、描述和注释翻译成用户使用的语言。源文档的语言不等于用户使用的语言。请使用上方的术语表准确映射术语。 不要将本文档中的中文原封不动地复制到英文或日文回复中。

文档链接语言：提供官方文档 URL 时，中文用户使用 lan=zh-CN，其他用户使用 lan=en-US。

术语表

中文	English	说明
埋点方案	Tracking Plan	AE 项目级事件／属性定义
代码埋点	Tracking Code Generation	根据方案生成 SDK／LogBus 代码
埋点代码	Tracking Code	生成的 SDK 初始化代码 + track() 调用 + 辅助工具
输出方式	Output Mode	insert（注入）或 snippet（文件交付）
插入	Insert	直接将代码注入用户的项目
片段 / 代码片段	Snippet	以文件形式交付到 .ae-cli/output/ 的代码
采集端	Collection Platform / Platform	事件的发送端：客户端、服务端或两者
客户端	Client	客户端 SDK（Android/iOS/Web 等）
服务端	Server	服务端 SDK（Java/Python/Go 等）
两端都采集	Both	客户端和服务端都采集的事件
SDK 集成模式	SDK Integration Mode	client_only / server_only / both
用户体系	User Identity System	distinct_id / account_id 策略
校验脚本	Validation / Debug Script	用于验证埋点是否正常工作的测试代码
LogBus2 配置	LogBus2 Configuration	LogBus2 日志同步工具的 daemon.json
LoggerConsumer	LoggerConsumer	将事件写入本地日志文件的服务端 SDK consumer
BatchConsumer	BatchConsumer	分批上传事件的服务端 SDK consumer
公共属性	Super Property	自动附加到所有事件的属性。⚠️ 正确的中文 AE 术语是“公共属性”或“公共事件属性”。切勿将“Super Property”翻译成“超级属性”——这不是有效的 AE 术语。
预置属性	Preset Property	以 # 为前缀的系统属性（例如 #device_id、#time）
事件属性	Event Property	特定事件上的自定义属性
用户属性	User Property	设置在用户档案上的属性
上报地址	SERVER_URL	数据接入端点（不同于 Web URL！）
APP_ID	APP_ID	AE 管理后台 →“集成配置”中的应用 ID
project_id	Project ID	AE 项目标识符（≠ APP_ID）
自动采集	Auto-track	自动采集的事件（应用安装、启动、浏览、点击）
埋点方案上传	Plan Upload	将埋点方案 xlsx 上传到 AE

触发条件

当用户提出“生成埋点代码／帮我添加 Web 埋点／生成 LogBus 配置／服务端上报代码”等请求时触发。支持多个平台，并可为每个平台独立选择输出方式。

阶段 0 — 确认（每条消息只问一个问题）

预检查：读取 draft.json 中的现有配置

首先，检查 .ae-cli/draft.json 是否存在，并读取现有配置：

配置项	draft.json 字段	处理方式
AE 项目 ID	meta.project_id	有值 → 确认；缺失 → 询问
AE 网站地址	meta.host	有值 → 确认；缺失 → 询问
SERVER_URL	meta.server_url	有值 → 确认；缺失 → 尝试从项目配置中查找，然后在无法获取时询问
APP_ID	meta.app_id	有值 → 确认；缺失 → 尝试从可访问的项目列表中查找，然后在无法获取时询问
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：属于单平台（向后兼容）
• 示例：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 → 使用 draft 中的值
• 用户输入新值 → 更新 draft.json 并使用新值

必需配置（必须解析并确认每一项）

⚠️ 关键：SERVER_URL 和 APP_ID 是相互独立的配置项。即使 draft.json 中有 project_id 和 host，也必须解析并确认这两项。project_id ≠ APP_ID，host ≠ SERVER_URL。

1. APP_ID — 提问前优先自动查询：
   • 如果已知 meta.project_id，针对当前 host 运行一次 ae-cli project info list。
   • 找到 projectId 与 meta.project_id 相匹配的项目。
   • 如果匹配的项目有 appId，询问："我找到了项目 <projectId> 对应的 APP_ID <appId>。使用它吗？是 / 输入新值"
   • 如果项目不存在、匹配结果不明确或没有 appId，请用户从 AE Admin → "Project Settings" → "Integration Config" 复制 APP_ID。
2. SERVER_URL — 数据接入端点（不同于网页 URL；前往 AE Admin → "Project Settings" → "Integration Config" → 填写 "Public URL"）
   • 如果已知 meta.project_id，可以尝试运行一次 ae-cli project info get --project-id <project_id>。
   • 仅当响应明确包含接收器 URL 字段（例如 serverUrl、pushUrl、push_url、receiverUrl、publicUrl、publicReceiverAddress、privateReceiverAddress，或等效的数据接入端点字段）时，才使用返回值。
   • 如果同时存在 publicReceiverAddress 和 privateReceiverAddress，则生成代码片段时优先将 publicReceiverAddress 用作 SERVER_URL，除非用户明确需要内部／私有网络接收器。
   • 如果找到了值，询问："我找到了项目 <projectId> 对应的 SERVER_URL <url>。使用它吗？是 / 输入新值"
   • ⚠️ 只有之前填写过时才会显示 "Public URL"；如果为空，则不会显示此字段。
   • 解决方法：向运维人员询问 URL，或跳过此步骤（在代码中使用 SERVER_URL 或 PUSH_URL 占位符）。

host 处理（可选）：

• 如果需要从 AE 获取方案（没有本地 draft.json），则询问 host。
• 如果存在本地 draft.json，则代码生成不需要 host。
• Debug 验证前，运行 ae-cli config current 并确认当前 host 与目标 AE 环境匹配；如果不匹配，运行 ae-cli config set-host <AE_HOST>。
• 默认使用 ae-cli tracking debug-device 和 ae-cli tracking debug-data 完成 Debug 验证；只有在这些 CLI 功能不可用时，才提示用户打开 AE Debug 页面。

仅存在 xlsx 文件时（没有 draft.json）

首先，检查 .ae-cli/draft.json 和 .ae-cli/draft.xlsx 是否都存在：

如果两者都不存在 — 当前环境尚未生成埋点方案。提醒用户有两种选择：

1. 是否需要先生成埋点方案？

   • 是 → 建议使用 ae-generate-tracking-plan 技能。
   • 参考：使用用户提供的埋点方案文档作为源材料。

2. 如果已有埋点方案

   • 提供 xlsx 文件路径，并使用 ae-cli tracking code import-template --template 导入。
   • 或将 xlsx 文件放到 .ae-cli/draft.xlsx，然后重新运行。

如果 xlsx 文件存在（通过 ae-cli tracking code import-template --template 提供或放置在 .ae-cli/draft.xlsx 中）：

步骤 1：解析 xlsx 文件

ae-cli tracking code import-template --template <xlsx-path> --out .ae-cli/draft.json

此命令：

1. 从 xlsx 中读取事件、事件属性、公共属性和用户属性。
2. 根据事件的 platform 字段推断 sdk_integration_mode。
3. 输出 draft.json（meta 部分仅包含 events 和 plan_name）。

步骤 2：从 xlsx 中可以推断的内容

字段	能否推断？	说明
事件列表	✅	来自 #event data 工作表
事件属性池	✅	来自 #event data 工作表
超级属性	✅	来自 #super property 工作表
用户属性	✅	来自 #user data 工作表
sdk_integration_mode	⚠️ 有限	可根据 xlsx 的“Platform”列推断（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"

内部表示：ae-cli tracking code import-template --template 会将 xlsx 的“Platform”列值解析为内部 platform 字段值：

• client → 客户端采集
• server → 服务端采集
• both → 两端采集

代码生成期间的平台筛选：

• 客户端代码：仅生成 platform === "client" 或 platform === "both" 的事件
• 服务端代码：仅生成 platform === "server" 或 platform === "both" 的事件
• 如果 xlsx 没有平台列：为客户端和服务端生成所有事件（向后兼容）

第 3 步：询问缺失的配置

按顺序逐项询问，每条消息只问一项：

1. SDK 集成模式：询问 “数据将通过客户端还是服务端上报？client / server / both”

2. 客户端平台（仅当 sdk_integration_mode 包含 client 时）： 询问 “你的应用使用哪些平台？”

   • Android / Android SDK
   • iOS / iOS SDK
   • OpenHarmony / OpenHarmony SDK（仅限中国用户）
   • Web / H5（JavaScript SDK）
   • 微信小程序（Mini-program SDK）（仅限中国用户）
   • 微信小游戏（Mini-game SDK）（仅限中国用户）
   • Unity 游戏（Unity SDK）
   • Cocos 游戏（CocosCreator / Cocos2d-x / Cocos2d-Lua / LayaAir — Cocos2d-Lua 和 LayaAir 仅限中国用户）
   • React Native / Flutter / uni-app
   • 其他

   → 用户选择后，仅当选择 Android 或 iOS 时，继续询问：

   • Android → 询问 “使用哪种编程语言？Java / Kotlin / both”
   • iOS → 询问 “使用哪种编程语言？Objective-C / Swift / both”

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. APP_ID / SERVER_URL：使用上述优先查询流程解析，并向用户确认找到的值；仅对无法找到或被用户拒绝的值进行询问。

第 4 步：合并配置并继续执行第 1 阶段

将收集到的信息写入 .ae-cli/draft.json 的 meta 部分，然后继续执行第 1 阶段。

---

如果没有本地计划文件

如果没有 .ae-cli/draft.json 或 .ae-cli/remote-plan.json：

1. AE projectId — 从 AE Admin 获取

2. AE Web 地址 — 获取计划所需

3. 运行 ae-cli tracking plan fetch 以获取埋点计划

   后续规则（根据集成模式确定需要为哪些平台生成代码）：

   集成模式	要生成代码的平台/端
   client_only	1 个客户端平台（从计划的 client_sdk_type 中读取，或询问）
   server_only	1 种服务端语言（从计划的 server_language 中读取，或询问）
   both	客户端平台 + 服务端语言（两者都需要）

平台定义

客户端平台（对应客户端 SDK）：

计划字段	平台	SDK
android	Android	Android SDK
ios	iOS	iOS SDK
openharmony	OpenHarmony	OpenHarmony SDK
javascript	Web / H5	JavaScript SDK
miniprogram	小程序	Mini-program SDK
unity	Unity	Unity SDK
game_engine	游戏引擎	Cocos / Laya / Unreal

服务端语言（对应服务端 SDK）：

计划字段	语言	SDK
java	Java	Java SDK
python	Python	Python SDK
go	Go	Go SDK
nodejs	Node.js	Node SDK
php	PHP	PHP SDK
csharp	C#	C# SDK

SDK 文档路径：

• 不要使用本节中的硬编码 wiki 路径。
• 始终先读取 references/sdk-index.md，并使用其中列出的所选 SDK 路径。
• 如果 references/sdk-index.md 中的路径在本地 wiki 镜像中不存在，请使用针对 SDK 的关键词在 ~/.ae-cli/wiki/raw/ 下搜索，并使用最匹配的最新主文档。

---

输出模式定义

每个平台都可以选择以下两种输出模式之一：

模式	描述	参数	交付内容
insert	直接将代码注入用户项目	需要项目路径（绝对路径）	将代码写入目标目录
snippet	输出 Markdown 并生成代码文件	无需路径	.ae-cli/output/<platform>-sdk.<ext>

服务端默认项（始终为服务端生成）：

• LoggerConsumer 代码（insert 或 snippet，与用户选择的模式一致）
• LogBus2 配置文件（.ae-cli/output/daemon.json）
• 官方文档链接：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

独立选项：

• debug — 验证脚本（生成测试上传代码）

---

阶段 1 — 加载计划

ae-cli auth login --host <host>
ae-cli auth status
ae-cli tracking plan fetch --project <projectId> --host <host> > .ae-cli/remote-plan.json

失败时的回退方案：

• AE 无法访问 → 询问用户是否要使用 .ae-cli/draft.json（本地已有计划）
• 两者都不可用 → 中止，并建议先运行 ae-generate-tracking-plan

读取 SDK 集成配置： 从计划文件中读取：

• meta.sdk_integration_mode — SDK 集成模式
• meta.client_sdk_type — 客户端 SDK 类型（如果为 client_only 或 both）
• meta.server_language — 服务端语言（如果为 server_only 或 both）
• meta.user_identity — 用户身份配置（用于生成 login() / identify() 调用）
• user_properties — 用户属性池（每个条目的 name + update_type，用于生成 user_set / user_setOnce / user_add 调用）

确定要生成代码的平台列表：

platforms = {
  client: [client_sdk_type]  // e.g. ['android'] or ['javascript']
  server: [server_language]  // e.g. ['java'] or ['python']
}

---

阶段 2 — 路由模式（选择输出模式）

2.1 显示平台列表

根据阶段 1 的配置，显示需要生成代码的平台：

Platforms requiring code generation:

Client:
- android (Android SDK)

Server:
- java (Java SDK, default LoggerConsumer + LogBus2)

2.2 快捷选项

提供快捷方式以简化交互：

选项 1：一键生成（推荐）

• 所有平台都使用 snippet 模式
• 一次性将所有代码文件生成到 .ae-cli/output/
• 无需项目路径 — 直接提供可复制的代码
• 最适合快速获取代码参考并手动集成

选项 2：插入项目

• 每个平台分别选择 insert 或 snippet
• 需要项目路径 — 代码会直接写入项目目录
• 最适合需要将代码放到指定位置的现有项目

2.3 按平台选择流程

如果用户选择“按平台选择”，则按平台顺序询问：

客户端平台提示词：

Client android — choose output mode:
1. insert — requires project path
2. snippet — no path needed, generates code file

Your choice: insert / snippet

• insert → 询问 “项目路径是什么？（绝对路径）”
• snippet → 无需额外参数

服务端语言提示词：

Server java — choose output mode:
1. insert — requires project path
2. snippet — no path needed, generates code file

Your choice: insert / snippet

(Defaults included: LoggerConsumer + LogBus2 config + official docs link)

• insert → 询问 “项目路径是什么？（绝对路径）”
• snippet → 无需额外参数
• 无论模式如何，服务端始终会生成 .ae-cli/output/daemon.json
• 始终提供 LogBus2 官方文档链接：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

2.4 独立选项

完成平台选择后，询问：

“生成调试验证脚本？是 / 否”

• yes → 生成 .ae-cli/output/te-debug.<ext>
• no → 跳过

2.5 选择摘要

显示最终选择摘要：

Output mode summary:

Client android: snippet
  Deliverables: .ae-cli/output/android-sdk.java

Server java: snippet
  Deliverables: .ae-cli/output/java-sdk.java
                .ae-cli/output/daemon.json

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone option: debug
  Deliverable: te-debug.java

Confirm? yes / no

---

阶段 3 — 执行（按平台）

3.1 执行前检查

阶段 3 开始前，检查：

test -z "$(git status --porcelain)" || echo "uncommitted changes present"

处理规则：

• snippet / debug → 无需检查（不会修改用户代码）
• 选择 insert → 检查 git 状态
  • git 工作区干净 → 继续
  • git 工作区有未提交更改 → 暂停，等待用户选择：

    检测到未提交的更改。插入模式要求 git 工作区干净。
    
    请选择：
    1. 先提交 / 暂存，然后告诉我，我会继续插入
    2. 切换到代码片段模式（稍后重新运行 skill 以使用插入模式）
    

    • 用户选择 1 → 用户完成提交 / 暂存后，重新执行阶段 3.1 检查，然后继续插入
    • 用户选择 2 → 本次运行中，所有 insert 模式都切换为 snippet

3.2 平台分发与执行

事件平台筛选规则（重要）：

• xlsx“平台”列的值映射到 platform 字段：
  • 客户端 / client → platform: "client"
  • 服务端 / server → platform: "server"
  • 客户端,服务端 / client,server → platform: "both"
• 客户端代码：仅生成 platform === "client" 或 platform === "both" 的事件
• 服务端代码：仅生成 platform === "server" 或 platform === "both" 的事件
• 如果 xlsx 没有平台列（旧版计划）：生成所有事件（向后兼容）
• platform === undefined（xlsx 缺少该列）→ 为客户端和服务端都生成

客户端代码生成：

输出模式	执行流程
insert	读取 references/client-sdk-insert.md → 探查项目 → 制定插入计划 → 编辑并写入
snippet	读取 references/snippet-delivery.md → 输出 markdown + 生成 .ae-cli/output/<platform>-sdk.<ext>

仅生成 platform === "client" 或 platform === "both" 的事件

⚠️ 硬性规则：切勿猜测 SDK 导入语句

• 生成前，必须读取 references/sdk-index.md，找到对应的 SDK wiki 主文档，确认路径存在，然后读取该主文档
• 必须从 wiki 主文档复制导入语句和包名，切勿猜测
• 示例：JavaScript SDK 的 npm 包为 thinkingdata-browser，导入变量为 ta
• 如果生成的代码与 wiki 文档不符（例如 TDAnalytics / te / @thinkingdata/web-sdk），请重新读取 wiki 并修正
• 每次生成代码前都要重新读取文档，切勿依赖“记住”的代码

---

服务端代码生成：

输出模式	执行流程
insert	读取 references/server-sdk-insert.md → 探查项目 → 制定插入计划 → 编辑并写入
snippet	读取 references/snippet-delivery.md → 输出 markdown + 生成 .ae-cli/output/<language>-sdk.<ext>

仅生成 platform === "server" 或 platform === "both" 的事件

服务端默认项（始终包含）：

• 生成 LoggerConsumer 模式代码（写入本地日志文件）
• 生成 .ae-cli/output/daemon.json（LogBus2 配置）
• 始终提供 LogBus2 官方文档链接：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

⚠️ 硬性规则：切勿猜测 SDK 导入语句

• 生成前，必须读取 references/sdk-index.md，找到对应的 SDK wiki 主文档，确认路径存在，然后读取该主文档
• 必须从 wiki 主文档复制导入语句和包名，切勿猜测
• 每次生成代码前都要重新读取文档，切勿依赖“记住”的代码

---

独立选项执行：

选项	执行流程
debug	读取 references/debug-script.md → 生成 .ae-cli/output/te-debug.<ext>

---

阶段 4 — 交付（输出清单）

根据所选输出模式显示交付内容：

附件上传

生成所有 .ae-cli/output/ 文件后，将每个生成的输出文件上传到 Agent 附件库，方便用户从文件／附件管理入口下载。

使用现有附件命令：

ae-cli agent +add-attachment --files '<json-array-of-generated-output-files>'

上传列表规则：

• 包含 .ae-cli/output/ 下生成的所有代码片段文件。
• 包含生成的服务配置文件，例如 .ae-cli/output/daemon.json 和 LogBus README 文件。
• 包含 .ae-cli/output/README.md。
• 如果用户选择了调试选项，则包含生成的调试脚本。
• 不要上传直接插入用户项目中的文件；只上传生成的输出产物。

附件上传兼容性

Agent 附件后端仅支持有限的文档 MIME 类型。.java、.kt、.swift、.m、.ets、.cs、.py、.go、.ts、.js、.php 和 .json 等代码／配置产物如果直接上传，可能会被拒绝。

运行 ae-cli agent +add-attachment 前，按以下规则准备上传列表：

• 在 .ae-cli/output/ 下保留每个原始生成文件，不做更改。
• 对于扩展名可能不受附件后端支持的每个生成文本产物，通过在文件名后追加 .txt 创建一个仅用于上传的副本。
  • 示例：.ae-cli/output/java-sdk.java → .ae-cli/output/java-sdk.java.txt
  • 示例：.ae-cli/output/daemon.json → .ae-cli/output/daemon.json.txt
• .txt 副本的内容必须与原始文件完全相同。不要用 Markdown 代码围栏包裹，不要添加标题，也不要有意更改换行符。
• 上传 .txt 兼容副本，而不是不受支持的原始文件。
• 将 .md、.txt 和 .csv 产物原样保留在上传列表中。
• 在最终回复中，先列出原始交付文件路径，再说明仅用于附件上传的 .txt 兼容副本。

如果上传成功，在最终回复中包含附件上传结果，并告知用户可从文件／附件管理入口获取文件。如果因 Agent 附件凭据不可用而导致上传失败，则保留 .ae-cli/output/ 中的本地文件，并告知用户上传未完成。

所有代码片段

Deliverables:

Client:
- .ae-cli/output/android-sdk.java (Android SDK code snippet)

Server:
- .ae-cli/output/java-sdk.java (Java SDK LoggerConsumer code)
- .ae-cli/output/daemon.json (LogBus2 configuration)

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone:
- .ae-cli/output/te-debug.java (validation script)

README: .ae-cli/output/README.md (usage instructions)

Attachment upload: uploaded generated output files to the file/attachment management entry

混合模式（部分插入，部分代码片段）

Deliverables:

Client android (insert):
- <project-path>/src/main/java/.../TrackingHelper.java (SDK init + event calls)

Server java (snippet):
- .ae-cli/output/java-sdk.java (LoggerConsumer code snippet)
- .ae-cli/output/daemon.json (LogBus2 configuration)

LogBus2 official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone:
- .ae-cli/output/te-debug.java (validation script)

Attachment upload: uploaded generated output files to the file/attachment management entry

Markdown 代码片段展示

对于所有 snippet 选择，在 Markdown 回复中按平台分组展示代码：

## Client Android

### SDK Initialization
```java
TDAnalytics.init(this, SERVER_URL, APPID);

Super Properties

Map<String, Object> superProperties = new HashMap<>();
superProperties.put("channel", "app_store");
TDAnalytics.setSuperProperties(superProperties);

事件组：auth

user_login

TDAnalytics.track("user_login", new HashMap<String, Object>() {{
    put("login_method", "phone");
}});

...

---

## Phase 5 — Validate hint

Provide validation guidance based on selected platforms:

### Validation Steps

验证步骤：

1. 确认当前 AE 环境： ae-cli config current

2. 列出现有的 Debug 设备： ae-cli tracking debug-device list --project-id <project_id>

3. 如果脚本的稳定设备 ID 不存在，则创建该 ID，然后选中它： ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>

4. 运行验证脚本：

   • 客户端：运行 .ae-cli/output/te-debug-client.
   • 服务端：运行 .ae-cli/output/te-debug-server.

5. 查询最近一小时的 Debug 数据： ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>

6. 确认 has_data=true，然后检查事件名称、属性结构和错误字段。 如有需要，添加 --event-name <event_name> 或 --start-time "YYYY-MM-DD HH:mm:ss"。

7. 仅当 CLI 功能不可用时，打开 AE Debug 页面： https:///#/data/debug

8. 对于 LogBus2：

   • 将 daemon.json 复制到 LogBus2 conf/ 目录
   • 启动：./logbus start
   • 官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

### After validation passes

- Remind user to commit changes (if any `insert` was used)
- Remind user to call `login()` / `identify()` (associate user IDs) and `user_set` / `user_setOnce` / `user_add` (set user properties) at the right business moments
- Remind user to copy daemon.json to LogBus2 conf/ directory

### Validation failure

- Ask user to paste error text for debugging
- Check SERVER_URL / appId correctness
- Check network connectivity
- Check LogBus2 config file format

---

## Prohibitions

- **Any `insert` without running `git status` check first (IMPORTANT: must check first; refuse execution if uncommitted changes exist)**
- Skipping reference docs in Phase 3 and inserting code arbitrarily
- Ignoring `// @tracking <event>` comment incremental detection
- Reusing web host as SERVER_URL (must be separate)
- **Using LogBus v1 (deprecated — only use LogBus2)**
- Generating LogBus2 config without providing official documentation link
- Including `platform === "server"` exclusive events in client code
- Including `platform === "client"` exclusive events in server code (unless `platform === "both"`)
- **Skipping SDK main doc read and guessing integration method** — each SDK has different integration approaches; must read wiki main doc's "Integrate SDK" section first, and choose the correct method based on project characteristics (with/without build tools)
- **Translating "Super Property" as "超级属性" in any user-facing output (code comments, interaction prompts, markdown) — the correct AE Chinese term is "公共事件属性" or "公共属性"**
- **Entering Phase 1 before Phase 0.5 is complete** — SDK integration must be confirmed before inserting code, otherwise generated track() calls won't work

---

## Internal Reference

All output mode rules are in `references/*.md`. This SKILL.md only handles phase orchestration.

**SDK document index**:
- `references/sdk-index.md` — All SDK wiki document path index (canonical source)

**Output mode references**:
- `references/client-sdk-insert.md` — Client code insertion workflow
- `references/snippet-delivery.md` — Code snippet generation workflow
- `references/server-sdk-insert.md` — Server code insertion workflow (LoggerConsumer + LogBus2)
- `references/logbus-config.md` — LogBus2 configuration generation (includes official docs link)
- `references/debug-script.md` — Validation script generation

**LogBus2 official documentation** (must provide when generating config):
- User guide: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
- Download link is in the official doc's "二、Download LogBus2" section

**Wiki directory structure** (see `~/.ae-cli/wiki/schema.md`):
- `~/.ae-cli/wiki/raw/` — AE official documentation mirror (read-only, maintained by crawler)
- `~/.ae-cli/wiki/synthesis/` — LLM-synthesized overview documents

**Document reading order during code generation**:
1. Read `references/sdk-index.md` to find the selected SDK's main document and advanced guide paths.
2. Verify the main document path exists in the local wiki mirror before reading it.
3. If the indexed path is missing, search under `~/.ae-cli/wiki/raw/` with SDK-specific keywords such as SDK name, platform name, language name, and `main doc`; choose the latest main document, not historical/versioned documents.
4. Read the wiki main doc first (initialization, imports, package names, basic API).
5. Read the advanced guide only after the main doc (LoggerConsumer, user properties, auto-track, preset properties, etc.).
6. Check advanced guide sub-documents if needed.