@playcraft/cli 0.1.66 → 0.1.67

package/dist/assets/client.js

@@ -55,11 +55,11 @@ export function scopedAssetTask(scope, value) {
     return task;
 }
 export async function readAssetTasks(client, scope) {
-    const value = assetGenerationTaskListSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'list' }));
+    const value = assetGenerationTaskListSchema.parse(await client.get('/workspace-assets', { ...scope, audioProtocolVersion: '1', audioScoreProtocolVersion: '1', action: 'list' }));
     return { tasks: value.tasks.map(task => scopedAssetTask(scope, task)) };
 }
 export async function readAssetTask(client, scope, taskId) {
-    const task = scopedAssetTask(scope, await client.get('/workspace-assets', { ...scope, action: 'get', taskId }));
+    const task = scopedAssetTask(scope, await client.get('/workspace-assets', { ...scope, audioProtocolVersion: '1', audioScoreProtocolVersion: '1', action: 'get', taskId }));
     if (task.taskId !== taskId)
         throw new Error(t('scopeMismatch'));
     return task;
@@ -99,6 +99,8 @@ async function verifyFile(path, file) {
 /** Stage and verify every member before publishing the new local output. */
 export async function downloadAssetTask(client, scope, taskId, output, versionId) {
     const task = await readAssetTask(client, scope, taskId);
+    if (task.audioResult)
+        throw new Error(t('audioSourceRequired'));
     if (!['awaiting_adoption', 'saved'].includes(task.status) || !task.output)
         throw new Error(t('outputUnavailable'));
     let bundle = task.bundle, entry = task.output;

package/dist/assets/messages.js

@@ -22,6 +22,7 @@ const messages = {
         invalidContent: 'Downloaded content does not match the task size or content digest.', failed: 'Asset operation failed',
         timeoutReached: 'Waiting timed out. Use assets get or assets wait with the same task identifier; generation was not cancelled.',
         requestTooLarge: 'The request document exceeds the permitted size.',
+        audioSourceRequired: 'This task contains editable sound candidates. Use playcraft audio source inspect/render/adopt with its task and candidate identifiers.',
     },
     zh: {
         topic: '生成工作区素材，管理工作区面板中同一批任务', estimate: '估算生成费用，不创建任务', generate: '创建可恢复的素材生成任务',
@@ -40,6 +41,7 @@ const messages = {
         invalidContent: '下载内容与任务记录的大小或内容摘要不一致。', failed: '素材操作失败',
         timeoutReached: '等待已超时。请使用同一任务标识运行 assets get 或 assets wait，生成任务未取消。',
         requestTooLarge: '请求文档超过允许大小。',
+        audioSourceRequired: '此任务包含可编辑声音候选。请使用 playcraft audio source inspect/render/adopt，并传入任务和候选标识。',
     },
 };
 export function assetMessage(key) {

package/dist/audio-source/messages.js

@@ -0,0 +1,35 @@
+const copy = {
+    en: { audioTopic: 'Process audio files and manage workspace sound and music assets', topic: 'Create and revise workspace sound effects and music', capabilities: 'Inspect available sound features',
+        inspect: 'Read the exact source, audition status and history', create: 'Generate short sound candidates in the workspace asset tasks',
+        edit: 'Save a source revision or a shape preserving simple adjustment', render: 'Render an exact source revision',
+        adopt: 'Save a private candidate and its complete representation bundle', rollback: 'Restore an earlier source revision',
+        bind: 'Record a version bound event handoff for game integration', scope: 'Workspace identifier; inferred from the project',
+        directory: 'Engineering directory; inferred from the project', path: 'Workspace source path ending in .pcaudio.json or .pcscore.json',
+        task: 'Existing generation task identifier', candidate: 'Candidate identifier', revision: 'Expected current source revision',
+        hash: 'Expected current source content digest', document: 'Validated sound source document', request: 'Generation request document',
+        requestId: 'Stable operation identity; reuse after an uncertain response', output: 'Destination workspace source path',
+        destinationRevision: 'Expected destination revision, or 0 when absent', destinationHash: 'Expected destination digest when replacing a source',
+        version: 'Historical source revision to restore', event: 'Explicit game event name; actual code integration is a separate verified step',
+        macro: 'Simple adjustment: volume, pitch, duration, brightness; music also supports tempo', value: 'Adjustment value: gain, semitones, seconds, cutoff multiplier or beats per minute',
+        lockedTracks: 'Comma separated locked music track identifiers', preserveMelody: 'Preserve pitched note identities, timing and melody',
+        selection: 'Frozen music selection document with trackIds, noteIds and rangeBeats', adjustment: 'Structured music adjustment document',
+        voices: 'Comma separated selected voice identifiers', invalid: 'Invalid sound command arguments.', failed: 'Sound operation failed',
+        locked: 'Comma separated locked voice identifiers from the selected context', preserve: 'Comma separated protected parameter targets from the selected context',
+    },
+    zh: { audioTopic: '处理音频文件，生成和续改工作区音效与音乐', topic: '生成和续改工作区音效与音乐', capabilities: '查看声音能力', inspect: '读取精确源、试听状态和历史',
+        create: '在工作区素材任务中生成短音效候选', edit: '保存源修订或保留曲线形状的简单调整', render: '渲染精确源版本',
+        adopt: '保存私有候选及完整表示包', rollback: '恢复历史源版本', bind: '记录固定声音版本的游戏事件交接',
+        scope: '工作区标识；从工程推断', directory: '工程目录；从工程推断', path: '以 .pcaudio.json 或 .pcscore.json 结尾的工程源路径',
+        task: '已有生成任务标识', candidate: '候选标识', revision: '预期当前源修订号', hash: '预期当前源内容摘要',
+        document: '声音源文档路径', request: '生成请求文档路径', requestId: '稳定操作标识；响应不确定时复用',
+        output: '目标工程源路径', destinationRevision: '预期目标修订；目标不存在时为 0', destinationHash: '替换目标时预期的内容摘要',
+        version: '要恢复的历史源修订', event: '明确的游戏事件名称；代码接入需要另外验证', macro: '简单调整：volume、pitch、duration、brightness；音乐另支持 tempo',
+        lockedTracks: '用逗号分隔的锁定音乐轨道标识', preserveMelody: '保留旋律音符身份、拍点与音高',
+        selection: '含轨道、音符与节拍范围的冻结选区文档', adjustment: '结构化音乐调整文档路径',
+        value: '调整值：音量、半音、秒或滤波倍数', voices: '用逗号分隔的选中声部标识', invalid: '声音命令参数无效。', failed: '声音操作失败',
+        locked: '用逗号分隔的锁定声部；来自所选上下文', preserve: '用逗号分隔的保护参数路径；来自所选上下文',
+    },
+};
+export function audioSourceMessage(key) {
+    return copy[(process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/commands/assets.js

@@ -37,7 +37,7 @@ async function run(command, options, action) {
     }
 }
 function write(client, body) {
-    return client.post(body.action === 'animation-draft' ? '/workspace-assets/animation-draft' : '/workspace-assets', workspaceAssetToolWriteSchema.parse(body));
+    return client.post(body.action === 'animation-draft' ? '/workspace-assets/animation-draft' : '/workspace-assets', workspaceAssetToolWriteSchema.parse({ ...body, audioProtocolVersion: 1, audioScoreProtocolVersion: 1 }));
 }
 export function registerWorkspaceAssetCommands(program) {
     const assets = program.command('assets').description(t('topic'));

package/dist/commands/audio-source.js

@@ -0,0 +1,109 @@
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { applyAudioAdjustment, applyScoreAdjustment, parseSoundDocument, workspaceAudioProtectionSchema, scoreProtectionSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveAssetScope, readAssetRequest } from '../assets/client.js';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { audioSourceMessage as t } from '../audio-source/messages.js';
+function target(options) {
+    if (options.path && !options.task && !options.candidate)
+        return { kind: 'workspace-file', path: options.path };
+    if (options.task && options.candidate && !options.path)
+        return { kind: 'generation-candidate', taskId: options.task, candidateId: options.candidate };
+    throw new Error(t('invalid'));
+}
+function expected(options) {
+    const revision = Number(options.revision);
+    if (!Number.isSafeInteger(revision) || revision < 1 || !/^[a-f0-9]{64}$/.test(options.hash ?? ''))
+        throw new Error(t('invalid'));
+    return { expectedRevision: revision, expectedContentHash: options.hash };
+}
+function scoped(command) { return command.option('--workspace <id>', t('scope')).option('--directory <name>', t('directory')); }
+function selected(command) { return scoped(command).option('--path <path>', t('path')).option('--task <id>', t('task')).option('--candidate <id>', t('candidate')); }
+function writable(command) {
+    return selected(command).requiredOption('--revision <number>', t('revision')).requiredOption('--hash <digest>', t('hash'))
+        .requiredOption('--request-id <id>', t('requestId')).option('--locked-voices <ids>', t('locked')).option('--preserve-targets <targets>', t('preserve'))
+        .option('--locked-tracks <ids>', t('lockedTracks')).option('--preserve-melody', t('preserveMelody')).option('--selection <file>', t('selection'));
+}
+async function protection(options, score = false) {
+    const list = (value) => value?.split(',').map(item => item.trim()).filter(Boolean) ?? [];
+    if (score || options.lockedTracks !== undefined || options.preserveMelody !== undefined || options.selection) {
+        if (options.lockedVoices !== undefined || options.preserveTargets !== undefined)
+            throw new Error(t('invalid'));
+        return scoreProtectionSchema.parse({ lockedTrackIds: list(options.lockedTracks), preserveMelody: options.preserveMelody ?? false,
+            ...(options.selection ? { selection: await readAssetRequest(options.selection) } : {}) });
+    }
+    return workspaceAudioProtectionSchema.parse({ lockedVoiceIds: list(options.lockedVoices), preserveTargets: list(options.preserveTargets) });
+}
+function output(action) {
+    return async (options) => {
+        try {
+            console.log(JSON.stringify(await action(options), null, 2));
+        }
+        catch (error) {
+            console.error(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    };
+}
+async function action(options, request) {
+    return new AgentApiClient().post('/workspace-audio', { ...await resolveAssetScope(options), audioScoreProtocolVersion: 1, request });
+}
+export function registerAudioSourceCommands(audio) {
+    const source = audio.command('source').description(t('topic'));
+    scoped(source.command('capabilities').description(t('capabilities'))).action(output(async (options) => new AgentApiClient().get('/workspace-audio', { ...await resolveAssetScope(options), audioScoreProtocolVersion: '1', action: 'capabilities' }, { signal: AbortSignal.timeout(165_000) })));
+    selected(source.command('inspect').description(t('inspect'))).action(output(async (options) => {
+        const value = target(options);
+        return new AgentApiClient().get('/workspace-audio', { ...await resolveAssetScope(options), audioScoreProtocolVersion: '1', action: 'read',
+            ...(value.kind === 'workspace-file' ? { path: value.path } : { taskId: value.taskId, candidateId: value.candidateId }) });
+    }));
+    scoped(source.command('create').description(t('create'))).requiredOption('--request <file>', t('request'))
+        .requiredOption('--request-id <id>', t('requestId'))
+        .action(output(async (options) => {
+        const request = await readAssetRequest(options.request);
+        if (!request || typeof request !== 'object' || Array.isArray(request))
+            throw new Error(t('invalid'));
+        return new AgentApiClient().post('/workspace-assets', { ...await resolveAssetScope(options), audioProtocolVersion: 1, audioScoreProtocolVersion: 1,
+            action: 'create', clientRequestId: options.requestId,
+            request: { ...request, kind: 'audio', representation: ('representation' in request ? request.representation : undefined) ?? 'synth-sfx' } });
+    }));
+    for (const name of ['edit', 'save'])
+        writable(source.command(name).description(t('edit')))
+            .option('--document <file>', t('document')).option('--macro <kind>', t('macro')).option('--value <number>', t('value')).option('--voices <ids>', t('voices'))
+            .option('--adjustment <file>', t('adjustment'))
+            .action(output(async (options) => {
+            let document;
+            if (options.document && !options.macro && !options.adjustment)
+                document = parseSoundDocument(await readFile(resolveSandboxPath(options.document)));
+            else if (!options.document && (!!options.macro !== !!options.adjustment)) {
+                const value = target(options), state = await new AgentApiClient().get('/workspace-audio', { ...await resolveAssetScope(options), audioScoreProtocolVersion: '1', action: 'read', ...(value.kind === 'workspace-file' ? { path: value.path } : { taskId: value.taskId, candidateId: value.candidateId }) });
+                if (state.revision !== expected(options).expectedRevision || state.contentHash !== options.hash)
+                    throw new Error('audio_revision_conflict');
+                const policy = await protection(options, state.document.format === 'playcraft.score');
+                if (state.document.format === 'playcraft.score') {
+                    const adjustment = options.adjustment ? await readAssetRequest(options.adjustment) : { kind: options.macro, value: Number(options.value) };
+                    document = applyScoreAdjustment(state.document, adjustment, scoreProtectionSchema.parse(policy));
+                }
+                else {
+                    if (options.adjustment || !['volume', 'pitch', 'duration', 'brightness'].includes(options.macro))
+                        throw new Error(t('invalid'));
+                    document = applyAudioAdjustment(state.document, { kind: options.macro, value: Number(options.value),
+                        ...(options.voices ? { voiceIds: options.voices.split(',') } : {}) }, policy);
+                }
+            }
+            else
+                throw new Error(t('invalid'));
+            return action(options, { action: 'save', requestId: options.requestId ?? randomUUID(), target: target(options), ...expected(options), document,
+                protection: await protection(options, document.format === 'playcraft.score') });
+        }));
+    writable(source.command('render').description(t('render'))).action(output(options => action(options, { action: 'render', requestId: options.requestId ?? randomUUID(), target: target(options), ...expected(options) })));
+    writable(source.command('adopt').description(t('adopt'))).requiredOption('--output <path>', t('output'))
+        .option('--destination-revision <number>', t('destinationRevision'), '0').option('--destination-hash <digest>', t('destinationHash'))
+        .action(output(options => action(options, { action: 'adopt', requestId: options.requestId ?? randomUUID(), target: target(options), ...expected(options),
+        path: options.output, expectedDestinationRevision: Number(options.destinationRevision), expectedDestinationContentHash: options.destinationHash ?? null })));
+    writable(source.command('rollback').description(t('rollback'))).requiredOption('--version <number>', t('version'))
+        .action(output(options => action(options, { action: 'rollback', requestId: options.requestId ?? randomUUID(), target: target(options), ...expected(options), versionRevision: Number(options.version) })));
+    for (const name of ['bind', 'integrate'])
+        writable(source.command(name).description(t('bind'))).requiredOption('--event <name>', t('event'))
+            .action(output(options => action(options, { action: 'bind', requestId: options.requestId ?? randomUUID(), target: target(options), ...expected(options), eventName: options.event })));
+}

package/dist/commands/audio.js

@@ -1,4 +1,6 @@
 import { getAudioInfo, compressAudio, trimAudio, convertAudio, fadeAudio, concatAudio, normalizeAudio, loopAudio, mixAudio, } from '../utils/audio-processor.js';
+import { registerAudioSourceCommands } from './audio-source.js';
+import { audioSourceMessage } from '../audio-source/messages.js';
 /**
  * Parse and validate `audio mix --volumes` / `--offsets` against `--inputs`.
  */
@@ -45,7 +47,8 @@ function buildValidatedMixTracks(inputs, volumeStrs, offsetStrs) {
 export function registerAudioCommands(program) {
     const audio = program
         .command('audio')
-        .description('素材工具：本地音频处理（ffmpeg，不调用 API）');
+        .description(audioSourceMessage('audioTopic'));
+    registerAudioSourceCommands(audio);
     // ── audio-info ──────────────────────────────────────────────────────────
     audio
         .command('info')
@@ -67,15 +70,19 @@ export function registerAudioCommands(program) {
         .description('压缩音频文件（降低比特率/采样率，转单声道，或指定目标体积）')
         .requiredOption('--input <file>', '输入音频文件路径')
         .requiredOption('--output <file>', '输出音频文件路径')
-        .option('--bitrate <kbps>', '目标比特率（kbps），如 64', parseInt)
-        .option('--sample-rate <hz>', '目标采样率（Hz），如 22050', parseInt)
+        .option('--format <format>', '输出格式：mp3、ogg、opus、wav（默认由扩展名确定）')
+        .option('--bitrate <kbps>', '目标比特率（kbps），如 64', Number)
+        .option('--sample-rate <hz>', '目标采样率（Hz），如 22050', Number)
+        .option('--channels <count>', '输出声道数：1 或 2', Number)
         .option('--mono', '转为单声道', false)
-        .option('--target-size <size>', '目标体积（自动计算比特率），如 30KB、1.5MB')
+        .option('--target-size <size>', '输出体积上限（不能满足时失败），如 30KB、1.5MB')
         .action(async (opts) => {
         try {
             await compressAudio(opts.input, opts.output, {
+                format: opts.format,
                 bitrate: opts.bitrate,
                 sampleRate: opts.sampleRate,
+                channels: opts.channels,
                 mono: opts.mono,
                 targetSize: opts.targetSize,
             });

package/dist/commands/build.js

@@ -9,6 +9,7 @@ import inquirer from 'inquirer';
 import { tmpdir } from 'node:os';
 import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
 import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/build-isolation.js';
+import { markAudioBuildInputs, verifyAudioBuildInputs } from '../workspace-runtime/workspaces/audio-assets/build-inputs.js';
 import { finalizeWorkspacePlayable, readWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
@@ -302,13 +303,14 @@ export async function buildCommand(projectPath, options) {
         try {
             const signature = canonicalOutput ? await workspacePlayableSignature(workspace.root) : undefined;
             const project = path.join(scratch, 'project'), output = path.join(scratch, 'output');
-            await isolateWorkspaceForBuild(workspace.root, project);
+            const audioInputs = await isolateWorkspaceForBuild(workspace.root, project);
             await buildCommand(project, { ...options, workspaceArtifact: false, output });
+            await verifyAudioBuildInputs(workspace.root, audioInputs);
             if (canonicalOutput) {
                 const entries = await fs.readdir(output, { withFileTypes: true });
                 if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
                     throw new Error('preview_not_single_file');
-                await finalizeWorkspacePlayable(workspace.root, await fs.readFile(path.join(output, entries[0].name)), 'playcraft build', { expectedSignature: signature });
+                await finalizeWorkspacePlayable(workspace.root, markAudioBuildInputs(await fs.readFile(path.join(output, entries[0].name)), audioInputs), 'playcraft build', { expectedSignature: signature });
                 console.log(path.join(workspace.root, WORKSPACE_PLAYABLE_OUTPUT_PATH));
                 try {
                     const { bytes } = await readWorkspacePlayable(workspace.root);

package/dist/commands/tools-context.js

@@ -0,0 +1,46 @@
+import { basename, dirname } from 'node:path';
+import { workspaceDirectoryRegistrationSchema, workspaceExecutionContextQuerySchema } from '@playcraft/common/cloud-workspace/runtime';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
+import { handleError } from './tools-utils.js';
+import { readExecutionContextFromBridge } from '../utils/execution-context-bridge.js';
+const messages = {
+    en: { description: 'Read selected current execution context from the platform',
+        fields: 'Comma-separated fields to read: user,team,workspace,clock',
+        revision: 'Previous revision of the same fields, only when their values remain visible',
+        scope: 'Run this command from the current cloud workspace basic or Remix engineering directory.' },
+    zh: { description: '按需读取平台解析的当前执行上下文',
+        fields: '需要读取的字段，以逗号分隔：user,team,workspace,clock',
+        revision: '相同字段的已有修订号，仅在对应结果仍可见时使用',
+        scope: '请在当前云工作区的 basic 或 Remix 工程目录执行此命令。' },
+};
+const language = () => /^zh/i.test(process.env.PLAYCRAFT_LANG ?? process.env.LANG ?? '') ? messages.zh : messages.en;
+const scopeSchema = workspaceDirectoryRegistrationSchema.pick({ workspaceId: true, directoryName: true });
+export async function readExecutionContext(request, client, cwd = process.cwd()) {
+    const query = workspaceExecutionContextQuerySchema.parse(request);
+    const mediated = await readExecutionContextFromBridge(query);
+    if (mediated)
+        return mediated;
+    const context = await generatedWorkspace(cwd);
+    const scope = scopeSchema.safeParse(context ? { workspaceId: context.workspaceId, directoryName: basename(context.root) } : undefined);
+    if (!context || !scope.success || basename(dirname(context.root)) !== context.workspaceId)
+        throw new Error(language().scope);
+    return (client ?? new AgentApiClient()).readWorkspaceExecutionContext(scope.data, query);
+}
+export function registerContextCommands(tools) {
+    const t = language();
+    tools.command('get-context').description(t.description)
+        .requiredOption('--fields <fields>', t.fields)
+        .option('--known-revision <revision>', t.revision)
+        .option('--json', 'JSON (JavaScript Object Notation, 数据交换格式)')
+        .action(async (options) => {
+        try {
+            const request = workspaceExecutionContextQuerySchema.parse({ fields: options.fields.split(',').map((field) => field.trim()),
+                ...(options.knownRevision ? { knownRevision: options.knownRevision } : {}) });
+            console.log(JSON.stringify(await readExecutionContext(request), null, options.json ? undefined : 2));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/tools.js

@@ -5,6 +5,7 @@ import { register3DCommands } from './tools-3d.js';
 import { registerDetectCommand } from './tools-detect.js';
 import { registerVideoReviewCommand } from './tools-video-review.js';
 import { registerImageContextCommand } from './tools-image-context.js';
+import { registerContextCommands } from './tools-context.js';
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
@@ -16,4 +17,5 @@ export function registerToolsCommands(program) {
     register3DCommands(tools);
     registerDetectCommand(tools);
     registerVideoReviewCommand(tools);
+    registerContextCommands(tools);
 }

package/dist/project-skills/builtin-import.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { canonicalProjectSkillsJson, declarationDigest, dependencyDigest, extractBundleArchive, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
+import { canonicalProjectSkillsJson, declarationDigest, dependencyDigest, extractBundleArchive, sourceTreeDigest, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
 import { LEGACY_VIDEO_SOURCE_HASHES, WORKSPACE_BUILTIN_SKILL_NAMES } from '@playcraft/common/cloud-workspace/runtime';
 import { projectSkillsCache } from './local-store.js';
 export const IMPORTABLE_BUILTIN_SKILLS = WORKSPACE_BUILTIN_SKILL_NAMES;
@@ -20,14 +20,15 @@ async function safeDirectory(root, path) {
     return current;
 }
 /** Selects published platform revisions once; neither directory contents nor names authorize a replacement. */
-export async function selectPlatformSkillSnapshot(names, access) {
+export async function selectPlatformSkillSnapshot(names, access, lockVersion = 4, existingLock = false) {
     if (!names.length || new Set(names).size !== names.length
         || names.some(name => !IMPORTABLE_BUILTIN_SKILLS.includes(name)))
         throw new Error('workspace_skills_builtin_unknown');
     if (!access)
         throw new Error('workspace_skills_platform_required');
     const requested = names.map(platformSkillRef);
-    const response = await access.resolve(requested);
+    const response = await (lockVersion === 4 ? existingLock ? access.resolve(requested, 4, 4) : access.resolve(requested, 4)
+        : access.resolve(requested));
     const snapshot = validateProjectSkillsSnapshot(response?.declaration, response?.lock);
     if (snapshot.declaration.entries.length !== names.length || snapshot.lock.entries.length !== names.length)
         throw new Error('workspace_skills_invalid');
@@ -41,16 +42,19 @@ export async function selectPlatformSkillSnapshot(names, access) {
     }
     const artifacts = await Promise.all(snapshot.lock.entries.map(async (entry) => {
         const archive = await access.loadArtifact(entry);
-        if (archive.length > 80 * 1024 * 1024 || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        const artifactHash = createHash('sha256').update(archive).digest('hex');
+        if (archive.length > 80 * 1024 * 1024 || (snapshot.lock.lockVersion === 3 && artifactHash !== entry.revision.artifactHash))
             throw new Error('workspace_skills_digest_mismatch');
         const extracted = extractBundleArchive(archive);
         if (extracted.issues.length || !extracted.files.some(file => file.path === 'SKILL.md'))
             throw new Error('workspace_skills_invalid_bundle');
-        return { artifactHash: entry.revision.artifactHash, archive };
+        if (snapshot.lock.lockVersion === 4 && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.revision.contentHash)
+            throw new Error('workspace_skills_digest_mismatch');
+        return { artifactHash, archive, contentHash: snapshot.lock.lockVersion === 4 ? entry.revision.contentHash : undefined };
     }));
     return { ...snapshot, artifacts };
 }
-async function commitSnapshot(directory, snapshot, originalDeclaration, staged) {
+async function commitSnapshot(directory, snapshot, originalDeclaration, originalLock, staged) {
     const declarationPath = join(directory, PROJECT_SKILLS_DECLARATION_PATH);
     const pending = [];
     for (const [path, value] of [[PROJECT_SKILLS_DECLARATION_PATH, snapshot.declaration], [PROJECT_SKILLS_LOCK_PATH, snapshot.lock]]) {
@@ -59,11 +63,25 @@ async function commitSnapshot(directory, snapshot, originalDeclaration, staged)
         await writeFile(temporary, `${canonicalProjectSkillsJson(value)}\n`, { flag: 'wx', mode: 0o644 });
         pending.push(temporary);
     }
+    const [currentDeclaration, currentLock] = await Promise.all([
+        readFile(declarationPath).catch((error) => { if (error.code === 'ENOENT')
+            return null; throw error; }),
+        readProjectSkillsLockFile(directory),
+    ]);
+    if (!currentDeclaration?.equals(originalDeclaration) || currentLock !== originalLock)
+        throw new Error('skills_revision_conflict');
     await rename(pending[0], declarationPath);
     try {
         await rename(pending[1], join(directory, PROJECT_SKILLS_LOCK_PATH));
     }
     catch (error) {
+        const current = await readFile(declarationPath).catch((readError) => {
+            if (readError.code === 'ENOENT')
+                return null;
+            throw readError;
+        });
+        if (!current?.equals(Buffer.from(`${canonicalProjectSkillsJson(snapshot.declaration)}\n`)))
+            throw new Error('skills_revision_conflict');
         // The old lock still exists. Restore its exact declaration before releasing the writer lease.
         const restore = `${declarationPath}.${randomUUID()}.tmp`;
         staged.push(restore);
@@ -75,13 +93,23 @@ async function commitSnapshot(directory, snapshot, originalDeclaration, staged)
 async function cacheArtifacts(cache, selected) {
     await mkdir(cache, { recursive: true, mode: 0o700 });
     for (const artifact of selected.artifacts) {
-        const path = join(cache, `${artifact.artifactHash}.tar.gz`);
-        try {
-            await writeFile(path, artifact.archive, { flag: 'wx', mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST' || !(await readFile(path)).equals(artifact.archive))
-                throw error;
+        for (const name of [`${artifact.artifactHash}.tar.gz`, ...(artifact.contentHash ? [`content-${artifact.contentHash}.tar.gz`] : [])]) {
+            const path = join(cache, name);
+            try {
+                await writeFile(path, artifact.archive, { flag: 'wx', mode: 0o600 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const existing = await readFile(path);
+                if (name.startsWith('content-')) {
+                    const extracted = extractBundleArchive(existing);
+                    if (extracted.issues.length || sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== artifact.contentHash)
+                        throw error;
+                }
+                else if (!existing.equals(artifact.archive))
+                    throw error;
+            }
         }
     }
 }
@@ -100,7 +128,8 @@ export async function importBuiltinProjectSkills(directory, options, cache = pro
         if (!declarationStat.isFile() || declarationStat.isSymbolicLink() || declarationStat.size > 1024 * 1024)
             throw new Error('workspace_skills_invalid');
         const originalDeclaration = await readFile(declarationPath);
-        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), await readProjectSkillsLockFile(directory));
+        const originalLock = await readProjectSkillsLockFile(directory);
+        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), originalLock);
         if (options.expectedDeclarationHash !== previous.lock.declarationHash || options.expectedLockHash !== hash(previous.lock))
             throw new Error('skills_revision_conflict');
         const next = structuredClone(previous);
@@ -122,7 +151,9 @@ export async function importBuiltinProjectSkills(directory, options, cache = pro
         }
         const imported = [];
         if (missing.length) {
-            const resolved = selected ?? await selectPlatformSkillSnapshot(missing, access);
+            const resolved = selected ?? await selectPlatformSkillSnapshot(missing, access, previous.lock.lockVersion, previous.lock.lockVersion === 4);
+            if (resolved.lock.lockVersion !== previous.lock.lockVersion)
+                throw new Error('workspace_skills_lock_version_mismatch');
             await cacheArtifacts(cache, resolved);
             for (const name of missing) {
                 const entry = resolved.declaration.entries.find(item => item.entryKey === name);
@@ -130,12 +161,12 @@ export async function importBuiltinProjectSkills(directory, options, cache = pro
                 if (!entry || !locked)
                     throw new Error('workspace_skills_invalid');
                 next.declaration.entries.push({ ...entry, enabled });
-                next.lock.entries.push(locked);
+                next.lock = { ...next.lock, entries: [...next.lock.entries, locked] };
                 imported.push(name);
             }
             next.lock.declarationHash = declarationDigest(next.declaration);
             validateProjectSkillsSnapshot(next.declaration, next.lock);
-            await commitSnapshot(directory, next, originalDeclaration, staged);
+            await commitSnapshot(directory, next, originalDeclaration, originalLock, staged);
         }
         return { ...next, imported, unchanged, lockHash: hash(next.lock) };
     }
@@ -159,7 +190,8 @@ export async function migrateVideoProjectSkills(directory, options, cache, acces
         if (!declarationStat.isFile() || declarationStat.isSymbolicLink() || declarationStat.size > 1024 * 1024)
             throw new Error('workspace_skills_invalid');
         const originalDeclaration = await readFile(declarationPath);
-        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), await readProjectSkillsLockFile(directory));
+        const originalLock = await readProjectSkillsLockFile(directory);
+        const previous = validateProjectSkillsSnapshot(originalDeclaration.toString('utf8'), originalLock);
         const oldLockHash = hash(previous.lock);
         if (options.expectedDeclarationHash !== previous.lock.declarationHash || options.expectedLockHash !== oldLockHash)
             throw new Error('skills_revision_conflict');
@@ -180,7 +212,9 @@ export async function migrateVideoProjectSkills(directory, options, cache, acces
                 throw new Error('workspace_skills_builtin_conflict');
             replacements.push({ entry, name });
         }
-        const selected = await selectPlatformSkillSnapshot(replacements.map(item => item.name), access);
+        const selected = await selectPlatformSkillSnapshot(replacements.map(item => item.name), access, previous.lock.lockVersion, previous.lock.lockVersion === 4);
+        if (selected.lock.lockVersion !== previous.lock.lockVersion)
+            throw new Error('workspace_skills_lock_version_mismatch');
         await cacheArtifacts(cache, selected);
         const next = structuredClone(previous);
         for (const { entry, name } of replacements) {
@@ -206,18 +240,31 @@ export async function migrateVideoProjectSkills(directory, options, cache, acces
         for (const { entry } of replacements) {
             if (entry.source.kind !== 'repository')
                 throw new Error('workspace_skills_invalid');
+            const expectedSource = previous.lock.entries.find(item => item.entryKey === entry.entryKey)?.sourceTreeHash;
+            if ((await readProjectSkillSource(directory, entry)).sourceTreeHash !== expectedSource)
+                throw new Error('workspace_skills_builtin_conflict');
             const from = join(directory, entry.source.root), to = join(history, entry.entryKey);
             await rename(from, to);
             moved.push({ from, to });
+            const movedEntry = { ...entry, source: { ...entry.source, root: `.playcraft/skill-migrations/${oldLockHash}/${entry.entryKey}` } };
+            if ((await readProjectSkillSource(directory, movedEntry)).sourceTreeHash !== expectedSource)
+                throw new Error('workspace_skills_builtin_conflict');
         }
-        await commitSnapshot(directory, next, originalDeclaration, staged);
+        await commitSnapshot(directory, next, originalDeclaration, originalLock, staged);
         committed = true;
         return { ...next, migrated: options.entryKeys, history: `.playcraft/skill-migrations/${oldLockHash}/migration.json`, lockHash: hash(next.lock) };
     }
     finally {
         if (!committed)
-            for (const item of moved.reverse())
-                await rename(item.to, item.from).catch(() => undefined);
+            for (const item of moved.reverse()) {
+                const occupied = await lstat(item.from).then(() => true, (error) => {
+                    if (error.code === 'ENOENT')
+                        return false;
+                    throw error;
+                });
+                if (!occupied)
+                    await rename(item.to, item.from).catch(() => undefined);
+            }
         for (const path of staged)
             await rm(path, { force: true });
         await rm(lease, { force: true });

package/dist/project-skills/commands.js

@@ -8,6 +8,7 @@ import { runLocalProjectSkills, localProjectSkillUsage } from './local-run.js';
 import { projectSkillsMessage as t } from './messages.js';
 import { reconcileLocalProjectSkills } from './reconcile.js';
 import { importBuiltinProjectSkills } from './builtin-import.js';
+import { migrateProjectSkillsLockV4 } from './migrate-lock.js';
 export async function inspectLocalProjectSkills(directory) {
     const inventory = await inspectProjectSkills(directory);
     // Report metadata only; never print complete skill bytes or project test data.
@@ -22,7 +23,7 @@ export function registerProjectSkillsCommands(skills) {
             process.stdout.write(`${JSON.stringify(await action(), null, 2)}\n`);
         }
         catch (error) {
-            process.stderr.write(`${t('failed')}: ${error instanceof Error && error.message === 'workspace_skills_platform_required' ? t('platformRequired') : error instanceof Error ? error.message : String(error)}\n`);
+            process.stderr.write(`${t('failed')}: ${error instanceof Error && error.message === 'workspace_skills_platform_required' ? t('platformRequired') : error instanceof Error && 'code' in error && error.code === 'lock_migration_required' ? t('migrateLockRequired') : error instanceof Error ? error.message : String(error)}\n`);
             process.exitCode = 1;
         }
     };
@@ -36,7 +37,15 @@ export function registerProjectSkillsCommands(skills) {
     project.command('usage').description(t('usage')).option('--dir <path>', t('directory'), '.')
         .action((options) => output(() => localProjectSkillUsage(resolve(options.dir))));
     project.command('sync').description(t('sync')).option('--dir <path>', t('directory'), '.')
-        .action((options) => output(() => syncLocalProjectSkills(resolve(options.dir))));
+        .option('--lock-version <3|4>', t('lockVersion'))
+        .action((options) => output(() => {
+        if (options.lockVersion !== undefined && options.lockVersion !== '3' && options.lockVersion !== '4')
+            throw new Error(t('invalidLockVersion'));
+        const lockVersion = options.lockVersion === undefined ? undefined : options.lockVersion === '4' ? 4 : 3;
+        return syncLocalProjectSkills(resolve(options.dir), undefined, { lockVersion });
+    }));
+    project.command('migrate-lock-v4').description(t('migrateLockV4')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => migrateProjectSkillsLockV4(resolve(options.dir))));
     project.command('import-builtins <names...>').description(t('importBuiltins')).option('--dir <path>', t('directory'), '.')
         .requiredOption('--expected-declaration-hash <hash>', t('expectedDeclarationHash'))
         .requiredOption('--expected-lock-hash <hash>', t('expectedLockHash'))

package/dist/project-skills/lifecycle.js

@@ -6,7 +6,7 @@ import { projectSkillsMessage as t } from './messages.js';
 /** Existing formats keep their legacy consumer; format 3 never silently downgrades. */
 export async function prepareLocalSkillLifecycle(directory, action, cache) {
     const raw = await readProjectSkillsLockFile(directory);
-    const managed = raw !== null && JSON.parse(raw).lockVersion === 3;
+    const managed = raw !== null && [3, 4].includes(JSON.parse(raw).lockVersion);
     if (!managed && process.env.PROJECT_SKILLS_ADOPTION_ENABLED !== 'true')
         return { managed: false };
     if (raw !== null && !managed)