ae-tracking 0.1.0

package/skills/generate-tracking-plan/references/autotrack-events.md

@@ -0,0 +1,238 @@
+# SDK 自动采集事件定义（内部参考）
+
+> 本文件定义各平台 SDK 的自动采集事件，供 `generate-tracking-plan` skill 在 Phase 2
+> 自动注入到 draft 中使用。
+
+---
+
+## 事件注入规则
+
+1. 根据 `meta.sdk_type` 选择对应平台的自动采集事件
+2. 注入的事件标记 `source: "autotrack"`，与 `template/prd/chat` 区分
+3. 自动采集事件的事件属性只包含预置属性（以 `#` 开头），不包含自定义属性
+4. 预置属性不需要在 `event_properties` 池中定义，由 SDK 自动采集
+
+---
+
+## Android SDK
+
+### 事件列表
+
+| 事件名 | 显示名 | 事件说明 | 预置属性 |
+|---|---|---|---|
+| `ta_app_install` | APP 安装 | APP 首次安装时上报，升级不触发，删除重装会触发 | — |
+| `ta_app_start` | APP 启动 | 用户开启 APP 或从后台唤醒时触发 | `#resume_from_background`, `#start_reason`, `#background_duration` |
+| `ta_app_end` | APP 关闭 | 用户关闭 APP 或将 APP 调至后台时触发 | `#duration` |
+| `ta_app_view` | APP 页面浏览 | 用户浏览 Activity 时触发 | `#screen_name`, `#title`, `#url`, `#referrer` |
+| `ta_app_click` | APP 控件点击 | 用户点击控件时触发 | `#screen_name`, `#title`, `#element_id`, `#element_type`, `#element_content`, `#element_position`, `#element_selector` |
+| `ta_app_crash` | APP 崩溃 | APP 出现未捕获异常时上报 | `#app_crashed_reason` |
+
+### Draft JSON 示例
+
+```json
+{
+  "event_name": "ta_app_install",
+  "display_name": "APP 安装",
+  "event_desc": "APP 首次安装时上报，升级不触发，删除重装会触发",
+  "event_tag": "系统事件",
+  "prop_names": [],
+  "source": "autotrack"
+}
+```
+
+---
+
+## iOS SDK
+
+### 事件列表
+
+与 Android SDK 一致，事件名相同：
+
+| 事件名 | 显示名 | 事件说明 |
+|---|---|---|
+| `ta_app_install` | APP 安装 | APP 首次安装时上报 |
+| `ta_app_start` | APP 启动 | 用户开启 APP 或从后台唤醒 |
+| `ta_app_end` | APP 关闭 | 用户关闭 APP 或进入后台 |
+| `ta_app_view` | APP 页面浏览 | 用户切换 ViewController |
+| `ta_app_click` | APP 控件点击 | 用户点击控件 |
+| `ta_app_crash` | APP 崩溃 | APP 出现未捕获异常 |
+
+### iOS 特有事件
+
+| 事件名 | 显示名 | 说明 | 预置属性 |
+|---|---|---|---|
+| `ta_app_bg_start` | APP 后台启动 | APP 在后台启动时触发（需开启配置） | — |
+
+---
+
+## JavaScript SDK（Web / H5）
+
+### 事件列表
+
+| 事件名 | 显示名 | 事件说明 | 预置属性 |
+|---|---|---|---|
+| `ta_pageview` | 页面浏览 | 调用 `ta.quick("autoTrack")` 时上报 | `#url`, `#referrer`, `#title` |
+| `ta_page_show` | 页面显示 | 页面显示时触发（需开启配置） | — |
+| `ta_page_hide` | 页面隐藏 | 页面隐藏时触发（需开启配置） | `#duration` |
+
+---
+
+## 小程序 SDK
+
+### 事件列表
+
+| 事件名 | 显示名 | 事件说明 | 预置属性 |
+|---|---|---|---|
+| `ta_mp_launch` | 小程序初始化 | 小程序被首次打开时触发，进程生命周期内只触发一次 | `#scene`, `#start_reason` |
+| `ta_mp_show` | 小程序启动 | 小程序被启动或从后台调回前台时触发 | `#scene`, `#url_path`, `#start_reason` |
+| `ta_mp_hide` | 小程序隐藏 | 小程序被调入后台时触发 | `#scene`, `#duration` |
+| `ta_mp_view` | 小程序页面浏览 | 页面被打开或从后台调回前台时触发 | `#scene`, `#url_path`, `#referrer` |
+| `ta_mp_share` | 小程序转发分享 | 转发按钮被点击时触发 | `#scene`, `#url_path` |
+| `ta_page_leave` | 小程序页面卸载 | 页面卸载时触发 | `#duration`, `#url_path` |
+| `ta_add_favorite` | 小程序页面收藏 | 页面被收藏时触发 | `#url_path` |
+| `ta_mp_click` | 小程序元素点击 | 页面元素被点击时触发 | `#element_id`, `#element_type`, `#element_content`, `#element_name` |
+
+### 平台支持矩阵
+
+| 事件 | 微信小程序 | 微信小游戏 | 抖音小程序 | 支付宝小程序 | 其他小程序 |
+|---|---|---|---|---|---|
+| `ta_mp_launch` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `ta_mp_show` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `ta_mp_hide` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `ta_mp_view` | ✅ | ❌ | ✅ | ✅ | ✅ |
+| `ta_mp_share` | ✅ | ❌ | ✅ | ✅ | 视平台 |
+| `ta_page_leave` | ✅ | ❌ | ✅ | ✅ | 视平台 |
+| `ta_add_favorite` | ✅ | ❌ | ❌ | ❌ | 视平台 |
+| `ta_mp_click` | ✅ | ❌ | ✅ | ✅ | 视平台 |
+
+---
+
+## Unity SDK
+
+### 事件列表
+
+| 事件名 | 显示名 | 事件说明 | 预置属性 |
+|---|---|---|---|
+| `ta_app_install` | APP 安装 | 首次安装后打开时触发 | — |
+| `ta_app_start` | APP 启动 | 游戏进入前台时触发 | `#resume_from_background` |
+| `ta_app_end` | APP 关闭 | 游戏进入后台时触发 | `#duration` |
+
+### 微信小游戏特殊事件
+
+| 事件名 | 显示名 | 说明 | 预置属性 |
+|---|---|---|---|
+| `ta_mg_launch` | 小游戏初始化 | 替代 `ta_app_install` | `#start_reason` |
+| `ta_mg_show` | 小游戏启动 | 替代 `ta_app_start` | `#start_reason` |
+| `ta_mg_hide` | 小游戏隐藏 | 替代 `ta_app_end` | `#duration` |
+
+---
+
+## 其他游戏引擎 SDK
+
+### Cocos2d-x / CocosCreator / LayaAir
+
+与 Unity SDK 一致，支持：
+- `ta_app_install` / `ta_app_start` / `ta_app_end`
+
+### Unreal SDK
+
+| 事件名 | 显示名 | 说明 |
+|---|---|---|
+| `ta_app_install` | APP 安装 | 首次安装时触发 |
+| `ta_app_start` | APP 启动 | 游戏进入前台 |
+| `ta_app_end` | APP 关闭 | 游戏进入后台 |
+
+---
+
+## 跨平台框架
+
+### React Native SDK
+
+继承原生 SDK（iOS/Android）的自动采集事件。
+
+### Flutter SDK
+
+继承原生 SDK（iOS/Android）的自动采集事件。
+
+### uni-app SDK
+
+| 平台 | 自动采集事件 |
+|---|---|
+| 微信小程序 | 继承小程序 SDK 自动采集事件 |
+| APP（iOS/Android） | 继承原生 SDK 自动采集事件 |
+| H5 | 继承 JavaScript SDK 自动采集事件 |
+
+---
+
+## 预置属性定义
+
+所有预置属性以 `#` 开头，由 SDK 自动采集。**预置属性不需要在埋点方案中定义**，
+但需要了解其含义以便分析使用。
+
+| 属性名 | 中文名 | 类型 | 适用事件 | 说明 |
+|---|---|---|---|---|
+| `#duration` | 事件时长 | number | `ta_app_end`, `ta_mp_hide`, `ta_page_hide` | 单位：秒 |
+| `#resume_from_background` | 是否从后台唤醒 | bool | `ta_app_start` | true=后台唤醒，false=直接启动 |
+| `#screen_name` | 页面名称 | string | `ta_app_view`, `ta_app_click` | Activity 类名 / ViewController 类名 |
+| `#title` | 页面标题 | string | `ta_app_view`, `ta_app_click` | 页面标题 |
+| `#url` | 页面地址 | string | `ta_app_view`, `ta_pageview` | 当前页面地址 |
+| `#referrer` | 前向地址 | string | `ta_app_view`, `ta_mp_view`, `ta_pageview` | 跳转前页面地址 |
+| `#url_path` | 页面路径 | string | 小程序事件 | 小程序页面路径 |
+| `#element_id` | 元素 ID | string | `ta_app_click`, `ta_mp_click` | 控件 ID |
+| `#element_type` | 元素类型 | string | `ta_app_click`, `ta_mp_click` | 控件类型 |
+| `#element_content` | 元素内容 | string | `ta_app_click`, `ta_mp_click` | 控件上的内容 |
+| `#element_position` | 元素位置 | string | `ta_app_click`, `ta_mp_click` | 控件位置信息 |
+| `#element_selector` | 元素选择器 | string | `ta_app_click` | viewPath 拼接 |
+| `#element_name` | 元素名称 | string | `ta_mp_click` | 小程序元素名称 |
+| `#app_crashed_reason` | 异常信息 | string | `ta_app_crash` | 崩溃堆栈信息 |
+| `#scene` | 场景值 | number | 小程序事件 | 小程序启动场景值 |
+| `#start_reason` | 启动原因 | string | `ta_app_start`, `ta_mp_launch`, `ta_mp_show` | JSON 字符串，启动来源信息 |
+| `#background_duration` | 后台停留时长 | number | `ta_app_start` | 单位：秒 |
+
+---
+
+## SDK 类型 → 自动采集事件映射
+
+```typescript
+type SDKType =
+  | 'android'
+  | 'ios'
+  | 'javascript'
+  | 'wechat_mp'      // 微信小程序
+  | 'wechat_mg'      // 微信小游戏
+  | 'douyin_mp'      // 抖音小程序
+  | 'alipay_mp'      // 支付宝小程序
+  | 'unity'
+  | 'unity_wxmg'     // Unity 微信小游戏
+  | 'cocos2dx'
+  | 'cocoscreator'
+  | 'layaair'
+  | 'unreal'
+  | 'react_native'
+  | 'flutter'
+  | 'uniapp_mp'      // uni-app 小程序端
+  | 'uniapp_app'     // uni-app APP端
+  | 'uniapp_h5'      // uni-app H5端
+  ;
+
+function getAutotrackEvents(sdkType: SDKType): Event[] {
+  // 根据 sdkType 返回对应的自动采集事件数组
+}
+```
+
+### 映射规则
+
+| SDK 类型 | 自动采集事件 |
+|---|---|
+| `android` | install, start, end, view, click, crash |
+| `ios` | install, start, end, view, click, crash |
+| `javascript` | pageview, page_show, page_hide |
+| `wechat_mp` | launch, show, hide, view, share, page_leave, favorite, click |
+| `wechat_mg` | launch, show, hide |
+| `unity` | install, start, end |
+| `unity_wxmg` | mg_launch, mg_show, mg_hide |
+| `cocos2dx` / `cocoscreator` / `layaair` / `unreal` | install, start, end |
+| `react_native` / `flutter` | 继承原生（根据运行平台动态选择） |
+| `uniapp_mp` | 继承小程序 |
+| `uniapp_app` | 继承原生 |
+| `uniapp_h5` | 继承 JavaScript |

package/skills/generate-tracking-plan/references/te-api.md

@@ -0,0 +1,97 @@
+# AE 后台 API（内部参考）
+
+> 本文件是 `src/client.ts` 的实现依据，供内部贡献者维护。
+> **Skill 正文不应引用本文档** —— skill 使用方通过 CLI 命令交互，不关心底层端点。
+> xlsx 格式约定在 `xlsx-schema.md`，不在此文档。
+
+抓取环境：`https://web-ta-demo.thinkingdata.cn`。如接口变更，重走
+`docs/superpowers/plans/2026-04-15-ae-tracking-skill.md` Task 3 的 chrome-devtools 抓包流程。
+
+## 认证
+
+### Token
+- localStorage key：`ACCESS_TOKEN`
+- 存储形态：**JSON 编码字符串**（带双引号），使用前须 `replace(/^["']|["']$/g, '')`
+
+### 两种传 token 方式（按端点区分）
+- **GET/JSON 类接口**：Header `authorization: bearer <token>`（全小写）
+- **Excel 上传接口**：**form field `access_token`**，裸 UUID，**不用** Authorization header
+
+## 响应统一包装
+
+```json
+{ "return_code": 0, "return_message": "success", "showStackMessage": false, "data": ... }
+```
+- `return_code === 0` 为成功；非 0 抛错，取 `return_message`
+- 某些端点（如 `excel-save` / 空项目 `query`）成功时无 `data`
+
+## 端点
+
+### 1. GET `/v1/ta/bury/manage/program/query`
+
+获取项目唯一的埋点方案。
+
+- Query：`projectId` 必填 number
+- Header：`authorization: bearer <token>`
+- Response `data` 结构（事件池 / 事件属性池 / 公共属性 / 用户属性）：
+
+```jsonc
+{
+  "projectId": 1603,
+  "events": [
+    { "eventName": "...", "displayName": "...", "eventDesc": "...", "eventTag": "...",
+      "props": ["prop_name", "parent.child"], "propInfosOnEvent": [{"name":"...","hasReported":false}] }
+  ],
+  "eventProps": [ { "name": "...", "displayName": "...", "type": "string", "desc": "..." } ],
+  "commonEventProps": [ /* 同 eventProps */ ],
+  "userProps": [
+    { "name": "...", "displayName": "...", "type": "datetime",
+      "propTag": "时间类", "updateType": "user_setOnce" }
+  ]
+}
+```
+
+空项目：`data` 不存在，直接 `{ return_code: 0, return_message: "success" }`。
+
+### 2. GET `/v1/ta/bury/manage/program/delete?projectId=<id>`
+
+一次清空整个项目的方案（事件 / 事件属性 / 公共属性 / 用户属性）。
+
+### 3. POST `/v1/ta/bury/manage/program/excel-save`
+
+批量上传 xlsx。
+
+- Content-Type：`multipart/form-data`
+- Form fields（全必填）：
+  - `file` — xlsx 二进制
+  - `projectId` — 文本
+  - `access_token` — 文本，裸 UUID
+- **无** Authorization header
+- Response：`{ return_code: 0, return_message: "success" }`（无 data）
+
+**合并语义**：对事件走 **merge-by-name**（同名不覆盖、新名新增）。若要完全替换，
+必须先调 `delete` 端点清空再上传。
+
+## 类型枚举（AE 后端接受值）
+
+### PropType（事件属性 / 公共属性 / 用户属性 `type` 字段）
+| canonical | 说明 |
+|---|---|
+| `string` | 文本 |
+| `number` | 数值 |
+| `bool` | 布尔 |
+| `datetime` | 日期时间 |
+| `array_row` | 对象数组（允许 `父名.子名` 嵌套子属性） |
+| `array_string` | 字符串数组 |
+
+### UpdateType（用户属性 `updateType` 字段）
+| canonical | 语义 |
+|---|---|
+| `user_set` | 覆盖赋值 |
+| `user_setOnce` | 仅首次赋值 |
+| `user_add` | 数值累加 |
+
+## v2（暂未实现）
+
+- UI「逐个添加」通向单事件 CRUD 接口（`POST /v1/ta/bury/manage/event/*` 族），v1 走 excel-save 统一入口
+- 列项目、校验错误响应等见 plan 文档的"未抓端点"清单

package/skills/generate-tracking-plan/references/xlsx-schema.md

@@ -0,0 +1,149 @@
+# AE 埋点方案 xlsx 格式契约（内部参考）
+
+> `src/xlsx/{read,write}.ts` 实现依据。SKILL 不读此文档。
+
+官方模板：`tracking-plan-template/TE官方模板_dataTrackSample.xlsx`（从 AE 后台
+`/downloads/zh/dataTrackSample.xlsx` 下载）。所有字段规则以此模板为准，行业模板
+（电商/卡牌/社交/阅读）做读取兼容，不做 writer 适配。
+
+---
+
+## 写 xlsx 必须遵守的 3 条硬规则（端到端验证过）
+
+以下任一违反 → `excel-save` 返回 `return_code=0 success`，但**数据静默不落库**：
+
+### 规则 1. 必填列 header 带 `（必填）` 后缀
+- `事件名（必填）`、`属性名（必填）`、`属性类型（必填）`
+- 没有 `（必填）`，后端会丢弃整张 sheet 的数据
+
+### 规则 2. `#事件数据` 的事件字段列（A-D）跨多行必须**合并单元格**
+- 同一事件有多个属性时，A-D 列在 row N 到 row M 之间用 `mergeCells('A{N}:A{M}')` 合并
+- 否则后端按行级字符串匹配，报错 `事件名重复`
+- 官方模板就是合并单元格，SheetJS 读出来 row2+ 的 event 字段为 `null`（这是合并单元格的副作用）
+
+### 规则 3. 工作簿必须存在 `#用户ID体系` sheet
+- 即使只写一行 header 也行（内容可以全空）
+- 缺失整张 sheet → 后端丢弃整份方案
+
+---
+
+## Sheet 清单
+
+工作簿的 `#` 前缀 sheet 是数据 sheet，AE 后端只读这几张；其它（`接入必知`、
+`数据类型设计原则` 等）是说明文档，**写 xlsx 时不需要生成**。
+
+| Sheet | 含义 | 写 xlsx 策略 |
+|---|---|---|
+| `#事件数据` | 事件 × 属性展开（见规则 2） | 生成并合并 A-D 列 |
+| `#公共事件属性` | 公共属性定义 | 逐行生成 |
+| `#用户数据` | 用户属性定义（含更新方式） | 逐行生成 |
+| `#用户ID体系` | 系统预置属性说明 | **仅写 header 占位**（见规则 3） |
+
+### `#事件数据` 列定义（A→I）
+
+| 列 | 列名 | 必填 | 对应字段 |
+|---|---|---|---|
+| A | `事件名（必填）` | ✅ | `eventName` / `Event.event_name` |
+| B | `事件显示名` | 否 | `displayName` |
+| C | `事件说明` | 否 | `eventDesc` |
+| D | `事件标签` | 否 | `eventTag` |
+| E | `采集端` | 否 | `platform`（见下） |
+| F | `属性名（必填）` | ✅ | 属性 `name`（允许 `父.子`） |
+| G | `属性显示名` | 否 | 属性 `displayName` |
+| H | `属性类型（必填）` | ✅ | 类型中文值，见类型表 |
+| I | `属性说明` | 否 | 属性 `desc` |
+
+**采集端列（E）的值**：
+| `platform` 值 | xlsx 写入值 |
+|---|---|
+| `client` | `client` |
+| `server` | `server` |
+| `both` | `client,server` |
+| `undefined` | （留空） |
+
+**行语义**：一行一对 `(event, property)`。同一事件多属性时，A-E 按事件字段填写，F-I 按属性变化，
+A-E 在 writer 里用 `mergeCells` 合并。
+
+**property-less 事件**（罕见）：仍写一行，A-D 填事件字段，E-H 全空。AE 接受，
+但不推荐——建议至少给一个有语义的属性（例如 `user_logout` 加 `session_duration_ms`）。
+
+### `#公共事件属性` 列定义（A→D）
+
+| 列 | 列名 | 必填 |
+|---|---|---|
+| A | `属性名（必填）` | ✅ |
+| B | `属性显示名` | 否 |
+| C | `属性类型（必填）` | ✅ |
+| D | `属性说明` | 否 |
+
+### `#用户数据` 列定义（A→F）
+
+| 列 | 列名 | 必填 |
+|---|---|---|
+| A | `属性名（必填）` | ✅ |
+| B | `属性显示名` | 否 |
+| C | `属性类型（必填）` | ✅ |
+| D | `更新方式` | 否（默认视为 `user_set`） |
+| E | `属性说明` | 否 |
+| F | `属性标签` | 否 |
+
+**D 列直接填英文 canonical 值**：`user_set` / `user_setOnce` / `user_add`，不翻译中文。
+
+---
+
+## 类型枚举
+
+### PropType（xlsx 中文值 ↔ canonical）
+
+| canonical（draft.json） | xlsx 写入值 | xlsx 读取可接受值（含行业 alias） |
+|---|---|---|
+| `string` | `文本` | `文本` / `字符串` |
+| `number` | `数值` | `数值` / `数量` |
+| `bool` | `布尔` | `布尔` |
+| `datetime` | `时间` | `时间` |
+| `array_row` | `对象组` | `对象组` / `对象`（fallback） |
+| `array_string` | `列表` | `列表` |
+
+Writer 方向统一用第二列（官方中文正式名），不输出 alias。
+Reader 方向对 alias / 未知值做 fallback 并打 stderr warning。
+
+### UpdateType（用户属性 `更新方式`）
+
+| canonical | 语义 |
+|---|---|
+| `user_set` | 覆盖赋值（默认） |
+| `user_setOnce` | 仅首次赋值 |
+| `user_add` | 数值累加 |
+
+xlsx 里填写英文 canonical 值本身，不翻译。
+
+官方文档提及 `user_append`（字符串数组追加），样本中无实例，暂不实现。
+
+---
+
+## Reader 兼容规则（从 xlsx → Draft）
+
+- `.claude` 之外工作簿里只读 `#` 前缀 sheet
+- header 规范化：strip `（必填）` / `(必填)` 后缀，把 `名称` 归一化为 `名`
+- `#事件数据` 合并单元格读出来是 null → 用"继承上一行 event_name"策略还原
+- 属性列空、类型列空、prose / instruction 行 → skip
+- 行业模板额外前置列（`事件模块` / `属性分类`）通过 header 名查找，忽略不识别的列
+
+### 行业模板已知差异（只读取，不写入）
+
+| 模板 | 额外列 | 类型 alias | 其它 |
+|---|---|---|---|
+| 卡牌游戏 | `事件模块` / `属性分类` | `字符串` | 部分类型列空 |
+| 电商 | 部分 header 为空字符串（WPS 生成副作用） | — | 按列位置推断 |
+| 社交聊天 | `事件模块` / `属性分类` | `数量` | `更新方式` 含多行注释 |
+| 阅读类 | `事件模块` / `属性分类` | `字符串` | 同上 |
+
+写 xlsx 时**不**生成这些行业扩展列，统一输出官方 schema。
+
+---
+
+## 开放问题（记一下，不影响 v1）
+
+1. AE 后端是否区分 `object`（单对象）与 `array_row`（对象数组）—— 样本中无 `object` 实例，API 枚举里也没见
+2. `user_append` updateType 是否真的可用 —— 待构造测试
+3. 严格错误码 —— 所有校验失败目前都是 `return_code=0 success` + 静默丢弃，无法从响应区分成功/失败；UI 上传才显示错误文案

package/skills/te-wiki-synthesize/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: te-wiki-synthesize
+description: 基于 ~/.ae-tracking/wiki/te-docs/raw/ 和 index.md 综合输出主题页到 synthesis/。触发词：综合文档、wiki 整理、synthesize docs、生成综合页。走 load-index → propose-topics → dispatch-subagents → collect → log → commit 六步。
+---
+
+# te-wiki-synthesize
+
+## 何时触发
+
+由其他 skill（如埋点专家 skill）或用户显式调用，目标是将散落在 `~/.ae-tracking/wiki/te-docs/raw/` 下的 219 个原始页面归纳为若干主题综合页，输出到 `~/.ae-tracking/wiki/te-docs/synthesis/`。
+
+---
+
+## Phase 1 — Load Index
+
+读 `~/.ae-tracking/wiki/te-docs/index.md`，了解 raw/ 的页面覆盖与分类。
+
+**禁止**直接读 `raw/` 目录——raw 文件量巨大，直接读会污染主 agent 上下文。主 agent 在整个流程中仅读 `index.md`，不触碰 `raw/` 或 `synthesis/` 正文。
+
+---
+
+## Phase 2 — Propose Topics
+
+基于 index 内容动态归纳 3–8 个综合主题。参考方向（按 index 实际覆盖决定，非固定）：
+
+| 建议主题 slug | 方向描述 |
+|---|---|
+| `sdk-selection` | SDK 选型矩阵（客户端 vs 服务端 vs 批量导入） |
+| `js-sdk-cheatsheet` | JS / H5 / 小程序 SDK 速查 |
+| `mobile-sdk-cheatsheet` | iOS / Android / Unity SDK 速查 |
+| `log-ingestion` | 日志接入方案对比（logbus / datax / kafka） |
+| `restful-api-reference` | RESTful 接口速查 |
+| `debug-checklist` | Debug 与数据校验流程 |
+| `identity-system` | 用户 ID 体系 / 属性体系 |
+
+每个主题需关联至少 3 个 raw 源文件；否则合并到相近主题或放弃。确定主题列表后向用户展示（一行一条），等待 `ok` 或调整意见后再进入 Phase 3。
+
+---
+
+## Phase 3 — Dispatch Subagents（并行）
+
+每个主题派发一个 subagent，每批并行 3–4 个（避免 token 风暴）。
+
+### Subagent 入参
+
+```json
+{
+  "topic": "<主题名（中文）>",
+  "rawPaths": ["~/.ae-tracking/wiki/te-docs/raw/xxx.md", "..."],
+  "outPath": "~/.ae-tracking/wiki/te-docs/synthesis/<slug>.md"
+}
+```
+
+### Subagent 执行步骤
+
+1. 读 `rawPaths` 指向的所有文件
+2. 写综合页到 `outPath`，格式要求见下方「综合页格式」
+3. 返回 `{ status: "ok"|"fail", title: string, outPath: string, reason?: string }`
+   **不回传正文**（主 agent 只看标题和文件名）
+
+### 综合页格式
+
+```markdown
+---
+topic: <主题名>
+sources:
+  - raw/xxx.md
+  - raw/yyy.md
+generated: <ISO date, e.g. 2026-04-15>
+---
+
+# <主题名>
+
+<正文>
+```
+
+正文规则：
+
+- **选型 / 决策类**主题：用 Markdown 表格对比各方案
+- **速查 / API 类**主题：代码片段 + 简短说明
+- 每个论点必须追溯到某个 raw 文件，行内标注 `[[raw/xxx.md]]`
+- 不引外网 URL；如需外链，只引 raw 文件 frontmatter 里的 `sourceUrl`
+- 每篇综合页至少引用 3 个不同 raw 源；不足 3 个的主题不单独成文
+
+---
+
+## Phase 4 — Collect Results
+
+主 agent 汇总各 subagent 返回值：
+
+- `ok`：记录 `title`、`outPath`、源文件数
+- `fail`：记录 `reason`，提示用户是否跳过或重试
+
+主 agent **不读** synthesis 正文，仅依据标题和文件名判断结果。
+
+---
+
+## Phase 5 — 追加日志
+
+在 `~/.ae-tracking/wiki/te-docs/log.md` 末尾追加一个段落：
+
+```markdown
+## Synthesis (<ISO date>)
+
+| 主题 | 文件 | 源文件数 |
+|---|---|---|
+| <title> | synthesis/<slug>.md | <n> |
+| ... | ... | ... |
+```
+
+---
+
+## Phase 6 — Commit
+
+```bash
+git add ~/.ae-tracking/wiki/te-docs/synthesis ~/.ae-tracking/wiki/te-docs/log.md
+git commit -m "feat(wiki): synthesis pages for <N> topics"
+```
+
+---
+
+## 约束
+
+- `synthesis/*.md` 只写不读——subagent 写完即 exit，不做反复迭代
+- 主 agent 全程不读 `raw/` 或 `synthesis/` 正文
+- 禁止修改 `raw/` 下任何文件
+- 每篇 synthesis 至少引用 3 个 raw 源；不足则合并或跳过
+
+---
+
+## 产物示例
+
+```
+~/.ae-tracking/wiki/te-docs/synthesis/
+├── sdk-selection.md
+├── js-sdk-cheatsheet.md
+├── mobile-sdk-cheatsheet.md
+├── log-ingestion.md
+├── restful-api-reference.md
+├── debug-checklist.md
+└── identity-system.md
+```