@playcraft/cli 0.0.39 → 0.0.41

package/dist/commands/skills.js

@@ -0,0 +1,1379 @@
+/**
+ * playcraft skills <command>
+ *
+ * 开发时 Skill 发现与脚手架工具。
+ * 解决问题：Agent 在构建特定类型项目（如 Three.js 3D 棋盘游戏）时，
+ * 不知道应该用哪些 skill 文件，导致重复造轮子或遗漏已有实现。
+ *
+ * 子命令：
+ *   list      列出所有可用 skill（支持按 engine/category/tag 过滤）
+ *   match     按引擎+意图推荐完整 skill 集合（含依赖图遍历）
+ *   scaffold  将指定 skill 的 ref 文件复制到目标项目目录
+ *
+ * Skill 目录发现优先级：
+ *   1. --skills-dir 参数
+ *   2. AGENT_SKILLS_PATHS 环境变量（逗号分隔）
+ *   3. <cwd>/node_modules/@playcraft/skills/skills
+ *   4. <CLI 自身>/../../skills/skills（monorepo 开发时）
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSkillRefsFromAtomPlanProject, validateAtomPlanProject } from '../atom-plan/validate-atom-plan.js';
+import { loadConfig } from '../config.js';
+const KNOWN_ENGINES = ['phaser', 'threejs'];
+const SCORE_THRESHOLD_FULL = 8;
+const SCORE_THRESHOLD_DISCOVERY = 6;
+/** 引擎等非媒体类备选最多展示条数 */
+export const MAX_ALTERNATIVES_PER_CLASS = 3;
+/** 媒体角色（BGM / 背景 / 面板等）每类备选最多展示条数 */
+export const MAX_MEDIA_ALTERNATIVES_PER_CLASS = 10;
+export function capAlternatives(ranked, limit = MAX_ALTERNATIVES_PER_CLASS) {
+    return { items: ranked.slice(0, limit), total: ranked.length };
+}
+/** 泛化 intent 词：单独命中时不应拉起大量无关 gameplay / 组件 */
+const GENERIC_INTENT_TAGS = new Set([
+    'grid',
+    'tile',
+    'tiles',
+    'casual',
+    'puzzle',
+    'gameplay',
+    'core',
+    'game',
+    'rules',
+    'algorithm',
+    'logic',
+    'ui',
+    'component',
+    'sprite',
+    'image',
+    'audio',
+    'validator',
+    'balance',
+    'quality',
+    'compliance',
+    'ux',
+    'processing',
+    'pipeline',
+    'sheet',
+    'atlas',
+    'animation',
+    'anim',
+    'render',
+    '2d',
+    '3d',
+]);
+function isSpecificIntentTag(tag) {
+    return !GENERIC_INTENT_TAGS.has(tag.toLowerCase());
+}
+/** 用户 intent 词 → 技能库常用 tags / 角色（如 mahjong → tile 贴图） */
+const INTENT_TAG_ALIASES = {
+    mahjong: ['tile', 'tiles', '牌面'],
+    麻将: ['tile', 'tiles', 'mahjong', '牌面'],
+    solitaire: ['solitaire', 'klondike', 'card'],
+};
+const ANCHOR_MEDIA_ROLE_LABELS = {
+    tileTextureSet: { label: '牌面/瓦片贴图组', layer: '视觉资产层' },
+    backgroundTexture: { label: '场景背景贴图', layer: '背景图层' },
+    levelDataPack: { label: '关卡数据包', layer: '配置层' },
+};
+export function expandIntentTags(intentTags) {
+    const out = new Set();
+    for (const raw of intentTags) {
+        const t = raw.trim();
+        if (!t)
+            continue;
+        out.add(t);
+        out.add(t.toLowerCase());
+        for (const alias of INTENT_TAG_ALIASES[t.toLowerCase()] ?? []) {
+            out.add(alias);
+        }
+    }
+    return [...out];
+}
+export function entryMatchesIntentTag(entry, tag) {
+    const { manifest } = entry;
+    const t = tag.toLowerCase();
+    if (manifest.tags?.some((x) => x.toLowerCase() === t || x.toLowerCase().includes(t)))
+        return true;
+    if (manifest.atomId.toLowerCase().includes(t))
+        return true;
+    // 中文短词不做 label 子串匹配，避免「牌」命中「翻牌」等误伤
+    if (tag.length >= 2 && /[\u4e00-\u9fff]/.test(tag) && manifest.label.zh.includes(tag))
+        return true;
+    if (manifest.label.en.toLowerCase().includes(t))
+        return true;
+    const gt = getGameplayType(manifest);
+    if (gt && (gt.toLowerCase() === t || gt.toLowerCase().includes(t)))
+        return true;
+    return false;
+}
+function countIntentMatches(entry, intentTags) {
+    let n = 0;
+    for (const tag of intentTags) {
+        if (entryMatchesIntentTag(entry, tag))
+            n++;
+    }
+    return n;
+}
+function passesGameplayIntentFilter(entry, intentTags) {
+    if (entry.manifest.category !== 'gameplay')
+        return true;
+    const gt = getGameplayType(entry.manifest);
+    if (gt && intentTags.some((t) => t.toLowerCase() === gt.toLowerCase()))
+        return true;
+    return intentTags.some((t) => isSpecificIntentTag(t) && entryMatchesIntentTag(entry, t));
+}
+/** 无直接 atom 命中、但通过 INTENT_TAG_ALIASES 关联到技能的 intent 词 */
+export function findIntentAliasOnlyTags(entries, intentTags) {
+    const aliasOnly = [];
+    for (const raw of intentTags) {
+        const t = raw.trim();
+        if (!t)
+            continue;
+        if (entries.some((e) => entryMatchesIntentTag(e, t)))
+            continue;
+        const aliases = INTENT_TAG_ALIASES[t.toLowerCase()] ?? [];
+        if (aliases.some((a) => entries.some((e) => entryMatchesIntentTag(e, a))))
+            aliasOnly.push(t);
+    }
+    return aliasOnly;
+}
+/** 用户写了但未命中任何 atom 的 intent 词（直连与别名均无匹配） */
+export function findUnresolvedIntentTags(entries, intentTags) {
+    const unresolved = [];
+    for (const raw of intentTags) {
+        const t = raw.trim();
+        if (!t)
+            continue;
+        if (entries.some((e) => entryMatchesIntentTag(e, t)))
+            continue;
+        const aliases = INTENT_TAG_ALIASES[t.toLowerCase()] ?? [];
+        if (aliases.some((a) => entries.some((e) => entryMatchesIntentTag(e, a))))
+            continue;
+        unresolved.push(t);
+    }
+    return unresolved;
+}
+// ─── 媒体/配置通用角色（引擎无关，每个可玩广告都需要）──────────────────────
+/**
+ * 任何游戏都需要这些 bindingRole 对应的媒体资产。
+ * 格式：role → { label, layer }
+ */
+const UNIVERSAL_MEDIA_ROLES = {
+    // 音频
+    bgMusic: { label: '背景音乐（BGM）', layer: '音频层' },
+    sfxClick: { label: '点击/消除音效', layer: '音频层' },
+    sfxAppear: { label: '路径出现音效', layer: '音频层' },
+    sfxSuccess: { label: '成功音效', layer: '音频层' },
+    sfxFail: { label: '关卡失败音效', layer: '音频层' },
+    sfxLose: { label: '扣命音效', layer: '音频层' },
+    sfxMistake: { label: '错误/被阻挡音效', layer: '音频层' },
+    sfxArrowMoveError: { label: '箭头无效移动音效', layer: '音频层' },
+    sfxButtonClick: { label: 'UI 按钮点击音效', layer: '音频层' },
+    sfxWinAnim: { label: '胜利动画音效', layer: '音频层' },
+    // 图像：结果面板 & UI 元素
+    successFeedbackPanel: { label: '胜利结果面板', layer: '视觉资产层' },
+    failFeedbackPanel: { label: '失败结果面板', layer: '视觉资产层' },
+    dangerFlashOverlay: { label: '危险警示闪光遮罩', layer: '视觉资产层' },
+    normalParticleAsset: { label: '普通粒子素材', layer: '视觉资产层' },
+    winParticleAsset: { label: '胜利粒子素材', layer: '视觉资产层' },
+    appLogo: { label: '应用 Logo', layer: '视觉资产层' },
+    tutorialPointer: { label: '教程手指指针', layer: '视觉资产层' },
+    clockIcon: { label: '计时器图标', layer: '视觉资产层' },
+    boardEntitySprite: { label: '棋盘实体精灵', layer: '视觉资产层' },
+    directionalIndicator: { label: '方向指示器', layer: '视觉资产层' },
+};
+// ─── 层级定义（按构建顺序排序）──────────────────────────────────────────────
+const LAYER_ORDER = {
+    '引擎层': 0,
+    '构建层': 1,
+    '布局层': 2,
+    '场景层': 3,
+    '状态层': 4,
+    '输入层': 5,
+    '渲染层': 6,
+    '动画层': 7,
+    '玩法层': 8,
+    '实体层': 9,
+    'UI层': 10,
+    '音频层': 11,
+    '视觉资产层': 12,
+    '背景图层': 13,
+    '配置层': 14,
+    '工具层': 15,
+    '其他': 99,
+};
+function getCategoryLayer(category, atomId) {
+    const id = atomId.toLowerCase();
+    if (category === 'engine')
+        return '引擎层';
+    if (category === 'build')
+        return '构建层';
+    if (category === 'layout')
+        return '布局层';
+    if (category === 'scene')
+        return '场景层';
+    if (category === 'state')
+        return '状态层';
+    if (category === 'gameplay')
+        return '玩法层';
+    if (category === 'visual' || id.includes('sprite') || id.includes('image') || id.includes('aiimage'))
+        return '实体层';
+    if (category === 'audio')
+        return '音频层';
+    if (category === 'config')
+        return '配置层';
+    if (category === 'util')
+        return '工具层';
+    // component 需要按子类型细分
+    if (id.includes('input') || id.includes('handler'))
+        return '输入层';
+    if (id.includes('render') || id.includes('renderer'))
+        return '渲染层';
+    if (id.includes('animation') || id.includes('anim'))
+        return '动画层';
+    if (id.includes('camera'))
+        return '场景层';
+    if (id.includes('tray') || id.includes('ui') || id.includes('bar') || id.includes('panel'))
+        return 'UI层';
+    return 'UI层'; // component 默认 UI 层
+}
+// ─── Skill 目录发现 ──────────────────────────────────────────────────────────
+/**
+ * 解析 skills 目录，优先级：
+ *  1. --skills-dir CLI 参数
+ *  2. playcraft.config.json 中的 skillsDir
+ *  3. AGENT_SKILLS_PATHS 环境变量（逗号分隔）
+ *  4. node_modules/@playcraft/skills/skills
+ *  5. monorepo 开发时的相对路径
+ */
+function resolveSkillsDirs(customDir, configDir) {
+    if (customDir) {
+        return [path.resolve(customDir)];
+    }
+    const dirs = [];
+    // 来自 playcraft.config.json
+    if (configDir) {
+        dirs.push(path.resolve(configDir));
+    }
+    // 来自环境变量
+    const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+    dirs.push(...envPaths);
+    // node_modules 中的 @playcraft/skills
+    const cwdModulesPath = path.join(process.cwd(), 'node_modules', '@playcraft', 'skills', 'skills');
+    if (fs.existsSync(cwdModulesPath)) {
+        dirs.push(cwdModulesPath);
+    }
+    // monorepo 开发时：CLI 包相对于 skills 包的路径
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const monoSkillsPath = path.resolve(__dirname, '..', '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(monoSkillsPath)) {
+        dirs.push(monoSkillsPath);
+    }
+    // 编译后的 dist 路径
+    const distSkillsPath = path.resolve(__dirname, '..', '..', '..', 'skills', 'skills');
+    if (fs.existsSync(distSkillsPath) && distSkillsPath !== monoSkillsPath) {
+        dirs.push(distSkillsPath);
+    }
+    return [...new Set(dirs)];
+}
+// ─── Manifest 索引器 ─────────────────────────────────────────────────────────
+function loadSkillIndex(skillsDirs) {
+    const entries = [];
+    const seen = new Set();
+    for (const dir of skillsDirs) {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            continue;
+        const subdirs = fs.readdirSync(dir, { withFileTypes: true });
+        for (const dirent of subdirs) {
+            if (!dirent.isDirectory())
+                continue;
+            const skillDir = path.join(dir, dirent.name);
+            const manifestPath = path.join(skillDir, 'manifest.json');
+            if (!fs.existsSync(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (!manifest.atomId || seen.has(manifest.atomId))
+                    continue;
+                seen.add(manifest.atomId);
+                entries.push({ atomId: manifest.atomId, dir: skillDir, manifest });
+            }
+            catch {
+                // 跳过无法解析的 manifest
+            }
+        }
+    }
+    return entries;
+}
+// ─── 推荐算法 ────────────────────────────────────────────────────────────────
+function getGameplayType(manifest) {
+    const gen = manifest['generation'];
+    return gen?.gameplayType;
+}
+function pinAtomIdToEngine(pinAtomId) {
+    if (!pinAtomId.endsWith('.aicomponent'))
+        return null;
+    const name = pinAtomId.slice(0, -'.aicomponent'.length);
+    return KNOWN_ENGINES.includes(name) ? name : null;
+}
+/**
+ * 仅按 intent 打分（discovery 相位）。不假设目标引擎。
+ */
+export function scoreSkillIntentOnly(entry, intentTags) {
+    if (intentTags.length === 0)
+        return 0;
+    const { manifest } = entry;
+    let score = 0;
+    for (const tag of intentTags) {
+        if (entryMatchesIntentTag(entry, tag))
+            score += 3;
+    }
+    const gameplayType = getGameplayType(manifest);
+    if (gameplayType && intentTags.some((t) => t.toLowerCase() === gameplayType.toLowerCase()))
+        score += 12;
+    for (const tag of intentTags) {
+        if (manifest.atomId.toLowerCase().includes(tag.toLowerCase()))
+            score += 2;
+    }
+    if (manifest.category === 'engine')
+        score += 1;
+    return score;
+}
+/**
+ * 从 discovery 相位已匹配的 skill 聚合候选引擎。
+ */
+export function inferSuggestedEngines(scored, intentTags) {
+    const totals = new Map();
+    const bump = (engine, delta, reason) => {
+        if (!KNOWN_ENGINES.includes(engine))
+            return;
+        const cur = totals.get(engine) ?? { score: 0, reasons: new Set() };
+        cur.score += delta;
+        cur.reasons.add(reason);
+        totals.set(engine, cur);
+    };
+    if (intentTags.some((t) => ['3d', 'threejs', 'three', 'board', 'path', 'webgl'].includes(t))) {
+        bump('threejs', 10, '意图标签偏 3D / Three.js');
+    }
+    if (intentTags.some((t) => ['2d', 'phaser', 'match3', 'grid', 'tile', 'canvas'].includes(t))) {
+        bump('phaser', 10, '意图标签偏 2D / Phaser');
+    }
+    for (const { entry, score } of scored) {
+        const { manifest } = entry;
+        const renderBackend = manifest['renderBackend'];
+        for (const e of renderBackend ?? []) {
+            bump(e, score * 0.5, `${entry.atomId} renderBackend`);
+        }
+        const engineVariants = manifest['engineVariants'];
+        for (const e of Object.keys(engineVariants ?? {})) {
+            bump(e, score * 0.4, `${entry.atomId} 含 ${e} 变体`);
+        }
+        for (const imp of manifest.imports ?? []) {
+            if (!imp.pinAtomId)
+                continue;
+            const eng = pinAtomIdToEngine(imp.pinAtomId);
+            if (eng)
+                bump(eng, score, `${entry.atomId} → ${imp.pinAtomId}`);
+        }
+        if (manifest.category === 'engine') {
+            const eng = pinAtomIdToEngine(manifest.atomId);
+            if (eng)
+                bump(eng, score + 5, `引擎节点 ${manifest.atomId}`);
+        }
+    }
+    const ranked = [...totals.entries()]
+        .map(([engine, { score, reasons }]) => ({
+        engine,
+        score: Math.round(score * 10) / 10,
+        reasons: [...reasons],
+    }))
+        .sort((a, b) => b.score - a.score)
+        .filter((s) => s.score > 0);
+    return capAlternatives(ranked).items;
+}
+/**
+ * 计算一个 skill 对给定 engine + intent 的匹配分数。
+ * 得分越高，越应该被推荐。
+ */
+export function scoreSkill(entry, engine, intentTags) {
+    const { manifest } = entry;
+    let score = 0;
+    // 1. 引擎精确匹配：renderBackend 或 engineVariants 中有指定引擎
+    const renderBackend = manifest['renderBackend'];
+    if (renderBackend?.includes(engine))
+        score += 15;
+    const engineVariants = manifest['engineVariants'];
+    if (engineVariants?.[engine])
+        score += 15;
+    // 2. 标签包含引擎名
+    if (manifest.tags?.includes(engine))
+        score += 8;
+    // 3. intent 标签重叠（含别名、label、atomId）
+    for (const tag of intentTags) {
+        if (entryMatchesIntentTag(entry, tag))
+            score += 3;
+    }
+    // 4. imports 中依赖该引擎的 skill
+    const importsEngine = manifest.imports?.some((imp) => imp.pinAtomId === `${engine}.aicomponent`);
+    if (importsEngine)
+        score += 5;
+    return score;
+}
+/**
+ * 按 imports 图遍历，收集 skill 的所有传递依赖（BFS）。
+ * engine-aware：当 skill 有指定引擎的 engineVariant 时，优先使用
+ * engineVariants[engine].imports 而非 manifest 顶层 imports，
+ * 避免将另一引擎的依赖（如 phaser.aicomponent）错误地拉进来。
+ */
+function collectDependencies(atomId, index, engine, visited = new Set()) {
+    if (visited.has(atomId))
+        return [];
+    visited.add(atomId);
+    const entry = index.get(atomId);
+    if (!entry)
+        return [];
+    // 如果 engineVariants[engine] 存在，使用其 imports 列表（字符串数组形式）
+    const engineVariants = entry.manifest['engineVariants'];
+    const variantImports = engineVariants?.[engine]?.imports;
+    const deps = [];
+    if (variantImports && variantImports.length > 0) {
+        // variant 的 imports 是 atomId 字符串数组
+        for (const pinId of variantImports) {
+            if (!visited.has(pinId)) {
+                deps.push(pinId);
+                deps.push(...collectDependencies(pinId, index, engine, visited));
+            }
+        }
+    }
+    else {
+        // 无 variant，使用顶层 imports
+        for (const imp of entry.manifest.imports ?? []) {
+            if (imp.pinAtomId && !visited.has(imp.pinAtomId)) {
+                deps.push(imp.pinAtomId);
+                deps.push(...collectDependencies(imp.pinAtomId, index, engine, visited));
+            }
+        }
+    }
+    return deps;
+}
+/**
+ * 从 manifest 中提取指定 engine 的 scaffold 文件列表。
+ * 优先使用 engineVariants[engine].scaffoldFiles，其次 scaffold.files。
+ */
+function getScaffoldFiles(manifest, engine) {
+    const engineVariants = manifest['engineVariants'];
+    const variantFiles = engineVariants?.[engine]?.scaffoldFiles;
+    if (variantFiles && Object.keys(variantFiles).length > 0) {
+        return Object.fromEntries(Object.entries(variantFiles).map(([k, v]) => [k, { source: v.source, mode: v.mode ?? 'full', weight: v.weight ?? 10 }]));
+    }
+    const sharedFiles = manifest['sharedFiles'];
+    const scaffoldFiles = {};
+    if (manifest.scaffold?.files) {
+        for (const [k, v] of Object.entries(manifest.scaffold.files)) {
+            const contribution = v;
+            if (contribution.source) {
+                scaffoldFiles[k] = { source: contribution.source, mode: contribution.mode ?? 'full', weight: contribution.weight ?? 10 };
+            }
+        }
+    }
+    if (sharedFiles) {
+        for (const [k, v] of Object.entries(sharedFiles)) {
+            scaffoldFiles[k] = { source: v.source, mode: v.mode ?? 'full', weight: v.weight ?? 10 };
+        }
+    }
+    return scaffoldFiles;
+}
+/** 无法推断引擎时的兜底：仅 intent 命中项，无依赖展开与 scaffold */
+function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines) {
+    const scored = entries
+        .map((entry) => ({ entry, score: scoreSkillIntentOnly(entry, intentTags) }))
+        .filter(({ score }) => score >= SCORE_THRESHOLD_DISCOVERY)
+        .sort((a, b) => b.score - a.score);
+    const items = scored.map(({ entry, score }) => {
+        const { manifest } = entry;
+        const layer = getCategoryLayer(manifest.category, manifest.atomId);
+        const gameplayType = getGameplayType(manifest);
+        const matchedTags = intentTags.filter((t) => manifest.tags?.includes(t));
+        let reason = matchedTags.length > 0 ? `标签匹配：${matchedTags.join(', ')}` : `score=${score}`;
+        if (gameplayType && intentTags.includes(gameplayType)) {
+            reason = `玩法类型 ${gameplayType} 匹配`;
+        }
+        const supportedEngines = [];
+        const renderBackend = manifest['renderBackend'];
+        if (renderBackend?.length)
+            supportedEngines.push(...renderBackend);
+        const engineVariants = manifest['engineVariants'];
+        if (engineVariants)
+            supportedEngines.push(...Object.keys(engineVariants));
+        for (const imp of manifest.imports ?? []) {
+            const eng = imp.pinAtomId ? pinAtomIdToEngine(imp.pinAtomId) : null;
+            if (eng)
+                supportedEngines.push(eng);
+        }
+        const enginesHint = [...new Set(supportedEngines.filter((e) => KNOWN_ENGINES.includes(e)))];
+        if (enginesHint.length > 0) {
+            reason += `；候选引擎：${enginesHint.join('/')}`;
+        }
+        return {
+            atomId: manifest.atomId,
+            label: manifest.label,
+            layer,
+            reason,
+            scaffoldFiles: {},
+            hasEngineVariant: false,
+            skillDir: entry.dir,
+        };
+    });
+    items.sort((a, b) => (LAYER_ORDER[a.layer] ?? 99) - (LAYER_ORDER[b.layer] ?? 99));
+    const mediaGroups = buildMediaGroups(entries, intentTags);
+    return {
+        engine: null,
+        engineSource: 'none',
+        intent: intentTags,
+        suggestedEngines,
+        items,
+        mediaGroups,
+        missingSlots: [],
+    };
+}
+/**
+ * 仅 --intent：先推断引擎，再对首选引擎做完整 match（一轮输出全部内容）。
+ */
+export function buildAutoMatchResult(entries, intentTags) {
+    const scored = entries
+        .map((entry) => ({ entry, score: scoreSkillIntentOnly(entry, intentTags) }))
+        .filter(({ score }) => score >= SCORE_THRESHOLD_DISCOVERY);
+    const suggestedEngines = inferSuggestedEngines(scored, intentTags);
+    const engine = suggestedEngines[0]?.engine;
+    if (!engine) {
+        return buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines);
+    }
+    const full = buildMatchResult(entries, engine, intentTags);
+    const gap = suggestedEngines.length > 1 ? suggestedEngines[0].score - suggestedEngines[1].score : 99;
+    return {
+        ...full,
+        engineSource: 'inferred',
+        suggestedEngines,
+        engineAmbiguous: suggestedEngines.length > 1 && gap < 5,
+    };
+}
+function selectMatchSeedAtomIds(scored, engine, intentTags) {
+    const seeds = new Set([`${engine}.aicomponent`]);
+    for (const { entry, score } of scored) {
+        const { manifest } = entry;
+        if (manifest.category === 'gameplay') {
+            if (passesGameplayIntentFilter(entry, intentTags))
+                seeds.add(entry.atomId);
+            continue;
+        }
+        if (manifest.category === 'engine')
+            continue;
+        if (['aiimage', 'aiaudio', 'aiconfig'].includes(manifest.bundleType))
+            continue;
+        const specificHits = intentTags.filter((t) => isSpecificIntentTag(t) && entryMatchesIntentTag(entry, t));
+        if (specificHits.length > 0 && score >= SCORE_THRESHOLD_FULL)
+            seeds.add(entry.atomId);
+    }
+    return seeds;
+}
+function expandSeedClosure(seedIds, indexMap, engine) {
+    const closed = new Set();
+    for (const seedId of seedIds) {
+        closed.add(seedId);
+        for (const depId of collectDependencies(seedId, indexMap, engine)) {
+            closed.add(depId);
+        }
+    }
+    return closed;
+}
+function buildItemReason(entry, engine, intentTags, score, via) {
+    const { manifest } = entry;
+    if (via === 'dependency')
+        return '传递依赖';
+    if (manifest.category === 'engine')
+        return '引擎根节点';
+    const gt = getGameplayType(manifest);
+    if (gt && intentTags.includes(gt))
+        return `玩法 ${gt}`;
+    const hasEngineVariant = !!manifest['engineVariants']?.[engine];
+    if (hasEngineVariant)
+        return `${engine} 变体`;
+    const matchedTags = intentTags.filter((t) => manifest.tags?.includes(t));
+    if (matchedTags.length > 0)
+        return `标签：${matchedTags.join(', ')}`;
+    return score !== null ? `score=${score}` : '推荐';
+}
+export function buildMatchResult(entries, engine, intentTags) {
+    const indexMap = new Map(entries.map((e) => [e.atomId, e]));
+    const scoreById = new Map();
+    const expandedIntent = expandIntentTags(intentTags);
+    const scored = entries
+        .map((entry) => {
+        const score = scoreSkill(entry, engine, expandedIntent);
+        scoreById.set(entry.atomId, score);
+        return { entry, score };
+    })
+        .filter(({ score }) => score >= SCORE_THRESHOLD_FULL)
+        .sort((a, b) => b.score - a.score);
+    const seedIds = selectMatchSeedAtomIds(scored, engine, expandedIntent);
+    const requiredIds = expandSeedClosure(seedIds, indexMap, engine);
+    const seedIdSet = seedIds;
+    const anchorEntries = [];
+    for (const id of seedIds) {
+        if (id.endsWith('.aigameplay')) {
+            const e = indexMap.get(id);
+            if (e)
+                anchorEntries.push(e);
+        }
+    }
+    const allItems = [];
+    for (const atomId of requiredIds) {
+        const entry = indexMap.get(atomId);
+        if (!entry)
+            continue;
+        const { manifest } = entry;
+        const layer = getCategoryLayer(manifest.category, manifest.atomId);
+        const scaffoldFiles = getScaffoldFiles(manifest, engine);
+        const hasEngineVariant = !!manifest['engineVariants']?.[engine];
+        const via = seedIdSet.has(atomId) ? 'seed' : 'dependency';
+        const reason = buildItemReason(entry, engine, expandedIntent, scoreById.get(atomId) ?? null, via);
+        allItems.push({
+            atomId: manifest.atomId,
+            label: manifest.label,
+            layer,
+            reason,
+            scaffoldFiles,
+            hasEngineVariant,
+            skillDir: entry.dir,
+        });
+    }
+    allItems.sort((a, b) => (LAYER_ORDER[a.layer] ?? 99) - (LAYER_ORDER[b.layer] ?? 99));
+    const mediaGroups = buildMediaGroupsForAnchors(entries, expandedIntent, anchorEntries);
+    const mediaRoles = new Set(mediaGroups.map((g) => g.role));
+    const missingSlots = [];
+    for (const entry of anchorEntries) {
+        for (const imp of entry.manifest.imports ?? []) {
+            if (!imp.matchBindingRoles?.length || imp.pinAtomId)
+                continue;
+            for (const role of imp.matchBindingRoles) {
+                const group = mediaGroups.find((g) => g.role === role);
+                if (!group?.candidates.length) {
+                    missingSlots.push(`${entry.atomId} → ${role}`);
+                }
+            }
+        }
+    }
+    return {
+        engine,
+        engineSource: 'explicit',
+        intent: intentTags,
+        items: allItems,
+        mediaGroups,
+        missingSlots,
+    };
+}
+// ─── 媒体/配置资产匹配（第二遍：引擎无关，按 bindingRole 分组）────────────
+/**
+ * 媒体 skill（aiimage / aiaudio / aiconfig）是引擎无关的，
+ * 通过 bindingRoles 和语义标签连接到游戏。
+ *
+ * 策略：
+ * 1. Role-based：收集所有声明了 bindingRoles 的媒体 skill，按 role 分组（同 role = 候选项）
+ * 2. Tag-based：背景图（tags: background）、通用 BGM 备选无 bindingRole → 按 tag 伪分组
+ * 3. 只输出 UNIVERSAL_MEDIA_ROLES 定义的角色，避免噪音
+ */
+function collectAnchorBindingRoles(anchorEntries) {
+    const roles = new Set(['background']);
+    for (const entry of anchorEntries) {
+        for (const imp of entry.manifest.imports ?? []) {
+            for (const role of imp.matchBindingRoles ?? [])
+                roles.add(role);
+        }
+    }
+    return roles;
+}
+function collectMediaRoleMap(entries) {
+    const mediaEntries = entries.filter((e) => ['aiimage', 'aiaudio', 'aiconfig'].includes(e.manifest.bundleType));
+    const roleMap = new Map();
+    for (const entry of mediaEntries) {
+        for (const role of entry.manifest.bindingRoles ?? []) {
+            if (!roleMap.has(role))
+                roleMap.set(role, []);
+            roleMap.get(role).push({
+                atomId: entry.atomId,
+                labelZh: entry.manifest.label.zh,
+                labelEn: entry.manifest.label.en,
+            });
+        }
+    }
+    const backgrounds = mediaEntries.filter((e) => !e.manifest.bindingRoles?.length && e.manifest.tags?.includes('background'));
+    if (backgrounds.length > 0) {
+        roleMap.set('background', backgrounds.map((e) => ({
+            atomId: e.atomId,
+            labelZh: e.manifest.label.zh,
+            labelEn: e.manifest.label.en,
+        })));
+    }
+    const bgmAlts = mediaEntries.filter((e) => !e.manifest.bindingRoles?.length && e.manifest.tags?.includes('bgm'));
+    if (bgmAlts.length > 0) {
+        const existing = roleMap.get('bgMusic') ?? [];
+        roleMap.set('bgMusic', [
+            ...existing,
+            ...bgmAlts.map((e) => ({
+                atomId: e.atomId,
+                labelZh: e.manifest.label.zh,
+                labelEn: e.manifest.label.en,
+            })),
+        ]);
+    }
+    return roleMap;
+}
+/** 锚定玩法 imports 声明的媒体角色 + 通用音频/面板；含 tileTextureSet 等非常规角色 */
+function buildMediaGroupsForAnchors(entries, intentTags, anchorEntries) {
+    const neededRoles = collectAnchorBindingRoles(anchorEntries);
+    const roleMap = collectMediaRoleMap(entries);
+    const groups = [];
+    const emitted = new Set();
+    const pushRole = (role, label, layer) => {
+        if (emitted.has(role))
+            return;
+        const candidates = roleMap.get(role);
+        if (!candidates?.length)
+            return;
+        groups.push(finalizeMediaGroup({ role, label, layer, candidates }, entries, intentTags));
+        emitted.add(role);
+    };
+    if (neededRoles.has('background') || neededRoles.has('backgroundTexture')) {
+        pushRole('background', '背景图（任选其一）', '背景图层');
+        pushRole('backgroundTexture', ANCHOR_MEDIA_ROLE_LABELS.backgroundTexture.label, ANCHOR_MEDIA_ROLE_LABELS.backgroundTexture.layer);
+    }
+    for (const [role, meta] of Object.entries(UNIVERSAL_MEDIA_ROLES)) {
+        if (!neededRoles.has(role))
+            continue;
+        pushRole(role, meta.label, meta.layer);
+    }
+    for (const role of neededRoles) {
+        if (emitted.has(role))
+            continue;
+        const meta = ANCHOR_MEDIA_ROLE_LABELS[role] ?? { label: role, layer: '视觉资产层' };
+        pushRole(role, meta.label, meta.layer);
+    }
+    return groups;
+}
+function rankMediaCandidates(candidates, entries, intentTags) {
+    return [...candidates].sort((a, b) => {
+        const entryA = entries.find((e) => e.atomId === a.atomId);
+        const entryB = entries.find((e) => e.atomId === b.atomId);
+        const scoreA = entryA ? countIntentMatches(entryA, intentTags) : 0;
+        const scoreB = entryB ? countIntentMatches(entryB, intentTags) : 0;
+        return scoreB - scoreA;
+    });
+}
+function finalizeMediaGroup(group, entries, intentTags) {
+    const ranked = rankMediaCandidates(group.candidates, entries, intentTags);
+    const { items, total } = capAlternatives(ranked, MAX_MEDIA_ALTERNATIVES_PER_CLASS);
+    return total > items.length ? { ...group, candidates: items, totalCandidates: total } : { ...group, candidates: items };
+}
+function buildMediaGroups(entries, intentTags) {
+    const roleMap = collectMediaRoleMap(entries);
+    const groups = [];
+    // 先加背景图（放最前面）
+    const bgCandidates = roleMap.get('background');
+    if (bgCandidates?.length) {
+        groups.push(finalizeMediaGroup({
+            role: 'background',
+            layer: '背景图层',
+            label: '背景图（任选其一）',
+            candidates: bgCandidates,
+        }, entries, intentTags));
+    }
+    // 再按 UNIVERSAL_MEDIA_ROLES 顺序输出
+    for (const [role, meta] of Object.entries(UNIVERSAL_MEDIA_ROLES)) {
+        if (role === 'background')
+            continue; // 已处理
+        const candidates = roleMap.get(role);
+        if (!candidates?.length)
+            continue;
+        groups.push(finalizeMediaGroup({ role, layer: meta.layer, label: meta.label, candidates }, entries, intentTags));
+    }
+    return groups;
+}
+// ─── 输出格式化 ──────────────────────────────────────────────────────────────
+function printMatchResult(result, verbose, entries) {
+    const { engine, intent, items, mediaGroups, engineSource } = result;
+    const unresolved = findUnresolvedIntentTags(entries, intent);
+    const aliasOnly = findIntentAliasOnlyTags(entries, intent);
+    const intentStr = intent.length > 0 ? `意图[${intent.join(', ')}]` : '';
+    const totalMedia = mediaGroups.reduce((s, g) => s + g.candidates.length, 0);
+    const codeItems = items.filter((i) => /\.(aigameplay|aicomponent|aiconfig)$/.test(i.atomId));
+    const engineLine = engineSource === 'inferred'
+        ? `engine=${engine}（自动）`
+        : engineSource === 'none'
+            ? '未选定引擎'
+            : `engine=${engine}`;
+    console.log(`\n${engineLine}${intentStr ? `  ${intentStr}` : ''}`);
+    console.log(`代码 skill ${codeItems.length} 个 · 媒体 ${mediaGroups.length} 类（${totalMedia} 候选）\n`);
+    if (result.suggestedEngines?.length && engineSource !== 'explicit') {
+        const top = result.suggestedEngines.map((s) => `${s.engine}${s.engine === engine ? '*' : ''}`).join(', ');
+        console.log(`候选引擎：${top}${result.engineAmbiguous ? '  ⚠️ 分差小，可用 --engine 覆盖' : ''}\n`);
+    }
+    for (const word of aliasOnly) {
+        const tileGroup = mediaGroups.find((g) => g.role === 'tileTextureSet');
+        if (tileGroup?.candidates.length) {
+            console.log(`ℹ️  intent「${word}」无专用 .aigameplay，已按牌面贴图（tileTextureSet）推荐\n`);
+        }
+        else {
+            console.log(`ℹ️  intent「${word}」已通过关联标签匹配相关 skill\n`);
+        }
+    }
+    for (const word of unresolved) {
+        console.log(`ℹ️  intent「${word}」未匹配到 DAG atom skill（可 --json 查看或补充仓库 skill）\n`);
+    }
+    if (engineSource === 'none') {
+        console.log(`指定 --engine 后可展开依赖与 scaffold。\n`);
+        return;
+    }
+    if (!verbose) {
+        let currentLayer = '';
+        for (const item of items) {
+            if (item.layer !== currentLayer) {
+                currentLayer = item.layer;
+                console.log(`${currentLayer}：`);
+            }
+            const sc = Object.keys(item.scaffoldFiles).length;
+            const scHint = sc > 0 ? ` · scaffold×${sc}` : '';
+            console.log(`  ${item.atomId}  ${item.label.zh}（${item.reason}）${scHint}`);
+        }
+        if (mediaGroups.length > 0) {
+            console.log('\n媒体（玩法 imports 相关）：');
+            for (const g of mediaGroups) {
+                const names = g.candidates.map((c) => c.atomId).join(' | ');
+                const more = g.totalCandidates && g.totalCandidates > g.candidates.length
+                    ? ` (+${g.totalCandidates - g.candidates.length})`
+                    : '';
+                const pick = (g.totalCandidates ?? g.candidates.length) > 1 ? '任选' : '';
+                console.log(`  ${g.label}${pick ? `（${pick}）` : ''}：${names}${more}`);
+            }
+        }
+        if (result.missingSlots.length > 0) {
+            console.log('\n⚠️ 未绑定软槽：');
+            for (const s of result.missingSlots)
+                console.log(`  - ${s}`);
+        }
+        console.log('\n加 --json 供 atom-plan；加 --verbose 查看 scaffold 明细与命令。\n');
+        return;
+    }
+    // ── verbose：完整分层列表 ──
+    let currentLayer = '';
+    for (const item of items) {
+        if (item.layer !== currentLayer) {
+            currentLayer = item.layer;
+            console.log(`  ── ${currentLayer} ──────────────────────`);
+        }
+        const variantMark = engine && item.hasEngineVariant ? ` [${engine} 变体]` : '';
+        console.log(`  • ${item.atomId}${variantMark}  ${item.label.zh}`);
+        console.log(`    ${item.reason}`);
+        const files = Object.entries(item.scaffoldFiles);
+        if (files.length > 0) {
+            for (const [dest, { source }] of files) {
+                console.log(`      ${source} → ${dest}`);
+            }
+        }
+        console.log();
+    }
+    if (mediaGroups.length > 0) {
+        console.log(`  ── 媒体资产 ──────────────────────`);
+        for (const g of mediaGroups) {
+            const names = g.candidates.map((c) => `${c.atomId}（${c.labelZh}）`).join(' / ');
+            const more = g.totalCandidates && g.totalCandidates > g.candidates.length
+                ? ` …共 ${g.totalCandidates} 个，仅列前 ${MAX_MEDIA_ALTERNATIVES_PER_CLASS}`
+                : '';
+            console.log(`  ${g.label}：${names}${more}\n`);
+        }
+    }
+    if (result.missingSlots.length > 0) {
+        console.log(`⚠️  未绑定软槽：`);
+        for (const s of result.missingSlots)
+            console.log(`   - ${s}`);
+        console.log();
+    }
+}
+function printMatchFooters(result, verbose) {
+    if (!result.engine)
+        return;
+    const codeItems = result.items.filter((i) => /\.(aigameplay|aicomponent|aiconfig)$/.test(i.atomId));
+    if (!verbose) {
+        const ids = codeItems.map((i) => i.atomId).join(',');
+        console.log(`scaffold: playcraft skills scaffold --engine ${result.engine} --atoms ${ids} --out ./game`);
+        console.log(`link:     playcraft skills link --from-atom-plan --prune  # 或 --atoms <子集>`);
+        return;
+    }
+    const atomIdList = codeItems.map((i) => i.atomId).join(',');
+    console.log(`\n💡 Scaffold：playcraft skills scaffold --engine ${result.engine} --atoms ${atomIdList} --out ./game`);
+    console.log(`🔗 Link：playcraft skills link --atoms ${atomIdList}`);
+}
+// ─── Scaffold 辅助：merge-json 模式 ──────────────────────────────────────────
+/**
+ * 深度合并两个 JSON 对象：incoming 中的新 key 追加到 existing，已有 key 保留 existing 的值。
+ * 对象类型字段（dependencies / devDependencies / compilerOptions 等）递归合并。
+ */
+function mergeJson(existing, incoming) {
+    const result = { ...existing };
+    for (const [key, inVal] of Object.entries(incoming)) {
+        if (key in result) {
+            const exVal = result[key];
+            if (exVal !== null && inVal !== null &&
+                typeof exVal === 'object' && typeof inVal === 'object' &&
+                !Array.isArray(exVal) && !Array.isArray(inVal)) {
+                result[key] = mergeJson(exVal, inVal);
+            }
+            // 已有 key 且非对象：保留 existing 的值，不覆盖
+        }
+        else {
+            result[key] = inVal;
+        }
+    }
+    return result;
+}
+// ─── Scaffold 执行器 ─────────────────────────────────────────────────────────
+function runScaffold(opts) {
+    const { entries, atomIds, engine, outDir, dryRun, force } = opts;
+    const indexMap = new Map(entries.map((e) => [e.atomId, e]));
+    let copied = 0;
+    let skipped = 0;
+    for (const atomId of atomIds) {
+        const entry = indexMap.get(atomId);
+        if (!entry) {
+            console.warn(`[warn] 未找到 skill: ${atomId}`);
+            continue;
+        }
+        const scaffoldFiles = getScaffoldFiles(entry.manifest, engine);
+        if (Object.keys(scaffoldFiles).length === 0) {
+            console.log(`[skip] ${atomId}：无 scaffold 文件`);
+            continue;
+        }
+        for (const [destRelPath, { source, mode }] of Object.entries(scaffoldFiles)) {
+            const srcPath = path.join(entry.dir, source);
+            const destPath = path.join(outDir, destRelPath);
+            if (!fs.existsSync(srcPath)) {
+                console.warn(`[warn] ${atomId}: 源文件不存在: ${srcPath}`);
+                continue;
+            }
+            const destExists = fs.existsSync(destPath);
+            // merge-json 模式：目标文件已存在时合并而非覆盖（不受 --force 影响）
+            if (mode === 'merge-json' && destExists) {
+                if (dryRun) {
+                    console.log(`[dry-run] ${source} → ${destRelPath} (merge-json)`);
+                    copied++;
+                    continue;
+                }
+                try {
+                    const existing = JSON.parse(fs.readFileSync(destPath, 'utf-8'));
+                    const incoming = JSON.parse(fs.readFileSync(srcPath, 'utf-8'));
+                    const merged = mergeJson(existing, incoming);
+                    fs.writeFileSync(destPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+                    console.log(`[merged] ${source} → ${destRelPath}`);
+                    copied++;
+                }
+                catch (e) {
+                    console.warn(`[warn] ${atomId}: merge-json 失败，回退到跳过: ${e.message}`);
+                    skipped++;
+                }
+                continue;
+            }
+            if (destExists && !force) {
+                console.log(`[skip] ${destRelPath} 已存在（使用 --force 覆盖）`);
+                skipped++;
+                continue;
+            }
+            if (dryRun) {
+                console.log(`[dry-run] ${source} → ${destRelPath}`);
+                copied++;
+                continue;
+            }
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+            fs.copyFileSync(srcPath, destPath);
+            console.log(`[copied] ${source} → ${destRelPath}`);
+            copied++;
+        }
+    }
+    console.log(`\n完成：${copied} 个文件${dryRun ? '（dry-run）' : ''}，${skipped} 个跳过。`);
+}
+// ─── 项目内 DAG Skill 软连接（IDE 自动发现）────────────────────────────────────
+const ATOM_SKILL_LINK_SUFFIXES = [
+    '.aigameplay',
+    '.aicomponent',
+    '.aiconfig',
+    '.aiimage',
+    '.aiaudio',
+    '.aivalidator',
+];
+/** 模板内静态 Skill 目录名前缀，禁止被 link/prune 覆盖 */
+const PROTECTED_SKILL_PREFIXES = ['playcraft-'];
+function isAtomSkillLinkName(name) {
+    return ATOM_SKILL_LINK_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+function isProtectedSkillDirName(name) {
+    return PROTECTED_SKILL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+ * 从 atom-plan.md 的 Atom List 表解析非空的 skillRef 列。
+ * 仅解析 `## Atom List` 与下一个 `##` 之间的 Markdown 表格。
+ */
+export function parseSkillRefsFromAtomPlan(content) {
+    const lines = content.split('\n');
+    let inAtomList = false;
+    let skillRefIdx = -1;
+    const refs = new Set();
+    for (const line of lines) {
+        if (/^##\s+Atom List\b/i.test(line)) {
+            inAtomList = true;
+            skillRefIdx = -1;
+            continue;
+        }
+        if (inAtomList && /^##\s+/.test(line))
+            break;
+        if (!inAtomList || !line.trim().startsWith('|'))
+            continue;
+        const cols = line
+            .split('|')
+            .slice(1, -1)
+            .map((c) => c.trim());
+        if (cols.length === 0)
+            continue;
+        if (skillRefIdx < 0) {
+            if (cols.includes('skillRef')) {
+                skillRefIdx = cols.indexOf('skillRef');
+            }
+            continue;
+        }
+        if (cols.every((c) => /^:?-+:?$/.test(c) || c === ''))
+            continue;
+        if (cols.includes('atomId') && cols.includes('assignTo'))
+            continue;
+        const ref = cols[skillRefIdx];
+        if (!ref || ref === '—' || ref === '-' || ref.startsWith('{{'))
+            continue;
+        refs.add(ref);
+    }
+    return [...refs];
+}
+export async function linkAtomSkillsToProject(options) {
+    const projectDir = path.resolve(options.projectDir);
+    const skillsLinkDir = path.join(projectDir, '.claude', 'skills');
+    const entryById = new Map(options.entries.map((e) => [e.atomId, e]));
+    const linked = [];
+    const skipped = [];
+    const missing = [];
+    const targetIds = new Set(options.atomIds.map((id) => id.trim()).filter(Boolean));
+    if (!options.dryRun) {
+        await fs.promises.mkdir(skillsLinkDir, { recursive: true });
+    }
+    for (const atomId of targetIds) {
+        const entry = entryById.get(atomId);
+        if (!entry) {
+            missing.push(atomId);
+            continue;
+        }
+        const linkPath = path.join(skillsLinkDir, atomId);
+        if (isProtectedSkillDirName(atomId)) {
+            skipped.push(atomId);
+            continue;
+        }
+        const skillMd = path.join(entry.dir, 'SKILL.md');
+        if (!fs.existsSync(skillMd)) {
+            missing.push(`${atomId} (no SKILL.md)`);
+            continue;
+        }
+        const relTarget = path.relative(path.dirname(linkPath), entry.dir);
+        if (fs.existsSync(linkPath)) {
+            const stat = fs.lstatSync(linkPath);
+            if (stat.isSymbolicLink()) {
+                const current = fs.readlinkSync(linkPath);
+                const resolvedCurrent = path.isAbsolute(current)
+                    ? current
+                    : path.resolve(path.dirname(linkPath), current);
+                if (path.resolve(resolvedCurrent) === path.resolve(entry.dir) && !options.force) {
+                    skipped.push(atomId);
+                    continue;
+                }
+                if (!options.dryRun && options.force) {
+                    await fs.promises.unlink(linkPath);
+                }
+            }
+            else if (!options.force) {
+                skipped.push(`${atomId} (exists, not symlink)`);
+                continue;
+            }
+            else if (!options.dryRun) {
+                await fs.promises.rm(linkPath, { recursive: true, force: true });
+            }
+        }
+        if (options.dryRun) {
+            console.log(`[dry-run] ${linkPath} → ${entry.dir}`);
+            linked.push(atomId);
+            continue;
+        }
+        await fs.promises.symlink(relTarget, linkPath, 'dir');
+        linked.push(atomId);
+    }
+    const pruned = [];
+    if (options.prune && fs.existsSync(skillsLinkDir)) {
+        const children = await fs.promises.readdir(skillsLinkDir, { withFileTypes: true });
+        for (const child of children) {
+            if (!child.isSymbolicLink() || !isAtomSkillLinkName(child.name))
+                continue;
+            if (targetIds.has(child.name) || isProtectedSkillDirName(child.name))
+                continue;
+            const linkPath = path.join(skillsLinkDir, child.name);
+            if (options.dryRun) {
+                console.log(`[dry-run prune] ${linkPath}`);
+            }
+            else {
+                await fs.promises.unlink(linkPath);
+            }
+            pruned.push(child.name);
+        }
+    }
+    if (!options.dryRun) {
+        const manifestPath = path.join(skillsLinkDir, '.playcraft-dag-links.json');
+        await fs.promises.writeFile(manifestPath, JSON.stringify({
+            linkedAt: new Date().toISOString(),
+            atomIds: [...targetIds],
+            linked,
+            skillsDirs: [...new Set(options.entries.map((e) => path.dirname(e.dir)))],
+        }, null, 2) + '\n', 'utf-8');
+    }
+    return { linked, skipped, pruned, missing };
+}
+// ─── CLI 注册 ────────────────────────────────────────────────────────────────
+export function registerSkillsCommands(program) {
+    const skills = program
+        .command('skills')
+        .description('开发时 Skill 发现与脚手架工具（按 engine/intent 推荐 skill 集合，或将 ref 文件复制到项目）');
+    // 公共选项：skills 目录
+    const addSkillsDirOption = (cmd) => cmd.option('--skills-dir <path>', '指定 skills 目录路径（默认自动发现）');
+    // ── list ──────────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('list')
+        .description('列出所有可用 skill（支持按 engine/category/tag 过滤）')
+        .option('--engine <name>', '只显示支持该引擎的 skill（如 threejs/phaser）')
+        .option('--category <name>', '按 category 过滤（engine/layout/component/gameplay/visual/audio/config...）')
+        .option('--tag <tag>', '按标签过滤')
+        .option('--json', '输出 JSON 格式')).action(async (opts) => {
+        const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+        const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+        if (dirs.length === 0) {
+            console.error('未找到 skills 目录。请通过 --skills-dir 指定、在 playcraft.config.json 中配置 skillsDir，或设置 AGENT_SKILLS_PATHS 环境变量。');
+            process.exit(1);
+        }
+        let entries = loadSkillIndex(dirs);
+        if (opts.engine) {
+            entries = entries.filter((e) => {
+                const renderBackend = e.manifest['renderBackend'];
+                const engineVariants = e.manifest['engineVariants'];
+                return renderBackend?.includes(opts.engine) || !!engineVariants?.[opts.engine] || e.manifest.tags?.includes(opts.engine);
+            });
+        }
+        if (opts.category) {
+            entries = entries.filter((e) => e.manifest.category === opts.category);
+        }
+        if (opts.tag) {
+            entries = entries.filter((e) => e.manifest.tags?.includes(opts.tag));
+        }
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(entries.map((e) => ({
+                atomId: e.atomId,
+                category: e.manifest.category,
+                label: e.manifest.label,
+                tags: e.manifest.tags,
+                bindingRoles: e.manifest.bindingRoles,
+                dir: e.dir,
+            })), null, 2) + '\n');
+            return;
+        }
+        console.log(`\n共 ${entries.length} 个 skill:\n`);
+        for (const e of entries) {
+            const renderBackend = e.manifest['renderBackend'];
+            const engines = renderBackend ? ` [${renderBackend.join('/')}]` : '';
+            console.log(`  ${e.atomId}${engines}`);
+            console.log(`    ${e.manifest.label.zh} | ${e.manifest.category} | tags: ${e.manifest.tags?.join(', ')}`);
+        }
+        console.log();
+    });
+    // ── match ─────────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('match')
+        .description('按 intent 推荐完整 skill 集合（含依赖与 scaffold）；省略 --engine 时自动从 intent 推断引擎')
+        .option('--engine <name>', '目标引擎（threejs / phaser）；省略则由 --intent 自动推断')
+        .option('--intent <tags>', '意图关键词，逗号分隔（如 board,3d,path,animation）', '')
+        .option('--json', '输出 JSON 格式')
+        .option('--verbose', '输出 scaffold 明细与完整媒体/命令提示')).action(async (opts) => {
+        const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+        const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+        if (dirs.length === 0) {
+            console.error('未找到 skills 目录。请通过 --skills-dir 指定、在 playcraft.config.json 中配置 skillsDir，或设置 AGENT_SKILLS_PATHS 环境变量。');
+            process.exit(1);
+        }
+        const entries = loadSkillIndex(dirs);
+        const intentTags = opts.intent
+            ? opts.intent.split(',').map((t) => t.trim()).filter(Boolean)
+            : [];
+        if (!opts.engine && intentTags.length === 0) {
+            console.error('请至少指定 --intent 或 --engine。\n' +
+                '  示例：playcraft skills match --intent "match3,grid" --json\n' +
+                '  示例：playcraft skills match --engine phaser --intent "match3,grid" --json');
+            process.exit(1);
+        }
+        const result = opts.engine
+            ? buildMatchResult(entries, opts.engine, intentTags)
+            : buildAutoMatchResult(entries, intentTags);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            return;
+        }
+        printMatchResult(result, !!opts.verbose, entries);
+        printMatchFooters(result, !!opts.verbose);
+        if (opts.verbose)
+            console.log();
+    });
+    // ── scaffold ──────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('scaffold')
+        .description('将指定 skill 的 ref 文件复制到目标项目目录')
+        .requiredOption('--engine <name>', '目标引擎（决定使用哪个 engineVariant 的文件）')
+        .requiredOption('--atoms <ids>', 'skill atomId 列表，逗号分隔（如 grid_board_layout.aicomponent,camera_controller_3d.aicomponent）')
+        .option('--out <dir>', '输出目录（默认当前工作目录）', process.cwd())
+        .option('--dry-run', '只打印要复制的文件，不实际执行')
+        .option('--force', '覆盖已存在的文件')).action(async (opts) => {
+        const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+        const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+        if (dirs.length === 0) {
+            console.error('未找到 skills 目录。请通过 --skills-dir 指定、在 playcraft.config.json 中配置 skillsDir，或设置 AGENT_SKILLS_PATHS 环境变量。');
+            process.exit(1);
+        }
+        const entries = loadSkillIndex(dirs);
+        const atomIds = opts.atoms.split(',').map((s) => s.trim()).filter(Boolean);
+        runScaffold({
+            entries,
+            atomIds,
+            engine: opts.engine,
+            outDir: path.resolve(opts.out),
+            dryRun: !!opts.dryRun,
+            force: !!opts.force,
+        });
+    });
+    // ── link ──────────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('link')
+        .description('将 DAG Atom Skill 软连接到 .claude/skills/<atomId>/；下游优先读项目内路径，playcraft skills read 仅作断链兜底（不替代 scaffold）')
+        .option('--atoms <ids>', 'atomId 列表，逗号分隔')
+        .option('--from-atom-plan', '从 docs/atom-plan.md 的 Atom List 解析 skillRef 列')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--prune', '移除 .claude/skills/ 下不在本次列表中的 DAG 软连接')
+        .option('--dry-run', '只打印将创建/删除的软连接')
+        .option('--force', '覆盖已存在的软连接或同名非链接目录')).action(async (opts) => {
+        const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+        const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+        if (dirs.length === 0) {
+            console.error('未找到 skills 目录。请通过 --skills-dir 指定、在 playcraft.config.json 中配置 skillsDir，或设置 AGENT_SKILLS_PATHS 环境变量。');
+            process.exit(1);
+        }
+        const entries = loadSkillIndex(dirs);
+        let atomIds = [];
+        if (opts.fromAtomPlan) {
+            atomIds = parseSkillRefsFromAtomPlanProject(opts.projectDir);
+            if (atomIds.length === 0) {
+                console.error('未找到 docs/atom-plan.json（或 atom-plan.md）中的非空 skillRef');
+                process.exit(1);
+            }
+        }
+        if (opts.atoms) {
+            atomIds.push(...opts.atoms.split(',').map((s) => s.trim()).filter(Boolean));
+        }
+        atomIds = [...new Set(atomIds)];
+        if (atomIds.length === 0) {
+            console.error('请指定 --atoms <id1,id2> 或 --from-atom-plan（且 atom-plan 中含非空 skillRef）');
+            process.exit(1);
+        }
+        const result = await linkAtomSkillsToProject({
+            projectDir: opts.projectDir,
+            atomIds,
+            entries,
+            dryRun: !!opts.dryRun,
+            force: !!opts.force,
+            prune: !!opts.prune,
+        });
+        console.log(`\n🔗 DAG Skill 软连接 → ${path.join(path.resolve(opts.projectDir), '.claude', 'skills')}`);
+        if (result.linked.length)
+            console.log(`   已链接 (${result.linked.length})：${result.linked.join(', ')}`);
+        if (result.skipped.length)
+            console.log(`   跳过 (${result.skipped.length})：${result.skipped.join(', ')}`);
+        if (result.missing.length)
+            console.log(`   未找到 (${result.missing.length})：${result.missing.join(', ')}`);
+        if (result.pruned.length)
+            console.log(`   已 prune (${result.pruned.length})：${result.pruned.join(', ')}`);
+        if (result.missing.length > 0)
+            process.exit(1);
+    });
+    // ── validate-atom-plan ────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('validate-atom-plan')
+        .description('校验 docs/atom-plan.json 中 skillRef 均存在于 skills 库，且落在 skillsMatch.items 内')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--allow-markdown', '若无 JSON 则回退校验 atom-plan.md（不推荐）')
+        .option('--json', '输出 JSON 格式')).action(async (opts) => {
+        const result = await validateAtomPlanProject({
+            projectDir: opts.projectDir,
+            skillsDir: opts.skillsDir,
+            preferJson: !opts.allowMarkdown,
+        });
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else if (result.ok) {
+            console.log(`\n✓ atom-plan 校验通过（${result.source}，${result.skillRefsChecked.length} 个 skillRef）`);
+            for (const w of result.warnings)
+                console.log(`  ⚠ ${w}`);
+            console.log();
+        }
+        else {
+            console.error(`\n✗ atom-plan 校验失败（${result.source}）\n`);
+            for (const e of result.errors)
+                console.error(`  - ${e}`);
+            for (const w of result.warnings)
+                console.error(`  ⚠ ${w}`);
+            console.error();
+        }
+        if (!result.ok)
+            process.exit(1);
+    });
+    // ── read ──────────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('read <atomId>')
+        .description('输出指定 skill 的 SKILL.md 内容（供 Agent 直接读取 Recipe 和使用说明）')).action(async (atomId, opts) => {
+        const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+        const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+        if (dirs.length === 0) {
+            console.error('未找到 skills 目录。请通过 --skills-dir 指定、在 playcraft.config.json 中配置 skillsDir，或设置 AGENT_SKILLS_PATHS 环境变量。');
+            process.exit(1);
+        }
+        const entries = loadSkillIndex(dirs);
+        const entry = entries.find((e) => e.atomId === atomId);
+        if (!entry) {
+            console.error(`未找到 skill: ${atomId}`);
+            console.error(`可用 skill 列表：playcraft skills list --json`);
+            process.exit(1);
+        }
+        const skillMdPath = path.join(entry.dir, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath)) {
+            console.error(`${atomId} 没有 SKILL.md（skillDir: ${entry.dir}）`);
+            process.exit(1);
+        }
+        process.stdout.write(fs.readFileSync(skillMdPath, 'utf-8'));
+    });
+}