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.

.ae-cli/draft.json

meta.project_id

meta.host

meta.server_url

meta.app_id

meta.sdk_integration_mode

meta.client_platforms

meta.client_sdk_type

meta.server_language

meta.user_identity

project_id

APP_ID

host

SERVER_URL

• 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

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

• Prefer

  meta.client_platform_languages

  (e.g.

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

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

• 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

project_id

APP_ID

host

SERVER_URL

1. 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".
2. 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)

• 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

.ae-cli/draft.json

.ae-cli/draft.xlsx

1. 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)
2. 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

ae-cli tracking code import-template --template

.ae-cli/draft.xlsx

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

1. Reads events, event properties, super properties, and user properties from xlsx
2. Infers

   sdk_integration_mode

   from the event

   platform

   field
3. Outputs draft.json (meta section has events and plan_name only)

#event data

#event data

#super property

#user data

• 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"

ae-cli tracking code import-template --template

platform

• client

  → client-side collection

• server

  → server-side collection

• both

  → both platforms

• 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)

1. SDK integration mode: ask "Will tracking be reported via client-side or server-side? client / server / both"
2. 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"
3. 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
4. User identity system:
   • Account ID source: user_account / role_id / none
   • Visitor ID strategy: auto / device_id / custom
5. 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.

.ae-cli/draft.json

.ae-cli/draft.json

.ae-cli/remote-plan.json

1. AE projectId — get from AE Admin
2. AE web address — needed to fetch plan
3. 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)

android

ios

openharmony

javascript

miniprogram

unity

game_engine

java

python

go

nodejs

php

csharp

• 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.

.ae-cli/output/<platform>-sdk.<ext>

• 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

• debug

  — validation script (generates test upload code)

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 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

• 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)

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

• 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

• 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

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 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

• yes

  → generate

  .ae-cli/output/te-debug.<ext>

• no

  → skip

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

• 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

• 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

insert

references/client-sdk-insert.md

snippet

references/snippet-delivery.md

.ae-cli/output/<platform>-sdk.<ext>

platform === "client"

platform === "both"

• 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

insert

references/server-sdk-insert.md

snippet

references/snippet-delivery.md

.ae-cli/output/<language>-sdk.<ext>

platform === "server"

platform === "both"

• 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

• 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

debug

references/debug-script.md

.ae-cli/output/te-debug.<ext>

.ae-cli/output/

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

• 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.

.java

.kt

.swift

.m

.ets

.cs

.py

.go

.ts

.js

.php

.json

ae-cli agent +add-attachment

• 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.

.ae-cli/output/

• 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

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

• 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

references/*.md

• references/sdk-index.md

  — All SDK wiki document path index (canonical source)

• 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

• 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

~/.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

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.