@macroui/event-tracker 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 macroui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,343 @@
+# @macroui/event-tracker
+
+> 自研的 Web 埋点 SDK，参考神策 sa-sdk-javascript 的 API 风格
+>
+> 4 种发送方式 / 全埋点 / WebView 桥 / 加密插件 —— 全 TypeScript 源码，全 Jest 单测
+
+[![Coverage](https://img.shields.io/badge/coverage-51%25-yellow)](.)
+[![Tests](https://img.shields.io/badge/tests-90%20passed-brightgreen)](.)
+[![License](https://img.shields.io/badge/license-MIT-blue)](.)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](.)
+
+## 特性
+
+- **多发送方式**：`image` / `beacon` / `ajax` / `batch`，自动降级
+- **多 sink 上报**：`server_url: string | string[]`
+- **预置事件**：`$pageview` / `$WebClick` / `$WebStay` / `$SignUp` / `$BindID` / `$UnbindID`
+- **公共属性**：`$lib` / `$app_id` / `$screen_width` / `$viewport_width` / `$url` / `$referrer` / `$latest_utm_*` ...
+- **用户身份**：`distinct_id` / `anonymous_id` / `first_id` / `login_id` / `original_id`
+- **3 阶段拦截器**：`buildDataStage` / `businessStage` / `sendDataStage`，priority 排序
+- **7 生命周期钩子**：`sdkReady` / `sdkInitPara` / `sdkAfterInitPara` / `sdkInitAPI` / `sdkAfterInitAPI` / `changeDistinctId` / `switch`
+- **加密插件**：XOR+Base64 / **AES-GCM（Web Crypto）**
+- **WebView 桥**：vapph5 协议，自动取 `app_version` / `app_id` / `channel`
+- **失败重试**：指数退避 1s→2s→4s→30s cap
+- **失败队列**：localStorage 暂存，断网时延后上报
+- **跨实例通信**：`BroadcastChannel`（localStorage 兜底）
+- **签名身份**：`HMAC-SHA256` 防 cookie 篡改
+- **13 个官方插件**：pageload / pageleave / exposure / session-event / debug-sender / indexeddb-sender / auto-track / webview-bridge / encrypt / etc.
+- **TypeScript**：完整 .d.ts，IDE 提示
+- **多格式**：`ESM` / `CJS` / `UMD` / `UMD-min`
+- **零依赖**：核心 SDK 无第三方依赖
+- **测试**：Jest 90 测试 / 15 套件 + fast-check 属性测试 + tsd 类型测试
+- **覆盖率**：51% lines（开发期阈值：30%）
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install @macroui/event-tracker
+```
+
+### 初始化（UMD）
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@macroui/event-tracker/dist/event-tracker.min.js"></script>
+<script>
+  eventTracker.init({
+    app_id: 'demo',
+    server_url: 'https://api.example.com/sa',
+    send_type: 'beacon', // 'image' | 'beacon' | 'ajax' | 'batch'
+    debug: 1,            // 0=关闭 1=basic 2=verbose
+  });
+  eventTracker.track('user_login', { method: 'email' });
+</script>
+```
+
+### ESM
+
+```ts
+import { EventTracker, pageLoad, sessionEvent } from '@macroui/event-tracker';
+
+const sdk = new EventTracker();
+sdk.init({
+  app_id: 'demo',
+  server_url: 'https://api.example.com/sa',
+  send_type: 'ajax',
+});
+
+sdk.use(pageLoad());
+sdk.use(sessionEvent());
+
+sdk.track('button_click', { btn_id: 'submit' });
+sdk.setProfile({ $city: 'Beijing', $plan: 'pro' });
+```
+
+### 多 sink / 多实例
+
+```ts
+sdk.switchServer(['https://primary.example.com/sa', 'https://backup.example.com/sa']);
+
+const tracker2 = initPara({
+  app_id: 'demo',
+  server_url: 'https://api2.example.com/sa',
+  client_id: 'm2',
+});
+```
+
+## API 一览
+
+### 事件
+
+| API | 说明 |
+|---|---|
+| `track(event, props, cb?)` | 自定义事件 |
+| `trackSignup(userId, props?, cb?)` | 注册即触发（$SignUp） |
+| `trackLinkage(props, cb?)` | 关联事件 |
+| `trackLink(el, props?, cb?)` | 单链接点击 |
+| `trackLinks(els, props?, cb?)` | 多链接点击 |
+| `trackHeatMap(props, cb?)` | 热力图事件 |
+| `trackWebClick(props, cb?)` | $WebClick |
+| `trackWebStay(props, cb?)` | $WebStay |
+| `alias(newId, originalId?)` | 合并身份 |
+
+### Profile
+
+| API | 说明 |
+|---|---|
+| `setProfile(props, cb?)` | 设置 |
+| `setOnceProfile(props, cb?)` | 仅首次 |
+| `incrementProfile(props, cb?)` | 累加 |
+| `appendProfile(props, cb?)` | 追加 |
+| `unsetProfile(prop, cb?)` | 取消 |
+| `deleteProfile(cb?)` | 删除 |
+
+### 身份
+
+| API | 说明 |
+|---|---|
+| `identify(id, save=true)` | 设置 distinct_id |
+| `login(id)` | 登录 |
+| `logout(newAnon?)` | 登出 + 重置匿名 |
+| `resetAnonymousIdentity(newAnon?)` | 同 logout |
+| `getDistinctId()` | 当前 distinct_id |
+| `getAnonymousId()` | 匿名 ID |
+| `getFirstId()` | 首次访问 ID |
+| `getLoginId()` | 登录 ID |
+| `getOriginalId()` | 登录前 ID |
+
+### 公共属性
+
+| API | 说明 |
+|---|---|
+| `register(props)` | 永久属性 |
+| `registerOnce(props)` | 一次性 |
+| `registerPage(props)` | 页面（一次性） |
+| `registerSession(props)` | 会话（永久） |
+| `registerSessionOnce(props)` | 会话（一次性） |
+| `clearAllRegister()` | 清空 |
+| `unsetRegister(key)` | 单个清空 |
+
+### 控制
+
+| API | 说明 |
+|---|---|
+| `flush()` | 强制 flush batch + failed queue |
+| `waitUntilIdle()` | 等待所有 in-flight 完成 |
+| `abort(reason?)` | Abort 所有挂起任务 |
+| `close()` / `shutdown()` | 完整关闭 |
+| `disable()` / `enable()` | 禁用 / 启用 |
+| `setServerURL(url)` | 切换 sink |
+| `use(plugin)` | 注册插件 |
+| `getPresetProperties()` | 当前 preset |
+
+## 插件
+
+13 个官方插件，按场景分组：
+
+### 自动采集
+- `pageLoad()` — $WebPageLoad（性能 API）
+- `pageLeave()` — $WebPageLeave（visibilitychange）
+- `exposure(opts)` — $element_exposure（IntersectionObserver）
+- `sessionEvent(opts)` — $session_start / $session_end
+- `autoTrack()` — pageview / webclick / webstay
+
+### 发送增强
+- `debugSender(opts)` — debug 模式（GET 到 ?debug URL + alert）
+- `indexedDBSender(opts)` — 写到 IDB outbox
+- `webviewBridge()` — vapph5 协议
+
+### 安全 / 隐私
+- `encryptor({ encrypt, decrypt?, encryptEvent?, decryptEvent? })` — 通用加密
+- `xorEncryptor(key)` — XOR+Base64 便捷工厂
+- `aesGcmEncryptAsync(key)` / `aesGcmDecryptAsync(key)` — AES-GCM
+
+## Plugin Authoring Guide
+
+写自定义插件非常简单：
+
+```ts
+import type { Plugin, InstallContext } from '@macroui/event-tracker';
+
+export function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+    install({ stages, config, sdk }: InstallContext) {
+      // 注册阶段拦截器
+      stages.sendDataStage.register({
+        name: 'my-modifier',
+        priority: 50,                         // 越大越晚
+        entry(ctx) {
+          // 修改 ctx.data（事件或属性）
+          if (ctx.data && ctx.data.properties) {
+            ctx.data.properties.$my_plugin = 'ran';
+          }
+        },
+      });
+    },
+    uninstall({ config }) {
+      // 清理工作：删除 config 字段、解除事件监听等
+    },
+  };
+}
+
+sdk.use(myPlugin());
+```
+
+### 阶段（stage）约定
+
+| 阶段 | 用途 | 推荐 priority |
+|---|---|---|
+| `buildDataStage` | 事件构造后，encrypt / send 之前 | 1-50（低） |
+| `businessStage` | 业务校验 / 转换 / 风控 | 50-150 |
+| `sendDataStage` | 实际发送 / 加密 / 落盘 | 100+（高） |
+
+### 生命周期钩子
+
+```ts
+install({ sdk }) {
+  sdk.getRegistry().on('sdkReady', (cfg) => { /* cfg: TrackerConfig */ });
+  sdk.getRegistry().on('changeDistinctId', (id) => { /* 用户切换身份 */ });
+}
+```
+
+钩子列表：`sdkReady` / `sdkInitPara` / `sdkAfterInitPara` / `sdkInitAPI` / `sdkAfterInitAPI` / `changeDistinctId` / `switch`
+
+## 加密 / 解密
+
+```ts
+import { encryptor, aesGcmEncryptAsync, aesGcmDecryptAsync } from '@macroui/event-tracker';
+
+sdk.use(encryptor({
+  encrypt: aesGcmEncryptAsync('my-32-byte-secret-key-1234567890ab'),
+  decrypt: aesGcmDecryptAsync('my-32-byte-secret-key-1234567890ab'),
+  encryptEvent: (e) => {
+    // 脱敏：去掉 PII 字段
+    if (e.properties?.phone) delete e.properties.phone;
+    return e;
+  },
+}));
+```
+
+> ⚠️ `aesGcmEncrypt` 同步版本仅做 API 完整性占位（Web Crypto 是异步的）；
+> 真同步场景请用 XOR（`xorEncryptor`）。
+
+## 失败处理
+
+SDK 包含三层失败保护：
+
+1. **重试**：`max_retry_count` × 指数退避（默认 3 次）
+2. **失败队列**：失败的事件入 localStorage，下次启动重发
+3. **`flush()`**：手动强制 flush batch + failed queue
+
+```ts
+sdk.track('important_event');
+await sdk.waitUntilIdle(); // 等待所有 in-flight
+
+// 出错捕获
+sdk.track('foo', {}, (err) => {
+  if (err) console.error('send failed:', err);
+});
+```
+
+## 从神策 v1.27 / v2.0 迁移
+
+| 神策 API | event-tracker | 状态 |
+|---|---|---|
+| `init(config)` | `init(config)` | ✅ 完全兼容字段名 |
+| `track(name, props)` | `track(name, props)` | ✅ |
+| `trackSignup(userId)` | `trackSignup(userId)` | ✅ |
+| `profileSet(props)` | `setProfile(props)` | ✅ 别名 `setProfile` |
+| `profileSetOnce(props)` | `setOnceProfile(props)` | ✅ |
+| `register(props)` | `register(props)` | ✅ |
+| `initPara(config)` | `initPara(config)` | ✅ |
+| `registerAppid(id)` | `registerAppid(id)` | ✅ |
+| `alias(newId)` | `alias(newId)` | ✅ |
+| `trackLinkage` / `trackLink` / `trackLinks` | 同名 | ✅ |
+| `trackHeatMap` / `trackWebClick` / `trackWebStay` | 同名 | ✅ |
+| `debug_mode` 集成 | `debugSender({ url })` 单独插件 | ⚠️ 需 use |
+| 38 个官方插件 | 13 个核心插件 | ⚠️ 关键已覆盖 |
+| 加密 `encode` | `encryptor({ encrypt })` | ⚠️ 插件化，需 use |
+
+## 开发
+
+```bash
+git clone https://github.com/macroui/event-tracker
+cd event-tracker
+npm install
+
+# 开发
+npm run typecheck      # tsc --noEmit
+npm run lint           # eslint
+npm test               # Jest
+npm run test:cov       # 覆盖率
+npm run test:bench     # 性能基准
+npm run test:types     # 类型测试（tsd）
+
+# 构建
+npm run build          # rollup + tsc-dts
+```
+
+## 架构
+
+```
+src/
+├── core/
+│   ├── tracker.ts          主类（init + 公共 getter）
+│   ├── track-api.ts        track 家族方法
+│   ├── identity-api.ts     identify / login / logout / alias
+│   ├── profile-api.ts      profile set/append/...
+│   ├── register-api.ts     register / registerOnce
+│   ├── send-pipeline.ts    sendEvent + flush + waitUntilIdle
+│   ├── identity.ts         IdentityManager
+│   ├── uuid.ts             UUID v4
+│   ├── logger.ts           日志
+│   ├── env.ts              浏览器能力
+│   ├── stage.ts            StageChain（3 阶段）
+│   ├── lifecycle.ts        7 生命周期钩子
+│   ├── plugin.ts           PluginRegistry
+│   ├── instance-channel.ts 跨实例通信
+│   ├── retry-policy.ts     指数退避
+│   ├── failed-queue.ts     失败队列
+│   ├── profile-store.ts    用户档案（v1.2）
+│   ├── signed-identity.ts  HMAC 签名
+│   ├── errors.ts           SDKError 体系
+│   └── instance-factory.ts initPara / registerAppid
+├── storage/                KVStore + IndexedDB
+├── send/                   ImageSender / BeaconSender / AjaxSender / BatchSender
+├── presets/                预置属性
+├── plugins/                13 个插件
+└── types/                  TrackerConfig（10 个子集）+ EventData + 常量
+```
+
+## 路线图
+
+- v1.0：基础 6 插件 ✅
+- v1.1：完整神策 API + 3 阶段 + 7 钩子 + 多 sink + 加密 + 重试 + 跨实例 ✅
+- v1.1.1：架构重构 + 类型分层 + 错误体系 + signedIdentity + 9 个测试套件 ✅
+- v1.2：plugin marketplace / web worker / WebAssembly 加密
+- v2.0：service worker / Source Map / 多端协议统一
+
+## 许可
+
+MIT

package/bin/event-tracker-suggest.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * event-tracker suggest — AI Event Suggestion (v1.3.0)
+ *
+ * 扫描项目源码中的 sdk.track 调用，分析：
+ *  - 事件名（按出现频次排序）
+ *  - 缺失的预置 property
+ *  - 命名规范违例（小写 / 中文 / emoji）
+ *  - 循环里调用警告
+ *
+ * 输出建议到 console + 可选 JSON
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve, extname, basename } from 'node:path';
+
+const TRACK_RE = /\bsdk\.track(?:Signup|Linkage)?\s*\(\s*['"`]([^'"`]+)['"`]/g;
+const LOOP_RE = /\b(for|while)\s*\([^)]*\)\s*\{[^}]*sdk\.track/s;
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const p = resolve(dir, e.name);
+    if (e.isDirectory()) {
+      if (['node_modules', 'dist', 'coverage', '.git', 'build'].includes(e.name)) continue;
+      yield* walk(p);
+    } else {
+      const ext = extname(p);
+      if (['.ts', '.tsx', '.js', '.jsx', '.vue'].includes(ext)) yield p;
+    }
+  }
+}
+
+const RULES = [
+  { name: 'should_be_english', test: (n: string) => !/^[\x20-\x7E]+$/.test(n), msg: '事件名建议纯 ASCII（兼容服务端解析）' },
+  { name: 'lowercase_only', test: (n: string) => /^[a-z][a-z0-9_]*$/.test(n), msg: '建议小写 + 下划线（snake_case）' },
+  { name: 'should_be_short', test: (n: string) => n.length <= 32, msg: '事件名建议 ≤ 32 字符' },
+];
+
+async function analyze(target: string): Promise<{
+  events: Record<string, number>;
+  loops: Array<{ file: string; line: number }>;
+  violations: Array<{ event: string; rule: string; msg: string }>;
+  suggestions: string[];
+}> {
+  const events: Record<string, number> = {};
+  const loops: Array<{ file: string; line: number }> = [];
+  const violations: Array<{ event: string; rule: string; msg: string }> = [];
+
+  for await (const file of walk(resolve(process.cwd(), target))) {
+    let content: string;
+    try { content = await readFile(file, 'utf8'); } catch { continue; }
+    const lines = content.split('\n');
+    let m: RegExpExecArray | null;
+    TRACK_RE.lastIndex = 0;
+    while ((m = TRACK_RE.exec(content)) !== null) {
+      const name = m[1];
+      events[name] = (events[name] || 0) + 1;
+      for (const r of RULES) {
+        if (!r.test(name)) violations.push({ event: name, rule: r.name, msg: r.msg });
+      }
+    }
+    for (let i = 0; i < lines.length; i++) {
+      if (LOOP_RE.test(lines[i])) {
+        loops.push({ file, line: i + 1 });
+      }
+      LOOP_RE.lastIndex = 0;
+    }
+  }
+
+  // 建议
+  const suggestions: string[] = [];
+  const sorted = Object.entries(events).sort((a, b) => b[1] - a[1]);
+  for (const [name, count] of sorted) {
+    if (count > 10) suggestions.push(`考虑把高频事件 '${name}' 加为预置事件（count=${count}）`);
+  }
+  if (loops.length) suggestions.push(`检测到 ${loops.length} 处循环内 sdk.track 调用，建议改用 batch send 或节流`);
+
+  return { events, loops, violations, suggestions };
+}
+
+const target = process.argv[2] || 'src';
+const jsonOut = process.argv.includes('--json');
+
+// 跳过命令本身
+analyze(target).then((res) => {
+  if (jsonOut) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(res, null, 2));
+    return;
+  }
+  // eslint-disable-next-line no-console
+  console.log(`\n📊 Event Suggestion Report  (target: ${target})\n`);
+  // eslint-disable-next-line no-console
+  console.log('事件统计：');
+  for (const [name, count] of Object.entries(res.events).sort((a, b) => b[1] - a[1])) {
+    // eslint-disable-next-line no-console
+    console.log(`  ${String(count).padStart(4)}  ${name}`);
+  }
+  if (res.violations.length) {
+    // eslint-disable-next-line no-console
+    console.log(`\n❌ 命名违例（${res.violations.length}）：`);
+    const grouped: Record<string, Array<{ event: string; msg: string }>> = {};
+    for (const v of res.violations) {
+      (grouped[v.rule] ||= []).push({ event: v.event, msg: v.msg });
+    }
+    for (const [rule, list] of Object.entries(grouped)) {
+      // eslint-disable-next-line no-console
+      console.log(`  [${rule}] ${list.length} 次`);
+      for (const it of list.slice(0, 3)) {
+        // eslint-disable-next-line no-console
+        console.log(`    - ${it.event}: ${it.msg}`);
+      }
+    }
+  }
+  if (res.loops.length) {
+    // eslint-disable-next-line no-console
+    console.log(`\n⚠️  循环内调用（${res.loops.length}）：`);
+    for (const l of res.loops.slice(0, 5)) {
+      // eslint-disable-next-line no-console
+      console.log(`  ${l.file}:${l.line}`);
+    }
+  }
+  if (res.suggestions.length) {
+    // eslint-disable-next-line no-console
+    console.log(`\n💡 建议：`);
+    for (const s of res.suggestions) {
+      // eslint-disable-next-line no-console
+      console.log(`  - ${s}`);
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log('');
+}).catch((e) => {
+  // eslint-disable-next-line no-console
+  console.error('suggest failed:', e);
+  process.exit(1);
+});
+// keep basename used to avoid unused var warning
+void basename;

package/bin/event-tracker.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * event-tracker CLI (v1.2.0)
+ *
+ * Usage:
+ *   npx event-tracker init       生成初始化代码片段
+ *   npx event-tracker dev        启动本地 mock server
+ *   npx event-tracker analyze    分析 SDK 产物大小（须先 build）
+ *
+ * 不强制依赖：纯 ESM CLI，单文件 0 依赖
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const HELP = `event-tracker CLI (v1.3.0)
+
+Commands:
+  init [target] 生成初始化代码片段（vue/react/html/node）
+  dev          启动 mock 上报服务（端口 8888）
+  analyze      分析 dist/ 下产物大小（含 visualizer）
+  suggest [dir] AI 事件埋点建议（基于源码扫描）
+  help         帮助
+`;
+
+function printInit(target: string): void {
+  const T = (target || 'html').toLowerCase();
+  const snippets: Record<string, string> = {
+    html: `<script src="https://unpkg.com/@macroui/event-tracker@latest/dist/event-tracker.min.js"></script>
+<script>
+  eventTracker.init({
+    app_id: 'demo',
+    server_url: 'https://api.example.com/sa',
+    send_type: 'beacon',
+  });
+  eventTracker.track('PageView', { $referrer: document.referrer });
+</script>`,
+    vue: `import eventTracker from '@macroui/event-tracker';
+eventTracker.init({
+  app_id: import.meta.env.VITE_APP_ID,
+  server_url: import.meta.env.VITE_SA_URL,
+  send_type: 'beacon',
+});
+// 在 main.ts 调用即可`,
+    react: `import eventTracker from '@macroui/event-tracker';
+eventTracker.init({
+  app_id: process.env.REACT_APP_SA_APP_ID!,
+  server_url: process.env.REACT_APP_SA_URL!,
+  send_type: 'beacon',
+});
+// 在 index.tsx 顶层调用`,
+    node: `import { initPara } from '@macroui/event-tracker';
+const sdk = initPara({
+  app_id: 'node-app',
+  server_url: 'https://api.example.com/sa',
+  send_type: 'ajax',
+});
+sdk.track('ServerStart', { $pid: process.pid });`,
+  };
+  // eslint-disable-next-line no-console
+  console.log(snippets[T] || snippets.html);
+}
+
+async function startDev(): Promise<void> {
+  const { createServer } = await import('node:http');
+  const port = Number(process.env.PORT || 8888);
+  const srv = createServer((req, res) => {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      // eslint-disable-next-line no-console
+      console.log(`[mock] ${req.method} ${req.url} body=${body.slice(0, 200)}`);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, received: body.length }));
+    });
+  });
+  srv.listen(port, () => {
+    // eslint-disable-next-line no-console
+    console.log(`[event-tracker mock] listening on http://localhost:${port}`);
+  });
+}
+
+async function analyze(): Promise<void> {
+  const distDir = resolve(process.cwd(), 'dist');
+  if (!existsSync(distDir)) {
+    // eslint-disable-next-line no-console
+    console.error('dist/ not found, run `npm run build` first.');
+    process.exit(1);
+  }
+  const { readdir, stat } = await import('node:fs/promises');
+  const files = await readdir(distDir);
+  const rows: Array<{ name: string; size: number; gzip: number }> = [];
+  for (const f of files) {
+    const p = resolve(distDir, f);
+    let s;
+    try { s = await stat(p); } catch { continue; }
+    if (!s.isFile()) continue;
+    if (f.endsWith('.map')) continue;
+    let gzip = 0;
+    if (f.endsWith('.js') || f.endsWith('.cjs') || f.endsWith('.mjs')) {
+      try {
+        const buf = await readFile(p);
+        const { gzipSync } = await import('node:zlib');
+        gzip = gzipSync(buf).length;
+      } catch { /* ignore */ }
+    }
+    rows.push({ name: f, size: s.size, gzip });
+  }
+  rows.sort((a, b) => b.size - a.size);
+  // eslint-disable-next-line no-console
+  console.log('File                              Size       Gzip');
+  for (const r of rows) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `${r.name.padEnd(40)}${(r.size / 1024).toFixed(2).padStart(8)}KB  ${(r.gzip / 1024).toFixed(2).padStart(8)}KB`,
+    );
+  }
+  const vizPath = resolve(distDir, 'stats.html');
+  // eslint-disable-next-line no-console
+  console.log(`\n可视化报告：${existsSync(vizPath) ? '✅ ' + vizPath : '❌ 未生成（运行 ANALYZE=1 npm run visualize 重新 build）'}`);
+}
+
+const [, , cmd, arg] = process.argv;
+switch (cmd) {
+  case 'init':
+    printInit(arg);
+    break;
+  case 'dev':
+    void startDev();
+    break;
+  case 'analyze':
+    void analyze();
+    break;
+  case 'suggest': {
+    // delegate to event-tracker-suggest.mjs
+    const { spawn } = await import('node:child_process');
+    const target = arg || 'src';
+    const isJson = process.argv.includes('--json');
+    const child = spawn(process.execPath, [
+      new URL('./event-tracker-suggest.mjs', import.meta.url).pathname,
+      target,
+      ...(isJson ? ['--json'] : []),
+    ], { stdio: 'inherit' });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    break;
+  }
+  case 'help':
+  case undefined:
+    // eslint-disable-next-line no-console
+    console.log(HELP);
+    break;
+  default:
+    // eslint-disable-next-line no-console
+    console.error(`Unknown command: ${cmd}\n${HELP}`);
+    process.exit(1);
+}