@playcraft/cli 0.0.52 → 0.0.55

package/dist/commands/create.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import pc from 'picocolors';
 import ora from 'ora';
+import { resolveCreateTemplate, resolveCreateTemplateDir, } from '../scaffold/templates.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 /** 生成一个本地占位 Project ID（99xxxxxx），后续可通过 playcraft config set 更新为真实 ID */
@@ -873,16 +874,151 @@ async function runEnsureProject(targetDir) {
         return { warnings: ['ensure-project completed but returned non-JSON (JavaScript Object Notation, JavaScript 对象表示法) output'] };
     }
 }
+async function patchPlayablePackageJson(targetDir, name) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+    pkg.name = toPackageName(name);
+    pkg.description = `${name} — playable ad project`;
+    await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+async function initializeAgentProject(targetDir) {
+    await setupPlatformSkillLinks(targetDir, __dirname);
+    const codebuddySpinner = ora('生成 CodeBuddy Code 配置...').start();
+    try {
+        await setupCodeBuddyEnv(targetDir, __dirname);
+        codebuddySpinner.succeed('CodeBuddy Code 配置生成完成');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        codebuddySpinner.warn(`CodeBuddy Code 配置生成跳过: ${message}`);
+    }
+    const cursorSpinner = ora('生成 Cursor 配置...').start();
+    try {
+        await setupCursorEnv(targetDir);
+        cursorSpinner.succeed('Cursor 配置生成完成');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        cursorSpinner.warn(`Cursor 配置生成跳过: ${message}`);
+    }
+    try {
+        const localPath = path.join(targetDir, '.claude', 'settings.local.json');
+        const localRaw = await fs.readFile(localPath, 'utf-8');
+        const localSettings = JSON.parse(localRaw);
+        fixSettingsLocalPermissions(localSettings, targetDir);
+        await fs.writeFile(localPath, JSON.stringify(localSettings, null, 2) + '\n');
+    }
+    catch {
+        // settings.local.json 不存在或解析失败，跳过
+    }
+    const ensureSpinner = ora('初始化项目工作流...').start();
+    try {
+        const ensureResult = await runEnsureProject(targetDir);
+        ensureSpinner.succeed('项目工作流初始化完成');
+        for (const warning of ensureResult.warnings ?? []) {
+            console.log(pc.dim(`  ensure-project: ${warning}`));
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ensureSpinner.fail(`项目工作流初始化失败: ${message}`);
+        process.exit(1);
+    }
+}
+function printCreateNextSteps(template, _targetDir, name, here) {
+    console.log();
+    console.log(pc.dim('下一步：'));
+    if (!here) {
+        console.log(`  ${pc.cyan(`cd ${name}`)}`);
+    }
+    console.log(`  ${pc.cyan('npm install')}`);
+    if (template.kind === 'agent') {
+        console.log(`  ${pc.cyan('playcraft skills init-atom-tree --intent "<your game keywords>"')}`);
+        console.log(`  ${pc.cyan('playcraft remix init-template --from-atom-tree')}`);
+        console.log(`  ${pc.cyan('npm run verify:contract && npm run dev')}`);
+        console.log();
+        console.log(pc.dim('如需使用 PlayCraft CLI 打渠道包：'));
+        console.log(`  ${pc.cyan('playcraft build . -p facebook')}`);
+        console.log();
+        console.log(pc.dim('正式接入 PlayCraft 后，替换项目 ID：'));
+        console.log(`  ${pc.cyan('playcraft config set --key projectId --value <真实项目ID>')}`);
+    }
+    else {
+        console.log(`  ${pc.cyan('npm run dev')}`);
+        console.log();
+        console.log(pc.dim('构建渠道包：'));
+        console.log(`  ${pc.cyan('npm run build -- google')}`);
+        console.log(`  ${pc.cyan('npm run builds')}`);
+        console.log();
+        console.log(pc.dim('或使用 PlayCraft CLI：'));
+        console.log(`  ${pc.cyan(`playcraft build ${here ? '.' : name} -p facebook`)}`);
+    }
+    console.log();
+}
+/** Resolve target directory and display name for `playcraft create`. */
+export function resolveCreatePaths(baseDir, projectName, here) {
+    const resolvedBase = path.resolve(baseDir);
+    if (here) {
+        const name = projectName?.trim() || path.basename(resolvedBase) || 'project';
+        return { targetDir: resolvedBase, name };
+    }
+    const name = projectName?.trim();
+    if (!name) {
+        throw new Error('project-name is required unless --here is set');
+    }
+    return { targetDir: path.join(resolvedBase, name), name };
+}
+/** Returns false when the user declines overwrite; exits the process. */
+export async function confirmTargetDirOverwrite(targetDir, displayLabel, force) {
+    try {
+        const stat = await fs.stat(targetDir);
+        if (!stat.isDirectory())
+            return true;
+        const entries = await fs.readdir(targetDir);
+        if (entries.length === 0)
+            return true;
+        if (force)
+            return true;
+        const { overwrite } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: pc.yellow(`目录 ${displayLabel} 已存在且非空，继续会覆盖同名文件，是否继续？`),
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(pc.yellow('已取消'));
+            process.exit(0);
+        }
+        return true;
+    }
+    catch {
+        return true;
+    }
+}
 export async function createCommand(projectName, options) {
     console.log(pc.cyan('\n🎮 PlayCraft 可玩广告项目创建\n'));
+    let template;
+    try {
+        template = resolveCreateTemplate(options.template ?? 'agent');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(pc.red(message));
+        process.exit(1);
+    }
     const baseDir = options.dir ? path.resolve(options.dir) : process.cwd();
+    const here = options.here ?? false;
+    const force = options.force ?? false;
+    const isAgentTemplate = template.kind === 'agent';
     const answers = await inquirer.prompt([
         {
             type: 'input',
             name: 'projectName',
             message: '项目目录名:',
-            default: projectName,
-            when: !projectName,
+            default: projectName ?? (here ? path.basename(baseDir) : undefined),
+            when: !projectName && !here,
             validate: (input) => {
                 if (!input.trim())
                     return '项目名称不能为空';
@@ -896,6 +1032,7 @@ export async function createCommand(projectName, options) {
             name: 'port',
             message: '本地 Agent 端口:',
             default: '2468',
+            when: isAgentTemplate,
             validate: (input) => {
                 const port = parseInt(input, 10);
                 if (isNaN(port) || port < 1 || port > 65535) {
@@ -909,6 +1046,7 @@ export async function createCommand(projectName, options) {
             name: 'skillsDir',
             message: 'Skills 目录路径 (可选，供 playcraft skills 命令使用，直接回车跳过):',
             default: '',
+            when: isAgentTemplate,
             validate: async (input) => {
                 if (!input.trim())
                     return true;
@@ -928,42 +1066,21 @@ export async function createCommand(projectName, options) {
             name: 'token',
             message: '认证令牌 (可选，可稍后通过 playcraft config set 更新):',
             default: '',
+            when: isAgentTemplate,
         },
     ]);
-    const name = projectName || answers.projectName;
-    const port = parseInt(answers.port, 10);
-    const skillsDir = answers.skillsDir?.trim() || '';
-    const token = answers.token;
+    const name = here
+        ? (projectName?.trim() || path.basename(baseDir) || 'project')
+        : (projectName || answers.projectName);
+    const port = isAgentTemplate ? parseInt(answers.port ?? '2468', 10) : 0;
+    const skillsDir = isAgentTemplate ? (answers.skillsDir?.trim() || '') : '';
     const projectId = generateMockProjectId();
-    const targetDir = path.join(baseDir, name);
-    // 检查目标目录是否已存在
-    try {
-        const stat = await fs.stat(targetDir);
-        if (stat.isDirectory()) {
-            const entries = await fs.readdir(targetDir);
-            if (entries.length > 0) {
-                const { overwrite } = await inquirer.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'overwrite',
-                        message: pc.yellow(`目录 ${name} 已存在且非空，继续会覆盖同名文件，是否继续？`),
-                        default: false,
-                    },
-                ]);
-                if (!overwrite) {
-                    console.log(pc.yellow('已取消'));
-                    process.exit(0);
-                }
-            }
-        }
-    }
-    catch {
-        // 目录不存在，正常继续
-    }
-    const spinner = ora('复制项目模板...').start();
+    const { targetDir } = resolveCreatePaths(baseDir, name, here);
+    const overwriteLabel = here ? targetDir : name;
+    await confirmTargetDirOverwrite(targetDir, overwriteLabel, force);
+    const spinner = ora(`复制项目模板 (${template.id})...`).start();
     try {
-        // 定位 project-template 目录（打包后路径：dist/commands/ → ../../project-template）
-        const templateDir = path.resolve(__dirname, '..', '..', 'project-template');
+        const templateDir = resolveCreateTemplateDir(template.id);
         try {
             await fs.access(templateDir);
         }
@@ -971,54 +1088,13 @@ export async function createCommand(projectName, options) {
             spinner.fail(`找不到项目模板目录: ${templateDir}`);
             process.exit(1);
         }
-        // 复制模板
         await copyDir(templateDir, targetDir);
-        spinner.succeed('项目模板复制完成');
-        // 为 Platform Tool skills 创建 .claude/skills/ 软连接
-        await setupPlatformSkillLinks(targetDir, __dirname);
-        // 为 CodeBuddy Code 生成独立的 .codebuddy/ 配置目录
-        const codebuddySpinner = ora('生成 CodeBuddy Code 配置...').start();
-        try {
-            await setupCodeBuddyEnv(targetDir, __dirname);
-            codebuddySpinner.succeed('CodeBuddy Code 配置生成完成');
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            codebuddySpinner.warn(`CodeBuddy Code 配置生成跳过: ${message}`);
-        }
-        // 为 Cursor 生成 .cursor/rules/ 规则文件
-        const cursorSpinner = ora('生成 Cursor 配置...').start();
-        try {
-            await setupCursorEnv(targetDir);
-            cursorSpinner.succeed('Cursor 配置生成完成');
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            cursorSpinner.warn(`Cursor 配置生成跳过: ${message}`);
-        }
-        // 修复 .claude/settings.local.json 中硬编码的开发者路径
-        try {
-            const localPath = path.join(targetDir, '.claude', 'settings.local.json');
-            const localRaw = await fs.readFile(localPath, 'utf-8');
-            const localSettings = JSON.parse(localRaw);
-            fixSettingsLocalPermissions(localSettings, targetDir);
-            await fs.writeFile(localPath, JSON.stringify(localSettings, null, 2) + '\n');
-        }
-        catch {
-            // settings.local.json 不存在或解析失败，跳过
-        }
-        const ensureSpinner = ora('初始化项目工作流...').start();
-        try {
-            const ensureResult = await runEnsureProject(targetDir);
-            ensureSpinner.succeed('项目工作流初始化完成');
-            for (const warning of ensureResult.warnings ?? []) {
-                console.log(pc.dim(`  ensure-project: ${warning}`));
-            }
+        spinner.succeed(`项目模板复制完成 (${template.label})`);
+        if (template.kind === 'playable') {
+            await patchPlayablePackageJson(targetDir, name);
         }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            ensureSpinner.fail(`项目工作流初始化失败: ${message}`);
-            process.exit(1);
+        else {
+            await initializeAgentProject(targetDir);
         }
         const gitSpinner = ora('初始化 Git 仓库...').start();
         try {
@@ -1033,25 +1109,15 @@ export async function createCommand(projectName, options) {
         // 完成提示
         console.log(pc.green(`\n✅ 项目创建完成！\n`));
         console.log(pc.bold('  目录:   ') + pc.cyan(targetDir));
-        console.log(pc.bold('  项目ID: ') + pc.cyan(projectId) + pc.dim('  （临时占位 ID，正式接入 PlayCraft 后请更新）'));
-        console.log(pc.bold('  端口:   ') + pc.cyan(String(port)));
-        if (skillsDir) {
-            console.log(pc.bold('  Skills: ') + pc.cyan(skillsDir));
+        console.log(pc.bold('  模板:   ') + pc.cyan(template.id) + pc.dim(` (${template.label})`));
+        if (isAgentTemplate) {
+            console.log(pc.bold('  项目ID: ') + pc.cyan(projectId) + pc.dim('  （临时占位 ID，正式接入 PlayCraft 后请更新）'));
+            console.log(pc.bold('  端口:   ') + pc.cyan(String(port)));
+            if (skillsDir) {
+                console.log(pc.bold('  Skills: ') + pc.cyan(skillsDir));
+            }
         }
-        console.log();
-        console.log(pc.dim('下一步：'));
-        console.log(`  ${pc.cyan(`cd ${name}`)}`);
-        console.log(`  ${pc.cyan('npm install')}`);
-        console.log(`  ${pc.cyan('playcraft skills init-atom-tree --intent "<your game keywords>"')}`);
-        console.log(`  ${pc.cyan('playcraft remix init-template --from-atom-tree')}`);
-        console.log(`  ${pc.cyan('npm run verify:contract && npm run dev')}`);
-        console.log();
-        console.log(pc.dim('如需使用 PlayCraft CLI 打渠道包：'));
-        console.log(`  ${pc.cyan('playcraft build . -p facebook')}`);
-        console.log();
-        console.log(pc.dim('正式接入 PlayCraft 后，替换项目 ID：'));
-        console.log(`  ${pc.cyan(`playcraft config set --key projectId --value <真实项目ID>`)}`);
-        console.log();
+        printCreateNextSteps(template, targetDir, name, here);
     }
     catch (error) {
         spinner.fail('项目创建失败');

package/dist/index.js

@@ -43,8 +43,11 @@ if (!process.argv.includes('upgrade')) {
 // create 命令
 program
     .command('create [project-name]')
-    .description('从模板创建新的可玩广告项目（包含 Agent Team 工作目录结构）')
+    .description('从模板创建新的可玩广告项目')
     .option('-d, --dir <path>', '在指定目录下创建项目', process.cwd())
+    .option('-t, --template <id>', '模板: agent | phaser-playable | three-playable', 'agent')
+    .option('--here', '在当前目录（或 --dir 指定目录）直接初始化，不创建子目录')
+    .option('-f, --force', '非交互模式：目标目录非空时仍覆盖同名文件')
     .action(async (projectName, options) => {
     await createCommand(projectName, options);
 });

package/dist/scaffold/templates.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { resolveCliPackageRoot } from './compose.js';
+export const CREATE_TEMPLATES = {
+    agent: {
+        id: 'agent',
+        dir: 'project-template',
+        label: 'Agent Team 工作流（默认）',
+        kind: 'agent',
+    },
+    'phaser-playable': {
+        id: 'phaser-playable',
+        dir: 'project-templates/playable-template-phaser',
+        label: 'Phaser 可玩广告模板',
+        kind: 'playable',
+    },
+    'three-playable': {
+        id: 'three-playable',
+        dir: 'project-templates/playable-template-three',
+        label: 'Three.js 可玩广告模板',
+        kind: 'playable',
+    },
+};
+export const CREATE_TEMPLATE_IDS = Object.keys(CREATE_TEMPLATES);
+export function resolveCreateTemplate(templateId) {
+    const normalized = templateId.trim();
+    const meta = CREATE_TEMPLATES[normalized];
+    if (!meta) {
+        throw new Error(`Unknown template "${templateId}". Supported: ${CREATE_TEMPLATE_IDS.join(', ')}`);
+    }
+    return meta;
+}
+export function resolveCreateTemplateDir(templateId, cliRoot = resolveCliPackageRoot()) {
+    const meta = resolveCreateTemplate(templateId);
+    return path.join(cliRoot, meta.dir);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.52",
+  "version": "0.0.55",
   "private": false,
   "type": "module",
   "engines": {
@@ -45,8 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.52",
-    "@playcraft/common": "^0.0.52",
+    "@playcraft/build": "^0.0.55",
+    "@playcraft/common": "^0.0.55",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",

package/project-templates/playable-template-phaser/.playcraftignore

@@ -0,0 +1,10 @@
+# 构建时排除的文件/目录
+.git/
+scripts/
+node_modules/
+*.md
+*.backup
+.DS_Store
+vite.config.ts
+index.html
+tsconfig.json

package/project-templates/playable-template-phaser/CLAUDE.md

@@ -0,0 +1,178 @@
+# Phaser Playable Template - 项目说明
+
+本项目是基于 Phaser 的可玩广告模板，使用 PlayCraft 平台架构（`@playcraft/adsdk` + `@playcraft/devkit`）。
+
+## 架构特点
+
+- **SDK**：`@playcraft/adsdk` - 可玩广告运行时 SDK
+- **构建工具**：`@playcraft/devkit` - 可玩广告构建工具链
+- **本地开发**：Vite 开发服务器，支持 HMR 热更新
+- **主题系统**：配置化架构，支持 JSON5 Schema + 覆盖配置
+
+## 开发命令
+
+### 本地开发
+
+```bash
+# 使用 Vite 开发服务器（推荐，速度快，支持 HMR）
+npm run dev
+
+# 使用 playable-scripts 开发服务器（与构建环境一致）
+npm run dev:wp
+```
+
+### 构建
+
+```bash
+# 构建单个渠道（preview）
+npm run build
+
+# 批量构建所有渠道
+npm run builds
+
+# 打包为 PlayCraft 模板 ZIP
+npm run pack-to-playcraft-template-zip
+```
+
+### 资源处理
+
+```bash
+# 将图片转为 WebP 格式（质量 90）
+npm run webp
+
+# 将图片转为 WebP 格式（质量 80）
+npm run webp:80
+```
+
+## 目录结构
+
+```
+playable-template-phaser/
+├── src/
+│   ├── theme/                    # 主题系统
+│   │   ├── theme.schema.json5    # 配置协议（默认值）
+│   │   ├── theme.metadata.md     # 主题元数据
+│   │   ├── blue-theme/           # 蓝色主题
+│   │   │   ├── index.ts          # 主题入口
+│   │   │   ├── theme.data.json5  # 配置覆盖
+│   │   │   └── assets/           # 主题资源
+│   │   ├── green-theme/          # 绿色主题
+│   │   ├── red-theme/            # 红色主题
+│   │   └── index.ts              # 主题统一出口
+│   ├── config/                   # 配置管理
+│   │   ├── ThemeConfig.ts        # 主题配置获取器
+│   │   └── LoadingConfig.ts      # Loading 配置
+│   ├── scenes/                   # Phaser 场景
+│   ├── managers/                 # 管理器
+│   ├── ui/                       # UI 组件
+│   ├── Game.ts                   # 游戏主类
+│   └── index.ts                  # 入口文件
+├── assets/                       # 公共资源
+├── vite.config.ts                # Vite 配置
+├── index.html                    # Vite 入口 HTML
+├── builds.config.js              # 构建配置
+├── package.json                  # 项目配置
+└── tsconfig.json                 # TypeScript 配置
+```
+
+## 主题系统
+
+### 配置优先级
+
+```
+theme.data.json5（主题覆盖）> theme.schema.json5（默认值）
+```
+
+### 切换主题
+
+修改 `src/theme/index.ts`：
+
+```typescript
+export { default } from './blue-theme'; // 蓝色主题
+// export { default } from './green-theme';  // 绿色主题
+// export { default } from './red-theme';     // 红色主题
+```
+
+### 添加新主题
+
+1. 复制现有主题目录（如 `blue-theme`）
+2. 修改 `theme.data.json5` 配置
+3. 添加主题特定资源到 `assets/` 目录
+4. 更新 `index.ts` 的资源映射
+5. 在 `theme/index.ts` 切换主题
+
+## 配置系统
+
+### 读取配置
+
+使用 `sdk.getConfig()` 或封装的配置获取器：
+
+```typescript
+import { GameThemeConfig } from './config/ThemeConfig';
+
+// 获取配置值
+const backgroundColor = GameThemeConfig.BACKGROUND_COLOR;
+const difficulty = GameThemeConfig.DIFFICULTY;
+```
+
+### 资源路径解析
+
+资源路径通过 `assetRecordByPath` 自动解析为真实 URL：
+
+```typescript
+// theme.schema.json5 中定义路径
+assets: {
+  logo: {
+    default: "./assets/logo.webp"
+  }
+}
+
+// theme/index.ts 中映射路径
+import logoWebp from 'assets/logo.webp';
+const assetRecordByPath = {
+  './assets/logo.webp': logoWebp,
+};
+
+// 代码中获取 URL
+const logoUrl = GameThemeConfig.ASSET_LOGO;  // 解析后的真实 URL
+```
+
+## 相关技能
+
+如需进行以下操作，请加载对应技能：
+
+- **SDK 埋点检查**：`playable-sdk-tracking`
+- **构建产物检查**：`playable-output-checker`
+- **项目初始化**：`playable-project-scaffold`
+- **资源提取/重打包**：`game-asset-extractor`
+
+## 常见问题
+
+### Q1: 资源 URL 为空
+
+**原因**：`assetRecordByPath` 缺少路径映射
+
+**解决**：在主题 `index.ts` 中添加资源映射
+
+### Q2: 配置值为 undefined
+
+**原因**：`theme.schema.json5` 缺少该字段的 `default` 值
+
+**解决**：在 schema 中添加字段定义及默认值
+
+### Q3: 模块顶层缓存导致配置为空
+
+**原因**：在模块加载时立即读取配置，此时 `sdk.setConfig()` 还没执行
+
+**解决**：使用 getter 延迟获取，或在运行时获取配置
+
+## 技术栈
+
+- **游戏引擎**：Phaser 3.88.2
+- **语言**：TypeScript 5.7.2
+- **构建工具**：Vite 5.4.0 (本地) / @playcraft/devkit (生产)
+- **配置格式**：JSON5 (支持注释)
+
+## 更多信息
+
+详细的平台改造指南请参考：`playable-template/skills/playable-platform-refactor/SKILL.md`