ae-generate-tracking-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ae-generate-tracking-code

Conversation language: This skill document is in English, but all output to the user MUST be in the user's input language. English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply. If uncertain, default to English. This applies to all output: section titles, phase names, template prompts, code comments, etc. ⚠️ CRITICAL: Many reference documents (wiki SDK docs, code examples) contain Chinese text. When reading Chinese source material to answer an English/Japanese user, you MUST translate headings, descriptions, and comments to the user's language. The source document's language is NOT the user's language. Use the Terminology Glossary above to map terms accurately. Do NOT copy Chinese text verbatim from this document into English/Japanese replies.
Document link language: When providing official documentation URLs, use
lan=zh-CN
for Chinese users,
lan=en-US
for all others.

对话语言：本技能文档为英文，但所有输出给用户的内容必须使用用户输入的语言。英文输入→英文回复；中文输入→中文回复；日文输入→日文回复。若不确定，默认使用英文。此规则适用于所有输出内容：章节标题、阶段名称、模板提示、代码注释等。 ⚠️ 重要提示：许多参考文档（wiki SDK文档、代码示例）包含中文文本。当阅读中文源文档来回复英文/日文用户时，必须将标题、描述和注释翻译成用户使用的语言。源文档的语言并非用户的语言，请使用上方的术语对照表准确映射术语。请勿直接将本文档中的中文文本复制到英文/日文回复中。
文档链接语言：提供官方文档URL时，中文用户使用
lan=zh-CN
，其他用户使用
lan=en-US
。

Terminology Glossary

术语对照表

中文	English	Notes
埋点方案	Tracking Plan	AE project-level event/property definitions
代码埋点	Tracking Code Generation	Generating SDK/LogBus code from a plan
埋点代码	Tracking Code	The generated SDK init + track() calls + helpers
输出方式	Output Mode	insert (inject) or snippet (file delivery)
插入	Insert	Direct code injection into the user's project
片段 / 代码片段	Snippet	Code delivered as files under `.ae-cli/output/`
采集端	Collection Platform / Platform	Where events are sent from: client, server, or both
客户端	Client	Client-side SDK (Android/iOS/Web/etc.)
服务端	Server	Server-side SDK (Java/Python/Go/etc.)
两端都采集	Both	Events collected from both client and server
SDK 集成模式	SDK Integration Mode	`client_only` / `server_only` / `both`
用户体系	User Identity System	distinct_id / account_id strategy
校验脚本	Validation / Debug Script	Test code to verify tracking works
LogBus2 配置	LogBus2 Configuration	`daemon.json` for LogBus2 log sync tool
LoggerConsumer	LoggerConsumer	Server SDK consumer that writes events to local log files
BatchConsumer	BatchConsumer	Server SDK consumer that uploads events in batches
公共属性	Super Property	Properties attached to all events automatically. ⚠️ The correct Chinese AE term is "公共属性" or "公共事件属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term.
预置属性	Preset Property	System properties prefixed with `#` (e.g. `#device_id` , `#time` )
事件属性	Event Property	Custom properties on specific events
用户属性	User Property	Properties set on the user profile
上报地址	SERVER_URL	Data ingestion endpoint (different from web URL!)
APP_ID	APP_ID	Application ID from AE Admin → "Integration Config"
project_id	Project ID	AE project identifier (≠ APP_ID)
自动采集	Auto-track	Auto-collected events (app install, start, view, click)
埋点方案上传	Plan Upload	Upload tracking plan xlsx to AE

中文	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消费者
BatchConsumer	BatchConsumer	批量上传事件的服务端SDK消费者
公共属性	Super Property	自动附加到所有事件的属性。⚠️ AE官方正确中文术语为「公共属性」或「公共事件属性」，切勿将"Super Property"翻译为「超级属性」——这并非AE的有效术语。
预置属性	Preset Property	以 `#` 开头的系统属性（如 `#device_id` 、 `#time` ）
事件属性	Event Property	特定事件的自定义属性
用户属性	User Property	用户画像上设置的属性
上报地址	SERVER_URL	数据接入端点（与网页URL不同！）
APP_ID	APP_ID	从AE管理后台→「集成配置」获取的应用ID
project_id	Project ID	AE项目标识符（≠ APP_ID）
自动采集	Auto-track	自动采集的事件（应用安装、启动、页面浏览、点击）
埋点方案上传	Plan Upload	将跟踪计划xlsx文件上传至AE

When to Trigger

触发时机

Trigger when user says: "generate tracking code / help me add web tracking / generate logbus config / server-side reporting code" etc. Supports multiple platforms with independent output mode selection per platform.

当用户说出如下内容时触发："generate tracking code / help me add web tracking / generate logbus config / server-side reporting code"等。支持多平台，且每个平台可独立选择输出模式。

Phase 0 — Anchor (one question per message)

阶段0 — 锚点（每条消息一个问题）

Pre-check: Read existing configuration from draft.json

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

First, check if

.ae-cli/draft.json

exists and read existing configuration:

Config Item	draft.json Field	Handling
AE projectId	`meta.project_id`	Has value → confirm; missing → ask
AE web address	`meta.host`	Has value → confirm; missing → ask
SERVER_URL	`meta.server_url`	Has value → confirm; missing → try lookup from project config, then ask if unavailable
APP_ID	`meta.app_id`	Has value → confirm; missing → try lookup from accessible project list, then ask if unavailable
SDK integration mode	`meta.sdk_integration_mode`	Has value → use directly
Client SDK type	`meta.client_platforms` (preferred) or `meta.client_sdk_type`	Has value → use directly
Server language	`meta.server_language`	Has value → use directly
User identity system	`meta.user_identity`	Has value → use directly

Important:

project_id

≠

APP_ID

, and

host

≠

SERVER_URL

. Even if project_id and host are already set, SERVER_URL and APP_ID must still be resolved and confirmed separately. Prefer lookup first; ask the user only when lookup is unavailable or ambiguous.

Multi-platform support:

If
```
client_platforms
```
exists (array): multi-platform scenario — generate code for each platform
If only
```
client_sdk_type
```
exists: single platform (backward compatible)
Example:
```
client_platforms: ["android", "openharmony"]
```
→ generate code for Android + OpenHarmony

Language support:

Android SDK: supports Java / Kotlin (can generate both)
iOS SDK: supports Objective-C / Swift (can generate both)
Other SDKs: fixed language, no selection needed

Language configuration source:

Prefer

meta.client_platform_languages

(e.g.

{"android": ["java", "kotlin"]}

)

If not configured, ask user for Android/iOS platforms only

Confirmation flow:

Has value → ask "Confirm using draft.json config: <value>? yes / enter new value"
User says
```
yes
```
→ use draft value
User enters new value → update draft.json and use new value

首先检查

.ae-cli/draft.json

是否存在，并读取现有配置：

配置项	draft.json字段	处理方式
AE projectId	`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中的配置：<value>？是 / 输入新值"**
用户回复
```
yes
```
→使用draft中的值
用户输入新值→更新draft.json并使用新值

Required configuration (must resolve and confirm each item)

必填配置（必须逐一确认并获取）

⚠️ Key: SERVER_URL and APP_ID are independent config items. Even if draft.json has project_id and host, you MUST resolve and confirm them.
project_id
≠
APP_ID
,
host
≠
SERVER_URL
.

APP_ID — Prefer automatic lookup before asking:
- If
```
meta.project_id
```
  is known, run
```
ae-cli project info list
```
  once for the current host.
- Find the project whose
```
projectId
```
  matches
```
meta.project_id
```
  .
- If the matched project has
```
appId
```
  , ask: "I found APP_ID
  <appId>
  for project
  <projectId>
  . Use it? yes / enter new value"
- If the project is missing, ambiguous, or has no
```
appId
```
  , ask the user to copy APP_ID from AE Admin → "Project Settings" → "Integration Config".
SERVER_URL — Data ingestion endpoint (different from web URL; go to AE Admin → "Project Settings" → "Integration Config" → fill in "Public URL")
- If
```
meta.project_id
```
  is known, you may try
```
ae-cli project info get --project-id <project_id>
```
  once.
- Use the returned value only if the response explicitly contains a receiver URL field such as
```
serverUrl
```
  ,
```
pushUrl
```
  ,
```
push_url
```
  ,
```
receiverUrl
```
  ,
```
publicUrl
```
  ,
```
publicReceiverAddress
```
  ,
```
privateReceiverAddress
```
  , or equivalent ingestion endpoint field.
- If both
```
publicReceiverAddress
```
  and
```
privateReceiverAddress
```
  are present, prefer
```
publicReceiverAddress
```
  as
```
SERVER_URL
```
  for generated snippets unless the user explicitly needs an internal/private-network receiver.
- If a value is found, ask: "I found SERVER_URL
  <url>
  for project
  <projectId>
  . Use it? yes / enter new value"
- ⚠️ "Public URL" only shows if previously filled in; if empty, this field won't display
- Solution: ask ops for the URL, or skip this step (use
```
SERVER_URL
```
  or
```
PUSH_URL
```
  placeholder in code)

host handling (optional):

If you need to fetch plan from AE (no local draft.json) → ask for host
If local draft.json exists → host is not required for code generation
Before Debug validation, run
```
ae-cli config current
```
and confirm the active host matches the target AE environment; if it does not, run
```
ae-cli config set-host <AE_HOST>
```
Complete Debug validation with
```
ae-cli tracking debug-device
```
and
```
ae-cli tracking debug-data
```
by default; only hint the user to open the AE Debug page when those CLI capabilities are unavailable

⚠️ 关键：SERVER_URL和APP_ID是独立配置项。即使draft.json中有project_id和host，仍必须确认并获取这两项。
project_id
≠
APP_ID
，
host
≠
SERVER_URL
。

APP_ID — 优先自动查找，再询问用户：
- 若已知
```
meta.project_id
```
  ，针对当前host执行一次
```
ae-cli project info list
```
  命令。
- 找到
```
projectId
```
  与
```
meta.project_id
```
  匹配的项目。
- 若匹配项目有
```
appId
```
  ，询问："我找到项目
  <projectId>
  对应的APP_ID为
  <appId>
  。是否使用该值？是 / 输入新值"
- 若项目缺失、结果不明确或无
```
appId
```
  ，请用户从AE管理后台→「项目设置」→「集成配置」中复制APP_ID。
SERVER_URL — 数据接入端点（与网页URL不同；前往AE管理后台→「项目设置」→「集成配置」→填写「公网地址」）
- 若已知
```
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>
  。是否使用该值？是 / 输入新值"
- ⚠️「公网地址」仅在已填写时显示；若为空，该字段不会展示
- 解决方案：询问运维人员获取URL，或跳过此步骤（代码中使用
```
SERVER_URL
```
  或
```
PUSH_URL
```
  占位符）

host处理（可选）：

若需要从AE获取方案（无本地draft.json）→询问host
若存在本地draft.json→代码生成无需host
在调试验证前，执行
```
ae-cli config current
```
并确认当前host与目标AE环境匹配；若不匹配，执行
```
ae-cli config set-host <AE_HOST>
```
默认使用
```
ae-cli tracking debug-device
```
和
```
ae-cli tracking debug-data
```
完成调试验证；仅当CLI功能不可用时，提示用户打开AE调试页面

If only xlsx file exists (no draft.json)

仅存在xlsx文件（无draft.json）

First, check if both

.ae-cli/draft.json

and

.ae-cli/draft.xlsx

exist:

If both are missing — the current environment hasn't generated a tracking plan yet. Remind user of two options:

Do you need to generate a tracking plan first?
- Yes → suggest using
```
ae-generate-tracking-plan
```
  skill
- Reference: tracking plan document (Feishu: https://www.feishu.cn/docx/Jt0VdhNB6oSJ4TxISs1cq2Ebnmg)
If you already have a tracking plan
- Provide the xlsx file path and use
```
ae-cli tracking code import-template --template
```
  to import
- Or place the xlsx file at
```
.ae-cli/draft.xlsx
```
  and re-run

If xlsx file exists (provided via

ae-cli tracking code import-template --template

or placed at

.ae-cli/draft.xlsx

Step 1: Parse the xlsx file

bash

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

This command:

Reads events, event properties, super properties, and user properties from xlsx
Infers
```
sdk_integration_mode
```
from the event
```
platform
```
field
Outputs draft.json (meta section has events and plan_name only)

Step 2: What can be inferred from xlsx

Field	Can Infer?	Notes
Event list	✅	From `#event data` sheet
Event property pool	✅	From `#event data` sheet
Super properties	✅	From `#super property` sheet
User properties	✅	From `#user data` sheet
sdk_integration_mode	⚠️ Limited	xlsx "Platform" column can infer (client/server/both); if missing, must ask
client_platforms	❌	Must ask user
client_platform_languages	❌	Must ask user (Android/iOS only)
server_language	❌	Must ask user (only if sdk_integration_mode includes server)
user_identity	❌	Must ask user
host / project_id	❌	Must ask or skip

"Platform" column parsing rules:

Empty / no column → cannot infer platform; default to client-side code generation (backward compatible)
```
客户端
```
/
```
client
```
→ client-only collection, parsed as
```
platform: "client"
```
```
服务端
```
/
```
server
```
→ server-only collection, parsed as
```
platform: "server"
```

客户端,服务端

client,server

服务端,客户端

server,client

→ both platforms, parsed as

platform: "both"

Internal representation: xlsx "Platform" column values are parsed by

ae-cli tracking code import-template --template

into internal

platform

field values:

```
client
```
→ client-side collection
```
server
```
→ server-side collection
```
both
```
→ both platforms

Platform filtering during code generation:

Client code: only generate events where
```
platform === "client"
```
or
```
platform === "both"
```
Server code: only generate events where
```
platform === "server"
```
or
```
platform === "both"
```
If xlsx has no platform column: generate all events for both client and server (backward compatible)

Step 3: Ask for missing configuration

Ask in order, one item per message:

SDK integration mode: ask "Will tracking be reported via client-side or server-side? client / server / both"
Client platform(s) (only if sdk_integration_mode includes client): ask "What platform(s) is your app?"
- Android / Android SDK
- iOS / iOS SDK
- OpenHarmony / OpenHarmony SDK (Chinese users only)
- Web / H5 (JavaScript SDK)
- WeChat Mini-program (Mini-program SDK) (Chinese users only)
- WeChat Mini-game (Mini-game SDK) (Chinese users only)
- Unity Game (Unity SDK)
- Cocos Game (CocosCreator / Cocos2d-x / Cocos2d-Lua / LayaAir — Cocos2d-Lua & LayaAir for Chinese users only)
- React Native / Flutter / uni-app
- Other
→ After user selects, only if Android or iOS is selected, follow up:
- Android → ask "Which programming language? Java / Kotlin / both"
- iOS → ask "Which programming language? Objective-C / Swift / both"
Server language (only if sdk_integration_mode includes server): ask "What is your server-side language?"
- Java
- Python
- Go
- Node.js
- PHP
- C# / .NET
- Other
User identity system:
- Account ID source: user_account / role_id / none
- Visitor ID strategy: auto / device_id / custom
APP_ID / SERVER_URL: resolve them with the lookup-first flow above, confirm any found values with the user, and ask only for values that cannot be found or are rejected by the user.

Step 4: Merge configuration and proceed to Phase 1

Write gathered info to

.ae-cli/draft.json

meta section, then proceed to Phase 1.

首先检查

.ae-cli/draft.json

和

.ae-cli/draft.xlsx

是否同时存在：

若两者均缺失 — 当前环境尚未生成跟踪计划。提醒用户有两种选择：

是否需要先生成跟踪计划？
- 是→建议使用
```
ae-generate-tracking-plan
```
  技能
- 参考文档：跟踪计划文档（飞书：https://www.feishu.cn/docx/Jt0VdhNB6oSJ4TxISs1cq2Ebnmg）
若已拥有跟踪计划
- 提供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文件

bash

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

该命令执行以下操作：

从xlsx中读取事件、事件属性、公共属性和用户属性
从事件的
```
platform
```
字段推断
```
sdk_integration_mode
```
输出draft.json（meta部分仅包含事件和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"

内部表示：xlsx的「Platform」列值通过

ae-cli tracking code import-template --template

命令解析为内部

platform

字段值：

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

代码生成时的平台过滤规则：

客户端代码：仅生成

platform === "client"

或

platform === "both"

的事件

服务端代码：仅生成

platform === "server"

或

platform === "both"

的事件

若xlsx无platform列：为客户端和服务端生成所有事件（向后兼容）

步骤3：询问缺失的配置

按顺序逐一询问，每条消息一个问题：

SDK集成模式：询问**"埋点将通过客户端还是服务端上报？client / server / both"**
客户端平台（仅当sdk_integration_mode包含client时）：询问**"你的应用是哪个/哪些平台？"**
- Android / Android SDK
- iOS / iOS SDK
- OpenHarmony / OpenHarmony SDK（仅中文用户）
- Web / H5（JavaScript SDK）
- 微信小程序（小程序SDK）（仅中文用户）
- 微信小游戏（小游戏SDK）（仅中文用户）
- Unity游戏（Unity SDK）
- Cocos游戏（CocosCreator / Cocos2d-x / Cocos2d-Lua / LayaAir — 仅中文用户支持Cocos2d-Lua & LayaAir）
- React Native / Flutter / uni-app
- 其他
→ 用户选择后，仅当选择Android或iOS时，继续询问：
- Android → 询问**"使用哪种编程语言？Java / Kotlin / 两者都要"**
- iOS → 询问**"使用哪种编程语言？Objective-C / Swift / 两者都要"**
服务端语言（仅当sdk_integration_mode包含server时）：询问**"你的服务端使用哪种语言？"**
- Java
- Python
- Go
- Node.js
- PHP
- C# / .NET
- 其他
用户身份体系：
- 账号ID来源：user_account / role_id / none
- 访客ID策略：auto / device_id / custom
APP_ID / SERVER_URL：按照上述优先查找的流程获取并确认，仅当无法找到或用户拒绝使用找到的值时，才询问用户。

步骤4：合并配置并进入阶段1

将收集到的信息写入

.ae-cli/draft.json

的meta部分，然后进入阶段1。

If no local plan file

无本地方案文件

Without

.ae-cli/draft.json

.ae-cli/remote-plan.json

AE projectId — get from AE Admin
AE web address — needed to fetch plan

Run

ae-cli tracking plan fetch

to retrieve the tracking plan

Follow-up rules (determine which platforms need code based on integration mode):

Integration Mode	Platforms/Sides to Generate
`client_only`	1 client platform (read from plan's `client_sdk_type` or ask)
`server_only`	1 server language (read from plan's `server_language` or ask)
`both`	Client platform + server language (both needed)

若没有

.ae-cli/draft.json

或

.ae-cli/remote-plan.json

：

AE projectId — 从AE管理后台获取
AE网页地址 — 获取方案所需

执行

ae-cli tracking plan fetch

命令获取跟踪计划

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

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

Platform Definitions

平台定义

Client platforms (corresponding to client SDKs):

plan field	Platform	SDK
`android`	Android	Android SDK
`ios`	iOS	iOS SDK
`openharmony`	OpenHarmony	OpenHarmony SDK
`javascript`	Web / H5	JavaScript SDK
`miniprogram`	Mini-program	Mini-program SDK
`unity`	Unity	Unity SDK
`game_engine`	Game Engine	Cocos / Laya / Unreal

Server languages (corresponding to server SDKs):

plan field	Language	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 document paths:

Do not use hard-coded wiki paths from this section.
Always read
```
references/sdk-index.md
```
first and use the path listed there for the selected SDK.
If the path from
```
references/sdk-index.md
```
does not exist in the local wiki mirror, search under
```
~/.ae-cli/wiki/raw/
```
with SDK-specific keywords and use the best matching latest main document.

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

方案字段	平台	SDK
`android`	Android	Android SDK
`ios`	iOS	iOS SDK
`openharmony`	OpenHarmony	OpenHarmony SDK
`javascript`	Web / H5	JavaScript SDK
`miniprogram`	小程序	小程序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镜像中不存在，请在
```
~/.ae-cli/wiki/raw/
```
下使用SDK特定关键词搜索，并选择最匹配的最新主文档。

Output Mode Definitions

输出模式定义

Each platform can choose between two output modes:

Mode	Description	Parameters	Deliverables
insert	Direct Edit injection into user project	Requires project path (absolute)	Code written to target directory
snippet	Markdown print + generate code file	No path needed	`.ae-cli/output/<platform>-sdk.<ext>`

Server-side defaults (always generated for server):

LoggerConsumer code (insert or snippet, matching user's choice)
LogBus2 config file (
```
.ae-cli/output/daemon.json
```
)
Official docs link: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

Standalone option:

```
debug
```
— validation script (generates test upload code)

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

模式	描述	参数	交付物
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
```
— 校验脚本（生成测试上传代码）

Phase 1 — Load plan

阶段1 — 加载方案

bash

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

Failure fallback:

AE unreachable → ask user if they want to use
```
.ae-cli/draft.json
```
(local existing plan)
Neither available → abort, suggest running
```
ae-generate-tracking-plan
```
first

Read SDK integration config: From the plan file, read:

```
meta.sdk_integration_mode
```
— SDK integration mode
```
meta.client_sdk_type
```
— client SDK type (if
```
client_only
```
or
```
both
```
)
```
meta.server_language
```
— server language (if
```
server_only
```
or
```
both
```
)
```
meta.user_identity
```
— user identity config (used to generate
```
login()
```
/
```
identify()
```
calls)

Determine list of platforms to generate code for:

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

bash

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()
```
调用）

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

platforms = {
  client: [client_sdk_type]  // 例如 ['android'] 或 ['javascript']
  server: [server_language]  // 例如 ['java'] 或 ['python']
}

Phase 2 — Route mode (select output mode)

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

2.1 Show platform list

2.1 展示平台列表

Based on Phase 1 config, display the platforms that need code:

Platforms requiring code generation:

Client:
- android (Android SDK)

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

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

需要生成代码的平台：

客户端：
- android（Android SDK）

服务端：
- java（Java SDK，默认LoggerConsumer + LogBus2架构）

2.2 Quick options

2.2 快捷选项

Provide shortcuts to simplify interaction:

Option 1: One-click generation (recommended)

All platforms use
```
snippet
```
mode
Generate all code files to
```
.ae-cli/output/
```
at once
No project path needed — delivers copy-ready code directly
Best for quickly getting code reference to integrate manually

Option 2: Insert into project

Each platform independently chooses
```
insert
```
or
```
snippet
```
Project path required — code is written directly to your project directory
Best for existing projects where code should land in specific locations

提供快捷方式简化交互：

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

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

选项2：插入到项目中

每个平台独立选择
```
insert
```
或
```
snippet
```
模式
需要项目路径 — 代码直接写入用户项目目录
最适合现有项目，代码需放置在特定位置的场景

2.3 Per-platform selection flow

2.3 按平台选择流程

If user chooses "per-platform selection", ask in platform order:

Client platform prompt:

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

Your choice: insert / snippet

```
insert
```
→ ask "What is the project path? (absolute path)"
```
snippet
```
→ no additional parameters

Server language prompt:

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
```
→ ask "What is the project path? (absolute path)"
```
snippet
```
→ no additional parameters
Server always gets
```
.ae-cli/output/daemon.json
```
regardless of mode
Always provide LogBus2 official docs link: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

若用户选择「按平台选择」，按平台顺序询问：

客户端平台提示：

客户端android — 选择输出模式：
1. insert — 需要项目路径
2. snippet — 无需路径，生成代码文件

你的选择：insert / snippet

```
insert
```
→ 询问**"项目路径是什么？（绝对路径）"**
```
snippet
```
→ 无需额外参数

服务端语言提示：

服务端java — 选择输出模式：
1. insert — 需要项目路径
2. snippet — 无需路径，生成代码文件

你的选择：insert / snippet

（默认包含：LoggerConsumer + LogBus2配置 + 官方文档链接）

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

2.4 Standalone option

2.4 独立选项

After platform selection is done, ask:

"Generate a debug validation script? yes / no"

```
yes
```
→ generate
```
.ae-cli/output/te-debug.<ext>
```
```
no
```
→ skip

平台选择完成后，询问：

"是否生成调试校验脚本？是 / 否"

```
是
```
→ 生成
```
.ae-cli/output/te-debug.<ext>
```
```
否
```
→ 跳过

2.5 Summary of selections

2.5 选择摘要

Show final selection summary:

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

展示最终选择的摘要：

输出模式摘要：

客户端android：snippet
  交付物：.ae-cli/output/android-sdk.java

服务端java：snippet
  交付物：.ae-cli/output/java-sdk.java
                .ae-cli/output/daemon.json

LogBus2官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

独立选项：debug
  交付物：te-debug.java

确认？是 / 否

Phase 3 — Execute (per platform)

阶段3 — 执行（按平台）

3.1 Pre-execution check

3.1 执行前检查

Before Phase 3 begins, check:

bash

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

Handling rules:

```
snippet
```
/
```
debug
```
→ no check needed (doesn't touch user code)

insert

selection → check git status

git clean → proceed

git dirty → pause, wait for user choice:

Uncommitted changes detected. Insert mode requires a clean git workspace.

Choose:
1. Commit / stash first, then tell me and I'll continue with insert
2. Switch to snippet mode for code snippets (re-run skill later for insert)

User chooses 1 → after user completes commit/stash, re-check Phase 3.1, then proceed with insert
User chooses 2 → all
```
insert
```
modes switch to
```
snippet
```
for this run

进入阶段3前，执行检查：

bash

test -z "$(git status --porcelain)" || echo "存在未提交的更改"

处理规则：

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

请选择：
1. 先提交/暂存更改，然后告知我，我将继续执行insert模式
2. 切换为snippet模式生成代码片段（之后可重新运行技能执行insert）
```
  - 用户选择1→用户完成提交/暂存后，重新执行阶段3.1的检查，然后继续执行insert模式
  - 用户选择2→本次运行中所有
```
insert
```
    模式切换为
```
snippet
```
    模式

3.2 Platform dispatch and execution

3.2 平台分发与执行

Event platform filtering rules (important):

xlsx "Platform" column values map to

platform

field:

```
客户端
```
/
```
client
```
→
```
platform: "client"
```
```
服务端
```
/
```
server
```
→
```
platform: "server"
```

客户端,服务端

client,server

→

platform: "both"

Client code: only generate events where
```
platform === "client"
```
or
```
platform === "both"
```
Server code: only generate events where
```
platform === "server"
```
or
```
platform === "both"
```
If xlsx has no platform column (legacy plan): generate all events (backward compatible)
```
platform === undefined
```
(xlsx lacks column) → generate for both sides

Client code generation:

Output Mode	Execution Flow
`insert`	Read `references/client-sdk-insert.md` → Explore project → Plan insertion → Edit to write
`snippet`	Read `references/snippet-delivery.md` → Print markdown + generate `.ae-cli/output/<platform>-sdk.<ext>`

Only generate events where
platform === "client"
or
platform === "both"

⚠️ Hard rule: Never guess SDK imports

Before generating, MUST read
```
references/sdk-index.md
```
, resolve the corresponding SDK wiki main document, verify the path exists, and then read that main document
MUST copy import statements and package names from the wiki main document, never guess
Example: JavaScript SDK npm package is
```
thinkingdata-browser
```
, import variable is
```
ta
```
If generated code doesn't match wiki docs (e.g.
```
TDAnalytics
```
/
```
te
```
/
```
@thinkingdata/web-sdk
```
), re-read wiki and fix
Re-read docs before every code generation, never rely on "remembered" code

Server code generation:

Output Mode	Execution Flow
`insert`	Read `references/server-sdk-insert.md` → Explore project → Plan insertion → Edit to write
`snippet`	Read `references/snippet-delivery.md` → Print markdown + generate `.ae-cli/output/<language>-sdk.<ext>`

Only generate events where
platform === "server"
or
platform === "both"

Server-side defaults (always included):

Generate LoggerConsumer mode code (writes to local log files)
Generate
```
.ae-cli/output/daemon.json
```
(LogBus2 configuration)
Always provide LogBus2 official docs link: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

⚠️ Hard rule: Never guess SDK imports

Before generating, MUST read
```
references/sdk-index.md
```
, resolve the corresponding SDK wiki main document, verify the path exists, and then read that main document
MUST copy import statements and package names from the wiki main document, never guess
Re-read docs before every code generation, never rely on "remembered" code

Standalone option execution:

Option	Execution Flow
`debug`	Read `references/debug-script.md` → Generate `.ae-cli/output/te-debug.<ext>`

事件平台过滤规则（重要）：

xlsx的「Platform」列值映射为

platform

字段：

```
客户端
```
/
```
client
```
→
```
platform: "client"
```
```
服务端
```
/
```
server
```
→
```
platform: "server"
```

客户端,服务端

client,server

→

platform: "both"

客户端代码：仅生成

platform === "client"

或

platform === "both"

的事件

服务端代码：仅生成

platform === "server"

或

platform === "both"

的事件

若xlsx无platform列（旧版方案）：生成所有事件（向后兼容）
```
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>`

Phase 4 — Deliver (output manifest)

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

Show deliverables based on selected output modes:

根据所选输出模式展示交付物：

Attachment upload

附件上传

After all

.ae-cli/output/

files are generated, upload every generated output file to the Agent attachment library so the user can download them from the file/attachment management entry.

Use the existing attachment command:

bash

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

Upload list rules:

Include all generated snippet files under
```
.ae-cli/output/
```
.
Include generated server config files such as
```
.ae-cli/output/daemon.json
```
and LogBus README files.
Include
```
.ae-cli/output/README.md
```
.
Include generated debug scripts if the user selected the debug option.
Do not upload files inserted directly into the user's project; only upload generated output artifacts.

所有

.ae-cli/output/

下的文件生成完成后，将每个生成的输出文件上传至Agent附件库，以便用户从文件/附件管理入口下载。

使用现有附件命令：

bash

ae-cli agent +add-attachment --files '<生成输出文件的JSON数组>'

上传列表规则：

包含
```
.ae-cli/output/
```
下所有生成的代码片段文件。
包含生成的服务端配置文件，如
```
.ae-cli/output/daemon.json
```
和LogBus README文件。
包含
```
.ae-cli/output/README.md
```
。
若用户选择了debug选项，包含生成的调试脚本。
请勿上传直接插入到用户项目中的文件；仅上传生成的输出产物。

Attachment upload compatibility

附件上传兼容性

The Agent attachment backend accepts a limited document MIME set. Code/config artifacts such as

.java

.kt

.swift

.m

.ets

.cs

.py

.go

.ts

.js

.php

, and

.json

may be rejected if uploaded directly.

Before running

ae-cli agent +add-attachment

, prepare the upload list as follows:

Keep every original generated file unchanged under
```
.ae-cli/output/
```
.
For each generated text artifact whose extension may be unsupported by the attachment backend, create an upload-only sibling copy by appending
```
.txt
```
to the filename.
- Example:
```
.ae-cli/output/java-sdk.java
```
  →
```
.ae-cli/output/java-sdk.java.txt
```
- Example:
```
.ae-cli/output/daemon.json
```
  →
```
.ae-cli/output/daemon.json.txt
```
The
```
.txt
```
copy must have identical content to the original file. Do not wrap it in markdown fences, do not add headers, and do not change line endings intentionally.
Upload the
```
.txt
```
compatibility copies instead of the unsupported originals.
Keep
```
.md
```
,
```
.txt
```
, and
```
.csv
```
artifacts in the upload list as-is.
In the final response, list the original deliverable paths first, then mention any
```
.txt
```
compatibility copies used only for attachment upload.

If upload succeeds, include the attachment upload result in the final response and tell the user the files are available from the file/attachment management entry. If upload fails because Agent attachment credentials are unavailable, keep the local

.ae-cli/output/

files and tell the user the upload did not complete.

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/

下的文件，并告知用户上传未完成。

All snippets

全snippet模式

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

交付物：

客户端：
- .ae-cli/output/android-sdk.java（Android SDK代码片段）

服务端：
- .ae-cli/output/java-sdk.java（Java SDK LoggerConsumer代码）
- .ae-cli/output/daemon.json（LogBus2配置）

LogBus2官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

独立选项：
- .ae-cli/output/te-debug.java（校验脚本）

README：.ae-cli/output/README.md（使用说明）

附件上传：已将生成的输出文件上传至文件/附件管理入口

Mixed (some insert + some snippet)

混合模式（部分insert + 部分snippet）

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

交付物：

客户端android（insert）：
- <项目路径>/src/main/java/.../TrackingHelper.java（SDK初始化 + 事件调用）

服务端java（snippet）：
- .ae-cli/output/java-sdk.java（LoggerConsumer代码片段）
- .ae-cli/output/daemon.json（LogBus2配置）

LogBus2官方文档：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

独立选项：
- .ae-cli/output/te-debug.java（校验脚本）

附件上传：已将生成的输出文件上传至文件/附件管理入口

Markdown code snippet display

Markdown代码片段展示

For all

snippet

selections, display code grouped by platform in the markdown response:

undefined

对于所有

snippet

选择，在Markdown回复中按平台分组展示代码：

undefined

Client Android

客户端Android

SDK Initialization

SDK初始化

java

TDAnalytics.init(this, SERVER_URL, APPID);

java

TDAnalytics.init(this, SERVER_URL, APPID);

Super Properties

公共属性

java

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

java

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

Event Group: auth

事件组：auth

user_login

java

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

...

---

java

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

...

---

Phase 5 — Validate hint

阶段5 — 验证提示

Provide validation guidance based on selected platforms:

根据所选平台提供验证指导：

Validation Steps

验证步骤

Validation steps:
1. Confirm the active AE environment:
   ae-cli config current

2. List existing Debug devices:
   ae-cli tracking debug-device list --project-id <project_id>

3. Create the script's stable device ID if it is missing, then select it:
   ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>
   ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>

4. Run validation script:
   - Client: run .ae-cli/output/te-debug-client.<ext>
   - Server: run .ae-cli/output/te-debug-server.<ext>

5. Query the most recent hour of Debug data:
   ae-cli tracking debug-data list --project-id <project_id> --device-id <device_id>

6. Confirm has_data=true, then inspect event names, property structures, and error fields.
   If needed, add --event-name <event_name> or --start-time "YYYY-MM-DD HH:mm:ss".

7. Only if the CLI capability is unavailable, open the AE Debug page:
   https://<host>/#/data/debug

8. For LogBus2:
   - Copy daemon.json to LogBus2 conf/ directory
   - Start: ./logbus start
   - Official docs: https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US

验证步骤：
1. 确认当前AE环境：
   ae-cli config current

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

3. 若脚本的稳定设备ID缺失，创建并选择该设备：
   ae-cli tracking debug-device add --project-id <project_id> --device-id <device_id> --device-name <name>
   ae-cli tracking debug-device select --project-id <project_id> --device-id <device_id>

4. 运行校验脚本：
   - 客户端：运行.ae-cli/output/te-debug-client.<ext>
   - 服务端：运行.ae-cli/output/te-debug-server.<ext>

5. 查询最近一小时的调试数据：
   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调试页面：
   https://<host>/#/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()
```
in code to associate user IDs
Remind user to copy daemon.json to LogBus2 conf/ directory

提醒用户提交更改（若使用过
```
insert
```
模式）
提醒用户在代码中调用
```
login()
```
/
```
identify()
```
关联用户ID
提醒用户将daemon.json复制到LogBus2的conf/目录

Validation failure

验证失败

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

请用户粘贴错误文本以便调试
检查SERVER_URL / appId是否正确
检查网络连接
检查LogBus2配置文件格式

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

未先执行
git status
检查就执行任何
insert
操作（重要：必须先检查；若存在未提交更改，拒绝执行）
跳过阶段3的参考文档，随意插入代码
忽略
```
// @tracking <event>
```
注释的增量检测
将网页host作为SERVER_URL使用（必须分开）
使用LogBus v1（已废弃 — 仅使用LogBus2）
生成LogBus2配置时不提供官方文档链接
在客户端代码中包含
```
platform === "server"
```
的专属事件
在服务端代码中包含
```
platform === "client"
```
的专属事件（除非
```
platform === "both"
```
）
跳过SDK主文档读取，猜测集成方式 — 每个SDK的集成方式不同；必须先读取wiki主文档的「集成SDK」章节，再根据项目特点选择正确的方式（有无构建工具）
在任何面向用户的输出（代码注释、交互提示、Markdown）中将"Super Property"翻译为「超级属性」—— AE官方正确中文术语为「公共事件属性」或「公共属性」
未完成阶段0.5就进入阶段1 — 必须先确认SDK集成方式，再插入代码，否则生成的track()调用无法生效

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:

Read
```
references/sdk-index.md
```
to find the selected SDK's main document and advanced guide paths.
Verify the main document path exists in the local wiki mirror before reading it.
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.
Read the wiki main doc first (initialization, imports, package names, basic API).
Read the advanced guide only after the main doc (LoggerConsumer, user properties, auto-track, preset properties, etc.).
Check advanced guide sub-documents if needed.

所有输出模式规则均在

references/*.md

中。本SKILL.md仅处理阶段编排。

SDK文档索引：

```
references/sdk-index.md
```
— 所有SDK wiki文档路径索引（权威来源）

输出模式参考：

```
references/client-sdk-insert.md
```
— 客户端代码插入流程
```
references/snippet-delivery.md
```
— 代码片段生成流程
```
references/server-sdk-insert.md
```
— 服务端代码插入流程（LoggerConsumer + LogBus2）
```
references/logbus-config.md
```
— LogBus2配置生成（包含官方文档链接）
```
references/debug-script.md
```
— 校验脚本生成

LogBus2官方文档（生成配置时必须提供）：

用户指南：https://docs-v2.thinkingdata.cn/?version=latest&code=logbus2_installation&lan=en-US
下载链接在官方文档的「二、下载LogBus2」章节中

Wiki目录结构（详见

~/.ae-cli/wiki/schema.md

）：

```
~/.ae-cli/wiki/raw/
```
— AE官方文档镜像（只读，由爬虫维护）
```
~/.ae-cli/wiki/synthesis/
```
— LLM生成的概述文档

代码生成时的文档读取顺序：

读取
```
references/sdk-index.md
```
，找到所选SDK的主文档和进阶指南路径。
读取前验证主文档路径在本地wiki镜像中是否存在。
若索引路径缺失，在
```
~/.ae-cli/wiki/raw/
```
下使用SDK特定关键词（如SDK名称、平台名称、语言名称、
```
main doc
```
）搜索；选择最新的主文档，而非历史/版本化文档。
先读取wiki主文档（初始化、导入、包名、基础API）。
仅在读完主文档后再读取进阶指南（LoggerConsumer、用户属性、自动采集、预置属性等）。
如有需要，查看进阶指南的子文档。