@playcraft/cli 0.1.42 → 0.1.44-beta

package/dist/video-replication/evidence.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import sharp from 'sharp';
+import { videoUnderstandingAnalysisSchema, validateVideoUnderstandingContent, } from '@playcraft/common/agent-tools';
+import { openVideo, runMediaTool, verifyVideo } from './media.js';
+import { VideoCliError, videoMessage } from './messages.js';
+import { ensureVideoEvidenceGitExcluded } from '../utils/video-evidence-git.js';
+import { comparisonOutputPath, comparisonOutputRoot, writeComparisonArtifact, writeComparisonJson } from './comparison-output.js';
+import { ComparisonCliError } from './comparison-messages.js';
+async function videoOutput(action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (error instanceof ComparisonCliError && error.code === 'unsafeOutput')
+            throw new VideoCliError('unsafeOutput', 64);
+        throw error;
+    }
+}
+export async function writeJsonAtomic(path, value) {
+    await videoOutput(async () => {
+        await comparisonOutputRoot(dirname(path), true);
+        await writeComparisonJson(dirname(path), basename(path), value);
+    });
+}
+export async function prepareArtifactDirectory(out, runId, resume) {
+    if (!(await ensureVideoEvidenceGitExcluded(process.cwd())))
+        console.error(videoMessage('gitExcludeWarning'));
+    await videoOutput(async () => {
+        await comparisonOutputRoot(out, true);
+        await comparisonOutputPath(out, 'request.json');
+    });
+    const names = await readdir(out);
+    if (!names.length && !resume)
+        return;
+    try {
+        const saved = JSON.parse(await readFile(join(out, 'request.json'), 'utf8'));
+        if (resume && saved.schemaVersion === 'playcraft.video-request.v1' && saved.runId === runId && saved.out === resolve(out))
+            return;
+    }
+    catch { /* An unrelated or incomplete output directory must not be overwritten. */ }
+    throw new VideoCliError('outputConflict', 64);
+}
+export async function loadSavedRequest(out, runId, workspaceId) {
+    try {
+        await videoOutput(() => comparisonOutputPath(out, 'request.json'));
+        const value = JSON.parse(await readFile(join(out, 'request.json'), 'utf8'));
+        if (value.schemaVersion !== 'playcraft.video-request.v1' || value.runId !== runId || value.workspaceId !== workspaceId || value.out !== resolve(out) || typeof value.videoPath !== 'string')
+            throw new Error('invalid');
+        return value;
+    }
+    catch {
+        throw new VideoCliError('resumeMissing', 64);
+    }
+}
+const escapeXml = (text) => text.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
+const escapeMarkdown = (text) => text.replace(/([\\`*_[\]<>])/g, '\\$1');
+export function renderVideoAnalysis(analysis, frames) {
+    const lines = [`# ${videoMessage('summary')}`, '', escapeMarkdown(analysis.summary), '', videoMessage('transcriptNotice'), ''];
+    for (const [key, items] of [
+        ['observations', analysis.observations], ['inferences', analysis.inferences], ['unknowns', analysis.unknowns],
+    ]) {
+        lines.push(`## ${videoMessage(key)}`, '');
+        for (const item of items) {
+            const confidence = 'confidence' in item ? ` (${item.confidence})` : '';
+            lines.push(`- **${escapeMarkdown(item.id)}**${confidence}: ${escapeMarkdown(item.text)}`);
+        }
+        lines.push('');
+    }
+    lines.push(`## ${videoMessage('events')}`, '');
+    for (const event of analysis.events)
+        lines.push(`- ${escapeMarkdown(event.id)} [${event.startMs}–${event.endMs} ms]: ${event.kind}`);
+    lines.push('', `## ${videoMessage('hints')}`, '');
+    for (const [key, items] of Object.entries(analysis.reconstructionHints)) {
+        lines.push(`### ${videoMessage(key === 'candidateRules' ? 'rules' : key)}`, '');
+        for (const item of items)
+            lines.push(`- ${escapeMarkdown(item)}`);
+        lines.push('');
+    }
+    lines.push(`## ${videoMessage('evidence')}`, '');
+    for (const evidence of analysis.evidence)
+        lines.push(`- ${escapeMarkdown(evidence.id)} [${evidence.startMs}–${evidence.endMs} ms]: [frame](${frames.get(evidence.id)})`);
+    return `${lines.join('\n')}\n`;
+}
+/** Materialize only validated original-video timestamps; the model never supplies file paths. */
+export async function materializeVideoEvidence(input) {
+    let analysis;
+    try {
+        analysis = videoUnderstandingAnalysisSchema.parse(input.analysis);
+        validateVideoUnderstandingContent({
+            summary: analysis.summary, observations: analysis.observations, events: analysis.events,
+            evidence: analysis.evidence, inferences: analysis.inferences, unknowns: analysis.unknowns,
+            reconstructionHints: analysis.reconstructionHints,
+        }, analysis.source, input.request?.clip);
+    }
+    catch {
+        throw new VideoCliError('invalidResult');
+    }
+    // Refuse any redirected destination before replacing evidence from a previous attempt.
+    await videoOutput(async () => {
+        await comparisonOutputRoot(input.out, true);
+        for (const path of [...analysis.evidence.map(item => `keyframes/${item.id}.png`), 'analysis.json', 'analysis.md', 'manifest.json', 'contact-sheet.jpg'])
+            await comparisonOutputPath(input.out, path);
+    });
+    const file = await openVideo(input.sourcePath);
+    const frames = new Map();
+    const manifestFrames = [];
+    const tiles = [];
+    const width = 240;
+    const height = 200;
+    const columns = Math.min(4, analysis.evidence.length);
+    try {
+        await verifyVideo(file, analysis.source);
+        const frameOutput = await runMediaTool('ffprobe', [
+            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+            '-select_streams', 'v:0', '-show_entries', 'frame=best_effort_timestamp_time', '-of', 'csv=p=0', '/dev/fd/3',
+        ], file.fd, input.signal);
+        const rawFrameTimes = frameOutput.split('\n').map(line => Number.parseFloat(line) * 1000).filter(Number.isFinite);
+        const firstFrameTime = rawFrameTimes[0] ?? 0;
+        const frameTimes = rawFrameTimes.map(time => time - firstFrameTime).filter(time => time >= 0 && time < analysis.source.durationMs);
+        if (!frameTimes.length)
+            throw new VideoCliError('invalidResult');
+        for (const [index, evidence] of analysis.evidence.entries()) {
+            input.signal?.throwIfAborted();
+            const path = `keyframes/${evidence.id}.png`;
+            // Quantize the model's suggested midpoint to a real decoded frame, including the final frame.
+            const requestedTimeMs = (evidence.startMs + evidence.endMs) / 2;
+            const timeMs = frameTimes.reduce((best, candidate) => Math.abs(candidate - requestedTimeMs) < Math.abs(best - requestedTimeMs) ? candidate : best);
+            await videoOutput(() => writeComparisonArtifact(input.out, path, temporary => runMediaTool('ffmpeg', [
+                '-v', 'error', '-nostdin', '-y', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+                '-ss', (Math.max(0, timeMs - 0.01) / 1000).toFixed(6), '-i', '/dev/fd/3', '-map', '0:v:0',
+                '-frames:v', '1', '-vf', 'scale=min(1280\\,iw):-2', '-threads', '1', temporary,
+            ], file.fd, input.signal)));
+            const bytes = await readFile(join(input.out, path));
+            const metadata = await sharp(bytes).metadata();
+            if (!metadata.width || !metadata.height)
+                throw new VideoCliError('invalidResult');
+            frames.set(evidence.id, path);
+            manifestFrames.push({ evidenceId: evidence.id, timeMs, requestedTimeMs, path, sha256: createHash('sha256').update(bytes).digest('hex') });
+            const thumbnail = await sharp(bytes).resize(width, height - 30, { fit: 'contain', background: '#f4f4f4' }).png().toBuffer();
+            const label = Buffer.from(`<svg width="${width}" height="30"><rect width="100%" height="100%" fill="white"/><text x="8" y="20" font-size="12">${escapeXml(evidence.id)} ${(timeMs / 1000).toFixed(2)}s</text></svg>`);
+            const tile = await sharp({ create: { width, height, channels: 3, background: '#ffffff' } }).composite([{ input: thumbnail, top: 0, left: 0 }, { input: label, top: height - 30, left: 0 }]).png().toBuffer();
+            tiles.push({ input: tile, left: (index % columns) * width, top: Math.floor(index / columns) * height });
+        }
+        await verifyVideo(file, analysis.source);
+    }
+    finally {
+        await file.close();
+    }
+    const contactSheet = join(input.out, 'contact-sheet.jpg');
+    await videoOutput(() => writeComparisonArtifact(input.out, 'contact-sheet.jpg', temporary => sharp({ create: { width: columns * width, height: Math.ceil(tiles.length / columns) * height, channels: 3, background: '#dddddd' } }).composite(tiles).jpeg({ quality: 85 }).toFile(temporary)));
+    // Keep analysis.json compatible with the shared schema; local frame references live in the manifest.
+    const analysisPath = join(input.out, 'analysis.json');
+    const markdown = join(input.out, 'analysis.md');
+    await writeJsonAtomic(analysisPath, analysis);
+    await videoOutput(() => writeComparisonArtifact(input.out, 'analysis.md', temporary => writeFile(temporary, renderVideoAnalysis(analysis, frames), { mode: 0o600, flag: 'wx' })));
+    const manifest = join(input.out, 'manifest.json');
+    await writeJsonAtomic(manifest, {
+        schemaVersion: 'playcraft.video-evidence.v1', runId: analysis.runId, state: 'completed', source: analysis.source, model: analysis.model,
+        analysis: 'analysis.json', markdown: 'analysis.md', contactSheet: 'contact-sheet.jpg',
+        frames: manifestFrames, frameTimeSemantics: 'nearest-decoded-original-video-frame',
+    });
+    return { manifest, analysis: analysisPath, markdown, contactSheet, keyframes: manifestFrames.map(frame => join(input.out, frame.path)) };
+}

package/dist/video-replication/media.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { open, realpath } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { VIDEO_MAX_BYTES, videoSourceSchema, } from '@playcraft/common/agent-tools';
+import { VideoCliError, videoMessage } from './messages.js';
+/** No shell, external protocols, or unbounded child-process output. */
+export function runMediaTool(tool, args, inputFd, signal) {
+    return new Promise((resolve, reject) => {
+        const override = process.env[tool === 'ffmpeg' ? 'FFMPEG_PATH' : 'FFPROBE_PATH'];
+        if (override && !isAbsolute(override)) {
+            reject(new VideoCliError('mediaTool'));
+            return;
+        }
+        const child = spawn(override || tool, args, { stdio: ['ignore', 'pipe', 'pipe', inputFd], signal });
+        let output = '';
+        let diagnostic = '';
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(new VideoCliError('mediaTool', 4, { cause: new Error(`${tool}: ${videoMessage('mediaTimedOut')}`) }));
+        }, 30_000);
+        child.stdout.on('data', chunk => {
+            output += chunk.toString();
+            if (output.length > 1024 * 1024) {
+                child.kill('SIGKILL');
+                finish(new VideoCliError('videoFormat', 4, { cause: new Error(`${tool}: ${videoMessage('mediaOutputLimit')}`) }));
+            }
+        });
+        child.stderr.on('data', chunk => { diagnostic = (diagnostic + chunk.toString()).slice(0, 4096); });
+        child.once('error', error => finish(error.name === 'AbortError' ? error : new VideoCliError('mediaTool', 4, { cause: error })));
+        child.once('close', code => finish(code === 0 ? undefined : new VideoCliError('videoFormat', 4, { cause: new Error(`${tool}: ${videoMessage('mediaExit')} ${code}. ${diagnostic}`) })));
+    });
+}
+export async function openVideo(path) {
+    try {
+        const file = await open(path, 'r');
+        const stat = await file.stat();
+        if (!stat.isFile()) {
+            await file.close();
+            throw new VideoCliError('videoMissing', 64);
+        }
+        if (stat.size <= 0 || stat.size > VIDEO_MAX_BYTES) {
+            await file.close();
+            throw new VideoCliError('videoQuota', 64);
+        }
+        return file;
+    }
+    catch (error) {
+        if (error instanceof VideoCliError)
+            throw error;
+        throw new VideoCliError('videoMissing', 64, { cause: error });
+    }
+}
+async function digests(file) {
+    const sha = createHash('sha256');
+    const md5 = createHash('md5');
+    for await (const chunk of file.createReadStream({ autoClose: false, start: 0 })) {
+        sha.update(chunk);
+        md5.update(chunk);
+    }
+    return { sha256: sha.digest('hex'), contentMd5: md5.digest('base64') };
+}
+export async function probeVideo(path, signal) {
+    const absolute = await realpath(path).catch(error => { throw new VideoCliError('videoMissing', 64, { cause: error }); });
+    const file = await openVideo(absolute);
+    try {
+        const stat = await file.stat();
+        const magic = Buffer.alloc(16);
+        await file.read(magic, 0, magic.length, 0);
+        const isIso = magic.subarray(4, 8).toString('ascii') === 'ftyp';
+        const isWebm = magic.readUInt32BE(0) === 0x1a45dfa3;
+        if (!isIso && !isWebm)
+            throw new VideoCliError('videoFormat', 64);
+        const output = await runMediaTool('ffprobe', [
+            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+            '-show_entries', 'format=duration,format_name:stream=codec_type,width,height,duration',
+            '-of', 'json', '/dev/fd/3',
+        ], file.fd, signal);
+        const result = JSON.parse(output);
+        const video = result.streams?.find(stream => stream.codec_type === 'video');
+        if (!video)
+            throw new VideoCliError('videoFormat', 64);
+        const durationMs = Number(result.format?.duration ?? video.duration) * 1000;
+        const hashes = await digests(file);
+        const parsed = videoSourceSchema.safeParse({
+            sha256: hashes.sha256, sizeBytes: stat.size, durationMs, width: video.width, height: video.height,
+            mimeType: isWebm ? 'video/webm' : magic.subarray(8, 12).toString('ascii') === 'qt  ' ? 'video/quicktime' : 'video/mp4',
+        });
+        if (!parsed.success)
+            throw new VideoCliError('videoQuota', 64);
+        return { path: absolute, source: parsed.data, contentMd5: hashes.contentMd5 };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function verifyVideo(file, expected) {
+    const stat = await file.stat();
+    if (stat.size !== expected.sizeBytes || (await digests(file)).sha256 !== expected.sha256)
+        throw new VideoCliError('sourceChanged', 64);
+}

package/dist/video-replication/messages.js

@@ -0,0 +1,97 @@
+const messages = {
+    en: {
+        topic: 'Video understanding and replica comparison with evidence frames',
+        models: 'List authorized video models and supported processing modes',
+        understand: 'Understand a local reference video using a managed video model',
+        jobs: 'Inspect or cancel an existing analysis without submitting new inference',
+        get: 'Read an existing video task state', cancel: 'Explicitly request remote cancellation',
+        workspace: 'Workspace UUID (defaults to the nearest workspace context file)',
+        json: 'Print machine-readable JSON (always enabled)', video: 'Local MP4, MOV or WebM file',
+        question: 'Focused question about the video', context: 'Prior analysis.json for this video',
+        processing: 'auto | agentic | static', fps: 'Static sampling: 1 | 2 | 4 | 8',
+        clip: 'Static clip in original video seconds: start:end',
+        model: 'Authorized model configuration UUID', out: 'Artifact directory',
+        timeout: 'Maximum local wait in seconds; the remote task remains recoverable',
+        resume: 'Resume this existing run UUID; cannot be combined with new inputs',
+        invalidArguments: 'Invalid video command arguments.',
+        workspaceMissing: 'Specify --workspace or run inside a Cloud Workspace checkout.',
+        workspaceMismatch: 'The explicit workspace does not match the checkout context.',
+        videoMissing: 'The video must be a readable regular file.',
+        videoQuota: 'The video exceeds 100 MiB or 180 seconds, or has unsupported dimensions.',
+        videoFormat: 'The file is not a supported MP4, MOV or WebM video.',
+        mediaTool: 'FFmpeg and ffprobe are required. Check the managed runtime installation.',
+        outputConflict: 'The artifact directory belongs to another run. Choose an empty directory.',
+        unsafeOutput: 'The artifact directory contains a linked or unsupported output path.',
+        gitExcludeWarning: 'The local Git ignore rule could not be updated. Video analysis will continue; do not commit .playcraft/video-replication evidence to the repository.',
+        invalidContext: 'The context is invalid or belongs to a different video.',
+        invalidResult: 'The video service returned invalid or incomplete evidence.',
+        sourceChanged: 'The video changed since it was probed or the task was created.',
+        uploadFailed: 'Video upload could not be completed.',
+        modelUnavailable: 'No authorized model supports the requested video processing mode.',
+        resumeMissing: 'The saved request is missing or does not match this run and workspace.',
+        timeoutReached: 'Local waiting ended. Resume this run to check its existing result.',
+        interrupted: 'Interrupted. Remote cancellation was not requested or confirmed.',
+        uncertain: 'The remote outcome is unknown. Check this run; do not submit another analysis.',
+        remoteFailed: 'The remote analysis failed or was cancelled.',
+        failed: 'Video understanding failed. Inspect the saved request and task before retrying.',
+        probing: 'Inspecting the video', uploading: 'Uploading the video',
+        preparing: 'Preparing the video command', loadingModels: 'Loading authorized video models',
+        initializingUpload: 'Initializing the video upload', finalizingUpload: 'Validating the uploaded video',
+        failureStage: 'Stage', failureReason: 'Reason', mediaExit: 'Media tool exit status',
+        mediaTimedOut: 'Media tool timed out', mediaOutputLimit: 'Media tool output exceeded the limit',
+        submitting: 'Submitting the analysis', waiting: 'Waiting for the existing analysis',
+        extracting: 'Extracting evidence frames',
+        summary: 'Summary', observations: 'Observed facts', events: 'Events',
+        inferences: 'Inferences', unknowns: 'Unknowns', hints: 'Reconstruction suggestions',
+        evidence: 'Evidence', entities: 'Entities', assets: 'Assets', rules: 'Candidate rules',
+        transcriptNotice: 'Observed events cover only the demonstrated video. Inferred controls and hidden rules remain uncertain.',
+    },
+    zh: {
+        topic: '视频理解与复刻比较，抽取证据关键帧',
+        models: '列出有权使用的视频模型和处理模式',
+        understand: '使用受管视频模型理解本地参考视频',
+        jobs: '核对或取消已有任务，不新建推理', get: '读取已有视频任务状态', cancel: '明确请求远端取消',
+        workspace: '工作区编号，默认读取最近的工作区上下文文件',
+        json: '输出机器可读的 JSON（始终启用）', video: '本地 MP4、MOV 或 WebM 文件',
+        question: '需要确认的视频问题', context: '同一视频的已有 analysis.json',
+        processing: 'auto | agentic | static', fps: '静态抽样：1 | 2 | 4 | 8',
+        clip: '原视频上的静态片段秒数：开始:结束', model: '有权使用的模型配置编号', out: '制品输出目录',
+        timeout: '本地等待的最长秒数，远端任务仍可恢复', resume: '恢复已有任务编号，不能与新输入组合使用',
+        invalidArguments: '视频命令参数无效。', workspaceMissing: '请指定 --workspace，或在云端工作区目录内运行。',
+        workspaceMismatch: '指定的工作区与当前目录的工作区上下文不一致。',
+        videoMissing: '视频必须是可读的普通文件。', videoQuota: '视频超出 100 MiB、180 秒或支持的画面尺寸。',
+        videoFormat: '文件不是支持的 MP4、MOV 或 WebM 视频。', mediaTool: '需要 FFmpeg 和 ffprobe，请检查受管运行环境安装。',
+        outputConflict: '输出目录属于另一轮任务，请使用空目录。', invalidContext: '上下文无效，或属于另一份视频。',
+        unsafeOutput: '制品目录包含符号链接或不支持的输出路径。',
+        gitExcludeWarning: '无法更新 Git 本地忽略规则。视频分析将继续，请勿将 .playcraft/video-replication 证据提交到仓库。',
+        invalidResult: '视频服务返回的证据无效或不完整。', sourceChanged: '视频在探测后或任务创建后发生了变化。',
+        uploadFailed: '视频上传未完成。', modelUnavailable: '没有有权使用且支持所需视频模式的模型。',
+        resumeMissing: '找不到保存的请求，或请求与任务、工作区不一致。',
+        timeoutReached: '本地等待结束，请恢复此任务核对已有结果。',
+        interrupted: '操作已中断，尚未请求或确认远端取消。',
+        uncertain: '远端结果未知，请核对此任务，不要另建分析。', remoteFailed: '远端分析失败或已取消。',
+        failed: '视频理解失败，请先核对已保存的请求和任务再重试。',
+        probing: '正在探测视频', uploading: '正在上传视频', submitting: '正在提交分析',
+        preparing: '正在准备视频命令', loadingModels: '正在加载有权使用的视频模型',
+        initializingUpload: '正在初始化视频上传', finalizingUpload: '正在校验已上传的视频',
+        failureStage: '失败阶段', failureReason: '具体原因', mediaExit: '媒体工具退出状态',
+        mediaTimedOut: '媒体工具执行超时', mediaOutputLimit: '媒体工具输出超出限制',
+        waiting: '正在等待已有分析', extracting: '正在抽取证据关键帧',
+        summary: '概述', observations: '观察事实', events: '事件', inferences: '推断', unknowns: '未知项',
+        hints: '复刻建议', evidence: '证据', entities: '实体', assets: '素材', rules: '候选规则',
+        transcriptNotice: '观察事件仅覆盖视频展示的路径；操作方式和隐藏规则的推断仍需确认。',
+    },
+};
+export function videoMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}
+export class VideoCliError extends Error {
+    code;
+    exitCode;
+    constructor(code, exitCode = 4, options) {
+        super(videoMessage(code), options);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}

package/dist/workspace/messages.js

@@ -0,0 +1,67 @@
+const messages = {
+    en: {
+        description: 'Download cloud workspaces and push local commits back',
+        clone: 'Clone the current workspace files, including uncommitted changes',
+        push: 'Push local commits back; reject concurrent cloud changes',
+        workspaceId: 'Cloud workspace identifier', directory: 'Engineering directory, or root for the whole workspace',
+        target: 'Local checkout directory', url: 'PlayCraft service base address, including any environment prefix',
+        token: 'Personal access token', json: 'Print structured output',
+        invalidTarget: 'Invalid workspace identifier, directory, or service address.',
+        directoryExists: 'The target directory already exists. Choose an empty new directory.',
+        metadataMissing: 'No workspace checkout metadata found. Run workspace clone first.',
+        cleanRequired: 'Commit or discard local changes before running workspace push.',
+        notReady: 'Workspace access is not ready. Open the workspace and retry.',
+        conflict: 'Cloud files changed since this checkout. Clone again and merge your changes before pushing.',
+        failed: 'Workspace transfer failed', cloned: 'Workspace cloned:', pushed: 'Local commits pushed to the cloud workspace.',
+        tooLarge: 'The service rejected this transfer because of its size. Check the workspace quota and the service upload configuration; direct download cannot upload your changes.',
+        byteCount: '{value} bytes',
+        quotaExceeded: 'Push would use {actual}, exceeding the workspace quota of {limit}. Reduce the committed files or ask an administrator to increase the quota. Cloud files were not changed.',
+        diskFull: 'Insufficient disk space for transfer staging or file replacement. Required: {actual}; available after reserved space: {limit}. Free disk space and retry.',
+        diskFullUnknown: 'The disk filled while preparing or applying the transfer. Free disk space on the local computer or sandbox and retry. Your local commits are preserved.',
+        diskUnavailable: 'Could not check available workspace storage. Retry or ask an administrator to check the sandbox disk.',
+        proxyTooLarge: 'The upload gateway rejected the transfer (413). Ask an administrator to increase the gateway upload limit; direct download cannot upload your changes.',
+        timeout: 'Workspace transfer timed out. Your local commits are preserved. Retry the push to confirm its result; ask an administrator to check service timeouts if it repeats.',
+        network: 'Could not reach the workspace service. Check the service address and your connection, then retry. Your local commits are preserved.',
+        busy: 'The workspace has an active task, terminal, or file write. Wait for it to finish, then retry the push.',
+        gitMissing: 'Git is not installed or is unavailable on the command path. Install Git and retry.',
+        gitFailed: 'Git could not prepare or apply the workspace transfer. Check local repository integrity and available disk space; retry or contact an administrator.',
+        baseMissing: 'The original workspace snapshot is missing from this local repository. Clone the workspace again and merge your local files before pushing.',
+        invalidTransfer: 'The workspace contains an unsupported path, symbolic link, or invalid transfer data. Check the committed files before retrying.',
+        upgradeRequired: 'This server does not support incremental workspace transfer. Upgrade the server before pushing with this command.',
+        preflight: 'Push preflight passed: {files} files, {bytes} of content. Preparing incremental transfer.',
+        upload: 'Uploading incremental transfer: {bytes}.',
+        login: 'Log in to the target environment using playcraft login --url',
+    },
+    zh: {
+        description: '下载云工作区，并将本地提交推送回来', clone: '克隆当前工作区文件，包含尚未提交的修改',
+        push: '把本地提交推送回来；云端有新修改时拒绝覆盖', workspaceId: '云工作区标识',
+        directory: '工程目录；root 表示整个工作区', target: '本地克隆目录',
+        url: 'PlayCraft 服务基址，保留环境路径前缀', token: '个人访问令牌', json: '输出结构化结果',
+        invalidTarget: '工作区标识、目录或服务地址无效。', directoryExists: '目标目录已存在，请选择新的目录。',
+        metadataMissing: '未找到工作区克隆信息，请先运行 workspace clone。', cleanRequired: '请先提交或丢弃本地修改，再运行 workspace push。',
+        notReady: '工作区访问尚未就绪，请打开工作区后重试。', conflict: '云端文件在克隆后发生变化，请重新克隆并合并本地修改后再推送。',
+        failed: '工作区传输失败', cloned: '工作区已克隆到：', pushed: '本地提交已推送回云工作区。',
+        tooLarge: '服务端因大小拒绝了本次传输。请检查工作区配额及服务上传配置；直接下载无法把本地修改推回云端。',
+        byteCount: '{value} 字节',
+        quotaExceeded: '推送后工作区将占用 {actual}，超过配额 {limit}。请减少已提交的文件，或联系管理员提高配额。云端文件未被修改。',
+        diskFull: '暂存传输包或替换文件所需的磁盘空间不足。需要 {actual}；保留余量后可用 {limit}。请释放磁盘空间后重试。',
+        diskFullUnknown: '准备或应用传输时磁盘已满。请释放本机或沙箱磁盘空间后重试，本地提交已保留。',
+        diskUnavailable: '无法检查工作区存储空间。请重试，或联系管理员检查沙箱磁盘。',
+        proxyTooLarge: '上传网关拒绝了本次传输（413）。请联系管理员提高网关上传上限；直接下载无法把本地修改推回云端。',
+        timeout: '工作区传输超时。本地提交已保留，可重试推送以确认结果；若持续发生，请联系管理员检查服务超时配置。',
+        network: '无法连接工作区服务。请检查服务地址和网络后重试，本地提交已保留。',
+        busy: '工作区有正在执行的任务、终端或文件写入。请等待结束后重试推送。',
+        gitMissing: '未安装 Git 或命令路径中无法找到 Git。请安装后重试。',
+        gitFailed: 'Git 无法准备或应用工作区传输。请检查本地仓库完整性及磁盘空间，重试或联系管理员。',
+        baseMissing: '本地仓库缺少最初的工作区快照。请重新克隆工作区，并合并本地文件后再推送。',
+        invalidTransfer: '工作区包含不支持的路径、符号链接或无效传输数据。请检查已提交文件后重试。',
+        upgradeRequired: '当前服务端尚不支持工作区增量传输。请升级服务端后再使用此命令推送。',
+        preflight: '推送预检查通过：{files} 个文件，内容共 {bytes}。正在准备增量传输。',
+        upload: '正在上传增量传输包：{bytes}。',
+        login: '请使用 playcraft login --url 登录目标环境',
+    },
+};
+export function workspaceMessage(key, values = {}) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key].replace(/\{(\w+)\}/g, (placeholder, name) => String(values[name] ?? placeholder));
+}