ae-generate-tracking-plan
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, example text, option lists, etc.
⚠️ CRITICAL: Template localization is CLI-owned. Do NOT manually translate imported template content with the model. Use the src/tracking/i18n module as the source of truth by setting AE_LANG=<user_lang>, writing draft.meta.lang, and regenerating through ae-cli tracking code import-template / ae-cli tracking plan draft.
Before changing any template-owned localized label, first look up the corresponding translation in src/tracking/i18n (for example resources/xlsx/sheets.ts, resources/xlsx/headers.ts, resources/xlsx/types.ts, and resources/cli/*.json). If no matching translation exists there, preserve the imported text and ask before rewriting business semantics.
Do NOT copy Chinese text verbatim from this document into English/Japanese replies unless it is an identifier, template name needed for CLI import, or original source material quoted for traceability.
Terminology Glossary
| 中文 |
English |
Notes |
| 埋点方案 |
Tracking Plan |
AE project-level event & property definitions |
| 埋点模板 |
Tracking Plan Template |
Pre-built industry/genre xlsx templates |
| 方案名称 |
Plan Name |
User-facing plan identifier |
| 应用场景 |
Application Scenario |
One-sentence description of what the app does |
| 素材来源 |
Source Material Type |
prd / chat / codebase / template / data |
| 数据样本 / 文件画像 |
Data Sample / File Profile |
Column→property mapping source from an ae-data-integration inspect profile (source_type: data) |
| 业务维度 |
Business Dimension |
Revenue model, core loop, functional entries, currency system |
| 收入模型 |
Revenue Model |
IAA / IAP / mixed / subscription / commission |
| 核心循环 |
Core Loop |
Core gameplay loop (e.g. "grind stages → earn coins → gacha for heroes") |
| 功能入口 |
Functional Entry |
Stage, shop, guild, leaderboard, task, achievement, etc. |
| 货币体系 |
Currency System |
Hard currency (diamonds), soft currency (gold), etc. |
| 事件 |
Event |
Named user action or system occurrence (event_name) |
| 事件属性 |
Event Property |
Data attached to an event (prop_names) |
| 公共事件属性 |
Common/Super Property |
Property attached to every event automatically. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |
| 用户属性 |
User Property |
Property on the user profile (persistent state) |
| 预置属性 |
Preset Property |
System property prefixed with # (#device_id, #time, etc.) |
| 自动采集事件 |
Auto-track Event |
SDK auto-collected events (ta_app_start, ta_page_show, etc.) |
| 系统事件 |
System Event |
event_tag value reserved for SDK auto-track events (ta_*). One of two non-module tags (together with 基础事件). |
| 基础事件 |
Basic |
event_tag value for account-level lifecycle/progression events (register, login, level_up, create_role, etc.). Not tied to any functional module. |
| 功能模块 |
Functional Module |
event_tag value for feature-specific business events; identifies which module the event belongs to (e.g. Battle, Shop, Ads, Payment, Basic) |
| SDK 集成模式 |
SDK Integration Mode |
client_only / server_only / both / none |
| 客户端平台 |
Client Platform |
Android, iOS, Web, Unity, Mini-program, etc. |
| 服务端语言 |
Server Language |
Java, Python, Go, Node.js, PHP, etc. |
| 用户体系 |
User Identity System |
distinct_id strategy + account_id source |
| 访客 ID |
Visitor ID / Distinct ID |
Anonymous identity before login |
| 账号 ID |
Account ID |
Identified user after login |
| 插入 |
Insert |
Direct code injection into project |
| 片段 |
Snippet |
Code delivered as standalone files |
| 对象组 |
Object Array (array_row) |
[{...}] — variable-length list of related entities |
| 对象 |
Object (object) |
{...} — fixed-structure single entity |
| 校验 |
Validation |
Draft rule checking before xlsx generation |
| 上传 |
Upload |
Pushing the xlsx tracking plan to AE |
| 追加 |
Append |
Adding new events/properties to an existing plan |
| 替换 |
Replace |
Deleting existing plan and uploading a new one |
| 冲突检测 |
Conflict Detection |
Detecting type mismatches and duplicate events before upload |
| 归档 |
Archive |
Copying final draft.xlsx to plans/ directory |
| xlsx 格式契约 |
xlsx Format Contract |
Column rules for AE-compatible Excel generation |
| draft.json |
draft.json |
Internal intermediate representation (JSON) of the tracking plan |
| display_name |
Display Name |
Human-readable name in the user's language |
| event_tag |
Event Tag |
Functional module the event belongs to (e.g. Battle, Shop, Ads, Payment). Auto-track events use "System Event". |
| snake_case |
snake_case |
Canonical naming format: lowercase_with_underscores |
When to Trigger
Trigger when user mentions: "tracking plan / tracking template / AE plan / help me create tracking" etc.
App types covered: H5 / Web / iOS / Android / Mini-program / Unity. Follow strictly
Phase 0 → 1 → 2 → 3 → 4, do not skip steps.
Phase 1 / 3 / 4 are executed via ae-cli tracking CLI (ae-cli tracking plan draft
/ ae-cli auth login / ae-cli tracking plan upload / ae-cli tracking plan delete).
All CLI commands must be prefixed with AE_LANG=<user_lang> (e.g. AE_LANG=en ae-cli tracking plan draft ...),
ensuring CLI output messages and generated xlsx headers match the user's language.
Upload commands MUST also pass --lang <user_lang> so the server parses the uploaded xlsx with the same sheet/header language.
Language rules: For newly generated content, user-facing fields in draft.json (display_name, event_desc, event_tag,
property display_name, property desc, etc.) should be generated in the user's input language.
Every event, event property, common event property, and user property must have a non-empty display_name.
A canonical snake_case identifier is not a substitute for a user-facing display name.
For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,
CLI messages, and auto-track/i18n-owned labels must come from src/tracking/i18n via AE_LANG=<user_lang> and draft.meta.lang.
When a localized label is needed, inspect src/tracking/i18n and use the existing resource key/value; do not invent translations from the model.
If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.
Only identifier fields like event_name, prop_name remain in English snake_case (canonical format).
This skill only cares about command behavior, not internal implementation.
Phase 0 — Anchor (one question per message)
Step 1: Language initialization
Determine <user_lang> from user's input language: Chinese→zh, English→en, Japanese→ja, Korean→ko. Other languages default to en.
All subsequent CLI commands must be prefixed with AE_LANG=<user_lang> to ensure CLI output and generated xlsx headers match the user's language.
When uploading the xlsx, pass --lang <user_lang> as well; it must match draft.meta.lang / the generated xlsx language.
Collect the following 5 items sequentially, do NOT ask all at once:
Item 1 — Application Scenario
Ask: "What is your application's business scenario? One sentence summary, e.g.: An e-commerce website where users browse products and place orders"
After user responds, record to meta.scenario and generate meta.plan_name.
Item 2 — Source Material + Business Dimension (combined)
Before asking, decide whether the current runtime is an agent sandbox. The agent may judge this from runtime context such as sandbox-provisioned cli-token.json, restricted filesystem access, or absence of the user's local files. Do not ask the user just to decide sandbox visibility.
Product document is available in sandbox environments only for files that are readable inside the sandbox workspace, including files the user attaches/uploads into the conversation workspace. It cannot read arbitrary local paths outside the sandbox unless those files are mounted or attached. Codebase is a local-material option and must be hidden in sandbox environments unless the codebase is already present in the readable workspace. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.
If not in a sandbox environment, ask exactly:
Choose your source material (up to 2):
1 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
3 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
4 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
5 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template
6 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
Reply with number(s), e.g. 1,5 or 4. Select up to 2 (option 6 is single-source).
If in a sandbox environment, ask exactly:
Choose your source material (up to 2):
1 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.
2 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
3 - Pre-built template (built-in industry and game genre templates) — Select a built-in template
4 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template
5 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options
Reply with number(s), e.g. 1,4 or 3. Select up to 2 (option 5 is single-source).
Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.
When translating this prompt, preserve the numeric prefixes and line breaks exactly. Every visible option MUST be on its own line and MUST begin with 1 -, 2 -, 3 -, etc. Never place two numbered options in the same paragraph or visual line. If a Markdown renderer may collapse soft line breaks, use Markdown hard line breaks (two trailing spaces before newline) rather than blank lines. Translation may change only the option text, not the numbering prefix or one-option-per-line structure.
User can multi-select (max 2). Interpret numbers by the visible list shown to the user, not by the non-sandbox canonical list.
Canonical source material options (non-sandbox numbering):
- Product document ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)
- Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.
- Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties
- Pre-built template (built-in industry and game genre templates) — Select a built-in template (run
AE_LANG=<user_lang> ae-cli tracking plan list-templates --json to see available templates)
Based on user selection, determine source material type and record to meta.source_type:
| Selection |
source_type |
Handling |
| Product doc only |
prd |
Read product docs (text/images), extract events and properties |
| Description only |
chat |
Construct events in Draft phase based on description |
| Codebase only |
codebase |
Scan source code, extract events/properties from business logic |
| Template only |
template |
Provide built-in template selection |
| Existing plan only |
existing_plan |
Import xlsx as baseline (see "Modify Existing Tracking Plan Flow" below) |
| Data sample only |
data |
Read the inspect profile (ae-local-data-profile/v1), map columns → events/properties (see "Data-path (source_type = data)" below) |
| Any two-item combo |
Join two types with _ |
First as baseline, second as supplement (priority: existing_plan → template → codebase → prd → chat) |
| Existing plan + Pre-built template |
NOT allowed |
Both provide event baselines; semantic conflict |
| Data sample + any other |
NOT allowed |
Data sample is a standalone single-source path |
Follow-up questions (ask in follow-up order defined in Multi-Source Combination Rules below):
- Product doc → if not in a sandbox environment, ask exactly:
What is the product document path?
You can provide one or more items, separated by commas or newlines:
1. Local file path
2. URL
3. Image file path
4. Folder path
- Product doc → if in a sandbox environment, ask exactly:
What is the product document path?
You can provide one or more items, separated by commas or newlines:
1. Sandbox workspace path
2. Uploaded attachment path
3. URL
4. Image file path
5. Folder path
You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available.
- Detailed description → If too vague, follow up on core features, user behaviors, business flows, monetization
- Codebase → ask "What is the project directory path?", then scan source to extract business logic
- Pre-built template → display matching templates for user confirmation
- Modify existing tracking plan → ask "Please provide the xlsx file path of your existing tracking plan", then follow the flow below
- Data sample → ask "Please provide the path of the inspect profile JSON (or the run directory containing it)", then read the
ae-local-data-profile/v1 product and follow the "Data-path (source_type = data)" flow below
Modify Existing Tracking Plan Flow (when user selects this option):
Import: Ask user for the file path, then immediately import:
AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json
Check result:
- If CLI errors (file not found / parse failure) → report error, ask user to fix the file and retry
- If
draft.json has events array empty → 🛑 Severe: No AE-format sheets found (missing # prefix sheets like #事件数据). Tell user the file does not appear to be an AE tracking plan xlsx. User must fix the original file and re-import.
Content validation (when events are non-empty):
AE_LANG=<user_lang> ae-cli tracking plan validate --in .ae-cli/draft.json --fix
Handle validation results by severity:
- If validate passes with no issues at all → skip to Step 5.
| Severity |
Examples |
Handling |
User Action |
| 🔧 Minor (auto-fixable) |
display_name duplicate, array_row sub-property inconsistency, event name duplicate |
--fix auto-fixes, writes to draft.json. Inform user of what was fixed. |
None (informed) |
| ⚠️ Medium (needs confirmation) |
snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type |
List each issue with current value → suggested fix. User confirms item by item before writing to draft.json. |
Confirm each fix |
| 🛑 Severe |
File cannot be parsed, or events array is empty after import |
Reject. Tell user the specific issue. User fixes original file and re-imports. |
Fix original file |
Medium issue confirmation format:
⚠️ The following content needs to be fixed:
| # | Issue | Location | Current | Suggested |
|---|-------|----------|---------|------------|
| 1 | snake_case | event_name | UserLogin | user_login |
| 2 | snake_case | prop_name | vipLevel | vip_level |
| 3 | invalid type | property "level" | integer | number |
Apply all suggested fixes? ok / specify per item / skip
ok → apply all suggested fixes to draft.json
specify per item → confirm each item one by one
skip → keep current values, handle in Refine phase later
⚠️ Never modify the user's original xlsx file. All changes go into draft.json.
Re-validate after fixes → loop until clean, then continue to the next follow-up question (if combined with another source material), or Item 3 (if existing_plan is the only source).
Codebase analysis flow (when source_type includes codebase):
- User provides project directory path
- Scan directory structure, identify tech stack (engine/framework/language)
- Read core business modules (game logic, scene management, UI interaction, state/data models, networking/payment, etc.)
- Extract from code:
- Events: Player interaction actions (click/swipe/trigger), scene transitions, game state changes (start/pause/end), business flow nodes (purchase/upgrade/unlock)
- Event Properties: Action parameters (bullet type/enemy level/item ID), state values (score/HP/coins), context (level ID/difficulty/mode)
- User Properties: Persistent state (level/experience/VIP/cumulative spend)
- Map extracted results to AE naming conventions (
snake_case event names + display_name in user's language)
- Confirm extracted results with user, supplement missing items
Business Dimension Confirmation:
After source material is confirmed, must process business dimension info based on source_type. User must explicitly confirm before proceeding.
| source_type |
Handling |
template |
Directly display template's inherited business dimensions; skip detailed inference |
existing_plan |
Infer business dimensions from existing plan content (analyze event modules, payment events, currency properties); follow up on missing items; event injection preview |
prd / codebase / chat |
Infer business dimensions → follow up on missing items → event injection preview |
Combo (e.g. template_prd) |
See detailed rules below — baseline source's method is primary, supplementary source contributes additional context |
If source_type is template or starts with template_ (covers template, template_prd, template_codebase, template_chat):
Display template's preset business dimensions:
Business Dimension (inherited from template: <template name>)
Revenue Model: <revenue_model>
Core Loop: <core_loop>
Functional Entries: <functional_entries>
Currency System: <currency_system>
Confirm using these business dimensions? ok / modify
- User
ok → proceed to next step
- User says "modify" → switch to prd/chat flow for user to supplement
- For combos (e.g.
template_prd): after confirming template dimensions, also note any supplementary insights from prd/chat as context for Phase 1.2.
If source_type includes existing_plan:
Infer business dimensions from the imported plan content:
- Analyze existing events: Examine
event_tag values to identify functional modules (e.g. events tagged "Battle" → 战斗 module). Examine event names for payment/ad-related patterns to infer revenue model.
- Inference display: Format inference results as a summary:
Business Dimension (inferred from existing plan: <filename>)
Revenue Model: <inferred from payment/ad events>
Core Loop: <inferred from event flow>
Functional Entries: <inferred from event_tag values>
Currency System: <inferred from currency-related properties>
Confirm these business dimensions? ok / modify
- Follow up missing: Only ask about items that could not be inferred
- Event injection preview: Show suggested injected event modules (only add events not already in the plan); user
ok to proceed
- For combos (e.g.
existing_plan_prd): after confirming dimensions from the plan, also note any supplementary insights from prd/chat as context for Phase 1.2.
If source_type is prd / codebase / chat:
- Inference display: Format inference results as a summary, using
business-dimension-mapping.md as the mapping baseline
- Follow up missing: Only ask about missing items or items inferred as "simple"
- Event injection preview: Show suggested injected event modules; user
ok to proceed
Platform validation: Use business-dimension-mapping.md Chapter 5 decision rules to check if injected events' platform assignments are reasonable.
Template matching (prd / codebase / chat scenarios, optional; NOT applicable to existing_plan or template scenarios):
After business dimension confirmation, auto-detect matching templates based on app type:
AE_LANG=<user_lang> ae-cli tracking plan list-templates --json
Show matching templates to user for confirmation. Confirmed templates serve as baseline and participate in Phase 1 event merging.
Multi-Source Combination Rules (when user selects 2 source materials)
Follow-up Order (Phase 0 questioning sequence):
Do not follow user's selection order. Instead, use this order:
existing_plan(blocking validation, always first)→ codebase/prd(user's selection order)→ chat → template
Rationale:
existing_plan must go first — import + validate may require the user to fix their file; processing it early avoids wasted context
codebase / prd — directly reflect actual business requirements, prioritized over generic descriptions and templates
chat — conversational description, supplements business context
template — generic industry template, least specific to the user's business
Source material processing happens primarily in Phase 1.2 (Merge Source Materials). The one exception is existing_plan: it is imported and validated in Phase 0 because user-provided files may need fixing before proceeding. All other sources are processed in Phase 1.2 per their standard flow.
Merge priority (Phase 1.2): existing_plan → template → codebase → prd → chat → autotrack
Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge prop_names without overwriting.
Business Dimension Inference (combined scenarios):
Use the baseline source's inference method as primary. Supplementary sources (especially prd/chat) may contribute additional information — present a merged view for user confirmation.
Valid Combinations:
The "Baseline" column identifies which source has higher merge priority (see Phase 1.2 merge order), which may differ from the user's selection order. Follow-up questioning uses the fixed order in "Multi-Source Combination Rules" above, not the user's selection order.
| Baseline |
Supplementary |
Phase 0 for supplementary |
| existing_plan |
codebase |
Collect path + quick tech stack detection |
| existing_plan |
prd |
Collect path |
| existing_plan |
chat |
Collect description; participates in dimension inference |
| template |
codebase |
Collect path + quick tech stack detection; template matching/import deferred to Phase 1.2 |
| template |
prd |
Collect path; template matching/import deferred to Phase 1.2 |
| template |
chat |
Collect description |
| codebase |
prd |
Collect path |
| codebase |
chat |
Collect description |
| prd |
chat |
Collect description |
| codebase |
template |
Same as template+codebase row above (template is baseline per merge priority) |
| prd |
template |
Same as template+prd row above (template is baseline per merge priority) |
Forbidden: existing_plan + template (both provide event baselines; semantic conflict).
Record business dimension info to meta.business_dimension:
"business_dimension": {
"revenue_model": "<model>",
"core_loop": "<description>",
"functional_entries": ["<entry list>"],
"currency_system": { ... },
"ad_scenes": [],
"iap_items": []
}
Data-path (source_type = data) — condensed single-gate flow
When the user selects the Data sample / file profile option (source_type = data), the flow diverges from the standard 5-item anchor. This path maps table columns → events/properties instead of inventing events from business understanding, and uses a single confirmation gate instead of the 5-segment Refine loop.
What to skip (only Item 1 — Application Scenario and Item 2 — Data sample are collected):
- Item 3 (SDK Integration Config) → skip.
meta.sdk_integration_mode = "none" (data ingested via RESTful / LogBus / DataX, no SDK). No SDK auto-track events are injected (Phase 1.4 already skips none).
- Item 4 (User Identity System) → skip the visitor-ID strategy question. Derive
meta.user_identity from the inspect profile's identity_candidates instead (e.g. a distinct_id / account_id column), account_id_source: "user_account" when an account column exists, otherwise "none".
- Business Dimension confirmation → skip. Mapping is driven by columns, not by revenue model / core loop.
meta.business_dimension stays empty.
Draft construction (replaces Phase 1.1/1.2/1.3 for the data path):
- Read the inspect profile: the
ae-local-data-profile/v1 JSON product (columns / types / samples / UE eligibility / mapping confidence). If it is not present or is stale, re-run ae-cli data-integration inspect for the source file first.
- Event model determination (reuse UE routing): single-table single-event
track / single-table multi-event (event-name column) / single-table user_set / mixed. The agent may propose splitting one table into multiple events (e.g. an ad table split by campaign_type into ad_show / ad_click); such proposals MUST be confirmed in the gate.
- Column → property mapping draft:
- Identify system columns first: time field,
distinct_id / account_id, event-name column, user-property-name column.
- Map the remaining columns to event properties / user properties / super properties.
- Naming:
snake_case event/property names + display_name + desc + event_tag (language follows the user's input).
- Type inference: CSV columns default to
string; infer number / bool / datetime / enum from field name + value distribution + business doc/prompt priors. Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate (do not ask column-by-column beforehand).
- Single confirmation gate (replaces Phase 2, see below).
- Merge with existing plan (reuse Phase 4.1/4.2 conflict detection).
- Persist:
.ae-cli/draft.json → xlsx → upload (sdk_integration_mode = none).
Single confirmation gate (one round, one summary table):
Present ONE merged table covering all of the following in a single message, then wait for a single reply:
- Event list:
event_name / display_name / desc / event_tag / platform.
- Property list:
name / display_name / type / desc / source, with uncertain types highlighted (marked "to-confirm").
- Field scope: default to plan-internal fields only; include a full-import switch for bringing all source columns in.
- Unrecognized / dirty data handling: how unmapped columns, null values, and unparseable rows are treated.
- Same-name property type conflicts: flagged inline in the gate (see Phase 4.2 Type A).
User replies once: ok (accept all), or targeted edits — rename / retype / add / remove individual columns or events. After the gate is confirmed, jump to Phase 3 (project token) then Phase 4 (merge + upload); do NOT enter the 5-segment Refine loop.
dry-run mode:
When the user requests dry-run (or the caller passes data-integration plan --dry-run), produce the draft preview + column→property mapping summary ONLY:
- Show the single confirmation gate table (events + properties + field scope + unrecognized-data handling) and the mapping result, but do NOT write
.ae-cli/draft.json.
- Do NOT generate xlsx, do NOT archive to
plans/, do NOT upload to AE.
- State explicitly that nothing was persisted; the user can approve a real run afterwards.
Item 3 — SDK Integration Config (client + server combined)
Ask: "What is your client platform? (multi-select OK, e.g. Android + iOS) Will you integrate a server-side SDK?"
After asking this Item 3 question, stop and wait for the user's answer. Do not display Item 4 in the same response.
Language filter: The following SDKs have Chinese-only documentation and are visible to Chinese users only: Mini-program, Mini-game, OpenHarmony, LayaAir, Egret, Cocos2d-Lua. Do not show these to non-Chinese users.
Client integration (multi-select OK):
| Option |
Client SDK Type |
| H5/Web App |
JavaScript SDK |
| Mobile Game - Android Native |
Android SDK |
| Mobile Game - iOS Native |
iOS SDK |
| Mobile Game - Unity |
Unity SDK |
| Mobile Game - CocosCreator |
CocosCreator SDK |
| Mobile Game - Cocos2d-x |
Cocos2d-x SDK |
| Mobile Game - Cocos2d-Lua |
Cocos2d-Lua SDK |
| Mobile Game - LayaAir |
LayaAir SDK |
| Mobile Game - Egret |
Egret SDK |
| Mobile Game - Unreal |
Unreal SDK |
| Mobile App - Android Native |
Android SDK |
| Mobile App - iOS Native |
iOS SDK |
| Mobile App - React Native |
React Native SDK |
| Mobile App - Flutter |
Flutter SDK |
| Mobile App - uni-app |
uni-app SDK |
| Mobile App - OpenHarmony |
OpenHarmony SDK |
| Mini-game |
Mini-game SDK (unified, supports WeChat/QQ/TikTok/Baidu, etc.) |
| Mini-program |
Mini-program SDK (unified, supports WeChat/TikTok/Alipay/Baidu, etc.) |
| PC Game - Unreal |
Unreal SDK |
| PC Game - Unity |
Unity SDK |
| PC App - C++ |
C++ SDK |
| PC App - C# |
C# SDK |
| PC App - macOS Native |
macOS SDK |
| PC App - OpenHarmony |
OpenHarmony SDK |
| No client SDK |
None (sdk_integration_mode: "server_only") |
Programming language (Android / iOS SDK only):
| SDK Type |
Supported Languages |
| Android SDK |
Java / Kotlin (can multi-select) |
| iOS SDK |
Objective-C / Swift (can multi-select) |
| Other SDKs |
Fixed language, no selection needed |
Follow-up: chose Android SDK → ask "Which programming language? Java / Kotlin / both"
Follow-up: chose iOS SDK → ask "Which programming language? Objective-C / Swift / both"
Record to client_platform_languages:
"client_platform_languages": {
"android": ["java", "kotlin"],
"openharmony": ["typescript"]
}
⚠️ Multi-platform meta field rules: When ≥2 client platforms are selected, Draft meta must use client_platforms (array) + client_platform_languages (dictionary). Do NOT use only client_sdk_type (single value) + client_language (single value), which would only record one platform. Single-platform scenarios use client_sdk_type + client_language.
Server integration:
| Option |
Server SDK Type |
sdk_integration_mode |
| Java |
Java SDK |
both |
| Python |
Python SDK |
both |
| Go |
Go SDK |
both |
| Node.js |
Node SDK |
both |
| PHP |
PHP SDK |
both |
| C# / .NET |
C# SDK |
both |
| C++ |
C++ SDK |
both |
| Erlang |
Erlang SDK |
both |
| Lua |
Lua SDK |
both |
| Ruby |
Ruby SDK |
both |
| Other |
Follow up on specific language; check wiki for SDK availability |
both |
| No server SDK |
None |
client_only or none |
SDK integration mode auto-detection:
| Client Integration |
Server Integration |
sdk_integration_mode |
| Yes |
Yes |
both |
| Yes |
No |
client_only |
| No |
Yes |
server_only |
| No |
No |
none (RESTful / LogBus / DataX data ingestion) |
none mode: Suitable for historical data import, batch data sync, third-party system integration, etc. Refine phase does not inject SDK auto-track events.
Item 3 confirmation gate:
After the user answers Item 3, normalize the SDK configuration and ask only the missing follow-up questions (for Android/iOS programming language or Other server language).
Then summarize the normalized SDK config and ask: "Confirm this SDK integration config? Reply ok to continue to Item 4, or describe changes."
Do not display Item 4 or ask identity questions until the user explicitly confirms this SDK integration config.
Item 4 — User Identity System (visitor ID + account ID combined)
Ask: "What is the visitor ID generation strategy?"
Options:
auto — SDK auto-generates (default, suitable for most scenarios)
device_id — Use device ID (iOS IDFV / Android AndroidID)
custom — Custom visitor ID (must call identify() immediately after SDK init)
Follow-up: chose custom → ask "What value should the visitor ID use? e.g.: device ID / UUID / guest temp ID"
Ask: "What is the account ID source?"
Options:
user_account — User account ID (unique identifier after login)
role_id — Role ID (game-specific; one account may have multiple roles)
none — No account system (pure guest mode)
Follow-up:
- chose
user_account → ask "What specific value for account ID? e.g.: user_id (user ID), phone (phone number), email (email address)"
- chose
role_id → explain "Role ID is suitable for games — one account can create multiple roles, enabling finer-grained per-role behavior analysis"
Record to meta.user_identity:
Phase 1 — Draft
1.1 Construct Canonical Draft
Draft conceptual structure (internal JSON; users do not view directly):
Draft
├── meta:
│ ├── app_type: App type
│ ├── sdk_integration_mode: SDK integration mode: client_only / server_only / both
│ ├── client_platforms?: Client SDK type list (required when multi-platform, e.g. ["android","ios"])
│ ├── client_sdk_type?: Primary client SDK type (single platform, backward compatible)
│ ├── client_platform_languages?: Per-platform languages (required when multi-platform, e.g. {"android":["kotlin"],"ios":["swift"]})
│ ├── client_language?: Client dev language (single platform, backward compatible)
│ ├── server_language?: Server dev language (only when server_only or both)
│ ├── project_id?: AE project ID (filled in Phase 3)
│ ├── host?: AE web address (filled in Phase 3)
│ ├── plan_name: Plan name
│ ├── lang: xlsx output language (zh/en/ja/ko), based on user's current language; controls generated xlsx headers/sheet names
│ ├── scenario: Business scenario description
│ ├── source_type: Source material type
│ ├── user_identity: User identity config
│ │ ├── account_id_source: Account ID source: user_account / role_id / none
│ │ ├── account_id_field?: Account ID field name (only when user_account, e.g. user_id / phone / email)
│ │ ├── distinct_id_strategy: Visitor ID strategy: auto / device_id / custom
│ │ └── distinct_id_custom_value?: Custom visitor ID value
│ └── business_dimension: Business dimension config (injected in Phase 1.3)
│ ├── revenue_model: Revenue model: IAA / IAP / mixed / subscription / commission
│ ├── core_loop: Core gameplay loop description
│ ├── functional_entries: Functional entry list
│ ├── currency_system: Currency system
│ ├── ad_scenes: Ad scenes (IAA / mixed only)
│ └── iap_items: IAP items (IAP / mixed only)
├── events: Event array, each with platform field
├── event_properties: Global event property pool (deduplicated)
├── common_event_properties: Common/super properties (attached to every event)
└── user_properties: User properties
SDK integration mode fields:
// Multi-platform example (Android + iOS)
{
"sdk_integration_mode": "both", // client_only / server_only / both
"client_platforms": ["android", "ios"], // Required for multi-platform
"client_platform_languages": { // Required for multi-platform; per-platform languages
"android": ["kotlin"],
"ios": ["swift"]
},
"server_language": "java" // Only when server_only or both
}
// Single platform example (backward compatible)
{
"sdk_integration_mode": "client_only",
"client_sdk_type": "android", // Single platform
"client_language": "kotlin" // Single platform
}
Event platform tag (events[].platform):
{
"event_name": "order_create",
"display_name": "Order Create",
"platform": "server", // client / server / both
"prop_names": ["order_id", "order_amount", "payment_method"],
"source": "prd"
}
platform: "client" — Client-side upload (user behavior events)
platform: "server" — Server-side upload (business data events)
platform: "both" — Both sides upload (timestamps must be synced)
Property object format (event_properties / common_event_properties pool entries):
{
"name": "order_amount",
"display_name": "Order Amount",
"type": "number",
"desc": "Order total in cents",
"source": "prd"
}
⚠️ Field names: use name (NOT prop_name), display_name, type, desc, source. Events reference properties by prop_names: ["order_amount", ...] — this is an array of property name references (string array), NOT property objects.
User property format (user_properties pool entries):
{
"name": "vip_level",
"display_name": "VIP Level",
"type": "number",
"desc": "Current VIP level of the user",
"source": "chat",
"update_type": "user_set"
}
update_type is one of: user_set (overwrite), user_setOnce (first-set-only), user_add (numeric accumulate).
User identity fields (meta.user_identity):
{
"account_id_source": "user_account", // Account ID source: user_account / role_id / none
"account_id_field": "user_id", // Account ID field name (only when user_account)
"distinct_id_strategy": "auto", // Visitor ID strategy: auto / device_id / custom
"distinct_id_custom_value": null // Custom visitor ID value description (only when strategy=custom)
}
Property types (enum): string / number / bool / datetime /
object (single object, with sub-properties) / array_row (object array, supports parent.child nesting) / array_string (string array)
Naming rules: Event names / property names must be snake_case; use display_name field for human-readable names.
1.2 Merge Source Materials
Merge order: existing_plan → template → codebase → prd → chat → autotrack
Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge prop_names without overwriting.
- existing_plan: Already imported and validated in Phase 0 (see "Modify Existing Tracking Plan Flow"). Events are in draft.json as the baseline; each item marked
source: "existing_plan". Higher-priority sources supplement with new events only; same-name events keep the existing_plan
…(truncated)
1---2name: ae-generate-tracking-plan3description: "Interactive generation of an AE tracking plan and upload. Trigger words: 埋点方案、埋点模板、tracking plan、AE 方案生成、create tracking plan、トラッキングプラン、트래킹 플랜. Follows anchor → draft → refine → token → upload five-phase workflow. Deliverable is a real tracking plan created in the AE platform."4metadata:5 source: https://skillmd.com/skills/thinkingaiagenticengine/ae-generate-tracking-plan6---78# ae-generate-tracking-plan910> **Conversation language**: This skill document is in English, but **all output to the user MUST be in the user's input language**.11> English input → English reply; Chinese input → Chinese reply; Japanese input → Japanese reply.12> If uncertain, default to English.13> This applies to all output: section titles, phase names, template prompts, example text, option lists, etc.14> **⚠️ CRITICAL: Template localization is CLI-owned. Do NOT manually translate imported template content with the model. Use the `src/tracking/i18n` module as the source of truth by setting `AE_LANG=<user_lang>`, writing `draft.meta.lang`, and regenerating through `ae-cli tracking code import-template` / `ae-cli tracking plan draft`.**15> **Before changing any template-owned localized label, first look up the corresponding translation in `src/tracking/i18n` (for example `resources/xlsx/sheets.ts`, `resources/xlsx/headers.ts`, `resources/xlsx/types.ts`, and `resources/cli/*.json`). If no matching translation exists there, preserve the imported text and ask before rewriting business semantics.**16> Do NOT copy Chinese text verbatim from this document into English/Japanese replies unless it is an identifier, template name needed for CLI import, or original source material quoted for traceability.1718## Terminology Glossary1920| 中文 | English | Notes |21|------|---------|-------|22| 埋点方案 | Tracking Plan | AE project-level event & property definitions |23| 埋点模板 | Tracking Plan Template | Pre-built industry/genre xlsx templates |24| 方案名称 | Plan Name | User-facing plan identifier |25| 应用场景 | Application Scenario | One-sentence description of what the app does |26| 素材来源 | Source Material Type | prd / chat / codebase / template / data |27| 数据样本 / 文件画像 | Data Sample / File Profile | Column→property mapping source from an `ae-data-integration` inspect profile (`source_type: data`) |28| 业务维度 | Business Dimension | Revenue model, core loop, functional entries, currency system |29| 收入模型 | Revenue Model | IAA / IAP / mixed / subscription / commission |30| 核心循环 | Core Loop | Core gameplay loop (e.g. "grind stages → earn coins → gacha for heroes") |31| 功能入口 | Functional Entry | Stage, shop, guild, leaderboard, task, achievement, etc. |32| 货币体系 | Currency System | Hard currency (diamonds), soft currency (gold), etc. |33| 事件 | Event | Named user action or system occurrence (`event_name`) |34| 事件属性 | Event Property | Data attached to an event (`prop_names`) |35| 公共事件属性 | Common/Super Property | Property attached to every event automatically. ⚠️ The correct Chinese AE term is "公共事件属性" or "公共属性". Never translate "Super Property" as "超级属性" — that is NOT a valid AE term. |36| 用户属性 | User Property | Property on the user profile (persistent state) |37| 预置属性 | Preset Property | System property prefixed with `#` (`#device_id`, `#time`, etc.) |38| 自动采集事件 | Auto-track Event | SDK auto-collected events (`ta_app_start`, `ta_page_show`, etc.) |39| 系统事件 | System Event | event_tag value reserved for SDK auto-track events (`ta_*`). One of two non-module tags (together with 基础事件). |40| 基础事件 | Basic | event_tag value for account-level lifecycle/progression events (register, login, level_up, create_role, etc.). Not tied to any functional module. |41| 功能模块 | Functional Module | event_tag value for feature-specific business events; identifies which module the event belongs to (e.g. Battle, Shop, Ads, Payment, Basic) |42| SDK 集成模式 | SDK Integration Mode | `client_only` / `server_only` / `both` / `none` |43| 客户端平台 | Client Platform | Android, iOS, Web, Unity, Mini-program, etc. |44| 服务端语言 | Server Language | Java, Python, Go, Node.js, PHP, etc. |45| 用户体系 | User Identity System | distinct_id strategy + account_id source |46| 访客 ID | Visitor ID / Distinct ID | Anonymous identity before login |47| 账号 ID | Account ID | Identified user after login |48| 插入 | Insert | Direct code injection into project |49| 片段 | Snippet | Code delivered as standalone files |50| 对象组 | Object Array (`array_row`) | `[{...}]` — variable-length list of related entities |51| 对象 | Object (`object`) | `{...}` — fixed-structure single entity |52| 校验 | Validation | Draft rule checking before xlsx generation |53| 上传 | Upload | Pushing the xlsx tracking plan to AE |54| 追加 | Append | Adding new events/properties to an existing plan |55| 替换 | Replace | Deleting existing plan and uploading a new one |56| 冲突检测 | Conflict Detection | Detecting type mismatches and duplicate events before upload |57| 归档 | Archive | Copying final draft.xlsx to `plans/` directory |58| xlsx 格式契约 | xlsx Format Contract | Column rules for AE-compatible Excel generation |59| draft.json | draft.json | Internal intermediate representation (JSON) of the tracking plan |60| display_name | Display Name | Human-readable name in the user's language |61| event_tag | Event Tag | Functional module the event belongs to (e.g. Battle, Shop, Ads, Payment). Auto-track events use "System Event". |62| snake_case | snake_case | Canonical naming format: `lowercase_with_underscores` |6364## When to Trigger6566Trigger when user mentions: "tracking plan / tracking template / AE plan / help me create tracking" etc.67App types covered: H5 / Web / iOS / Android / Mini-program / Unity. Follow strictly68Phase 0 → 1 → 2 → 3 → 4, do not skip steps.6970> Phase 1 / 3 / 4 are executed via `ae-cli tracking` CLI (`ae-cli tracking plan draft`71> / `ae-cli auth login` / `ae-cli tracking plan upload` / `ae-cli tracking plan delete`).72> **All CLI commands must be prefixed with `AE_LANG=<user_lang>`** (e.g. `AE_LANG=en ae-cli tracking plan draft ...`),73> ensuring CLI output messages and generated xlsx headers match the user's language.74> Upload commands MUST also pass `--lang <user_lang>` so the server parses the uploaded xlsx with the same sheet/header language.75> 76> **Language rules**: For newly generated content, user-facing fields in draft.json (`display_name`, `event_desc`, `event_tag`,77> property `display_name`, property `desc`, etc.) should be generated in the **user's input language**.78> Every event, event property, common event property, and user property must have a non-empty `display_name`.79> A canonical snake_case identifier is not a substitute for a user-facing display name.80> For imported templates, do NOT translate those fields manually. Template sheet names, headers, property type display values,81> CLI messages, and auto-track/i18n-owned labels must come from `src/tracking/i18n` via `AE_LANG=<user_lang>` and `draft.meta.lang`.82> When a localized label is needed, inspect `src/tracking/i18n` and use the existing resource key/value; do not invent translations from the model.83> If template business text needs localization and the CLI/i18n resources do not provide it, preserve the imported text and ask the user before rewriting business semantics.84> Only identifier fields like `event_name`, `prop_name` remain in English snake_case (canonical format).85> This skill only cares about command behavior, not internal implementation.8687---8889## Phase 0 — Anchor (one question per message)9091> **Step 1: Language initialization**92> 93> Determine `<user_lang>` from user's input language: Chinese→`zh`, English→`en`, Japanese→`ja`, Korean→`ko`. Other languages default to `en`.94> All subsequent CLI commands must be prefixed with `AE_LANG=<user_lang>` to ensure CLI output and generated xlsx headers match the user's language.95> When uploading the xlsx, pass `--lang <user_lang>` as well; it must match `draft.meta.lang` / the generated xlsx language.9697Collect the following **5 items** sequentially, **do NOT ask all at once**:9899### Item 1 — Application Scenario100101Ask: **"What is your application's business scenario? One sentence summary, e.g.: An e-commerce website where users browse products and place orders"**102103After user responds, record to `meta.scenario` and generate `meta.plan_name`.104105### Item 2 — Source Material + Business Dimension (combined)106107Before asking, decide whether the current runtime is an agent sandbox. The agent may judge this from runtime context such as sandbox-provisioned `cli-token.json`, restricted filesystem access, or absence of the user's local files. Do not ask the user just to decide sandbox visibility.108109Product document is available in sandbox environments **only for files that are readable inside the sandbox workspace**, including files the user attaches/uploads into the conversation workspace. It cannot read arbitrary local paths outside the sandbox unless those files are mounted or attached. Codebase is a local-material option and must be hidden in sandbox environments unless the codebase is already present in the readable workspace. When options are hidden, renumber the visible list contiguously from 1; never show skipped numbers.110111If **not** in a sandbox environment, ask exactly:112113```text114Choose your source material (up to 2):1151161 - Product document (local path, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)1172 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.1183 - Codebase (local project path; hidden in sandbox) — Analyze source code to extract events and properties1194 - Pre-built template (built-in industry and game genre templates) — Select a built-in template1205 - Modify existing tracking plan (local AE format xlsx file) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description / Codebase, but NOT with Pre-built template1216 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options122123Reply with number(s), e.g. 1,5 or 4. Select up to 2 (option 6 is single-source).124```125126If in a sandbox environment, ask exactly:127128```text129Choose your source material (up to 2):1301311 - Product document (sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp). You can attach/upload relevant files here.1322 - Detailed description (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.1333 - Pre-built template (built-in industry and game genre templates) — Select a built-in template1344 - Modify existing tracking plan (sandbox workspace path) — Import an existing tracking plan xlsx as baseline for modification; can be combined with Product doc / Description, but NOT with Pre-built template1355 - Data sample / file profile (from ae-data-integration inspect) — Map data columns (CSV/Excel/JSONL) to events & properties from an inspect profile; single-source path, not combinable with other options136137Reply with number(s), e.g. 1,4 or 3. Select up to 2 (option 5 is single-source).138```139140Do not rewrite this source material list as unnumbered bullets, cards, or prose. The user must be able to reply with the visible numbers.141When translating this prompt, preserve the numeric prefixes and line breaks exactly. Every visible option MUST be on its own line and MUST begin with `1 -`, `2 -`, `3 -`, etc. Never place two numbered options in the same paragraph or visual line. If a Markdown renderer may collapse soft line breaks, use Markdown hard line breaks (two trailing spaces before newline) rather than blank lines. Translation may change only the option text, not the numbering prefix or one-option-per-line structure.142143User can multi-select (max 2). Interpret numbers by the **visible list shown to the user**, not by the non-sandbox canonical list.144145Canonical source material options (non-sandbox numbering):1461471. **Product document** ****(****local path, sandbox workspace path, uploaded attachment, URL, image file, or folder) — Extract events and properties from product docs; supports md/pdf/docx/URL/images (png/jpg/jpeg/webp)1482. **Detailed description** (conversational) — Describe app business flow, core features, user behaviors, monetization model, etc.1493. **Codebase** (local project path; hidden in sandbox) — Analyze source code to extract events and properties1504. **Pre-built template** (built-in industry and game genre templates) — Select a built-in template (run `AE_LANG=<user_lang> ae-cli tracking plan list-templates --json` to see available templates)151152Based on user selection, determine source material type and record to `meta.source_type`:153154| Selection | source_type | Handling |155|---|---|---|156| Product doc only | `prd` | Read product docs (text/images), extract events and properties |157| Description only | `chat` | Construct events in Draft phase based on description |158| Codebase only | `codebase` | Scan source code, extract events/properties from business logic |159| Template only | `template` | Provide built-in template selection |160| Existing plan only | `existing_plan` | Import xlsx as baseline (see "Modify Existing Tracking Plan Flow" below) |161| Data sample only | `data` | Read the inspect profile (`ae-local-data-profile/v1`), map columns → events/properties (see "Data-path (source_type = data)" below) |162| Any two-item combo | Join two types with `_` | First as baseline, second as supplement (priority: existing_plan → template → codebase → prd → chat) |163| Existing plan + Pre-built template | **NOT allowed** | Both provide event baselines; semantic conflict |164| Data sample + any other | **NOT allowed** | Data sample is a standalone single-source path |165166**Follow-up questions** (ask in follow-up order defined in Multi-Source Combination Rules below):167- Product doc → if not in a sandbox environment, ask exactly:168 ```text169 What is the product document path?170171 You can provide one or more items, separated by commas or newlines:172 1. Local file path173 2. URL174 3. Image file path175 4. Folder path176 ```177- Product doc → if in a sandbox environment, ask exactly:178 ```text179 What is the product document path?180181 You can provide one or more items, separated by commas or newlines:182 1. Sandbox workspace path183 2. Uploaded attachment path184 3. URL185 4. Image file path186 5. Folder path187188 You can also attach/upload relevant files here, and I will read them from the sandbox workspace if available.189 ```190- Detailed description → If too vague, follow up on core features, user behaviors, business flows, monetization191- Codebase → ask **"What is the project directory path?"**, then scan source to extract business logic192- Pre-built template → display matching templates for user confirmation193- Modify existing tracking plan → ask **"Please provide the xlsx file path of your existing tracking plan"**, then follow the flow below194- Data sample → ask **"Please provide the path of the inspect profile JSON (or the run directory containing it)"**, then read the `ae-local-data-profile/v1` product and follow the "Data-path (source_type = data)" flow below195196**Modify Existing Tracking Plan Flow** (when user selects this option):1971981. **Import**: Ask user for the file path, then immediately import:199 ```bash200 AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json201 ```2022. **Check result**:203 - If CLI errors (file not found / parse failure) → report error, ask user to fix the file and retry204 - If `draft.json` has `events` array empty → 🛑 **Severe: No AE-format sheets found** (missing `#` prefix sheets like `#事件数据`). Tell user the file does not appear to be an AE tracking plan xlsx. User must fix the original file and re-import.2053. **Content validation** (when events are non-empty):206 ```bash207 AE_LANG=<user_lang> ae-cli tracking plan validate --in .ae-cli/draft.json --fix208 ```2094. **Handle validation results by severity**:210 - If validate passes with **no issues at all** → skip to Step 5.211212 | Severity | Examples | Handling | User Action |213 |---|---|---|---|214 | 🔧 **Minor** (auto-fixable) | `display_name` duplicate, `array_row` sub-property inconsistency, event name duplicate | `--fix` auto-fixes, writes to `draft.json`. Inform user of what was fixed. | None (informed) |215 | ⚠️ **Medium** (needs confirmation) | snake_case violation, property name duplicate, invalid property type, nested property parent is not a composite type | List each issue with current value → suggested fix. User confirms item by item before writing to `draft.json`. | Confirm each fix |216 | 🛑 **Severe** | File cannot be parsed, or events array is empty after import | Reject. Tell user the specific issue. User fixes **original file** and re-imports. | Fix original file |217218 **Medium issue confirmation format**:219 ```220 ⚠️ The following content needs to be fixed:221222 | # | Issue | Location | Current | Suggested |223 |---|-------|----------|---------|------------|224 | 1 | snake_case | event_name | UserLogin | user_login |225 | 2 | snake_case | prop_name | vipLevel | vip_level |226 | 3 | invalid type | property "level" | integer | number |227228 Apply all suggested fixes? ok / specify per item / skip229 ```230 - `ok` → apply all suggested fixes to `draft.json`231 - `specify per item` → confirm each item one by one232 - `skip` → keep current values, handle in Refine phase later233234 ⚠️ **Never modify the user's original xlsx file.** All changes go into `draft.json`.2352365. **Re-validate** after fixes → loop until clean, then continue to the next follow-up question (if combined with another source material), or Item 3 (if existing_plan is the only source).237238**Codebase analysis flow** (when source_type includes `codebase`):2392401. User provides project directory path2412. Scan directory structure, identify tech stack (engine/framework/language)2423. Read core business modules (game logic, scene management, UI interaction, state/data models, networking/payment, etc.)2434. Extract from code:244 - **Events**: Player interaction actions (click/swipe/trigger), scene transitions, game state changes (start/pause/end), business flow nodes (purchase/upgrade/unlock)245 - **Event Properties**: Action parameters (bullet type/enemy level/item ID), state values (score/HP/coins), context (level ID/difficulty/mode)246 - **User Properties**: Persistent state (level/experience/VIP/cumulative spend)2475. Map extracted results to AE naming conventions (`snake_case` event names + `display_name` in user's language)2486. Confirm extracted results with user, supplement missing items249250**Business Dimension Confirmation**:251252After source material is confirmed, **must** process business dimension info based on source_type. User must explicitly confirm before proceeding.253254| source_type | Handling |255|---|---|256| `template` | Directly display template's inherited business dimensions; skip detailed inference |257| `existing_plan` | Infer business dimensions from existing plan content (analyze event modules, payment events, currency properties); follow up on missing items; event injection preview |258| `prd` / `codebase` / `chat` | Infer business dimensions → follow up on missing items → event injection preview |259| Combo (e.g. `template_prd`) | See detailed rules below — baseline source's method is primary, supplementary source contributes additional context |260261**If source_type is template or starts with template_** (covers `template`, `template_prd`, `template_codebase`, `template_chat`):262263Display template's preset business dimensions:264265```266Business Dimension (inherited from template: <template name>)267268Revenue Model: <revenue_model>269Core Loop: <core_loop>270Functional Entries: <functional_entries>271Currency System: <currency_system>272273Confirm using these business dimensions? ok / modify274```275276- User `ok` → proceed to next step277- User says "modify" → switch to prd/chat flow for user to supplement278- For combos (e.g. `template_prd`): after confirming template dimensions, also note any supplementary insights from `prd`/`chat` as context for Phase 1.2.279280**If source_type includes existing_plan**:281282Infer business dimensions from the imported plan content:2832841. **Analyze existing events**: Examine `event_tag` values to identify functional modules (e.g. events tagged "Battle" → 战斗 module). Examine event names for payment/ad-related patterns to infer revenue model.2852. **Inference display**: Format inference results as a summary:286 ```287 Business Dimension (inferred from existing plan: <filename>)288289 Revenue Model: <inferred from payment/ad events>290 Core Loop: <inferred from event flow>291 Functional Entries: <inferred from event_tag values>292 Currency System: <inferred from currency-related properties>293294 Confirm these business dimensions? ok / modify295 ```2963. **Follow up missing**: Only ask about items that could not be inferred2974. **Event injection preview**: Show suggested injected event modules (only add events not already in the plan); user `ok` to proceed298- For combos (e.g. `existing_plan_prd`): after confirming dimensions from the plan, also note any supplementary insights from `prd`/`chat` as context for Phase 1.2.299300**If source_type is prd / codebase / chat**:3013021. **Inference display**: Format inference results as a summary, using `business-dimension-mapping.md` as the mapping baseline3032. **Follow up missing**: Only ask about missing items or items inferred as "simple"3043. **Event injection preview**: Show suggested injected event modules; user `ok` to proceed305306Platform validation: Use `business-dimension-mapping.md` Chapter 5 decision rules to check if injected events' platform assignments are reasonable.307308**Template matching** (prd / codebase / chat scenarios, optional; **NOT applicable to existing_plan or template scenarios**):309310After business dimension confirmation, auto-detect matching templates based on app type:311```bash312AE_LANG=<user_lang> ae-cli tracking plan list-templates --json313```314315Show matching templates to user for confirmation. Confirmed templates serve as baseline and participate in Phase 1 event merging.316317### Multi-Source Combination Rules (when user selects 2 source materials)318319**Follow-up Order** (Phase 0 questioning sequence):320321Do **not** follow user's selection order. Instead, use this order:322323```324existing_plan(blocking validation, always first)→ codebase/prd(user's selection order)→ chat → template325```326327Rationale:328- `existing_plan` must go first — import + validate may require the user to fix their file; processing it early avoids wasted context329- `codebase` / `prd` — directly reflect actual business requirements, prioritized over generic descriptions and templates330- `chat` — conversational description, supplements business context331- `template` — generic industry template, least specific to the user's business332333Source material processing happens primarily in Phase 1.2 (Merge Source Materials). The one exception is `existing_plan`: it is imported and validated in Phase 0 because user-provided files may need fixing before proceeding. All other sources are processed in Phase 1.2 per their standard flow.334335Merge priority (Phase 1.2): `existing_plan → template → codebase → prd → chat → autotrack`336Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge `prop_names` without overwriting.337338**Business Dimension Inference (combined scenarios)**:339340Use the baseline source's inference method as primary. Supplementary sources (especially prd/chat) may contribute additional information — present a merged view for user confirmation.341342**Valid Combinations**:343344> The "Baseline" column identifies which source has higher merge priority (see Phase 1.2 merge order), which may differ from the user's selection order. Follow-up questioning uses the fixed order in "Multi-Source Combination Rules" above, not the user's selection order.345346| Baseline | Supplementary | Phase 0 for supplementary |347|---|---|---|348| existing_plan | codebase | Collect path + quick tech stack detection |349| existing_plan | prd | Collect path |350| existing_plan | chat | Collect description; participates in dimension inference |351| template | codebase | Collect path + quick tech stack detection; template matching/import deferred to Phase 1.2 |352| template | prd | Collect path; template matching/import deferred to Phase 1.2 |353| template | chat | Collect description |354| codebase | prd | Collect path |355| codebase | chat | Collect description |356| prd | chat | Collect description |357| codebase | template | Same as template+codebase row above (template is baseline per merge priority) |358| prd | template | Same as template+prd row above (template is baseline per merge priority) |359360**Forbidden**: `existing_plan + template` (both provide event baselines; semantic conflict).361362**Record business dimension info to `meta.business_dimension`**:363```json364"business_dimension": {365 "revenue_model": "<model>",366 "core_loop": "<description>",367 "functional_entries": ["<entry list>"],368 "currency_system": { ... },369 "ad_scenes": [],370 "iap_items": []371}372```373374### Data-path (source_type = data) — condensed single-gate flow375376When the user selects the **Data sample / file profile** option (`source_type = data`), the flow diverges from the standard 5-item anchor. This path **maps table columns → events/properties** instead of inventing events from business understanding, and uses a **single confirmation gate** instead of the 5-segment Refine loop.377378**What to skip** (only Item 1 — Application Scenario and Item 2 — Data sample are collected):379380- **Item 3 (SDK Integration Config)** → skip. `meta.sdk_integration_mode = "none"` (data ingested via RESTful / LogBus / DataX, no SDK). No SDK auto-track events are injected (Phase 1.4 already skips `none`).381- **Item 4 (User Identity System)** → skip the visitor-ID strategy question. Derive `meta.user_identity` from the inspect profile's `identity_candidates` instead (e.g. a `distinct_id` / `account_id` column), `account_id_source: "user_account"` when an account column exists, otherwise `"none"`.382- **Business Dimension confirmation** → skip. Mapping is driven by columns, not by revenue model / core loop. `meta.business_dimension` stays empty.383384**Draft construction (replaces Phase 1.1/1.2/1.3 for the data path)**:3853861. **Read the inspect profile**: the `ae-local-data-profile/v1` JSON product (columns / types / samples / UE eligibility / mapping confidence). If it is not present or is stale, re-run `ae-cli data-integration inspect` for the source file first.3872. **Event model determination** (reuse UE routing): single-table single-event `track` / single-table multi-event (event-name column) / single-table `user_set` / mixed. The agent may propose **splitting one table into multiple events** (e.g. an ad table split by `campaign_type` into `ad_show` / `ad_click`); such proposals MUST be confirmed in the gate.3883. **Column → property mapping draft**:389 - Identify system columns first: time field, `distinct_id` / `account_id`, event-name column, user-property-name column.390 - Map the remaining columns to event properties / user properties / super properties.391 - Naming: `snake_case` event/property names + `display_name` + `desc` + `event_tag` (language follows the user's input).392 - Type inference: CSV columns default to `string`; infer `number` / `bool` / `datetime` / enum from field name + value distribution + business doc/prompt priors. **Uncertain or conflicting columns are marked "to-confirm" and asked only inside the gate** (do not ask column-by-column beforehand).3934. **Single confirmation gate** (replaces Phase 2, see below).3945. **Merge with existing plan** (reuse Phase 4.1/4.2 conflict detection).3956. **Persist**: `.ae-cli/draft.json` → xlsx → upload (`sdk_integration_mode = none`).396397**Single confirmation gate (one round, one summary table)**:398399Present ONE merged table covering all of the following in a single message, then wait for a single reply:400401- **Event list**: `event_name` / `display_name` / `desc` / `event_tag` / `platform`.402- **Property list**: `name` / `display_name` / `type` / `desc` / `source`, with uncertain types highlighted (marked "to-confirm").403- **Field scope**: default to plan-internal fields only; include a **full-import switch** for bringing all source columns in.404- **Unrecognized / dirty data handling**: how unmapped columns, null values, and unparseable rows are treated.405- **Same-name property type conflicts**: flagged inline in the gate (see Phase 4.2 Type A).406407User replies once: `ok` (accept all), or targeted edits — rename / retype / add / remove individual columns or events. After the gate is confirmed, jump to Phase 3 (project token) then Phase 4 (merge + upload); do NOT enter the 5-segment Refine loop.408409**dry-run mode**:410411When the user requests dry-run (or the caller passes `data-integration plan --dry-run`), produce the draft preview + column→property mapping summary ONLY:412413- Show the single confirmation gate table (events + properties + field scope + unrecognized-data handling) and the mapping result, but do NOT write `.ae-cli/draft.json`.414- Do NOT generate xlsx, do NOT archive to `plans/`, do NOT upload to AE.415- State explicitly that nothing was persisted; the user can approve a real run afterwards.416417### Item 3 — SDK Integration Config (client + server combined)418419Ask: **"What is your client platform? (multi-select OK, e.g. Android + iOS) Will you integrate a server-side SDK?"**420421After asking this Item 3 question, **stop and wait for the user's answer**. Do not display Item 4 in the same response.422423> **Language filter**: The following SDKs have Chinese-only documentation and are **visible to Chinese users only**: `Mini-program`, `Mini-game`, `OpenHarmony`, `LayaAir`, `Egret`, `Cocos2d-Lua`. Do not show these to non-Chinese users.424425**Client integration** (multi-select OK):426427| Option | Client SDK Type |428|---|---|429| H5/Web App | JavaScript SDK |430| Mobile Game - Android Native | Android SDK |431| Mobile Game - iOS Native | iOS SDK |432| Mobile Game - Unity | Unity SDK |433| Mobile Game - CocosCreator | CocosCreator SDK |434| Mobile Game - Cocos2d-x | Cocos2d-x SDK |435| Mobile Game - Cocos2d-Lua | Cocos2d-Lua SDK |436| Mobile Game - LayaAir | LayaAir SDK |437| Mobile Game - Egret | Egret SDK |438| Mobile Game - Unreal | Unreal SDK |439| Mobile App - Android Native | Android SDK |440| Mobile App - iOS Native | iOS SDK |441| Mobile App - React Native | React Native SDK |442| Mobile App - Flutter | Flutter SDK |443| Mobile App - uni-app | uni-app SDK |444| Mobile App - OpenHarmony | OpenHarmony SDK |445| Mini-game | Mini-game SDK (unified, supports WeChat/QQ/TikTok/Baidu, etc.) |446| Mini-program | Mini-program SDK (unified, supports WeChat/TikTok/Alipay/Baidu, etc.) |447| PC Game - Unreal | Unreal SDK |448| PC Game - Unity | Unity SDK |449| PC App - C++ | C++ SDK |450| PC App - C# | C# SDK |451| PC App - macOS Native | macOS SDK |452| PC App - OpenHarmony | OpenHarmony SDK |453| No client SDK | None (`sdk_integration_mode: "server_only"`) |454455**Programming language** (Android / iOS SDK only):456457| SDK Type | Supported Languages |458|---|---|459| Android SDK | Java / Kotlin (can multi-select) |460| iOS SDK | Objective-C / Swift (can multi-select) |461| Other SDKs | Fixed language, no selection needed |462463Follow-up: chose Android SDK → ask **"Which programming language? Java / Kotlin / both"**464Follow-up: chose iOS SDK → ask **"Which programming language? Objective-C / Swift / both"**465466Record to `client_platform_languages`:467```json468"client_platform_languages": {469 "android": ["java", "kotlin"],470 "openharmony": ["typescript"]471}472```473474> ⚠️ **Multi-platform meta field rules**: When ≥2 client platforms are selected, Draft meta **must** use `client_platforms` (array) + `client_platform_languages` (dictionary). Do NOT use only `client_sdk_type` (single value) + `client_language` (single value), which would only record one platform. Single-platform scenarios use `client_sdk_type` + `client_language`.475476**Server integration**:477478| Option | Server SDK Type | sdk_integration_mode |479|---|---|---|480| Java | Java SDK | `both` |481| Python | Python SDK | `both` |482| Go | Go SDK | `both` |483| Node.js | Node SDK | `both` |484| PHP | PHP SDK | `both` |485| C# / .NET | C# SDK | `both` |486| C++ | C++ SDK | `both` |487| Erlang | Erlang SDK | `both` |488| Lua | Lua SDK | `both` |489| Ruby | Ruby SDK | `both` |490| Other | Follow up on specific language; check wiki for SDK availability | `both` |491| No server SDK | None | `client_only` or `none` |492493**SDK integration mode auto-detection**:494495| Client Integration | Server Integration | sdk_integration_mode |496|---|---|---|497| Yes | Yes | `both` |498| Yes | No | `client_only` |499| No | Yes | `server_only` |500| No | No | `none` (RESTful / LogBus / DataX data ingestion) |501502`none` mode: Suitable for historical data import, batch data sync, third-party system integration, etc. Refine phase does not inject SDK auto-track events.503504**Item 3 confirmation gate**:505506After the user answers Item 3, normalize the SDK configuration and ask only the missing follow-up questions (for Android/iOS programming language or `Other` server language).507508Then summarize the normalized SDK config and ask: **"Confirm this SDK integration config? Reply ok to continue to Item 4, or describe changes."**509510Do not display Item 4 or ask identity questions until the user explicitly confirms this SDK integration config.511512### Item 4 — User Identity System (visitor ID + account ID combined)513514Ask: **"What is the visitor ID generation strategy?"**515516Options:517- `auto` — SDK auto-generates (default, suitable for most scenarios)518- `device_id` — Use device ID (iOS IDFV / Android AndroidID)519- `custom` — Custom visitor ID (must call `identify()` immediately after SDK init)520521Follow-up: chose `custom` → ask **"What value should the visitor ID use? e.g.: device ID / UUID / guest temp ID"**522523---524525Ask: **"What is the account ID source?"**526527Options:528- `user_account` — User account ID (unique identifier after login)529- `role_id` — Role ID (game-specific; one account may have multiple roles)530- `none` — No account system (pure guest mode)531532Follow-up:533- chose `user_account` → ask **"What specific value for account ID? e.g.: user_id (user ID), phone (phone number), email (email address)"**534- chose `role_id` → explain **"Role ID is suitable for games — one account can create multiple roles, enabling finer-grained per-role behavior analysis"**535536Record to `meta.user_identity`:537538---539540## Phase 1 — Draft541542### 1.1 Construct Canonical Draft543544Draft conceptual structure (**internal JSON; users do not view directly**):545546```547Draft548├── meta:549│ ├── app_type: App type550│ ├── sdk_integration_mode: SDK integration mode: client_only / server_only / both551│ ├── client_platforms?: Client SDK type list (required when multi-platform, e.g. ["android","ios"])552│ ├── client_sdk_type?: Primary client SDK type (single platform, backward compatible)553│ ├── client_platform_languages?: Per-platform languages (required when multi-platform, e.g. {"android":["kotlin"],"ios":["swift"]})554│ ├── client_language?: Client dev language (single platform, backward compatible)555│ ├── server_language?: Server dev language (only when server_only or both)556│ ├── project_id?: AE project ID (filled in Phase 3)557│ ├── host?: AE web address (filled in Phase 3)558│ ├── plan_name: Plan name559│ ├── lang: xlsx output language (zh/en/ja/ko), based on user's current language; controls generated xlsx headers/sheet names560│ ├── scenario: Business scenario description561│ ├── source_type: Source material type562│ ├── user_identity: User identity config563│ │ ├── account_id_source: Account ID source: user_account / role_id / none564│ │ ├── account_id_field?: Account ID field name (only when user_account, e.g. user_id / phone / email)565│ │ ├── distinct_id_strategy: Visitor ID strategy: auto / device_id / custom566│ │ └── distinct_id_custom_value?: Custom visitor ID value567│ └── business_dimension: Business dimension config (injected in Phase 1.3)568│ ├── revenue_model: Revenue model: IAA / IAP / mixed / subscription / commission569│ ├── core_loop: Core gameplay loop description570│ ├── functional_entries: Functional entry list571│ ├── currency_system: Currency system572│ ├── ad_scenes: Ad scenes (IAA / mixed only)573│ └── iap_items: IAP items (IAP / mixed only)574├── events: Event array, each with platform field575├── event_properties: Global event property pool (deduplicated)576├── common_event_properties: Common/super properties (attached to every event)577└── user_properties: User properties578```579580**SDK integration mode fields**:581582```json583// Multi-platform example (Android + iOS)584{585 "sdk_integration_mode": "both", // client_only / server_only / both586 "client_platforms": ["android", "ios"], // Required for multi-platform587 "client_platform_languages": { // Required for multi-platform; per-platform languages588 "android": ["kotlin"],589 "ios": ["swift"]590 },591 "server_language": "java" // Only when server_only or both592}593594// Single platform example (backward compatible)595{596 "sdk_integration_mode": "client_only",597 "client_sdk_type": "android", // Single platform598 "client_language": "kotlin" // Single platform599}600```601602**Event platform tag (`events[].platform`)**:603604```json605{606 "event_name": "order_create",607 "display_name": "Order Create",608 "platform": "server", // client / server / both609 "prop_names": ["order_id", "order_amount", "payment_method"],610 "source": "prd"611}612```613614- `platform: "client"` — Client-side upload (user behavior events)615- `platform: "server"` — Server-side upload (business data events)616- `platform: "both"` — Both sides upload (timestamps must be synced)617618**Property object format (`event_properties` / `common_event_properties` pool entries)**:619620```json621{622 "name": "order_amount",623 "display_name": "Order Amount",624 "type": "number",625 "desc": "Order total in cents",626 "source": "prd"627}628```629630> ⚠️ Field names: use `name` (NOT `prop_name`), `display_name`, `type`, `desc`, `source`. Events reference properties by `prop_names: ["order_amount", ...]` — this is an array of property `name` references (string array), NOT property objects.631632**User property format (`user_properties` pool entries)**:633634```json635{636 "name": "vip_level",637 "display_name": "VIP Level",638 "type": "number",639 "desc": "Current VIP level of the user",640 "source": "chat",641 "update_type": "user_set"642}643```644645> `update_type` is one of: `user_set` (overwrite), `user_setOnce` (first-set-only), `user_add` (numeric accumulate).646647**User identity fields (`meta.user_identity`)**:648649```json650{651 "account_id_source": "user_account", // Account ID source: user_account / role_id / none652 "account_id_field": "user_id", // Account ID field name (only when user_account)653 "distinct_id_strategy": "auto", // Visitor ID strategy: auto / device_id / custom654 "distinct_id_custom_value": null // Custom visitor ID value description (only when strategy=custom)655}656```657658**Property types** (enum): `string` / `number` / `bool` / `datetime` /659`object` (single object, with sub-properties) / `array_row` (object array, supports `parent.child` nesting) / `array_string` (string array)660661**Naming rules**: Event names / property names must be `snake_case`; use `display_name` field for human-readable names.662663### 1.2 Merge Source Materials664665Merge order: **existing_plan → template → codebase → prd → chat → autotrack**666667Earlier sources take precedence — same-name events keep the earlier version, later sources only add new events or merge `prop_names` without overwriting.668669- **existing_plan**: Already imported and validated in Phase 0 (see "Modify Existing Tracking Plan Flow"). Events are in draft.json as the baseline; each item marked `source: "existing_plan"`. Higher-priority sources supplement with new events only; same-name events keep the existing_plan version.670- **template**: User-selected industry template (see "Template Lookup Convention" below) as baseline; each item marked `source: "template"`671 - Templates are resolved by ae-cli from the ae-cli package root and user template directory672 - Import command: `AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json`673 - ⚠️ **Must validate immediately after template import** (see Phase 1.6); template content may not be fully correct674 - ⚠️ **Do not manually translate template content after import**: Do NOT read draft.json and model-translate `display_name`, `event_desc`, `event_tag`, or property `display_name`/`desc`. Keep imported business content as produced by the CLI/template reader unless the user explicitly asks for semantic rewriting.675 - ⚠️ **Use `src/tracking/i18n` for localization owned by the CLI**: `AE_LANG=<user_lang>` + `draft.meta.lang` control CLI messages, xlsx sheet names, xlsx headers, property type display values, and auto-track/i18n-owned labels. If these are wrong, inspect the existing translations under `src/tracking/i18n`, then regenerate with the intended locale instead of editing labels by hand.676 - ⚠️ **No model-invented translations for template labels**: When replacing or explaining a localized template-owned label, use the exact value from `src/tracking/i18n` resources. If no corresponding resource exists, preserve the template text and ask the user before changing semantics.677 - ⚠️ **event_tag is not free-form model translation**: Do not manually map `业务事件`/`系统事件` to another language. Preserve template tags, or rely on `src/tracking/i18n` and autotrack generation for system labels when the CLI owns them.678- **codebase**: Scan project source directory, extract events/properties from business logic; **same-name events merge prop_names without overwriting existing fields**; new items `source: "codebase"`679- **prd**: Read all user-provided product documents (md / pdf / docx / URL / images), extract events and properties from each file; **same-name events merge prop_names without overwriting existing fields**; image files analyzed via multimodal interpretation of UI elements and interaction flows; all new items `source: "prd"`680 - **prd path is a folder**: Recursively scan all files in the directory:681 - md/pdf/docx → read text content, extract events/properties682 - png/jpg/jpeg/webp → multimodal interpretation, analyze UI elements and interaction flows683 - subdirectories → recurse684 - other files → skip685 - **prd path is a URL**: Fetch URL content directly, process by the same rules above686- **chat**: Anchor phase business scenario + refine phase edit instructions, `source: "chat"`687- **autotrack**: Auto-inject SDK auto-track events based on `meta.client_sdk_type` (only for `client_only` or `both` mode), `source: "autotrack"`688689### 1.3 Inject Business Dimension Events690691Based on `meta.business_dimension` collected in Phase 0, inject corresponding events by the following rules.692693**Revenue model → Required events**:694695| Revenue Model | Injected Events | Description |696|---|---|---|697| `IAA` | `ad_show`, `ad_click`, `ad_reward_get` | Ad impression / click / reward claim |698| `IAP` | `payment`, `payment_fail` | Payment success / failure |699| `mixed` | All IAA + IAP events | |700| `subscription` | `subscription_start`, `subscription_renew`, `subscription_cancel` | Subscription start / renew / cancel |701| `commission` | `order_create`, `order_paid`, `commission_settled` | Order create / payment / commission settlement |702703**Core loop → Event sequence**:704705Parse node actions from user's `core_loop` description, map to events:706707Example: "Players repeatedly clear stages to earn coins, use coins to gacha for heroes"708→ Stage module: `stage_start` (stage begin), `stage_complete` (stage clear), `stage_fail` (stage fail)709→ Resource gain: `token_get` (coin gain, props: `token_type=diamond`, `token_amount`)710→ Gacha module: `gacha_draw` (gacha pull), `pool_type` (pool type), `draw_count` (draw count)711→ Hero gain: `hero_get` (hero acquired), `hero_id`712713**Functional entries → Module event groups**:714715| Functional Entry | Event Examples | Description |716|---|---|---|717| Stage | `stage_start`, `stage_complete`, `stage_fail`, `stage_id` | Stage start / complete / fail |718| Gacha | `gacha_draw`, `pool_type`, `draw_count`, `hero_get` | Gacha pull / pool / count / acquire |719| Shop | `shop_open`, `shop_buy`, `token_balance` | Shop open / buy / balance |720| Guild | `guild_join`, `guild_donate`, `guild_boss_start` | Guild join / donate / boss fight |721| Leaderboard | `rank_view`, `rank_refresh`, `rank_click` | Ranking view / refresh / click |722| Tasks | `task_accept`, `task_complete`, `task_reward_claim` | Task accept / complete / reward claim |723| Achievements | `achieve_unlock`, `achieve_reward_claim` | Achievement unlock / reward claim |724| Daily Check-in | `daily_sign`, `sign_reward_claim` | Daily sign-in / reward claim |725726**Currency system → Property design**:727728| Currency Type | Event | Properties |729|---|---|---|730| Hard currency (diamonds) gain | `token_get` | `token_type=diamond`, `token_amount`, `token_balance`, `source` |731| Soft currency (gold) gain | `token_get` | `token_type=gold`, `token_amount`, `token_balance`, `source` |732| Hard currency spend | `token_consume` | `token_type`, `token_amount`, `token_balance`, `consume_type` |733| Soft currency spend | `token_consume` | `token_type`, `token_amount`, `token_balance`, `consume_type` |734735**Injection rules**:7361. Business dimension events marked `source: "business_dimension"`7372. When merging with source material events, **same-name events keep the source material version, do not overwrite**7383. When revenue model is `none` (no monetization), skip revenue-related event injection739740### 1.4 Auto-inject SDK Auto-track Events741742Based on SDK integration mode collected in Phase 0, decide whether to inject auto-track events:743744**Injection conditions**:745- `sdk_integration_mode === "client_only"` → inject auto-track events746- `sdk_integration_mode === "both"` → inject auto-track events (client side only)747- `sdk_integration_mode === "server_only"` → **do NOT inject** (server SDKs have no auto-track)748- `sdk_integration_mode === "none"` → **do NOT inject** (no SDK; data ingestion via other methods)749750**Injection rules**:7511. **Only inject recommended events**; optional events are not auto-injected (prompted in Refine phase for optional enablement)7522. Auto-track events placed at the end of `events` array, marked `source: "autotrack"`7533. Auto-track event `event_tag` set to `"System Event"`7544. Auto-track events only carry preset properties (`prop_names` is empty or contains only preset property names)7555. Preset properties prefixed with `#` are not added to `event_properties` pool (auto-collected by SDK)7566. **Cleanup + Deduplication**: The CLI will:757 - **Remove** auto-track events inherited from templates or existing plans that don't match the user's selected SDKs. For example: if a template built for Android/iOS contains `ta_app_install`, `ta_app_start`, `ta_app_end` but the user selects JavaScript SDK, those `ta_app_*` events will be automatically removed since JavaScript SDK does not support them.758 - **Inject** the correct auto-track events for the user's selected SDKs.759 - **Deduplicate** by event name globally — won't inject events that already exist in the draft (correct auto-track events inherited from templates are kept).760761**SDK type → Recommended events** (see `references/autotrack-events.md` for details):762763| SDK Type | Recommended (auto-inject) | Optional (Refine prompt) |764|---|---|---|765| Android / iOS | `ta_app_install`, `ta_app_start`, `ta_app_end` | `ta_app_view`, `ta_app_click`, `ta_app_crash` |766| JavaScript | `ta_page_show`, `ta_page_hide` | `ta_pageview` |767| WeChat Mini-program | `ta_mp_launch`, `ta_mp_show`, `ta_mp_hide`, `ta_mp_view`, `ta_mp_share` | `ta_page_leave`, `ta_add_favorite`, `ta_mp_click` |768| WeChat Mini-game | `ta_mp_launch`, `ta_mp_show`, `ta_mp_hide` | — |769| Unity | `ta_app_install`, `ta_app_start`, `ta_app_end` | `ta_scene_loaded`, `ta_scene_unloaded` |770| Unity WeChat Mini-game | `ta_mg_launch`, `ta_mg_show`, `ta_mg_hide` | `ta_scene_loaded`, `ta_scene_unloaded` |771| Other game engines | `ta_app_install`, `ta_app_start`, `ta_app_end` | — |772773**Auto-track event purpose notes**:774- Auto-track events are the SDK's built-in auto-reporting mechanism; **you do not need to manually define same-name events**775- Example: JavaScript SDK's `ta_page_show` auto-collects page views; no need to define `home_page_show`, `about_page_show` etc.776- If templates already contain auto-track events (e.g. `ta_app_install` in industry templates), CLI will not inject duplicates777- These events require **enabling corresponding switches** during SDK initialization in the `ae-generate-tracking-code` phase778779**Draft JSON example**:780781```json782{783 "event_name": "ta_app_install",784 "display_name": "App Install",785 "event_desc": "Triggered on first app install; upgrades do not trigger; reinstall after deletion triggers",786 "event_tag": "System Event",787 "platform": "client",788 "prop_names": [],789 "source": "autotrack"790}791```792793**Note**: Auto-track event `platform` is always `"client"`, because only client SDKs have auto-track capability.794795### 1.5 Persist + Generate xlsx796797**Must write draft.json first, then run draft command. Do not skip this step and run ae-cli tracking plan draft directly.**798799- Save draft to `.ae-cli/draft.json`800- ⚠️ **Write `meta.lang`**: Set `draft.meta.lang` based on user's current language (`zh`/`en`/`ja`/`ko`), ensuring generated xlsx headers / sheet names / type values match the AE platform language801- **Must verify file was updated after writing** (check file modification time or content); only generate xlsx after confirming new content802- Generate upload-ready xlsx:803804```bash805AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx806```807808### 1.6 Rule Validation (must execute)809810Auto-validate during xlsx generation to ensure compliance with AE tracking plan rules:811812```bash813AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx --fix814```815816**Validation rules**:817818| Rule | Description | Auto-fix |819|---|---|---|820| Display name uniqueness | Within same property pool, `display_name` must not repeat | ✅ Add distinguishing prefix |821| Object array consistency | Same `array_row` across different events must have identical sub-properties | ✅ Fill missing sub-properties |822| snake_case | Event/property names must match `^[a-z][a-z0-9_]*$` | ❌ Manual fix needed |823| Property name uniqueness | Property names must not repeat | ❌ Manual fix needed |824| Event name uniqueness | Event names must not repeat | ✅ Remove later duplicates |825826**Validation flow**:8278281. CLI auto-validates draft.json8292. Fixable issues found → auto-fix → update draft.json → generate xlsx8303. Non-fixable issues found → error; manual fix of draft.json needed8314. No issues → proceed to Phase 1.7832833**Note**: Display names can be the same across different property pools (e.g. `vip_level` can be both an event property and a user property).834835> **Relationship to Phase 0 existing_plan validation**: The underlying rule engine is the same, but Phase 0 uses **interactive 3-tier** (Minor/Medium/Severe) because the user is present to confirm each fix. Phase 1.6 uses **batch 2-tier** (auto-fixable / manual-fix-needed) because it runs as part of the automated draft generation. Rules that are "Medium (needs confirmation)" in Phase 0 appear as "❌ Manual fix needed" here — the same rule, just without the interactive prompt.836837### 1.7 Show Summary838839Display to user via markdown table: event count / event property pool size / super property count / user property count; show deliverable paths.840841After displaying, tell user:842843```844Phase 1 complete.845Next: Phase 2 — Refine to confirm the plan.846```847848### 📁 Template Lookup Convention849850Run the following command to dynamically discover available templates:851852```bash853AE_LANG=<user_lang> ae-cli tracking plan list-templates --json854```855856**Language rules**: Template names and template business content must not be model-translated. Use localized names only when they are returned by the CLI or found in `src/tracking/i18n` resources. If `list-templates --json` only returns the original template `name`, display that name as-is and keep it unchanged for import. Before presenting or modifying any localized template-owned label, look it up in `src/tracking/i18n`; do not invent a translation.857858Built-in templates are resolved by ae-cli from the ae-cli package root. User templates are resolved from the ae-cli user template directory. Do **not** manually construct `./tracking-plan-template/...` paths from the user's current workspace.859860Search directories in order:8618621. `<ae-cli package root>/tracking-plan-template/` — bundled templates8632. `~/.ae-cli/templates/` — user-provided template directory864865Each template prefers `.md` distilled file (if same-name `.md` exists, return md path; otherwise return xlsx path).866Display the template names returned by the CLI, and keep the exact `name` from the JSON result for import. Auto-detect format on import:867868```bash869AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json870```871872---873874## Phase 2 — Refine (5-segment loop)875876> **Data path (`source_type = data`)**: skip this 5-segment loop entirely — use the single confirmation gate defined in "Data-path (source_type = data)" instead.877878In order, one conversation round per segment:8798801. **sdk_config (SDK config + User identity, combined)** — Show SDK integration mode, platform/language, visitor ID strategy, account ID source, corresponding SDK calls8812. **business (Business dimension + Business events, combined)** — Show revenue model, core loop, functional entries, injected event modules (grouped by platform)8823. **autotrack (Auto-track events)** — Show SDK auto-track events in a separate table, note enablement method8834. **common_props (Super properties)** — Show all super properties, note usage scenarios and considerations8845. **props (Event properties + User properties)** — Show event property pool grouped by event + user properties table885886Per-segment flow:8878881. Display corresponding section of current draft8892. Ask a segment-specific confirmation question. Always include the current segment number, current segment key, and next segment key:890 ```text891 Segment <n>/5 <segment_key> confirmed? Reply ok to continue to Segment <n+1>/5 <next_segment_key>, or describe changes.892 ```893 For Segment 5:894 ```text895 Segment 5/5 props confirmed? Reply ok to archive the plan and continue to Phase 3, or describe changes.896 ```8973. User gives natural language instructions → update `.ae-cli/draft.json` → re-run:898 ```bash899 AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx900 ```9014. User `ok` → proceed to next segment902903`ok` is a refine state-machine input, not a repeated-message error. If the user replies `ok` multiple times in a row, advance exactly one segment per `ok` in order. Before each confirmation prompt, print the new segment heading first, so consecutive confirmations do not look like the same question repeated.904905User may say **"Go back to segment N"** at any time to jump to any segment (N = 1-5).906907---908909### sdk_config (Phase 2 Segment 1)910911Show SDK integration config + user identity system:912913```914SDK Integration Config:915- Integration mode: <client_only / server_only / both / none>916- Client: <platform> (<language>)917- Server: <language>918919User Identity Config:920- Account ID source: <user_account / role_id / none>921- Account ID field: <specific field>922- Visitor ID strategy: <auto / device_id / custom>923924```925926User ok / modify.927928---929930### business (Phase 2 Segment 2)931932Show business dimensions + business events:933934```935Business Dimensions:936- Revenue model: <IAA / IAP / mixed / subscription / commission>937- Core loop: <description>938- Functional entries: <list>939- Currency system: <hard currency / soft currency>940941Injected Event Modules (grouped by platform):942943Client events (platform=client):944- <event>: <display_name> — <event_desc>945- ...946947Server events (platform=server):948- <event>: <display_name> — <event_desc>949- ...950951Both-platform events (platform=both):952- <event>: <display_name> — <event_desc>953```954955**Conflict detection**: If business dimensions contradict source materials, prominently flag for user confirmation.956957User ok / modify.958959---960961### autotrack (Phase 2 Segment 3)962963Only shown for `client_only` or `both` mode.964965Display SDK auto-track event list, with notes:966- These events are auto-collected by the SDK; **no manual track() calls needed** during code generation — just enable corresponding switches during SDK init967- `display_name` or `event_desc` can be adjusted; event names cannot be changed968969User ok / modify.970971---972973### common_props (Phase 2 Segment 4)974975Show all super properties (`name` / `display_name` / `type` / `desc`).976977Notes:978- Super properties are attached to every event; ideal for **business-wide global dimensions**979- Common super properties (by app type):980 - H5/Web: `channel` (source channel), `referrer_domain` (referring domain)981 - Mobile App: `channel`, `app_version`, `platform`982 - Game: `channel`, `vip_level`, `server_id`983 - Mini-program: `channel`, `scene`984- **Prohibited**: Do NOT set SDK preset properties (`#` prefix) as super properties985986User ok / modify.987988---989990### props (Phase 2 Segment 5)991992Show event property pool (grouped by event) + user properties table:993994- Event properties: `name` / `display_name` / `type` / `desc`, grouped by `event_tag`995- User properties: `name` / `display_name` / `type` / `update_type` / `desc`996997**User property update methods**:998| Update Method | Description | Use Case |999|---|---|---|1000| `user_setOnce` | Only set on first occurrence; subsequent updates ignored | First registration time, first payment time, first channel |1001| `user_set` | Overwrite update; always takes latest value | Current level, current balance, nickname, VIP status |1002| `user_add` | Numeric accumulation; suitable for cumulative values | Total recharge amount, total login days, total ads watched |10031004User ok → **immediately execute archive command**, then proceed to Phase 3.10051006---10071008### Refine Phase Heuristic Suggestions10091010- **Super properties vs Event properties**: Property appears on 3+ events → promote to super property; super properties are suitable for business-wide global dimensions (`channel`, `vip_level`, `ab_test_group`)1011- **Prohibited**: Do NOT set SDK preset properties (`#` prefix) as super properties1012- **Events must have properties**: Every event must have at least one semantically meaningful, describable property1013- **Nested properties**: `array_row` parent properties have `parent.child` sub-properties describing a group of objects10141015---10161017## Post-Phase 2 — Pre-delivery Self-check10181019**⚠️ Before uploading to AE, must complete the following self-check. Fix any issues before uploading.**10201021### Naming Convention Check10221023- [ ] Do event/property names start with a letter?1024- [ ] Do event/property names contain only letters, digits, and underscores (no Chinese, no spaces)?1025- [ ] Are there duplicate event names or synonymous events coexisting (e.g. `order_create` and `create_order`)?1026- [ ] Does the same property name map to multiple display names or types?1027- [ ] Does every event, event property, common event property, and user property have a non-empty `display_name` in the user's language?10281029### Revenue Model Required Events Check10301031| Revenue Model | Must Include Events | Check |1032|---|---|---|1033| IAA | `ad_show`, `ad_click`, `ad_reward_get` | [ ] |1034| IAP | `payment`, `payment_fail` | [ ] |1035| `mixed` | All IAA + IAP events | [ ] |1036| `subscription` | `subscription_start`, `subscription_renew`, `subscription_cancel` | [ ] |1037| commission | `order_create`, `order_paid`, `commission_settled` | [ ] |10381039### Paired Event Consistency Check10401041**Start/end paired events** (e.g. `battle_start`/`battle_end`) must carry **same-name, same-structure** object arrays:1042- Object array sub-properties reported by start event must be same name and same type in end event1043- Check: stage pairs (`stage_start`/`stage_complete`), battle pairs (`battle_start`/`battle_end`), gacha pairs (`gacha_draw`/`hero_get`), etc.10441045### Unit Description Check10461047- [ ] Are monetary fields annotated with unit (cents/USD)?1048- [ ] Are duration fields annotated with unit (seconds/milliseconds)?1049- [ ] Are balance fields annotated as post-recharge balance or pre-operation balance?10501051### Enum Value Check10521053- [ ] Are enum values listed in event description (≤ 10 values)?1054- [ ] For > 10 values, is there a note to use a dimension table?1055- [ ] Is the null-value fallback strategy documented (e.g. "unknown channel → use `unknown`")?10561057### Object Array Usage Check10581059Only use object arrays (`array_row`) when ALL THREE conditions are met; otherwise use object or plain properties:106010611. An event property has multiple same-type entities to record10622. Each entity needs ≥ 2 properties recorded10633. Entity count is variable10641065### Object Usage Check10661067Use object (`object`) when the following condition is met; distinguish from object arrays:10681069- **One-to-one** relationship → use `object`: e.g. user's current "equipment" details, player's "current deployed hero" (only one)1070- **One-to-many** relationship → use `array_row`: e.g. "backpack items" list, "lineup heroes" list (multiple)10711072Quick rule: **data shaped like `{...}` → use `object`; data shaped like `[{...}]` → use `array_row`**.10731074---10751076## Post-Phase 2 — Archive10771078After all 5 Refine segments are confirmed (user `ok` on Segment 5), **archive immediately; do not skip or delay**:10791080```bash1081AE_LANG=<user_lang> ae-cli tracking plan archive --draft .ae-cli/draft.json --xlsx .ae-cli/draft.xlsx --name "<plan_name>"1082```10831084| Parameter | Description | Example |1085|---|---|---|1086| `--draft` | draft.json path (required) | `.ae-cli/draft.json` |1087| `--xlsx` | draft.xlsx path (required) | `.ae-cli/draft.xlsx` |1088| `--name` | Plan name used as output filename prefix (required) | `"AI SaaS Website Tracking Plan"` |10891090Output lands at `plans/<date>-<plan_name>.xlsx`; `draft.json` is updated with `meta.archived_at`.10911092After archiving, tell user:10931094```1095✅ Archive complete1096File path: plans/<date>-<plan_name>.xlsx10971098Next: Phase 3 — Upload to AE:10991. Login to AE to get token11002. Get AE project ID11013. Upload plan to AE1102```11031104**⚠️ Hard rule**: Archive must complete before entering Phase 3. Before Phase 3.1's first question, must confirm `meta.archived_at` exists.11051106---11071108## Phase 3 — Token & projectId11091110At the start of Phase 3, tell user:11111112```1113## Phase 3 — Upload Preparation1114Next steps:11151. Check active AE host and login status11162. Login to AE to get token if needed11173. AE project ID1118```11191120### 3.1 Check Active AE Host and Login Status11211122Do not ask for the AE web address first. ae-cli stores an active AE host, and auth commands can use it directly.11231124First check current auth/host status:11251126```bash1127ae-cli auth status1128```11291130If an active host is configured, save that host to `.ae-cli/draft.json` `meta.host`. If `auth status` reports `authenticated: true`, skip login and continue to project ID.11311132Only if ae-cli reports no active host / no AE host configured, ask the user:11331134**"What is the AE web address?"**11351136After user responds, configure it and save the same value to `.ae-cli/draft.json` `meta.host`:11371138```bash1139ae-cli config set-host <host>1140```11411142If `auth status` reports unauthenticated, use the agent split-flow. Do **not** run blocking `ae-cli auth login` directly from an AI agent.11431144Step 1 — request an authorization URL and return control to the user:11451146```bash1147ae-cli auth login --no-wait1148```11491150Show the returned `verification_url` to the user and ask them to complete authorization. Keep the returned `device_code` for the next step.11511152Step 2 — after the user says authorization is complete, finish login:11531154```bash1155ae-cli auth login --device-code <device_code>1156ae-cli auth status1157```11581159Do not retry with `ae-cli auth login --host <host>` unless the previous command explicitly failed because no active host was configured. In that case, configure the host first, then restart the split-flow with `--no-wait`.11601161Common error tips and self-recovery:11621163| Error | Cause | What to Tell the User |1164|---|---|---|1165| `Device authorize request failed` | The agent runtime cannot reach the authorization service | Report that no device code was created and include the exact error |1166| `not_mac` | A legacy browser-token flow was attempted | Retry the split-flow device-code login; do not ask the user for browser tokens |1167| `NO_TAB_FOUND` | A legacy browser-token flow was attempted | Retry the split-flow device-code login; do not ask the user to open Chrome |11681169Token cached for 20 hours; same host avoids re-auth.11701171### 3.2 Get AE Project ID and Update Draft11721173Ask user: **"What is the AE project ID? Go to AE Admin → 'Project Settings' → 'Integration Config' → copy 'Project ID', or check the AE system URL parameter currentProjectId=<id>"**11741175After user provides projectId, update `.ae-cli/draft.json` `meta.project_id`.11761177---11781179## Phase 4 — Upload11801181At the start of Phase 4, tell user:11821183```1184## Phase 4 — Upload to AE1185Checking project's existing plan...1186```11871188### 4.1 Check Project's Existing Plan11891190Before uploading, check if the project already has a tracking plan:11911192```bash1193AE_LANG=<user_lang> ae-cli tracking plan fetch --project <projectId> > .ae-cli/existing-plan.json1194```11951196Do not add `--host` here unless the user explicitly provides a reachable override for this command. In agent sandboxes, ae-cli can resolve the request host from the sandbox-provisioned `cli-token.json`; passing a stale Kubernetes internal host can bypass that fallback.11971198**Result assessment**:1199- File empty or command error `404` → project has no plan; upload directly1200- File has content → project has an existing plan; show summary + **conflict detection**12011202**When existing plan exists, display**:1203```1204Project already has a tracking plan:1205- Events: XX1206- Event properties: YY1207- Super properties: ZZ1208- User properties: WW12091210Choose upload mode:12111. Append (keep existing plan, add new events/properties)12122. Replace (delete existing plan, upload new plan)12131214Append / Replace?1215```12161217---12181219### 4.2 Append Mode Conflict Detection12201221When user chooses "Append", **must detect conflicts** (AE merge-by-name has silent discard risk):12221223**Read two files**:1224- Existing plan: `.ae-cli/existing-plan.json`1225- New plan: `.ae-cli/draft.json`12261227**Detect two types of conflicts**:12281229#### Conflict Type A: Same-name property type mismatch (severe)12301231AE rule: Same-name properties must have the same type, otherwise reported data will be discarded.12321233**Detection logic**:12341235Compare `event_properties` / `common_event_properties` / `user_properties` three property pools:1236- For each property in the new plan, find same-name property in existing plan1237- If same name but different type → record as `property_type_conflict` (severe error)12381239**Conflict display**:1240```1241⚠️ Severe conflict: Same-name property type mismatch12421243The following properties have different types in the existing plan vs. new plan.1244Appending will cause reported data to be discarded:12451246| Property Name | Existing Type | New Plan Type |1247|---|---|---|1248| order_amount | number | string |1249| vip_level | string | number |12501251Suggestions:12521. Modify the new plan's property types to match the existing plan12532. Or choose "Replace" mode to redefine types12541255Continue append (without fixing) / Modify draft / Switch to replace?1256```12571258#### Conflict Type B: Same-name events (advisory)12591260AE merge-by-name: Same-name events are not overwritten; new-name events are added.12611262**Detection logic**:12631264For each event in the new plan, find same-name event in existing plan:1265- If same-name event exists → record as `event_exists` (advisory, not an error)12661267**Conflict display** (advisory only):1268```1269⚠️ Advisory: The following events already exist in the project (append mode will not overwrite)12701271- user_login (existing: 2 properties, new plan: 3 properties)1272- order_create (existing: 5 properties, new plan: 5 properties)12731274After append:1275- Existing event property associations will not change1276- New properties for existing events will not be added1277- New events will be added normally12781279Continue append? yes / no1280```12811282---12831284### 4.3 Upload Flow12851286Decide based on conflict detection results:12871288| Detection Result | Action |1289|---|---|1290| No conflicts | Upload directly |1291| Advisory only (Type B) | Upload after user confirmation |1292| Severe conflict (Type A) | User fixes or switches to replace |12931294Upload command:1295```bash1296AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]1297```12981299- **With `--replace`**: Delete existing project plan first then upload (when user chooses "Replace", or severe conflict switches to replace)1300- **Without `--replace`**: AE merge-by-name merge (no conflicts, or advisory only with user confirmation to append)13011302Upload commands MUST pass `--lang <user_lang>` explicitly. `--lang` must match the generated xlsx language and `draft.meta.lang`; `AE_LANG` is only used for CLI messages and xlsx regeneration context. Do not call AE user language config APIs and do not use `--switch-lang`. If the xlsx language is wrong, regenerate the xlsx with the intended language before uploading:1303```bash1304AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx1305AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]1306```13071308On successful upload, prompt user to verify in AE Admin. **Provide the full URL** (tracking plan page URL format: `https://<host>/#/data/plan`).13091310Then read the uploaded plan back through ae-cli and synchronize its display names to any event/property metadata1311that already exists in the project:13121313```bash1314AE_LANG=<user_lang> ae-cli tracking plan get --project-id <projectId> --host <host>1315AE_LANG=<user_lang> ae-cli tracking plan sync-display-names \1316 --project-id <projectId> \1317 --draft .ae-cli/draft.json \1318 --host <host>1319```13201321`sync-display-names` is intentionally safe to rerun:13221323- It fills only blank event/property metadata display names.1324- It never overwrites a non-empty display name already maintained in AE.1325- `missing_in_metadata` means that the event/property has not appeared in project metadata yet; it is not an upload failure.1326 Report those names and rerun the same command after the first Debug or production data reaches AE.1327- `missing_display_name_in_draft` means the generated plan is incomplete. Add the missing localized `display_name`,1328 regenerate/validate the xlsx, and rerun the upload/synchronization flow.13291330---13311332### 4.4 Upload Failure Handling and Auto-fix13331334Use `--auto-fix` option on upload (enabled by default); CLI auto-detects and fixes errors:13351336```bash1337AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]1338```13391340#### AE API Error Types13411342| Error Type | Description | Auto-fix |1343|---|---|---|1344| `event_prop_display_duplicate` | Event property display name duplicate | ✅ Add distinguishing prefix |1345| `complex_event_property_should_has_same_child_property` | Object array sub-property inconsistency | ✅ Fill missing sub-properties |1346| `event_name_duplicate` | Event name duplicate | ✅ Remove later duplicates |1347| `property_type_conflict` | Property type mismatch (append mode) | ❌ Switch to replace mode |13481349#### Auto-fix Flow13501351CLI auto-executes:13521. Upload xlsx to TE13532. Check if `eventErrorMap` has errors13543. Fixable errors → auto-fix draft.json → regenerate xlsx → re-upload13554. Loop up to 3 times; prompt user for manual intervention if exceeded13561357**Example output**:1358```1359🔧 Auto-fixing upload errors (attempt 1/3)...1360Fixed: Fixed object array sub-property inconsistency, Fixed display name duplicate1361[plan-upload] regenerated: .ae-cli/draft.xlsx1362```13631364---13651366### 4.5 Post-success Actions13671368After successful upload and display-name synchronization, prompt user to verify in AE Admin. **Provide the full URL**1369(tracking plan page URL format: `https://<host>/#/data/plan`). Include a short synchronization summary:1370updated counts, preserved existing counts, and any names still missing from project metadata.13711372**Ask about generating tracking code**:13731374The tracking plan has been uploaded successfully. Would you like to generate tracking code next?13751376- **Yes** → guide user to use the `ae-generate-tracking-code` skill1377- **No** → inform user of plan archive location: `plans/<date>-<plan_name>.xlsx`; can continue anytime13781379## Prohibitions13801381- Asking all anchor questions at once1382- Skipping Phase 3 and uploading directly1383- Manually assembling xlsx bypassing `.ae-cli/draft.json`1384- Translating "Super Property" as "超级属性" in any user-facing output (interaction prompts, plan summaries, event/property descriptions) — the correct AE Chinese term is "公共事件属性" or "公共属性"1385- Calling `fetch` AE API directly within the skill — all AE communication must go through project scripts / CLI13861387---13881389## Internal Reference (contributor use; not skill usage paths)13901391- `skills/ae-generate-tracking-plan/references/te-api.md` — AE backend endpoint capture documentation1392- `skills/ae-generate-tracking-plan/references/xlsx-schema.md` — xlsx format contract (writer rules + reader compatibility)1393- `skills/ae-generate-tracking-plan/references/autotrack-events.md` — SDK auto-track event definitions (per-platform event lists + SDK type mapping)1394- `skills/ae-generate-tracking-plan/references/business-dimension-mapping.md` — Business dimension → event/property mapping table (revenue model / functional entries / currency system → injected events)1395- `src/plan/types.ts` — Draft TypeScript type definitions