@playcraft/cli 0.0.19 → 0.0.21

package/dist/commands/tools.js

@@ -0,0 +1,447 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { tmpdir } from 'os';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+const TMP_DIR = join(tmpdir(), 'playcraft');
+function ensureTmpDir() {
+    mkdirSync(TMP_DIR, { recursive: true });
+}
+function tmpPath(prefix) {
+    return join(TMP_DIR, `${prefix}-${Date.now()}.json`);
+}
+function writeResult(prefix, data) {
+    ensureTmpDir();
+    const path = tmpPath(prefix);
+    writeFileSync(path, JSON.stringify(data, null, 2));
+    return path;
+}
+function handleError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${msg}`);
+    process.exit(1);
+}
+export function registerToolsCommands(program) {
+    const tools = program
+        .command('tools')
+        .description('调用后端 /api/agent/tools：素材 AI（generate-*）与平台能力（Git/沙箱构建/发布/查询/Prefab 等）');
+    // ─── Generation ─────────────────────────────────────────────
+    tools.command('generate-image')
+        .description('AI 生成图片')
+        .requiredOption('--prompt <text>', '图片描述')
+        .option('--aspect-ratio <ratio>', '宽高比 (1:1|16:9|9:16|3:4|4:3)', '1:1')
+        .requiredOption('--output <path>', '保存路径')
+        .option('--image-size <size>', '图片尺寸 (1K|2K|4K)')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/generate-image', {
+                prompt: opts.prompt,
+                aspectRatio: opts.aspectRatio,
+                imageSize: opts.imageSize,
+            });
+            mkdirSync(dirname(opts.output), { recursive: true });
+            const buf = Buffer.from(result.base64, 'base64');
+            writeFileSync(opts.output, buf);
+            const sizeKB = Math.round(buf.length / 1024);
+            console.log(`Image saved to ${opts.output} (${sizeKB}KB, ${result.mimeType})`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('generate-sfx')
+        .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
+        .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
+        .option('--duration <seconds>', '时长（秒，0.5-30）', parseFloat)
+        .option('--loop', '生成可循环的音效', false)
+        .requiredOption('--output <path>', '保存路径，如 ./assets/audio/click.mp3')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/generate-sfx', {
+                prompt: opts.prompt,
+                duration: opts.duration,
+                loop: opts.loop,
+            });
+            mkdirSync(dirname(opts.output), { recursive: true });
+            const buf = Buffer.from(result.audioBase64, 'base64');
+            writeFileSync(opts.output, buf);
+            const sizeKB = Math.round(buf.length / 1024);
+            console.log(`SFX saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('generate-bgm')
+        .description('AI 生成 BGM（30s 循环），使用 Google Lyria 3')
+        .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
+        .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
+        .option('--bpm <bpm>', '目标 BPM', parseInt)
+        .requiredOption('--output <path>', '保存路径，如 ./assets/audio/bgm.mp3')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/generate-bgm', {
+                prompt: opts.prompt,
+                style: opts.style,
+                bpm: opts.bpm,
+            });
+            mkdirSync(dirname(opts.output), { recursive: true });
+            const buf = Buffer.from(result.audioBase64, 'base64');
+            writeFileSync(opts.output, buf);
+            const sizeKB = Math.round(buf.length / 1024);
+            console.log(`BGM saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── Project Pipeline ───────────────────────────────────────
+    tools.command('save-to-git')
+        .description('同步沙箱内容到 Git 仓库')
+        .requiredOption('--project-id <id>', '项目数字 ID', parseInt)
+        .requiredOption('--message <text>', '提交信息')
+        .option('--branch <name>', '分支名', 'main')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/save-to-git', {
+                projectId: opts.projectId,
+                branch: opts.branch,
+                commitMessage: opts.message,
+            });
+            if (result.success) {
+                console.log(`Saved to git: commit ${result.commitHash ?? 'unknown'}`);
+            }
+            else if (result.conflict) {
+                console.log(`Conflict detected in ${result.conflictFiles?.length ?? 0} file(s)`);
+                if (result.conflictFiles?.length) {
+                    for (const f of result.conflictFiles)
+                        console.log(`  - ${f}`);
+                }
+                process.exit(1);
+            }
+            else {
+                console.error(`Error: ${result.error ?? 'Save failed'}`);
+                process.exit(1);
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('build-project')
+        .description('在沙箱中执行项目构建')
+        .requiredOption('--project-id <id>', '项目数字 ID', parseInt)
+        .option('--branch <name>', '分支名', 'main')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/build-project', {
+                projectId: opts.projectId,
+                branch: opts.branch,
+            });
+            if (result.success === false) {
+                if (result.output) {
+                    const logPath = writeResult('build', { output: result.output, error: result.error });
+                    console.error(`Build failed. Log: ${logPath}`);
+                }
+                else {
+                    console.error(`Error: ${result.error ?? 'Build failed'}`);
+                }
+                process.exit(1);
+            }
+            if (result.output) {
+                const logPath = writeResult('build', result);
+                console.log(`Build succeeded`);
+                console.log(`Log: ${logPath}`);
+            }
+            else {
+                console.log('Build succeeded');
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('publish')
+        .description('将构建产物上传到 COS，获取预览 URL')
+        .requiredOption('--project-id <id>', '项目数字 ID', parseInt)
+        .option('--branch <name>', '分支名', 'main')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/publish-to-cos', {
+                projectId: opts.projectId,
+                branch: opts.branch,
+            });
+            if (result.success === false) {
+                console.error(`Error: ${result.error ?? 'Publish failed'}`);
+                process.exit(1);
+            }
+            if (result.previewUrl) {
+                console.log(`Published: ${result.previewUrl}`);
+            }
+            else {
+                console.log('Published successfully');
+            }
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('create-remix')
+        .description('基于项目创建 Remix 分支')
+        .requiredOption('--project-id <id>', '项目数字 ID')
+        .requiredOption('--name <name>', 'Remix 显示名称')
+        .option('--source-branch <name>', '源分支', 'main')
+        .option('--description <text>', '描述')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/create-remix', {
+                projectId: opts.projectId,
+                sourceBranch: opts.sourceBranch,
+                name: opts.name,
+                description: opts.description,
+            });
+            if (result.success === false) {
+                console.error(`Error: ${result.error ?? 'Create remix failed'}`);
+                process.exit(1);
+            }
+            console.log(`Remix created: ${opts.name} (project ${result.projectId}, branch ${result.branchName})`);
+            if (result.editorUrl)
+                console.log(`Editor: ${result.editorUrl}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── Queries ────────────────────────────────────────────────
+    tools.command('list-templates')
+        .description('列出可用项目模板')
+        .option('--tag <filter>', '按标签过滤')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const params = {};
+            if (opts.tag)
+                params.tagFilter = opts.tag;
+            const result = await client.get('/list-templates', params);
+            const detailsPath = writeResult('list-templates', result);
+            if (opts.tag) {
+                console.log(`Found ${result.templateCount} templates matching "${opts.tag}" (${result.totalCount} total)`);
+            }
+            else {
+                console.log(`Found ${result.templateCount} templates`);
+            }
+            console.log(`Details: ${detailsPath}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('list-assets')
+        .description('列出项目资产')
+        .requiredOption('--project-id <id>', '项目数字 ID')
+        .option('--branch <name>', '分支名')
+        .option('--types <list>', '资产类型，逗号分隔（texture,script,audio,model...）')
+        .option('--search <keyword>', '名称搜索')
+        .option('--limit <n>', '最大数量', '30')
+        .option('--skip <n>', '偏移', '0')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const params = { projectId: opts.projectId };
+            if (opts.branch)
+                params.branch = opts.branch;
+            if (opts.types)
+                params.types = opts.types;
+            if (opts.search)
+                params.search = opts.search;
+            if (opts.limit)
+                params.limit = opts.limit;
+            if (opts.skip)
+                params.skip = opts.skip;
+            const result = await client.get('/list-project-assets', params);
+            const detailsPath = writeResult('list-assets', result);
+            const typeSummary = Object.entries(result.byTypeCount)
+                .map(([k, v]) => `${k}: ${v}`)
+                .join(', ');
+            console.log(`Found ${result.total} assets (${typeSummary})`);
+            console.log(`Details: ${detailsPath}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('list-remixes')
+        .description('列出可访问的 Remix 项目')
+        .option('--scope <scope>', 'my 或 gallery', 'my')
+        .option('--search <keyword>', '搜索')
+        .option('--limit <n>', '最大数量', '20')
+        .option('--page <n>', '页码', '1')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const params = {};
+            if (opts.scope)
+                params.scope = opts.scope;
+            if (opts.search)
+                params.search = opts.search;
+            if (opts.limit)
+                params.limit = opts.limit;
+            if (opts.page)
+                params.page = opts.page;
+            const result = await client.get('/list-remixes', params);
+            const detailsPath = writeResult('list-remixes', result);
+            console.log(`Found ${result.total} remixes (page ${result.page}/${result.totalPages})`);
+            console.log(`Details: ${detailsPath}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── Publish ────────────────────────────────────────────────
+    tools.command('publish-prefab')
+        .description('发布 Remixable Prefab 到资产库')
+        .requiredOption('--remix-project-id <id>', 'Remix 项目 ID', parseInt)
+        .requiredOption('--template <name>', '模板名')
+        .requiredOption('--variant <name>', '变体名')
+        .requiredOption('--prefab <name>', '预制件名')
+        .requiredOption('--staging-root <path>', 'Staging 目录路径')
+        .option('--visibility <v>', 'public 或 team', 'team')
+        .option('--team-id <id>', '团队 ID')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/publish-prefab', {
+                remixProjectId: opts.remixProjectId,
+                templateName: opts.template,
+                variantName: opts.variant,
+                prefabName: opts.prefab,
+                stagingRoot: opts.stagingRoot,
+                visibility: opts.visibility,
+                teamId: opts.teamId,
+            });
+            if (result.success === false) {
+                console.error(`Error: ${result.error ?? 'Publish prefab failed'}`);
+                process.exit(1);
+            }
+            console.log(`Prefab published: ${result.bundlePath} (${result.uploaded} files)`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    // ─── Builds ─────────────────────────────────────────────────
+    tools.command('list-builds')
+        .description('查看云端构建列表')
+        .option('--project-id <id>', '项目数字 ID（不填则查看当前用户所有项目）')
+        .option('--branch <name>', '按分支过滤')
+        .option('--status <status>', '按状态过滤 (queued|running|success|failed)')
+        .option('--platform <platform>', '按平台过滤 (facebook|snapchat|playcraft...)')
+        .option('--search <keyword>', '按名称/提交信息搜索')
+        .option('--limit <n>', '最大数量', '20')
+        .option('--skip <n>', '偏移', '0')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const params = {};
+            if (opts.projectId)
+                params.projectId = opts.projectId;
+            if (opts.branch)
+                params.branchName = opts.branch;
+            if (opts.status)
+                params.status = opts.status;
+            if (opts.platform)
+                params.platform = opts.platform;
+            if (opts.search)
+                params.search = opts.search;
+            if (opts.limit)
+                params.limit = opts.limit;
+            if (opts.skip)
+                params.skip = opts.skip;
+            const result = await client.get('/list-builds', params);
+            const detailsPath = writeResult('list-builds', result);
+            const statusCounts = {};
+            for (const item of result.items) {
+                statusCounts[item.status] = (statusCounts[item.status] ?? 0) + 1;
+            }
+            const statusSummary = Object.entries(statusCounts).map(([s, n]) => `${s}: ${n}`).join(', ');
+            console.log(`Found ${result.total} builds (${statusSummary || 'none'})`);
+            console.log(`Details: ${detailsPath}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('get-build')
+        .description('查看单次构建详情（状态、产物、校验结果等）')
+        .requiredOption('--id <buildId>', '构建 ID')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.get('/get-build', { id: opts.id });
+            if ('error' in result && result.error) {
+                console.error(`Error: ${result.error}`);
+                process.exit(1);
+            }
+            const detailsPath = writeResult('get-build', result);
+            const statusLine = result.status === 'running' && result.progress != null
+                ? `${result.status} (${result.progress}%)`
+                : result.status;
+            const sizeMB = result.outputSize ? `${(result.outputSize / 1024 / 1024).toFixed(2)}MB` : 'unknown size';
+            const nameLabel = result.name ? ` "${result.name}"` : '';
+            console.log(`Build ${result.id}${nameLabel}: ${statusLine} [${result.platform}/${result.format}] ${sizeMB}`);
+            if (result.error)
+                console.log(`Error: ${result.error}`);
+            if (result.downloadUrl)
+                console.log(`Download: ${result.downloadUrl}`);
+            if (result.previewUrl)
+                console.log(`Preview: ${result.previewUrl}`);
+            if (result.validationPassed === false) {
+                const errors = (result.validationWarnings ?? []).filter((w) => w.severity === 'error');
+                console.log(`Validation: FAILED (${errors.length} error(s))`);
+            }
+            else if (result.validationPassed === true) {
+                console.log(`Validation: PASSED`);
+            }
+            console.log(`Details: ${detailsPath}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.command('get-build-download')
+        .description('获取构建产物下载地址')
+        .requiredOption('--id <buildId>', '构建 ID')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.get('/get-build-download', { id: opts.id });
+            if (result.error) {
+                console.error(`Error: ${result.error}`);
+                process.exit(1);
+            }
+            console.log(`Download URL: ${result.downloadUrl}`);
+            if (result.previewUrl)
+                console.log(`Preview URL: ${result.previewUrl}`);
+            const sizeMB = result.size ? ` (${(result.size / 1024 / 1024).toFixed(2)}MB)` : '';
+            console.log(`Platform: ${result.platform}/${result.format}${sizeMB}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    tools.addHelpText('before', () => [
+        '子命令分区（均需 PLAYCRAFT_API_URL + PLAYCRAFT_SANDBOX_TOKEN 或 .playcraft.json）：',
+        '',
+        '  素材 AI    generate-image, generate-sfx, generate-bgm',
+        '  流水线     save-to-git, build-project, publish, create-remix',
+        '  查询       list-templates, list-assets, list-remixes, list-builds, get-build, get-build-download',
+        '  资产库     publish-prefab',
+        '',
+    ].join('\n'));
+}

package/dist/index.js

@@ -15,14 +15,19 @@ import { upgradeCommand } from './commands/upgrade.js';
 import { checkForUpdates } from './utils/version-checker.js';
 import { syncCommand } from './commands/sync.js';
 import { fixIdsCommand } from './commands/fix-ids.js';
+import { registerToolsCommands } from './commands/tools.js';
+import { registerImageCommands } from './commands/image.js';
+import { registerAudioCommands } from './commands/audio.js';
+import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
 program
     .name('playcraft')
-    .description('PlayCraft Local Dev Agent - 本地开发助手')
+    .description(CLI_ROOT_DESCRIPTION)
     .version(packageJson.version);
+registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
 if (!process.argv.includes('upgrade')) {
@@ -156,6 +161,7 @@ program
     .option('--compress-models', '压缩 3D 模型（默认根据平台配置，仅 PlayCanvas/Three.js/Babylon.js）')
     .option('--no-compress-models', '禁用模型压缩')
     .option('--model-compression <method>', '模型压缩方法 (draco|meshopt)', 'draco')
+    .option('--use-playable-scripts', '使用 @playcraft/devkit 构建工具打包（可玩广告项目专用）', false)
     .action(async (projectPath, options) => {
     await buildCommand(projectPath, options);
 });
@@ -281,6 +287,8 @@ program
     .option('--no-compress-models', '禁用模型压缩')
     .option('--model-compression <method>', '模型压缩方法 (draco|meshopt)', 'draco')
     .option('--esm-mode <mode>', 'ESM 模块处理模式 (auto|enabled|disabled)', 'auto')
+    .option('--use-playable-scripts', '使用 @playcraft/devkit 构建工具打包（可玩广告项目专用）', false)
+    .option('--theme <theme>', '指定要构建的主题（devkit 项目专用）')
     .action(async (projectPath, options) => {
     await buildAllCommand(projectPath, options);
 });
@@ -301,4 +309,17 @@ program
     .action(async (options) => {
     await upgradeCommand(options);
 });
+// topics — 与根 --help 顶部一致的命令分区说明（便于脚本或文档引用）
+program
+    .command('topics')
+    .description('打印命令分区说明（本地开发 / 素材 / 平台）')
+    .action(() => {
+    process.stdout.write(getCliTopicsHelpText());
+});
+// Agent domain tools (playcraft tools <command>)
+registerToolsCommands(program);
+// Local image processing (playcraft image <command>)
+registerImageCommands(program);
+// Local audio processing (playcraft audio <command>)
+registerAudioCommands(program);
 program.parse(process.argv);