ae-generate-tracking-plan

ae-generate-tracking-plan

跨技能协作

当剩余工作超出此技能的范围，或需要其他能力作为必要前提时，请遵循协作协议。根据能力从本次运行中可用的技能里进行选择，保留已验证的上下文，并继续完成剩余任务。如果已加载此协议，请重复使用。

对话语言：本文档使用英语，但所有面向用户的输出都必须使用用户输入的语言。 英语输入 → 英语回复；中文输入 → 中文回复；日语输入 → 日语回复。 如无法确定，默认使用英语。 此要求适用于所有输出：章节标题、阶段名称、模板提示词、示例文本、选项列表等。 ⚠️ 严重：模板本地化由 CLI 负责。请勿使用模型手动翻译导入的模板内容。应将 AE_LANG=<user_lang>，设置 draft.meta.lang，并通过 ae-cli tracking code import-template / ae-cli tracking plan draft 重新生成，以 src/tracking/i18n 模块作为唯一依据。 更改任何由模板管理的本地化标签之前，请先在 src/tracking/i18n 中查找对应的译文（例如 resources/xlsx/sheets.ts、resources/xlsx/headers.ts、resources/xlsx/types.ts 和 resources/cli/*.json）。如果其中没有匹配的译文，请保留导入的文本，并在改写业务语义前征求确认。 除非是标识符、CLI 导入所需的模板名称，或为便于追溯而引用的原始素材，否则请勿将本文档中的中文文本原样复制到英语或日语回复中。

术语表

中文	English	备注
埋点方案	Tracking Plan	AE 项目级事件和属性定义
埋点模板	Tracking Plan Template	预先构建的行业／类型 xlsx 模板
方案名称	Plan Name	面向用户的方案标识符
应用场景	Application Scenario	用一句话描述应用的功能
素材来源	Source Material Type	prd / chat / codebase / template / data
数据样本 / 文件画像	Data Sample / File Profile	从 ae-data-integration 的 inspect profile（source_type: data）中获取的列→属性映射来源
业务维度	Business Dimension	收入模型、核心循环、功能入口、货币体系
收入模型	Revenue Model	IAA / IAP / 混合 / 订阅 / 佣金
核心循环	Core Loop	核心玩法循环（例如“刷关卡 → 获得金币 → 抽取英雄”）
功能入口	Functional Entry	关卡、商店、公会、排行榜、任务、成就等
货币体系	Currency System	硬通货（钻石）、软通货（金币）等
事件	Event	命名的用户操作或系统发生事项（event_name）
事件属性	Event Property	附加到事件上的数据（prop_names）
公共事件属性	Common/Super Property	自动附加到每个事件上的属性。⚠️ AE 的正确中文术语是“公共事件属性”或“公共属性”。切勿将“Super Property”翻译为“超级属性”——这不是有效的 AE 术语。
用户属性	User Property	用户个人资料中的属性（持久状态）
预置属性	Preset Property	以 # 为前缀的系统属性（#device_id、#time 等）
自动采集事件	Auto-track Event	SDK 自动采集的事件（ta_app_start、ta_page_show 等）
系统事件	System Event	为 SDK 自动采集事件（ta_*）保留的 event_tag 值。两种非模块标签之一（另一种是基础事件）。
基础事件	Basic	用于账号级生命周期／进度事件（注册、登录、升级、创建角色等）的 event_tag 值。与任何功能模块无关。
功能模块	Functional Module	用于特定功能业务事件的 event_tag 值；标识事件所属的模块（例如 Battle、Shop、Ads、Payment、Basic）
SDK 集成模式	SDK Integration Mode	client_only / server_only / both / none
客户端平台	Client Platform	Android、iOS、Web、Unity、小程序等
服务端语言	Server Language	Java、Python、Go、Node.js、PHP 等
用户体系	User Identity System	distinct_id 策略 + account_id 来源
访客 ID	Visitor ID / Distinct ID	登录前的匿名身份标识
账号 ID	Account ID	登录后的已识别用户标识
插入	Insert	将代码直接注入项目
片段	Snippet	以独立文件形式提供的代码
对象组	Object Array (array_row)	[{...}] — 可变长度的相关实体列表
对象	Object (object)	{...} — 结构固定的单个实体
校验	Validation	生成 xlsx 前检查草稿规则
上传	Upload	将埋点方案 xlsx 上传到 AE
追加	Append	向现有方案添加事件／属性
替换	Replace	删除现有方案并上传新方案
冲突检测	Conflict Detection	上传前检测类型不匹配和重复事件
归档	Archive	将最终版 draft.xlsx 复制到 plans/ 目录
xlsx 格式契约	xlsx Format Contract	生成兼容 AE 的 Excel 文件时遵循的列规则
draft.json	draft.json	埋点方案的内部中间表示（JSON）
display_name	Display Name	用户语言中的易读名称
event_tag	Event Tag	事件所属的功能模块（例如 Battle、Shop、Ads、Payment）。自动采集事件使用“System Event”。
snake_case	snake_case	规范命名格式：lowercase_with_underscores

触发时机

当用户提到“埋点方案 / 埋点模板 / AE 方案 / 帮我创建埋点”等内容时触发。 适用应用类型：H5 / Web / iOS / Android / 小程序 / Unity。严格遵循 阶段 0 → 1 → 2 → 3 → 4，不要跳过步骤。

阶段 1 / 3 / 4 通过 ae-cli tracking 命令行工具执行（ae-cli tracking plan draft / ae-cli auth login / ae-cli tracking plan upload / ae-cli tracking plan delete）。 所有 CLI 命令前都必须加上 AE_LANG=<user_lang>（例如：AE_LANG=en ae-cli tracking plan draft ...）， 以确保 CLI 输出消息和生成的 xlsx 表头与用户的语言一致。 上传命令还必须传入 --lang <user_lang>，以便服务器使用相同的工作表和表头语言解析上传的 xlsx。

语言规则：对于新生成的内容，draft.json 中面向用户的字段（display_name、event_desc、event_tag、 属性 display_name、属性 desc 等）应使用用户的输入语言生成。 每个事件、事件属性、公共事件属性和用户属性都必须有非空的 display_name。 规范的 snake_case 标识符不能代替面向用户的显示名称。 对于导入的模板，不要手动翻译这些字段。模板工作表名称、表头、属性类型显示值、CLI 消息以及自动埋点 / i18n 管理的标签，必须通过 AE_LANG=<user_lang> 和 draft.meta.lang 从 src/tracking/i18n 获取。 需要本地化标签时，请检查 src/tracking/i18n 并使用现有资源键 / 值；不要由模型自行翻译。 如果模板业务文本需要本地化，但 CLI / i18n 资源未提供相应内容，请保留导入的文本，并在改写业务含义前询问用户。 只有标识符字段（如 event_name、prop_name）保留英文。属性名称使用 snake_case；事件名称默认使用小写，只有用户要求保留原样时才使用大写。 此技能仅关注命令行为，不涉及内部实现。

---

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

步骤 1：初始化语言

根据用户的输入语言确定 <user_lang>：中文→zh、英文→en、日文→ja、韩文→ko。其他语言默认使用 en。 后续所有 CLI 命令前都必须加上 AE_LANG=<user_lang>，以确保 CLI 输出和生成的 xlsx 表头与用户的语言一致。 上传 xlsx 时，也要传入 --lang <user_lang>；它必须与 draft.meta.lang / 生成的 xlsx 语言一致。

按顺序收集以下5 项，不要一次全部询问：

项目 1 — 应用场景

询问：“你的应用业务场景是什么？请用一句话概括，例如：一个供用户浏览商品并下单的电商网站。”

用户回答后，记录到 meta.scenario 并生成 meta.plan_name。

项目 2 — 素材来源 + 业务维度（合并询问）

询问前，判断当前运行环境是否为 Agent 沙箱。Agent 可以根据运行环境信息进行判断，例如沙箱中提供的 cli-token.json、受限的文件系统访问权限，或缺少用户的本地文件。不要仅为了判断沙箱可见性而询问用户。

在沙箱环境中，只有沙箱工作区内可读取的文件（包括用户附加 / 上传到对话工作区的文件）才可作为产品文档。无法读取沙箱外任意本地路径中的文件，除非这些文件已挂载或附加。代码库属于本地素材选项，在沙箱环境中必须隐藏，除非代码库已存在于可读取的工作区中。隐藏选项时，请从 1 开始连续重新编号可见列表；不要显示跳过的编号。

如果不在沙箱环境中，请原样询问：

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/xlsx/pptx/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).

如果在沙箱环境中，请原样询问：

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/xlsx/pptx/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).

不要将此源材料列表改写为无编号的项目符号、卡片或散文。用户必须能够使用可见编号进行回复。 翻译此提示词时，必须原样保留数字前缀和换行。每个可见选项都必须单独占一行，并且必须以 1 -、2 -、3 - 等开头。绝不要将两个带编号的选项放在同一段落或视觉行中。如果 Markdown 渲染器可能会合并软换行，请使用 Markdown 硬换行（在换行符前添加两个尾随空格），而不是空行。翻译只能更改选项文本，不能更改编号前缀或每行一个选项的结构。

用户可以多选（最多 2 项）。请根据向用户显示的可见列表解读数字，而不是根据非沙盒规范列表。

规范源材料选项（非沙盒编号）：

1. 产品文档 ****(****本地路径、沙盒工作区路径、上传的附件、URL、图像文件或文件夹) — 从产品文档中提取事件和属性；支持 md/pdf/docx/xlsx/pptx/URL/图像（png/jpg/jpeg/webp）
2. 详细描述（对话形式）— 描述应用业务流程、核心功能、用户行为、变现模式等。
3. 代码库（本地项目路径；在沙盒中隐藏）— 分析源代码以提取事件和属性
4. 预构建模板（内置行业和游戏类型模板）— 选择内置模板（运行 AE_LANG=<user_lang> ae-cli tracking plan list-templates --json 查看可用模板）

根据用户的选择，确定源材料类型并记录到 meta.source_type：

选择	source_type	处理方式
仅产品文档	prd	阅读产品文档（文本/图像），提取事件和属性
仅详细描述	chat	根据描述在草稿阶段构建事件
仅代码库	codebase	扫描源代码，从业务逻辑中提取事件/属性
仅模板	template	提供内置模板选择
仅现有方案	existing_plan	将 xlsx 导入为基准（参见下文“修改现有埋点方案流程”）
仅数据样本	data	读取 inspect profile（ae-local-data-profile/v1），将列映射到事件/属性（参见下文“数据路径（source_type = data）”）
任意两项组合	将两种类型用 _ 连接	第一项作为基准，第二项作为补充（优先级：existing_plan → template → codebase → prd → chat）
现有方案 + 预构建模板	不允许	两者都会提供事件基准；存在语义冲突
数据样本 + 任何其他选项	不允许	数据样本是独立的单一来源路径

后续问题（按照下文“多源组合规则”中定义的后续问题顺序提问）：

• 产品文档 → 如果不在沙盒环境中，请严格按以下内容提问：

  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
  

• 产品文档 → 如果在沙盒环境中，请严格按以下内容提问：

  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.
  

• 详细描述 → 如果过于模糊，请追问核心功能、用户行为、业务流程和变现方式
• 代码库 → 请询问 “项目目录路径是什么？”，然后扫描源代码以提取业务逻辑
• 预构建模板 → 显示匹配的模板供用户确认
• 修改现有埋点方案 → 请询问 “请提供现有埋点方案的 xlsx 文件路径”，然后按照下文的流程操作
• 数据样本 → 请询问 “请提供 inspect profile JSON 的路径（或包含该文件的运行目录）”，然后读取 ae-local-data-profile/v1 产品，并按照下文“数据路径（source_type = data）”流程操作

修改现有埋点方案流程（用户选择此选项时）：

1. 导入：询问用户文件路径，然后立即导入：

   AE_LANG=<user_lang> ae-cli tracking code import-template --template <path> --out .ae-cli/draft.json
   

2. 检查结果：

   • 如果 CLI 报错（文件不存在／解析失败）→ 报告错误，要求用户修复文件后重试
   • 如果 draft.json 的 events 数组为空 → 🛑 严重：未找到 AE 格式的工作表（缺少以 # 为前缀的工作表，例如 #事件数据）。告知用户该文件似乎不是 AE 埋点方案 xlsx 文件。用户必须修复原始文件并重新导入。

3. 内容验证（当 events 非空时）：

   AE_LANG=<user_lang> ae-cli tracking plan validate --in .ae-cli/draft.json --fix
   

4. 按严重程度处理验证结果：

   • 如果验证通过且没有任何问题 → 跳至步骤 5。

   严重程度	示例	处理方式	用户操作
   🔧 轻微（可自动修复）	display_name 重复、array_row 子属性不一致、事件名称重复	--fix 自动修复并写入 draft.json。告知用户已修复的内容。	无（告知即可）
   ⚠️ 中等（需要确认）	属性名称不符合 snake_case 规范、属性名称重复、属性类型无效、嵌套属性的父属性不是复合类型	列出每个问题的当前值 → 建议修复方案。写入 draft.json 前，逐项征得用户确认。	确认每项修复
   🛑 严重	文件无法解析，或导入后 events 数组为空	拒绝处理。告知用户具体问题。用户修复原始文件并重新导入。	修复原始文件

   中等问题的确认格式：

   ⚠️ The following content needs to be fixed:
   
   | # | Issue | Location | Current | Suggested |
   |---|-------|----------|---------|------------|
   | 1 | snake_case | event_name | UserLogin | user_login (keep UserLogin only if the user asked to preserve case) |
   | 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 → 将所有建议的修复应用到 draft.json
   • specify per item → 逐项确认
   • skip → 保留当前值，在后续的优化阶段处理

   ⚠️ 绝不要修改用户的原始 xlsx 文件。 所有更改都写入 draft.json。

5. 修复后重新验证 → 循环执行，直到没有问题，然后继续下一个后续问题（如果与其他来源材料结合使用），或进入第 3 项（如果 existing_plan 是唯一来源）。

代码库分析流程（当 source_type 包含 codebase 时）：

1. 用户提供项目目录路径
2. 扫描目录结构，识别技术栈（引擎／框架／语言）
3. 阅读核心业务模块（游戏逻辑、场景管理、UI 交互、状态／数据模型、网络／支付等）
4. 从代码中提取：
   • 事件：玩家交互操作（点击／滑动／触发）、场景切换、游戏状态变化（开始／暂停／结束）、业务流程节点（购买／升级／解锁）
   • 事件属性：操作参数（子弹类型／敌人等级／物品 ID）、状态值（分数／HP／金币）、上下文（关卡 ID／难度／模式）
   • 用户属性：持久化状态（等级／经验／VIP／累计消费）
5. 将提取结果映射到 AE 命名规范（事件名称默认小写，仅在用户要求时使用大写；属性名称使用 snake_case；display_name 使用用户所用语言）
6. 与用户确认提取结果，并补充缺失项

业务维度确认：

确认来源材料后，必须根据 source_type 处理业务维度信息。继续之前必须获得用户明确确认。

source_type	处理方式
template	直接展示模板继承的业务维度；跳过详细推断
existing_plan	根据现有方案内容推断业务维度（分析事件模块、支付事件、货币属性）；跟进缺失项；预览事件注入
prd / codebase / chat	推断业务维度 → 跟进缺失项 → 预览事件注入
组合来源（例如 template_prd）	参见下方详细规则——以基准来源的处理方式为主，补充来源提供额外上下文

如果 source_type 为 template 或以 template_ 开头（包括 template、template_prd、template_codebase、template_chat）：

展示模板预设的业务维度：

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

• 用户回复 ok → 进入下一步
• 用户回复“修改” → 切换到 prd/chat 流程，供用户补充信息
• 对于组合场景（例如 template_prd）：确认模板维度后，同时记录 prd/chat 中的补充见解，作为 Phase 1.2 的上下文。

如果 source_type 包含 existing_plan：

根据导入的计划内容推断业务维度：

1. 分析现有事件：检查 event_tag 值以识别功能模块（例如，标记为“战斗”的事件 → 战斗模块）。检查事件名称中与付费/广告相关的模式，以推断营收模式。
2. 展示推断结果：将推断结果格式化为摘要：

   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
   

3. 跟进缺失信息：仅询问无法推断的项目
4. 事件注入预览：展示建议注入的事件模块（仅添加计划中尚不存在的事件）；用户回复 ok 后继续

• 对于组合场景（例如 existing_plan_prd）：确认计划中的维度后，同时记录 prd/chat 中的补充见解，作为 Phase 1.2 的上下文。

如果 source_type 为 prd / codebase / chat：

1. 展示推断结果：使用 business-dimension-mapping.md 作为映射基准，将推断结果格式化为摘要
2. 跟进缺失信息：仅询问缺失项目或推断为“简单”的项目
3. 事件注入预览：展示建议注入的事件模块；用户回复 ok 后继续

平台验证：使用 business-dimension-mapping.md 第 5 章中的判定规则，检查注入事件的平台分配是否合理。

模板匹配（适用于 prd / codebase / chat 场景，可选；不适用于 existing_plan 或 template 场景）：

确认业务维度后，根据应用类型自动检测匹配的模板：

AE_LANG=<user_lang> ae-cli tracking plan list-templates --json

向用户展示匹配的模板以供确认。已确认的模板将作为基线，并参与 Phase 1 的事件合并。

多来源组合规则（用户选择 2 个来源材料时）

后续提问顺序（第 0 阶段提问顺序）：

不要按用户的选择顺序进行。请改用以下顺序：

existing_plan（blocking validation, always first）→ codebase/prd（user's selection order）→ chat → template

原因：

• existing_plan 必须排在首位——导入和验证可能需要用户修复文件；尽早处理可避免浪费上下文
• codebase / prd——直接反映实际业务需求，优先级高于通用描述和模板
• chat——对话式描述，用于补充业务背景
• template——通用行业模板，与用户业务的关联最小

来源材料主要在第 1.2 阶段（合并来源材料）处理。唯一例外是 existing_plan：它会在第 0 阶段导入并验证，因为用户提供的文件可能需要先修复才能继续。所有其他来源均按标准流程在第 1.2 阶段处理。

合并优先级（第 1.2 阶段）：existing_plan → template → codebase → prd → chat → autotrack 靠前的来源优先——同名事件保留较早来源的版本，后续来源只会添加新事件或合并 prop_names，不会覆盖已有内容。

业务维度推断（组合场景）：

以基准来源的推断方法为主。补充来源（尤其是 prd/chat）可以提供额外信息——向用户展示合并后的视图以供确认。

有效组合：

“基准来源”列指出哪个来源具有更高的合并优先级（参见第 1.2 阶段的合并顺序），这可能与用户的选择顺序不同。后续提问请遵循上述“多来源组合规则”中的固定顺序，而不是用户的选择顺序。

基准来源	补充来源	补充来源的第 0 阶段处理
existing_plan	codebase	收集路径 + 快速检测技术栈
existing_plan	prd	收集路径
existing_plan	chat	收集描述；参与维度推断
template	codebase	收集路径 + 快速检测技术栈；模板匹配/导入延迟至第 1.2 阶段
template	prd	收集路径；模板匹配/导入延迟至第 1.2 阶段
template	chat	收集描述
codebase	prd	收集路径
codebase	chat	收集描述
prd	chat	收集描述
codebase	template	与上方 template+codebase 行相同（根据合并优先级，template 是基准来源）
prd	template	与上方 template+prd 行相同（根据合并优先级，template 是基准来源）

禁止：existing_plan + template（两者都提供事件基线；语义冲突）。

将业务维度信息记录到 meta.business_dimension：

"business_dimension": {
  "revenue_model": "<model>",
  "core_loop": "<description>",
  "functional_entries": ["<entry list>"],
  "currency_system": { ... },
  "ad_scenes": [],
  "iap_items": []
}

数据路径（source_type = data）——精简的单确认关卡流程

当用户选择数据样本 / 文件概况选项（source_type = data）时，流程将偏离标准的 5 项锚点。此路径会将表格列映射为事件/属性，而不是根据业务理解构造事件，并使用单个确认关卡，而不是 5 段式 Refine 循环。

跳过的内容（仅收集第 1 项——应用场景和第 2 项——数据样本）：

• 第 3 项（SDK 集成配置） → 跳过。meta.sdk_integration_mode = "none"（通过 RESTful / LogBus / DataX 接入数据，不使用 SDK）。不会注入 SDK 自动追踪事件（第 1.4 阶段已跳过 none）。
• 第 4 项（用户身份系统） → 跳过访客 ID 策略问题。改为根据检查概况中的 identity_candidates 推导 meta.user_identity（例如 distinct_id / account_id 列）；存在账户列时，account_id_source: "user_account"，否则为 "none"。
• 业务维度确认 → 跳过。映射由列驱动，而非由收入模式 / 核心循环驱动。meta.business_dimension 保持为空。

草稿构建（在数据路径中取代第 1.1/1.2/1.3 阶段）：

1. 读取检查配置文件：读取 ae-local-data-profile/v1 JSON 产品（列 / 类型 / 样例 / UE 适用性 / 映射置信度）。如果该文件不存在或已过时，请先对源文件重新运行 ae-cli data-integration inspect。
2. 确定事件模型（复用 UE 路由）：单表单事件 track / 单表多事件（事件名称列）/ 单表 user_set / 混合。Agent 可以提议将一个表拆分为多个事件（例如，按 campaign_type 将广告表拆分为 ad_show / ad_click）；此类提议必须在确认环节中确认。
3. 列 → 属性映射草案：
   • 首先识别系统列：时间字段、distinct_id / account_id、事件名称列、用户属性名称列。
   • 将其余列映射为事件属性 / 用户属性 / 公共属性。
   • 命名：属性名称使用 snake_case，事件名称默认使用小写（仅在用户要求时使用大写）+ display_name + desc + event_tag（语言遵循用户输入）。
   • 类型推断：CSV 列默认为 string；根据字段名称 + 值分布 + 业务文档 / 提示词先验推断 number / bool / datetime / 枚举。不确定或冲突的列标记为“待确认”，并仅在确认环节中询问（不要提前逐列询问）。
4. 单次确认环节（替代第 2 阶段，见下文）。
5. 与现有计划合并（复用第 4.1 / 4.2 阶段的冲突检测）。
6. 持久化：.ae-cli/draft.json → xlsx → 上传（sdk_integration_mode = none）。

单次确认环节（一轮，一张汇总表）：

在一条消息中展示一张包含以下所有内容的合并表，然后等待用户回复一次：

• 事件列表：event_name / display_name / desc / event_tag / platform。
• 属性列表：name / display_name / type / desc / source，并突出显示不确定的类型（标记为“待确认”）。
• 字段范围：默认仅包含计划内部字段；提供一个完整导入开关，用于导入所有源列。
• 无法识别 / 脏数据的处理方式：如何处理未映射的列、空值和无法解析的行。
• 同名属性类型冲突：在确认环节中就地标出（见第 4.2 阶段 A 类）。

用户只回复一次：ok（全部接受），或提出指定修改——重命名 / 重新设定类型 / 添加 / 移除单个列或事件。确认环节完成后，直接进入第 3 阶段（项目令牌），然后进入第 4 阶段（合并 + 上传）；不要进入 5 段式 Refine 循环。

dry-run 模式：

用户请求 dry-run（或调用方传入 data-integration plan --dry-run）时，仅生成草案预览 + 列→属性映射摘要：

• 展示单次确认环节表格（事件 + 属性 + 字段范围 + 无法识别数据的处理方式）和映射结果，但不要写入 .ae-cli/draft.json。
• 不要生成 xlsx，不要归档到 plans/，也不要上传到 AE。
• 明确说明尚未持久化任何内容；用户之后可以批准正式运行。

条目 3 — SDK 集成配置（客户端 + 服务端）

询问：“您的客户端平台是什么？（可多选，例如 Android + iOS）是否要集成服务端 SDK？”

询问此条目 3 的问题后，停止并等待用户回答。不要在同一条回复中显示条目 4。

语言筛选：以下 SDK 仅提供中文文档，只对中文用户显示：Mini-program、Mini-game、OpenHarmony、LayaAir、Egret、Cocos2d-Lua。不要向非中文用户显示这些选项。

客户端集成（可多选）：

选项	客户端 SDK 类型
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（统一版，支持微信/QQ/TikTok/Baidu 等）
Mini-program	Mini-program SDK（统一版，支持微信/TikTok/Alipay/Baidu 等）
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	无（sdk_integration_mode: "server_only"）

编程语言（仅适用于 Android / iOS SDK）：

SDK 类型	支持的语言
Android SDK	Java / Kotlin（可多选）
iOS SDK	Objective-C / Swift（可多选）
其他 SDK	语言固定，无需选择

后续问题：选择 Android SDK → 询问 “使用哪种编程语言？Java / Kotlin / 两者都用” 后续问题：选择 iOS SDK → 询问 “使用哪种编程语言？Objective-C / Swift / 两者都用”

记录到 client_platform_languages：

"client_platform_languages": {
  "android": ["java", "kotlin"],
  "openharmony": ["typescript"]
}

⚠️ 多平台元字段规则：当选择 ≥2 个客户端平台时，Draft 元数据必须使用 client_platforms（数组）+ client_platform_languages（字典）。不要只使用 client_sdk_type（单个值）+ client_language（单个值），否则只能记录一个平台。单平台场景使用 client_sdk_type + client_language。

服务端集成：

选项	服务端 SDK 类型	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
其他	追问具体语言；查看 wiki 确认是否提供 SDK	both
无服务端 SDK	无	client_only 或 none

SDK 集成模式自动检测：

客户端集成	服务端集成	sdk_integration_mode
是	是	both
是	否	client_only
否	是	server_only
否	否	none（RESTful / LogBus / DataX 数据接入）

none 模式：适用于历史数据导入、批量数据同步、第三方系统集成等。Refine 阶段不会注入 SDK 自动采集事件。

条目 3 确认环节：

用户回答条目 3 后，规范化 SDK 配置，并且只询问缺失的后续问题（Android/iOS 编程语言或 Other 服务端语言）。

然后总结规范化后的 SDK 配置，并询问：“确认此 SDK 集成配置吗？回复 ok 继续条目 4，或描述需要的修改。”

在用户明确确认此 SDK 集成配置之前，不要显示条目 4，也不要询问身份问题。

条目 4 — 用户身份系统（访客 ID + 账号 ID 组合）

询问：“访客 ID 的生成策略是什么？”

选项：

• auto — SDK 自动生成（默认，适用于大多数场景）
• device_id — 使用设备 ID（iOS IDFV / Android AndroidID）
• custom — 自定义访客 ID（必须在 SDK 初始化后立即调用 identify()）

后续问题：选择 custom → 询问 “访客 ID 应使用什么值？例如：设备 ID / UUID / 临时访客 ID”

---

询问：“账号 ID 的来源是什么？”

选项：

• user_account — 用户账号 ID（登录后唯一的标识符）
• role_id — 角色 ID（适用于游戏；一个账号可以有多个角色）
• none — 无账号系统（纯访客模式）

后续问题：

• 选择 user_account → 询问 “账号 ID 的具体值是什么？例如：user_id（用户 ID）、phone（电话号码）、email（电子邮件地址）”
• 选择 role_id → 说明 “角色 ID 适用于游戏——一个账号可以创建多个角色，从而实现更细粒度的角色行为分析”

记录到 meta.user_identity：

---

阶段 1 — 草稿

1.1 构建规范草稿

草稿概念结构（内部 JSON；用户不会直接查看）：

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 集成模式字段：

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

事件平台标签（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" — 客户端上传（用户行为事件）
• platform: "server" — 服务端上传（业务数据事件）
• platform: "both" — 双端上传（时间戳必须同步）

属性对象格式（event_properties / common_event_properties 池条目）：

{
  "name": "order_amount",
  "display_name": "Order Amount",
  "type": "number",
  "desc": "Order total in cents",
  "source": "prd"
}

⚠️ 字段名称：使用 name（而非 prop_name）、display_name、type、desc、source。事件通过 prop_names: ["order_amount", ...] 引用属性——这是属性 name 引用的数组（字符串数组），不是属性对象。

用户属性格式（user_properties 池条目）：

{
  "name": "vip_level",
  "display_name": "VIP Level",
  "type": "number",
  "desc": "Current VIP level of the user",
  "source": "chat",
  "update_type": "user_set"
}

update_type 取值为：user_set（覆盖）、user_setOnce（仅首次设置）、user_add（数值累加）、user_append（数组追加）。

用户身份字段（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)
}

属性类型（枚举）：string / number / bool / datetime / object（单个对象，带子属性）/ array_row（对象数组，支持 parent.child 嵌套）/ array_string（字符串数组）

命名规则：属性名称必须使用 snake_case；事件名称默认使用小写，只有用户要求保留大写时才保留。使用 display_name 表示便于阅读的名称。

1.2 合并来源材料

合并顺序：existing_plan → template → codebase → prd → chat → autotrack

较早的来源优先级更高——同名事件保留较早版本，较晚的来源只添加新事件或合并 prop_names，不覆盖现有内容。

• existing_plan：已在阶段 0 导入并验证（参见“修改现有跟踪计划流程”）。事件在 draft.json 中作为基线；每项都标记为 source: "existing_plan"。优先级更高的来源仅补充新事件；同名事件保留 existing_plan 版本。
• template：用户选择的行业模板（参见下文“模板查找约定”）作为基线；每项都标记为 source: "template"
  • ae-cli 会从 ae-cli 包根目录和用户模板目录解析模板
  • 导入命令：AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json
  • ⚠️ 模板导入后必须立即验证（参见阶段 1.6）；模板内容可能并不完全正确
  • ⚠️ 导入后不要手动翻译模板内容：不要读取 draft.json 并使用模型翻译 display_name、event_desc、event_tag 或属性 display_name/desc。除非用户明确要求进行语义改写，否则保留 CLI/模板读取器生成的导入业务内容。
  • ⚠️ CLI 管理的本地化内容使用 src/tracking/i18n：AE_LANG=<user_lang> 和 draft.meta.lang 控制 CLI 消息、xlsx 工作表名称、xlsx 表头、属性类型显示值以及自动跟踪/i18n 管理的标签。如果这些内容不正确，请检查 src/tracking/i18n 下现有的翻译，然后使用预期的区域设置重新生成，而不是手动编辑标签。
  • ⚠️ 不要由模型臆造模板标签的翻译：替换或说明由本地化模板管理的标签时，请使用 src/tracking/i18n 资源中的确切值。如果没有对应资源，请保留模板文本，并在更改语义前询问用户。
  • ⚠️ event_tag 不是可自由翻译的内容：不要手动将 业务事件/系统事件 映射为其他语言。保留模板标签；或者在 CLI 管理系统标签时，依赖 src/tracking/i18n 和 autotrack 生成。
• codebase：扫描项目源代码目录，从业务逻辑中提取事件/属性；合并同名事件的 prop_names，不覆盖现有字段；新项标记为 source: "codebase"
• prd：读取用户提供的所有产品文档（md / pdf / docx / xlsx / pptx / URL / 图片），从每个文件中提取事件和属性；合并同名事件的 prop_names，不覆盖现有字段；通过多模态解读分析图片文件中的 UI 元素和交互流程；所有新项标记为 source: "prd"
  • 按照下表读取各种格式。 优先使用首选工具；若工具缺失，则回退到其他工具，不要因此放弃读取。

    格式	读取方式
    md	直接读取
    docx	pandoc -t markdown <file>；回退使用 markitdown <file>（缺少时执行 pip install markitdown）；最后使用 unzip -p <file> word/document.xml 并读取文本
    pdf（文本）	提取文本（原生 Read 或 PDF 文本提取器）
    pdf（扫描件）	将页面渲染为图片，然后使用视觉能力读取
    xlsx	使用保留结构的读取器（openpyxl / pandas，缺少时执行 pip install）读取行/列；跟踪表的行列布局承载着含义——不要依赖扁平化的 markdown 导出内容
    pptx	使用 markitdown <file>（缺少时执行 pip install markitdown）
    png/jpg/jpeg/webp	通过多模态解读分析 UI 元素和交互流程

  • xlsx 是第三种源材料路径，与现有的两种 xlsx 流程不同。 人类可读的跟踪表（事件/属性/类型行）在此处逐行读取。AE 格式的跟踪计划 xlsx 通过 import-template 处理；CSV/Excel 数据样本通过数据路径（ae-cli data-integration inspect）处理。不要将其中一种文件送入另一种流程。
  • prd 路径是文件夹：递归扫描目录中的所有文件：
    • md/pdf/docx/xlsx/pptx → 按照上表读取并提取事件/属性
    • png/jpg/jpeg/webp → 通过多模态解读分析 UI 元素和交互流程
    • 子目录 → 递归处理
    • 其他文件 → 跳过
  • prd 路径是 URL：直接获取 URL 内容，并按照上述相同规则处理
• chat：锚定阶段的业务场景 + 优化阶段的编辑说明，标记为 source: "chat"
• autotrack：根据 meta.client_sdk_type 自动注入 SDK 自动跟踪事件（仅限 client_only 或 both 模式），标记为 source: "autotrack"

1.3 注入业务维度事件

根据第 0 阶段收集的 meta.business_dimension，按以下规则注入相应事件。

营收模式 → 必需事件：

营收模式	注入的事件	描述
IAA	ad_show、ad_click、ad_reward_get	广告展示 / 点击 / 领取奖励
IAP	payment、payment_fail	支付成功 / 失败
mixed	所有 IAA + IAP 事件
subscription	subscription_start、subscription_renew、subscription_cancel	订阅开始 / 续订 / 取消
commission	order_create、order_paid、commission_settled	创建订单 / 支付 / 佣金结算

核心循环 → 事件序列：

从用户的 core_loop 描述中解析节点操作，并映射为事件：

示例：“玩家反复通关关卡以获得金币，再用金币抽取英雄” → 关卡模块：stage_start（开始关卡）、stage_complete（通关）、stage_fail（关卡失败） → 资源获取：token_get（获得金币，属性：token_type=diamond、token_amount） → 抽卡模块：gacha_draw（抽卡）、pool_type（卡池类型）、draw_count（抽取次数） → 英雄获取：hero_get（获得英雄）、hero_id

功能入口 → 模块事件组：

功能入口	事件示例	描述
关卡	stage_start、stage_complete、stage_fail、stage_id	开始 / 通关 / 失败
抽卡	gacha_draw、pool_type、draw_count、hero_get	抽卡 / 卡池 / 次数 / 获取英雄
商店	shop_open、shop_buy、token_balance	打开商店 / 购买 / 余额
公会	guild_join、guild_donate、guild_boss_start	加入公会 / 捐献 / 挑战首领
排行榜	rank_view、rank_refresh、rank_click	查看 / 刷新 / 点击排行榜
任务	task_accept、task_complete、task_reward_claim	接取 / 完成任务 / 领取奖励
成就	achieve_unlock、achieve_reward_claim	解锁成就 / 领取奖励
每日签到	daily_sign、sign_reward_claim	每日签到 / 领取奖励

货币系统 → 属性设计：

货币类型	事件	属性
硬通货（钻石）获取	token_get	token_type=diamond、token_amount、token_balance、source
软通货（金币）获取	token_get	token_type=gold、token_amount、token_balance、source
消耗硬通货	token_consume	token_type、token_amount、token_balance、consume_type
消耗软通货	token_consume	token_type、token_amount、token_balance、consume_type

注入规则：

1. 业务维度事件标记为 source: "business_dimension"
2. 与源材料中的事件合并时，同名事件保留源材料中的版本，不要覆盖
3. 营收模式为 none（无变现）时，跳过营收相关事件的注入

1.4 自动注入 SDK 自动跟踪事件

根据 Phase 0 收集的 SDK 集成模式，决定是否注入自动跟踪事件：

注入条件：

• sdk_integration_mode === "client_only" → 注入自动跟踪事件
• sdk_integration_mode === "both" → 注入自动跟踪事件（仅客户端）
• sdk_integration_mode === "server_only" → 不要注入（服务端 SDK 不支持自动跟踪）
• sdk_integration_mode === "none" → 不要注入（没有 SDK；通过其他方式导入数据）

注入规则：

1. 仅注入推荐事件；可选事件不会自动注入（可选启用会在 Refine 阶段提示）
2. 将自动跟踪事件放在 events 数组末尾，并标记为 source: "autotrack"
3. 自动跟踪事件的 event_tag 设为 "System Event"
4. 自动跟踪事件仅携带预置属性（prop_names 为空，或仅包含预置属性名称）
5. 前缀为 # 的预置属性不会添加到 event_properties 池中（由 SDK 自动采集）
6. 清理 + 去重：CLI 将执行以下操作：
   • 移除从模板或现有方案继承、但与用户所选 SDK 不匹配的自动跟踪事件。例如：如果面向 Android/iOS 的模板包含 ta_app_install、ta_app_start、ta_app_end，但用户选择了 JavaScript SDK，则会自动移除这些 ta_app_* 事件，因为 JavaScript SDK 不支持它们。
   • 注入适用于用户所选 SDK 的自动跟踪事件。
   • 按事件名称全局去重——草稿中已存在的事件不会重复注入（保留从模板继承的正确自动跟踪事件）。

SDK 类型 → 推荐事件（详情请参阅 references/autotrack-events.md）：

SDK 类型	推荐（自动注入）	可选（Refine 提示）
Android / iOS	ta_app_install、ta_app_start、ta_app_end	ta_app_view、ta_app_click、ta_app_crash
JavaScript	ta_page_show、ta_page_hide	ta_pageview
微信小程序	ta_mp_launch、ta_mp_show、ta_mp_hide、ta_mp_view、ta_mp_share	ta_page_leave、ta_add_favorite、ta_mp_click
微信小游戏	ta_mp_launch、ta_mp_show、ta_mp_hide	—
Unity	ta_app_install、ta_app_start、ta_app_end	ta_scene_loaded、ta_scene_unloaded
Unity 微信小游戏	ta_mg_launch、ta_mg_show、ta_mg_hide	ta_scene_loaded、ta_scene_unloaded
其他游戏引擎	ta_app_install、ta_app_start、ta_app_end	—

自动跟踪事件用途说明：

• 自动跟踪事件是 SDK 内置的自动上报机制；无需手动定义同名事件
• 示例：JavaScript SDK 的 ta_page_show 会自动采集页面浏览；无需定义 home_page_show、about_page_show 等事件。
• 如果模板中已包含自动跟踪事件（例如行业模板中的 ta_app_install），CLI 不会重复注入
• 在 ae-generate-tracking-code 阶段初始化 SDK 时，需要启用相应开关

草稿 JSON 示例：

{
  "event_name": "ta_app_install",
  "display_name": "App Install",
  "event_desc": "Triggered on first app install; upgrades do not trigger; reinstall after deletion triggers",
  "event_tag": "System Event",
  "platform": "client",
  "prop_names": [],
  "source": "autotrack"
}

注意：自动跟踪事件的 platform 始终为 "client"，因为只有客户端 SDK 支持自动跟踪。

1.5 持久化 + 生成 xlsx

必须先写入 draft.json，再运行 draft 命令。不要跳过此步骤，直接运行 ae-cli tracking plan draft。

• 将草稿保存到 .ae-cli/draft.json
• ⚠️ 写入 meta.lang：根据用户当前语言（zh/en/ja/ko）设置 draft.meta.lang，确保生成的 xlsx 表头／工作表名称／类型值与 AE 平台语言一致
• 写入后必须确认文件已更新（检查文件修改时间或内容）；确认新内容后才能生成 xlsx
• 生成可直接上传的 xlsx：

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx

1.6 规则验证（必须执行）

生成 xlsx 时自动验证，确保符合 AE 跟踪计划规则：

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx --fix

验证规则：

规则	描述	自动修复
显示名称唯一性	同一属性池中，display_name 不得重复	✅ 添加区分前缀
对象数组一致性	不同事件中相同的 array_row 必须具有相同的子属性	✅ 填充缺失的子属性
属性名称 snake_case 格式	属性名称必须匹配 ^[a-z][a-z0-9_]*$	❌ 需要手动修复
事件名称格式	事件名称匹配 ^[A-Za-z][A-Za-z0-9_]*$；默认使用小写，按需保留大写	❌ 需要手动修复
属性名称唯一性	属性名称不得重复	❌ 需要手动修复
事件名称唯一性	事件名称不得重复	✅ 删除后续重复项

验证流程：

1. CLI 自动验证 draft.json
2. 发现可修复的问题 → 自动修复 → 更新 draft.json → 生成 xlsx
3. 发现不可修复的问题 → 报错；需要手动修复 draft.json
4. 未发现问题 → 继续进入 Phase 1.7

注意：不同属性池中的显示名称可以相同（例如，vip_level 可以同时是事件属性和用户属性）。

与 Phase 0 现有计划验证的关系：底层规则引擎相同，但 Phase 0 使用交互式 3 级（轻微/中等/严重），因为用户在场，可以确认每项修复。Phase 1.6 使用批量 2 级（可自动修复/需要手动修复），因为它作为自动草稿生成流程的一部分运行。在 Phase 0 中标记为“中等（需要确认）”的规则，在此处会显示为“❌ 需要手动修复”——规则相同，只是不再进行交互式询问。

1.7 显示摘要

通过 Markdown 表格向用户显示：事件数量 / 事件属性池大小 / 超级属性数量 / 用户属性数量；显示交付文件路径。

显示后，告知用户：

Phase 1 complete.
Next: Phase 2 — Refine to confirm the plan.

📁 模板查找约定

运行以下命令以动态发现可用模板：

AE_LANG=<user_lang> ae-cli tracking plan list-templates --json

语言规则：模板名称和模板业务内容不得由模型翻译。仅当 CLI 返回本地化名称或在 src/tracking/i18n 资源中找到本地化名称时，才使用本地化名称。如果 list-templates --json 仅返回原始模板 name，则按原样显示该名称，并在导入时保持不变。在展示或修改任何模板自带的本地化标签前，先在 src/tracking/i18n 中查找；不得自行编造译文。

内置模板由 ae-cli 从 ae-cli 包根目录解析。用户模板从 ae-cli 用户模板目录解析。不要根据用户当前工作区手动构造 ./tracking-plan-template/... 路径。

按以下顺序搜索目录：

1. <ae-cli package root>/tracking-plan-template/ — 随包提供的模板
2. ~/.ae-cli/templates/ — 用户提供的模板目录

每个模板优先使用 .md 精简文件（如果存在同名 .md，则返回 md 路径；否则返回 xlsx 路径）。 显示 CLI 返回的模板名称，并在导入时保留 JSON 结果中的确切 name。导入时自动检测格式：

AE_LANG=<user_lang> ae-cli tracking code import-template --template-name "<template name>" --out .ae-cli/draft.json

---

阶段 2 — 优化（5 个分段循环）

数据路径（source_type = data）：完全跳过此 5 个分段循环，改用“数据路径（source_type = data）”中定义的单次确认关卡。

按顺序进行，每个分段各进行一轮对话：

1. sdk_config（SDK 配置 + 用户身份，合并） — 展示 SDK 集成模式、平台/语言、访客 ID 策略、账户 ID 来源及对应的 SDK 调用
2. business（业务维度 + 业务事件，合并） — 展示收入模式、核心循环、功能入口、注入的事件模块（按平台分组）
3. autotrack（自动跟踪事件） — 在单独的表格中展示 SDK 自动跟踪事件，并说明启用方法
4. common_props（超级属性） — 展示所有超级属性，并说明使用场景和注意事项
5. props（事件属性 + 用户属性） — 按事件分组展示事件属性池，并展示用户属性表格

每个分段的流程：

1. 展示当前草稿的对应部分
2. 提出该分段专属的确认问题。始终包含当前分段编号、当前分段键和下一分段键：

   Segment <n>/5 <segment_key> confirmed? Reply ok to continue to Segment <n+1>/5 <next_segment_key>, or describe changes.
   

   对于分段 5：

   Segment 5/5 props confirmed? Reply ok to archive the plan and continue to Phase 3, or describe changes.
   

3. 用户用自然语言给出指示 → 更新 .ae-cli/draft.json → 重新运行：

   AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
   

4. 用户回复 ok → 进入下一分段

ok 是优化状态机的输入，不是重复消息错误。如果用户连续多次回复 ok，则按顺序每次只前进一个分段。每次提示确认前，先打印新的分段标题，避免连续确认看起来像重复提问。

用户可随时说 “Go back to segment N”，跳转到任意分段（N = 1-5）。

---

sdk_config（阶段 2 分段 1）

展示 SDK 集成配置 + 用户身份系统：

SDK Integration Config:
- Integration mode: <client_only / server_only / both / none>
- Client: <platform> (<language>)
- Server: <language>

User Identity Config:
- Account ID source: <user_account / role_id / none>
- Account ID field: <specific field>
- Visitor ID strategy: <auto / device_id / custom>

用户回复 ok / 修改。

---

business（阶段 2 分段 2）

展示业务维度 + 业务事件：

Business Dimensions:
- Revenue model: <IAA / IAP / mixed / subscription / commission>
- Core loop: <description>
- Functional entries: <list>
- Currency system: <hard currency / soft currency>

Injected Event Modules (grouped by platform):

Client events (platform=client):
- <event>: <display_name> — <event_desc>
- ...

Server events (platform=server):
- <event>: <display_name> — <event_desc>
- ...

Both-platform events (platform=both):
- <event>: <display_name> — <event_desc>

冲突检测：如果业务维度与源材料矛盾，请醒目地标出并让用户确认。

用户回复 ok / 修改。

---

autotrack（阶段 2 分段 3）

仅在 client_only 或 both 模式下展示。

展示 SDK 自动跟踪事件列表，并附上说明：

• 这些事件由 SDK 自动采集；代码生成期间无需手动调用 track()，只需在 SDK 初始化时启用相应开关
• 可调整 display_name 或 event_desc；事件名称不可更改

用户回复 ok / 修改。

---

common_props（阶段 2 分段 4）

展示所有超级属性（name / display_name / type / desc）。

说明：

• 超级属性会附加到每个事件上，适用于业务全局维度
• 常见超级属性（按应用类型）：
  • H5/Web：channel（来源渠道）、referrer_domain（引荐域名）
  • Mobile App：channel、app_version、platform
  • Game：channel、vip_level、server_id
  • Mini-program：channel、scene
• 禁止：不得将 SDK 预置属性（# 前缀）设为超级属性

用户回复 ok / 修改。

---

props（阶段 2 分段 5）

展示事件属性池（按事件分组）+ 用户属性表格：

• 事件属性：name / display_name / type / desc，按 event_tag 分组
• 用户属性：name / display_name / type / update_type / desc

用户属性更新方法：

更新方法	说明	使用场景
user_setOnce	仅首次设置；后续更新将被忽略	首次注册时间、首次付款时间、首次渠道
user_set	覆盖更新；始终采用最新值	当前等级、当前余额、昵称、VIP 状态
user_add	数值累加；适用于累计值	充值总额、累计登录天数、广告观看总次数

用户回复 ok → 立即执行归档命令，然后进入阶段 3。

---

优化阶段启发式建议

• 超级属性与事件属性：某个属性出现在 3 个或更多事件中 → 将其提升为超级属性；超级属性适用于业务范围内的全局维度（channel、vip_level、ab_test_group）
• 禁止事项：不要将 SDK 预置属性（# 前缀）设为超级属性
• 事件必须包含属性：每个事件都必须至少包含一个有意义且可描述的属性
• 嵌套属性：array_row 父属性包含用于描述一组对象的 parent.child 子属性

---

阶段 2 之后 — 交付前自检

⚠️ 上传到 AE 前，必须完成以下自检。上传前修复所有问题。

命名规范检查

• 事件名和属性名是否以字母开头？
• 事件名和属性名是否仅包含字母、数字和下划线（不含中文、空格）？
• 是否存在重复的事件名或同时存在的同义事件（例如 order_create 和 create_order）？
• 同一属性名是否对应多个显示名称或类型？
• 每个事件、事件属性、公共事件属性和用户属性是否都包含以用户所用语言填写的非空 display_name？

收入模式必需事件检查

收入模式	必须包含的事件	检查
IAA	ad_show、ad_click、ad_reward_get	[ ]
IAP	payment、payment_fail	[ ]
mixed	所有 IAA + IAP 事件	[ ]
subscription	subscription_start、subscription_renew、subscription_cancel	[ ]
commission	order_create、order_paid、commission_settled	[ ]

成对事件一致性检查

开始/结束成对事件（例如 battle_start/battle_end）必须携带名称相同、结构相同的对象数组：

• 开始事件上报的对象数组子属性，在结束事件中必须具有相同的名称和类型
• 检查：关卡事件对（stage_start/stage_complete）、战斗事件对（battle_start/battle_end）、抽卡事件对（gacha_draw/hero_get）等

单位说明检查

• 金额字段是否注明单位（分/USD）？
• 时长字段是否注明单位（秒/毫秒）？
• 余额字段是否注明是充值后的余额还是操作前的余额？

枚举值检查

• 事件描述中是否列出了枚举值（≤ 10 个值）？
• 如果值超过 10 个，是否注明应使用维度表？
• 是否记录了空值回退策略（例如“未知渠道 → 使用 unknown”）？

对象数组使用检查

仅在以下三个条件全部满足时使用对象数组（array_row）；否则使用对象或普通属性：

1. 一个事件属性包含多个需要记录的同类型实体
2. 每个实体都需要记录 ≥ 2 个属性
3. 实体数量可变

对象使用检查

满足以下条件时使用对象（object）；注意与对象数组区分：

• 一对一关系 → 使用 object：例如用户当前的“装备”详情、玩家“当前部署的英雄”（仅一个）
• 一对多关系 → 使用 array_row：例如“背包物品”列表、“阵容英雄”列表（多个）

快速规则：数据形状为 {...} → 使用 object；数据形状为 [{...}] → 使用 array_row。

---

第 2 阶段之后 — 归档

确认全部 5 个 Refine 片段后（用户对片段 5 回复 ok），立即归档；不要跳过或延迟：

AE_LANG=<user_lang> ae-cli tracking plan archive --draft .ae-cli/draft.json --xlsx .ae-cli/draft.xlsx --name "<plan_name>"

参数	描述	示例
--draft	draft.json 路径（必填）	.ae-cli/draft.json
--xlsx	draft.xlsx 路径（必填）	.ae-cli/draft.xlsx
--name	用作输出文件名前缀的计划名称（必填）	"AI SaaS Website Tracking Plan"

输出文件位于 plans/<date>-<plan_name>.xlsx；draft.json 会更新 meta.archived_at。

归档后，告知用户：

✅ Archive complete
File path: plans/<date>-<plan_name>.xlsx

Next: Phase 3 — Upload to AE:
1. Login to AE to get token
2. Get AE project ID
3. Upload plan to AE

⚠️ 硬性规则：必须完成归档后才能进入第 3 阶段。在第 3 阶段第 1 步提出第一个问题之前，必须确认 meta.archived_at 存在。

---

第 3 阶段 — Token 和 projectId

第 3 阶段开始时，告知用户：

## Phase 3 — Upload Preparation
Next steps:
1. Check active AE host and login status
2. Login to AE to get token if needed
3. AE project ID

3.1 检查活跃 AE 主机和登录状态

不要先询问 AE Web 地址。ae-cli 会存储一个活跃 AE 主机，身份验证命令可以直接使用它。

首先检查当前身份验证和主机状态：

ae-cli auth status

如果已配置活跃主机，将该主机保存到 .ae-cli/draft.json 的 meta.host。如果 auth status 报告 authenticated: true，则跳过登录并继续获取项目 ID。

仅当 ae-cli 报告没有活跃主机／未配置 AE 主机时，才询问用户：

“AE Web 地址是什么？”

用户回复后，配置该地址，并将相同的值保存到 .ae-cli/draft.json 的 meta.host：

ae-cli config set-host <host>

如果 auth status 报告未通过身份验证，请使用 Agent 分步流程。AI Agent 不得直接运行会阻塞的 ae-cli auth login。

步骤 1 — 请求授权 URL，并将控制权交还给用户：

ae-cli auth login --no-wait

向用户显示返回的 verification_url，并请他们完成授权。保留返回的 device_code，用于下一步。

步骤 2 — 用户表示授权已完成后，完成登录：

ae-cli auth login --device-code <device_code>
ae-cli auth status

除非前一条命令明确因未配置活跃主机而失败，否则不要使用 ae-cli auth login --host <host> 重试。如果是这种情况，先配置主机，然后使用 --no-wait 重新开始分步流程。

常见错误提示和自助恢复方法：

错误	原因	告知用户的内容
Device authorize request failed	Agent 运行环境无法连接授权服务	告知用户未创建设备代码，并附上完整错误信息
not_mac	尝试了旧版浏览器 Token 流程	使用设备代码登录分步流程重试；不要向用户索要浏览器 Token
NO_TAB_FOUND	尝试了旧版浏览器 Token 流程	使用设备代码登录分步流程重试；不要要求用户打开 Chrome

Token 会缓存 20 小时；使用相同主机可避免重新进行身份验证。

3.2 获取 AE 项目 ID 并更新草稿

询问用户：“AE 项目 ID 是什么？前往 AE Admin → ‘Project Settings’ → ‘Integration Config’ → 复制 ‘Project ID’，或检查 AE 系统 URL 参数 currentProjectId=<id>。”

用户提供 projectId 后，更新 .ae-cli/draft.json 的 meta.project_id。

---

第 4 阶段 — 上传

第 4 阶段开始时，告知用户：

## Phase 4 — Upload to AE
Checking project's existing plan...

4.1 检查项目现有计划

上传前，检查项目是否已有追踪计划：

AE_LANG=<user_lang> ae-cli tracking plan fetch --project <projectId> > .ae-cli/existing-plan.json

除非用户明确提供了此命令可访问的覆盖地址，否则不要在此处添加 --host。在 Agent 沙箱中，ae-cli 可以从沙箱提供的 cli-token.json 解析请求主机；传入过时的 Kubernetes 内部主机可能会绕过此回退机制。

结果判断：

• 文件为空或命令错误 404 → 项目没有计划；直接上传
• 文件有内容 → 项目已有计划；显示摘要 + 冲突检测

存在现有计划时，显示：

Project already has a tracking plan:
- Events: XX
- Event properties: YY
- Super properties: ZZ
- User properties: WW

Choose upload mode:
1. Append (keep existing plan, add new events/properties)
2. Replace (delete existing plan, upload new plan)

Append / Replace?

---

4.2 追加模式冲突检测

用户选择“追加”时，必须检测冲突（AE 按名称合并可能会静默丢弃数据）：

读取两个文件：

• 现有计划：.ae-cli/existing-plan.json
• 新计划：.ae-cli/draft.json

检测两种类型的冲突：

冲突类型 A：同名属性类型不匹配（严重）

AE 规则：同名属性必须具有相同的类型，否则上报的数据将被丢弃。

检测逻辑：

比较 event_properties / common_event_properties / user_properties 三个属性池：

• 对于新方案中的每个属性，在现有方案中查找同名属性
• 如果名称相同但类型不同 → 记录为 property_type_conflict（严重错误）

冲突显示：

⚠️ Severe conflict: Same-name property type mismatch

The following properties have different types in the existing plan vs. new plan.
Appending will cause reported data to be discarded:

| Property Name | Existing Type | New Plan Type |
|---|---|---|
| order_amount | number | string |
| vip_level | string | number |

Suggestions:
1. Modify the new plan's property types to match the existing plan
2. Or choose "Replace" mode to redefine types

Continue append (without fixing) / Modify draft / Switch to replace?

冲突类型 B：同名事件（提示）

AE 按名称合并：同名事件不会被覆盖；新名称的事件会被添加。事件名称区分大小写（Purchase ≠ purchase）——仅更改大小写会创建新事件，而不是重命名。

检测逻辑：

对于新方案中的每个事件，在现有方案中查找同名事件：

• 如果存在同名事件 → 记录为 event_exists（提示，不是错误）

冲突显示（仅提示）：

⚠️ Advisory: The following events already exist in the project (append mode will not overwrite)

- user_login (existing: 2 properties, new plan: 3 properties)
- order_create (existing: 5 properties, new plan: 5 properties)

After append:
- Existing event property associations will not change
- New properties for existing events will not be added
- New events will be added normally

Continue append? yes / no

---

4.3 上传流程

根据冲突检测结果决定：

检测结果	操作
无冲突	直接上传
仅有提示（类型 B）	经用户确认后上传
严重冲突（类型 A）	由用户修复或切换到替换模式

上传命令：

AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

• 使用 --replace：先删除现有项目方案，然后上传（用户选择“替换”时，或严重冲突导致切换到替换模式时）
• 不使用 --replace：AE 按名称合并（无冲突时，或仅有提示且用户确认追加时）

上传命令必须显式传入 --lang <user_lang>。--lang 必须与生成的 xlsx 语言和 draft.meta.lang 一致；AE_LANG 仅用于 CLI 消息和 xlsx 重新生成上下文。不要调用 AE 用户语言配置 API，也不要使用 --switch-lang。如果 xlsx 语言不正确，请先使用预期语言重新生成 xlsx，再上传：

AE_LANG=<user_lang> ae-cli tracking plan draft --in .ae-cli/draft.json --out .ae-cli/draft.xlsx
AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

上传成功后，提示用户在 AE Admin 中验证。提供完整 URL（跟踪方案页面 URL 格式：https://<host>/#/data/plan）。

然后通过 ae-cli 读回已上传的方案，并将其显示名称同步到项目中已有的任何事件/属性元数据：

AE_LANG=<user_lang> ae-cli tracking plan get --project-id <projectId> --host <host>
AE_LANG=<user_lang> ae-cli tracking plan sync-display-names \
  --project-id <projectId> \
  --draft .ae-cli/draft.json \
  --host <host>

sync-display-names 可安全地重复运行：

• 它只会填充空白的事件/属性元数据显示名称。
• 它不会覆盖 AE 中已有的非空显示名称。
• missing_in_metadata 表示该事件/属性尚未出现在项目元数据中；这不代表上传失败。 报告这些名称，并在首批 Debug 或生产数据到达 AE 后重新运行相同命令。
• missing_display_name_in_draft 表示生成的方案不完整。补上缺失的本地化 display_name， 重新生成/验证 xlsx，然后重新运行上传/同步流程。

---

4.4 上传失败处理与自动修复

上传时使用 --auto-fix 选项（默认启用）；CLI 会自动检测并修复错误：

AE_LANG=<user_lang> ae-cli tracking plan upload --project <projectId> --xlsx .ae-cli/draft.xlsx --draft .ae-cli/draft.json --lang <user_lang> [--replace]

AE API 错误类型

错误类型	说明	自动修复
event_prop_display_duplicate	事件属性显示名称重复	✅ 添加用于区分的前缀
complex_event_property_should_has_same_child_property	对象数组子属性不一致	✅ 补齐缺失的子属性
event_name_duplicate	事件名称重复	✅ 移除后续重复项
property_type_conflict	属性类型不匹配（追加模式）	❌ 切换到替换模式

自动修复流程

CLI 自动执行：

1. 将 xlsx 上传到 AE
2. 检查 eventErrorMap 是否存在错误
3. 可修复的错误 → 自动修复 draft.json → 重新生成 xlsx → 重新上传
4. 最多循环 3 次；超出后提示用户手动处理

输出示例：

🔧 Auto-fixing upload errors (attempt 1/3)...
Fixed: Fixed object array sub-property inconsistency, Fixed display name duplicate
[plan-upload] regenerated: .ae-cli/draft.xlsx

---

4.5 成功后的操作

成功上传并同步显示名称后，提示用户在 AE Admin 中确认。提供完整 URL （跟踪计划页面 URL 格式：https://<host>/#/data/plan）。附上简短的同步摘要： 已更新数量、已保留的现有数量，以及项目元数据中仍缺少的任何名称。

询问是否生成跟踪代码：

跟踪计划已成功上传。接下来要生成跟踪代码吗？

• 是 → 引导用户使用 ae-generate-tracking-code 技能
• 否 → 告知用户计划存档位置：plans/<date>-<plan_name>.xlsx；用户可随时继续

禁止事项

• 一次性询问所有锚点问题
• 跳过 Phase 3 并直接上传
• 绕过 .ae-cli/draft.json 手动组装 xlsx
• 在任何面向用户的输出中（交互提示、计划摘要、事件/属性描述）将 "Super Property" 翻译为“超级属性”——AE 正确的中文术语是“公共事件属性”或“公共属性”
• 在技能中直接调用 fetch AE API——所有 AE 通信都必须通过项目脚本 / CLI 进行

---

内部参考（供贡献者使用；非技能使用路径）

• skills/ae-generate-tracking-plan/references/te-api.md — AE 后端端点捕获文档
• skills/ae-generate-tracking-plan/references/xlsx-schema.md — xlsx 格式规范（写入规则 + 读取兼容性）
• skills/ae-generate-tracking-plan/references/autotrack-events.md — SDK 自动跟踪事件定义（各平台事件列表 + SDK 类型映射）
• skills/ae-generate-tracking-plan/references/business-dimension-mapping.md — 业务维度 → 事件/属性映射表（收入模型 / 功能条目 / 货币体系 → 注入的事件）
• src/plan/types.ts — Draft TypeScript 类型定义