@playcraft/cli 0.0.56 → 0.0.58

package/dist/project-skills/commands.js

@@ -0,0 +1,72 @@
+import { verifyLocalProjectSkills } from './validation.js';
+export { verifyLocalProjectSkills } from './validation.js';
+import { downloadLocalProjectSkillArtifacts } from './remote-cache.js';
+import { resolve } from 'node:path';
+import { inspectProjectSkills, } from '@playcraft/common/project-skills';
+import { syncLocalProjectSkills, enableLocalProjectSkill, installFrozenProjectSkills, explainLocalProjectSkills } from './local-store.js';
+import { runLocalProjectSkills, localProjectSkillUsage } from './local-run.js';
+import { projectSkillsMessage as t } from './messages.js';
+import { reconcileLocalProjectSkills } from './reconcile.js';
+export async function inspectLocalProjectSkills(directory) {
+    const inventory = await inspectProjectSkills(directory);
+    // Report metadata only; never print complete skill bytes or project test data.
+    return { declaration: inventory.declaration, discovered: inventory.discovered, issues: inventory.issues,
+        sources: inventory.sources.map((source) => ({ entryKey: source.entryKey, root: source.root,
+            sourceTreeHash: source.sourceTreeHash, files: source.files.map((file) => file.path) })) };
+}
+export function registerProjectSkillsCommands(skills) {
+    const project = skills.command('project').description(t('description'));
+    const output = async (action) => {
+        try {
+            process.stdout.write(`${JSON.stringify(await action(), null, 2)}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    };
+    project.command('run <prompt>').description(t('run')).requiredOption('--model <provider/model>', t('model'))
+        .option('--dir <path>', t('directory'), '.').action((prompt, options) => output(async () => {
+        const result = await runLocalProjectSkills(resolve(options.dir), { prompt, model: options.model });
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+        return result;
+    }));
+    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))));
+    project.command('reconcile').description(t('reconcile')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => reconcileLocalProjectSkills(resolve(options.dir), { write: true })));
+    project.command('install').description(t('install')).requiredOption('--frozen', t('frozen')).option('--dir <path>', t('directory'), '.')
+        .option('--online', t('online')).action((options) => output(async () => {
+        const directory = resolve(options.dir);
+        if (options.online)
+            await downloadLocalProjectSkillArtifacts(directory);
+        return installFrozenProjectSkills(directory);
+    }));
+    for (const enabled of [true, false])
+        project.command(enabled ? 'enable <entryKey>' : 'disable <entryKey>')
+            .description(t(enabled ? 'enable' : 'disable')).option('--dir <path>', t('directory'), '.')
+            .action((entryKey, options) => output(() => enableLocalProjectSkill(resolve(options.dir), entryKey, enabled)));
+    project.command('explain').description(t('explain')).option('--dir <path>', t('directory'), '.')
+        .action((options) => output(() => explainLocalProjectSkills(resolve(options.dir))));
+    project.command('inspect').description(t('inspect')).option('--dir <path>', t('directory'), '.')
+        .action(async (options) => {
+        const result = await inspectLocalProjectSkills(resolve(options.dir));
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (result.issues.length)
+            process.exitCode = 1;
+    });
+    project.command('verify').description(t('verify')).option('--dir <path>', t('directory'), '.')
+        .option('--json', t('json')).action(async (options) => {
+        try {
+            const result = await verifyLocalProjectSkills(resolve(options.dir));
+            process.stdout.write(`${options.json ? JSON.stringify(result) : t('verified')}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${t('failed')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/project-skills/lifecycle.js

@@ -0,0 +1,28 @@
+import { spawnSync } from 'node:child_process';
+import { readProjectSkillsLockFile } from '@playcraft/common/project-skills';
+import { syncLocalProjectSkills, readLocalProjectSkillSnapshot, installFrozenProjectSkills } from './local-store.js';
+import { verifyLocalProjectSkills } from './validation.js';
+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;
+    if (!managed && process.env.PROJECT_SKILLS_ADOPTION_ENABLED !== 'true')
+        return { managed: false };
+    if (raw !== null && !managed)
+        return { managed: false, legacy: true };
+    if (action === 'create' || action === 'push' || !managed)
+        await syncLocalProjectSkills(directory, cache);
+    await verifyLocalProjectSkills(directory);
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    if (action === 'push') {
+        const paths = ['.playcraft/skills.json', '.playcraft/skills.lock.json', ...snapshot.declaration.entries.flatMap(entry => entry.source.kind === 'repository' ? [entry.source.root, ...(entry.projectFiles ?? [])] : [])];
+        const status = spawnSync('git', ['status', '--porcelain', '--', ...paths], { cwd: directory, encoding: 'utf8' });
+        if (status.status !== 0 || status.stdout.trim())
+            throw new Error(t('commitRequired'));
+    }
+    // Source-only checkouts work offline. Registry packages remain exact and require an authorized cache fill.
+    if (!snapshot.lock.entries.some(entry => entry.revision.kind === 'release'))
+        await installFrozenProjectSkills(directory, cache);
+    return { managed: true, declarationHash: snapshot.lock.declarationHash };
+}

package/dist/project-skills/local-run.js

@@ -0,0 +1,112 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { readFile, writeFile, mkdir, readdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createInterface } from 'node:readline';
+import { effectiveProjectSkills, readManagedSkillEvidence } from '@playcraft/common/project-skills';
+import { installFrozenProjectSkills, readLocalProjectSkillSnapshot, projectSkillsCache } from './local-store.js';
+import { verifyLocalProjectSkills } from './validation.js';
+import { projectSkillsMessage as t } from './messages.js';
+const require = createRequire(import.meta.url);
+export async function localProjectSkillUsage(directory, cache = projectSkillsCache()) {
+    const root = join(cache, 'usage', createHash('sha256').update(await realpath(directory)).digest('hex'));
+    let files;
+    try {
+        files = await readdir(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return Promise.all(files.filter(file => /^[a-f0-9-]+\.json$/.test(file)).sort().map(async (file) => JSON.parse(await readFile(join(root, file), 'utf8'))));
+}
+/** Local evidence is explicitly client-reported; it never acts as a server evaluation or access grant. */
+export async function runLocalProjectSkills(directory, options, cache = projectSkillsCache()) {
+    if (execFileSync('opencode', ['--version'], { encoding: 'utf8', timeout: 10000 }).trim() !== '1.18.31')
+        throw new Error(t('runner'));
+    const cwd = await realpath(directory);
+    await verifyLocalProjectSkills(cwd);
+    const snapshot = await readLocalProjectSkillSnapshot(cwd);
+    const installed = await installFrozenProjectSkills(cwd, cache);
+    const runId = randomUUID(), runtimeRoot = join(installed.generation, '.runtime');
+    const home = join(runtimeRoot, 'home');
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    const entries = await Promise.all(effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent').map(async (entry) => {
+        const bodyFile = join(installed.generation, entry.entryKey, 'SKILL.md');
+        return { name: entry.entryKey, skillRef: entry.revision.skillRef, revisionId: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
+            artifactHash: entry.revision.artifactHash, bodyFile, bodyHash: createHash('sha256').update(await readFile(bodyFile)).digest('hex'), description: entry.revision.skillRef };
+    }));
+    await writeFile(join(runtimeRoot, 'manifest.json'), JSON.stringify({ schemaVersion: 1, runtimeId: runId, lockId: snapshot.lock.declarationHash, entries }), { mode: 0o400 });
+    await writeFile(join(runtimeRoot, 'opencode.json'), JSON.stringify({ model: options.model,
+        plugin: [pathToFileURL(require.resolve('@playcraft/common/project-skills/runtime-plugin')).href] }), { mode: 0o400 });
+    const usageRoot = join(cache, 'usage', createHash('sha256').update(cwd).digest('hex'));
+    await mkdir(usageRoot, { recursive: true, mode: 0o700 });
+    const evidence = new Map();
+    const report = { schemaVersion: 1, runId, declarationHash: snapshot.lock.declarationHash, provenance: 'local-client-reported',
+        runnerVersion: '1.18.31', model: options.model, startedAt: new Date().toISOString(), status: 'running', collectionStatus: 'collecting', loaded: [] };
+    const reportPath = join(usageRoot, `${runId}.json`);
+    await writeFile(reportPath, JSON.stringify(report), { mode: 0o600 });
+    const environment = { ...process.env, HOME: home, XDG_CONFIG_HOME: join(home, '.config'), XDG_DATA_HOME: join(home, '.local/share'), XDG_STATE_HOME: join(home, '.local/state'), XDG_CACHE_HOME: join(home, '.cache'),
+        OPENCODE_CONFIG: join(runtimeRoot, 'opencode.json'), OPENCODE_CONFIG_DIR: join(runtimeRoot, 'config'),
+        OPENCODE_DISABLE_PROJECT_CONFIG: 'true', OPENCODE_DISABLE_CLAUDE_CODE: 'true', OPENCODE_DISABLE_DEFAULT_PLUGINS: 'true', OPENCODE_DISABLE_AUTOUPDATE: 'true',
+        PLAYCRAFT_SKILL_RUNTIME_FILE: join(runtimeRoot, 'manifest.json') };
+    delete environment.PLAYCRAFT_SKILL_RUNTIME_ROOT;
+    delete environment.OPENCODE_CONFIG_CONTENT;
+    let child;
+    let cancelled = false, killTimer;
+    const cancel = () => {
+        cancelled = true;
+        child?.kill('SIGTERM');
+        killTimer ??= setTimeout(() => child?.kill('SIGKILL'), 5000);
+        killTimer.unref();
+    };
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+        child = spawn('opencode', ['run', '--format', 'json', '--model', options.model, '--', options.prompt], { cwd, env: environment, stdio: ['ignore', 'pipe', 'inherit'] });
+        // Resolve spawn failures so an early error cannot become an unhandled rejection while reading stdout.
+        const finished = new Promise(resolve => {
+            child.once('error', error => resolve({ code: 1, error }));
+            child.once('close', code => resolve({ code: code ?? 1 }));
+        });
+        const lines = createInterface({ input: child.stdout });
+        let partial = false;
+        for await (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                const parsed = readManagedSkillEvidence(event);
+                if (parsed?.runtimeId === runId && parsed.lockId === report.declarationHash && entries.some(entry => entry.revisionId === parsed.skillVersionId && entry.artifactHash === parsed.artifactHash && entry.bodyHash === parsed.bodyHash)) {
+                    evidence.set(parsed.dedupeKey, parsed);
+                    report.loaded = [...evidence.values()];
+                    await writeFile(reportPath, JSON.stringify(report), { mode: 0o600 });
+                }
+                if (event.type === 'text' && typeof event.part?.text === 'string')
+                    process.stderr.write(event.part.text);
+            }
+            catch {
+                partial = true;
+            }
+        }
+        const result = await finished;
+        if (result.error)
+            throw result.error;
+        const code = cancelled ? 130 : result.code;
+        report.status = cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed';
+        report.collectionStatus = code === 0 && !partial ? 'complete' : 'partial';
+        return { ...report, reportPath, exitCode: code };
+    }
+    finally {
+        if (killTimer)
+            clearTimeout(killTimer);
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+        if (report.status === 'running') {
+            report.status = 'failed';
+            report.collectionStatus = 'partial';
+        }
+        await writeFile(reportPath, JSON.stringify(report), { mode: 0o600 });
+    }
+}

package/dist/project-skills/local-store.js

@@ -0,0 +1,149 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile, lstat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { projectSkillsMessage as t } from './messages.js';
+import { buildLocalProjectSkillsSnapshot, canonicalProjectSkillsJson, extractBundleArchive, createCanonicalBundleArchive, readProjectSkillSource, sourceTreeDigest, readProjectSkillsLockFile, inspectProjectSkills, setProjectSkillEnabled, validateProjectSkillsSnapshot, effectiveProjectSkills, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
+export const projectSkillsCache = () => process.env.PLAYCRAFT_SKILLS_CACHE_DIR
+    ? resolve(process.env.PLAYCRAFT_SKILLS_CACHE_DIR) : join(homedir(), '.playcraft', 'skill-artifacts');
+export async function readLocalProjectSkillSnapshot(directory) {
+    const inventory = await inspectProjectSkills(directory);
+    if (inventory.issues.length)
+        throw new Error(JSON.stringify(inventory.issues));
+    return validateProjectSkillsSnapshot(inventory.declaration, await readProjectSkillsLockFile(directory));
+}
+/** Serializes local writers; an interrupted pair is diagnosed by the declaration digest. */
+async function change(directory, action) {
+    const management = join(directory, '.playcraft');
+    await mkdir(management, { recursive: true });
+    if ((await lstat(management)).isSymbolicLink())
+        throw new Error('Linked project management directory');
+    const lease = join(management, 'skills-write.lock');
+    await writeFile(lease, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+    try {
+        return await action();
+    }
+    finally {
+        await rm(lease);
+    }
+}
+async function writeSnapshot(directory, snapshot) {
+    validateProjectSkillsSnapshot(snapshot.declaration, snapshot.lock);
+    for (const [file, value] of [[PROJECT_SKILLS_DECLARATION_PATH, snapshot.declaration], [PROJECT_SKILLS_LOCK_PATH, snapshot.lock]]) {
+        const target = join(directory, file), temporary = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temporary, `${canonicalProjectSkillsJson(value)}\n`, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, target);
+    }
+}
+export async function syncLocalProjectSkills(directory, cache = projectSkillsCache()) {
+    return change(directory, async () => {
+        let previous;
+        try {
+            previous = await readProjectSkillsLockFile(directory) ?? undefined;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const snapshot = buildLocalProjectSkillsSnapshot(await inspectProjectSkills(directory), previous);
+        await mkdir(cache, { recursive: true, mode: 0o700 });
+        for (const artifact of snapshot.artifacts) {
+            const target = join(cache, `${artifact.artifactHash}.tar.gz`);
+            const temporary = `${target}.${randomUUID()}.tmp`;
+            await writeFile(temporary, artifact.archive, { flag: 'wx', mode: 0o600 });
+            await rename(temporary, target);
+        }
+        await writeSnapshot(directory, snapshot);
+        return { declaration: snapshot.declaration, lock: snapshot.lock };
+    });
+}
+export async function enableLocalProjectSkill(directory, entryKey, enabled) {
+    return change(directory, async () => {
+        const previous = await readLocalProjectSkillSnapshot(directory);
+        const next = setProjectSkillEnabled(previous.declaration, previous.lock, entryKey, enabled);
+        // Disabled required dependencies are shown immediately, before changing either file.
+        for (const surface of ['portal-agent', 'sandbox-agent', 'build-time'])
+            effectiveProjectSkills(next.declaration, next.lock, surface);
+        await writeSnapshot(directory, next);
+        return next;
+    });
+}
+/** Restores exact cached bytes to a new generation. Never writes source directories. */
+export async function installFrozenProjectSkills(directory, cache = projectSkillsCache()) {
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    const generation = join(cache, 'runs', randomUUID());
+    const effective = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
+    try {
+        await mkdir(generation, { recursive: true, mode: 0o700 });
+        for (const entry of effective) {
+            const cached = join(cache, `${entry.revision.artifactHash}.tar.gz`);
+            let archive;
+            try {
+                archive = await readFile(cached);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT' || entry.revision.kind !== 'source')
+                    throw error;
+                const declaration = snapshot.declaration.entries.find(item => item.entryKey === entry.entryKey);
+                const source = await readProjectSkillSource(directory, declaration);
+                if (source.sourceTreeHash !== entry.sourceTreeHash)
+                    throw new Error(`Source digest mismatch: ${entry.entryKey}`);
+                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+                if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+                    throw new Error(`Artifact digest mismatch: ${entry.entryKey}`);
+                await writeFile(cached, archive, { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST')
+                    throw error; });
+            }
+            if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+                throw new Error(`Artifact digest mismatch: ${entry.entryKey}`);
+            const extracted = extractBundleArchive(archive);
+            if (extracted.issues.length)
+                throw new Error(JSON.stringify(extracted.issues));
+            if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
+                throw new Error(`Source digest mismatch: ${entry.entryKey}`);
+            for (const file of extracted.files) {
+                const target = join(generation, entry.entryKey, file.path);
+                await mkdir(join(target, '..'), { recursive: true });
+                await writeFile(target, file.data, { flag: 'wx', mode: 0o444 });
+            }
+        }
+        return { generation, entries: effective.length, declarationHash: snapshot.lock.declarationHash };
+    }
+    catch (error) {
+        await rm(generation, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function explainLocalProjectSkills(directory) {
+    const { declaration, lock } = await readLocalProjectSkillSnapshot(directory);
+    return declaration.entries.map((entry) => ({ ...entry, locked: lock.entries.find((locked) => locked.entryKey === entry.entryKey), reason: entry.enabled ? 'enabled_in_project' : 'disabled_in_project' }));
+}
+export async function adoptServerProjectSkillSnapshot(directory, expected, response, checkpoint) {
+    const next = validateProjectSkillsSnapshot(response.declaration, response.lock);
+    const withoutIdentity = (snapshot) => ({
+        declaration: { ...snapshot.declaration, entries: snapshot.declaration.entries.map(entry => ({ ...entry,
+                source: entry.source.kind === 'repository' ? { kind: entry.source.kind, root: entry.source.root } : entry.source })) },
+        entries: snapshot.lock.entries.map(entry => ({ entryKey: entry.entryKey, sourceTreeHash: entry.sourceTreeHash,
+            dependencies: entry.dependencies,
+            revision: entry.revision.kind === 'source' ? { ...entry.revision, skillRef: undefined } : entry.revision })),
+    });
+    if (canonicalProjectSkillsJson(withoutIdentity(expected)) !== canonicalProjectSkillsJson(withoutIdentity(next)))
+        throw new Error(t('reconcileChanged'));
+    return change(directory, async () => {
+        const current = await readLocalProjectSkillSnapshot(directory);
+        if (canonicalProjectSkillsJson(current) !== canonicalProjectSkillsJson(expected))
+            throw new Error(t('reconcileChanged'));
+        for (const entry of current.declaration.entries) {
+            if (entry.source.kind !== 'repository')
+                continue;
+            const source = await readProjectSkillSource(directory, entry);
+            if (source.sourceTreeHash !== current.lock.entries.find(item => item.entryKey === entry.entryKey)?.sourceTreeHash)
+                throw new Error(t('reconcileChanged'));
+        }
+        checkpoint();
+        const changed = canonicalProjectSkillsJson(current) !== canonicalProjectSkillsJson(next);
+        if (changed)
+            await writeSnapshot(directory, next);
+        return { changed };
+    });
+}

package/dist/project-skills/messages.js

@@ -0,0 +1,72 @@
+const messages = {
+    en: {
+        reconcile: 'Register the pushed commit and adopt verified platform skill identities',
+        reconcileChanged: 'The branch, source bytes, or settings changed. Sync, commit and push the current project before reconciling.',
+        reconcilePending: 'Indexing continues on the server. Retry reconcile later. Operation:',
+        reconcileFailed: 'Skill indexing failed. Inspect the project adoption operation and retry it.',
+        reconcileNext: 'Skills are registered. Run skills project reconcile to adopt the verified identities locally.',
+        reconcileCommit: 'Verified skill identities saved. Commit the declaration and lock, then run remix push.',
+        reconcileUnchanged: 'Local skills match the registered platform revisions.',
+        pushIndexFailed: 'Git push succeeded, but skill indexing did not finish. Run skills project reconcile to retry.',
+        unregistered: 'New skill sources are not in the project lock. Run skills project sync before starting a task.',
+        online: 'Download missing exact artifacts using this Remix’s platform authorization',
+        downloadMismatch: 'The server has no authorized artifact matching this local lock. Sync the project first.',
+        commitRequired: 'Skill source or lock changes are ready. Commit them, then run remix push again.',
+        run: 'Run a task with the frozen project skills in OpenCode 1.18.31',
+        usage: 'Show locally reported skill deliveries (no chat upload)',
+        model: 'OpenCode model identifier; credentials come from the local environment',
+        runner: 'Managed skills require OpenCode 1.18.31.',
+        sync: 'Save source revisions and cache their exact artifacts offline',
+        install: 'Restore exactly the saved lock from the local cache',
+        frozen: 'Require exact locked artifacts',
+        enable: 'Enable a project skill for the next run',
+        disable: 'Disable a project skill for the next run',
+        explain: 'Explain configured revisions, sources and enablement',
+        description: 'Inspect and validate this project’s managed skills',
+        inspect: 'Inspect source directories and declarations without changing files',
+        verify: 'Validate the saved lock and local source bytes',
+        directory: 'Project directory',
+        json: 'Print structured output',
+        verified: 'Local skill sources and configuration match the lock. Server authorization and runner verification are separate checks.',
+        failed: 'Skill verification failed',
+        missing: 'The project does not have a managed declaration and lock yet.',
+        changed: 'Source files have changed since the saved revision',
+    },
+    zh: {
+        reconcile: '登记已推送的提交，并采用平台核验后的技能身份',
+        reconcileChanged: '分支、源文件或配置发生变化，请同步、提交并推送当前项目后再对账。',
+        reconcilePending: '服务端仍在登记，请稍后重新运行 reconcile。操作编号：',
+        reconcileFailed: '技能登记失败，请检查项目接管操作并重试。',
+        reconcileNext: '技能源已登记，请运行 skills project reconcile 在本地采用已核验的身份。',
+        reconcileCommit: '已保存核验后的技能身份，请提交声明和锁文件，然后运行 remix push。',
+        reconcileUnchanged: '本地技能与平台登记的修订一致。',
+        pushIndexFailed: 'Git 推送成功，但技能登记未完成。请运行 skills project reconcile 重试。',
+        unregistered: '发现尚未登记到项目锁的技能源，请先运行 skills project sync 再开始任务。',
+        online: '使用此 Remix 的平台权限下载缺失的精确制品',
+        downloadMismatch: '服务端没有与此本地锁匹配的授权制品，请先同步项目。',
+        commitRequired: '技能源或锁文件已更新，请提交这些修改后再次运行 remix push。',
+        run: '使用固定项目技能和 OpenCode 1.18.31 运行任务',
+        usage: '查看本地自报的技能加载记录（不上传聊天）',
+        model: 'OpenCode 模型标识；凭据使用本地环境',
+        runner: '受控技能需要 OpenCode 1.18.31。',
+        sync: '保存源修订并离线缓存精确制品',
+        install: '按锁从本地缓存还原精确制品',
+        frozen: '要求精确锁定制品',
+        enable: '在下次运行中启用项目技能',
+        disable: '在下次运行中停用项目技能',
+        explain: '解释配置的修订、来源与启停状态',
+        description: '检查和验证当前项目的受控技能',
+        inspect: '检查技能源目录和声明，不修改文件',
+        verify: '验证已保存的锁和本地源文件',
+        directory: '项目目录',
+        json: '输出结构化结果',
+        verified: '本地技能源和配置与锁一致。服务端授权和运行器验证仍需单独检查。',
+        failed: '技能验证失败',
+        missing: '此项目还没有受控技能声明和锁。',
+        changed: '源文件与已保存的修订不一致',
+    },
+};
+export function projectSkillsMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/project-skills/reconcile.js

@@ -0,0 +1,62 @@
+import { spawnSync } from 'node:child_process';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { readRemixLocalMeta } from '../remix/local-git.js';
+import { readLocalProjectSkillSnapshot, adoptServerProjectSkillSnapshot } from './local-store.js';
+import { projectSkillsMessage as t } from './messages.js';
+/** Register the saved commit, then adopt only identity changes for the same local bytes and settings. */
+export async function reconcileLocalProjectSkills(directory, options = {}) {
+    const metadata = readRemixLocalMeta(directory);
+    const git = (args) => {
+        const result = spawnSync('git', args, { cwd: directory, encoding: 'utf8' });
+        if (result.status !== 0)
+            throw new Error(t('reconcileChanged'));
+        return result.stdout.trim();
+    };
+    if (git(['branch', '--show-current']) !== metadata.branch)
+        throw new Error(t('reconcileChanged'));
+    const commit = git(['rev-parse', 'HEAD']);
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    const paths = [
+        '.playcraft/skills.json',
+        '.playcraft/skills.lock.json',
+        ...snapshot.declaration.entries.flatMap((entry) => entry.source.kind === 'repository' ? [entry.source.root, ...(entry.projectFiles ?? [])] : []),
+    ];
+    if (git(['status', '--porcelain', '--', ...paths]))
+        throw new Error(t('commitRequired'));
+    const client = new PlayCraftHttpClient(options);
+    const base = `/projects/${encodeURIComponent(metadata.projectId)}/skills`;
+    const query = new URLSearchParams({ branch: metadata.branch });
+    const request = () => ({ signal: AbortSignal.timeout(30_000), redirect: 'error' });
+    const view = await client.get(`${base}/config?${query}`, undefined, request());
+    let operation = await client.post(`${base}/index`, { branch: metadata.branch, commit, expectedRevisionId: view.configuration?.id ?? null }, request());
+    const deadline = Date.now() + 15 * 60_000;
+    while (!['completed', 'failed', 'blocked', 'cancelled'].includes(operation.phase)) {
+        if (Date.now() > deadline)
+            throw new Error(`${t('reconcilePending')} ${operation.id}`);
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        operation = await client.get(`${base}/adoptions/${operation.id}?${query}`, undefined, request());
+    }
+    if (operation.phase !== 'completed')
+        throw new Error(operation.issues?.[0]?.detail || t('reconcileFailed'));
+    const updated = await client.get(`${base}/config?${query}`, undefined, request());
+    if (!updated.configuration || updated.configuration.id !== operation.configRevisionId)
+        throw new Error(t('reconcileChanged'));
+    if (!options.write)
+        return {
+            operationId: operation.id,
+            configRevisionId: operation.configRevisionId,
+            commit,
+            message: t('reconcileNext'),
+        };
+    const result = await adoptServerProjectSkillSnapshot(directory, snapshot, updated.configuration, () => {
+        if (git(['rev-parse', 'HEAD']) !== commit || git(['status', '--porcelain', '--', ...paths]))
+            throw new Error(t('reconcileChanged'));
+    });
+    return {
+        ...result,
+        operationId: operation.id,
+        configRevisionId: operation.configRevisionId,
+        commit,
+        message: result.changed ? t('reconcileCommit') : t('reconcileUnchanged'),
+    };
+}

package/dist/project-skills/remote-cache.js

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, writeFile, rename, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { readRemixLocalMeta } from '../remix/local-git.js';
+import { readLocalProjectSkillSnapshot, projectSkillsCache } from './local-store.js';
+import { projectSkillsMessage as t } from './messages.js';
+/** Only exact project-authorized revisions; identifiers inside Git never grant download access. */
+export async function downloadLocalProjectSkillArtifacts(directory, cache = projectSkillsCache()) {
+    const meta = readRemixLocalMeta(directory), client = new PlayCraftHttpClient();
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    const query = new URLSearchParams({ branch: meta.branch });
+    const view = await client.get(`/projects/${encodeURIComponent(meta.projectId)}/skills/config?${query}`);
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    let downloaded = 0;
+    for (const locked of snapshot.lock.entries) {
+        const file = join(cache, `${locked.revision.artifactHash}.tar.gz`);
+        try {
+            if (createHash('sha256').update(await readFile(file)).digest('hex') === locked.revision.artifactHash)
+                continue;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const authorized = view.entries?.find(entry => entry.entryKey === locked.entryKey && entry.artifactHash === locked.revision.artifactHash);
+        if (!authorized)
+            throw new Error(t('downloadMismatch'));
+        const response = await fetch(client.url(`/projects/${encodeURIComponent(meta.projectId)}/skills/versions/${authorized.versionId}/archive?${query}`), {
+            headers: { Authorization: `Bearer ${client.token}`, 'X-Request-Id': client.requestId }, redirect: 'error', signal: AbortSignal.timeout(60000),
+        });
+        if (!response.ok || !response.body)
+            throw new Error(`${t('downloadMismatch')} (${response.status})`);
+        const parts = [];
+        let size = 0;
+        for await (const chunk of response.body) {
+            size += chunk.byteLength;
+            if (size > 80 * 1024 * 1024)
+                throw new Error(t('downloadMismatch'));
+            parts.push(Buffer.from(chunk));
+        }
+        const archive = Buffer.concat(parts);
+        if (createHash('sha256').update(archive).digest('hex') !== locked.revision.artifactHash)
+            throw new Error(t('downloadMismatch'));
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        await writeFile(temporary, archive, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, file);
+        downloaded++;
+    }
+    return { downloaded };
+}

package/dist/project-skills/validation.js

@@ -0,0 +1,19 @@
+import { readProjectSkillSource, inspectProjectSkills } from '@playcraft/common/project-skills';
+import { readLocalProjectSkillSnapshot } from './local-store.js';
+import { projectSkillsMessage as t } from './messages.js';
+export async function verifyLocalProjectSkills(directory) {
+    const snapshot = await readLocalProjectSkillSnapshot(directory);
+    const inventory = await inspectProjectSkills(directory);
+    if (inventory.sources.length !== snapshot.declaration.entries.filter(entry => entry.source.kind === 'repository').length) {
+        throw new Error(t('unregistered'));
+    }
+    for (const entry of snapshot.declaration.entries) {
+        if (entry.source.kind !== 'repository')
+            continue;
+        const actual = await readProjectSkillSource(directory, entry);
+        const expected = snapshot.lock.entries.find((locked) => locked.entryKey === entry.entryKey);
+        if (actual.sourceTreeHash !== expected?.sourceTreeHash)
+            throw new Error(`${t('changed')}: ${entry.entryKey}`);
+    }
+    return { valid: true, declarationHash: snapshot.lock.declarationHash, entries: snapshot.lock.entries.length, scope: 'local-source-and-config' };
+}

package/dist/remix/clone.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
@@ -151,6 +152,7 @@ export async function remixClone(options) {
     };
     writePlaycraftMeta(targetDir, meta);
     configureRepoCredentialHelper(targetDir);
+    await prepareLocalSkillLifecycle(targetDir, 'checkout');
     let projectType;
     try {
         const project = await client.get(`/projects/${encodeURIComponent(projectId)}`);
@@ -200,7 +202,8 @@ export async function remixClone(options) {
     else {
         console.log('  playcraft start --project <project-id>   # PlayCanvas / 本地 Agent 预览');
     }
-    console.log('  git pull / git push   # 经 PlayCraft Git 代理（需已 login）');
+    console.log('  playcraft remix pull   # 拉取远端（沙箱 Save 后）');
+    console.log('  playcraft remix push   # 推回 Remix（Windows 勿直接 git push/pull）');
 }
 export { isRemoteCloneSource, resolveRemixCloneTarget };
 /**

package/dist/remix/init-template.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import * as path from 'node:path';
 import { applyEnginePackToProject, bakeFullTemplate, KNOWN_ADAPTERS, readAdapterFromAtomTree, readEngineMarker, resolveCliPackageRoot, } from '../scaffold/compose.js';
 import { autoLinkSkillsFromAtomTree } from '../commands/skills.js';
@@ -68,6 +69,7 @@ export async function initTemplateCommand(opts) {
             console.log(`  ⚠ auto-link skipped: ${err.message}`);
         }
     }
+    await prepareLocalSkillLifecycle(projectDir, 'create');
     console.log('\n下一步：');
     console.log('  npm install');
     console.log('  阅读 .claude/skills/<atom>/SKILL.md（已自动 link）并填 logs/developer-log.md § Skill Preflight');