@morehao/dsh-skills-console 0.3.8 → 0.4.0

package/lib/core/exporter.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureLink, inspectTarget, removeLink } from './links.js';
+
+/**
+ * 导出（export）= 把 canonical 里的技能显式暴露给**不读共享根**的其他 agent。
+ *
+ * 与 v1 的「接入/链接」的区别只有三条，但每条都改变行为：
+ * - 默认不导出任何 agent（`settings.exportTargets` 默认 `[]`）；
+ * - DSH 自己的扫描根不参与导出（`~/.dsh/skills` 是停用桩的位置，不是可见性通道）；
+ * - 只有「建链真的成功/已受管」才记账；删链失败不清账。
+ */
+
+/** 建链失败的统一形状：由调用方决定是 400 还是只记 warning。 */
+function failure(target, reason, extra = {}) {
+  return { target, reason, ...extra };
+}
+
+/**
+ * 逐 agent 导出。`record` 只在本次真的存在一条指向 canonical 的链时被调用
+ * （新建的、或此前已受管但没记账的「接管」场景），避免账本里出现不存在的链。
+ */
+export function exportSkills({ paths, registry, name, targets = [], record = () => {} }) {
+  const canonicalPath = path.join(paths.canonical, name);
+  const result = { created: [], skipped: [], failed: [] };
+  if (!fs.existsSync(canonicalPath)) {
+    result.failed.push(failure('*', 'not-installed'));
+    return result;
+  }
+
+  const seen = new Set();
+  for (const target of targets) {
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+
+    let resolved;
+    try {
+      resolved = registry.resolve(target);
+    } catch {
+      result.failed.push(failure(target, 'unknown-target'));
+      continue;
+    }
+    // 导出资格由注册表统一算好（扫描根 / 共享根 / 共享 home 三种原因），
+    // 这里不再按 kind 判断身份 —— 以后宿主多一个扫描根，只需要改 roots 一张表。
+    if (resolved.exportBlocked) {
+      result.skipped.push({ target, reason: resolved.exportBlocked });
+      continue;
+    }
+    if (!resolved.exists) {
+      result.failed.push(failure(target, 'target-missing', { dir: resolved.dir }));
+      continue;
+    }
+
+    const linkPath = path.join(resolved.dir, name);
+    const outcome = ensureLink({ linkPath, canonicalPath });
+    if (outcome.created) {
+      result.created.push({ target, linkPath, mode: outcome.mode || 'relative' });
+      record({ target, agentDir: resolved.dir, linkPath, mode: outcome.mode || 'relative', created: true });
+      continue;
+    }
+    if (outcome.state === 'managed' || outcome.state === 'managed-external') {
+      result.skipped.push({ target, reason: outcome.state, linkPath });
+      record({ target, agentDir: resolved.dir, linkPath, mode: outcome.mode || 'relative', created: false });
+      continue;
+    }
+    result.skipped.push({ target, reason: outcome.state, linkPath });
+  }
+  return result;
+}
+
+/**
+ * 摘掉一条导出链。默认只摘「指向 canonical」的；`allowDangling` 用于 canonical
+ * 已经不在时回收自家悬空链——此时用链名兜底，绝不按 `force` 整片删。
+ */
+export function unexportSkill({ linkPath, canonicalPath, name, allowDangling = false }) {
+  if (!linkPath) return { removed: false, reason: 'no-path' };
+  const direct = removeLink({ linkPath, canonicalPath, force: false });
+  if (direct.removed) return { removed: true, linkPath };
+  if (direct.reason !== 'not-managed' || !canonicalPath) return { ...direct, linkPath };
+
+  if (!allowDangling) return { ...direct, linkPath };
+  const dangling = isOurDanglingLink(linkPath, name);
+  if (!dangling) return { removed: false, reason: 'not-managed', linkPath };
+  const forced = removeLink({ linkPath, canonicalPath, force: true });
+  return { ...forced, linkPath, dangling: true };
+}
+
+/** 链还在、但目标已经不存在，且链名对得上 —— 只在这种情况下允许强制回收。 */
+export function isOurDanglingLink(linkPath, name) {
+  let st;
+  try {
+    st = fs.lstatSync(linkPath);
+  } catch {
+    return false;
+  }
+  if (!st.isSymbolicLink()) return false;
+  let raw;
+  try {
+    raw = fs.readlinkSync(linkPath);
+  } catch {
+    return false;
+  }
+  const normalized = raw.split(path.sep).join('/');
+  return normalized.endsWith(`/skills/${name}`) || path.basename(normalized) === name;
+}
+
+/**
+ * 汇总一条技能在各 agent 目录里的**导出**现场（`/state` 的 `installs[].exports`）。
+ *
+ * 只认「指向 canonical 的链接」：`foreign-link` 指向别的副本、`real` 是本地实体目录，
+ * 都不代表这份技能被导出过去。读共享根的 Agent 也不需要导出链——它们装好即见，
+ * 现场残留的链（历史版本或手工建的）同样不列。
+ */
+export function agentPresence({ paths, registry, name }) {
+  const canonicalPath = path.join(paths.canonical, name);
+  const rows = [];
+  for (const entry of registry.detected()) {
+    // DSH 的扫描根没有「导出态」：那里要么是真身、要么是停用桩，不列进 Agent 现场
+    if (entry.exportBlocked === 'dsh-native-root') continue;
+    // 读共享根的 Agent 不走导出这条路；把它的链算成导出会误导「为什么它在导出清单里」
+    if (entry.exportBlocked === 'shared-root') continue;
+    const linkPath = path.join(entry.dir, name);
+    const live = inspectTarget({ linkPath, canonicalPath });
+    // 只有真的指向 canonical 的链才算导出（未记账的 managed-external 仍保留：
+    // 它是「现场有、可接管」的导出，不是别人的东西）
+    if (live.state !== 'managed' && live.state !== 'managed-external') continue;
+    rows.push({
+      target: entry.target,
+      label: entry.label,
+      dir: entry.dir,
+      linkPath,
+      state: live.state,
+      broken: Boolean(live.broken),
+    });
+  }
+  return rows;
+}

package/lib/core/inventory.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { contentHash } from './hash.js';
-import { inspectTarget } from './links.js';
+import { agentPresence } from './exporter.js';
 
 /**
  * CLI 全局 lock（v3）。读不到、版本不认识、结构损坏都返回空账 ——
@@ -75,13 +75,13 @@ export function readFrontmatterDescription(skillPath) {
   }
 }
 
-function statusOf({ install, check, locallyModified, brokenLinks, subscribed }) {
+function statusOf({ install, check, locallyModified, brokenExports, subscribed }) {
   if (!install) return 'unmanaged';
   if (locallyModified && check?.status === 'update-available') return 'conflict';
   if (locallyModified) return 'locally-modified';
   if (check?.status === 'upstream-deleted') return 'upstream-deleted';
   if (check?.status === 'update-available') return 'update-available';
-  if (brokenLinks.length > 0) return 'broken-link';
+  if (brokenExports.length > 0) return 'broken-link';
   if (check?.status === 'current') return 'current';
   // 没有可用的上游订阅 = 永远拿不到更新结论（检查更新只覆盖有订阅的技能）。
   // 这跟「这次没判定出来」是两件事，混进 unknown 会让待检查计数永远降不下来。
@@ -90,42 +90,44 @@ function statusOf({ install, check, locallyModified, brokenLinks, subscribed })
 }
 
 /**
- * 右栏账本：canonical + installs + links。左栏（模型可见）由调用方从 `ctx.skills.snapshot` 取。
- * 两侧差异本身就是诊断数据，不做自动修复。
+ * 右栏账本：canonical + installs + exports + legacyShadows。
+ * 左栏（模型可见）由 `visibility.js` 扫根 + policy 判定得出，两侧差异就是诊断数据，
+ * 不做自动修复。
  */
-export function buildLedger({ paths, state, registry, lock, visibleNames = new Map() }) {
+export function buildLedger({ paths, state, registry, lock, visibility, now = new Date().toISOString() }) {
   const scanned = scanCanonical(paths);
-  const targets = registry.detected();
   const installs = new Map(state.installs.map((item) => [item.name, item]));
-  // 只有「state 里真有这条订阅记录」才算可检查：订阅被删掉（keepInstalled）后
-  // install.subscriptionId 会指向一个不存在的 id，那种行同样永远等不到结论。
   const subscriptions = new Set((state.subscriptions || []).map((item) => item.id));
+  const exportsBySkill = new Map();
+  for (const row of state.exports || []) {
+    const list = exportsBySkill.get(row.skill);
+    if (list) list.push(row);
+    else exportsBySkill.set(row.skill, [row]);
+  }
 
   const rows = scanned.map((entry) => {
     const install = installs.get(entry.name);
     const lockEntry = lock.skills?.[entry.name] || null;
-    const recordLinks = state.links.filter((link) => link.skill === entry.name);
+    const recordExports = exportsBySkill.get(entry.name) || [];
+    const presence = agentPresence({ paths, registry, name: entry.name });
 
-    // 期望接入矩阵：已有记录 + 各探测目录的现场状态
-    const links = [];
-    for (const target of targets) {
-      const linkPath = path.join(target.dir, entry.name);
-      const live = inspectTarget({ linkPath, canonicalPath: entry.path });
-      if (live.state === 'absent') continue;
-      const recorded = recordLinks.find((link) => link.target === target.target);
-      const stateName =
-        live.state === 'managed-external' && recorded ? 'managed' : live.state;
-      links.push({
-        target: target.target,
-        label: target.label,
-        linkPath,
-        state: stateName,
+    // 导出矩阵：账本里的记录 + 各 agent 目录里真的指向 canonical 的链
+    // （`agentPresence` 已滤掉 foreign-link / real / 共享根 Agent，它们都不算导出）
+    const exportsRows = [];
+    for (const item of presence) {
+      const recorded = recordExports.find((row) => row.target === item.target) || null;
+      exportsRows.push({
+        target: item.target,
+        label: item.label,
+        dir: item.dir,
+        linkPath: item.linkPath,
+        state: recorded && item.state === 'managed-external' ? 'managed' : item.state,
         recorded: Boolean(recorded),
-        broken: Boolean(live.broken),
+        broken: Boolean(item.broken),
       });
     }
 
-    const brokenLinks = links.filter((link) => link.broken);
+    const brokenExports = exportsRows.filter((item) => item.broken);
     let currentHash = null;
     let locallyModified = false;
     if (install && entry.kind === 'dir') {
@@ -134,8 +136,14 @@ export function buildLedger({ paths, state, registry, lock, visibleNames = new M
     }
 
     const check = state.checks?.[entry.name] || null;
-    const visibleSource = visibleNames.get(entry.name);
+    const visible = visibility?.byName?.get(entry.name) || null;
     const subscribed = Boolean(install?.subscriptionId) && subscriptions.has(install.subscriptionId);
+    const enabled = install ? install.enabled !== false : true;
+    // 只要存在 winner 就判「赢的是不是这一份」：技能自己声明 manual-only 时也不可见，
+    // 但它确实在扫描根里，不能被 UI 说成「扫描目录里没有它」。
+    const winnerIsCanonical = visible?.winnerPath
+      ? path.resolve(visible.winnerPath) === path.resolve(entry.path)
+      : null;
     return {
       name: entry.name,
       path: entry.path,
@@ -157,25 +165,51 @@ export function buildLedger({ paths, state, registry, lock, visibleNames = new M
       currentHash,
       installedAt: install?.installedAt ?? null,
       updatedAt: install?.updatedAt ?? null,
-      mode: install?.mode ?? 'on',
-      scopeProjects: install?.scopeProjects ?? [],
-      backup: install?.backup ?? null,
-      links,
-      brokenLinks: brokenLinks.length,
-      status: statusOf({ install, check, locallyModified, brokenLinks, subscribed }),
+      enabled,
+      /** @deprecated v2 起用 `enabled`；留着只为一份 minor 内的缓存客户端不白屏 */
+      mode: enabled ? 'on' : 'off',
+      exports: exportsRows,
+      brokenExports: brokenExports.length,
+      status: statusOf({ install, check, locallyModified, brokenExports, subscribed }),
       check,
-      visible: visibleNames.has(entry.name),
-      visibleSource: visibleSource ?? null,
-      note: entry.kind === 'broken' ? 'canonical 里是一个悬空链接' : entry.hasSkillFile ? null : '缺少 SKILL.md，DSH 无法解析',
+      visible: Boolean(visible?.visible),
+      visibleSource: visible?.winnerSource ?? null,
+      visibility: {
+        dsh: Boolean(visible?.visible),
+        shadowed: Boolean(visible?.shadowed),
+        winnerSource: visible?.winnerSource ?? null,
+        sources: visible?.sources ?? {},
+        winnerPath: visible?.winnerPath ?? null,
+        // 模型看到的那份不是这一份（同名副本在更小的 rank 上，例如 `x.bak-2026…/`）
+        winnerIsCanonical,
+        nameConflict: Boolean(visible?.nameConflict),
+        shadowedBy: visible?.shadowedBy ?? [],
+        // 被本地策略停用（键名保留一版，客户端文案已同步）
+        policyHidden: !enabled && Boolean(visible?.policyHidden),
+        // canonical 自己在 frontmatter 里声明 disable-model-invocation：
+        // 只影响模型调用，`/` 手动调用仍可用，不是「技能丢了」。
+        selfHidden: Boolean(visible?.foreignHidden && winnerIsCanonical === true),
+        hiddenBy: visible?.hiddenBy ?? [],
+        // 界面停用、但更靠前的同名副本仍然可见（项目 100/200 或 user-dsh 400）：
+        // 这条差异必须让 UI 说得出来。键名保留一版，语义改为「停用不了副本」。
+        shadowScopeMismatch: !enabled && winnerIsCanonical === false,
+      },
+      note: entry.kind === 'broken'
+        ? 'canonical 里是一个悬空链接'
+        : entry.hasSkillFile
+          ? null
+          : '缺少 SKILL.md，DSH 无法解析',
+      scannedAt: now,
     };
   });
 
   // 左栏有、右栏无：别人装的 / 别的 root 里的
   const visibleOnly = [];
-  for (const [name, source] of visibleNames.entries()) {
+  for (const [name, item] of visibility?.byName || []) {
+    if (!item.visible) continue;
     if (rows.some((row) => row.name === name)) continue;
-    visibleOnly.push({ name, source });
+    visibleOnly.push({ name, source: item.winnerSource, path: item.path, hostOnly: item.hostOnly });
   }
 
-  return { rows, visibleOnly, scannedAt: new Date().toISOString() };
+  return { rows, visibleOnly, scannedAt: now };
 }

package/lib/core/migrations.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { removeLink } from './links.js';
+import { reapShadowLeftovers, removeShadow } from './shadow.js';
+
+/**
+ * 状态迁移的**文件侧**执行。结构改写已经在 `state.upgradeStateV1` / `upgradeStateV2`
+ * 做完并落盘，这里只按 migration / legacyShadows 做幂等收尾：
+ *
+ * 1. v1 遗留：删掉历史上为了「提升 rank」而建的 DSH 侧链接，剪掉悬空导出记录；
+ *    **不再补建停用桩**（v0.4.0 起启停是 policy provider 的事）。
+ * 2. v2→v3：逐条清理 `legacyShadows[]` 里的旧停用桩。删不掉（foreign / link / locked）
+ *    的保留并写原因；`orphan` 不删（删了会让原本隐藏的技能突然可见）；`project:*`
+ *    只清理桩，不转成全局停用。
+ * 3. 写 manifest（`v1-to-v3-*` / `v2-to-v3-*`，planned → done），7 天后清理。
+ *
+ * 不做的事：不删外来链、不删真实目录、不动 canonical、不动 v3 lock。
+ */
+
+const MANIFEST_VERSION = 2;
+const BACKUP_KEEP_DAYS = 7;
+
+/** orphan 与「删失败」的行会留在 legacyShadows，等用户手动处理或启用时再清。 */
+function manifestName(migration, now) {
+  const prefix = migration?.from === 1 ? 'v1-to-v3' : 'v2-to-v3';
+  return `${prefix}-${now.replace(/[:.]/g, '-')}.json`;
+}
+
+function writeManifest(paths, file, payload) {
+  try {
+    fs.mkdirSync(paths.migrationsDir, { recursive: true });
+    fs.writeFileSync(path.join(paths.migrationsDir, file), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    return path.join(paths.migrationsDir, file);
+  } catch {
+    return null;
+  }
+}
+
+function isMigrationManifest(name) {
+  return name.startsWith('v1-to-') || name.startsWith('v2-to-');
+}
+
+/** 清理过期的迁移清单（默认 7 天）。state-v<n> 的原始状态副本不在清理范围内。 */
+export function pruneMigrationBackups({ paths, now = Date.now() }) {
+  let entries;
+  try {
+    entries = fs.readdirSync(paths.migrationsDir);
+  } catch {
+    return [];
+  }
+  const removed = [];
+  for (const name of entries) {
+    if (!isMigrationManifest(name)) continue;
+    const file = path.join(paths.migrationsDir, name);
+    try {
+      const stat = fs.statSync(file);
+      if (now - stat.mtimeMs > BACKUP_KEEP_DAYS * 24 * 3600 * 1000) {
+        fs.rmSync(file, { force: true });
+        removed.push(name);
+      }
+    } catch {
+      /* 忽略 */
+    }
+  }
+  return removed;
+}
+
+/** 旧桩删除结果 → legacyShadows 里保留的原因。 */
+function keepReason(outcome) {
+  if (!outcome) return 'locked';
+  if (outcome.reason === 'not-managed') return 'foreign';
+  if (outcome.reason === 'absent') return 'absent';
+  return outcome.reason || 'locked';
+}
+
+/**
+ * 执行（或继续执行）迁移。返回 `{ ok, migrated, report }`。
+ * 任何一步失败都不回滚已完成的步骤——每一步本身是幂等的，下次启动接着做。
+ */
+export function ensureMigrated({ paths, store, logger = () => {} }) {
+  const migration = store.state.migration;
+  if (!migration || migration.status === 'done') return { ok: true, migrated: false };
+  if (store.readOnly) return { ok: false, migrated: false, reason: 'state-readonly' };
+
+  const now = new Date().toISOString();
+  const report = {
+    version: MANIFEST_VERSION,
+    at: now,
+    from: migration.from ?? 2,
+    to: 3,
+    phase: 'planned',
+    linksRemoved: [],
+    linksKept: [],
+    exportsPruned: [],
+    legacyScopeProjectsDropped: [],
+    legacyShadowsRemoved: [],
+    legacyShadowsKept: [],
+    legacyShadowsOrphans: [],
+  };
+  const manifest = manifestName(migration, now);
+  writeManifest(paths, manifest, report);
+
+  // ① v1 遗留：删历史 DSH 侧链接：只删「指向 canonical 的同名链」，外来链/真实目录一律放过
+  for (const link of migration.legacyLinks || []) {
+    if (!link || typeof link.linkPath !== 'string') continue;
+    const canonicalPath = path.join(paths.canonical, link.skill);
+    const result = removeLink({ linkPath: link.linkPath, canonicalPath, force: false });
+    if (result.removed) report.linksRemoved.push(link.linkPath);
+    else report.linksKept.push({ linkPath: link.linkPath, skill: link.skill, reason: result.reason });
+  }
+
+  // ② 剪悬空导出记录：磁盘上没有这条链，就不要留在账上
+  const aliveExports = [];
+  for (const row of store.state.exports || []) {
+    if (row.linkPath && fs.existsSync(row.linkPath)) aliveExports.push(row);
+    else report.exportsPruned.push(row.linkPath || `${row.target}:${row.skill}`);
+  }
+
+  // ③ v1 遗留的 legacyScopeProjects 只记账后丢弃：项目级启停已移除（设计 §4.4.1）
+  const installs = (store.state.installs || []).map((install) => {
+    const next = { ...install };
+    if (Array.isArray(next.legacyScopeProjects) && next.legacyScopeProjects.length > 0) {
+      report.legacyScopeProjectsDropped.push({ name: next.name, roots: [...next.legacyScopeProjects] });
+    }
+    delete next.legacyScopeProjects;
+    return next;
+  });
+
+  // ④ v2→v3：清理旧停用桩（成功就消失，失败/orphan 留在 legacyShadows）
+  const legacyShadows = [];
+  for (const row of store.state.legacyShadows || []) {
+    if (row.reason === 'orphan') {
+      legacyShadows.push(row);
+      report.legacyShadowsOrphans.push({ skill: row.skill, stubPath: row.stubPath });
+      continue;
+    }
+    const outcome = removeShadow({ stubPath: row.stubPath, name: row.skill });
+    if (outcome.removed || outcome.reason === 'absent') {
+      report.legacyShadowsRemoved.push({ skill: row.skill, stubPath: row.stubPath, via: outcome.reason || 'removed' });
+      continue;
+    }
+    const kept = { ...row, reason: keepReason(outcome) };
+    legacyShadows.push(kept);
+    report.legacyShadowsKept.push({ skill: row.skill, stubPath: row.stubPath, reason: kept.reason });
+    logger('migration.legacy-shadow.kept', { skill: row.skill, stubPath: row.stubPath, reason: kept.reason });
+  }
+
+  store.update((draft) => {
+    draft.installs = installs;
+    draft.exports = aliveExports;
+    draft.legacyShadows = legacyShadows;
+    draft.migration = {
+      ...(draft.migration || {}),
+      from: migration.from ?? 2,
+      to: 3,
+      status: 'done',
+      completedAt: now,
+    };
+  });
+
+  report.phase = 'done';
+  report.completedAt = now;
+  writeManifest(paths, manifest, report);
+  pruneMigrationBackups({ paths });
+  // 以前中断留下的 `.shadow-*` 残骸，顺手清掉
+  reapShadowLeftovers(paths.dshGlobalSkills);
+  logger('state.migrated', {
+    from: report.from,
+    linksRemoved: report.linksRemoved.length,
+    linksKept: report.linksKept.length,
+    exports: aliveExports.length,
+    exportsPruned: report.exportsPruned.length,
+    legacyShadowsRemoved: report.legacyShadowsRemoved.length,
+    legacyShadowsKept: report.legacyShadowsKept.length,
+    legacyShadowsOrphans: report.legacyShadowsOrphans.length,
+  });
+  return { ok: true, migrated: true, report };
+}

package/lib/core/paths.js

@@ -12,6 +12,11 @@ export function createPaths(env = process.env, overrides = {}) {
   const dshHome = overrides.dshHome ?? env.DSH_HOME ?? path.join(home, '.dsh');
   const stateDir =
     overrides.stateDir ?? env.DSH_SKILLS_CONSOLE_HOME ?? path.join(dshHome, 'skills-console');
+  // 宿主 user-agents 扫描根。默认 `~/.agents`；DSH_AGENTS_HOME 指到别处时 canonical
+  // 就不在宿主的扫描根里了 —— 这种环境本插件不提供可见性兜底（/diagnostics 会报
+  // `canonical-not-scanned`），所以这个标志只用于如实告知，不再用来切换机制。
+  const defaultAgentsHome = path.join(home, '.agents');
+  const agentsHome = overrides.agentsHome ?? env.DSH_AGENTS_HOME ?? defaultAgentsHome;
   // 与 skills CLI 的 getSkillLockPath 对齐：设了 XDG_STATE_HOME 时 lock 在 XDG 下
   const lockFile = env.XDG_STATE_HOME
     ? path.join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json')
@@ -22,14 +27,22 @@ export function createPaths(env = process.env, overrides = {}) {
     configHome,
     dshHome,
     stateDir,
+    /** 宿主 user-agents 扫描根（rank 500 的父目录） */
+    agentsHome,
+    /** 宿主 user-agents 技能根（rank 500）：`<agentsHome>/skills` */
+    userAgentsSkills: path.join(agentsHome, 'skills'),
     /** canonical 真身：CLI 唯一的落点（F1） */
     canonical: path.join(home, '.agents', 'skills'),
+    /** canonical 是否就是宿主的 user-agents 扫描根（否则本插件不保证 DSH 可见性） */
+    canonicalScanned: path.resolve(agentsHome) === path.resolve(defaultAgentsHome),
     /** CLI 全局 lock（F4）；XDG_STATE_HOME 优先，与 CLI 一致 */
     lockFile,
     /** DSH 原生 user-dsh 根（rank 400） */
     dshGlobalSkills: path.join(dshHome, 'skills'),
     stateFile: path.join(stateDir, 'state.json'),
     backupsDir: path.join(stateDir, 'backups'),
+    /** state 迁移的备份与 manifest（v1 → v2），与技能备份分开存 */
+    migrationsDir: path.join(stateDir, 'migrations'),
     trashDir: path.join(stateDir, 'trash'),
     logFile: path.join(stateDir, 'dsh-skills-console.log'),
   };