@playcraft/cli 0.1.69 → 0.1.71

package/dist/workspace-runtime/workspaces/skills.js

@@ -1,26 +1,17 @@
 import { createHash } from 'node:crypto';
-import { constants } from 'node:fs';
-import { cp, lstat, open, readFile, readdir, rm, writeFile } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-import { load } from 'js-yaml';
-import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { cp, readdir, rm } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { canonicalProjectSkillsJson, inspectProjectSkills, readProjectSkillsLockFile } from '@playcraft/common/project-skills';
+import { ensureProjectSkillDirectory as safeDirectory, readLockedProjectSkillFiles as lockedFiles, projectSkillMetadata as metadata, readLockedProjectSkillSnapshot as readWorkspaceSkillSnapshot, freezeLockedProjectSkills, } from '../../project-skills/discovery.js';
+export { readLockedProjectSkillSnapshot as readWorkspaceSkillSnapshot } from '../../project-skills/discovery.js';
 import { initializeLocalProjectSkills } from '../../project-skills/local-store.js';
 import { resolveCliPackageRoot } from '../../scaffold/compose.js';
 import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import.js';
 import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
 import { excludeFromGit } from './dependencies.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
-import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
+import { ensureSharedDirectory } from './shared-write.js';
 import { ensureWorkspaceRemixReferenceSkill } from './remix-reference-skill.js';
-/** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
-export async function readWorkspaceSkillSnapshot(root) {
-    const management = await lstat(join(root, '.playcraft'));
-    const declaration = join(root, '.playcraft/skills.json');
-    const stat = await lstat(declaration);
-    if (!management.isDirectory() || management.isSymbolicLink() || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
-        throw new Error('workspace_skills_invalid');
-    return validateProjectSkillsSnapshot(await readFile(declaration, 'utf8'), await readProjectSkillsLockFile(root));
-}
 /** Maintains the bundled reference guide while preserving project selection and custom revisions. */
 export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
     await excludeFromGit(root, '/.playcraft/skills/');
@@ -61,177 +52,23 @@ export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
         },
     });
 }
-async function safeDirectory(root, path) {
-    let current = root;
-    for (const segment of path.split('/')) {
-        current = join(current, segment);
-        // Validate every existing segment before creating anything, so a link never redirects the tree.
-        const stat = await lstat(current).catch((error) => {
-            if (error.code === 'ENOENT')
-                return undefined;
-            throw error;
-        });
-        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
-            throw new Error('workspace_skills_invalid');
-    }
-    await ensureSharedDirectory(root, current);
-    return current;
-}
-/** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
-async function lockedFiles(root, cache, entry, view, loadArtifact) {
-    const persistent = await safeDirectory(root, '.playcraft/skill-artifacts');
-    const saved = join(persistent, `${entry.revision.artifactHash}.tar.gz`);
-    const path = join(cache, `${entry.revision.artifactHash}.tar.gz`);
-    const contentHash = view.lock.lockVersion === 4 ? entry.revision.contentHash : undefined;
-    const contentSaved = contentHash ? join(persistent, `content-${contentHash}.tar.gz`) : undefined;
-    const contentPath = contentHash ? join(cache, `content-${contentHash}.tar.gz`) : undefined;
-    let archive;
-    let contentAddressed = false;
-    try {
-        const stat = await lstat(saved);
-        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
-            throw new Error('workspace_skills_invalid_bundle');
-        archive = await readFile(saved);
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-        try {
-            if (!contentSaved)
-                throw error;
-            const stat = await lstat(contentSaved);
-            if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
-                throw new Error('workspace_skills_invalid_bundle');
-            archive = await readFile(contentSaved);
-            contentAddressed = true;
-        }
-        catch (cacheError) {
-            if (cacheError.code !== 'ENOENT')
-                throw cacheError;
-            try {
-                archive = await readFile(path);
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
-                try {
-                    if (!contentPath)
-                        throw error;
-                    archive = await readFile(contentPath);
-                    contentAddressed = true;
-                }
-                catch (contentError) {
-                    if (contentError.code !== 'ENOENT')
-                        throw contentError;
-                    const declaration = view.declaration.entries.find(item => item.entryKey === entry.entryKey);
-                    if (entry.revision.kind === 'source' && declaration.source.kind === 'repository') {
-                        const source = await readProjectSkillSource(root, declaration);
-                        if (source.sourceTreeHash !== entry.sourceTreeHash)
-                            throw new Error('workspace_skills_source_changed');
-                        if (contentHash) {
-                            if (source.sourceTreeHash !== contentHash)
-                                throw new Error('workspace_skills_digest_mismatch');
-                            return source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) }));
-                        }
-                        archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
-                    }
-                    else {
-                        if (!loadArtifact)
-                            throw new Error('workspace_skills_artifact_unavailable');
-                        archive = await loadArtifact(entry);
-                        contentAddressed = Boolean(contentHash);
-                    }
-                }
-            }
-        }
-    }
-    if (!contentAddressed && createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    const extracted = extractBundleArchive(archive);
-    if (extracted.issues.length)
-        throw new Error('workspace_skills_invalid_bundle');
-    if (contentHash && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== contentHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
-        throw new Error('workspace_skills_digest_mismatch');
-    await writeSharedFile(root, contentAddressed ? contentSaved : saved, archive);
-    return extracted.files;
-}
-function metadata(entryKey, content) {
-    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
-    const parsed = frontmatter ? load(frontmatter[1]) : {};
-    const data = parsed && typeof parsed === 'object' ? parsed : {};
-    return { entryKey, name: typeof data.name === 'string' ? data.name : entryKey,
-        description: typeof data.description === 'string' ? data.description : '', content };
-}
 export async function readWorkspaceSkills(root, cache, loadArtifact) {
     const snapshot = await readWorkspaceSkillSnapshot(root);
-    const skills = await Promise.all(snapshot.lock.entries.map(async (entry) => {
+    const reads = await Promise.allSettled(snapshot.lock.entries.map(async (entry) => {
         const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
         const body = files.find(file => file.path === 'SKILL.md');
         if (!body)
             throw new Error('workspace_skills_body_missing');
         return metadata(entry.entryKey, body.data.toString('utf8'));
     }));
+    const skills = reads.map(result => {
+        if (result.status === 'rejected')
+            throw result.reason;
+        return result.value;
+    });
     return { ...snapshot, lockHash: createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex'), skills };
 }
 /** Read-only task generation lives outside source discovery and is omitted from Git/snapshots. */
 export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
-    const snapshot = await readWorkspaceSkillSnapshot(root);
-    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
-    const base = await safeDirectory(root, '.playcraft/skills');
-    const lockHash = createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex');
-    const generation = await safeDirectory(base, lockHash);
-    const skills = [];
-    const expectedFiles = new Set();
-    for (const entry of entries) {
-        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
-        for (const file of files) {
-            const target = join(generation, entry.entryKey, file.path);
-            const relative = join(entry.entryKey, file.path);
-            expectedFiles.add(relative);
-            await safeDirectory(generation, dirname(relative));
-            // shared
-            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(error => {
-                if (error.code !== 'EEXIST')
-                    throw error;
-            });
-            const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
-            try {
-                const stat = await handle.stat();
-                if (!stat.isFile() || stat.nlink !== 1 || !file.data.equals(await handle.readFile()))
-                    throw new Error('workspace_skills_digest_mismatch');
-                // A private controller umask must not remove the developer's read access.
-                // Repair only the verified inode, keeping every frozen byte read-only.
-                await handle.chmod(0o444);
-            }
-            finally {
-                await handle.close();
-            }
-        }
-        const body = files.find(file => file.path === 'SKILL.md');
-        if (!body)
-            throw new Error('workspace_skills_body_missing');
-        const info = metadata(entry.entryKey, body.data.toString('utf8'));
-        skills.push({ name: info.name, description: info.description, skillRef: entry.revision.skillRef,
-            revision: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
-            path: join(generation, entry.entryKey, 'SKILL.md') });
-    }
-    const verifyTree = async (directory, relative = '') => {
-        for (const item of await readdir(directory, { withFileTypes: true })) {
-            const path = join(relative, item.name);
-            if (item.isSymbolicLink())
-                throw new Error('workspace_skills_invalid_bundle');
-            if (item.isDirectory()) {
-                if (![...expectedFiles].some(file => file.startsWith(`${path}/`)))
-                    throw new Error('workspace_skills_invalid_bundle');
-                await verifyTree(join(directory, item.name), path);
-            }
-            else if (!item.isFile() || !expectedFiles.has(path))
-                throw new Error('workspace_skills_invalid_bundle');
-        }
-    };
-    await verifyTree(generation);
-    return { declarationHash: snapshot.lock.declarationHash,
-        lockHash, skills };
+    return freezeLockedProjectSkills(root, cache, loadArtifact);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.69",
+  "version": "0.1.71",
   "private": false,
   "type": "module",
   "engines": {
@@ -56,8 +56,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.69",
-    "@playcraft/common": "0.1.69",
+    "@playcraft/build": "0.1.71",
+    "@playcraft/common": "0.1.71",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template/.claude/skills/playcraft-skill-recommender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-skill-recommender
-description: 构建项目前的 Skill 推荐与脚手架工具。在开始任何新游戏项目前必须先调用，根据引擎（threejs/phaser）和意图关键词，自动推荐完整的代码 skill 集合（含引擎层/布局层/输入层/渲染层/动画层/玩法层）和媒体资产（背景图/BGM/SFX/UI 面板），并生成可直接执行的 scaffold 命令。
+description: 开发前从远端技能库发现候选，按意图、引擎、触发词和能力匹配；选定精确版本后下载技能及依赖。普通技能与 Atom 均可发现，不依赖本地安装目录。已锁定技能仍由当前执行锁约束。
 triggers: 构建新游戏项目, 选择 skill, 查找可用组件, 3D项目搭建, Three.js项目, Phaser项目
 compatibility: agent,opencode
 ---
@@ -13,6 +13,28 @@ compatibility: agent,opencode
 
 ---
 
+## 默认流程：远端发现 → 精确选择 → 按需下载
+
+`skills match` 默认查询当前身份有权访问的远端技能元数据，不依赖本地技能目录，也不会下载所有正文：
+
+```bash
+playcraft skills match --intent "military,merge,base-building,strategy,island,battle" --engine threejs --json > /tmp/skills-match.json
+```
+
+候选包含 `skillRef`、`skillVersionId`、`version`、`artifactHash`、名称、描述、引擎、能力与匹配词。依据任务选择候选，再提交原精确引用，不能重新取最新版：
+
+```bash
+playcraft skills prepare --from-match /tmp/skills-match.json --skills "<匹配结果中的namespace/slug>" --json
+```
+
+- 选择阶段复验权限、引擎和硬依赖，生成独立选择锁；准备阶段只下载该锁的精确制品，校验后存入 `.playcraft/skill-selections/<selectionId>/`，相同选择可复用已校验缓存。
+- 在云端工程会话中，`prepare` 下载校验成功后默认返回 `activation_requested` / `executionReady: false`。请正常结束本回合，不要执行准备副本或重复申请同一接续；平台等待当前回合及其他原生执行结束后，在同一会话的新回合激活精确技能、读取新锁正文并继续原任务，保留已有修改。当前回合的锁始终不变。
+- `already_active` 表示这些精确技能已在当前锁中启用且满足本回合的执行要求，不会重复启动新回合；使用当前锁中的冻结路径。需要独占执行的技能若尚未获得本回合授权，仍会安排独占后续回合。需要只下载时使用 `--prepare-only`。本地无云端执行代理时仍返回 `prepared_requires_activation`，不会自行启动对话。
+- 激活保留原有技能及版本，遇到同引用不同修订、用户中途改锁、工程改绑定或权限撤回会明确失败，不会换最新版重试。来源回合取消、失败、结果未知或已有新的用户回合时，不自动重放原任务。
+- 当前可执行技能可用 `playcraft skills search --query "<关键词>" --json` 或 `playcraft skills match --installed --intent "<关键词>" --json` 查询，只返回当前锁内已启用的技能。普通技能无需 Atom manifest，使用前读取返回的冻结 `path`。
+- 远端失败须报告真实失败，不能退回目录扫描，也不能把失败当作没有匹配。沙箱自动复用当前执行身份；本地使用已登录的平台环境。不要索取或输出控制凭据。
+- 只有确实在本地编写 Atom 库时，才显式使用 `match --local` 或 `--skills-dir`。下文旧目录工具仅适用于这一场景，不能用于绕过运行时技能锁。
+
 ## 按场景选择命令
 
 | 你的场景                    | 推荐命令             | 说明                               |
@@ -33,10 +55,10 @@ compatibility: agent,opencode
 
 ```bash
 # 自动推断引擎
-playcraft skills match --intent "<关键词,逗号分隔>" --json
+playcraft skills match --local --intent "<关键词,逗号分隔>" --json
 
 # 指定引擎
-playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
+playcraft skills match --local --engine <threejs|phaser> --intent "<关键词>" --json
 ```
 
 **适用时机**：你已经知道要做什么类型的游戏，需要一次性获取完整的技术栈推荐。
@@ -51,13 +73,13 @@ playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
 
 ```bash
 # 三消游戏
-playcraft skills match --intent "match3,grid,tile,eliminate" --json
+playcraft skills match --local --intent "match3,grid,tile,eliminate" --json
 
 # 麻将收集消除
-playcraft skills match --intent "mahjong,tile,match,stacking,puzzle" --json
+playcraft skills match --local --intent "mahjong,tile,match,stacking,puzzle" --json
 
 # Three.js 3D 棋盘
-playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+playcraft skills match --local --engine threejs --intent "board,3d,path,animation" --json
 ```
 
 ---

package/project-template-v2/.claude/skills/playcraft-skill-recommender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-skill-recommender
-description: 构建项目前的 Skill 推荐与脚手架工具。在开始任何新游戏项目前必须先调用，根据引擎（threejs/phaser）和意图关键词，自动推荐完整的代码 skill 集合（含引擎层/布局层/输入层/渲染层/动画层/玩法层）和媒体资产（背景图/BGM/SFX/UI 面板），并生成可直接执行的 scaffold 命令。
+description: 开发前从远端技能库发现候选，按意图、引擎、触发词和能力匹配；选定精确版本后下载技能及依赖。普通技能与 Atom 均可发现，不依赖本地安装目录。已锁定技能仍由当前执行锁约束。
 triggers: 构建新游戏项目, 选择 skill, 查找可用组件, 3D项目搭建, Three.js项目, Phaser项目
 compatibility: agent,opencode
 ---
@@ -13,6 +13,28 @@ compatibility: agent,opencode
 
 ---
 
+## 默认流程：远端发现 → 精确选择 → 按需下载
+
+`skills match` 默认查询当前身份有权访问的远端技能元数据，不依赖本地技能目录，也不会下载所有正文：
+
+```bash
+playcraft skills match --intent "military,merge,base-building,strategy,island,battle" --engine threejs --json > /tmp/skills-match.json
+```
+
+候选包含 `skillRef`、`skillVersionId`、`version`、`artifactHash`、名称、描述、引擎、能力与匹配词。依据任务选择候选，再提交原精确引用，不能重新取最新版：
+
+```bash
+playcraft skills prepare --from-match /tmp/skills-match.json --skills "<匹配结果中的namespace/slug>" --json
+```
+
+- 选择阶段复验权限、引擎和硬依赖，生成独立选择锁；准备阶段只下载该锁的精确制品，校验后存入 `.playcraft/skill-selections/<selectionId>/`，相同选择可复用已校验缓存。
+- 在云端工程会话中，`prepare` 下载校验成功后默认返回 `activation_requested` / `executionReady: false`。请正常结束本回合，不要执行准备副本或重复申请同一接续；平台等待当前回合及其他原生执行结束后，在同一会话的新回合激活精确技能、读取新锁正文并继续原任务，保留已有修改。当前回合的锁始终不变。
+- `already_active` 表示这些精确技能已在当前锁中启用且满足本回合的执行要求，不会重复启动新回合；使用当前锁中的冻结路径。需要独占执行的技能若尚未获得本回合授权，仍会安排独占后续回合。需要只下载时使用 `--prepare-only`。本地无云端执行代理时仍返回 `prepared_requires_activation`，不会自行启动对话。
+- 激活保留原有技能及版本，遇到同引用不同修订、用户中途改锁、工程改绑定或权限撤回会明确失败，不会换最新版重试。来源回合取消、失败、结果未知或已有新的用户回合时，不自动重放原任务。
+- 当前可执行技能可用 `playcraft skills search --query "<关键词>" --json` 或 `playcraft skills match --installed --intent "<关键词>" --json` 查询，只返回当前锁内已启用的技能。普通技能无需 Atom manifest，使用前读取返回的冻结 `path`。
+- 远端失败须报告真实失败，不能退回目录扫描，也不能把失败当作没有匹配。沙箱自动复用当前执行身份；本地使用已登录的平台环境。不要索取或输出控制凭据。
+- 只有确实在本地编写 Atom 库时，才显式使用 `match --local` 或 `--skills-dir`。下文旧目录工具仅适用于这一场景，不能用于绕过运行时技能锁。
+
 ## 按场景选择命令
 
 | 你的场景                    | 推荐命令             | 说明                                    |
@@ -35,10 +57,10 @@ compatibility: agent,opencode
 
 ```bash
 # 自动推断引擎
-playcraft skills match --intent "<关键词,逗号分隔>" --json
+playcraft skills match --local --intent "<关键词,逗号分隔>" --json
 
 # 指定引擎
-playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
+playcraft skills match --local --engine <threejs|phaser> --intent "<关键词>" --json
 ```
 
 **适用时机**：你已经知道要做什么类型的游戏，需要一次性获取完整的技术栈推荐。
@@ -53,13 +75,13 @@ playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
 
 ```bash
 # 三消游戏
-playcraft skills match --intent "match3,grid,tile,eliminate" --json
+playcraft skills match --local --intent "match3,grid,tile,eliminate" --json
 
 # 麻将收集消除
-playcraft skills match --intent "mahjong,tile,match,stacking,puzzle" --json
+playcraft skills match --local --intent "mahjong,tile,match,stacking,puzzle" --json
 
 # Three.js 3D 棋盘
-playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+playcraft skills match --local --engine threejs --intent "board,3d,path,animation" --json
 ```
 
 ---

package/project-templates/empty/gitignore

@@ -31,3 +31,4 @@ playcraft.config.json
 Thumbs.db
 .idea/
 .vscode/
+.playcraft/skill-selections/

package/project-templates/phaser/.claude/skills/playcraft-skill-recommender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-skill-recommender
-description: 构建项目前的 Skill 推荐与脚手架工具。在开始任何新游戏项目前必须先调用，根据引擎（threejs/phaser）和意图关键词，自动推荐完整的代码 skill 集合（含引擎层/布局层/输入层/渲染层/动画层/玩法层）和媒体资产（背景图/BGM/SFX/UI 面板），并生成可直接执行的 scaffold 命令。
+description: 开发前从远端技能库发现候选，按意图、引擎、触发词和能力匹配；选定精确版本后下载技能及依赖。普通技能与 Atom 均可发现，不依赖本地安装目录。已锁定技能仍由当前执行锁约束。
 triggers: 构建新游戏项目, 选择 skill, 查找可用组件, 3D项目搭建, Three.js项目, Phaser项目
 compatibility: agent,opencode
 ---
@@ -13,6 +13,28 @@ compatibility: agent,opencode
 
 ---
 
+## 默认流程：远端发现 → 精确选择 → 按需下载
+
+`skills match` 默认查询当前身份有权访问的远端技能元数据，不依赖本地技能目录，也不会下载所有正文：
+
+```bash
+playcraft skills match --intent "military,merge,base-building,strategy,island,battle" --engine threejs --json > /tmp/skills-match.json
+```
+
+候选包含 `skillRef`、`skillVersionId`、`version`、`artifactHash`、名称、描述、引擎、能力与匹配词。依据任务选择候选，再提交原精确引用，不能重新取最新版：
+
+```bash
+playcraft skills prepare --from-match /tmp/skills-match.json --skills "<匹配结果中的namespace/slug>" --json
+```
+
+- 选择阶段复验权限、引擎和硬依赖，生成独立选择锁；准备阶段只下载该锁的精确制品，校验后存入 `.playcraft/skill-selections/<selectionId>/`，相同选择可复用已校验缓存。
+- 在云端工程会话中，`prepare` 下载校验成功后默认返回 `activation_requested` / `executionReady: false`。请正常结束本回合，不要执行准备副本或重复申请同一接续；平台等待当前回合及其他原生执行结束后，在同一会话的新回合激活精确技能、读取新锁正文并继续原任务，保留已有修改。当前回合的锁始终不变。
+- `already_active` 表示这些精确技能已在当前锁中启用且满足本回合的执行要求，不会重复启动新回合；使用当前锁中的冻结路径。需要独占执行的技能若尚未获得本回合授权，仍会安排独占后续回合。需要只下载时使用 `--prepare-only`。本地无云端执行代理时仍返回 `prepared_requires_activation`，不会自行启动对话。
+- 激活保留原有技能及版本，遇到同引用不同修订、用户中途改锁、工程改绑定或权限撤回会明确失败，不会换最新版重试。来源回合取消、失败、结果未知或已有新的用户回合时，不自动重放原任务。
+- 当前可执行技能可用 `playcraft skills search --query "<关键词>" --json` 或 `playcraft skills match --installed --intent "<关键词>" --json` 查询，只返回当前锁内已启用的技能。普通技能无需 Atom manifest，使用前读取返回的冻结 `path`。
+- 远端失败须报告真实失败，不能退回目录扫描，也不能把失败当作没有匹配。沙箱自动复用当前执行身份；本地使用已登录的平台环境。不要索取或输出控制凭据。
+- 只有确实在本地编写 Atom 库时，才显式使用 `match --local` 或 `--skills-dir`。下文旧目录工具仅适用于这一场景，不能用于绕过运行时技能锁。
+
 ## 按场景选择命令
 
 | 你的场景                    | 推荐命令             | 说明                               |
@@ -33,10 +55,10 @@ compatibility: agent,opencode
 
 ```bash
 # 自动推断引擎
-playcraft skills match --intent "<关键词,逗号分隔>" --json
+playcraft skills match --local --intent "<关键词,逗号分隔>" --json
 
 # 指定引擎
-playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
+playcraft skills match --local --engine <threejs|phaser> --intent "<关键词>" --json
 ```
 
 **适用时机**：你已经知道要做什么类型的游戏，需要一次性获取完整的技术栈推荐。
@@ -51,13 +73,13 @@ playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
 
 ```bash
 # 三消游戏
-playcraft skills match --intent "match3,grid,tile,eliminate" --json
+playcraft skills match --local --intent "match3,grid,tile,eliminate" --json
 
 # 麻将收集消除
-playcraft skills match --intent "mahjong,tile,match,stacking,puzzle" --json
+playcraft skills match --local --intent "mahjong,tile,match,stacking,puzzle" --json
 
 # Three.js 3D 棋盘
-playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+playcraft skills match --local --engine threejs --intent "board,3d,path,animation" --json
 ```
 
 ---

package/project-templates/threejs/.claude/skills/playcraft-skill-recommender/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-skill-recommender
-description: 构建项目前的 Skill 推荐与脚手架工具。在开始任何新游戏项目前必须先调用，根据引擎（threejs/phaser）和意图关键词，自动推荐完整的代码 skill 集合（含引擎层/布局层/输入层/渲染层/动画层/玩法层）和媒体资产（背景图/BGM/SFX/UI 面板），并生成可直接执行的 scaffold 命令。
+description: 开发前从远端技能库发现候选，按意图、引擎、触发词和能力匹配；选定精确版本后下载技能及依赖。普通技能与 Atom 均可发现，不依赖本地安装目录。已锁定技能仍由当前执行锁约束。
 triggers: 构建新游戏项目, 选择 skill, 查找可用组件, 3D项目搭建, Three.js项目, Phaser项目
 compatibility: agent,opencode
 ---
@@ -13,6 +13,28 @@ compatibility: agent,opencode
 
 ---
 
+## 默认流程：远端发现 → 精确选择 → 按需下载
+
+`skills match` 默认查询当前身份有权访问的远端技能元数据，不依赖本地技能目录，也不会下载所有正文：
+
+```bash
+playcraft skills match --intent "military,merge,base-building,strategy,island,battle" --engine threejs --json > /tmp/skills-match.json
+```
+
+候选包含 `skillRef`、`skillVersionId`、`version`、`artifactHash`、名称、描述、引擎、能力与匹配词。依据任务选择候选，再提交原精确引用，不能重新取最新版：
+
+```bash
+playcraft skills prepare --from-match /tmp/skills-match.json --skills "<匹配结果中的namespace/slug>" --json
+```
+
+- 选择阶段复验权限、引擎和硬依赖，生成独立选择锁；准备阶段只下载该锁的精确制品，校验后存入 `.playcraft/skill-selections/<selectionId>/`，相同选择可复用已校验缓存。
+- 在云端工程会话中，`prepare` 下载校验成功后默认返回 `activation_requested` / `executionReady: false`。请正常结束本回合，不要执行准备副本或重复申请同一接续；平台等待当前回合及其他原生执行结束后，在同一会话的新回合激活精确技能、读取新锁正文并继续原任务，保留已有修改。当前回合的锁始终不变。
+- `already_active` 表示这些精确技能已在当前锁中启用且满足本回合的执行要求，不会重复启动新回合；使用当前锁中的冻结路径。需要独占执行的技能若尚未获得本回合授权，仍会安排独占后续回合。需要只下载时使用 `--prepare-only`。本地无云端执行代理时仍返回 `prepared_requires_activation`，不会自行启动对话。
+- 激活保留原有技能及版本，遇到同引用不同修订、用户中途改锁、工程改绑定或权限撤回会明确失败，不会换最新版重试。来源回合取消、失败、结果未知或已有新的用户回合时，不自动重放原任务。
+- 当前可执行技能可用 `playcraft skills search --query "<关键词>" --json` 或 `playcraft skills match --installed --intent "<关键词>" --json` 查询，只返回当前锁内已启用的技能。普通技能无需 Atom manifest，使用前读取返回的冻结 `path`。
+- 远端失败须报告真实失败，不能退回目录扫描，也不能把失败当作没有匹配。沙箱自动复用当前执行身份；本地使用已登录的平台环境。不要索取或输出控制凭据。
+- 只有确实在本地编写 Atom 库时，才显式使用 `match --local` 或 `--skills-dir`。下文旧目录工具仅适用于这一场景，不能用于绕过运行时技能锁。
+
 ## 按场景选择命令
 
 | 你的场景                    | 推荐命令             | 说明                               |
@@ -33,10 +55,10 @@ compatibility: agent,opencode
 
 ```bash
 # 自动推断引擎
-playcraft skills match --intent "<关键词,逗号分隔>" --json
+playcraft skills match --local --intent "<关键词,逗号分隔>" --json
 
 # 指定引擎
-playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
+playcraft skills match --local --engine <threejs|phaser> --intent "<关键词>" --json
 ```
 
 **适用时机**：你已经知道要做什么类型的游戏，需要一次性获取完整的技术栈推荐。
@@ -51,13 +73,13 @@ playcraft skills match --engine <threejs|phaser> --intent "<关键词>" --json
 
 ```bash
 # 三消游戏
-playcraft skills match --intent "match3,grid,tile,eliminate" --json
+playcraft skills match --local --intent "match3,grid,tile,eliminate" --json
 
 # 麻将收集消除
-playcraft skills match --intent "mahjong,tile,match,stacking,puzzle" --json
+playcraft skills match --local --intent "mahjong,tile,match,stacking,puzzle" --json
 
 # Three.js 3D 棋盘
-playcraft skills match --engine threejs --intent "board,3d,path,animation" --json
+playcraft skills match --local --engine threejs --intent "board,3d,path,animation" --json
 ```
 
 ---