ae-tracking 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.1.0 (2026-05-11)
+
+### Overview
+
+AE (AgenticEngine) tracking-plan agent. Claude Code skills for full lifecycle tracking management — from plan generation to code deployment.
+
+### Features
+
+**generate-tracking-plan skill**: Create AE tracking plans from templates, PRD, codebase, or conversation.
+
+- Source types: template / prd / codebase / chat / website
+- Client SDKs: Android (Java/Kotlin), iOS (Obj-C/Swift), OpenHarmony, JavaScript, Mini-program, Unity, Cocos
+- Server SDKs: Java, Python, Go, Node.js, PHP, C#
+- Modes: client_only / server_only / both
+- Event platform: client / server / both (written to xlsx "采集端" column)
+
+**generate-tracking-code skill**: Generate SDK code from plan.
+
+- Output: snippet (file) or insert (into project)
+- Platform filter: client code includes events with platform=client/both; server code includes events with platform=server/both
+- Server: LoggerConsumer + LogBus2 architecture
+
+**xlsx import/export**:
+
+- `ae-tracking code import-xlsx`: Parse xlsx to draft.json, infer sdk_integration_mode from "采集端" column
+- `ae-tracking plan draft`: Generate xlsx with "采集端" column (client/server/client,server)
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `auth login/status/clear` | AE authentication (Chrome/Safari token extraction) |
+| `plan draft/upload/fetch/delete/validate` | Plan management |
+| `code import-xlsx/dryrun` | Code generation helpers |
+| `wiki sync/query` | AE documentation sync |
+| `init` | Initialize skill symlinks |
+
+### Dependencies
+
+- Node.js ≥ 20
+- exceljs, undici, commander

package/README.md

@@ -0,0 +1,50 @@
+# ae-tracking
+
+AE（AgenticEngine）埋点上报 CLI + Claude Code skill bundle.
+
+## Install
+
+```bash
+npm install -g ae-tracking
+ae-tracking init       # symlink skills into ~/.claude/skills/
+ae-tracking auth login
+```
+
+macOS pulls the token from Chrome automatically (requires "Allow JavaScript from Apple Events" enabled). Other platforms: paste the token when prompted.
+
+## Commands
+
+```
+ae-tracking init [--force] [--uninstall]
+ae-tracking plan {draft,validate,upload,fetch,delete}
+ae-tracking code dryrun
+ae-tracking auth {login,status,clear}
+ae-tracking wiki {query,sync}
+ae-tracking debug {device,send,watch}
+
+```
+
+Run `ae-tracking <group> --help` for details.
+
+## Skills
+
+After `init`, three Claude Code skills become available globally:
+
+- `generate-tracking-plan` — interactive tracking plan creation and upload
+- `generate-tracking-code` — generate SDK code / configs from an uploaded plan
+- `te-wiki-synthesize` — synthesize topic pages from the bundled AE docs wiki
+
+## Development
+
+```bash
+git clone <repo>
+cd ae-tracking
+npm install
+npm link          # makes `ae-tracking` point at this checkout
+npm run build
+npm test
+```
+
+## License
+
+TBD

package/dist/bin/ae-tracking.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/ae-tracking.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// bin/ae-tracking.ts
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import { registerAuth } from '../src/cli/auth.js';
+import { registerPlan } from '../src/cli/plan.js';
+import { registerCode } from '../src/cli/code.js';
+import { registerWiki } from '../src/cli/wiki.js';
+import { registerDebug } from '../src/cli/debug.js';
+import { registerInit } from '../src/cli/init.js';
+const req = createRequire(import.meta.url);
+const pkg = req('../../package.json');
+const program = new Command('ae-tracking').version(pkg.version);
+registerAuth(program.command('auth'));
+registerPlan(program.command('plan'));
+registerCode(program.command('code'));
+registerWiki(program.command('wiki'));
+registerDebug(program.command('debug'));
+registerInit(program.command('init'));
+await program.parseAsync();

package/dist/scripts/postinstall.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/postinstall.js

@@ -0,0 +1,17 @@
+// scripts/postinstall.ts
+import { runInit } from '../src/cli/init.js';
+async function main() {
+    try {
+        const report = await runInit({ quiet: true });
+        if (report.installed.length > 0) {
+            console.log(`ae-tracking: installed ${report.installed.length} skill(s) into ~/.claude/skills/`);
+        }
+        if (report.conflicts.length > 0) {
+            console.warn(`ae-tracking: ${report.conflicts.length} skill(s) had conflicts; run 'ae-tracking init --force' to resolve`);
+        }
+    }
+    catch (e) {
+        console.warn(`ae-tracking: postinstall skipped (${e.message}); run 'ae-tracking init' manually`);
+    }
+}
+main();

package/dist/src/auth.d.ts

@@ -0,0 +1,12 @@
+export declare function loadToken(hostUrl: string): {
+    host: string;
+    token: string;
+    updatedAt: string;
+} | null;
+export declare function saveToken(token: string, hostUrl: string): void;
+export declare function clearToken(hostUrl: string): void;
+export declare function resolveHost(override?: string): string;
+export declare function getToken(hostUrl: string): Promise<{
+    token: string;
+    browser?: string;
+}>;

package/dist/src/auth.js

@@ -0,0 +1,215 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getConfigDir, getActiveHost, extractHostname } from './config.js';
+const TOKEN_TTL_MS = 20 * 60 * 60 * 1000; // 20 hours
+const POLL_INTERVAL_MS = 2000;
+const POLL_TIMEOUT_MS = 60000;
+function tokensFile() {
+    return path.join(getConfigDir(), 'tokens.json');
+}
+function ensureDir() {
+    const dir = getConfigDir();
+    fs.mkdirSync(dir, { recursive: true });
+}
+function loadAllTokens() {
+    try {
+        if (fs.existsSync(tokensFile())) {
+            return JSON.parse(fs.readFileSync(tokensFile(), 'utf8'));
+        }
+    }
+    catch { }
+    return {};
+}
+function saveAllTokens(tokens) {
+    ensureDir();
+    fs.writeFileSync(tokensFile(), JSON.stringify(tokens, null, 2));
+}
+export function loadToken(hostUrl) {
+    const tokens = loadAllTokens();
+    const entry = tokens[hostUrl];
+    if (!entry || !entry.token)
+        return null;
+    if (entry.updatedAt) {
+        const age = Date.now() - new Date(entry.updatedAt).getTime();
+        if (age > TOKEN_TTL_MS) {
+            clearToken(hostUrl);
+            return null;
+        }
+    }
+    return { host: hostUrl, token: entry.token, updatedAt: entry.updatedAt };
+}
+export function saveToken(token, hostUrl) {
+    const tokens = loadAllTokens();
+    tokens[hostUrl] = { token, updatedAt: new Date().toISOString() };
+    saveAllTokens(tokens);
+}
+export function clearToken(hostUrl) {
+    const tokens = loadAllTokens();
+    delete tokens[hostUrl];
+    saveAllTokens(tokens);
+}
+export function resolveHost(override) {
+    if (override)
+        return override;
+    return getActiveHost();
+}
+function extractViaOsascript(hostUrl) {
+    if (process.platform !== 'darwin')
+        return { token: null, error: 'not_mac' };
+    const hostname = extractHostname(hostUrl);
+    // 尝试 Chrome
+    const chromeResult = extractFromChrome(hostname);
+    if (chromeResult.token)
+        return { ...chromeResult, browser: 'Chrome' };
+    if (chromeResult.error === 'no_js_permission')
+        return { ...chromeResult, browser: 'Chrome' };
+    // 尝试 Safari（Chrome 未找到 tab 时）
+    const safariResult = extractFromSafari(hostname);
+    if (safariResult.token)
+        return { ...safariResult, browser: 'Safari' };
+    if (safariResult.error === 'no_js_permission')
+        return { ...safariResult, browser: 'Safari' };
+    // 都没找到
+    return { token: null, error: 'no_tab' };
+}
+function extractFromChrome(hostname) {
+    const lines = [
+        'tell application "Google Chrome"',
+        '  repeat with w in windows',
+        '    repeat with t in tabs of w',
+        `      if URL of t contains "${hostname}" then`,
+        '        return execute t javascript "localStorage.getItem(\'ACCESS_TOKEN\')"',
+        '      end if',
+        '    end repeat',
+        '  end repeat',
+        '  return "NO_TAB_FOUND"',
+        'end tell',
+    ];
+    try {
+        const args = lines.flatMap(line => ['-e', line]);
+        const result = execFileSync('osascript', args, { encoding: 'utf8', timeout: 5000 }).trim();
+        if (result === 'NO_TAB_FOUND')
+            return { token: null, error: 'no_tab' };
+        if (!result || result === 'missing value')
+            return { token: null, error: 'no_token' };
+        return { token: result.replace(/^["']|["']$/g, ''), error: null };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes('not allowed') || msg.includes('assistive access') || msg.includes('(-1743)')) {
+            return { token: null, error: 'no_js_permission' };
+        }
+        return { token: null, error: 'no_tab' };
+    }
+}
+function extractFromSafari(hostname) {
+    const lines = [
+        'tell application "Safari"',
+        '  repeat with w in windows',
+        '    repeat with t in tabs of w',
+        `      if URL of t contains "${hostname}" then`,
+        '        return do JavaScript "localStorage.getItem(\'ACCESS_TOKEN\')" in t',
+        '      end if',
+        '    end repeat',
+        '  end repeat',
+        '  return "NO_TAB_FOUND"',
+        'end tell',
+    ];
+    try {
+        const args = lines.flatMap(line => ['-e', line]);
+        const result = execFileSync('osascript', args, { encoding: 'utf8', timeout: 5000 }).trim();
+        if (result === 'NO_TAB_FOUND')
+            return { token: null, error: 'no_tab' };
+        if (!result || result === 'missing value')
+            return { token: null, error: 'no_token' };
+        return { token: result.replace(/^["']|["']$/g, ''), error: null };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes('not allowed') || msg.includes('assistive access')) {
+            return { token: null, error: 'no_js_permission' };
+        }
+        return { token: null, error: 'no_tab' };
+    }
+}
+async function openAndPoll(hostUrl) {
+    process.stderr.write(`[ae-tracking] No AE tab found in Chrome/Safari. Opening ${hostUrl} ...\n`);
+    process.stderr.write(`[ae-tracking] Please login in Chrome or Safari, then your token will be captured automatically.\n`);
+    process.stderr.write(`[ae-tracking] (If using other browser, manually set AE_TOKEN env var)\n`);
+    // 尝试打开 Chrome
+    try {
+        const chromeScript = [
+            'tell application "Google Chrome"',
+            '  activate',
+            '  if (count of windows) > 0 then',
+            `    make new tab at end of tabs of window 1 with properties {URL:"${hostUrl}"}`,
+            '  else',
+            `    open location "${hostUrl}"`,
+            '  end if',
+            'end tell',
+        ];
+        execFileSync('osascript', chromeScript.flatMap(line => ['-e', line]), { timeout: 5000 });
+    }
+    catch {
+        // Chrome 不存在，尝试 Safari
+        try {
+            const safariScript = [
+                'tell application "Safari"',
+                '  activate',
+                `  open location "${hostUrl}"`,
+                'end tell',
+            ];
+            execFileSync('osascript', safariScript.flatMap(line => ['-e', line]), { timeout: 5000 });
+        }
+        catch {
+            // 都不存在，用系统默认方式打开
+            process.stderr.write(`[ae-tracking] Could not open Chrome/Safari. Please open ${hostUrl} manually.\n`);
+        }
+    }
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        const { token, error, browser } = extractViaOsascript(hostUrl);
+        if (token) {
+            process.stderr.write(`[ae-tracking] Token captured from ${browser} for ${hostUrl}.\n`);
+            return { token, browser };
+        }
+        if (error === 'no_js_permission')
+            return { token: null, browser };
+    }
+    process.stderr.write(`[ae-tracking] Polling timed out after ${POLL_TIMEOUT_MS / 1000}s.\n`);
+    return { token: null };
+}
+export async function getToken(hostUrl) {
+    if (!hostUrl) {
+        throw new Error('No AE host configured. Run: npx tsx scripts/te-token.ts set-host <url>');
+    }
+    // 1. Environment variable
+    if (process.env.AE_TOKEN) {
+        return { token: process.env.AE_TOKEN, browser: 'env' };
+    }
+    // 2. Cached token
+    const cached = loadToken(hostUrl);
+    if (cached && cached.token)
+        return { token: cached.token, browser: 'cache' };
+    // 3. osascript extraction (Chrome + Safari)
+    const { token: extracted, error, browser } = extractViaOsascript(hostUrl);
+    if (error === 'no_js_permission') {
+        throw new Error(`Browser JS-from-AppleEvents disabled. Enable: ${browser} → View → Developer → Allow JS from Apple Events.`);
+    }
+    if (error === 'not_mac') {
+        throw new Error('Auto extraction is macOS only (Chrome/Safari). Set AE_TOKEN env var instead.');
+    }
+    if (extracted) {
+        saveToken(extracted, hostUrl);
+        return { token: extracted, browser };
+    }
+    // 4. Open browser and poll
+    const polled = await openAndPoll(hostUrl);
+    if (polled.token) {
+        saveToken(polled.token, hostUrl);
+        return { token: polled.token, browser: polled.browser };
+    }
+    throw new Error(`Cannot obtain token for ${hostUrl}. Set AE_TOKEN env var.`);
+}

package/dist/src/cli/auth.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * 获取并缓存 token（可被其他命令调用）
+ * macOS: 从 Chrome/Safari localStorage 自动获取
+ * Windows/Linux: 引导用户手动获取并输入
+ */
+export declare function refreshToken(host: string): Promise<string>;
+export declare function registerAuth(cmd: Command): void;

package/dist/src/cli/auth.js

@@ -0,0 +1,81 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createInterface } from 'node:readline/promises';
+import { getTokenPath, getTeTrackingDir } from './home.js';
+import { getToken, saveToken, clearToken } from '../auth.js';
+const DEFAULT_HOST = 'https://web-ta-demo.thinkingdata.cn';
+async function loadCache() {
+    try {
+        return JSON.parse(await readFile(getTokenPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+async function saveCache(cache) {
+    await mkdir(getTeTrackingDir(), { recursive: true });
+    await writeFile(getTokenPath(), JSON.stringify(cache, null, 2), 'utf8');
+}
+/**
+ * 获取并缓存 token（可被其他命令调用）
+ * macOS: 从 Chrome/Safari localStorage 自动获取
+ * Windows/Linux: 引导用户手动获取并输入
+ */
+export async function refreshToken(host) {
+    let token;
+    let browser;
+    if (process.platform === 'darwin') {
+        // macOS: 从 Chrome/Safari 自动获取
+        clearToken(host);
+        const result = await getToken(host);
+        token = result.token;
+        browser = result.browser;
+        if (browser && browser !== 'cache' && browser !== 'env') {
+            console.log(`[auth] token captured from ${browser}`);
+        }
+    }
+    else {
+        // Windows/Linux: 引导用户手动获取 token
+        console.log('\n请按以下步骤获取 AE Token：');
+        console.log('1. 在浏览器打开并登录 AE 系统：' + host);
+        console.log('2. 按 F12 打开开发者工具');
+        console.log('3. 进入 Application → Local Storage → 找到 ACCESS_TOKEN');
+        console.log('4. 复制 token 值（去掉首尾引号）\n');
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        token = (await rl.question('粘贴 token: ')).trim();
+        rl.close();
+        if (!token) {
+            throw new Error('empty token');
+        }
+        saveToken(token, host);
+    }
+    const cache = await loadCache();
+    cache[host] = { token, updatedAt: new Date().toISOString() };
+    await saveCache(cache);
+    console.log(`[auth] token refreshed for ${host}`);
+    return token;
+}
+async function cmdLogin(opts) {
+    await refreshToken(opts.host);
+    console.log(`ok: token cached for ${opts.host}`);
+}
+async function cmdStatus() {
+    const cache = await loadCache();
+    const entries = Object.entries(cache);
+    if (entries.length === 0) {
+        console.log('(no cached tokens)');
+        return;
+    }
+    for (const [host, v] of entries) {
+        console.log(`${host}  ${v.token.slice(0, 6)}...${v.token.slice(-4)}  updated ${v.updatedAt}`);
+    }
+}
+async function cmdClear() {
+    await saveCache({});
+    console.log('ok: cache cleared');
+}
+export function registerAuth(cmd) {
+    cmd.description('manage AE access tokens');
+    cmd.command('login').option('--host <url>', 'AE host', DEFAULT_HOST).action(cmdLogin);
+    cmd.command('status').action(cmdStatus);
+    cmd.command('clear').action(cmdClear);
+}

package/dist/src/cli/code.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerCode(cmd: Command): void;

package/dist/src/cli/code.js

@@ -0,0 +1,85 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { detectProject } from '../project-detect/detect.js';
+import { readTemplateXlsx } from '../xlsx/read.js';
+/**
+ * Infer sdk_integration_mode from events' platform field (if present).
+ * Returns undefined if events have no platform info (e.g., from xlsx).
+ */
+function inferSdkMode(events) {
+    // If events have explicit platform field, we can infer
+    const hasPlatform = events.some((e) => e.platform !== undefined);
+    if (!hasPlatform)
+        return undefined; // xlsx doesn't have platform info
+    const platforms = new Set(events.map((e) => e.platform ?? 'client'));
+    if (platforms.has('both'))
+        return 'both';
+    if (platforms.has('client') && platforms.has('server'))
+        return 'both';
+    if (platforms.has('server'))
+        return 'server_only';
+    return 'client_only';
+}
+export function registerCode(cmd) {
+    cmd.description('tooling for generate-tracking-code skill');
+    cmd.command('import-xlsx')
+        .description('Import xlsx file to draft.json, inferring sdk_integration_mode from events')
+        .requiredOption('--xlsx <path>', 'Path to xlsx file')
+        .requiredOption('--out <path>', 'Output path for draft.json')
+        .option('--sdk-type <type>', 'Client SDK type (android/ios/openharmony/javascript/etc.)')
+        .option('--languages <langs>', 'Client languages comma-separated (e.g., java,kotlin for android)')
+        .option('--server <lang>', 'Server language (java/python/go/etc.)')
+        .action(async (opts) => {
+        const draft = await readTemplateXlsx(opts.xlsx);
+        // Infer sdk_integration_mode from events (if platform info available)
+        const inferredMode = inferSdkMode(draft.events);
+        if (inferredMode) {
+            draft.meta.sdk_integration_mode = inferredMode;
+            process.stdout.write(`[import-xlsx] inferred sdk_integration_mode: ${draft.meta.sdk_integration_mode}\n`);
+        }
+        else {
+            process.stdout.write(`[import-xlsx] sdk_integration_mode: ${draft.meta.sdk_integration_mode} (default, xlsx has no platform info)\n`);
+        }
+        // Apply CLI overrides
+        if (opts.sdkType) {
+            draft.meta.client_sdk_type = opts.sdkType;
+            draft.meta.client_platforms = [opts.sdkType];
+        }
+        if (opts.languages) {
+            const langs = opts.languages.split(',');
+            draft.meta.client_languages = langs;
+            if (draft.meta.client_platforms?.[0]) {
+                const platform = draft.meta.client_platforms[0];
+                const langMap = {};
+                langMap[platform] = langs;
+                draft.meta.client_platform_languages = langMap;
+            }
+        }
+        if (opts.server) {
+            draft.meta.server_language = opts.server;
+        }
+        await writeFile(opts.out, JSON.stringify(draft, null, 2), 'utf8');
+        process.stdout.write(`[import-xlsx] wrote ${draft.events.length} events to ${opts.out}\n`);
+    });
+    cmd.command('dryrun')
+        .requiredOption('--plan <path>', 'Draft JSON (from plan fetch)')
+        .option('--cwd <path>', 'target project dir', process.cwd())
+        .action(async (opts) => {
+        const draft = JSON.parse(await readFile(opts.plan, 'utf8'));
+        const detect = await detectProject(opts.cwd);
+        const tagged = new Map();
+        for (const ev of draft.events) {
+            const tag = ev.event_tag ?? 'uncategorized';
+            if (!tagged.has(tag))
+                tagged.set(tag, []);
+            tagged.get(tag).push(ev.event_name);
+        }
+        const out = {
+            detect,
+            sdkInit: { candidateFiles: detect.entryFiles, placed: false },
+            commonProperties: draft.common_event_properties.map((p) => p.name),
+            userProperties: draft.user_properties.map((p) => ({ name: p.name, update_type: p.update_type })),
+            eventGroups: [...tagged.entries()].map(([tag, events]) => ({ tag, events })),
+        };
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    });
+}

package/dist/src/cli/debug.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerDebug(cmd: Command): void;