ae-tracking 0.1.0

package/skills/generate-tracking-plan/SKILL.md

@@ -0,0 +1,826 @@
+---
+name: generate-tracking-plan
+description: 交互式生成 AE 埋点方案并上传。触发词：埋点方案、埋点模板、tracking plan、AE 方案生成。走 anchor → draft → refine → token → upload 五阶段，产物是 AE 后台里真实创建好的埋点方案。
+---
+
+# generate-tracking-plan
+
+## 何时触发
+
+用户提到"埋点方案 / 埋点模板 / tracking plan / AE 方案 / 帮我建埋点"等意图时触发。
+应用类型覆盖 H5 / Web / iOS / Android / 小程序 / Unity。进入本 skill 后严格按
+Phase 0 → 1 → 2 → 3 → 4 推进，不得跳步。
+
+> Phase 1 / 3 / 4 通过 `ae-tracking` CLI 执行（`ae-tracking plan draft`
+> / `ae-tracking auth` / `ae-tracking plan upload` / `ae-tracking plan delete`）。
+> 本 skill 只关心命令行为，不关心内部实现。
+
+---
+
+## Phase 0 — Anchor（每个问题单独一条消息）
+
+依次收集以下 **5 项**，**不得一次问完**：
+
+### 第 1 项 — 应用业务场景（多轮对话）
+
+#### 1.1 应用概述
+
+问：**"应用业务场景是什么？一句话概括，比如：电商网站，用户可以浏览商品和下单购买"**
+
+用户回答后，记录到 `meta.scenario`，并生成 `meta.plan_name`（方案名称）。
+
+#### 1.2 应用详情
+
+问：**"选择素材来源，最多选 2 项："**
+
+用户可多选（最多 2 项），选项如下：
+
+1. **产品文档**（本地路径或 URL）— 从产品文档抽取事件和属性
+2. **详细描述**（对话形式）— 描述应用业务流程、核心功能、用户行为、盈利模式等
+3. **工程代码**（本地目录路径）— 分析源码提取事件和属性
+4. **预置模板**（游戏(MMO,SLG,卡牌,塔防,棋牌,休闲养成)/电商/阅读/社交/短剧）— 选择内置模板
+5. **应用官网**（URL）— 抓取官网内容了解产品功能和业务
+
+根据用户选择判定素材来源并记录到 `meta.source_type`：
+
+| 选择 | source_type | 处理方式 |
+|---|---|---|
+| 仅产品文档 | `prd` | 读产品文档，抽取事件和属性 |
+| 仅详细描述 | `chat` | 根据描述在 Draft 阶段构造事件 |
+| 仅工程代码 | `codebase` | 扫描源码，从业务逻辑提取事件和属性 |
+| 仅预置模板 | `template` | 提供内置模板选择 |
+| 仅应用官网 | `website` | 抓取官网页面，抽取产品功能描述 |
+| 任意两项组合 | 用 `_` 连接两项 type | 第一项为 baseline，第二项补充（优先级：template → codebase → prd → website → chat） |
+
+**追问**（按选择顺序逐一追问）：
+- 产品文档 → 问 **"产品文档路径是什么？（本地路径或 URL）"**
+- 详细描述 → 如果描述过于简单，追问核心功能、用户行为、业务流程、盈利模式
+- 工程代码 → 问 **"工程目录路径是什么？"**，然后扫描源码提取业务逻辑
+- 预置模板 → 展示匹配的模板内容让用户确认
+- 应用官网 → 问 **"应用官网 URL 是什么？"**
+
+**工程代码分析流程（source_type 含 `codebase` 时）**：
+
+1. 用户提供工程目录路径
+2. 扫描目录结构，识别技术栈（引擎/框架/语言）
+3. 读取核心业务模块（游戏逻辑、场景管理、UI 交互、状态/数据模型、网络/支付等）
+4. 从代码中提取：
+   - **事件**：玩家交互动作（点击/滑动/触发）、场景切换、游戏状态变化（开始/暂停/结束）、业务流程节点（购买/升级/解锁）
+   - **事件属性**：动作参数（子弹类型/敌人等级/道具 ID）、状态值（分数/血量/金币）、上下文（关卡 ID/难度/模式）
+   - **用户属性**：持久状态（等级/经验/VIP/累计充值）
+5. 将提取结果映射为 AE 呝名规则（`snake_case` 事件名 + 中文 `display_name`）
+6. 与用户确认提取结果，补充遗漏
+
+**应用官网分析流程（source_type 含 `website` 时）**：
+
+1. 用户提供官网 URL
+2. 抓取官网主要页面（首页、功能介绍、定价等）
+3. 从页面内容提取：
+   - **产品功能列表** → 映射为核心事件
+   - **用户操作流程** → 映射为事件属性
+   - **用户身份/等级体系** → 映射为用户属性
+4. 将提取结果映射为 AE 命名规则，与用户确认
+
+---
+
+### 第 2 项 — 客户端 SDK 配置
+
+问：**"应用类型和开发工具是什么？"**
+
+> SDK 支持列表来源于 `wiki/te-docs/raw/接入指南/客户端-sdk/`，如有更新请同步修改本表。
+
+**选项**（应用类型 - 开发工具）：
+
+- **H5/Web应用** (Vue / React / 原生JS / 其他前端框架)
+- **手机游戏** (Android原生 / iOS原生 / Unity / CocosCreator / Cocos2d-x / LayaAir / Egret / Unreal / 其他引擎)
+- **手机APP** (Android原生 / iOS原生 / React Native / Flutter / uni-app / OpenHarmony)
+- **小游戏** (小游戏平台：微信 / QQ / 抖音 / 百度等)
+- **小程序** (小程序平台：微信 / 抖音 / 支付宝 / 百度 / 钉钉 / 快手 / QQ / 京东 / 360 / 快应用等)
+- **PC游戏** (Unreal / Unity / 其他引擎)
+- **PC应用** (C++ / C# / MacOS原生 / 其他)
+- **不集成客户端 SDK**
+
+**追问**：选 `其他` 相关选项 → 问 **"请描述具体开发工具"**
+
+**SDK 类型映射**：
+
+| 选择 | 客户端 SDK 类型 |
+|---|---|
+| H5/Web应用 - * | JavaScript SDK |
+| 手机游戏 - Android原生 | Android SDK |
+| 手机游戏 - iOS原生 | iOS SDK |
+| 手机游戏 - Unity | Unity SDK |
+| 手机游戏 - CocosCreator | CocosCreator SDK |
+| 手机游戏 - Cocos2d-x | Cocos2d-x SDK |
+| 手机游戏 - LayaAir | LayaAir SDK |
+| 手机游戏 - Egret | Egret SDK |
+| 手机游戏 - Unreal | Unreal SDK |
+| 手机APP - Android原生 | Android SDK |
+| 手机APP - iOS原生 | iOS SDK |
+| 手机APP - React Native | React Native SDK |
+| 手机APP - Flutter | Flutter SDK |
+| 手机APP - uni-app | uni-app SDK |
+| 手机APP - OpenHarmony | OpenHarmony SDK |
+| 小游戏 | 小游戏 SDK（统一 SDK，支持微信/QQ/抖音/百度等平台） |
+| 小程序 | 小程序 SDK（统一 SDK，支持微信/抖音/支付宝/百度等平台） |
+| PC游戏 - Unreal | Unreal SDK |
+| PC游戏 - Unity | Unity SDK |
+| PC应用 - C++ | C++ SDK |
+| PC应用 - C# | C# SDK |
+| PC应用 - MacOS原生 | MacOS SDK |
+| PC应用 - OpenHarmony | OpenHarmony SDK |
+| 不集成客户端 SDK | 无（`sdk_integration_mode: "server_only"`） |
+
+**多平台选择说明**：
+若用户选择了多个平台（如"Android 和 OpenHarmony"），则 `client_platforms` 记录为数组：
+```json
+"client_platforms": ["android", "openharmony"]
+```
+`client_sdk_type` 保留第一个作为主平台（向后兼容）。
+
+**开发语言选择**（仅 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`：
+```json
+"client_platform_languages": {
+  "android": ["java", "kotlin"],
+  "openharmony": ["typescript"]
+}
+```
+
+---
+
+### 第 3 项 — 服务端 SDK 配置
+
+问：**"是否集成服务端 SDK？服务端开发语言是什么？"**
+
+> SDK 支持列表来源于 `wiki/te-docs/raw/接入指南/服务端-sdk/`，如有更新请同步修改本表。
+
+**选项**：
+
+- Java
+- Python
+- Go
+- Node.js
+- PHP
+- C# / .NET
+- C++
+- Erlang
+- Lua
+- Ruby
+- 其他（请提供开发语言）
+- 不集成服务端 SDK
+
+**SDK 类型映射**：
+
+| 选择 | 服务端 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` |
+
+---
+
+### 第 4 项 — 用户体系配置（访客 ID）
+
+问：**"访客 ID 生成策略是什么？"**
+
+选项：
+- `auto` — SDK 自动生成（默认，适用于大多数场景）
+- `device_id` — 使用设备 ID（iOS IDFV / Android AndroidID）
+- `custom` — 自定义访客 ID（需在 SDK 初始化后立刻调用 `identify()`）
+
+**追问**：如果选 `custom`，问 **"访客 ID 取什么值？例如：设备 ID / UUID / 游客临时 ID"**
+
+---
+
+### 第 5 项 — 用户体系配置（账号 ID）
+
+问：**"账号 ID 来源是什么？"**
+
+选项：
+- `user_account` — 用户账号 ID（登录后的唯一标识）
+- `role_id` — 角色 ID（游戏类专用，一个账号可能有多个角色）
+- `none` — 无账号体系（纯游客模式）
+
+**追问**：
+- 选 `user_account` → 问 **"账号 ID 具体取什么值？例如：user_id（用户 ID）、phone（手机号）、email（邮箱）"**
+- 选 `role_id` → 说明 **"角色 ID 适合游戏类应用，一个账号可创建多个角色，可更细粒度分析每个角色的行为"**
+
+---
+
+### SDK 集成模式判定
+
+根据第 2、3 项的回答，自动判定 `sdk_integration_mode`：
+
+| 客户端集成 | 服务端集成 | sdk_integration_mode |
+|---|---|---|
+| 需要 | 需要 | `both` |
+| 需要 | 不需要 | `client_only` |
+| 不需要 | 需要 | `server_only` |
+| 不需要 | 不需要 | `none`（通过 RESTful API / LogBus / DataX 等方式上报） |
+
+**`none` 模式说明**：
+- 适用于历史数据导入、批量数据同步、第三方系统对接等场景
+- 在 Refine 阶段不注入 SDK 自动采集事件
+- 在 generate-tracking-code skill 中只生成 RESTful / LogBus / DataX 配置
+
+---
+
+### 事件上报平台分布（仅 `both` 模式）
+
+如果 `sdk_integration_mode === "both"`，在 Refine 阶段（第 3 段业务事件）引导用户指定：
+- 哪些事件由客户端上报（用户行为事件）
+- 哪些事件由服务端上报（业务数据事件）
+- 是否有事件需要两端同时上报
+
+**platform 字段写入 xlsx**：
+- `platform: "client"` → xlsx "采集端" 列填 `client`
+- `platform: "server"` → xlsx "采集端" 列填 `server`
+- `platform: "both"` → xlsx "采集端" 列填 `client,server`
+- `platform: undefined`（未指定）→ xlsx "采集端" 列留空
+
+---
+
+### 用户体系确认说明
+
+用户体系确认决定代码埋点时的 SDK 调用策略：
+
+| 场景 | SDK 调用时机 |
+|---|---|
+| 有账号体系 | 用户登录时调用 `login("<账号ID值>")`，退出登录时调用 `logout()` |
+| 自定义访客 ID | SDK 初始化后立刻调用 `identify("<访客ID值>")` |
+| 纯游客模式 | 无需调用 `login()`，只用 SDK 自动生成的访客 ID |
+
+**关键提醒**：
+- 避免在上报事件后调用 `identify()` 更改访客 ID，会导致用户匹配问题
+- 游戏类应用推荐使用「角色 ID」作为账号 ID（粒度更细，可分析不同角色行为）
+- 一个账号 ID 可绑定多个访客 ID（多设备登录场景）
+
+---
+
+## Phase 1 — Draft
+
+### 1.1 构造 canonical draft
+
+Draft 的概念结构（**内部 json，用户不直接看**）：
+
+```
+Draft
+├── meta:
+│   ├── app_type:                   应用类型
+│   ├── sdk_integration_mode:       SDK 集成模式：client_only / server_only / both
+│   ├── client_sdk_type?:           客户端 SDK 类型（仅 client_only 或 both）
+│   ├── client_language?:           客户端开发语言（游戏引擎需指定）
+│   ├── server_language?:           服务端开发语言（仅 server_only 或 both）
+│   ├── project_id?:                AE 项目 ID（Phase 3 补充）
+│   ├── host?:                      AE web 地址（Phase 3 补充）
+│   ├── plan_name:                  方案名称
+│   ├── scenario:                   业务场景描述
+│   └── user_identity:              用户体系配置
+│       ├── account_id_source:      账号 ID 来源：user_account / role_id / none
+│       ├── account_id_field?:      账号 ID 具体字段名（仅 user_account 时填写，如 user_id / phone / email）
+│       ├── distinct_id_strategy:   访客 ID 策略：auto / device_id / custom
+│       └── distinct_id_custom_value?: 自定义访客 ID 取值
+├── events:                         一组事件，每个事件含 platform 字段
+├── event_properties:               全局事件属性池（去重后）
+├── common_event_properties:        公共事件属性（每个事件自动带）
+└── user_properties:                用户属性
+```
+
+**SDK 集成模式字段**：
+
+```json
+{
+  "sdk_integration_mode": "both",       // client_only / server_only / both
+  "client_sdk_type": "android",         // 仅 client_only 或 both 时填写
+  "client_language": "java",            // 游戏引擎 SDK 需指定
+  "server_language": "java"             // 仅 server_only 或 both 时填写
+}
+```
+
+**事件平台标记（`events[].platform`）**：
+
+```json
+{
+  "event_name": "order_create",
+  "display_name": "订单创建",
+  "platform": "server",    // client / server / both
+  "prop_names": ["order_id", "order_amount", "payment_method"],
+  "source": "prd"
+}
+```
+
+- `platform: "client"` — 客户端上报（用户行为事件）
+- `platform: "server"` — 服务端上报（业务数据事件）
+- `platform: "both"` — 两端同时上报（需同步时间戳）
+
+**用户体系字段（`meta.user_identity`）**：
+
+```json
+{
+  "account_id_source": "user_account", // 账号 ID 来源：user_account / role_id / none
+  "account_id_field": "user_id",       // 账号 ID 具体字段名（仅 user_account 时填写）
+  "distinct_id_strategy": "auto",      // 访客 ID 策略：auto / device_id / custom
+  "distinct_id_custom_value": null     // 自定义访客 ID 取值说明（仅 strategy=custom 时填写）
+}
+```
+
+**属性类型**（枚举）：`string` / `number` / `bool` / `datetime` /
+`array_row`（对象数组，支持 `父名.子名` 嵌套）/ `array_string`（字符串数组）
+
+**命名规则**：事件名 / 属性名必须 `snake_case`；中文放 `display_name` 字段。
+
+### 1.2 合并素材
+
+按优先级从低到高：**template → codebase → prd → website → chat → autotrack**
+
+- **template**：用户选的行业模板（见下方「模板查找约定」）作为 baseline，每项标记 `source: "template"`
+- **codebase**：扫描工程目录源码，从业务逻辑提取事件/属性，**同名事件合并 prop_names，不覆盖既有字段**；新项 `source: "codebase"`
+- **prd**：读产品文档（md / pdf / docx / URL），抽取产品特有事件/属性，**同名事件合并 prop_names，不覆盖既有字段**；新项 `source: "prd"`
+- **website**：抓取应用官网，从页面内容提取产品功能和业务逻辑，**同名事件合并 prop_names**；新项 `source: "website"`
+- **chat**：anchor 阶段的业务场景 + refine 阶段的编辑指令，`source: "chat"`
+- **autotrack**：根据 `meta.client_sdk_type` 自动注入 SDK 自动采集事件（仅 `client_only` 或 `both` 模式），`source: "autotrack"`
+
+### 1.3 自动注入 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. 自动采集事件放在 `events` 数组末尾，标记 `source: "autotrack"`
+2. 自动采集事件的 `event_tag` 设为 `"系统事件"`
+3. 自动采集事件只携带预置属性（`prop_names` 为空或仅含预置属性名）
+4. 预置属性以 `#` 开头，不加入 `event_properties` 池（由 SDK 自动采集）
+
+**SDK 类型 → 自动采集事件映射**（详见 `references/autotrack-events.md`）：
+
+| SDK 类型 | 自动采集事件 |
+|---|---|
+| Android / iOS | `ta_app_install`, `ta_app_start`, `ta_app_end`, `ta_app_view`, `ta_app_click`, `ta_app_crash` |
+| JavaScript | `ta_pageview`, `ta_page_show`, `ta_page_hide` |
+| 微信小程序 | `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_app_crash`, `ta_scene_loaded`, `ta_scene_unloaded` |
+| Unity 微信小游戏 | `ta_mg_launch`, `ta_mg_show`, `ta_mg_hide`, `ta_app_crash`, `ta_scene_loaded`, `ta_scene_unloaded` |
+
+**Draft JSON 示例**：
+
+```json
+{
+  "event_name": "ta_app_install",
+  "display_name": "APP 安装",
+  "event_desc": "APP 首次安装时上报，升级不触发，删除重装会触发",
+  "event_tag": "系统事件",
+  "platform": "client",
+  "prop_names": [],
+  "source": "autotrack"
+}
+```
+
+**注意**：自动采集事件 `platform` 固定为 `"client"`，因为只有客户端 SDK 有自动采集能力。
+
+### 1.4 持久化 + 生成 xlsx
+
+- 保存 draft 到 `.ae-tracking/draft.json`
+- 生成上传用 xlsx：
+
+```bash
+ae-tracking plan draft --in .ae-tracking/draft.json --out .ae-tracking/draft.xlsx
+```
+
+### 1.5 规则校验（必须执行）
+
+生成 xlsx 时自动执行校验，确保符合 AE 埋点方案规则：
+
+```bash
+ae-tracking plan draft --in .ae-tracking/draft.json --out .ae-tracking/draft.xlsx --fix
+```
+
+**校验规则**：
+
+| 规则 | 说明 | 自动修复 |
+|---|---|---|
+| 显示名唯一 | 同一属性池内 `display_name` 不能重复 | ✅ 添加区分前缀 |
+| 对象组一致性 | 同一个 `array_row` 在不同事件中子属性必须一致 | ✅ 补充缺失子属性 |
+| snake_case | 事件名/属性名必须符合 `^[a-z][a-z0-9_]*$` | ❌ 需手动修改 |
+| 属性名唯一 | 属性名不能重复 | ❌ 需手动修改 |
+| 事件名唯一 | 事件名不能重复 | ✅ 移除后续重复事件 |
+
+**校验流程**：
+
+1. CLI 自动校验 draft.json
+2. 发现可修复问题 → 自动修复 → 更新 draft.json → 生成 xlsx
+3. 发现不可修复问题 → 报错，需手动修改 draft.json
+4. 无问题 → 进入 Phase 1.6
+
+**注意**：不同属性池的显示名可以相同（如 `vip_level` 可以同时作为事件属性和用户属性）。
+
+### 1.6 展示 Summary
+
+向用户 markdown 表格展示：事件数 / 事件属性池大小 / 公共属性数 / 用户属性数；告知产物路径。
+
+### 📁 模板查找约定
+
+按以下顺序找第一个存在的位置：
+
+1. `./tracking-plan-template/` —— 本项目根（开发期）
+2. `~/.ae-tracking/templates/` —— `ae-tracking` CLI 安装后的用户目录（未来默认）
+3. `require.resolve('ae-tracking/tracking-plan-template')` —— 作为 npm 依赖装入时（未来）
+
+模板文件：官方模板 `TE官方模板_dataTrackSample.xlsx`，行业模板 `电商 / 卡牌游戏 / 社交聊天类 / 阅读类APP埋点模板_v1.xlsx`。
+
+---
+
+## Phase 2 — Refine（分 7 段循环）
+
+按顺序，每段一轮对话：
+
+1. **sdk_integration（SDK 集成配置）** — 展示 SDK 集成模式：
+   - SDK 集成模式（client_only / server_only / both）
+   - 客户端 SDK 类型及开发语言（如有）
+   - 服务端开发语言（如有）
+   
+   **展示示例**：
+   ```
+   SDK 集成配置：
+   - 集成模式：both（客户端 + 服务端）
+   - 客户端：Android SDK（Java）
+   - 服务端：Java（Spring Boot）
+   
+   代码埋点提示：
+   - 客户端事件：使用 Android SDK API（TDAnalytics.track()）
+   - 服务端事件：使用 Java SDK API（TaAnalytics.track()）
+   ```
+
+2. **user_identity（用户体系）** — 展示用户体系配置：
+   - 账号 ID 来源及取值说明
+   - 访客 ID 生成策略
+   - 提示用户代码埋点时对应的 SDK 调用（`login()` / `identify()`）
+   
+   **展示示例**：
+   ```
+   用户体系配置：
+   - 账号 ID 来源：user_id（用户注册 ID）
+   - 访客 ID 策略：auto（SDK 自动生成）
+   
+   代码埋点提示：
+   - 用户登录时调用：ta.login("<用户ID>")
+   - 用户退出登录时调用：ta.logout()
+   ```
+
+3. **events（业务事件）** — 表格展示，**按 platform 分组**：
+   - **客户端事件**（`platform === "client"`）：用户行为事件
+   - **服务端事件**（`platform === "server"`）：业务数据事件
+   - **两端同时上报**（`platform === "both"`）：特殊标记
+   
+   表格列：`event_name` / `display_name` / `platform` / `event_tag` / `event_desc` / `prop_names`
+   
+   **仅展示 `source != "autotrack"` 的业务事件**
+
+4. **events（自动采集事件）** — 单独表格展示 SDK 自动采集事件（`source == "autotrack"`）
+   - 仅在 `sdk_integration_mode !== "server_only"` 时展示
+   - 提示用户"这些是 SDK 自动采集事件，无需代码埋点，SDK 初始化时开启即可"
+
+5. **common_event_properties** — 表格（`name` / `display_name` / `type` / `desc`）
+   - 提示用户：公共属性是每个事件都会携带的属性，适合**业务全局维度**
+   - **举例需结合应用实际情况**：
+     - H5/Web 应用：`channel`（来源渠道）、`referrer_domain`（来源域名）
+     - 手机 APP：`channel`、`app_version`（应用版本）、`platform`（iOS/Android）
+     - 游戏：`channel`、`vip_level`（会员等级）、`server_id`（服务器 ID）
+     - 小程序：`channel`、`scene`（进入场景值）
+   - **警告**：不要将 SDK 预置属性设为公共属性
+     - 预置属性以 `#` 开头，由 SDK 自动采集
+     - 根据已选定的客户端 SDK 类型，从 wiki 查找对应预置属性列表：
+       - JavaScript SDK → `wiki/te-docs/raw/接入指南/客户端-sdk/javascript/进阶指南/预置属性.md`
+       - Android SDK → `wiki/te-docs/raw/接入指南/客户端-sdk/android/进阶指南/预置属性.md`
+       - iOS SDK → `wiki/te-docs/raw/接入指南/客户端-sdk/ios/进阶指南/预置属性.md`
+       - Unity SDK → `wiki/te-docs/raw/接入指南/客户端-sdk/游戏引擎/unity/进阶指南/预置属性.md`
+       - 其他 SDK → 查找对应 SDK 目录下的 `进阶指南/预置属性.md`
+
+6. **event_properties** — 按事件分组，每组展示其引用的属性
+
+7. **user_properties** — 表格（`name` / `display_name` / `type` / `desc`）
+
+每段流程：
+
+1. 展示当前 draft 对应部分
+2. 问 **"这段对吗？`ok` 进入下一段，或描述要改什么"**
+3. 用户给自然语言指令 → 更新 `.ae-tracking/draft.json` → 重跑：
+   ```bash
+   ae-tracking plan draft --in .ae-tracking/draft.json --out .ae-tracking/draft.xlsx
+   ```
+4. 用户 `ok` 进下一段
+
+允许用户随时说 **"回到第 N 段"** 跳回任意段。
+
+---
+
+### SDK 集成配置展示说明（第 1 段）
+
+SDK 集成配置决定代码埋点的实现方式：
+
+| 集成模式 | 展示内容 |
+|---|---|
+| `client_only` | SDK 类型 + 开发语言 + 客户端 API 提示 |
+| `server_only` | 服务端语言 + 服务端 API 提示 |
+| `both` | 客户端 SDK + 服务端语言 + 两端 API 提示 |
+
+**代码埋点提示**：
+- 客户端事件：提示使用客户端 SDK API
+- 服务端事件：提示使用服务端 SDK API
+- 两端同时上报：提示两端需同步 `#event_time`
+
+---
+
+### 用户体系展示说明（第 2 段）
+
+用户体系配置是埋点方案的关键部分，影响：
+1. **用户识别准确性** — 登录前后数据能否正确关联
+2. **代码埋点实现** — 何时调用 `login()` / `identify()` / `logout()` |
+3. **用户属性上报** — 用户属性关联的是账号 ID 还是访客 ID
+
+**展示内容**：
+- 账号 ID 来源（user_account / role_id / none）
+- 账号 ID 具体字段名（如 user_account 时的 user_id / phone / email）
+- 访客 ID 生成策略（auto / device_id / custom）
+- 自定义访客 ID 取值说明（如有）
+- 对应的 SDK 调用时机和代码示例
+
+---
+
+### 业务事件展示说明（第 3 段）
+
+**按 platform 分组展示**：
+- 客户端事件：用户行为（页面浏览、点击、搜索等）
+- 服务端事件：业务数据（订单、支付、充值等）
+- 两端同时：需同步时间戳，确保数据关联
+
+**平台标记调整**：
+- 用户可通过自然语言指令修改事件的 `platform` 字段
+- 例如："订单创建改为服务端上报" → `platform: "server"`
+
+---
+
+### 自动采集事件展示说明（第 4 段）
+
+- 自动采集事件单独展示在第 2 段，与业务事件分开
+- 自动采集事件不可删除（必须存在），但可修改 `display_name` 和 `event_desc`
+- 自动采集事件的预置属性由 SDK 自动采集，不需要定义到 `event_properties` 池
+- 提示用户在代码中通过 `enableAutoTrack()` 开启对应的自动采集事件
+
+### Refine 阶段的几个启发式建议
+
+- **公共属性 vs 事件属性**：
+  - 如果一个属性出现在 3 个以上事件上，考虑升为公共属性（减少上报冗余）
+  - 公共属性适合**业务维度**：`channel`（来源渠道）、`vip_level`（会员等级）、`ab_test_group`（实验分组）、`is_new_user`（是否新用户）
+  - **禁止**将 SDK 预置属性设为公共属性：`#app_version`、`#os`、`#device_model`、`#network_type` 等由 SDK 自动采集，手动设置会造成冗余或冲突
+- **事件要不要有属性**：每个事件至少带一个有语义的属性（如登出事件带 `session_duration_ms`）；否则 AE 上传可能被当成无效事件
+- **嵌套属性**：`array_row` 类型的父属性下可以挂 `父.子` 子属性，用来描述一组对象（如 `card_detail.hero_name`）
+
+---
+
+## Phase 2 完成后 — 归档
+
+所有 7 段 Refine 确认完毕后（用户 `ok` 通过第 7 段后），立即归档：
+
+```bash
+cp .ae-tracking/draft.xlsx ./plans/$(date +%F)-<plan_name>.xlsx
+git add ./plans/$(date +%F)-<plan_name>.xlsx
+```
+
+**提示用户**：
+- 归档已完成，后续上传不会覆盖本地文件
+- 上传后可在 AE 后台查看，或继续调整后重新归档
+
+---
+
+## Phase 3 — Token & projectId
+
+### 3.1 获取 AE web 地址
+
+❌ **禁止在此处提供未经确认的示例 URL**，直接询问用户即可。
+
+问用户：**"AE web 地址是什么？"**
+
+用户回答后，保存到 `.ae-tracking/draft.json` 的 `meta.host` 字段。
+
+根据 AE web 地址引导获取和保存 token：
+
+```bash
+ae-tracking auth login --host <host>
+ae-tracking auth status
+```
+
+常见错误提示与自助恢复：
+
+| 错误 | 原因 | 提示用户做什么 |
+|---|---|---|
+| `Chrome JS-from-AppleEvents disabled` | Chrome 禁用了 AppleScript 执行 JS | Chrome 菜单 View → Developer → Allow JavaScript from Apple Events，重试 |
+| `not_mac` | 非 macOS | 手动设置 `export AE_TOKEN=<uuid>`（从 DevTools → Application → Local Storage → `ACCESS_TOKEN` 取，去掉首尾引号）|
+| `NO_TAB_FOUND` | 没在 Chrome 登录 AE | 先在 Chrome 打开并登录 TE，重试 |
+
+Token 缓存 20 小时，同 host 下次免取。
+
+### 3.2 获取 AE 项目ID 并更新 draft
+
+问用户：**"AE 项目ID 是什么？请前往 AE 系统「项目管理」→「接入配置」→ 复制「项目ID」，或者查看 AE 系统 URL 参数 currentProjectId=<id>"**
+
+用户提供 projectId 后，更新到 `.ae-tracking/draft.json` 的 `meta.project_id` 字段。
+
+---
+
+## Phase 4 — Upload
+
+### 4.1 检查项目现有方案
+
+上传前先检查项目是否已有埋点方案：
+
+```bash
+ae-tracking plan fetch --project <projectId> --host <host> > .ae-tracking/existing-plan.json
+```
+
+**判断结果**：
+- 文件为空或命令报错 `404` → 项目无方案，直接上传
+- 文件有内容 → 项目已有方案，展示 summary + **冲突检测**
+
+**已有方案时展示**：
+```
+项目已有埋点方案：
+- 事件数：XX
+- 事件属性数：YY
+- 公共属性数：ZZ
+- 用户属性数：WW
+
+请选择上传方式：
+1. 追加（保留现有方案，添加新事件/属性）
+2. 替换（删除现有方案，上传新方案）
+
+追加 / 替换？
+```
+
+---
+
+### 4.2 追加模式的冲突检测
+
+用户选择"追加"时，**必须检测冲突**（AE merge-by-name 有静默丢弃风险）：
+
+**读取两份文件**：
+- 既有方案：`.ae-tracking/existing-plan.json`
+- 新方案：`.ae-tracking/draft.json`
+
+**检测两类冲突**：
+
+#### 冲突类型 A：同名属性类型不一致（严重）
+
+AE 规定：同名属性必须类型一致，否则上报数据会被抛弃。
+
+**检测逻辑**：
+
+对比 `event_properties` / `common_event_properties` / `user_properties` 三个属性池：
+- 遍历新方案每个属性，在既有方案中查找同名属性
+- 若同名但类型不一致 → 记录为 `property_type_conflict`（严重错误）
+
+**冲突展示**：
+```
+⚠️ 严重冲突：同名属性类型不一致
+
+以下属性在既有方案和新方案中类型不同，
+追加上传会导致上报数据被抛弃：
+
+| 属性名 | 既有类型 | 新方案类型 |
+|---|---|---|
+| order_amount | number | string |
+| vip_level | string | number |
+
+建议：
+1. 修改新方案的属性类型，与既有方案一致
+2. 或选择「替换」模式重新定义类型
+
+继续追加（不修复） / 修改 draft / 改用替换？
+```
+
+#### 冲突类型 B：同名事件（提醒）
+
+AE merge-by-name：同名事件不覆盖，新名事件新增。
+
+**检测逻辑**：
+
+遍历新方案每个事件，在既有方案中查找同名事件：
+- 若同名事件已存在 → 记录为 `event_exists`（提醒，非错误）
+
+**冲突展示**（仅有提醒时）：
+```
+⚠️ 提醒：以下事件已存在于项目中（追加模式不会覆盖）
+
+- user_login（既有：2 属性，新方案：3 属性）
+- order_create（既有：5 属性，新方案：5 属性）
+
+追加后：
+- 既有事件的属性关联不会改变
+- 既有事件的新属性不会被添加
+- 新事件会正常添加
+
+是否继续追加？yes / no
+```
+
+---
+
+### 4.3 上传流程
+
+根据冲突检测结果决定：
+
+| 检测结果 | 处理方式 |
+|---|---|
+| 无冲突 | 直接上传 |
+| 仅有提醒（类型 B） | 用户确认后上传 |
+| 有严重冲突（类型 A） | 用户修复或改用替换 |
+
+上传命令：
+```bash
+ae-tracking plan upload --project <projectId> --xlsx .ae-tracking/draft.xlsx [--replace]
+```
+
+- **加 `--replace`**：先删除项目现有方案再上传（用户选择"替换"时，或严重冲突改用替换）
+- **不加 `--replace`**：AE merge-by-name 合并（无冲突或仅有提醒，用户确认追加）
+
+成功上传后，提示用户去 AE 后台确认，**提供完整 URL**。
+
+---
+
+### 4.4 上传失败处理与自动修复
+
+上传时使用 `--auto-fix` 选项（默认开启），CLI 会自动检测错误并修复：
+
+```bash
+ae-tracking plan upload --project <projectId> --xlsx .ae-tracking/draft.xlsx --draft .ae-tracking/draft.json [--replace]
+```
+
+#### AE API 错误类型
+
+| 错误类型 | 错误描述 | 自动修复 |
+|---|---|---|
+| `event_prop_display_duplicate` | 事件属性显示名重复 | ✅ 添加区分前缀 |
+| `complex_event_property_should_has_same_child_property` | 对象组子属性不一致 | ✅ 补充缺失子属性 |
+| `event_name_duplicate` | 事件名重复 | ✅ 移除后续重复事件 |
+| `property_type_conflict` | 属性类型不一致（追加模式） | ❌ 改用替换模式 |
+
+#### 自动修复流程
+
+CLI 自动执行：
+1. 上传 xlsx 到 TE
+2. 检查 `eventErrorMap` 是否有错误
+3. 有可修复错误 → 自动修复 draft.json → 重新生成 xlsx → 重新上传
+4. 循环最多 3 次，超过后提示用户手动介入
+
+**示例输出**：
+```
+🔧 Auto-fixing upload errors (attempt 1/3)...
+Fixed: 修复对象组子属性不一致, 修复显示名重复
+[plan-upload] regenerated: .ae-tracking/draft.xlsx
+```
+
+---
+
+### 4.5 成功后处理
+
+成功上传后，提示用户去 AE 后台确认，**提供完整 URL**
+
+## 禁止
+
+- 一次问完所有 anchor 问题
+- 跳过 Phase 3 直接 upload
+- 手动拼 xlsx 绕过 `.ae-tracking/draft.json`
+- 在 skill 里直接 `fetch` AE API —— 所有 AE 通信必须通过项目的脚本 / 未来的 CLI
+
+---
+
+## 内部参考（贡献者用，不是 skill 使用路径）
+
+- `skills/generate-tracking-plan/references/te-api.md` — AE 后端三个端点的抓包文档
+- `skills/generate-tracking-plan/references/xlsx-schema.md` — xlsx 格式契约（writer 规则 + reader 兼容）
+- `skills/generate-tracking-plan/references/autotrack-events.md` — SDK 自动采集事件定义（各平台事件列表 + SDK 类型映射）
+- `src/plan/types.ts` — Draft 的 TypeScript 类型定义