feat(sdk): 版本注入与事件归属骨架（0.2.0/build_id/schema_version）

Co-Authored-By: Claude Code <noreply@anthropic.com>

sdk/src/index.ts

@@ -3,6 +3,7 @@ import { mergeConfig } from "./config";
 import { Transport } from "./transport";
 import { startPageTracking } from "./events";
 import { buildEnvContext, collectHighEntropyHints, pageContext } from "./context";
+import { SDK_VERSION, BUILD_ID, SCHEMA_VERSION, CONFIG_VERSION } from "./types";
 import type { CtkConfig } from "./config";
 
 // IIFE 打包入口（build.mjs）：模块加载即接管全局 ctk 命令队列并重放。
@@ -49,7 +50,7 @@ function dispatch(cmd: string, arg?: unknown) {
         occurred_at: new Date().toISOString(),
         path: pc.path,
         title: pc.title,
-        properties: { sdk_version: "0.1.0" },
+        properties: { sdk_version: SDK_VERSION, build_id: BUILD_ID, schema_version: SCHEMA_VERSION, config_version: CONFIG_VERSION },
       });
       startPageTracking(transport);
     } else if (cmd === "track" && transport) {

sdk/src/types.ts

@@ -0,0 +1,23 @@
+/** 事件归属四元组：入队时冻结，flush 不再重读（spec §1.1） */
+export interface Attribution {
+  site_id: string;
+  visitor_id: string;
+  session_id: string;
+  page_id: string;
+  seq: number;
+  purpose?: null; // V1.1 预留
+  epoch?: null; // V1.1 预留
+  grant_ref?: null; // V1.1 预留
+}
+export const SDK_VERSION = "0.2.0"; // 与 package.json 同步手维护
+export const SCHEMA_VERSION = 2;
+export const CONFIG_VERSION = "1";
+
+// build_id 由 esbuild/vitest define 注入的全局常量（ambient 声明，
+// 不能用模块级 export declare——esbuild 打包时会被擦除导致引用悬空）
+declare global {
+  // eslint-disable-next-line no-var
+  var __BUILD_ID__: string | undefined;
+}
+/** 运行时兜底读取（build 注入缺失时降级 "unknown"，绝不抛） */
+export const BUILD_ID: string = globalThis.__BUILD_ID__ ?? "unknown";