@yottameta/yotta-skills-plugin 0.29.4 → 0.29.5

package/skills/yotta-skills/lib/cli-help.js

@@ -37,11 +37,12 @@ const CLI_GLOBAL_OPTIONS = [
   { flag: '--context', arg: '<json>', what: 'hook evaluate 的检查结果 JSON', when: '外部传入 checks / wrapperRegistered / evidence 时', caution: '' },
   { flag: '--skill', arg: '<slug>', what: 'usage mark 的技能 slug', when: '记录技能使用信号时', caution: '' },
   { flag: '--signal', arg: '<name>', what: 'usage mark 的信号：used / named / accepted', when: '记录技能使用信号时', caution: '' },
-  { flag: '--yes', arg: '', what: 'usage reset 的确认开关', when: '确认清空本地使用记录时', caution: '会清空记录文件' },
+  { flag: '--yes', arg: '', what: '确认开关（usage reset / hub hosts remove --purge / hub cleanup-backups / hub config rollback）', when: '确认执行破坏性或迁移类操作时', caution: '默认都是预览；--yes 才真正执行' },
   { flag: '--explain', arg: '', what: 'decide-memory 文本报告追加信号明细', when: '想看裁决依据时', caution: '' },
   { flag: '--promote', arg: '', what: 'decide-memory 只写本地建议文件（不写元忆）', when: '想留下裁决建议文件时', caution: '不会写元忆、不会删除任何内容' },
   { flag: '--hub', arg: '<path>', what: 'Hub 目录（默认 ~/.yottaskills/hub；持久配置见 hub config）', when: '使用自定义 Hub 位置时', caution: '覆盖顺序：--hub > YOTTA_SKILLS_HUB > config.json > 默认' },
   { flag: '--move', arg: '', what: 'hub config set 迁移：复制校验旧 Hub → 重链宿主 → 旧 Hub 入回收站（7 天）', when: '换 Hub 位置并带上已有技能时', caution: 'fail-closed：校验失败不切配置；重链失败保留旧 Hub' },
+  { flag: '--clean-residue', arg: '', what: 'hub config set --move / rollback：目标只含空 Hub 台账残留时先移入回收站再迁移', when: '迁移 / 回滚目标目录有 .yotta-hub.json 残留时', caution: '只清理元阁自己的空台账残留，不合并其它内容' },
   { flag: '--port', arg: '<n>', what: 'view 面板端口（默认 8789）', when: '端口冲突或想固定端口时', caution: '仅 127.0.0.1 监听' },
   { flag: '--all', arg: '', what: 'hub link / unlink 作用于全部已核实宿主', when: '全量分发或解除时', caution: '' },
   { flag: '--include-discovered', arg: '', what: 'hub link / unlink / remove 时纳入自动发现目录', when: '确认要扩围到未核实目录时', caution: '默认只链已核实宿主；桥接目录永不链接' },
@@ -185,8 +186,10 @@ const CLI_HELP_MODEL = [
           { name: 'hosts include', usage: 'hub hosts include <agentId|dir> [--json]', what: '恢复接管（移出「不接管」名单）', when: '重新纳入发现 / 链接时', options: ['--json'] },
           { name: 'hosts set', usage: 'hub hosts set <agentId> --dir <dir> [--label <名称>] [--json] | hub hosts set <agentId> --clear', what: '目录覆盖：用户级覆盖内置映射；--clear 恢复默认', when: '宿主技能目录与内置映射不一致时', options: ['--dir', '--label', '--clear', '--json'] },
           { name: 'config get', usage: 'hub config get [--json]', what: '查看生效 Hub 位置与来源（--hub / YOTTA_SKILLS_HUB / config.json / 默认）', when: '确认当前 Hub 与配置覆盖时', options: ['--json'] },
-          { name: 'config set', usage: 'hub config set --hub <path> [--move]', what: '持久化 Hub 位置；--move 迁移旧 Hub（复制校验 → 重链 → 回收站 7 天）', when: '换 Hub 存储位置时', options: ['--hub', '--move', '--json'] },
+          { name: 'config set', usage: 'hub config set --hub <path> [--move [--clean-residue]]', what: '持久化 Hub 位置；--move 迁移旧 Hub（复制校验 → 重链 → 回收站 7 天）；未迁移时记录原位置供面板提示', when: '换 Hub 存储位置时', options: ['--hub', '--move', '--clean-residue', '--json'] },
+          { name: 'config rollback', usage: 'hub config rollback [--yes] [--clean-residue]', what: '回滚到上次迁移前的 Hub 位置（位置回退，用当前内容；反向迁移同内核）', when: '迁移后想退回原位置时', options: ['--yes', '--clean-residue', '--json'] },
           { name: 'config clear', usage: 'hub config clear [--json]', what: '清除配置覆盖，恢复 flag > env > 默认', when: '撤销持久 Hub 位置时', options: ['--json'] },
+          { name: 'cleanup-backups', usage: 'hub cleanup-backups [--yes] [--include-discovered]', what: '清理宿主 / Hub 里的 .yottaskills-backup-* / .yottaskills-staging 历史残留（移入回收站 7 天）', when: '宿主把备份当技能扫描、或迁移后要清残留时', options: ['--yes', '--include-discovered', '--dir', '--agent', '--json'] },
           { name: 'install', usage: 'hub install [skill...]', what: '把元技能装进 Hub 真源（清单 27 + 特殊家族 5）', when: '初始化 Hub 或补装技能时', options: ['--hub'] },
           { name: 'update', usage: 'hub update', what: '更新 Hub 内的元技能（非元技能不参与；只升不降）', when: '日常维护 Hub 真源时', options: ['--hub'] },
           { name: 'adopt', usage: 'hub adopt [--scan | --apply] [--include <a,b>] [--in-place]', what: '把各宿主已有技能收编进 Hub（默认复制保真）', when: '接管机器上已装的技能时', options: ['--scan', '--apply', '--include', '--in-place', '--force', '--skip-scan', '--allow-unverified'] },
@@ -306,7 +309,9 @@ const CLI_HELP_QUICK = [
       { cmd: 'hub hosts set', example: 'yotta-skills hub hosts set <agentId> --dir <目录>' },
       { cmd: 'hub config get', example: 'yotta-skills hub config get', note: '查看生效位置与来源' },
       { cmd: 'hub config set', example: 'yotta-skills hub config set --hub <Hub目录>', note: '持久化 Hub 位置；迁移旧 Hub 加 --move' },
+      { cmd: 'hub config rollback', example: 'yotta-skills hub config rollback --yes', note: '回滚到上次迁移前的位置（位置回退，用当前内容）', danger: true },
       { cmd: 'hub config clear', example: 'yotta-skills hub config clear', note: '清除持久覆盖，恢复默认解析' },
+      { cmd: 'hub cleanup-backups', example: 'yotta-skills hub cleanup-backups --yes', note: '历史备份 / 暂存残留移入回收站（7 天可恢复）', danger: true },
       { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录>', note: '只移除注册，不删目录' },
       { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录> --purge', danger: true, note: '清理残留目录：先预览，--yes 才执行；目录入回收站保留 7 天' },
       { cmd: 'hub install', example: 'yotta-skills hub install' },

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

@@ -151,9 +151,14 @@ function replaceWithBackup(target, options) {
     return null;
   }
   if (!opts.force) throw new Error('目标已存在真目录；如需替换请显式加 --force');
-  const backup = target + '.yottaskills-backup-' + Date.now();
-  fs.renameSync(target, backup);
-  return backup;
+  // 0.29.5 S3：旧副本不再原地留 <name>.yottaskills-backup-*（宿主会当技能扫），
+  // 统一移入回收站（7 天可恢复）；跨卷走复制 + 校验 + 删源。
+  const trashRoot = opts.trashRoot || hubLib.resolveTrashRoot(opts.hubDir, opts);
+  const stamp = hubLib.trashRunStamp(opts.now);
+  const dest = path.join(trashRoot, stamp, 'hub-adopt', path.basename(target));
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const transfer = hubLib.moveEntryAcrossDevices(target, dest, { renameEntry: opts.renameEntry });
+  return { path: dest, method: transfer.method, trashRoot };
 }
 
 function copyFidelity(sourceDir, targetDir) {
@@ -182,6 +187,9 @@ function applyCandidates(options) {
   const include = opts.include || [];
   const results = [];
   fs.mkdirSync(hubDir, { recursive: true });
+  try {
+    hubLib.pruneTrash(hubLib.resolveTrashRoot(hubDir, opts));
+  } catch (_) { /* best-effort */ }
 
   for (const candidate of candidates) {
     if (!includeMatch(candidate.slug, include)) continue;
@@ -220,8 +228,15 @@ function applyCandidates(options) {
     }
     let backup = null;
     let tmp = null;
+    let installed = false;
     try {
-      backup = replaceWithBackup(target, { force: opts.force });
+      backup = replaceWithBackup(target, {
+        force: opts.force,
+        hubDir,
+        env: opts.env,
+        trashRoot: opts.trashRoot,
+        renameEntry: opts.renameEntry,
+      });
       if (opts.inPlace) {
         hubLib.createDirLink(candidate.source, target);
       } else {
@@ -229,27 +244,44 @@ function applyCandidates(options) {
         fs.renameSync(tmp, target);
         tmp = null;
       }
+      installed = true;
       results.push({
         slug: candidate.slug,
         status: 'imported',
-        note: opts.inPlace ? '已原地登记并链接到 Hub' : '已复制到 Hub',
-        backup,
+        note: (opts.inPlace ? '已原地登记并链接到 Hub' : '已复制到 Hub') +
+          (backup ? '；旧副本已移入回收站（保留 ' + hubLib.TRASH_RETENTION_DAYS + ' 天）' : ''),
+        backup: backup ? backup.path : null,
         scanVerdict: scan.verdict,
         sourcePath: candidate.source,
         sourceAgent: candidate.sourceHost,
       });
-      hubLib.appendAudit(hubDir, {
-        event: 'adopt',
-        slug: candidate.slug,
-        source: candidate.source,
-        sourceHost: candidate.sourceHost,
-        inPlace: Boolean(opts.inPlace),
-        verdict: scan.verdict,
-        backup,
-      });
+      try {
+        hubLib.appendAudit(hubDir, {
+          event: 'adopt',
+          slug: candidate.slug,
+          source: candidate.source,
+          sourceHost: candidate.sourceHost,
+          inPlace: Boolean(opts.inPlace),
+          verdict: scan.verdict,
+          backup: backup ? backup.path : null,
+        });
+      } catch (_) { /* 审计失败不把已完成的收编判失败 */ }
     } catch (error) {
       if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
-      results.push({ slug: candidate.slug, status: 'error', note: error.message });
+      let restored = false;
+      if (backup && !installed) {
+        try {
+          hubLib.moveEntryAcrossDevices(backup.path, target, { renameEntry: opts.renameEntry });
+          restored = true;
+        } catch (_) { /* 保留回收站副本供人工恢复 */ }
+      }
+      results.push({
+        slug: candidate.slug,
+        status: 'error',
+        note: error.message +
+          (backup && !restored ? '（旧副本保留在回收站：' + backup.path + '）' : ''),
+        backup: backup && !restored ? backup.path : null,
+      });
     }
   }
   const synced = hubLib.syncHubState(hubDir, { manifest: opts.manifest, homeDir: opts.homeDir, env: opts.env });
@@ -286,23 +318,60 @@ function refreshFrom(options) {
   }
   let backup = null;
   let tmp = null;
+  let installed = false;
   try {
-    backup = replaceWithBackup(target, { force: true });
+    backup = replaceWithBackup(target, {
+      force: true,
+      hubDir,
+      env: opts.env,
+      trashRoot: opts.trashRoot,
+      renameEntry: opts.renameEntry,
+    });
     tmp = copyFidelity(source, target);
     fs.renameSync(tmp, target);
     tmp = null;
+    installed = true;
+  } catch (error) {
+    if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+    let restored = false;
+    if (backup && !installed) {
+      try {
+        hubLib.moveEntryAcrossDevices(backup.path, target, { renameEntry: opts.renameEntry });
+        restored = true;
+      } catch (_) { /* 保留回收站副本供人工恢复 */ }
+    }
+    return {
+      ok: false,
+      slug,
+      error: error.message + (backup && !restored ? '（旧副本保留在回收站：' + backup.path + '）' : ''),
+      backup: backup && !restored ? backup.path : null,
+    };
+  }
+  try {
     hubLib.syncHubState(hubDir, { manifest: opts.manifest, homeDir: opts.homeDir, env: opts.env });
     persistImportMeta(hubDir, slug, {
       sourcePath: source,
       scanVerdict: scan.verdict,
       updatedAt: new Date().toISOString(),
     });
-    hubLib.appendAudit(hubDir, { event: 'refresh', slug, source, verdict: scan.verdict, backup });
-    return { ok: true, slug, source, backup, verdict: scan.verdict, scanPolicy: scan.policy || null };
-  } catch (error) {
-    if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
-    return { ok: false, slug, error: error.message };
-  }
+  } catch (_) { /* 状态刷新 best-effort；链接 / 台账下次同步 */ }
+  try {
+    hubLib.appendAudit(hubDir, {
+      event: 'refresh',
+      slug,
+      source,
+      verdict: scan.verdict,
+      backup: backup ? backup.path : null,
+    });
+  } catch (_) { /* 审计失败不把已完成的刷新判失败 */ }
+  return {
+    ok: true,
+    slug,
+    source,
+    backup: backup ? backup.path : null,
+    verdict: scan.verdict,
+    scanPolicy: scan.policy || null,
+  };
 }
 
 module.exports = {

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

@@ -1,6 +1,7 @@
 'use strict';
 /**
- * Hub 迁移（0.29.2 U4）—— `hub config set --hub <new> --move` 的两段式实现。
+ * Hub 迁移（0.29.2 U4；0.29.5 抽出共享内核）—— `hub config set --hub <new> --move`
+ * 的两段式实现。
  *
  * 1) stageHubCopy({ from, to })：复制旧 Hub → 逐技能 treeHash 校验；失败
  *    fail-closed（清理暂存副本、旧 Hub 不动、配置不切换）。
@@ -10,10 +11,15 @@
  *
  * 配置切换（config.json 写入）由调用方在两段之间执行；写入失败时调用
  * discardStagedCopy() 清理暂存副本。
+ *
+ * 0.29.5：runHubMigration() 把「复制 → 切配置 → 重链 → 旧 Hub 入回收站 → 记录
+ * lastMigration」收成一个共享内核，CLI `hub config set --move` / `hub config
+ * rollback` 与面板迁移向导 / 一键回滚共用，避免两套行为漂移。
  */
 const fs = require('fs');
 const path = require('path');
 const hubLib = require('./hub');
+const skillsConfigLib = require('./skills-config');
 
 function nowStamp() {
   return new Date().toISOString().replace(/[:.]/g, '-');
@@ -51,6 +57,48 @@ function listEntries(dir) {
   }
 }
 
+/** 空 Hub 台账残留：目标目录里只有元阁自己写过的空台账 / 审计文件。 */
+const HUB_RESIDUE_FILES = new Set(['.yotta-hub.json', '.yotta-hub-audit.jsonl']);
+
+/** 只读检查目标目录状态（迁移 fail-closed 判定 + 面板「清理残留并迁移」入口）。 */
+function inspectTargetDir(dir) {
+  const resolved = path.resolve(dir);
+  const exists = fs.existsSync(resolved);
+  const entries = exists ? listEntries(resolved) : [];
+  const residueOnly = entries.length > 0 && entries.every((name) => HUB_RESIDUE_FILES.has(name));
+  return {
+    dir: resolved,
+    exists,
+    entries,
+    empty: entries.length === 0,
+    residueOnly,
+    residueFiles: residueOnly ? entries : [],
+  };
+}
+
+/** 把「空 Hub 台账残留」移入回收站（保留 7 天），返回 { ok, moved, trashDir }。 */
+function clearTargetResidue(dir, options) {
+  const opts = options || {};
+  const resolved = path.resolve(dir);
+  const state = inspectTargetDir(resolved);
+  if (!state.residueOnly) return { ok: false, error: '目标目录不是空 Hub 台账残留：' + resolved };
+  const trashRoot = hubLib.resolveTrashRoot(opts.hubDir || resolved, opts);
+  const dest = path.join(trashRoot, 'hub-residue-' + nowStamp());
+  const moved = [];
+  try {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of state.residueFiles) {
+      const from = path.join(resolved, name);
+      const to = path.join(dest, name);
+      hubLib.moveEntryAcrossDevices(from, to);
+      moved.push({ from, to });
+    }
+  } catch (error) {
+    return { ok: false, error: '清理残留失败：' + error.message, moved, trashDir: dest };
+  }
+  return { ok: true, moved, trashDir: dest };
+}
+
 /** 清理暂存副本（仅在 stage 阶段失败或配置写入失败时调用）。 */
 function discardStagedCopy(options) {
   const opts = options || {};
@@ -176,8 +224,171 @@ function relinkAndRetireOldHub(options) {
   return { ok: incomplete === 0, from, to, relink, incomplete, trashedTo, trashError };
 }
 
+function classifyStageError(error) {
+  const text = String(error || '');
+  if (/非空/.test(text)) return 'target-non-empty';
+  if (/嵌套/.test(text)) return 'target-nested';
+  if (/相同/.test(text)) return 'target-same';
+  return 'stage-failed';
+}
+
+/**
+ * 共享迁移内核：stage → 切配置 → 重链 → 旧 Hub 入回收站 → 记录 lastMigration。
+ *
+ * options:
+ * - from / to（必填）；targets（宿主目录数组；不传则不重链）
+ * - configOpts（默认 { homeDir, env }）；manifest / homeDir / env
+ * - via（'cli' | 'view'）；kind（'migrate' | 'rollback'）
+ * - cleanResidue（true = 目标为空 Hub 台账残留时先移入回收站再迁移）
+ *
+ * 返回 { ok, phase, report?, error?, code?, stage?, finish? }；部分失败
+ * （重链未全部完成）时旧 Hub 保留、report 记录 incomplete，绝不报成功。
+ */
+function runHubMigration(options) {
+  const opts = options || {};
+  const from = path.resolve(opts.from);
+  const to = path.resolve(opts.to);
+  const via = opts.via || 'cli';
+  const kind = opts.kind === 'rollback' ? 'rollback' : 'migrate';
+  const configOpts = opts.configOpts || { homeDir: opts.homeDir, env: opts.env };
+
+  const oldHasContent = fs.existsSync(from) && listEntries(from).length > 0;
+  if (!oldHasContent) {
+    const setResult = skillsConfigLib.setHub(configOpts, { hub: to });
+    if (!setResult.ok) return { ok: false, phase: 'config', error: setResult.error, code: 'config-failed' };
+    return {
+      ok: true,
+      phase: 'done',
+      switchedOnly: true,
+      report: {
+        moved: false,
+        kind,
+        from,
+        to,
+        at: new Date().toISOString(),
+        reason: '旧 Hub 不存在或为空（' + from + '），仅切换指针',
+        verifiedSkills: 0,
+        relinkDirs: 0,
+        incomplete: 0,
+        trashedTo: null,
+        trashError: null,
+        oldHubKept: null,
+        via,
+      },
+    };
+  }
+
+  let residue = null;
+  const targetState = inspectTargetDir(to);
+  if (targetState.residueOnly) {
+    if (!opts.cleanResidue) {
+      return {
+        ok: false,
+        phase: 'preflight',
+        code: 'target-residue',
+        error: '新 Hub 目录含空 Hub 台账残留（' + targetState.residueFiles.join('、') + '）：' + to +
+          '。可勾选「清理残留并迁移」后重试。',
+        target: targetState,
+      };
+    }
+    residue = clearTargetResidue(to, { hubDir: from, env: opts.env });
+    if (!residue.ok) return { ok: false, phase: 'preflight', code: 'residue-clean-failed', error: residue.error };
+  }
+
+  const staged = stageHubCopy({ from, to });
+  if (!staged.ok) {
+    return { ok: false, phase: 'stage', code: classifyStageError(staged.error), error: staged.error };
+  }
+  const setResult = skillsConfigLib.setHub(configOpts, { hub: to });
+  if (!setResult.ok) {
+    discardStagedCopy({ to, existed: staged.existed });
+    return { ok: false, phase: 'config', code: 'config-failed', error: setResult.error };
+  }
+  const finish = relinkAndRetireOldHub({
+    from,
+    to,
+    targets: opts.targets,
+    manifest: opts.manifest,
+    homeDir: opts.homeDir,
+    env: opts.env,
+  });
+  const report = {
+    moved: true,
+    kind,
+    from,
+    to,
+    at: new Date().toISOString(),
+    verifiedSkills: staged.verifiedSkills,
+    relinkDirs: finish.relink.length,
+    relink: finish.relink,
+    incomplete: finish.incomplete,
+    trashedTo: finish.trashedTo,
+    trashError: finish.trashError,
+    oldHubKept: (finish.incomplete > 0 || finish.trashError) ? from : null,
+    via,
+  };
+  skillsConfigLib.recordLastMigration(configOpts, report);
+  return {
+    ok: finish.ok,
+    phase: finish.ok ? 'done' : 'relink',
+    report,
+    finish,
+    residue,
+  };
+}
+
+/** 回收站保留剩余天数（向上取整，最小 0；at 缺失按 0 天算）。 */
+function trashDaysLeft(at, options) {
+  const opts = options || {};
+  const days = Number(opts.days) > 0 ? Number(opts.days) : hubLib.TRASH_RETENTION_DAYS;
+  const started = Date.parse(at || '');
+  if (!Number.isFinite(started)) return 0;
+  const elapsedDays = Math.floor(Math.max(0, Date.now() - started) / (24 * 60 * 60 * 1000));
+  return Math.max(0, days - elapsedDays);
+}
+
+/**
+ * 回滚预览（只读）：当前 Hub → 上次迁移的原位置，反向迁移同内核。
+ * 语义 = 位置回退（用当前内容，不丢迁移后改动），不是恢复旧快照。
+ */
+function previewRollback(options) {
+  const opts = options || {};
+  const configOpts = opts.configOpts || { homeDir: opts.homeDir, env: opts.env };
+  const config = skillsConfigLib.readConfig(configOpts);
+  const last = config.lastMigration;
+  if (!last) {
+    return { ok: false, code: 'no-migration', error: '没有可回滚的迁移记录（config.json 无 lastMigration）' };
+  }
+  const current = opts.currentDir
+    ? { dir: path.resolve(opts.currentDir), source: opts.currentSource || 'flag' }
+    : skillsConfigLib.resolveHub(configOpts);
+  const target = inspectTargetDir(last.from);
+  const blocked = [];
+  if (!fs.existsSync(current.dir)) blocked.push('当前 Hub 不存在：' + current.dir);
+  if (target.exists && !target.empty && !target.residueOnly) {
+    blocked.push('回滚目标非空（fail-closed，不合并）：' + target.dir);
+  }
+  return {
+    ok: blocked.length === 0,
+    code: blocked.length ? 'rollback-blocked' : null,
+    blocked,
+    current: current.dir,
+    target: target.dir,
+    targetState: target,
+    lastMigration: last,
+    daysLeft: trashDaysLeft(last.at, opts),
+    command: 'yotta-skills hub config rollback --yes',
+  };
+}
+
 module.exports = {
   discardStagedCopy,
   stageHubCopy,
   relinkAndRetireOldHub,
+  inspectTargetDir,
+  clearTargetResidue,
+  runHubMigration,
+  previewRollback,
+  trashDaysLeft,
+  HUB_RESIDUE_FILES,
 };

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

@@ -0,0 +1,85 @@
+'use strict';
+/**
+ * Hub 链接目标范围（0.29.5）—— `hub link --all` 与面板迁移向导 / 一键回滚的
+ * 重链范围共用同一真源，避免 CLI 与面板两套范围漂移。
+ *
+ * 默认范围 = 通用目录（Universal .agents / 通用 AGENTS.md）+ 已核实宿主目录；
+ * `includeDiscovered` 显式纳入自动发现目录；桥接目录永不纳入（发现层已过滤
+ * 不接管名单与 YottaCode）。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const agentDirsLib = require('./agent-dirs');
+const hostsRegistryLib = require('./hosts-registry');
+
+function normalizeTargetKey(dir) {
+  const resolved = path.resolve(dir);
+  let real = resolved;
+  try {
+    real = fs.realpathSync.native(resolved);
+  } catch (_) { /* missing path: fall back to the resolved spelling */ }
+  return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+
+/** 通用技能目录（与旧 CLI universalSkillDirs 同源）。 */
+function universalSkillDirs(options) {
+  const opts = options || {};
+  const home = opts.homeDir || os.homedir();
+  const env = opts.env || process.env;
+  const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config');
+  return [
+    { dir: path.join(xdg, 'agents', 'skills'), agentId: 'universal', label: 'Universal .agents' },
+    { dir: path.join(home, '.agents', 'skills'), agentId: 'agents', label: '通用 AGENTS.md' },
+  ];
+}
+
+/**
+ * 计算 --all 范围目标（只读；不创建目录、不链接）。
+ * options: { discovery, registry, homeDir, env, includeDiscovered }
+ */
+function computeHubTargets(options) {
+  const opts = options || {};
+  const discovery = opts.discovery || { hosts: [] };
+  const homeDir = opts.homeDir || os.homedir();
+  const env = opts.env || process.env;
+  const registry = opts.registry || hostsRegistryLib.readHostsRegistry({ homeDir, env });
+  const excludedEntry = (input) => hostsRegistryLib.excludedEntryFor(registry, input);
+  const targets = [];
+  const seen = new Set();
+  const add = (dir, agentId, label, meta) => {
+    if (!dir) return;
+    const resolved = path.resolve(dir);
+    const key = normalizeTargetKey(resolved);
+    if (seen.has(key)) return;
+    seen.add(key);
+    targets.push({
+      dir: resolved,
+      agentId: agentId || null,
+      label: label || '指定目录',
+      verified: Boolean(meta && meta.verified),
+      bridgeOnly: Boolean(meta && meta.bridgeOnly),
+      detection: (meta && meta.detection) || 'mapping',
+      explicit: Boolean(meta && meta.explicit),
+    });
+  };
+
+  for (const item of universalSkillDirs({ homeDir, env })) {
+    if (agentDirsLib.isYottaCodeDir(item.dir)) continue;
+    if (excludedEntry({ dir: item.dir, agentId: item.agentId })) continue;
+    add(item.dir, item.agentId, item.label, { verified: true });
+  }
+  for (const host of discovery.hosts || []) {
+    if (!host.exists) continue;
+    if (host.bridgeOnly) continue;
+    if (!opts.includeDiscovered && !host.verified) continue;
+    add(host.dir, host.agentId, host.label, host);
+  }
+  return targets;
+}
+
+module.exports = {
+  normalizeTargetKey,
+  universalSkillDirs,
+  computeHubTargets,
+};