@playcraft/devkit 1.0.14 → 1.0.15-beta.1

package/cli/commands/build.js

@@ -1,4 +1,4 @@
-"use strict";process.env.BABEL_ENV="production";process.env.NODE_ENV="production";const fs=require("fs");const path=require("path");const{runBuild}=require("../../core/webpack.build.js");const{runThemeValidation,restoreSchema}=require("../../core/utils/validateThemeData");/**
+"use strict";process.env.BABEL_ENV="production";process.env.NODE_ENV="production";const fs=require("fs");const path=require("path");const{runBuild}=require("../../core/webpack.build.js");const{runThemeValidation,restoreSchema}=require("../../core/utils/validateThemeData");const{runPreBuildChecks}=require("../../core/validators/pre-build-checker.js");/**
  * 从主题入口文件中检测当前主题名称。
  * 支持以下模式：
  *   export { default } from './themeName';
@@ -7,7 +7,15 @@
 const buildsConfigPath=path.join(projectRoot,"builds.config.js");let themeConfig={sourceDir:"src/theme",entryFile:"src/theme/index.ts"};if(fs.existsSync(buildsConfigPath)){try{delete require.cache[buildsConfigPath];const config=require(buildsConfigPath);if(config.themes){themeConfig={...themeConfig,...config.themes}}}catch(e){// 忽略错误
 }}const entryPath=path.join(projectRoot,themeConfig.entryFile);if(!fs.existsSync(entryPath)){return{themeName:null,themeConfig}}const content=fs.readFileSync(entryPath,"utf8");// 匹配: export { default } from './themeName' 或 import ... from './themeName'
 const match=content.match(/from\s+['"]\.\/([^'"]+)['"]/);if(match){return{themeName:match[1],themeConfig}}return{themeName:null,themeConfig}}// --- 主流程 ---
-const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(projectRoot);let schemaPathToRestore=null;// In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
+const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(projectRoot);let schemaPathToRestore=null;// ============================================================
+// 📌 编译前检查（埋点验证等）
+// ============================================================
+// 支持通过环境变量控制是否跳过检查
+// - SKIP_PRE_BUILD_CHECKS=1: 强制跳过检查
+// - PLAYABLE_BATCH_MODE=1: 批量构建模式，子进程自动跳过检查（主进程已执行）
+const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";const shouldSkipChecks=process.env.SKIP_PRE_BUILD_CHECKS==="1"||isBatchMode;async function runPreChecks(){if(shouldSkipChecks){console.log("\n\u26A0\uFE0F  \u8DF3\u8FC7\u7F16\u8BD1\u524D\u68C0\u67E5\uFF08SKIP_PRE_BUILD_CHECKS=1\uFF09\n");return}const checkResult=await runPreBuildChecks(projectRoot,{verbose:false,showDetails:true,failFast:false});if(!checkResult.success){console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u5931\u8D25\uFF0C\u7EC8\u6B62\u6784\u5EFA\u3002");console.error("\u63D0\u793A\uFF1A\u5982\u9700\u8DF3\u8FC7\u68C0\u67E5\uFF0C\u53EF\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF: SKIP_PRE_BUILD_CHECKS=1\n");process.exit(1)}}// 执行编译前检查（异步）
+runPreChecks().then(()=>{// 检查通过后继续原有流程
+continueWithBuild()}).catch(err=>{console.error("\n\u274C \u7F16\u8BD1\u524D\u68C0\u67E5\u51FA\u9519:",err);process.exit(1)});function continueWithBuild(){// In batch mode (PLAYABLE_BATCH_MODE=1), the parent process has already
 // executed runThemeValidation and overwritten theme.schema.json5 with merged data.
 // Running it again in child processes would cause a race condition:
 //   1. Child reads the already-overwritten schema (pure data, no "properties"/"default")
@@ -15,4 +23,4 @@ const projectRoot=process.cwd();const{themeName,themeConfig}=detectCurrentTheme(
 //   3. Child overwrites schema with {} → file becomes empty object
 const isBatchMode=process.env.PLAYABLE_BATCH_MODE==="1";if(themeName&&!isBatchMode){const buildLog=(msg,level)=>{const colors={info:"\x1B[36m",success:"\x1B[32m",error:"\x1B[31m"};const reset="\x1B[0m";const color=colors[level]||"";console.log(`${color}[build] ${msg}${reset}`)};const{valid,schemaPath}=runThemeValidation(themeName,projectRoot,themeConfig,{log:buildLog});schemaPathToRestore=schemaPath;if(!valid){// 校验失败时恢复 schema（备份可能已创建）
 if(schemaPathToRestore)restoreSchema(schemaPathToRestore);process.exit(1)}}// 执行构建，无论成功或失败都恢复 schema
-runBuild().then(()=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore)}).catch(err=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore);console.error(err);process.exit(1)});
+runBuild().then(()=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore)}).catch(err=>{if(schemaPathToRestore)restoreSchema(schemaPathToRestore);console.error(err);process.exit(1)})}

package/core/batch-build.js

@@ -7,7 +7,7 @@
  * 2. 每个构建任务使用独立的临时目录（dist-temp-{taskId}）
  * 3. 构建完成后自动移动到目标目录并清理临时目录
  * 4. 支持灵活的配置系统
- */const{execSync,exec}=require("child_process");const fs=require("fs");const path=require("path");const os=require("os");const{promisify}=require("util");const{fetchTemporaryCredentials,createCOSClient,uploadDirectoryToCOS,uploadFileToCOS,purgeCDNCache}=require("./cos-uploader");const{runThemeValidation,restoreSchema}=require("./utils/validateThemeData");const execAsync=promisify(exec);/**
+ */const{execSync,exec}=require("child_process");const fs=require("fs");const path=require("path");const os=require("os");const{promisify}=require("util");const{fetchTemporaryCredentials,createCOSClient,uploadDirectoryToCOS,uploadFileToCOS,purgeCDNCache}=require("./cos-uploader");const{runThemeValidation,restoreSchema}=require("./utils/validateThemeData");const{runPreBuildChecks}=require("./validators/pre-build-checker.js");const execAsync=promisify(exec);/**
  * 更新 preview.json 文件
  */async function updatePreviewJson(cosConfig,cosPrefix,currentTheme,previewLinks,credentials=null){const previewJsonKey=cosPrefix?`${cosPrefix}/preview.json`:"preview.json";// 如果没有传入凭证，尝试获取一次
 if(!credentials){try{credentials=await fetchTemporaryCredentials()}catch(error){log(`获取临时凭证失败，跳过 preview.json 更新: ${error.message}`,"warn");return}}// 读取现有的 preview.json 文件
@@ -135,7 +135,10 @@ if(buildJson.filename){log("  \u26A0\uFE0F  build.json.filename \u5C06\u88AB\u5F
  */function mergeConfig(defaultConfig,userConfig){const result={...defaultConfig};for(const key in userConfig){if(typeof userConfig[key]==="object"&&!Array.isArray(userConfig[key])){result[key]={...defaultConfig[key],...userConfig[key]}}else{result[key]=userConfig[key]}}return result}/**
  * 打印配置摘要
  */function printSummary(config,themes,channels){var _os$cpus$;const totalBuilds=themes.length*channels.length;const cpuCount=os.cpus().length;const cpuModel=((_os$cpus$=os.cpus()[0])===null||_os$cpus$===void 0?void 0:_os$cpus$.model)||"Unknown";log("========================================");log("\u5F00\u59CB\u6279\u91CF\u6784\u5EFA\u4EFB\u52A1");log(`项目: ${config.title}`);log(`主题数: ${themes.length}`);log(`渠道数: ${channels.length}`);log(`总构建数: ${totalBuilds}`);log(`CPU: ${cpuCount} 核心 (${cpuModel.substring(0,40)}${cpuModel.length>40?"...":""})`);log(`并发数: ${config.build.parallel} (自动优化)`);log("========================================\n");if(themes.length<=10){log(`主题列表: ${themes.join(", ")}`,"debug")}log(`渠道列表: ${channels.join(", ")}`,"debug");log("")}// ==================== 主函数 ====================
-async function buildBatch(){const projectRoot=process.cwd();const startTime=Date.now();try{// 加载配置（包含远程配置合并）
+async function buildBatch(){const projectRoot=process.cwd();const startTime=Date.now();try{// ============================================================
+// 📌 编译前检查（埋点验证等）- 仅在主进程执行一次
+// ============================================================
+const shouldSkipChecks=process.env.SKIP_PRE_BUILD_CHECKS==="1";if(!shouldSkipChecks){log("\u6267\u884C\u7F16\u8BD1\u524D\u68C0\u67E5\uFF08\u57CB\u70B9\u9A8C\u8BC1\u7B49\uFF09...","info");const checkResult=await runPreBuildChecks(projectRoot,{verbose:false,showDetails:true,failFast:false});if(!checkResult.success){log("\u7F16\u8BD1\u524D\u68C0\u67E5\u5931\u8D25\uFF0C\u7EC8\u6B62\u6279\u91CF\u6784\u5EFA\u3002","error");log("\u63D0\u793A\uFF1A\u5982\u9700\u8DF3\u8FC7\u68C0\u67E5\uFF0C\u53EF\u8BBE\u7F6E\u73AF\u5883\u53D8\u91CF: SKIP_PRE_BUILD_CHECKS=1","warn");process.exit(1)}log("\u2713 \u7F16\u8BD1\u524D\u68C0\u67E5\u901A\u8FC7","success")}else{log("\u8DF3\u8FC7\u7F16\u8BD1\u524D\u68C0\u67E5\uFF08SKIP_PRE_BUILD_CHECKS=1\uFF09","warn")}// 加载配置（包含远程配置合并）
 const config=await loadConfig(projectRoot);// 解析命令行参数
 const args=parseArgs();// 应用命令行参数
 if(args.parallel!==null){config.build.parallel=args.parallel}// 是否启用渠道折叠为 zip 模式

package/core/index.js

@@ -1 +1,4 @@
-"use strict";const{allowedExtensions,webpackCommonConfig}=require("./webpack.common.js");const{parseArgvOptions}=require("./utils/parseArgvOptions.js");const{mergeOptions}=require("./utils/mergeOptions.js");const{options}=require("./options.js");const{DAPIInjectorPlugin}=require("./plugins/DAPIInjectorPlugin.js");const{DebuggerInjectionPlugin}=require("./plugins/DebuggerInjectionPlugin.js");const{ExitAPIInjectorPlugin}=require("./plugins/ExitAPIInjectorPlugin.js");const{runBuild,makeWebpackBuildConfig}=require("./webpack.build.js");const{runDev,makeWebpackDevConfig}=require("./webpack.dev.js");const{runViteDev,makeViteDevConfig}=require("./vite.dev.js");exports.mergeOptions=mergeOptions;exports.parseArgvOptions=parseArgvOptions;exports.options=options;exports.allowedExtensions=allowedExtensions;exports.webpackCommonConfig=webpackCommonConfig;exports.makeWebpackDevConfig=makeWebpackDevConfig;exports.makeWebpackBuildConfig=makeWebpackBuildConfig;exports.runDev=runDev;exports.runBuild=runBuild;exports.DAPIInjectorPlugin=DAPIInjectorPlugin;exports.ExitAPIInjectorPlugin=ExitAPIInjectorPlugin;exports.DebuggerInjectionPlugin=DebuggerInjectionPlugin;exports.makeViteDevConfig=makeViteDevConfig;exports.runViteDev=runViteDev;
+"use strict";const{allowedExtensions,webpackCommonConfig}=require("./webpack.common.js");const{parseArgvOptions}=require("./utils/parseArgvOptions.js");const{mergeOptions}=require("./utils/mergeOptions.js");const{options}=require("./options.js");const{DAPIInjectorPlugin}=require("./plugins/DAPIInjectorPlugin.js");const{DebuggerInjectionPlugin}=require("./plugins/DebuggerInjectionPlugin.js");const{ExitAPIInjectorPlugin}=require("./plugins/ExitAPIInjectorPlugin.js");const{runBuild,makeWebpackBuildConfig}=require("./webpack.build.js");const{runDev,makeWebpackDevConfig}=require("./webpack.dev.js");const{runViteDev,makeViteDevConfig}=require("./vite.dev.js");// 验证器
+const{runPreBuildChecks,runTrackingCheck,registerChecker,toggleChecker,listCheckers}=require("./validators/pre-build-checker.js");const{validateTracking,printValidationResult,TRACKING_METHODS,SDK_TO_TRACKING_MAP}=require("./validators/tracking-validator.js");exports.mergeOptions=mergeOptions;exports.parseArgvOptions=parseArgvOptions;exports.options=options;exports.allowedExtensions=allowedExtensions;exports.webpackCommonConfig=webpackCommonConfig;exports.makeWebpackDevConfig=makeWebpackDevConfig;exports.makeWebpackBuildConfig=makeWebpackBuildConfig;exports.runDev=runDev;exports.runBuild=runBuild;exports.DAPIInjectorPlugin=DAPIInjectorPlugin;exports.ExitAPIInjectorPlugin=ExitAPIInjectorPlugin;exports.DebuggerInjectionPlugin=DebuggerInjectionPlugin;exports.makeViteDevConfig=makeViteDevConfig;exports.runViteDev=runViteDev;// 编译前检查器导出
+exports.runPreBuildChecks=runPreBuildChecks;exports.runTrackingCheck=runTrackingCheck;exports.registerChecker=registerChecker;exports.toggleChecker=toggleChecker;exports.listCheckers=listCheckers;// 埋点验证器导出
+exports.validateTracking=validateTracking;exports.printValidationResult=printValidationResult;exports.TRACKING_METHODS=TRACKING_METHODS;exports.SDK_TO_TRACKING_MAP=SDK_TO_TRACKING_MAP;

package/core/validators/index.d.ts

@@ -0,0 +1,242 @@
+// ============================================================
+// 埋点验证器类型定义
+// ============================================================
+
+/**
+ * 埋点方法配置
+ */
+export interface TrackingMethod {
+  /** 方法名 */
+  name: string;
+  /** 是否必须调用 */
+  required: boolean;
+  /** 方法描述 */
+  description: string;
+  /** 对应的渠道埋点 */
+  channels: string[];
+}
+
+/**
+ * 验证结果
+ */
+export interface ValidationResult {
+  /** 验证是否通过 */
+  success: boolean;
+  /** 集成类型 */
+  integrationType: 'sdk' | 'tracking' | 'none';
+  /** 方法检测结果 */
+  methods: Array<{
+    method: string;
+    found: boolean;
+    required: boolean;
+    description: string;
+  }>;
+  /** 错误信息列表 */
+  errors: string[];
+  /** 警告信息列表 */
+  warnings: string[];
+  /** 统计信息 */
+  stats: {
+    totalFiles: number;
+    scannedFiles: number;
+    hasTrackingImport: boolean;
+    hasSDKImport: boolean;
+  };
+}
+
+/**
+ * 验证选项
+ */
+export interface ValidationOptions {
+  /** 文件扩展名列表 */
+  extensions?: string[];
+  /** 排除的目录列表 */
+  excludeDirs?: string[];
+  /** 是否输出详细信息 */
+  verbose?: boolean;
+}
+
+/**
+ * 验证项目中的埋点调用
+ * @param projectRoot - 项目根目录
+ * @param options - 验证选项
+ */
+export declare function validateTracking(
+  projectRoot: string,
+  options?: ValidationOptions
+): ValidationResult;
+
+/**
+ * 格式化验证结果并输出到控制台
+ * @param result - 验证结果
+ * @param showDetails - 是否显示详细信息
+ */
+export declare function printValidationResult(
+  result: ValidationResult,
+  showDetails?: boolean
+): void;
+
+/**
+ * 扫描目录获取所有源码文件
+ * @param dir - 目录路径
+ * @param extensions - 文件扩展名列表
+ * @param excludeDirs - 排除的目录名列表
+ */
+export declare function scanSourceFiles(
+  dir: string,
+  extensions?: string[],
+  excludeDirs?: string[]
+): string[];
+
+/**
+ * 检测代码中是否包含 tracking 方法的直接调用
+ * @param content - 文件内容
+ * @param methodName - 方法名
+ */
+export declare function detectDirectTrackingCall(
+  content: string,
+  methodName: string
+): boolean;
+
+/**
+ * 检测代码中是否包含 SDK 方法调用
+ * @param content - 文件内容
+ * @param sdkMethod - SDK 方法名
+ */
+export declare function detectSDKCall(
+  content: string,
+  sdkMethod: string
+): boolean;
+
+/**
+ * 检测是否导入了 @playcraft/ads-tracking
+ * @param content - 文件内容
+ */
+export declare function hasTrackingImport(content: string): boolean;
+
+/**
+ * 检测是否导入了 @playcraft/adsdk
+ * @param content - 文件内容
+ */
+export declare function hasSDKImport(content: string): boolean;
+
+/**
+ * 所有埋点方法配置
+ */
+export declare const TRACKING_METHODS: TrackingMethod[];
+
+/**
+ * SDK 静态方法映射到 tracking 方法
+ */
+export declare const SDK_TO_TRACKING_MAP: Record<string, string>;
+
+// ============================================================
+// 编译前检查器类型定义
+// ============================================================
+
+/**
+ * 检查结果
+ */
+export interface CheckResult {
+  /** 是否通过 */
+  success: boolean;
+  /** 结果消息 */
+  message: string;
+  /** 额外数据 */
+  data?: any;
+  /** 错误对象（如果检查出错） */
+  error?: Error;
+}
+
+/**
+ * 检查器定义
+ */
+export interface Checker {
+  /** 检查器名称 */
+  name: string;
+  /** 检查器描述 */
+  description: string;
+  /** 是否启用 */
+  enabled: boolean;
+  /** 验证函数 */
+  validator: (projectRoot: string, options: any) => Promise<CheckResult> | CheckResult;
+}
+
+/**
+ * 编译前检查选项
+ */
+export interface PreBuildCheckOptions {
+  /** 只执行指定的检查器 ID */
+  only?: string[];
+  /** 跳过指定的检查器 ID */
+  skip?: string[];
+  /** 详细输出 */
+  verbose?: boolean;
+  /** 显示详细报告 */
+  showDetails?: boolean;
+  /** 遇到错误立即停止 */
+  failFast?: boolean;
+  /** 文件扩展名（传递给检查器） */
+  extensions?: string[];
+  /** 排除的目录（传递给检查器） */
+  excludeDirs?: string[];
+}
+
+/**
+ * 编译前检查结果
+ */
+export interface PreBuildCheckResult {
+  /** 是否全部通过 */
+  success: boolean;
+  /** 各检查器的结果 */
+  results: Map<string, CheckResult>;
+}
+
+/**
+ * 执行所有已启用的编译前检查器
+ * @param projectRoot - 项目根目录
+ * @param options - 选项
+ */
+export declare function runPreBuildChecks(
+  projectRoot: string,
+  options?: PreBuildCheckOptions
+): Promise<PreBuildCheckResult>;
+
+/**
+ * 单独运行埋点验证（快捷方法）
+ * @param projectRoot - 项目根目录
+ * @param options - 选项
+ */
+export declare function runTrackingCheck(
+  projectRoot: string,
+  options?: ValidationOptions
+): Promise<CheckResult>;
+
+/**
+ * 注册自定义检查器
+ * @param id - 检查器 ID
+ * @param checker - 检查器配置
+ */
+export declare function registerChecker(id: string, checker: Checker): void;
+
+/**
+ * 启用/禁用检查器
+ * @param id - 检查器 ID
+ * @param enabled - 是否启用
+ */
+export declare function toggleChecker(id: string, enabled: boolean): void;
+
+/**
+ * 获取所有检查器列表
+ */
+export declare function listCheckers(): Array<{
+  id: string;
+  name: string;
+  description: string;
+  enabled: boolean;
+}>;
+
+/**
+ * 内部检查器注册表（高级用户使用）
+ */
+export declare const checkers: Map<string, Checker>;

package/core/validators/pre-build-checker.js

@@ -0,0 +1,89 @@
+"use strict";const{validateTracking,printValidationResult}=require("./tracking-validator.js");// ============================================================
+// 检查器注册表
+// ============================================================
+/**
+ * 检查器定义
+ * @typedef {Object} Checker
+ * @property {string} name - 检查器名称
+ * @property {string} description - 检查器描述
+ * @property {boolean} enabled - 是否启用
+ * @property {(projectRoot: string, options: any) => Promise<CheckResult>|CheckResult} validator - 验证函数
+ *//**
+ * 检查结果
+ * @typedef {Object} CheckResult
+ * @property {boolean} success - 是否通过
+ * @property {string} message - 结果消息
+ * @property {any} [data] - 额外数据
+ *//**
+ * 所有注册的检查器
+ * @type {Map<string, Checker>}
+ */const checkers=new Map;// ============================================================
+// 内置检查器
+// ============================================================
+/**
+ * 埋点验证检查器
+ */checkers.set("tracking",{name:"\u57CB\u70B9\u9A8C\u8BC1",description:"\u9A8C\u8BC1\u9879\u76EE\u4E2D\u662F\u5426\u6B63\u786E\u8C03\u7528\u4E86\u6240\u6709\u5FC5\u987B\u7684\u57CB\u70B9\u65B9\u6CD5",enabled:true,validator:(projectRoot,options={})=>{const result=validateTracking(projectRoot,{verbose:options.verbose||false,extensions:options.extensions,excludeDirs:options.excludeDirs});return{success:result.success,message:result.success?"\u2705 \u57CB\u70B9\u9A8C\u8BC1\u901A\u8FC7":`❌ 埋点验证失败：缺少 ${result.errors.length} 个必须的埋点方法`,data:result}}});// 预留：未来可添加更多检查器
+// checkers.set('assets', {
+//   name: '资源检查',
+//   description: '验证项目资源文件的完整性和规范性',
+//   enabled: false,
+//   validator: (projectRoot, options) => {
+//     // TODO: 实现资源检查逻辑
+//     return { success: true, message: '资源检查通过' };
+//   }
+// });
+// checkers.set('config', {
+//   name: '配置检查',
+//   description: '验证项目配置文件的正确性',
+//   enabled: false,
+//   validator: (projectRoot, options) => {
+//     // TODO: 实现配置检查逻辑
+//     return { success: true, message: '配置检查通过' };
+//   }
+// });
+// ============================================================
+// 检查器管理
+// ============================================================
+/**
+ * 注册自定义检查器
+ * @param {string} id - 检查器 ID
+ * @param {Checker} checker - 检查器配置
+ */function registerChecker(id,checker){if(checkers.has(id)){console.warn(`[警告] 检查器 "${id}" 已存在，将被覆盖`)}checkers.set(id,checker)}/**
+ * 启用/禁用检查器
+ * @param {string} id - 检查器 ID
+ * @param {boolean} enabled - 是否启用
+ */function toggleChecker(id,enabled){const checker=checkers.get(id);if(checker){checker.enabled=enabled}else{console.warn(`[警告] 未找到检查器: ${id}`)}}/**
+ * 获取所有检查器列表
+ * @returns {Array<{id: string, name: string, description: string, enabled: boolean}>}
+ */function listCheckers(){return Array.from(checkers.entries()).map(([id,checker])=>({id,name:checker.name,description:checker.description,enabled:checker.enabled}))}// ============================================================
+// 执行检查
+// ============================================================
+/**
+ * 执行所有已启用的检查器
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} [options] - 选项
+ * @param {string[]} [options.only] - 只执行指定的检查器 ID
+ * @param {string[]} [options.skip] - 跳过指定的检查器 ID
+ * @param {boolean} [options.verbose] - 详细输出
+ * @param {boolean} [options.showDetails] - 显示详细报告
+ * @param {boolean} [options.failFast] - 遇到错误立即停止
+ * @returns {Promise<{success: boolean, results: Map<string, CheckResult>}>}
+ */async function runPreBuildChecks(projectRoot,options={}){const{only=[],skip=[],verbose=false,showDetails=true,failFast=false}=options;const results=new Map;let allSuccess=true;console.log("\n"+"\u2550".repeat(70));console.log("\uD83D\uDD0D \u7F16\u8BD1\u524D\u68C0\u67E5");console.log("\u2550".repeat(70));// 确定要执行的检查器
+let checkersToRun=Array.from(checkers.entries()).filter(([id,checker])=>{// 如果指定了 only，只运行指定的
+if(only.length>0&&!only.includes(id))return false;// 跳过 skip 列表中的
+if(skip.includes(id))return false;// 只运行启用的
+return checker.enabled});if(checkersToRun.length===0){console.log("\n\u26A0\uFE0F  \u6CA1\u6709\u542F\u7528\u7684\u68C0\u67E5\u5668");console.log("\u2550".repeat(70)+"\n");return{success:true,results}}if(verbose){console.log(`\n📋 将执行 ${checkersToRun.length} 个检查器:`);checkersToRun.forEach(([id,checker])=>{console.log(`  - ${checker.name} (${id})`)});console.log("")}// 执行检查器
+for(const[id,checker]of checkersToRun){try{console.log(`\n▶️  执行检查: ${checker.name}`);console.log("-".repeat(70));const result=await Promise.resolve(checker.validator(projectRoot,options));results.set(id,result);console.log(result.message);// 详细输出（针对埋点验证）
+if(showDetails&&id==="tracking"&&result.data){printValidationResult(result.data,showDetails)}if(!result.success){allSuccess=false;if(failFast){console.log("\n\u26A0\uFE0F  failFast \u6A21\u5F0F\uFF1A\u68C0\u6D4B\u5230\u5931\u8D25\uFF0C\u7EC8\u6B62\u540E\u7EED\u68C0\u67E5");break}}}catch(error){console.error(`\n❌ 检查器 "${checker.name}" 执行失败:`,error.message);results.set(id,{success:false,message:`执行出错: ${error.message}`,error});allSuccess=false;if(failFast)break}}// 总结
+console.log("\n"+"\u2550".repeat(70));console.log("\uD83D\uDCCA \u68C0\u67E5\u603B\u7ED3");console.log("\u2550".repeat(70));const successCount=Array.from(results.values()).filter(r=>r.success).length;const totalCount=results.size;console.log(`\n通过: ${successCount}/${totalCount}`);if(allSuccess){console.log("\n\u2705 \u6240\u6709\u68C0\u67E5\u901A\u8FC7\uFF0C\u53EF\u4EE5\u7EE7\u7EED\u7F16\u8BD1\uFF01")}else{console.log("\n\u274C \u90E8\u5206\u68C0\u67E5\u5931\u8D25\uFF0C\u8BF7\u4FEE\u590D\u540E\u518D\u7F16\u8BD1\u3002")}console.log("\u2550".repeat(70)+"\n");return{success:allSuccess,results}}/**
+ * 单独运行埋点验证（快捷方法）
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} [options] - 选项
+ * @returns {Promise<CheckResult>}
+ */async function runTrackingCheck(projectRoot,options={}){const checker=checkers.get("tracking");if(!checker){throw new Error("\u57CB\u70B9\u68C0\u67E5\u5668\u672A\u6CE8\u518C")}return await Promise.resolve(checker.validator(projectRoot,options))}// ============================================================
+// 导出
+// ============================================================
+module.exports={// 主要函数
+runPreBuildChecks,runTrackingCheck,// 检查器管理
+registerChecker,toggleChecker,listCheckers,// 内部访问（供高级用户）
+checkers};

package/core/validators/tracking-validator.js

@@ -0,0 +1,113 @@
+"use strict";const fs=require("fs");const path=require("path");// ============================================================
+// 埋点方法配置
+// ============================================================
+/**
+ * 埋点方法配置
+ * @typedef {Object} TrackingMethod
+ * @property {string} name - 方法名
+ * @property {boolean} required - 是否必须调用
+ * @property {string} description - 方法描述
+ * @property {string[]} channels - 对应的渠道埋点
+ *//**
+ * 所有埋点方法配置
+ * @type {TrackingMethod[]}
+ */const TRACKING_METHODS=[{name:"onPlaycraftTrackingInit",required:true,description:"SDK \u521D\u59CB\u5316\u5F00\u59CB",channels:["Bigabid:mraid_viewable","InMobi:Ad_Load_Start","AppLovin:LOADING"]},{name:"onPlaycraftTrackingLoading",required:true,description:"\u6E38\u620F\u8D44\u6E90\u52A0\u8F7D\u4E2D",channels:["Bigabid:game_viewable","InMobi:Ad_Viewable","AppLovin:LOADED"]},{name:"onPlaycraftTrackingLoaded",required:true,description:"\u4E3B\u573A\u666F\u5C31\u7EEA\uFF0C\u7528\u6237\u53EF\u4EA4\u4E92",channels:["AppLovin:DISPLAYED"]},{name:"onPlaycraftChallengeStart",required:true,description:"\u6311\u6218\u5F00\u59CB\uFF08\u9996\u6B21\u7528\u6237\u4EA4\u4E92\uFF09",channels:["Bigabid:engagement","InMobi:First_Engagement","AppLovin:CHALLENGE_STARTED"]},{name:"onPlaycraftChallengeProgress",required:false,description:"\u8FDB\u5EA6\u767E\u5206\u6BD4\u8FFD\u8E2A\uFF08\u53EF\u9009\uFF09",channels:["AppLovin:CHALLENGE_PASS_*"]},{name:"onPlaycraftChallengeSuccess",required:true,description:"\u6E38\u620F\u6311\u6218\u6210\u529F",channels:["AppLovin:CHALLENGE_SOLVED","Bigabid:complete","InMobi:Gameplay_Complete"]},{name:"onPlaycraftChallengeFinish",required:false,description:"\u6E38\u620F\u7ED3\u675F\uFF08\u53EF\u9009\uFF09",channels:["Bigabid:complete","InMobi:Gameplay_Complete","AppLovin:ENDCARD_SHOWN"]},{name:"onPlaycraftInstall",required:true,description:"\u70B9\u51FB\u5B89\u88C5",channels:["Bigabid:click","InMobi:DSP_Click","AppLovin:CTA_CLICKED"]},{name:"onPlaycraftRetry",required:false,description:"\u91CD\u8BD5\u6E38\u620F\uFF08\u53EF\u9009\uFF09",channels:["AppLovin:CHALLENGE_RETRY"]},{name:"onPlaycraftChallengeFailed",required:true,description:"\u6E38\u620F\u6311\u6218\u5931\u8D25",channels:["AppLovin:CHALLENGE_FAILED"]}];/**
+ * SDK 静态方法映射到 tracking 方法
+ * 这些 SDK 方法内部会调用对应的 tracking 方法
+ */const SDK_TO_TRACKING_MAP={"playcraftInit":"onPlaycraftTrackingInit","playcraftStart":"onPlaycraftTrackingLoading","playcraftInteractive":"onPlaycraftTrackingLoaded","playcraftChallengeStart":"onPlaycraftChallengeStart","recordPlaycraftChallengeProgress":"onPlaycraftChallengeProgress","playcraftRecordSuccess":"onPlaycraftChallengeSuccess","playcraftFinish":"onPlaycraftChallengeFinish","playcraftInstall":"onPlaycraftInstall","playcraftRetry":"onPlaycraftRetry","playcraftRecordFailed":"onPlaycraftChallengeFailed"};// ============================================================
+// 文件扫描工具
+// ============================================================
+/**
+ * 递归扫描目录获取所有源码文件
+ * @param {string} dir - 目录路径
+ * @param {string[]} extensions - 文件扩展名列表
+ * @param {string[]} excludeDirs - 排除的目录名列表
+ * @returns {string[]} 文件路径列表
+ */function scanSourceFiles(dir,extensions=[".ts",".tsx",".js",".jsx"],excludeDirs=["node_modules","dist","build",".git",".claude"]){const files=[];function scan(currentDir){if(!fs.existsSync(currentDir))return;const entries=fs.readdirSync(currentDir,{withFileTypes:true});for(const entry of entries){const fullPath=path.join(currentDir,entry.name);if(entry.isDirectory()){// 跳过排除的目录
+if(excludeDirs.includes(entry.name))continue;scan(fullPath)}else if(entry.isFile()){// 检查文件扩展名
+const ext=path.extname(entry.name);if(extensions.includes(ext)){files.push(fullPath)}}}}scan(dir);return files}/**
+ * 读取文件内容（带错误处理）
+ * @param {string} filePath - 文件路径
+ * @returns {string|null} 文件内容或 null
+ */function readFileContent(filePath){try{return fs.readFileSync(filePath,"utf-8")}catch(err){console.warn(`[警告] 无法读取文件: ${filePath}`,err.message);return null}}// ============================================================
+// 方法调用检测
+// ============================================================
+/**
+ * 检测代码中是否包含 tracking 方法的直接调用
+ * @param {string} content - 文件内容
+ * @param {string} methodName - 方法名
+ * @returns {boolean} 是否找到调用
+ * 
+ * 注意：不依赖对象名称，只检测方法调用模式
+ * 匹配：xxx.onPlaycraftXxx( 或 xxx['onPlaycraftXxx']( 或 xxx["onPlaycraftXxx"](
+ */function detectDirectTrackingCall(content,methodName){const patterns=[// 匹配 .方法名(
+new RegExp(`\\.${methodName}\\s*\\(`),// 匹配 ['方法名'](
+new RegExp(`\\['${methodName}'\\]\\s*\\(`),// 匹配 ["方法名"](
+new RegExp(`\\["${methodName}"\\]\\s*\\(`)];return patterns.some(pattern=>pattern.test(content))}/**
+ * 检测代码中是否包含 SDK 方法调用（会间接触发 tracking）
+ * @param {string} content - 文件内容
+ * @param {string} sdkMethod - SDK 方法名
+ * @returns {boolean} 是否找到调用
+ * 
+ * 注意：不依赖对象名称，只检测方法调用模式
+ * 匹配：xxx.playcraftXxx( 或 xxx['playcraftXxx']( 或 xxx["playcraftXxx"](
+ */function detectSDKCall(content,sdkMethod){const patterns=[// 匹配 .方法名(
+new RegExp(`\\.${sdkMethod}\\s*\\(`),// 匹配 ['方法名'](
+new RegExp(`\\['${sdkMethod}'\\]\\s*\\(`),// 匹配 ["方法名"](
+new RegExp(`\\["${sdkMethod}"\\]\\s*\\(`)];return patterns.some(pattern=>pattern.test(content))}/**
+ * 检测是否导入了 @playcraft/ads-tracking
+ * @param {string} content - 文件内容
+ * @returns {boolean} 是否导入了 tracking
+ */function hasTrackingImport(content){return /from\s+['"]@playcraft\/ads-tracking['"]/.test(content)||/require\s*\(\s*['"]@playcraft\/ads-tracking['"]\s*\)/.test(content)}/**
+ * 检测是否导入了 @playcraft/adsdk
+ * @param {string} content - 文件内容
+ * @returns {boolean} 是否导入了 SDK
+ */function hasSDKImport(content){return /from\s+['"]@playcraft\/adsdk['"]/.test(content)||/require\s*\(\s*['"]@playcraft\/adsdk['"]\s*\)/.test(content)}// ============================================================
+// 验证核心逻辑
+// ============================================================
+/**
+ * 验证结果
+ * @typedef {Object} ValidationResult
+ * @property {boolean} success - 验证是否通过
+ * @property {'sdk'|'tracking'|'none'} integrationType - 集成类型
+ * @property {Array<{method: string, found: boolean, required: boolean, description: string}>} methods - 方法检测结果
+ * @property {string[]} errors - 错误信息列表
+ * @property {string[]} warnings - 警告信息列表
+ * @property {Object} stats - 统计信息
+ *//**
+ * 验证项目中的埋点调用
+ * @param {string} projectRoot - 项目根目录
+ * @param {Object} [options] - 验证选项
+ * @param {string[]} [options.extensions] - 文件扩展名
+ * @param {string[]} [options.excludeDirs] - 排除的目录
+ * @param {boolean} [options.verbose] - 是否输出详细信息
+ * @returns {ValidationResult} 验证结果
+ */function validateTracking(projectRoot,options={}){const{extensions=[".ts",".tsx",".js",".jsx"],excludeDirs=["node_modules","dist","build",".git"],verbose=false}=options;const result={success:false,integrationType:"none",methods:[],errors:[],warnings:[],stats:{totalFiles:0,scannedFiles:0,hasTrackingImport:false,hasSDKImport:false}};// 1. 扫描所有源码文件
+if(verbose)console.log(`\n[扫描] 开始扫描项目: ${projectRoot}`);const files=scanSourceFiles(projectRoot,extensions,excludeDirs);result.stats.totalFiles=files.length;if(files.length===0){result.errors.push("\u672A\u627E\u5230\u4EFB\u4F55\u6E90\u7801\u6587\u4EF6");return result}if(verbose)console.log(`[扫描] 找到 ${files.length} 个源码文件\n`);// 2. 读取所有文件内容并合并（用于全局检测）
+let allContent="";for(const file of files){const content=readFileContent(file);if(content){allContent+=content+"\n";result.stats.scannedFiles++}}// 3. 判断集成类型
+result.stats.hasTrackingImport=hasTrackingImport(allContent);result.stats.hasSDKImport=hasSDKImport(allContent);if(result.stats.hasTrackingImport&&result.stats.hasSDKImport){result.integrationType="sdk";// SDK 优先
+}else if(result.stats.hasSDKImport){result.integrationType="sdk"}else if(result.stats.hasTrackingImport){result.integrationType="tracking"}else{result.errors.push("\u672A\u68C0\u6D4B\u5230 @playcraft/adsdk \u6216 @playcraft/ads-tracking \u7684\u5BFC\u5165");return result}if(verbose){console.log(`[集成类型] ${result.integrationType==="sdk"?"SDK \u96C6\u6210\uFF08\u901A\u8FC7 sdk \u9759\u6001\u65B9\u6CD5\u8C03\u7528\uFF09":"\u76F4\u63A5 tracking \u96C6\u6210"}`);console.log(`[导入检测] SDK: ${result.stats.hasSDKImport?"\u2713":"\u2717"} | Tracking: ${result.stats.hasTrackingImport?"\u2713":"\u2717"}\n`)}// 4. 检测每个埋点方法
+for(const method of TRACKING_METHODS){let found=false;if(result.integrationType==="sdk"){// SDK 集成：检测 SDK 方法调用
+const sdkMethod=Object.keys(SDK_TO_TRACKING_MAP).find(key=>SDK_TO_TRACKING_MAP[key]===method.name);if(sdkMethod){found=detectSDKCall(allContent,sdkMethod)}}else if(result.integrationType==="tracking"){// 直接 tracking 集成：检测 tracking 方法调用
+found=detectDirectTrackingCall(allContent,method.name)}result.methods.push({method:method.name,found,required:method.required,description:method.description});// 必须方法未找到 -> 错误
+if(method.required&&!found){result.errors.push(`❌ 缺少必须的埋点方法: ${method.name} (${method.description})`)}// 可选方法未找到 -> 警告
+if(!method.required&&!found){result.warnings.push(`⚠️  未找到可选埋点方法: ${method.name} (${method.description})`)}}// 5. 判断验证结果
+result.success=result.errors.length===0;return result}// ============================================================
+// 格式化输出
+// ============================================================
+/**
+ * 格式化验证结果并输出到控制台
+ * @param {ValidationResult} result - 验证结果
+ * @param {boolean} [showDetails=true] - 是否显示详细信息
+ */function printValidationResult(result,showDetails=true){console.log("\n"+"=".repeat(60));console.log("\uD83D\uDCCA \u57CB\u70B9\u9A8C\u8BC1\u62A5\u544A");console.log("=".repeat(60));// 统计信息
+console.log(`\n📁 文件统计: 扫描 ${result.stats.scannedFiles}/${result.stats.totalFiles} 个文件`);console.log(`🔗 集成类型: ${result.integrationType==="sdk"?"SDK \u96C6\u6210":result.integrationType==="tracking"?"Tracking \u76F4\u63A5\u96C6\u6210":"\u672A\u68C0\u6D4B\u5230"}`);// 方法检测结果
+if(showDetails){console.log("\n\uD83D\uDCCB \u65B9\u6CD5\u68C0\u6D4B\u660E\u7EC6:");console.log("-".repeat(60));const requiredMethods=result.methods.filter(m=>m.required);const optionalMethods=result.methods.filter(m=>!m.required);console.log("\n\u5FC5\u987B\u65B9\u6CD5:");for(const m of requiredMethods){const status=m.found?"\u2705":"\u274C";console.log(`  ${status} ${m.method.padEnd(35)} ${m.found?"\u5DF2\u8C03\u7528":"\u672A\u8C03\u7528"}`)}console.log("\n\u53EF\u9009\u65B9\u6CD5:");for(const m of optionalMethods){const status=m.found?"\u2705":"\u26A0\uFE0F ";console.log(`  ${status} ${m.method.padEnd(35)} ${m.found?"\u5DF2\u8C03\u7528":"\u672A\u8C03\u7528"}`)}}// 错误信息
+if(result.errors.length>0){console.log("\n\u274C \u9519\u8BEF:");result.errors.forEach(err=>console.log(`  ${err}`))}// 警告信息
+if(result.warnings.length>0){console.log("\n\u26A0\uFE0F  \u8B66\u544A:");result.warnings.forEach(warn=>console.log(`  ${warn}`))}// 最终结果
+console.log("\n"+"=".repeat(60));if(result.success){console.log("\u2705 \u9A8C\u8BC1\u901A\u8FC7\uFF01\u6240\u6709\u5FC5\u987B\u7684\u57CB\u70B9\u65B9\u6CD5\u90FD\u5DF2\u6B63\u786E\u8C03\u7528\u3002")}else{console.log("\u274C \u9A8C\u8BC1\u5931\u8D25\uFF01\u5B58\u5728\u7F3A\u5931\u7684\u5FC5\u987B\u57CB\u70B9\u65B9\u6CD5\uFF0C\u8BF7\u68C0\u67E5\u4EE3\u7801\u3002")}console.log("=".repeat(60)+"\n")}// ============================================================
+// 导出
+// ============================================================
+module.exports={// 核心验证函数
+validateTracking,printValidationResult,// 配置数据（供外部使用）
+TRACKING_METHODS,SDK_TO_TRACKING_MAP,// 工具函数（供外部使用）
+scanSourceFiles,detectDirectTrackingCall,detectSDKCall,hasTrackingImport,hasSDKImport};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/devkit",
-  "version": "1.0.14",
+  "version": "1.0.15-beta.1",
   "description": "HTML5 Playable Ads 构建工具，支持多广告渠道打包",
   "main": "core/index.js",
   "module": "core/index.js",
@@ -15,7 +15,8 @@
     "defines.d.ts"
   ],
   "scripts": {
-    "deploy": "npm run build && cd dist && npm publish --registry https://registry.npmjs.org/ --access public"
+    "deploy": "npm run build && cd dist && npm publish --registry https://registry.npmjs.org/ --access public",
+    "deploy:beta": "npm run build && cd dist && npm publish --registry https://registry.npmjs.org/ --access public --tag beta"
   },
   "author": "Tencent ADS Team",
   "license": "MIT",