@playcraft/cli 0.0.44 → 0.0.47

package/dist/commands/skills.js

@@ -9,18 +9,21 @@
  *   list      列出所有可用 skill（支持按 engine/category/tag 过滤）
  *   match     按引擎+意图推荐完整 skill 集合（含依赖图遍历）
  *   scaffold  将指定 skill 的 ref 文件复制到目标项目目录
+ *   inspect   输出 skill 的文件清单（scaffold 路径 + files 逻辑索引 + 用途描述）
+ *   read      输出指定 skill 的 SKILL.md（供 Agent 读取详细使用说明）
  *
  * Skill 目录发现优先级：
  *   1. --skills-dir 参数
  *   2. AGENT_SKILLS_PATHS 环境变量（逗号分隔）
- *   3. <cwd>/node_modules/@playcraft/skills/skills
- *   4. <CLI 自身>/../../skills/skills（monorepo 开发时）
+ *   3. <cwd>/node_modules/@playcraft/skills/playcraft-skills（兼容旧路径 skills）
+ *   4. <CLI 自身>/../../skills/playcraft-skills（monorepo 开发时，兼容旧路径 skills）
  */
 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 { validateAsrCoverageProject } from '../atom-plan/validate-asr-coverage.js';
+import { getFusionHintsForGameplayAtoms, } from '../atom-tree/fusion-hints.js';
+import { collectPinnedDependencies, loadSkillManifestIndex, parseAtomTreeJson, parseSelectedAtomRefsFromAtomTreeProject, isUninitializedAtomTreeSkeleton, resolveSkillsDirs, validateAtomTreeSelectionProject, } from '../atom-tree/selection.js';
+import { buildAtomTreeSkeleton } from '../atom-tree/build-skeleton.js';
+import { validateAsrCoverageProject } from '../asr/validate-asr-coverage.js';
 import { loadConfig } from '../config.js';
 const KNOWN_ENGINES = ['phaser', 'threejs'];
 const SCORE_THRESHOLD_FULL = 8;
@@ -32,6 +35,13 @@ 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 };
 }
+/** Resolve atom-graph fusesWith hints for matched gameplay skills. */
+export function resolveFusionHintsFromMatchItems(items) {
+    const gameplayAtomIds = items
+        .map((item) => item.atomId)
+        .filter((atomId) => atomId.endsWith('.aigameplay'));
+    return getFusionHintsForGameplayAtoms(gameplayAtomIds);
+}
 /** 泛化 intent 词：单独命中时不应拉起大量无关 gameplay / 组件 */
 const GENERIC_INTENT_TAGS = new Set([
     'grid',
@@ -207,79 +217,37 @@ const LAYER_ORDER = {
     '其他': 99,
 };
 function getCategoryLayer(category, atomId) {
-    const id = atomId.toLowerCase();
+    // 新 6 值 category 直接映射
     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'))
+    if (category === 'visual')
+        return '视觉层';
+    if (category === 'ui')
         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);
+    if (category === 'asset')
+        return '资产层';
+    if (category === 'misc')
+        return '工具层';
+    // 旧 category 值兼容（渐进迁移期间可能遇到）
+    const id = atomId.toLowerCase();
+    if (category === 'build')
+        return '引擎层';
+    if (category === 'layout' || category === 'scene' || category === 'state')
+        return '玩法层';
+    if (category === 'audio' || category === 'config')
+        return '资产层';
+    if (category === 'util' || category === 'tool' || category === 'validator')
+        return '工具层';
+    if (category === 'animation' || category === 'vfx' || category === 'rendering')
+        return '视觉层';
+    if (category === 'component') {
+        if (id.includes('ui') || id.includes('bar') || id.includes('panel') || id.includes('tray'))
+            return 'UI层';
+        return '玩法层';
     }
-    return [...new Set(dirs)];
+    return '玩法层';
 }
 // ─── Manifest 索引器 ─────────────────────────────────────────────────────────
 function loadSkillIndex(skillsDirs) {
@@ -315,12 +283,35 @@ function getGameplayType(manifest) {
     const gen = manifest['generation'];
     return gen?.gameplayType;
 }
-function pinAtomIdToEngine(pinAtomId) {
-    if (!pinAtomId.endsWith('.aicomponent'))
+function isEngineManifest(manifest) {
+    return manifest.category === 'engine' || manifest.bundleType === 'aicomponent';
+}
+function isGameplayManifest(manifest) {
+    return manifest.category === 'gameplay' || manifest.bundleType === 'aigameplay';
+}
+function isMediaOrConfigManifest(manifest) {
+    return manifest.category === 'asset' || manifest.category === 'config';
+}
+/**
+ * 从 skill 的 manifest 中判断是否指向一个已知引擎 skill。
+ * 不再依赖 pinAtomId 后缀（如 .aicomponent、-runtime），而是通过传入 manifest 的 bundleType / category 来判断。
+ */
+function pinAtomIdToEngine(pinAtomId, manifest) {
+    if (!isEngineManifest(manifest))
         return null;
-    const name = pinAtomId.slice(0, -'.aicomponent'.length);
+    const name = pinAtomIdToBareName(pinAtomId);
     return KNOWN_ENGINES.includes(name) ? name : null;
 }
+/**
+ * 从 pinAtomId 提取裸名。
+ * 这里只做兼容性归一化，不再把后缀作为类型判断依据。
+ */
+function pinAtomIdToBareName(pinAtomId) {
+    if (pinAtomId.endsWith('.aicomponent')) {
+        return pinAtomId.slice(0, -'.aicomponent'.length);
+    }
+    return pinAtomId.replace(/-runtime$/, '');
+}
 /**
  * 仅按 intent 打分（discovery 相位）。不假设目标引擎。
  */
@@ -347,7 +338,7 @@ export function scoreSkillIntentOnly(entry, intentTags) {
 /**
  * 从 discovery 相位已匹配的 skill 聚合候选引擎。
  */
-export function inferSuggestedEngines(scored, intentTags) {
+export function inferSuggestedEngines(scored, intentTags, indexMap) {
     const totals = new Map();
     const bump = (engine, delta, reason) => {
         if (!KNOWN_ENGINES.includes(engine))
@@ -376,12 +367,13 @@ export function inferSuggestedEngines(scored, intentTags) {
         for (const imp of manifest.imports ?? []) {
             if (!imp.pinAtomId)
                 continue;
-            const eng = pinAtomIdToEngine(imp.pinAtomId);
+            const impManifest = indexMap.get(imp.pinAtomId)?.manifest;
+            const eng = pinAtomIdToEngine(imp.pinAtomId, impManifest ?? manifest);
             if (eng)
                 bump(eng, score, `${entry.atomId} → ${imp.pinAtomId}`);
         }
         if (manifest.category === 'engine') {
-            const eng = pinAtomIdToEngine(manifest.atomId);
+            const eng = pinAtomIdToEngine(manifest.atomId, manifest);
             if (eng)
                 bump(eng, score + 5, `引擎节点 ${manifest.atomId}`);
         }
@@ -419,7 +411,11 @@ export function scoreSkill(entry, engine, intentTags) {
             score += 3;
     }
     // 4. imports 中依赖该引擎的 skill
-    const importsEngine = manifest.imports?.some((imp) => imp.pinAtomId === `${engine}.aicomponent`);
+    const importsEngine = manifest.imports?.some((imp) => {
+        if (!imp.pinAtomId)
+            return false;
+        return pinAtomIdToEngine(imp.pinAtomId, { category: 'engine' }) === engine;
+    });
     if (importsEngine)
         score += 5;
     return score;
@@ -430,7 +426,11 @@ export function scoreSkill(entry, engine, intentTags) {
  * engineVariants[engine].imports 而非 manifest 顶层 imports，
  * 避免将另一引擎的依赖（如 phaser.aicomponent）错误地拉进来。
  */
-function collectDependencies(atomId, index, engine, visited = new Set()) {
+function collectDependencies(atomId, index, engine, visited = new Set(), depth = 0) {
+    const MAX_DEPTH = 100;
+    if (depth > MAX_DEPTH) {
+        throw new Error(`依赖收集递归深度超过限制 (${MAX_DEPTH})，当前atom: ${atomId}`);
+    }
     if (visited.has(atomId))
         return [];
     visited.add(atomId);
@@ -446,7 +446,7 @@ function collectDependencies(atomId, index, engine, visited = new Set()) {
         for (const pinId of variantImports) {
             if (!visited.has(pinId)) {
                 deps.push(pinId);
-                deps.push(...collectDependencies(pinId, index, engine, visited));
+                deps.push(...collectDependencies(pinId, index, engine, visited, depth + 1));
             }
         }
     }
@@ -455,7 +455,7 @@ function collectDependencies(atomId, index, engine, visited = new Set()) {
         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));
+                deps.push(...collectDependencies(imp.pinAtomId, index, engine, visited, depth + 1));
             }
         }
     }
@@ -474,10 +474,23 @@ function getScaffoldFiles(manifest, engine) {
     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 };
+        const files = manifest.scaffold.files;
+        if (Array.isArray(files)) {
+            // Array format: [{ source, dest, mode?, weight? }]
+            for (const item of files) {
+                const entry = item;
+                if (entry.source && entry.dest) {
+                    scaffoldFiles[entry.dest] = { source: entry.source, mode: entry.mode ?? 'full', weight: entry.weight ?? 10 };
+                }
+            }
+        }
+        else {
+            // Record format: { 'dest/path': { source, mode?, weight? } }
+            for (const [k, v] of Object.entries(files)) {
+                const contribution = v;
+                if (contribution.source) {
+                    scaffoldFiles[k] = { source: contribution.source, mode: contribution.mode ?? 'full', weight: contribution.weight ?? 10 };
+                }
             }
         }
     }
@@ -489,7 +502,7 @@ function getScaffoldFiles(manifest, engine) {
     return scaffoldFiles;
 }
 /** 无法推断引擎时的兜底：仅 intent 命中项，无依赖展开与 scaffold */
-function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines) {
+function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines, indexMap) {
     const scored = entries
         .map((entry) => ({ entry, score: scoreSkillIntentOnly(entry, intentTags) }))
         .filter(({ score }) => score >= SCORE_THRESHOLD_DISCOVERY)
@@ -511,7 +524,11 @@ function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines) {
         if (engineVariants)
             supportedEngines.push(...Object.keys(engineVariants));
         for (const imp of manifest.imports ?? []) {
-            const eng = imp.pinAtomId ? pinAtomIdToEngine(imp.pinAtomId) : null;
+            const pinAtomId = imp.pinAtomId;
+            if (!pinAtomId)
+                continue;
+            const impManifest = indexMap?.get(pinAtomId)?.manifest ?? manifest;
+            const eng = pinAtomIdToEngine(pinAtomId, impManifest);
             if (eng)
                 supportedEngines.push(eng);
         }
@@ -524,6 +541,7 @@ function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines) {
             label: manifest.label,
             layer,
             reason,
+            roles: [],
             scaffoldFiles: {},
             hasEngineVariant: false,
             skillDir: entry.dir,
@@ -539,6 +557,7 @@ function buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines) {
         items,
         mediaGroups,
         missingSlots: [],
+        fusionHints: resolveFusionHintsFromMatchItems(items),
     };
 }
 /**
@@ -548,10 +567,11 @@ 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 indexMap = new Map(entries.map((e) => [e.atomId, e]));
+    const suggestedEngines = inferSuggestedEngines(scored, intentTags, indexMap);
     const engine = suggestedEngines[0]?.engine;
     if (!engine) {
-        return buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines);
+        return buildIntentOnlyMatchResult(entries, intentTags, suggestedEngines, indexMap);
     }
     const full = buildMatchResult(entries, engine, intentTags);
     const gap = suggestedEngines.length > 1 ? suggestedEngines[0].score - suggestedEngines[1].score : 99;
@@ -563,17 +583,21 @@ export function buildAutoMatchResult(entries, intentTags) {
     };
 }
 function selectMatchSeedAtomIds(scored, engine, intentTags) {
-    const seeds = new Set([`${engine}.aicomponent`]);
+    const seeds = new Set();
     for (const { entry, score } of scored) {
         const { manifest } = entry;
-        if (manifest.category === 'gameplay') {
+        if (isEngineManifest(manifest) && pinAtomIdToEngine(entry.atomId, manifest) === engine) {
+            seeds.add(entry.atomId);
+            continue;
+        }
+        if (isGameplayManifest(manifest)) {
             if (passesGameplayIntentFilter(entry, intentTags))
                 seeds.add(entry.atomId);
             continue;
         }
-        if (manifest.category === 'engine')
+        if (isEngineManifest(manifest))
             continue;
-        if (['aiimage', 'aiaudio', 'aiconfig'].includes(manifest.bundleType))
+        if (isMediaOrConfigManifest(manifest))
             continue;
         const specificHits = intentTags.filter((t) => isSpecificIntentTag(t) && entryMatchesIntentTag(entry, t));
         if (specificHits.length > 0 && score >= SCORE_THRESHOLD_FULL)
@@ -591,10 +615,52 @@ function expandSeedClosure(seedIds, indexMap, engine) {
     }
     return closed;
 }
-function buildItemReason(entry, engine, intentTags, score, via) {
+function formatDependencyReason(dep) {
+    const dependedByText = dep.dependedBy.length > 0 ? dep.dependedBy.join('、') : '上游 skill';
+    return `传递依赖：被 ${dependedByText} 依赖`;
+}
+function buildDependencyReasonMap(requiredIds, indexMap, engine) {
+    const reasonMap = new Map();
+    const getOrCreate = (atomId) => {
+        const current = reasonMap.get(atomId) ?? { dependedBy: new Set(), roles: new Set() };
+        reasonMap.set(atomId, current);
+        return current;
+    };
+    for (const parentId of requiredIds) {
+        const entry = indexMap.get(parentId);
+        if (!entry)
+            continue;
+        const engineVariants = entry.manifest['engineVariants'];
+        const variantImports = engineVariants?.[engine]?.imports;
+        if (variantImports && variantImports.length > 0) {
+            for (const depId of variantImports) {
+                if (!requiredIds.has(depId))
+                    continue;
+                const ctx = getOrCreate(depId);
+                ctx.dependedBy.add(parentId);
+            }
+            continue;
+        }
+        for (const imp of entry.manifest.imports ?? []) {
+            if (imp.pinAtomId && requiredIds.has(imp.pinAtomId)) {
+                const ctx = getOrCreate(imp.pinAtomId);
+                ctx.dependedBy.add(parentId);
+                for (const role of imp.matchBindingRoles ?? []) {
+                    ctx.roles.add(role);
+                }
+            }
+        }
+    }
+    return new Map([...reasonMap.entries()].map(([atomId, ctx]) => [atomId, {
+            dependedBy: [...ctx.dependedBy].sort(),
+            roles: [...ctx.roles].sort(),
+        }]));
+}
+function buildItemReason(entry, engine, intentTags, score, via, dependencyReason) {
     const { manifest } = entry;
-    if (via === 'dependency')
-        return '传递依赖';
+    if (via === 'dependency') {
+        return formatDependencyReason(dependencyReason ?? { dependedBy: [], roles: [] });
+    }
     if (manifest.category === 'engine')
         return '引擎根节点';
     const gt = getGameplayType(manifest);
@@ -623,12 +689,12 @@ export function buildMatchResult(entries, engine, intentTags) {
     const seedIds = selectMatchSeedAtomIds(scored, engine, expandedIntent);
     const requiredIds = expandSeedClosure(seedIds, indexMap, engine);
     const seedIdSet = seedIds;
+    const dependencyReasonMap = buildDependencyReasonMap(requiredIds, indexMap, engine);
     const anchorEntries = [];
     for (const id of seedIds) {
-        if (id.endsWith('.aigameplay')) {
-            const e = indexMap.get(id);
-            if (e)
-                anchorEntries.push(e);
+        const e = indexMap.get(id);
+        if (e && isGameplayManifest(e.manifest)) {
+            anchorEntries.push(e);
         }
     }
     const allItems = [];
@@ -641,12 +707,14 @@ export function buildMatchResult(entries, engine, intentTags) {
         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);
+        const dependencyReason = dependencyReasonMap.get(atomId);
+        const reason = buildItemReason(entry, engine, expandedIntent, scoreById.get(atomId) ?? null, via, dependencyReason);
         allItems.push({
             atomId: manifest.atomId,
             label: manifest.label,
             layer,
             reason,
+            roles: dependencyReason?.roles ?? [],
             scaffoldFiles,
             hasEngineVariant,
             skillDir: entry.dir,
@@ -654,7 +722,6 @@ export function buildMatchResult(entries, engine, intentTags) {
     }
     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 ?? []) {
@@ -675,6 +742,7 @@ export function buildMatchResult(entries, engine, intentTags) {
         items: allItems,
         mediaGroups,
         missingSlots,
+        fusionHints: resolveFusionHintsFromMatchItems(allItems),
     };
 }
 // ─── 媒体/配置资产匹配（第二遍：引擎无关，按 bindingRole 分组）────────────
@@ -698,7 +766,7 @@ function collectAnchorBindingRoles(anchorEntries) {
     return roles;
 }
 function collectMediaRoleMap(entries) {
-    const mediaEntries = entries.filter((e) => ['aiimage', 'aiaudio', 'aiconfig'].includes(e.manifest.bundleType));
+    const mediaEntries = entries.filter((e) => isMediaOrConfigManifest(e.manifest));
     const roleMap = new Map();
     for (const entry of mediaEntries) {
         for (const role of entry.manifest.bindingRoles ?? []) {
@@ -810,7 +878,7 @@ function printMatchResult(result, verbose, entries) {
     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 codeItems = items.filter((i) => i.layer !== '资产层');
     const engineLine = engineSource === 'inferred'
         ? `engine=${engine}（自动）`
         : engineSource === 'none'
@@ -865,7 +933,7 @@ function printMatchResult(result, verbose, entries) {
             for (const s of result.missingSlots)
                 console.log(`  - ${s}`);
         }
-        console.log('\n加 --json 供 atom-plan；加 --verbose 查看 scaffold 明细与命令。\n');
+        console.log('\n加 --json 供 atom-tree；加 --verbose 查看 scaffold 明细与命令。\n');
         return;
     }
     // ── verbose：完整分层列表 ──
@@ -906,18 +974,58 @@ function printMatchResult(result, verbose, entries) {
 function printMatchFooters(result, verbose) {
     if (!result.engine)
         return;
-    const codeItems = result.items.filter((i) => /\.(aigameplay|aicomponent|aiconfig)$/.test(i.atomId));
+    const codeItems = result.items.filter((i) => i.layer !== '资产层');
     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 <子集>`);
+        console.log(`link:     playcraft skills link --from-atom-tree --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 模式 ──────────────────────────────────────────
+// ─── Scaffold 辅助 ───────────────────────────────────────────────────────────
+/**
+ * 修复 Windows 路径中因 shell/Agent 转义丢失的路径分隔符。
+ *
+ * 典型场景：Agent 传入 D:\project\playcraft-tencent\test19\game，
+ * 反斜杠被 shell 消费后变成 D:projectplaycraft-tencenttest19game。
+ *
+ * 策略：如果路径不以 \ 或 / 开头且不含路径分隔符，尝试在已知目录边界插入分隔符。
+ */
+function sanitizeWindowsPath(raw) {
+    // 已经包含路径分隔符（/ 或 \\），说明未被破坏
+    if (/[\\/]/.test(raw))
+        return raw;
+    // 只处理 Windows 绝对路径格式 D:xxx（盘符后无分隔符）
+    const m = raw.match(/^([A-Za-z]:)(.+)$/);
+    if (!m)
+        return raw;
+    const drive = m[1];
+    const rest = m[2];
+    // 尝试在已知的 monorepo 目录边界插入 /
+    // projectplaycraft-tencent → project/playcraft-tencent
+    // playcraft-tencenttest19 → playcraft-tencent/test19
+    const segments = [
+        'project', 'playcraft-tencent', 'playcraft-skills', 'packages',
+        'test16', 'test19', 'src', 'game', 'docs', 'skills',
+    ];
+    let result = rest;
+    for (const seg of segments) {
+        const idx = result.indexOf(seg);
+        if (idx > 0) {
+            // 在已知段之前插入 /
+            result = result.slice(0, idx) + '/' + result.slice(idx);
+        }
+    }
+    // 如果仍然没有分隔符，尝试按大写字母边界插入（兜底）
+    if (!/[\\/]/.test(result)) {
+        // 不做暴力拆分，保持原样
+    }
+    return drive + '/' + result;
+}
+// ─── Scaffold merge-json 模式 ─────────────────────────────────────────────
 /**
  * 深度合并两个 JSON 对象：incoming 中的新 key 追加到 existing，已有 key 保留 existing 的值。
  * 对象类型字段（dependencies / devDependencies / compilerOptions 等）递归合并。
@@ -940,23 +1048,57 @@ function mergeJson(existing, incoming) {
     }
     return result;
 }
+function dedupeAtomRefs(atomRefs) {
+    const seen = new Set();
+    const deduped = [];
+    for (const atomRef of atomRefs) {
+        const normalized = atomRef.trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        deduped.push(normalized);
+    }
+    return deduped;
+}
+function getImportedAtomIdsForEngine(entry, engine) {
+    const engineVariants = entry.manifest['engineVariants'];
+    const variantImports = engineVariants?.[engine]?.imports;
+    if (variantImports && variantImports.length > 0) {
+        return dedupeAtomRefs(variantImports);
+    }
+    const topLevelImports = (entry.manifest.imports ?? [])
+        .map((imp) => imp.pinAtomId?.trim())
+        .filter((pinAtomId) => !!pinAtomId);
+    return dedupeAtomRefs(topLevelImports);
+}
 // ─── 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;
+    // manifest 数据：记录每个 atomId 复制了哪些文件，用于落盘 scaffold-manifest.md
+    const manifestData = [];
     for (const atomId of atomIds) {
         const entry = indexMap.get(atomId);
         if (!entry) {
             console.warn(`[warn] 未找到 skill: ${atomId}`);
             continue;
         }
+        const importedAtomIds = getImportedAtomIdsForEngine(entry, engine);
+        if (importedAtomIds.length > 0) {
+            for (const importedAtomId of importedAtomIds) {
+                const importedEntry = indexMap.get(importedAtomId);
+                const importedDir = importedEntry?.dir ?? '(missing skill dir)';
+                console.log(`[import-link] [${atomId}] ${importedAtomId} -> ${importedDir}`);
+            }
+        }
         const scaffoldFiles = getScaffoldFiles(entry.manifest, engine);
         if (Object.keys(scaffoldFiles).length === 0) {
             console.log(`[skip] ${atomId}：无 scaffold 文件`);
             continue;
         }
+        const atomManifestFiles = [];
         for (const [destRelPath, { source, mode }] of Object.entries(scaffoldFiles)) {
             const srcPath = path.join(entry.dir, source);
             const destPath = path.join(outDir, destRelPath);
@@ -968,7 +1110,8 @@ function runScaffold(opts) {
             // merge-json 模式：目标文件已存在时合并而非覆盖（不受 --force 影响）
             if (mode === 'merge-json' && destExists) {
                 if (dryRun) {
-                    console.log(`[dry-run] ${source} → ${destRelPath} (merge-json)`);
+                    console.log(`[dry-run] [${atomId}] ${source} → ${destRelPath} (merge-json)`);
+                    atomManifestFiles.push({ dest: destRelPath, status: 'dry-run' });
                     copied++;
                     continue;
                 }
@@ -977,7 +1120,8 @@ function runScaffold(opts) {
                     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}`);
+                    console.log(`[merged] [${atomId}] ${source} → ${destRelPath}`);
+                    atomManifestFiles.push({ dest: destRelPath, status: 'merged' });
                     copied++;
                 }
                 catch (e) {
@@ -987,82 +1131,143 @@ function runScaffold(opts) {
                 continue;
             }
             if (destExists && !force) {
-                console.log(`[skip] ${destRelPath} 已存在（使用 --force 覆盖）`);
+                console.log(`[skip] [${atomId}] ${destRelPath} 已存在（使用 --force 覆盖）`);
+                atomManifestFiles.push({ dest: destRelPath, status: 'skipped' });
                 skipped++;
                 continue;
             }
             if (dryRun) {
-                console.log(`[dry-run] ${source} → ${destRelPath}`);
+                console.log(`[dry-run] [${atomId}] ${source} → ${destRelPath}`);
+                atomManifestFiles.push({ dest: destRelPath, status: 'dry-run' });
                 copied++;
                 continue;
             }
-            fs.mkdirSync(path.dirname(destPath), { recursive: true });
-            fs.copyFileSync(srcPath, destPath);
-            console.log(`[copied] ${source} → ${destRelPath}`);
+            if (fs.statSync(srcPath).isDirectory()) {
+                // 检查目录深度，防止递归过深
+                const pathDepth = srcPath.split(path.sep).length;
+                const MAX_PATH_DEPTH = 100;
+                if (pathDepth > MAX_PATH_DEPTH) {
+                    throw new Error(`目录路径深度超过限制 (${MAX_PATH_DEPTH})，路径: ${srcPath}`);
+                }
+                fs.mkdirSync(destPath, { recursive: true });
+                fs.cpSync(srcPath, destPath, { recursive: true });
+            }
+            else {
+                fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                fs.copyFileSync(srcPath, destPath);
+            }
+            console.log(`[copied] [${atomId}] ${source} → ${destRelPath}`);
+            atomManifestFiles.push({ dest: destRelPath, status: 'copied' });
             copied++;
         }
+        if (atomManifestFiles.length > 0) {
+            manifestData.push({ atomId, files: atomManifestFiles });
+        }
     }
     console.log(`\n完成：${copied} 个文件${dryRun ? '（dry-run）' : ''}，${skipped} 个跳过。`);
+    // ── 生成 docs/scaffold-manifest.md 落盘（增量 upsert）──────────────────────
+    if (!dryRun && manifestData.length > 0) {
+        const docsDir = path.join(process.cwd(), 'docs');
+        const manifestPath = path.join(docsDir, 'scaffold-manifest.md');
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        /** 将一条 manifestData 条目渲染为 markdown 段落（不含末尾空行） */
+        const renderAtomSection = (atomId, files) => {
+            const sectionLines = [];
+            sectionLines.push(`## ${atomId}`);
+            sectionLines.push(``);
+            sectionLines.push(`> 查看用法：\`playcraft skills read ${atomId}\``);
+            sectionLines.push(``);
+            const copiedFiles = files.filter((f) => f.status === 'copied' || f.status === 'merged');
+            const skippedFiles = files.filter((f) => f.status === 'skipped');
+            if (copiedFiles.length > 0) {
+                for (const f of copiedFiles) {
+                    sectionLines.push(`- \`${f.dest}\`${f.status === 'merged' ? ' *(merged)*' : ''}`);
+                }
+            }
+            if (skippedFiles.length > 0) {
+                sectionLines.push(``);
+                sectionLines.push(`已跳过（文件已存在）：`);
+                for (const f of skippedFiles) {
+                    sectionLines.push(`- \`${f.dest}\` *(skipped)*`);
+                }
+            }
+            return sectionLines.join('\n');
+        };
+        try {
+            fs.mkdirSync(docsDir, { recursive: true });
+            // ── 增量 upsert：文件已存在时保留旧段落，只替换/追加本次涉及的 atomId ──
+            if (fs.existsSync(manifestPath)) {
+                const existing = fs.readFileSync(manifestPath, 'utf-8');
+                // 按 "## <atomId>" 分割成段落 Map（key = atomId，value = 段落文本，不含前导 ##）
+                // 段落边界：下一个 "^## " 或文件末尾
+                const sectionRegex = /^## (.+)$/m;
+                // 将文件拆分为：header 部分（第一个 ## 之前）+ 各 atomId 段落
+                const firstSectionIdx = existing.search(/^## /m);
+                let header = firstSectionIdx === -1 ? existing : existing.slice(0, firstSectionIdx);
+                // 更新 header 里的"最后更新时间"行（> 生成时间：...）
+                header = header.replace(/^> 生成时间：.+$/m, `> 最后更新：${now}`);
+                // 如果 header 里没有"最后更新"行（旧格式只有"生成时间"），则追加
+                if (!header.includes('> 最后更新：')) {
+                    header = header.replace(/^> 生成时间：.+$/m, `> 生成时间：$&\n> 最后更新：${now}`);
+                }
+                // 解析现有段落（排除 footer：段落内尾部的 "---\n\n*Developer…*" 不属于 atom 内容）
+                const existingSections = new Map();
+                const rawSections = existing.slice(firstSectionIdx === -1 ? existing.length : firstSectionIdx);
+                // 用正则逐段切割
+                const splitPattern = /(?=^## )/m;
+                for (const chunk of rawSections.split(splitPattern)) {
+                    const match = chunk.match(sectionRegex);
+                    if (match) {
+                        // 去掉段落内混入的 footer（旧格式可能把 "---\n\n*Developer…*" 写在每段末尾）
+                        const atomContent = chunk.replace(/\n---\n[\s\S]*$/, '').trimEnd();
+                        existingSections.set(match[1].trim(), atomContent);
+                    }
+                }
+                // upsert：本次 manifestData 覆盖同名段落，新 atomId 追加
+                for (const { atomId, files } of manifestData) {
+                    existingSections.set(atomId, renderAtomSection(atomId, files));
+                }
+                // 重新拼装：header + 各段落（按原有顺序，新增的追加到末尾）
+                const footer = `\n---\n\n*Developer：在 Step 0 摄入阶段请先阅读本文件，了解各资源来自哪个 skill atom，再通过 \`playcraft skills read <atomId>\` 读取对应 SKILL.md 理解绑定方式。*\n`;
+                const body = [...existingSections.values()].join('\n\n') + '\n';
+                fs.writeFileSync(manifestPath, header + body + footer, 'utf-8');
+                console.log(`\n[manifest] 已更新 docs/scaffold-manifest.md（增量）`);
+            }
+            else {
+                // 文件不存在：全量写入
+                const lines = [
+                    `# Scaffold Manifest`,
+                    ``,
+                    `> 由 \`playcraft skills scaffold\` 自动生成，记录本次 scaffold 的文件来源。`,
+                    `> 生成时间：${now}`,
+                    `> 引擎：${engine}`,
+                    ``,
+                    `---`,
+                    ``,
+                ];
+                for (const { atomId, files } of manifestData) {
+                    lines.push(renderAtomSection(atomId, files));
+                    lines.push(``);
+                }
+                lines.push(`---`);
+                lines.push(``);
+                lines.push(`*Developer：在 Step 0 摄入阶段请先阅读本文件，了解各资源来自哪个 skill atom，再通过 \`playcraft skills read <atomId>\` 读取对应 SKILL.md 理解绑定方式。*`);
+                lines.push(``);
+                fs.writeFileSync(manifestPath, lines.join('\n'), 'utf-8');
+                console.log(`\n[manifest] 已生成 docs/scaffold-manifest.md`);
+            }
+        }
+        catch (e) {
+            console.warn(`[warn] scaffold-manifest.md 写入失败: ${e.message}`);
+        }
+    }
 }
 // ─── 项目内 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');
@@ -1122,13 +1327,28 @@ export async function linkAtomSkillsToProject(options) {
         await fs.promises.symlink(relTarget, linkPath, 'dir');
         linked.push(atomId);
     }
+    const manifestPath = path.join(skillsLinkDir, '.playcraft-dag-links.json');
     const pruned = [];
     if (options.prune && fs.existsSync(skillsLinkDir)) {
         const children = await fs.promises.readdir(skillsLinkDir, { withFileTypes: true });
+        let knownLinkedIds = new Set();
+        if (fs.existsSync(manifestPath)) {
+            try {
+                const prev = JSON.parse(await fs.promises.readFile(manifestPath, 'utf-8'));
+                knownLinkedIds = new Set((prev.atomIds ?? []).filter(Boolean));
+            }
+            catch {
+                knownLinkedIds = new Set();
+            }
+        }
         for (const child of children) {
-            if (!child.isSymbolicLink() || !isAtomSkillLinkName(child.name))
+            if (!child.isSymbolicLink())
+                continue;
+            if (isProtectedSkillDirName(child.name))
+                continue;
+            if (targetIds.has(child.name))
                 continue;
-            if (targetIds.has(child.name) || isProtectedSkillDirName(child.name))
+            if (knownLinkedIds.size > 0 && !knownLinkedIds.has(child.name))
                 continue;
             const linkPath = path.join(skillsLinkDir, child.name);
             if (options.dryRun) {
@@ -1151,6 +1371,31 @@ export async function linkAtomSkillsToProject(options) {
     }
     return { linked, skipped, pruned, missing };
 }
+/**
+ * Convenience wrapper: read meta.selectedAtoms from docs/atom-tree.json and link
+ * them into the project's .claude/skills/ (prune stale by default). Used as a
+ * fallback inside init-template so a project is never left with selected-but-unlinked
+ * atoms. Returns the link result plus the atom ids it acted on.
+ */
+export async function autoLinkSkillsFromAtomTree(projectDir, opts = {}) {
+    const atomIds = parseSelectedAtomRefsFromAtomTreeProject(projectDir);
+    if (atomIds.length === 0) {
+        return { linked: [], skipped: [], pruned: [], missing: [], atomIds: [] };
+    }
+    const config = await loadConfig({}).catch(() => ({ skillsDir: undefined }));
+    const dirs = resolveSkillsDirs(opts.skillsDir, config.skillsDir);
+    if (dirs.length === 0) {
+        return { linked: [], skipped: [], pruned: [], missing: atomIds, atomIds };
+    }
+    const entries = loadSkillIndex(dirs);
+    const result = await linkAtomSkillsToProject({
+        projectDir,
+        atomIds,
+        entries,
+        prune: opts.prune ?? true,
+    });
+    return { ...result, atomIds };
+}
 // ─── CLI 注册 ────────────────────────────────────────────────────────────────
 export function registerSkillsCommands(program) {
     const skills = program
@@ -1259,11 +1504,15 @@ export function registerSkillsCommands(program) {
         }
         const entries = loadSkillIndex(dirs);
         const atomIds = opts.atoms.split(',').map((s) => s.trim()).filter(Boolean);
+        // 修复 Windows 路径中因 shell/Agent 转义丢失的路径分隔符：
+        // D:\project\playcraft-tencent\test19\game → 反斜杠被 shell 消费后变成 D:projectplaycraft-tencenttest19game
+        // 这里尝试恢复为 D:/project/playcraft-tencent/test19/game
+        const sanitizedOut = sanitizeWindowsPath(opts.out);
         runScaffold({
             entries,
             atomIds,
             engine: opts.engine,
-            outDir: path.resolve(opts.out),
+            outDir: path.resolve(sanitizedOut),
             dryRun: !!opts.dryRun,
             force: !!opts.force,
         });
@@ -1273,7 +1522,7 @@ export function registerSkillsCommands(program) {
         .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('--from-atom-tree', '从 docs/atom-tree.json 的 meta.selectedAtoms 读取当次参考 atom 列表')
         .option('--project-dir <path>', '项目根目录', process.cwd())
         .option('--prune', '移除 .claude/skills/ 下不在本次列表中的 DAG 软连接')
         .option('--dry-run', '只打印将创建/删除的软连接')
@@ -1286,10 +1535,10 @@ export function registerSkillsCommands(program) {
         }
         const entries = loadSkillIndex(dirs);
         let atomIds = [];
-        if (opts.fromAtomPlan) {
-            atomIds = parseSkillRefsFromAtomPlanProject(opts.projectDir);
+        if (opts.fromAtomTree) {
+            atomIds = parseSelectedAtomRefsFromAtomTreeProject(opts.projectDir);
             if (atomIds.length === 0) {
-                console.error('未找到 docs/atom-plan.json（或 atom-plan.md）中的非空 skillRef');
+                console.error('未找到 docs/atom-tree.json 的非空 meta.selectedAtoms');
                 process.exit(1);
             }
         }
@@ -1298,7 +1547,7 @@ export function registerSkillsCommands(program) {
         }
         atomIds = [...new Set(atomIds)];
         if (atomIds.length === 0) {
-            console.error('请指定 --atoms <id1,id2> 或 --from-atom-plan（且 atom-plan 中含非空 skillRef）');
+            console.error('请指定 --atoms <id1,id2> 或 --from-atom-tree（且 atom-tree 中含非空 meta.selectedAtoms）');
             process.exit(1);
         }
         const result = await linkAtomSkillsToProject({
@@ -1321,29 +1570,27 @@ export function registerSkillsCommands(program) {
         if (result.missing.length > 0)
             process.exit(1);
     });
-    // ── validate-atom-plan ────────────────────────────────────────────────────
+    // ── validate-atom-tree-selection ──────────────────────────────────────────
     addSkillsDirOption(skills
-        .command('validate-atom-plan')
-        .description('校验 docs/atom-plan.json 中 skillRef 均存在于 skills 库，且落在 skillsMatch.items 内')
+        .command('validate-atom-tree-selection')
+        .description('校验 docs/atom-tree.json 的 meta.selectedAtoms 是否存在、匹配并满足软槽位约束')
         .option('--project-dir <path>', '项目根目录', process.cwd())
-        .option('--allow-markdown', '若无 JSON 则回退校验 atom-plan.md（不推荐）')
         .option('--json', '输出 JSON 格式')).action(async (opts) => {
-        const result = await validateAtomPlanProject({
+        const result = await validateAtomTreeSelectionProject({
             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）`);
+            console.log(`\n✓ atom-tree selection 校验通过（${result.selectedAtomRefsChecked.length} 个 selected atom refs）`);
             for (const w of result.warnings)
                 console.log(`  ⚠ ${w}`);
             console.log();
         }
         else {
-            console.error(`\n✗ atom-plan 校验失败（${result.source}）\n`);
+            console.error('\n✗ atom-tree selection 校验失败\n');
             for (const e of result.errors)
                 console.error(`  - ${e}`);
             for (const w of result.warnings)
@@ -1400,4 +1647,533 @@ export function registerSkillsCommands(program) {
         }
         process.stdout.write(fs.readFileSync(skillMdPath, 'utf-8'));
     });
+    // ── inspect ───────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('inspect <atomId>')
+        .description('输出 skill 的文件清单：scaffold 目标路径 + files 逻辑索引 + 各文件用途描述')
+        .option('--json', '输出 JSON 格式')).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`);
+            process.exit(1);
+        }
+        const { manifest, dir } = entry;
+        const scaffoldRows = [];
+        if (manifest.scaffold?.files) {
+            for (const [dest, v] of Object.entries(manifest.scaffold.files)) {
+                const contribution = v;
+                if (!contribution.source)
+                    continue;
+                const srcAbs = path.join(dir, contribution.source);
+                // 目录项：检查目录是否存在
+                const exists = contribution.source.endsWith('/')
+                    ? fs.existsSync(srcAbs)
+                    : fs.existsSync(srcAbs);
+                scaffoldRows.push({
+                    dest,
+                    source: contribution.source,
+                    mode: contribution.mode ?? 'full',
+                    exists,
+                });
+            }
+        }
+        const fileRows = [];
+        if (Array.isArray(manifest.files)) {
+            for (const item of manifest.files) {
+                const absPath = path.join(dir, item.path);
+                fileRows.push({
+                    path: item.path,
+                    description: item.description ?? '',
+                    exists: fs.existsSync(absPath),
+                });
+            }
+        }
+        // ── JSON 输出 ──────────────────────────────────────────────────────────
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({
+                atomId,
+                label: manifest.label,
+                bundleType: manifest.bundleType,
+                scaffoldFiles: scaffoldRows,
+                files: fileRows,
+            }, null, 2) + '\n');
+            return;
+        }
+        // ── 人读输出 ──────────────────────────────────────────────────────────
+        console.log(`\n${atomId}  ${manifest.label.zh} / ${manifest.label.en}`);
+        console.log(`bundleType: ${manifest.bundleType}  category: ${manifest.category}\n`);
+        if (scaffoldRows.length > 0) {
+            console.log('── Scaffold 文件（playcraft skills scaffold 会复制这些）────────────────');
+            const maxDest = Math.max(...scaffoldRows.map((r) => r.dest.length), 4);
+            const maxSrc = Math.max(...scaffoldRows.map((r) => r.source.length), 6);
+            console.log(`  ${'dest'.padEnd(maxDest)}  ${'source'.padEnd(maxSrc)}  mode`);
+            console.log(`  ${'─'.repeat(maxDest)}  ${'─'.repeat(maxSrc)}  ────`);
+            for (const r of scaffoldRows) {
+                const missing = r.exists ? '' : '  ⚠ 源文件缺失';
+                console.log(`  ${r.dest.padEnd(maxDest)}  ${r.source.padEnd(maxSrc)}  ${r.mode}${missing}`);
+            }
+            console.log();
+        }
+        else {
+            console.log('── Scaffold 文件：（无）────────────────\n');
+        }
+        if (fileRows.length > 0) {
+            console.log('── Files（ref/ 内容清单 + 用途说明）────────────────────────────────────');
+            for (const r of fileRows) {
+                const missing = r.exists ? '' : '  ⚠ 文件缺失';
+                console.log(`  ${r.path}${missing}`);
+                if (r.description) {
+                    const lines = r.description.match(/.{1,80}/g) ?? [r.description];
+                    for (const line of lines)
+                        console.log(`    ${line}`);
+                }
+            }
+            console.log();
+        }
+        else {
+            console.log('── Files：（无）────────────────\n');
+        }
+    });
+    // ── gettags ───────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('gettags')
+        .description('列出所有 skill 的 tags（去重）')
+        .option('--category <category>', '按 category 筛选（逗号分隔）')
+        .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);
+        }
+        const filterCategories = opts.category?.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) ?? [];
+        let entries = loadSkillIndex(dirs);
+        if (filterCategories.length > 0) {
+            entries = entries.filter((e) => filterCategories.includes(e.manifest.category.toLowerCase()));
+        }
+        const tags = [...new Set(entries.flatMap((e) => e.manifest.tags ?? []))].sort();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(tags) + '\n');
+            return;
+        }
+        process.stdout.write(tags.join(' ') + '\n');
+    });
+    // ── getkeywords ───────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('getkeywords')
+        .description('列出所有 skill 的 keywords（去重）')
+        .option('--category <category>', '按 category 筛选（逗号分隔）')
+        .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);
+        }
+        const filterCategories = opts.category?.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) ?? [];
+        let entries = loadSkillIndex(dirs);
+        if (filterCategories.length > 0) {
+            entries = entries.filter((e) => filterCategories.includes(e.manifest.category.toLowerCase()));
+        }
+        const keywords = [...new Set(entries.flatMap((e) => e.manifest.keywords ?? []))].sort();
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(keywords) + ',');
+            return;
+        }
+        process.stdout.write(keywords.join(' ') + ',');
+    });
+    // ── filter ────────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('filter')
+        .description('按 tags / keywords / category / role 筛选 skill')
+        .option('--tags <tags>', '按 tags 筛选（逗号分隔）')
+        .option('--keywords <keywords>', '按 keywords 筛选（逗号分隔）')
+        .option('--category <category>', '按 category 筛选（逗号分隔）')
+        .option('--role <roles>', '按 bindingRoles 筛选（逗号分隔）')
+        .option('--and', '维度内使用 AND（默认 OR，如 --tags a,b 命中含 a 或 b 的 skill）')
+        .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);
+        }
+        const filterTags = opts.tags?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+        const filterKeywords = opts.keywords?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+        const filterCategories = opts.category?.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) ?? [];
+        const filterRoles = opts.role?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+        if (filterTags.length === 0 && filterKeywords.length === 0 && filterCategories.length === 0 && filterRoles.length === 0) {
+            console.error('请至少指定一个筛选条件：--tags、--keywords、--category 或 --role');
+            process.exit(1);
+        }
+        const entries = loadSkillIndex(dirs);
+        const useAnd = !!opts.and;
+        const matched = entries.filter((entry) => {
+            const manifest = entry.manifest;
+            const entryTags = manifest.tags ?? [];
+            const entryKeywords = manifest.keywords ?? [];
+            const entryCategory = manifest.category.toLowerCase();
+            const entryRoles = manifest.bindingRoles ?? [];
+            const conditions = [];
+            if (filterTags.length > 0) {
+                conditions.push(useAnd
+                    ? filterTags.every((t) => entryTags.includes(t))
+                    : filterTags.some((t) => entryTags.includes(t)));
+            }
+            if (filterKeywords.length > 0) {
+                conditions.push(useAnd
+                    ? filterKeywords.every((kw) => entryKeywords.includes(kw))
+                    : filterKeywords.some((kw) => entryKeywords.includes(kw)));
+            }
+            if (filterCategories.length > 0) {
+                conditions.push(useAnd
+                    ? filterCategories.every((c) => entryCategory === c)
+                    : filterCategories.includes(entryCategory));
+            }
+            if (filterRoles.length > 0) {
+                conditions.push(useAnd
+                    ? filterRoles.every((r) => entryRoles.includes(r))
+                    : filterRoles.some((r) => entryRoles.includes(r)));
+            }
+            return conditions.every(Boolean);
+        });
+        if (opts.json) {
+            const output = matched.map((e) => {
+                const m = e.manifest;
+                const gen = m['generation'];
+                return {
+                    atomId: e.atomId,
+                    category: m.category,
+                    bundleType: m.bundleType ?? null,
+                    mode: m.mode ?? null,
+                    label: m.label,
+                    tags: m.tags ?? [],
+                    bindingRoles: m.bindingRoles ?? [],
+                    gameplayType: gen?.gameplayType ?? null,
+                };
+            });
+            process.stdout.write(JSON.stringify(output) + '\n');
+            return;
+        }
+        for (const entry of matched) {
+            const label = entry.manifest.label.zh || entry.manifest.label.en;
+            console.log(`[${entry.manifest.category}] ${entry.atomId} — ${label}`);
+        }
+    });
+    // ── init-atom-tree ─────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('init-atom-tree')
+        .description('初始化 docs/atom-tree.json（运行 match 填充 meta.skillsMatch，meta.selectedAtoms 待追加）')
+        .requiredOption('--intent <tags>', '意图关键词，逗号或空格分隔（如 mahjong,tile,match 或 "match3 swap gem"）')
+        .option('--engine <name>', '目标引擎（phaser / threejs）；省略则从 intent 推断')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--force', '覆盖已存在的 atom-tree.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);
+        }
+        const entries = loadSkillIndex(dirs);
+        const intentTags = opts.intent
+            .split(/[,\s]+/)
+            .map((t) => t.trim())
+            .filter(Boolean);
+        if (intentTags.length === 0) {
+            console.log('--intent 不能为空。示例：--intent "match3,swap,gem" 或 --intent "match3 swap gem"');
+            console.log('若 atom-tree.json 已存在：playcraft skills init-atom-tree --intent "..." --engine phaser --force');
+            process.exit(1);
+        }
+        const projectDir = path.resolve(opts.projectDir);
+        const docsDir = path.join(projectDir, 'docs');
+        const outputPath = path.join(docsDir, 'atom-tree.json');
+        if (fs.existsSync(outputPath) && !opts.force) {
+            try {
+                const existing = parseAtomTreeJson(fs.readFileSync(outputPath, 'utf-8'));
+                if (!isUninitializedAtomTreeSkeleton(existing)) {
+                    console.log(`${outputPath} 已存在且含用户选择。`);
+                    console.log('下一步：playcraft skills select-atom --id "<atom-ref>" 或 init-atom-tree --force 覆盖');
+                    process.exit(1);
+                }
+            }
+            catch {
+                console.log(`${outputPath} 已存在但无法解析 JSON。使用 --force 覆盖。`);
+                process.exit(1);
+            }
+        }
+        const result = opts.engine
+            ? buildMatchResult(entries, opts.engine, intentTags)
+            : buildAutoMatchResult(entries, intentTags);
+        if (!result.engine) {
+            console.log('无法从 intent 推断运行引擎。请指定：--engine phaser 或 --engine threejs');
+            console.log(`示例：playcraft skills init-atom-tree --intent "${intentTags.join(',')}" --engine phaser --force`);
+            process.exit(1);
+        }
+        const skillsMatch = {
+            engine: result.engine,
+            engineSource: result.engineSource,
+            intent: result.intent,
+            items: result.items.map((i) => ({
+                atomId: i.atomId,
+                label: i.label,
+                layer: i.layer,
+                reason: i.reason,
+                roles: i.roles,
+                hasEngineVariant: i.hasEngineVariant,
+            })),
+            mediaGroups: result.mediaGroups.map((g) => ({
+                role: g.role,
+                label: g.label,
+                layer: g.layer,
+                candidates: g.candidates.map((c) => ({ atomId: c.atomId })),
+            })),
+            ...(result.fusionHints?.length ? { fusionHints: result.fusionHints } : {}),
+        };
+        const tree = buildAtomTreeSkeleton({
+            engine: result.engine,
+            engineSource: result.engineSource,
+            intent: intentTags,
+            skillsMatch,
+            ringsRing1Only: true,
+            selectionRevision: {
+                changes: 'Initial skeleton from playcraft skills init-atom-tree',
+                author: 'cli',
+            },
+        });
+        fs.mkdirSync(docsDir, { recursive: true });
+        fs.writeFileSync(outputPath, JSON.stringify(tree, null, 2) + '\n');
+        console.log(`\n✓ ${outputPath} 已生成`);
+        console.log(`  meta.skillsMatch: ${result.items.length} items + ${result.mediaGroups.length} mediaGroups`);
+        if (result.fusionHints?.length) {
+            console.log(`  meta.skillsMatch.fusionHints: ${result.fusionHints.length} pair(s)`);
+            for (const hint of result.fusionHints) {
+                console.log(`    - ${hint.from} × ${hint.to} → ${hint.recommendedType} (${hint.risk} risk${hint.preferPseudoFusion ? ', prefer pseudo-fusion' : ''})`);
+            }
+        }
+        console.log('  meta.selectedAtoms: [] (使用 playcraft skills select-atom 逐条追加 selected atom ref)\n');
+        console.log('下一步：');
+        console.log('  playcraft remix init-template --from-atom-tree');
+        console.log('  npm install && npm run verify:contract');
+        console.log('  playcraft skills select-atom --id "<selected-atom-ref>"  # 逗号分隔可批量：a,b,c');
+        console.log('  playcraft skills validate-atom-tree-selection');
+        console.log('  playcraft skills link --from-atom-tree --prune\n');
+    });
+    // ── select-atom ────────────────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('select-atom')
+        .description('向 docs/atom-tree.json 的 meta.selectedAtoms 追加 selected atom ref（支持逗号批量），并自动补齐硬依赖')
+        .requiredOption('--id <atomId>', '要加入 meta.selectedAtoms 的 atom ref（逗号分隔可批量，如 phaser.aicomponent,match3_core.aigameplay）')
+        .option('--project-dir <path>', '项目根目录', process.cwd())).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 manifestIndex = loadSkillManifestIndex(dirs);
+        const projectDir = path.resolve(opts.projectDir);
+        const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+        if (!fs.existsSync(jsonPath)) {
+            console.error(`${jsonPath} 不存在。先运行 playcraft skills init-atom-tree。`);
+            process.exit(1);
+        }
+        const tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+        const atomRefs = dedupeAtomRefs(opts.id
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean));
+        if (atomRefs.length === 0) {
+            console.error('atom ref 不能为空。示例：--id "phaser.aicomponent,match3_core.aigameplay"');
+            process.exit(1);
+        }
+        tree.meta.selectedAtoms = dedupeAtomRefs(tree.meta?.selectedAtoms ?? []);
+        const itemIds = dedupeAtomRefs((tree.meta?.skillsMatch?.items ?? []).map((i) => i.atomId));
+        const notInMatch = atomRefs.filter((ref) => itemIds.length > 0 && !itemIds.includes(ref));
+        const toSelect = atomRefs.filter((ref) => !notInMatch.includes(ref));
+        if (notInMatch.length > 0) {
+            console.log(`跳过不在 meta.skillsMatch.items 中的 atom refs: ${notInMatch.join(', ')}`);
+            if (itemIds.length > 0) {
+                console.log(`可用的 atom refs: ${itemIds.join(', ')}`);
+            }
+        }
+        if (toSelect.length === 0) {
+            process.exit(1);
+        }
+        const engine = tree.meta?.skillsMatch?.engine?.trim();
+        if (!engine) {
+            console.log('docs/atom-tree.json 缺少 meta.skillsMatch.engine。');
+            console.log('下一步：playcraft skills init-atom-tree --intent "..." --engine phaser --force');
+            process.exit(1);
+        }
+        let totalAppended = 0;
+        for (const atomRef of toSelect) {
+            if (tree.meta.selectedAtoms.includes(atomRef)) {
+                console.log(`已存在，跳过: ${atomRef}`);
+                continue;
+            }
+            if (!manifestIndex.has(atomRef)) {
+                console.log(`未找到 skill manifest，跳过: ${atomRef}`);
+                continue;
+            }
+            const importedAtomIds = dedupeAtomRefs(collectPinnedDependencies(atomRef, manifestIndex, engine));
+            const missingImportedAtomIds = importedAtomIds.filter((importedAtomId) => !manifestIndex.has(importedAtomId));
+            if (missingImportedAtomIds.length > 0) {
+                console.log(`跳过 ${atomRef}：import 依赖未找到 ${missingImportedAtomIds.join(', ')}`);
+                continue;
+            }
+            const currentSelected = tree.meta.selectedAtoms;
+            const nextAtoms = dedupeAtomRefs([...currentSelected, atomRef, ...importedAtomIds]);
+            const appendedAtomIds = nextAtoms.filter((id) => !currentSelected.includes(id));
+            tree.meta.selectedAtoms = nextAtoms;
+            totalAppended += appendedAtomIds.length;
+            console.log(`✓ 已添加 selected atom ref "${atomRef}"`);
+            if (importedAtomIds.length > 0) {
+                console.log(`  自动补齐硬依赖 imports: ${importedAtomIds.join(', ')}`);
+            }
+            console.log(`  本次新增 ${appendedAtomIds.length} 条：${appendedAtomIds.join(', ')}`);
+        }
+        if (totalAppended === 0) {
+            process.exit(1);
+        }
+        fs.writeFileSync(jsonPath, JSON.stringify(tree, null, 2) + '\n');
+        console.log(`  meta.selectedAtoms 当前共 ${tree.meta.selectedAtoms.length} 条`);
+    });
+    // ── replace-selected-atom ─────────────────────────────────────────────────
+    skills
+        .command('replace-selected-atom')
+        .description('替换 docs/atom-tree.json meta.selectedAtoms 中已有的 selected atom ref')
+        .requiredOption('--id <atomId>', '当前的 atom ref')
+        .requiredOption('--to <atomId>', '替换后的 atom ref')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .action((opts) => {
+        const projectDir = path.resolve(opts.projectDir);
+        const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+        if (!fs.existsSync(jsonPath)) {
+            console.error(`${jsonPath} 不存在。先运行 playcraft skills init-atom-tree。`);
+            process.exit(1);
+        }
+        const tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+        const fromRef = opts.id.trim();
+        const toRef = opts.to.trim();
+        if (!fromRef || !toRef) {
+            console.error('当前 atom ref 与替换后的 atom ref 都不能为空。');
+            process.exit(1);
+        }
+        tree.meta.selectedAtoms ??= [];
+        const idx = tree.meta.selectedAtoms.findIndex((atom) => atom === fromRef);
+        if (idx === -1) {
+            console.error(`atom ref "${fromRef}" 不存在于 meta.selectedAtoms 中。`);
+            console.error(`现有 selectedAtoms: ${tree.meta.selectedAtoms.join(', ')}`);
+            process.exit(1);
+        }
+        if (fromRef !== toRef && tree.meta.selectedAtoms.includes(toRef)) {
+            console.error(`atom ref "${toRef}" 已存在于 meta.selectedAtoms 中。`);
+            process.exit(1);
+        }
+        const itemIds = (tree.meta?.skillsMatch?.items ?? []).map((i) => i.atomId);
+        if (itemIds.length > 0 && !itemIds.includes(toRef)) {
+            console.error(`atom ref "${toRef}" 不在 meta.skillsMatch.items 中。`);
+            console.error(`可用的 atom refs: ${itemIds.join(', ')}`);
+            process.exit(1);
+        }
+        tree.meta.selectedAtoms[idx] = toRef;
+        fs.writeFileSync(jsonPath, JSON.stringify(tree, null, 2) + '\n');
+        console.log(`✓ 已更新 selected atom ref "${fromRef}" → "${toRef}"`);
+    });
+    // ── unselect-atom ──────────────────────────────────────────────────────────
+    skills
+        .command('unselect-atom')
+        .description('从 docs/atom-tree.json 的 meta.selectedAtoms 中删除指定 selected atom ref')
+        .requiredOption('--id <atomId>', '要删除的 atom ref')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .action((opts) => {
+        const projectDir = path.resolve(opts.projectDir);
+        const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+        if (!fs.existsSync(jsonPath)) {
+            console.error(`${jsonPath} 不存在。`);
+            process.exit(1);
+        }
+        const tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+        tree.meta.selectedAtoms ??= [];
+        const idx = tree.meta.selectedAtoms.findIndex((atom) => atom === opts.id);
+        if (idx === -1) {
+            console.error(`atom ref "${opts.id}" 不存在于 meta.selectedAtoms 中。`);
+            console.error(`现有 selectedAtoms: ${tree.meta.selectedAtoms.join(', ')}`);
+            process.exit(1);
+        }
+        tree.meta.selectedAtoms.splice(idx, 1);
+        fs.writeFileSync(jsonPath, JSON.stringify(tree, null, 2) + '\n');
+        console.log(`✓ 已删除 selected atom ref "${opts.id}"`);
+        console.log(`  meta.selectedAtoms 当前共 ${tree.meta.selectedAtoms.length} 条`);
+    });
+    // ── gen-atom-tree-md ───────────────────────────────────────────────────────
+    skills
+        .command('gen-atom-tree-md')
+        .description('从 docs/atom-tree.json 生成/更新 docs/atom-tree.md 阅读指南')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--force', '覆盖已存在的 atom-tree.md')
+        .action((opts) => {
+        const projectDir = path.resolve(opts.projectDir);
+        const jsonPath = path.join(projectDir, 'docs', 'atom-tree.json');
+        const mdPath = path.join(projectDir, 'docs', 'atom-tree.md');
+        if (!fs.existsSync(jsonPath)) {
+            console.error(`${jsonPath} 不存在。先运行 playcraft skills init-atom-tree。`);
+            process.exit(1);
+        }
+        if (fs.existsSync(mdPath) && !opts.force) {
+            console.error(`${mdPath} 已存在。使用 --force 覆盖。`);
+            process.exit(1);
+        }
+        const tree = parseAtomTreeJson(fs.readFileSync(jsonPath, 'utf-8'));
+        const sm = tree.meta?.skillsMatch;
+        const skillRefs = [...new Set(tree.meta?.selectedAtoms ?? [])];
+        let md = '# Atom Tree Reading Guide\n\n';
+        md += '> Canonical machine-readable source: `docs/atom-tree.json`\n\n';
+        md += `> Engine: \`${sm?.engine ?? 'unknown'}\` | Intent: \`${(sm?.intent ?? []).join(', ')}\`\n\n`;
+        md += '## Acceptance Criteria\n\n';
+        md += '| itemId | Criteria |\n| ------ | -------- |\n';
+        for (const ref of skillRefs) {
+            md += `| ${ref} | _TODO_ |\n`;
+        }
+        md += '\n';
+        md += '## Matched Skills Summary\n\n';
+        md += '| skillRef | reuseLevel | purpose | matchReason | keyConstraint | readFirst |\n';
+        md += '| -------- | ---------- | ------- | ----------- | ------------- | --------- |\n';
+        for (const ref of skillRefs) {
+            const item = sm?.items?.find((i) => i.atomId === ref);
+            const label = item?.label?.zh || item?.label?.en || '';
+            md += `| ${ref} | _TODO_ | ${label} | _TODO_ | _TODO_ | _TODO_ |\n`;
+        }
+        md += '\n';
+        md += '## Per-Skill Reading Notes\n\n';
+        for (const ref of skillRefs) {
+            md += `### ${ref}\n\n`;
+            md += '- Purpose: _TODO_\n';
+            md += '- Read First: _TODO_\n';
+            md += '- Watch Out: _TODO_\n\n';
+        }
+        md += '## mediaGroups Disposition\n\n';
+        md += '| candidate | decision | reason | notes |\n';
+        md += '| --------- | -------- | ------ | ----- |\n';
+        for (const group of sm?.mediaGroups ?? []) {
+            for (const c of group.candidates) {
+                md += `| ${c.atomId} | _TODO_ | ${group.label} | |\n`;
+            }
+        }
+        md += '\n';
+        md += '## Gaps\n\n';
+        md += '| need | whyNoMatch |\n| ---- | ---------- |\n';
+        md += '| _none identified_ | |\n\n';
+        fs.writeFileSync(mdPath, md);
+        console.log(`✓ 已生成 ${mdPath}`);
+        console.log(`  selectedAtoms: ${skillRefs.length} | mediaGroups: ${(sm?.mediaGroups ?? []).length}`);
+    });
 }