@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/commands/create.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { execFileSync, execSync } from 'child_process';
 import inquirer from 'inquirer';
 import fs from 'fs/promises';
@@ -6,8 +7,11 @@ import { fileURLToPath } from 'url';
 import pc from 'picocolors';
 import ora from 'ora';
 import { resolveCreateTemplate, resolveCreateTemplateDir, } from '../scaffold/templates.js';
+import { PLATFORM_SKILL_DIRS } from './platform-skills.generated.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/** `@playcraft/skills` 包内 Platform Skill 的目录名（与 Atom Skill 的 `skills/` 区分）。 */
+const PLATFORM_SKILLS_DIRNAME = 'playcraft-skills';
 /** 生成一个本地占位 Project ID（99xxxxxx），后续可通过 playcraft config set 更新为真实 ID */
 function generateMockProjectId() {
     const suffix = Math.floor(Math.random() * 90_000_000) + 10_000_000;
@@ -849,7 +853,7 @@ function extractSkillBodyForCursor(content) {
  * @param cliCommandsDir CLI 命令所在目录（用于解析 skills 包位置）
  * @param configDir 配置目录名（如 '.claude' 或 '.codebuddy'）
  */
-async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
+export async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
     const skillsLinkDir = path.join(targetDir, configDir, 'skills');
     await fs.mkdir(skillsLinkDir, { recursive: true });
     // 以下 Skill 在项目模板中以静态目录形式存在，不创建软连接覆盖它们。
@@ -868,11 +872,12 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         'playcraft-image-generation',
         'playcraft-audio-generation',
     ]);
-    // 尝试从 CLI 安装包的位置定位 @playcraft/skills/skills 目录
+    // Platform Skill 住在 playcraft-skills/，与 Atom Skill 的 skills/ 是两个目录。
+    // 尝试从 CLI 安装包的位置定位它（monorepo 内或与 CLI 平级安装时可解析）。
     const candidateDirs = [
-        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', 'skills', 'skills'),
+        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
     ];
     let resolvedSkillsDir = null;
     for (const dir of candidateDirs) {
@@ -885,18 +890,24 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
             // 继续下一个候选
         }
     }
-    // 相对路径（指向 npm install 后的 node_modules）始终创建，作为安装后激活的备用
-    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', 'skills');
+    // 相对路径（指向 npm install 后的 node_modules）作为安装后激活的备用
+    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', PLATFORM_SKILLS_DIRNAME);
     if (resolvedSkillsDir) {
-        // 能立即解析 → 创建指向绝对路径的软连接，当下即可使用
+        // 能立即解析 → 以真实目录为准创建绝对路径软连接，当下即可使用。
+        // 按「是否含 SKILL.md」判定而非 playcraft- 前缀：sound-effects 无前缀但同样是平台技能。
         const entries = await fs.readdir(resolvedSkillsDir, { withFileTypes: true });
         for (const entry of entries) {
-            if (!entry.name.startsWith('playcraft-') || staticSkills.has(entry.name))
+            if (!entry.isDirectory() || staticSkills.has(entry.name))
                 continue;
-            const linkPath = path.join(skillsLinkDir, entry.name);
             const targetPath = path.join(resolvedSkillsDir, entry.name);
             try {
-                await fs.symlink(targetPath, linkPath, 'dir');
+                await fs.access(path.join(targetPath, 'SKILL.md'));
+            }
+            catch {
+                continue;
+            }
+            try {
+                await fs.symlink(targetPath, path.join(skillsLinkDir, entry.name), 'dir');
             }
             catch {
                 // 已存在则跳过
@@ -904,28 +915,9 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         }
     }
     else {
-        // 无法立即解析 → 创建指向 node_modules 的相对路径软连接，npm install 后自动激活
-        const knownPlatformTools = [
-            'playcraft-asset-management',
-            'playcraft-audio-generation',
-            'playcraft-build',
-            'playcraft-code-editor',
-            'playcraft-create-remix',
-            'playcraft-deploy',
-            'playcraft-image-generation',
-            'playcraft-image-processing',
-            'playcraft-platform-intro',
-            'playcraft-prefab',
-            'playcraft-project-management',
-            'playcraft-remix-workflow',
-            'playcraft-save',
-            'playcraft-skill-recommender',
-            'playcraft-sprite-generation',
-            'playcraft-sprite-remix',
-            'playcraft-sprite-sheet',
-            'playcraft-3d-flip-sprite',
-        ];
-        for (const name of knownPlatformTools) {
+        // 无法立即解析 → 指向 node_modules 的相对路径软连接，npm install 后自动激活。
+        // 清单由 scripts/generate-platform-skills.mjs 从真实目录生成并由 CI 校验，不要手写。
+        for (const name of PLATFORM_SKILL_DIRS) {
             if (staticSkills.has(name))
                 continue;
             const linkPath = path.join(skillsLinkDir, name);
@@ -1289,6 +1281,7 @@ export async function createCommand(projectName, options) {
                 smokeSpinner.warn(`Harness 自检跳过: ${message}`);
             }
         }
+        await prepareLocalSkillLifecycle(targetDir, 'create');
         const gitSpinner = ora(isWorktreeMode ? '提交项目分支...' : '初始化 Git 仓库...').start();
         try {
             if (isWorktreeMode) {

package/dist/commands/image-layer-messages.js

@@ -0,0 +1,37 @@
+const messages = {
+    en: {
+        decompose: 'Separate an image into a base and editable layers using the cloud workspace pipeline',
+        input: 'Input image path or image address', outputDir: 'Output directory',
+        engine: 'Layer engine: seedream (workspace) or qwen (legacy)', imageModel: 'Image model reference for workspace layer separation',
+        size: 'Workspace layer size: auto, 1K, 1.5K, 2K', prompt: 'Optional layer guidance', team: 'Team used for model configuration',
+        numLayers: 'Legacy Qwen layer count, 2–10', safety: 'Disable the legacy Qwen safety checker', format: 'Legacy Qwen output format',
+        ninePatch: 'Analyze stretchable nine-patch borders with the cloud workspace vision model',
+        output: 'Save the analysis as a file', visionModel: 'Vision model reference',
+        invalidFile: 'Input must be a regular image file of at most {maxBytes} bytes', downloadFailed: 'Image download failed ({status})',
+        tooLarge: 'Input image exceeds {maxBytes} bytes', unsupportedInput: 'Input must be a single image in a supported format',
+        unsupportedOutput: 'Unsupported output image type: {mimeType}', invalidEngine: '--engine must be seedream or qwen',
+        legacyOnly: '--num-layers, --no-safety-checker and --output-format require --engine qwen',
+        workspaceOnly: '--image-model, --size and --team-id require --engine seedream',
+        invalidSize: '--size must be auto, 1K, 1.5K or 2K', invalidCount: '--num-layers must be an integer between 2 and 10',
+        saved: 'Saved separated layers and decompose-layers-meta.json to {outputDir}', failed: 'Image command failed: {message}',
+    },
+    zh: {
+        decompose: '使用云工作区同款管线，将图片分解为底图和可编辑图层',
+        input: '输入图片路径或图片地址', outputDir: '输出目录',
+        engine: '分层引擎：seedream（云工作区）或 qwen（旧版）', imageModel: '云工作区图层分离的图像模型引用',
+        size: '云工作区分层尺寸：auto、1K、1.5K、2K', prompt: '可选图层分离提示词', team: '模型配置所属团队',
+        numLayers: '旧版 Qwen 图层数量，2–10', safety: '关闭旧版 Qwen 安全检测', format: '旧版 Qwen 输出格式',
+        ninePatch: '使用云工作区视觉模型分析点九图可拉伸边界', output: '将分析结果保存到文件', visionModel: '视觉模型引用',
+        invalidFile: '输入必须是大小不超过 {maxBytes} 字节的普通图片文件', downloadFailed: '图片下载失败（{status}）',
+        tooLarge: '输入图片超过 {maxBytes} 字节', unsupportedInput: '输入必须是支持格式的单张图片',
+        unsupportedOutput: '不支持的输出图片类型：{mimeType}', invalidEngine: '--engine 必须为 seedream 或 qwen',
+        legacyOnly: '--num-layers、--no-safety-checker 和 --output-format 需要使用 --engine qwen',
+        workspaceOnly: '--image-model、--size 和 --team-id 需要使用 --engine seedream',
+        invalidSize: '--size 必须为 auto、1K、1.5K 或 2K', invalidCount: '--num-layers 必须为 2 到 10 之间的整数',
+        saved: '已将分离图层与 decompose-layers-meta.json 保存到 {outputDir}', failed: '图片命令执行失败：{message}',
+    },
+};
+export function imageLayerMessage(key, values = {}) {
+    const language = (process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en';
+    return messages[language][key].replace(/\{(\w+)\}/g, (match, name) => String(values[name] ?? match));
+}

package/dist/commands/image-layer-tools.js

@@ -0,0 +1,185 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import sharp from 'sharp';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { imageLayerMessage as t } from './image-layer-messages.js';
+import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
+const MAX_IMAGE_BYTES = 30_000_000;
+const isRemote = (input) => /^https?:\/\//i.test(input);
+function localImageBytes(input, maxBytes) {
+    const filename = resolveSandboxPath(input);
+    const info = statSync(filename);
+    if (!info.isFile() || info.size > maxBytes) {
+        throw new Error(t('invalidFile', { maxBytes }));
+    }
+    return readFileSync(filename);
+}
+async function inputImage(input) {
+    let bytes;
+    if (isRemote(input)) {
+        const response = await fetch(input, { signal: AbortSignal.timeout(60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(t('downloadFailed', { status: response.status }));
+        if (Number(response.headers.get('content-length')) > MAX_IMAGE_BYTES) {
+            await response.body.cancel();
+            throw new Error(t('tooLarge', { maxBytes: MAX_IMAGE_BYTES }));
+        }
+        const reader = response.body.getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                total += chunk.value.byteLength;
+                if (total > MAX_IMAGE_BYTES)
+                    throw new Error(t('tooLarge', { maxBytes: MAX_IMAGE_BYTES }));
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        bytes = Buffer.concat(chunks);
+    }
+    else {
+        bytes = localImageBytes(input, MAX_IMAGE_BYTES);
+    }
+    const metadata = await sharp(bytes).metadata();
+    const inputMimeTypes = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' };
+    const mimeType = inputMimeTypes[metadata.format ?? ''];
+    if (!mimeType || (metadata.pages ?? 1) > 1)
+        throw new Error(t('unsupportedInput'));
+    return { imageBase64: bytes.toString('base64'), mimeType };
+}
+function imageExtension(mimeType) {
+    const formats = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
+    const extension = formats[mimeType];
+    if (!extension)
+        throw new Error(t('unsupportedOutput', { mimeType }));
+    return extension;
+}
+function saveLayer(outputDir, stem, layer) {
+    const file = `${stem}.${imageExtension(layer.mimeType)}`;
+    writeFileSync(join(outputDir, file), Buffer.from(layer.imageBase64, 'base64'));
+    const { imageBase64: _bytes, ...metadata } = layer;
+    return { ...metadata, file };
+}
+function fail(error) {
+    console.error(t('failed', { message: error instanceof Error ? error.message : String(error) }));
+    process.exit(1);
+}
+export function registerImageLayerTools(image) {
+    image.command('decompose-layers')
+        .description(t('decompose'))
+        .requiredOption('--input <path>', t('input'))
+        .option('--output-dir <dir>', t('outputDir'), './decompose-layers-output')
+        .option('--engine <name>', t('engine'), 'seedream')
+        .option('--image-model <ref>', t('imageModel'))
+        .option('--size <size>', t('size'))
+        .option('--prompt <text>', t('prompt'), '')
+        .option('--team-id <id>', t('team'))
+        .option('--num-layers <n>', t('numLayers'), (value) => Number(value), 4)
+        .option('--no-safety-checker', t('safety'))
+        .option('--output-format <format>', t('format'), 'png')
+        .action(async (opts, command) => {
+        try {
+            const legacyFlags = ['numLayers', 'safetyChecker', 'outputFormat'].some(name => command.getOptionValueSource(name) === 'cli');
+            const explicitEngine = command.getOptionValueSource('engine') === 'cli';
+            const engine = legacyFlags && !explicitEngine ? 'qwen' : opts.engine;
+            if (!['seedream', 'qwen'].includes(engine))
+                throw new Error(t('invalidEngine'));
+            if (engine === 'seedream' && legacyFlags) {
+                throw new Error(t('legacyOnly'));
+            }
+            if (engine === 'qwen' && (opts.imageModel || opts.size || opts.teamId)) {
+                throw new Error(t('workspaceOnly'));
+            }
+            if (opts.size && !['auto', '1K', '1.5K', '2K'].includes(opts.size)) {
+                throw new Error(t('invalidSize'));
+            }
+            if (engine === 'qwen' && (!Number.isInteger(opts.numLayers) || opts.numLayers < 2 || opts.numLayers > 10)) {
+                throw new Error(t('invalidCount'));
+            }
+            const outputDir = resolveSandboxPath(opts.outputDir);
+            const input = opts.input;
+            const startedAt = Date.now();
+            const client = new AgentApiClient();
+            let metadata;
+            const savedImages = [];
+            if (engine === 'seedream') {
+                const result = await client.post('/image/layer-decomposition', {
+                    ...await inputImage(input),
+                    prompt: opts.prompt || undefined,
+                    size: opts.size || 'auto',
+                    imageModelRef: opts.imageModel,
+                    teamId: opts.teamId,
+                });
+                mkdirSync(outputDir, { recursive: true });
+                const base = saveLayer(outputDir, 'base', result.base);
+                const layers = result.layers.map((layer, index) => saveLayer(outputDir, `layer_${String(index).padStart(2, '0')}`, layer));
+                savedImages.push(...[base, ...layers].map(layer => join(outputDir, layer.file)));
+                metadata = { source: input, engine, base, layers, usage: result.usage };
+            }
+            else {
+                const maxBytes = Number.parseInt(process.env.PLAYCRAFT_IMAGE_MAX_INPUT_BYTES || '', 10);
+                const payload = {
+                    ...(isRemote(input) ? { imageUrl: input } : {
+                        imageBase64: localImageBytes(input, maxBytes > 0 ? maxBytes : 512 * 1024 * 1024).toString('base64'),
+                    }),
+                    numLayers: opts.numLayers,
+                    prompt: opts.prompt,
+                    enableSafetyChecker: opts.safetyChecker !== false,
+                    outputFormat: opts.outputFormat,
+                };
+                const result = await client.post('/image-layered/decompose', payload);
+                mkdirSync(outputDir, { recursive: true });
+                const layers = result.layers.map((layer) => {
+                    const file = `layer_${String(layer.index).padStart(2, '0')}.${imageExtension(layer.mimeType)}`;
+                    writeFileSync(join(outputDir, file), Buffer.from(layer.imageBase64, 'base64'));
+                    savedImages.push(join(outputDir, file));
+                    const { imageBase64: _bytes, ...details } = layer;
+                    return { ...details, file };
+                });
+                metadata = { source: input, engine, requestId: result.requestId, numLayers: result.numLayers,
+                    hasNsfwConcepts: result.hasNsfwConcepts, layers };
+            }
+            const elapsed = `${((Date.now() - startedAt) / 1000).toFixed(1)}s`;
+            writeFileSync(join(outputDir, 'decompose-layers-meta.json'), JSON.stringify({ ...metadata, elapsed }, null, 2));
+            for (const imagePath of savedImages)
+                await captureGeneratedArtifact(imagePath, 'decompose-layers');
+            console.log(t('saved', { outputDir }));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    image.command('analyze-nine-patch')
+        .description(t('ninePatch'))
+        .requiredOption('--input <path>', t('input'))
+        .option('--output <path>', t('output'))
+        .option('--vision-model <ref>', t('visionModel'))
+        .option('--team-id <id>', t('team'))
+        .action(async (opts) => {
+        try {
+            const input = await inputImage(opts.input);
+            const result = await new AgentApiClient().post('/image/analyze-nine-patch', {
+                imageBase64: input.imageBase64,
+                visionModelRef: opts.visionModel,
+                teamId: opts.teamId,
+            });
+            const json = JSON.stringify(result, null, 2);
+            if (opts.output) {
+                const output = resolveSandboxPath(opts.output);
+                mkdirSync(dirname(output), { recursive: true });
+                writeFileSync(output, json);
+            }
+            console.log(json);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

package/dist/commands/image.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 import yaml from 'js-yaml';
 import { AgentApiClient } from '../utils/agent-api-client.js';
+import { registerImageLayerTools } from './image-layer-tools.js';
 import { resolveSandboxPath } from '../utils/sandbox-path.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
 const DEFAULT_MAX_INPUT_BYTES = 512 * 1024 * 1024;
@@ -1853,79 +1854,7 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
-    // ─── decompose-layers ──────────────────────────────────────────────────────
-    img
-        .command('decompose-layers')
-        .description([
-        '302 Qwen-Image-Layered 整图语义分层：将合成图拆成 N 个 RGBA 图层',
-        '',
-        '  示例:',
-        '    playcraft image decompose-layers --input composite.png --output-dir ./layers',
-        '    playcraft image decompose-layers --input https://example.com/a.png --num-layers 4',
-        '',
-        '  需 Admin 配置 provider=302、modelKind=image 的 API Key；耗时约 1–2 分钟。',
-        '  本地文件需 storage 公网 URL，或 --input 使用 HTTPS 直链。',
-    ].join('\n'))
-        .requiredOption('--input <path>', '输入图片路径或 HTTPS URL')
-        .option('--output-dir <dir>', '输出目录', './decompose-layers-output')
-        .option('--num-layers <n>', '分层数量 2–10', cliParseInt, 4)
-        .option('--prompt <text>', '可选分层语义引导', '')
-        .option('--no-safety-checker', '关闭安全检测')
-        .option('--output-format <fmt>', '输出格式', 'png')
-        .action(async (opts) => {
-        try {
-            const payload = {
-                numLayers: opts.numLayers,
-                prompt: opts.prompt || '',
-                enableSafetyChecker: opts.safetyChecker !== false,
-                outputFormat: opts.outputFormat,
-            };
-            const input = opts.input;
-            const isUrl = input.startsWith('http://') || input.startsWith('https://');
-            if (isUrl) {
-                payload.imageUrl = input;
-                console.log(`Using image URL: ${input}`);
-            }
-            else {
-                const resolvedDecomposeInput = assertInputWithinLimit(input);
-                payload.imageBase64 = readFileSync(resolvedDecomposeInput).toString('base64');
-                console.log(`Uploading local image: ${input}`);
-            }
-            console.log(`Decomposing into ${payload.numLayers} layer(s) via 302 Qwen-Image-Layered (may take 1–2 min)…`);
-            const t0 = Date.now();
-            const client = new AgentApiClient();
-            const result = await client.post('/image-layered/decompose', payload);
-            const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
-            const outputDir = opts.outputDir;
-            mkdirSync(outputDir, { recursive: true });
-            for (const layer of result.layers) {
-                const ext = layer.mimeType.includes('png') ? 'png' : 'png';
-                const filename = `layer_${String(layer.index).padStart(2, '0')}.${ext}`;
-                writeFileSync(join(outputDir, filename), Buffer.from(layer.imageBase64, 'base64'));
-                const dim = layer.width && layer.height ? ` ${layer.width}×${layer.height}` : '';
-                console.log(`  ${filename}${dim}`);
-            }
-            const meta = {
-                source: input,
-                requestId: result.requestId,
-                numLayers: result.numLayers,
-                elapsed: `${elapsed}s`,
-                hasNsfwConcepts: result.hasNsfwConcepts,
-                layers: result.layers.map((l) => ({
-                    index: l.index,
-                    url: l.url,
-                    width: l.width,
-                    height: l.height,
-                    seed: l.seed,
-                })),
-            };
-            writeFileSync(join(outputDir, 'decompose-layers-meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
-            console.log(`\nDone in ${elapsed}s — ${result.layers.length} layer(s) → ${outputDir}/`);
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
+    registerImageLayerTools(img);
     // ─── segment ─────────────────────────────────────────────────────────────
     img
         .command('segment')

package/dist/commands/library-messages.js

@@ -0,0 +1,46 @@
+const messages = {
+    en: {
+        topic: 'Find and download authorized shared asset library content',
+        list: 'List library assets with filters and pagination', search: 'Search library names and content metadata',
+        get: 'Read asset metadata', files: 'List every file in an asset or bundle', facets: 'Inspect available categories and tags',
+        download: 'Download an asset or a complete bundle with relative dependencies',
+        query: 'Search text', id: 'Library asset identifier', type: 'Asset type', path: 'Library path prefix',
+        category: 'Category', subcategory: 'Subcategory', tags: 'Comma-separated tags',
+        visibility: 'public | team', team: 'Authorized team identifier', page: 'Page number, starting at 1',
+        limit: 'Results per page (1–100)', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
+        expand: 'Return individual files instead of collapsed bundles',
+        output: 'New file path, or a new directory for a bundle', outputDir: 'New directory for the downloaded content',
+        json: 'Print machine-readable JSON (JavaScript Object Notation, 数据交换格式; always enabled)',
+        invalidNumber: 'Expected a positive integer.', invalidId: 'Invalid library asset identifier.',
+        invalidManifest: 'The library returned an invalid or unsafe file manifest.',
+        outputRequired: 'Specify exactly one of --output or --output-dir.',
+        outputExists: 'The output already exists. Choose a new path to preserve existing files.',
+        failed: 'Asset library command failed.',
+    },
+    zh: {
+        topic: '检索和下载有权访问的共享素材库内容',
+        list: '按条件分页列出素材库内容', search: '检索素材名称和内容元数据',
+        get: '读取素材详情', files: '列出素材或素材包内的全部文件', facets: '查看可用分类与标签',
+        download: '下载素材或完整素材包，保留依赖文件的相对路径',
+        query: '检索文本', id: '素材库中的素材编号', type: '素材类型', path: '素材库路径前缀',
+        category: '分类', subcategory: '子分类', tags: '标签，逗号分隔',
+        visibility: 'public（公共）或 team（团队）', team: '有权访问的团队编号', page: '页码，从 1 开始',
+        limit: '每页数量（1–100）', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
+        expand: '返回单独文件，不折叠素材包', output: '新的文件路径；素材包则为新的目录', outputDir: '下载内容的新目录',
+        json: '输出机器可读的 JSON (JavaScript Object Notation, 数据交换格式)，始终启用',
+        invalidNumber: '请输入正整数。', invalidId: '素材库编号无效。',
+        invalidManifest: '素材库返回的文件清单无效或包含不安全路径。',
+        outputRequired: '请指定 --output 或 --output-dir，且只指定一项。',
+        outputExists: '输出路径已存在，请选择新路径以保留已有文件。', failed: '素材库命令执行失败。',
+    },
+};
+export function libraryMessage(key) {
+    return messages[(process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en'][key];
+}
+export class LibraryError extends Error {
+    code;
+    constructor(code) {
+        super(libraryMessage(code));
+        this.code = code;
+    }
+}

package/dist/commands/library.js

@@ -0,0 +1,130 @@
+import { InvalidArgumentError, Option } from 'commander';
+import { link, lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import { dirname, join, posix, resolve } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { libraryMessage as t, LibraryError } from './library-messages.js';
+function assetId(value) {
+    if (!/^(?:\d{1,20}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/i.test(value))
+        throw new InvalidArgumentError(t('invalidId'));
+    return value;
+}
+function positiveInteger(value) {
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new InvalidArgumentError(t('invalidNumber'));
+    return value;
+}
+function filters(command) {
+    return command.option('--search <text>', t('query')).option('--type <type>', t('type'))
+        .option('--path <path>', t('path')).option('--category <category>', t('category'))
+        .option('--subcategory <category>', t('subcategory')).option('--tags <tags>', t('tags'))
+        .addOption(new Option('--visibility <scope>', t('visibility')).choices(['public', 'team']))
+        .option('--team-id <id>', t('team')).option('--page <number>', t('page'), positiveInteger, '1')
+        .option('--limit <number>', t('limit'), value => {
+        positiveInteger(value);
+        if (Number(value) > 100)
+            throw new InvalidArgumentError(t('limit'));
+        return value;
+    }, '30')
+        .addOption(new Option('--sort-by <field>', t('sort')).choices(['modifiedAt', 'createdAt', 'name', 'referenceCount', 'size']))
+        .addOption(new Option('--sort-order <order>', t('order')).choices(['asc', 'desc']))
+        .option('--expand-prefabs', t('expand')).option('--json', t('json'));
+}
+function query(options) {
+    return Object.fromEntries(Object.entries(options)
+        .filter(([key, value]) => key !== 'json' && value !== undefined && value !== false)
+        .map(([key, value]) => [key, String(value)]));
+}
+async function action(run) {
+    try {
+        console.log(JSON.stringify({ ok: true, result: await run() }, null, 2));
+    }
+    catch (error) {
+        const code = error instanceof LibraryError ? error.code : 'failed';
+        console.error(`${t('failed')} ${error instanceof Error ? error.message : String(error)}`);
+        console.log(JSON.stringify({ ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } }));
+        process.exitCode = 1;
+    }
+}
+function validatedFiles(manifest) {
+    if (!manifest || !['file', 'bundle'].includes(manifest.kind) || !Array.isArray(manifest.files) ||
+        !manifest.files.length || (manifest.kind === 'file' && manifest.files.length !== 1))
+        throw new LibraryError('invalidManifest');
+    const seen = new Set();
+    for (const file of manifest.files) {
+        try {
+            assetId(file.id);
+        }
+        catch {
+            throw new LibraryError('invalidManifest');
+        }
+        const path = file.path;
+        if (typeof path !== 'string' || !path || path.startsWith('/') || /[\\:\x00-\x1f]/.test(path) ||
+            path.split('/').some(part => !part || part === '.' || part === '..') || posix.normalize(path) !== path)
+            throw new LibraryError('invalidManifest');
+        const key = path.toLowerCase();
+        if (seen.has(key))
+            throw new LibraryError('invalidManifest');
+        seen.add(key);
+    }
+    for (const key of seen) {
+        for (let parent = posix.dirname(key); parent !== '.'; parent = posix.dirname(parent)) {
+            if (seen.has(parent))
+                throw new LibraryError('invalidManifest');
+        }
+    }
+    return manifest.files;
+}
+export async function downloadLibraryAsset(client, id, options) {
+    if (Boolean(options.output) === Boolean(options.outputDir))
+        throw new LibraryError('outputRequired');
+    assetId(id);
+    const manifest = await client.get(`/asset-library/${encodeURIComponent(id)}/files`);
+    const files = validatedFiles(manifest);
+    const destination = resolve(resolveSandboxPath(options.output ?? options.outputDir));
+    const existing = await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (existing)
+        throw new LibraryError('outputExists');
+    await mkdir(dirname(destination), { recursive: true });
+    const staging = await mkdtemp(join(dirname(destination), '.playcraft-library-'));
+    const directory = manifest.kind === 'bundle' || Boolean(options.outputDir);
+    const downloaded = [];
+    try {
+        for (const file of files) {
+            const target = directory ? join(staging, file.path) : join(staging, 'content');
+            const { bytes } = await client.download(`/asset-library/${encodeURIComponent(file.id)}/file`, target);
+            downloaded.push({ id: file.id, path: directory ? join(destination, file.path) : destination, bytes });
+        }
+        // Recheck before publishing the complete bundle; failures never expose a partial download.
+        if (await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; }))
+            throw new LibraryError('outputExists');
+        if (directory)
+            await rename(staging, destination);
+        else
+            await link(join(staging, 'content'), destination);
+        return { assetId: manifest.assetId, kind: manifest.kind, output: destination, files: downloaded };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+export function registerLibraryCommands(program) {
+    const library = program.command('library').description(t('topic'));
+    filters(library.command('list').description(t('list')))
+        .action((options) => action(() => new AgentApiClient().get('/asset-library', query(options))));
+    filters(library.command('search').description(t('search')).argument('<query>', t('query')))
+        .action((search, options) => action(() => new AgentApiClient().get('/asset-library', query({ ...options, search }))));
+    library.command('facets').description(t('facets')).option('--path <path>', t('path'))
+        .addOption(new Option('--visibility <scope>', t('visibility')).choices(['public', 'team']))
+        .option('--team-id <id>', t('team')).option('--json', t('json'))
+        .action((options) => action(() => new AgentApiClient().get('/asset-library/facets', query(options))));
+    for (const command of ['get', 'files']) {
+        library.command(command).description(t(command)).argument('<assetId>', t('id'), assetId).option('--json', t('json'))
+            .action((id) => action(() => new AgentApiClient().get(`/asset-library/${encodeURIComponent(id)}${command === 'files' ? '/files' : ''}`)));
+    }
+    library.command('download').description(t('download')).argument('<assetId>', t('id'), assetId)
+        .option('--output <path>', t('output')).option('--output-dir <directory>', t('outputDir')).option('--json', t('json'))
+        .action((id, options) => action(() => downloadLibraryAsset(new AgentApiClient(), id, options)));
+}