@yottameta/yotta-skills-plugin 0.29.3 → 0.29.5

package/skills/yotta-skills/lib/hub-view-server.js

@@ -36,6 +36,8 @@ const cliHelpLib = require('./cli-help');
 const hostsRegistryLib = require('./hosts-registry');
 const hostPurgeLib = require('./host-purge');
 const skillsConfigLib = require('./skills-config');
+const hubMigrateLib = require('./hub-migrate');
+const hubTargetsLib = require('./hub-targets');
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8789;
@@ -149,6 +151,16 @@ function discovery(ctx) {
   return discoveryLib.discoverHosts({ homeDir: ctx.homeDir, env: ctx.env });
 }
 
+/** 迁移 / 回滚的重链范围（与 CLI hub link --all 同源，只取存在的目录）。 */
+function migrationTargets(ctx, excludeDirs) {
+  const skip = (excludeDirs || []).filter(Boolean);
+  return hubTargetsLib.computeHubTargets({
+    discovery: discovery(ctx),
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  }).filter((item) => fs.existsSync(item.dir) && !skip.some((dir) => sameDir(item.dir, dir)));
+}
+
 function scanEngineInfo(ctx, found) {
   const engine = hubScanLib.scanEngineForHub(ctx.hubDir, found, { python: ctx.python, verify: ctx.verify });
   if (!engine) return { available: false, path: null };
@@ -166,6 +178,22 @@ function overviewPayload(ctx) {
   });
   const audit = readJsonlTail(hubAuditPath(ctx.hubDir), 8);
   const hubNow = skillsConfigLib.resolveHub({ homeDir: ctx.homeDir, env: ctx.env });
+  const config = skillsConfigLib.readConfig({ homeDir: ctx.homeDir, env: ctx.env });
+  const lastMigration = config.lastMigration
+    ? { ...config.lastMigration, daysLeft: hubMigrateLib.trashDaysLeft(config.lastMigration.at) }
+    : null;
+  let switchPending = null;
+  if (config.lastSwitch && !sameDir(config.lastSwitch.from, ctx.hubDir)) {
+    const oldSkills = hubLib.countHubSkills(config.lastSwitch.from);
+    if (oldSkills > 0) {
+      switchPending = {
+        from: config.lastSwitch.from,
+        to: config.lastSwitch.to,
+        at: config.lastSwitch.at,
+        skills: oldSkills,
+      };
+    }
+  }
   return {
     version: ctx.version,
     hubDir: ctx.hubDir,
@@ -195,6 +223,47 @@ function overviewPayload(ctx) {
     },
     doctor: { ok: doctor.ok, summary: doctor.summary, checks: doctor.checks },
     audit: { count: audit.entries.length, recent: audit.entries, invalid: audit.invalid },
+    // 0.29.5 S1/S2：最近一次迁移 + 未迁移提示（面板迁移向导 / 一键回滚数据源）。
+    migration: {
+      last: lastMigration,
+      lastSwitch: config.lastSwitch,
+      switchPending,
+      trashRetentionDays: hubLib.TRASH_RETENTION_DAYS,
+    },
+  };
+}
+
+/** GET /api/hub/config：Hub 位置 + 最近迁移 + 回滚预览（只读）。 */
+function hubConfigPayload(ctx) {
+  const configOpts = { homeDir: ctx.homeDir, env: ctx.env };
+  const resolvedNow = skillsConfigLib.resolveHub(configOpts);
+  const resolved = ctx.hubFlag
+    ? {
+        dir: ctx.hubDir,
+        source: 'flag',
+        configured: resolvedNow.configured,
+        configFile: resolvedNow.configFile,
+        defaultDir: resolvedNow.defaultDir,
+      }
+    : resolvedNow;
+  const config = skillsConfigLib.readConfig(configOpts);
+  const rollback = hubMigrateLib.previewRollback({
+    configOpts,
+    env: ctx.env,
+    currentDir: ctx.hubFlag ? ctx.hubDir : null,
+  });
+  return {
+    hub: resolved.dir,
+    source: resolved.source,
+    configured: resolved.configured,
+    configFile: resolved.configFile,
+    defaultDir: resolved.defaultDir,
+    lastMigration: config.lastMigration
+      ? { ...config.lastMigration, daysLeft: hubMigrateLib.trashDaysLeft(config.lastMigration.at) }
+      : null,
+    lastSwitch: config.lastSwitch,
+    rollback,
+    trashRetentionDays: hubLib.TRASH_RETENTION_DAYS,
   };
 }
 
@@ -686,7 +755,12 @@ function writeHostInclude(ctx, body) {
   return { code: 200, payload: { action: 'hosts.include', removed: result.removed } };
 }
 
-/** 0.29.2 U4：面板「Hub 位置」设置 / 清除（写 config.json；重启 view 生效）。 */
+/**
+ * 0.29.2 U4：面板「Hub 位置」设置 / 清除；0.29.5 S1/S2 升级为迁移向导 + 一键回滚：
+ * - mode=move（默认）：复用 CLI `--move` 同一内核（复制校验 → 切配置 → 重链 → 回收站）。
+ * - mode=switch：仅切换指针；旧 Hub 有内容时记录 lastSwitch（面板横幅提示未迁移）。
+ * - body.rollback=true：一键回滚（位置回退，用当前内容；反向迁移同内核）。
+ */
 function writeHubConfig(ctx, body) {
   if (String(body.confirm || '') !== CONFIRM.hubConfig) {
     return { code: 400, payload: { error: '确认串不匹配（需要 "' + CONFIRM.hubConfig + '"）。' } };
@@ -703,24 +777,180 @@ function writeHubConfig(ctx, body) {
     }
     return { code: 200, payload: { action: 'config.clear', removed: result.removed, restartRequired: true } };
   }
+
+  if (body.rollback) return writeHubRollback(ctx, configOpts, body);
+
   const hub = String(body.hub || '').trim();
   const guard = skillsConfigLib.validateHubPath(hub, configOpts);
   if (!guard.ok) return { code: 400, payload: { error: guard.error } };
-  const result = skillsConfigLib.setHub(configOpts, { hub });
-  if (!result.ok) return { code: 400, payload: { error: result.error } };
-  const auditDir = fs.existsSync(result.hub) ? result.hub : current.dir;
+  const target = guard.dir;
+  const mode = body.mode === 'switch' ? 'switch' : 'move';
+  // 仅允许「迁移未迁移的旧 Hub → 当前位置」使用显式 from（必须命中 lastSwitch 记录），
+  // 不接受任意目录作为迁移源。
+  let migrationFrom = current.dir;
+  const fromOverride = String(body.from || '').trim();
+  if (mode === 'move' && fromOverride) {
+    const config = skillsConfigLib.readConfig(configOpts);
+    const pending = config.lastSwitch;
+    if (!pending || !sameDir(pending.from, fromOverride)) {
+      return {
+        code: 400,
+        payload: { error: 'from 只能指向面板记录的「未迁移旧 Hub」（' + (pending ? pending.from : '当前无记录') + '）。' },
+      };
+    }
+    migrationFrom = path.resolve(fromOverride);
+  }
+  if (mode === 'move' && sameDir(target, migrationFrom)) {
+    return { code: 400, payload: { error: '新旧 Hub 路径相同：' + target } };
+  }
+
+  if (mode === 'switch') {
+    if (sameDir(target, current.dir)) {
+      return { code: 400, payload: { error: '新旧 Hub 路径相同：' + target } };
+    }
+    const result = skillsConfigLib.setHub(configOpts, { hub: target });
+    if (!result.ok) return { code: 400, payload: { error: result.error } };
+    const oldSkills = hubLib.countHubSkills(current.dir);
+    if (oldSkills > 0) {
+      skillsConfigLib.recordLastSwitch(configOpts, {
+        from: current.dir,
+        to: target,
+        at: nowIso(),
+        skills: oldSkills,
+        via: 'view',
+      });
+    }
+    const auditDir = fs.existsSync(target) ? target : current.dir;
+    if (fs.existsSync(auditDir)) {
+      try {
+        hubLib.appendAudit(auditDir, {
+          event: 'config.set',
+          hub: target,
+          previousHub: current.dir,
+          moved: false,
+          via: 'view',
+        });
+      } catch (_) { /* best-effort */ }
+    }
+    return {
+      code: 200,
+      payload: {
+        action: 'config.set',
+        mode: 'switch',
+        hub: target,
+        previous: current.dir,
+        configFile: result.configFile,
+        oldSkills,
+        restartRequired: true,
+      },
+    };
+  }
+
+  const migration = hubMigrateLib.runHubMigration({
+    from: migrationFrom,
+    to: target,
+    targets: migrationTargets(ctx, [target, migrationFrom]),
+    manifest: ctx.manifest,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+    configOpts,
+    via: 'view',
+    cleanResidue: Boolean(body.cleanResidue),
+  });
+  if (!migration.ok && migration.phase !== 'relink') {
+    return {
+      code: migration.code === 'target-residue' ? 409 : 400,
+      payload: {
+        error: migration.error,
+        code: migration.code,
+        target: migration.target || null,
+      },
+    };
+  }
+  const auditDir = fs.existsSync(target) ? target : current.dir;
   if (fs.existsSync(auditDir)) {
     try {
-      hubLib.appendAudit(auditDir, { event: 'config.set', hub: result.hub, previousHub: current.dir, via: 'view' });
+      hubLib.appendAudit(auditDir, {
+        event: 'config.set',
+        hub: target,
+        previousHub: current.dir,
+        moved: true,
+        incomplete: migration.report.incomplete,
+        via: 'view',
+      });
     } catch (_) { /* best-effort */ }
   }
   return {
     code: 200,
     payload: {
       action: 'config.set',
-      hub: result.hub,
+      mode: 'move',
+      hub: target,
       previous: current.dir,
-      configFile: result.configFile,
+      configFile: skillsConfigLib.resolveHub(configOpts).configFile,
+      move: migration.report,
+      restartRequired: true,
+    },
+  };
+}
+
+/** 面板一键回滚：预览 → 反向迁移（位置回退，用当前内容；同内核）。 */
+function writeHubRollback(ctx, configOpts, body) {
+  const preview = hubMigrateLib.previewRollback({
+    configOpts,
+    env: ctx.env,
+    currentDir: ctx.hubFlag ? ctx.hubDir : null,
+  });
+  if (!preview.ok) {
+    return {
+      code: 400,
+      payload: {
+        error: preview.error || ('回滚被阻断：' + (preview.blocked || []).join('；')),
+        preview,
+      },
+    };
+  }
+  const migration = hubMigrateLib.runHubMigration({
+    from: preview.current,
+    to: preview.target,
+    kind: 'rollback',
+    targets: migrationTargets(ctx, [preview.current, preview.target]),
+    manifest: ctx.manifest,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+    configOpts,
+    via: 'view',
+    cleanResidue: Boolean(body.cleanResidue),
+  });
+  if (!migration.ok && migration.phase !== 'relink') {
+    return {
+      code: migration.code === 'target-residue' ? 409 : 400,
+      payload: {
+        error: migration.error,
+        code: migration.code,
+        target: migration.target || null,
+      },
+    };
+  }
+  const auditDir = fs.existsSync(preview.target) ? preview.target : preview.current;
+  if (fs.existsSync(auditDir)) {
+    try {
+      hubLib.appendAudit(auditDir, {
+        event: 'config.rollback',
+        hub: preview.target,
+        previousHub: preview.current,
+        incomplete: migration.report.incomplete,
+        via: 'view',
+      });
+    } catch (_) { /* best-effort */ }
+  }
+  return {
+    code: 200,
+    payload: {
+      action: 'config.rollback',
+      hub: preview.target,
+      previous: preview.current,
+      move: migration.report,
       restartRequired: true,
     },
   };
@@ -865,6 +1095,7 @@ function handleGet(ctx, pathname, url, res) {
   }
   if (pathname === '/api/records') return json(res, 200, recordsPayload(ctx, queryLimit(url)));
   if (pathname === '/api/rollback/list') return json(res, 200, rollbackListPayload(ctx, queryLimit(url)));
+  if (pathname === '/api/hub/config') return json(res, 200, hubConfigPayload(ctx));
   if (pathname === '/api/route') {
     const request = String(url.searchParams.get('request') || '').trim();
     if (!request) return json(res, 400, { error: '缺少 request 参数（需求摘要）。' });

package/skills/yotta-skills/lib/hub.js

@@ -394,6 +394,41 @@ function scanHubSkills(hubDir) {
   return result.sort((a, b) => a.slug.localeCompare(b.slug));
 }
 
+/** 轻量技能计数（顶层目录 / 链接含 SKILL.md；不做哈希，用于提示与 doctor）。 */
+function countHubSkills(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return 0;
+  }
+  let count = 0;
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    try {
+      if (fs.existsSync(path.join(dir, entry.name, SKILL_FILE))) count += 1;
+    } catch (_) { /* skip unreadable entry */ }
+  }
+  return count;
+}
+
+/** 空 Hub 提示：优先指向「未迁移旧 Hub」（0.29.5 S1），否则回退到 install / adopt。 */
+function emptyHubHint(opts, hubDir) {
+  const fallback = '先运行 yotta-skills hub install 或 hub adopt --apply';
+  try {
+    const config = skillsConfigLib.readConfig({ homeDir: opts.homeDir, env: opts.env });
+    if (config.lastSwitch && config.lastSwitch.from && !samePath(config.lastSwitch.from, hubDir)) {
+      const count = countHubSkills(config.lastSwitch.from);
+      if (count > 0) {
+        return '旧 Hub ' + config.lastSwitch.from + ' 还有 ' + count + ' 个技能未迁移；迁移：yotta-skills hub config set --hub "' +
+          path.resolve(hubDir) + '" --move（面板「一键迁移」同源）';
+      }
+    }
+  } catch (_) { /* fall back */ }
+  return fallback;
+}
+
 function manifestSlugs(manifest) {
   const set = new Set();
   const list = Array.isArray(manifest) ? manifest : (manifest && manifest.skills) || [];
@@ -457,6 +492,11 @@ function safeHostName(value) {
   return cleaned || 'host';
 }
 
+/** 目录短哈希（回收站命名去重：不同目录同 basename 时不互相撞车）。 */
+function shortPathHash(dir) {
+  return crypto.createHash('sha1').update(path.resolve(dir)).digest('hex').slice(0, 8);
+}
+
 /** 清理回收站中超过保留期的条目（best-effort；返回清理数量）。 */
 function pruneTrash(trashRoot, options) {
   const opts = options || {};
@@ -488,6 +528,77 @@ function pruneTrash(trashRoot, options) {
   return pruned;
 }
 
+/** 历史备份 / 暂存残留的目录名标记（0.29.5 S3）。 */
+const BACKUP_RESIDUE_MARKERS = [
+  '.yottaskills-backup-',
+  '.yottaskills-import-',
+  '.yottaskills-rollback-',
+  '.yottaskills-staging',
+];
+
+/**
+ * 扫描宿主 / Hub 目录里的 `.yottaskills-backup-*` / `.yottaskills-import-*`
+ * 历史残留（只读）。dirs = [{ dir, label }] 或字符串数组。
+ */
+function findBackupResidues(options) {
+  const opts = options || {};
+  const dirs = Array.isArray(opts.dirs) ? opts.dirs : [];
+  const found = [];
+  for (const item of dirs) {
+    const dir = path.resolve(typeof item === 'string' ? item : item.dir);
+    const label = typeof item === 'string' ? null : (item.label || null);
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!BACKUP_RESIDUE_MARKERS.some((marker) => entry.name.includes(marker))) continue;
+      found.push({
+        dir,
+        label,
+        name: entry.name,
+        path: path.join(dir, entry.name),
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * 清理历史备份残留：移入回收站 `backup-cleanup-<stamp>/`（保留 7 天）。
+ * options: { dirs, hubDir, trashRoot, residues, now, renameEntry }
+ */
+function cleanupBackupResidues(options) {
+  const opts = options || {};
+  const residues = Array.isArray(opts.residues) ? opts.residues : findBackupResidues(opts);
+  const baseHub = opts.hubDir || (opts.dirs && opts.dirs.length
+    ? (typeof opts.dirs[0] === 'string' ? opts.dirs[0] : opts.dirs[0].dir)
+    : null);
+  const trashRoot = opts.trashRoot || resolveTrashRoot(baseHub || process.cwd(), opts);
+  const stamp = trashRunStamp(opts.now);
+  const renameEntry = typeof opts.renameEntry === 'function' ? opts.renameEntry : fs.renameSync;
+  const moved = [];
+  const failed = [];
+  for (const item of residues) {
+    const dest = path.join(
+      trashRoot,
+      'backup-cleanup-' + stamp,
+      safeHostName(path.basename(item.dir)) + '-' + shortPathHash(item.dir),
+      item.name,
+    );
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const transfer = moveEntryAcrossDevices(item.path, dest, { renameEntry });
+      moved.push({ from: item.path, to: dest, dir: item.dir, name: item.name, method: transfer.method });
+    } catch (error) {
+      failed.push({ path: item.path, error: error.message });
+    }
+  }
+  return { ok: failed.length === 0, trashRoot, found: residues.length, moved, failed };
+}
+
 /**
  * 列出宿主目录中某个家族技能的副本：
  * - 精确同名（slug）的真目录 / 链接；
@@ -656,7 +767,7 @@ function linkSkills(options) {
   const makeLink = typeof opts.createLink === 'function' ? opts.createLink : createDirLink;
   const renameEntry = typeof opts.renameEntry === 'function' ? opts.renameEntry : fs.renameSync;
   const stamp = trashRunStamp(opts.now);
-  const hostName = safeHostName(opts.label || path.basename(targetDir));
+  const hostName = safeHostName(opts.label || path.basename(targetDir)) + '-' + shortPathHash(targetDir);
   let prunedTrash = 0;
   if (!dryRun) {
     try {
@@ -897,6 +1008,7 @@ function linkSkills(options) {
 
     // ── 非家族技能：保持原行为（同名冲突默认跳过，不自动删） ────────────
     let backup = null;
+    let backupMethod = null;
     if (current.kind === 'link' && current.inHub && current.targetExists !== false && samePath(current.target, skill.dir)) {
       results.push({ slug, status: 'linked', target, note: '已链接到 hub' });
       continue;
@@ -917,11 +1029,21 @@ function linkSkills(options) {
       }
       if (current.kind === 'directory') {
         if (dryRun) {
-          results.push({ slug, status: 'would-backup', target, note: '将备份真目录后建立链接' });
+          results.push({
+            slug,
+            status: 'would-backup',
+            target,
+            note: '将把真目录旧副本移入回收站（保留 ' + TRASH_RETENTION_DAYS + ' 天）后建立链接',
+          });
           continue;
         }
-        backup = target + '.yottaskills-backup-' + Date.now();
-        fs.renameSync(target, backup);
+        // 0.29.5 S3：旧副本不再原地留 <name>.yottaskills-backup-*（宿主会当技能扫），
+        // 统一移入回收站（7 天可恢复）；跨卷走复制 + 校验 + 删源。
+        const dest = path.join(trashRoot, stamp, hostName, slug);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const transfer = moveEntryAcrossDevices(target, dest, { renameEntry });
+        backup = dest;
+        backupMethod = transfer.method;
       } else if (current.kind === 'link') {
         if (dryRun) {
           results.push({ slug, status: 'would-replace', target, note: '将替换已有链接' });
@@ -937,8 +1059,10 @@ function linkSkills(options) {
       results.push({ slug, status: 'would-link', target, note: '将建立链接' });
       continue;
     }
+    let linked = false;
     try {
       makeLink(skill.dir, target);
+      linked = true;
       const index = links.findIndex((item) => item.slug === slug && samePath(item.dir || '', targetDir));
       const record = {
         slug,
@@ -949,17 +1073,41 @@ function linkSkills(options) {
         hubDir: skill.dir,
         linkedAt: nowIso(),
         backup,
+        backupMethod,
       };
       if (index >= 0) links[index] = record;
       else links.push(record);
-      results.push({ slug, status: 'linked', target, note: backup ? '已备份原目录并建立链接' : '已建立链接', backup });
-      appendAudit(hubDir, { event: 'link', slug, target, hubDir: skill.dir, backup });
+      results.push({
+        slug,
+        status: 'linked',
+        target,
+        note: backup
+          ? '真目录旧副本已移入回收站（保留 ' + TRASH_RETENTION_DAYS + ' 天）并建立链接'
+          : '已建立链接',
+        backup,
+        backupMethod,
+        trashDir: backup ? trashRoot : null,
+      });
+      try {
+        appendAudit(hubDir, { event: 'link', slug, target, hubDir: skill.dir, backup, backupMethod });
+      } catch (_) { /* 审计失败不把已完成的链接判失败 */ }
     } catch (error) {
+      // 替换失败时把旧副本从回收站移回原位，避免宿主目录留下空位。
+      let restored = false;
+      if (backup && !linked) {
+        try {
+          moveEntryAcrossDevices(backup, target, { renameEntry });
+          restored = true;
+        } catch (_) { /* 保留回收站副本供人工恢复 */ }
+      }
       results.push({
         slug,
         status: 'error',
         target,
-        note: error.message + '（未静默降级为复制；请检查目录权限或改用 --dir 指定可写目录）',
+        backup: restored ? null : backup,
+        note: error.message +
+          (backup ? (restored ? '（旧副本已恢复原位）' : '（旧副本保留在回收站：' + backup + '）') : '') +
+          '（未静默降级为复制；请检查目录权限或改用 --dir 指定可写目录）',
       });
     }
   }
@@ -1395,6 +1543,38 @@ function singleSourceChecks(opts, add) {
   }
 }
 
+/** 0.29.5 S3：历史备份 / 暂存残留只读检查（宿主扫描目录 + Hub 自身）。 */
+function backupResidueChecks(opts, add) {
+  const hubDir = path.resolve(opts.hubDir);
+  const dirs = [];
+  if (fs.existsSync(hubDir)) dirs.push({ dir: hubDir, label: 'Hub' });
+  let discovery = opts.discovery;
+  if (!discovery) {
+    try {
+      discovery = require('./agent-discovery').discoverHosts({ homeDir: opts.homeDir, env: opts.env });
+    } catch (_) {
+      discovery = { hosts: [] };
+    }
+  }
+  for (const host of discovery.hosts || []) {
+    if (!host || !host.exists || !host.dir) continue;
+    dirs.push({ dir: host.dir, label: host.label || host.agentId || host.dir });
+  }
+  const residues = findBackupResidues({ dirs });
+  if (residues.length === 0) return;
+  const byDir = new Map();
+  for (const item of residues) {
+    if (!byDir.has(item.dir)) byDir.set(item.dir, []);
+    byDir.get(item.dir).push(item.name);
+  }
+  for (const [dir, names] of byDir) {
+    add('backup_residue:' + dir, false, 'warning',
+      '发现 ' + names.length + ' 个历史备份 / 暂存残留（宿主会把备份当技能扫描）: ' + names.slice(0, 5).join('、') +
+        (names.length > 5 ? ' 等 ' + names.length + ' 项' : ''),
+      '清理：yotta-skills hub cleanup-backups --yes（移入回收站，保留 ' + TRASH_RETENTION_DAYS + ' 天）');
+  }
+}
+
 function doctor(options) {
   const opts = options || {};
   const hubDir = path.resolve(opts.hubDir);
@@ -1405,7 +1585,7 @@ function doctor(options) {
 
   add('hub_dir', fs.existsSync(hubDir), 'error',
     fs.existsSync(hubDir) ? 'Hub 目录存在' : 'Hub 目录不存在',
-    fs.existsSync(hubDir) ? null : '先运行 yotta-skills hub install 或 hub adopt --apply');
+    fs.existsSync(hubDir) ? null : emptyHubHint(opts, hubDir));
   if (fs.existsSync(hubDir)) {
     try {
       fs.accessSync(hubDir, fs.constants.W_OK);
@@ -1423,7 +1603,7 @@ function doctor(options) {
   const stateSkills = Object.values(synced.state.skills || {});
   if (fs.existsSync(hubDir) && stateSkills.length === 0) {
     add('hub_nonempty', false, 'error', 'Hub 目录存在但没有任何技能',
-      '先运行 yotta-skills hub install 或 hub adopt --apply');
+      emptyHubHint(opts, hubDir));
   }
   for (const skill of stateSkills) {
     add('skill_present:' + skill.slug, skill.status === 'present', 'error',
@@ -1463,6 +1643,9 @@ function doctor(options) {
   try {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
+  try {
+    backupResidueChecks(opts, add);
+  } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
 
   // F3（0.29.0）：宿主状态细分只读检查 —— 残留 / 仅标记给 info 提示，不 fail。
   if (opts.discovery) {
@@ -1512,12 +1695,18 @@ module.exports = {
   hashTree,
   moveEntryAcrossDevices,
   scanHubSkills,
+  countHubSkills,
   syncHubState,
   familySlugSet,
   compareVersions,
   readSkillMeta,
   resolveTrashRoot,
   pruneTrash,
+  BACKUP_RESIDUE_MARKERS,
+  findBackupResidues,
+  cleanupBackupResidues,
+  trashRunStamp,
+  safeHostName,
   listFamilyCopies,
   createDirLink,
   removeDirLink,