@yottameta/yotta-skills-plugin 0.27.0 → 0.28.0

package/skills/yotta-skills/lib/agent-dirs.js

@@ -40,7 +40,7 @@ const AGENT_DIRS = {
   fx:                { label: 'fx',                    dirs: ['.fx/skills'] },
   gemini:            { label: 'Gemini CLI',            dirs: ['.gemini/skills', '.agents/skills'] },
   copilot:           { label: 'GitHub Copilot',        dirs: ['.copilot/skills', '.agents/skills'] },
-  goose:             { label: 'Goose',                 dirs: ['.config/goose/skills', '.goose/skills'] },
+  goose:             { label: 'Goose',                 dirs: ['.config/goose/skills', '.agents/skills'] },
   grok:              { label: 'Grok Build',            dirs: ['.grok/skills'] },
   hermes:            { label: 'Hermes Agent',          dirs: ['.hermes/skills'] },
   'inference-sh':    { label: 'inference.sh',          dirs: ['.inferencesh/skills'] },
@@ -54,6 +54,7 @@ const AGENT_DIRS = {
   kode:              { label: 'Kode',                  dirs: ['.kode/skills'] },
   lingma:            { label: 'Lingma',                dirs: ['.lingma/skills'] },
   mcpjam:            { label: 'MCPJam',                dirs: ['.mcpjam/skills'] },
+  mimocode:          { label: 'MiMo Code',             dirs: ['.config/mimocode/skills'] },
   minimax:           { label: 'MiniMax Code',          dirs: ['.minimax/skills'] },
   'mistral-vibe':    { label: 'Mistral Vibe',          dirs: ['.vibe/skills'] },
   moxby:             { label: 'Moxby',                 dirs: ['.moxby/skills'] },
@@ -68,6 +69,7 @@ const AGENT_DIRS = {
   'qoder-cn':        { label: 'Qoder CN',              dirs: ['.qoder-cn/skills'] },
   qwen:              { label: 'Qwen Code',             dirs: ['.qwen/skills'] },
   reasonix:          { label: 'Reasonix',              dirs: ['.reasonix/skills'] },
+  replit:            { label: 'Replit',                dirs: ['.config/agents/skills'] },
   rovodev:           { label: 'Rovo Dev',              dirs: ['.rovodev/skills'] },
   roo:               { label: 'Roo Code',              dirs: ['.roo/skills'] },
   'sarvam-code':     { label: 'Sarvam Code',           dirs: ['.sarvam/skills', '.agents/skills'] },
@@ -85,14 +87,30 @@ const AGENT_DIRS = {
   pochi:             { label: 'Pochi',                 dirs: ['.pochi/skills'] },
   adal:              { label: 'AdaL',                  dirs: ['.adal/skills'] },
   dsh:               { label: 'DSH / DeepSeek Harness', dirs: ['.dsh/skills'] },
-  yottacode:         { label: 'YottaCode',             dirs: ['.yottacode/skills'] },
-  box:               { label: 'Box Agent',             dirs: ['.box-agent/skills'] },
+  yottacode:         { label: 'YottaCode',             dirs: ['.yottacode/skills'], verified: false },
+  box:               { label: 'Box Agent',             dirs: ['.box-agent/skills'], verified: false },
   lmstudio:          { label: 'LM Studio',             dirs: ['.lmstudio/skills'] },
   ccswitch:          { label: 'CC Switch',             dirs: ['.cc-switch/skills'] },
   agents:            { label: '通用 AGENTS.md',         dirs: ['.agents/skills'] },
-  universal:         { label: 'Universal .agents',      dirs: ['.agents/skills'] },
+  universal:         { label: 'Universal .agents',      dirs: ['.config/agents/skills', '.agents/skills'] },
 };
 
+/**
+ * Rel paths that follow XDG_CONFIG_HOME when it is set.
+ *
+ * Verified against the upstream Vercel Labs `skills` CLI v1.7.0 table
+ * (2026-10-03): only amp / universal / replit (`configHome/agents/skills`),
+ * devin (`configHome/devin/skills`) and opencode (`configHome/opencode/skills`)
+ * resolve through the config home. Everything else uses the literal
+ * `~/.config/...` path even when XDG_CONFIG_HOME is set (crush / kimchi per the
+ * upstream table; goose follows the machine-verified `~/.config/goose`).
+ */
+const XDG_CONFIG_RELS = new Set([
+  '.config/agents/skills',
+  '.config/devin/skills',
+  '.config/opencode/skills',
+]);
+
 function envPath(env, key) {
   const value = env && env[key];
   return value ? String(value) : null;
@@ -119,8 +137,11 @@ function resolveUserDir(rel, options) {
     return path.join(envPath(env, 'CODEX_HOME') || path.join(home, '.codex'), 'skills');
   }
   if (rel.startsWith('.config/')) {
-    const base = envPath(env, 'XDG_CONFIG_HOME') || path.join(home, '.config');
-    return path.join(base, ...rel.slice('.config/'.length).split('/'));
+    const xdg = envPath(env, 'XDG_CONFIG_HOME');
+    if (xdg && XDG_CONFIG_RELS.has(rel)) {
+      return path.join(xdg, ...rel.slice('.config/'.length).split('/'));
+    }
+    return path.join(home, rel);
   }
   if (rel === '.openclaw/skills') {
     return path.join(envPath(env, 'OPENCLAW_STATE_DIR') || path.join(home, '.openclaw'), 'skills');
@@ -150,16 +171,16 @@ function resolveUserDir(rel, options) {
 function knownRoots(options) {
   const roots = [];
   const seen = new Set();
-  const add = (dir, agentId, label) => {
+  const add = (dir, agentId, label, verified) => {
     if (!dir) return;
     const resolved = path.resolve(dir);
     if (seen.has(resolved)) return;
     seen.add(resolved);
-    roots.push({ dir: resolved, agentId, label, known: true });
+    roots.push({ dir: resolved, agentId, label, known: true, verified: verified !== false });
   };
   for (const [agentId, info] of Object.entries(AGENT_DIRS)) {
     for (const rel of info.dirs) {
-      add(resolveUserDir(rel, options), agentId, info.label);
+      add(resolveUserDir(rel, options), agentId, info.label, info.verified !== false);
     }
   }
   return roots;
@@ -169,15 +190,25 @@ function knownRoots(options) {
 function envRoots(options) {
   const env = envObject(options);
   const roots = [];
-  const add = (dir, agentId, label) => {
+  const add = (dir, agentId, label, extra) => {
     if (!dir) return;
-    roots.push({ dir: path.resolve(dir), agentId: agentId || null, label: label || '环境变量指定目录', known: false, env: true });
+    roots.push({
+      dir: path.resolve(dir),
+      agentId: agentId || null,
+      label: label || '环境变量指定目录',
+      known: false,
+      env: true,
+      verified: true,
+      ...(extra || {}),
+    });
   };
 
   add(envPath(env, 'CODEX_HOME') && path.join(env.CODEX_HOME, 'skills'), 'codex', 'Codex（CODEX_HOME）');
   add(envPath(env, 'XDG_CONFIG_HOME') && path.join(env.XDG_CONFIG_HOME, 'opencode', 'skills'), 'opencode', 'OpenCode（XDG_CONFIG_HOME）');
-  add(envPath(env, 'XDG_STATE_HOME') && path.join(env.XDG_STATE_HOME, 'skills'), null, 'XDG_STATE_HOME/skills');
-  add(envPath(env, 'XDG_DATA_HOME') && path.join(env.XDG_DATA_HOME, 'skills'), null, 'XDG_DATA_HOME/skills');
+  add(envPath(env, 'XDG_STATE_HOME') && path.join(env.XDG_STATE_HOME, 'skills'), null,
+    'XDG_STATE_HOME/skills（锁桥接，不链接）', { bridgeOnly: true });
+  add(envPath(env, 'XDG_DATA_HOME') && path.join(env.XDG_DATA_HOME, 'skills'), null,
+    'XDG_DATA_HOME/skills（数据桥接，不链接）', { bridgeOnly: true });
   add(envPath(env, 'DSH_HOME') && path.join(env.DSH_HOME, 'skills'), 'dsh', 'DSH（DSH_HOME）');
   add(envPath(env, 'DSH_AGENTS_HOME') && path.join(env.DSH_AGENTS_HOME, 'skills'), 'dsh', 'DSH Agents（DSH_AGENTS_HOME）');
   add(envPath(env, 'OPENCLAW_STATE_DIR') && path.join(env.OPENCLAW_STATE_DIR, 'skills'), 'openclaw', 'OpenClaw（OPENCLAW_STATE_DIR）');
@@ -188,14 +219,40 @@ function envRoots(options) {
     .split(path.delimiter)
     .map((item) => item.trim())
     .filter(Boolean);
-  for (const dir of extra) add(dir, null, 'YOTTA_SKILLS_DISCOVERY_ROOTS');
+  for (const dir of extra) add(dir, null, 'YOTTA_SKILLS_DISCOVERY_ROOTS', { verified: false });
 
   return roots;
 }
 
+/**
+ * Lock / data bridge directories: the official `skills` CLI keeps its lock in
+ * `$XDG_STATE_HOME/skills`, and `$XDG_DATA_HOME/skills` is a data bridge.
+ * Neither is a host skill-loading directory, so both are never link targets.
+ */
+function bridgeOnlyDirs(options) {
+  const env = envObject(options);
+  const dirs = [];
+  if (envPath(env, 'XDG_STATE_HOME')) dirs.push(path.join(env.XDG_STATE_HOME, 'skills'));
+  if (envPath(env, 'XDG_DATA_HOME')) dirs.push(path.join(env.XDG_DATA_HOME, 'skills'));
+  return dirs.map((dir) => path.resolve(dir));
+}
+
+function isBridgeOnlyDir(dir, options) {
+  if (!dir) return false;
+  const target = path.resolve(dir);
+  for (const bridge of bridgeOnlyDirs(options)) {
+    const relative = path.relative(bridge, target);
+    if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) return true;
+  }
+  return false;
+}
+
 module.exports = {
   AGENT_DIRS,
+  XDG_CONFIG_RELS,
   resolveUserDir,
   knownRoots,
   envRoots,
+  bridgeOnlyDirs,
+  isBridgeOnlyDir,
 };

package/skills/yotta-skills/lib/agent-discovery.js

@@ -101,6 +101,8 @@ function addRoot(list, seen, dir, meta) {
     if (meta && meta.known && existing) existing.known = true;
     if (meta && meta.agentId && !existing.agentId) existing.agentId = meta.agentId;
     if (meta && meta.label && existing.label === '自动发现目录') existing.label = meta.label;
+    if (meta && meta.verified) existing.verified = true;
+    if (meta && meta.bridgeOnly) existing.bridgeOnly = true;
     return;
   }
   const record = {
@@ -109,6 +111,8 @@ function addRoot(list, seen, dir, meta) {
     label: (meta && meta.label) || '自动发现目录',
     known: Boolean(meta && meta.known),
     env: Boolean(meta && meta.env),
+    verified: Boolean(meta && meta.verified),
+    bridgeOnly: Boolean(meta && meta.bridgeOnly),
     detection: (meta && meta.detection) || 'mapping',
     exists: isDirectory(resolved),
   };
@@ -169,8 +173,8 @@ function commonRoots(options) {
   add(env.ProgramFiles, 2);
   add(env['ProgramFiles(x86)'], 2);
   add(env.XDG_CONFIG_HOME, 3);
-  add(env.XDG_STATE_HOME, 3);
-  add(env.XDG_DATA_HOME, 3);
+  // XDG_STATE_HOME / XDG_DATA_HOME are lock / data bridges, not skill roots:
+  // never scan them for link targets (see agent-dirs envRoots bridgeOnly).
   add(env.DSH_HOME, 3);
   add(env.DSH_AGENTS_HOME, 3);
   add(env.OPENCLAW_STATE_DIR, 2);

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

@@ -212,6 +212,9 @@ function hostsPayload(ctx) {
     summary: {
       hosts: hosts.length,
       existing: hosts.filter((host) => host.exists).length,
+      verified: hosts.filter((host) => host.exists && host.verified && !host.bridgeOnly).length,
+      discovered: hosts.filter((host) => host.exists && !host.verified && !host.bridgeOnly).length,
+      bridge: hosts.filter((host) => host.exists && host.bridgeOnly).length,
       installedMarks: found.installed.length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
@@ -245,6 +248,9 @@ function linkPlanPayload(ctx, targetDir) {
   if (!host) {
     return { error: '目标目录不在已发现的宿主目录中；请先在宿主矩阵中确认该目录。', code: 400 };
   }
+  if (host.bridgeOnly) {
+    return { error: '该目录是锁 / 数据桥接目录（XDG_STATE_HOME/skills 或 XDG_DATA_HOME/skills），永不作为链接目标。', code: 400 };
+  }
   const result = hubLib.linkSkills({
     hubDir: ctx.hubDir,
     targetDir: host.dir,
@@ -407,6 +413,9 @@ function writeLink(ctx, body) {
   const targetDir = String(body.targetDir || '');
   const host = found.hosts.find((item) => sameDir(item.dir, targetDir));
   if (!host) return { code: 400, payload: { error: '目标目录不在已发现的宿主目录中。' } };
+  if (host.bridgeOnly) {
+    return { code: 400, payload: { error: '该目录是锁 / 数据桥接目录（XDG_STATE_HOME/skills 或 XDG_DATA_HOME/skills），永不作为链接目标。' } };
+  }
   if (body.force) {
     return {
       code: 400,

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

@@ -154,6 +154,11 @@ function samePath(left, right) {
   return a === b;
 }
 
+function pathKey(dir) {
+  const real = safeRealpath(dir);
+  return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+
 function isInside(root, target) {
   const base = safeRealpath(root);
   const candidate = safeRealpath(target);
@@ -189,6 +194,161 @@ function hashTree(dir) {
   return hash.digest('hex');
 }
 
+/** 统计目录树中的普通文件数与总字节数（不跟随链接；跨卷复制校验用）。 */
+function treeStats(dir) {
+  let files = 0;
+  let bytes = 0;
+  const walk = (current) => {
+    for (const name of fs.readdirSync(current)) {
+      const full = path.join(current, name);
+      const stat = fs.lstatSync(full);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) walk(full);
+      else if (stat.isFile()) {
+        files += 1;
+        bytes += stat.size;
+      }
+    }
+  };
+  walk(path.resolve(dir));
+  return { files, bytes };
+}
+
+/** 重建链接条目：目录优先用 junction（Windows）/ dir（POSIX），文件用 file。 */
+function copyLinkEntry(src, dest) {
+  const target = fs.readlinkSync(src);
+  let kinds;
+  if (process.platform === 'win32') {
+    let isDir = null;
+    try {
+      isDir = fs.statSync(src).isDirectory();
+    } catch (_) {
+      isDir = null;
+    }
+    kinds = isDir === false ? ['file', 'junction'] : ['junction', 'file'];
+  } else {
+    let isDir = false;
+    try {
+      isDir = fs.statSync(src).isDirectory();
+    } catch (_) {
+      isDir = false;
+    }
+    kinds = [isDir ? 'dir' : 'file'];
+  }
+  let lastError = null;
+  for (const kind of kinds) {
+    try {
+      fs.symlinkSync(target, dest, kind);
+      return;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError || new Error('无法重建链接：' + src);
+}
+
+/** 逐条目复制目录树（保真：含链接、空目录与全部普通文件）。 */
+function copyEntryFaithful(src, dest) {
+  const stat = fs.lstatSync(src);
+  if (stat.isSymbolicLink()) {
+    copyLinkEntry(src, dest);
+    return;
+  }
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      const child = path.join(src, name);
+      const childStat = fs.lstatSync(child);
+      if (childStat.isSymbolicLink()) copyLinkEntry(child, path.join(dest, name));
+      else if (childStat.isDirectory()) copyEntryFaithful(child, path.join(dest, name));
+      else if (childStat.isFile()) fs.copyFileSync(child, path.join(dest, name));
+      else throw new Error('不支持的条目类型：' + child);
+    }
+    return;
+  }
+  if (stat.isFile()) {
+    fs.copyFileSync(src, dest);
+    return;
+  }
+  throw new Error('不支持的条目类型：' + src);
+}
+
+/** 删除条目：链接只删链接本身，不触碰目标。 */
+function removeEntryFaithful(entryPath) {
+  const stat = fs.lstatSync(entryPath);
+  if (stat.isSymbolicLink()) {
+    removeDirLink(entryPath);
+    return;
+  }
+  fs.rmSync(entryPath, { recursive: true, force: true });
+}
+
+/** 校验复制结果：链接比对目标，目录比对 treeHash + 文件数 + 字节数。 */
+function verifyEntryCopy(src, dest) {
+  const srcStat = fs.lstatSync(src);
+  const destStat = fs.lstatSync(dest);
+  if (srcStat.isSymbolicLink() !== destStat.isSymbolicLink()) {
+    return { ok: false, reason: '条目类型不一致' };
+  }
+  if (srcStat.isSymbolicLink()) {
+    if (fs.readlinkSync(src) !== fs.readlinkSync(dest)) {
+      return { ok: false, reason: '链接目标不一致' };
+    }
+    return { ok: true };
+  }
+  if (hashTree(src) !== hashTree(dest)) {
+    return { ok: false, reason: 'treeHash 不一致' };
+  }
+  const from = treeStats(src);
+  const to = treeStats(dest);
+  if (from.files !== to.files || from.bytes !== to.bytes) {
+    return {
+      ok: false,
+      reason: '文件数 / 字节数不一致（源 ' + from.files + ' 个 / ' + from.bytes + ' 字节；副本 ' +
+        to.files + ' 个 / ' + to.bytes + ' 字节）',
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * 跨卷安全移动：优先 rename；EXDEV（跨盘）时回退「复制 → 校验 → 删除源」。
+ * 任一步失败都不静默丢数据：源完整则回滚副本；源已不完整则保留完整副本并报出路径。
+ */
+function moveEntryAcrossDevices(src, dest, options) {
+  const opts = options || {};
+  const renameEntry = typeof opts.renameEntry === 'function' ? opts.renameEntry : fs.renameSync;
+  try {
+    renameEntry(src, dest);
+    return { method: 'rename' };
+  } catch (error) {
+    if (!error || error.code !== 'EXDEV') throw error;
+  }
+  copyEntryFaithful(src, dest);
+  let check;
+  try {
+    check = verifyEntryCopy(src, dest);
+  } catch (error) {
+    check = { ok: false, reason: error.message };
+  }
+  if (!check.ok) {
+    try { removeEntryFaithful(dest); } catch (_) { /* 保留现场供排查 */ }
+    throw new Error('跨卷复制校验失败（' + check.reason + '）；源目录未动，副本已清理');
+  }
+  try {
+    removeEntryFaithful(src);
+  } catch (error) {
+    let intact = false;
+    try { intact = verifyEntryCopy(dest, src).ok; } catch (_) { intact = false; }
+    if (intact) {
+      try { removeEntryFaithful(dest); } catch (_) { /* 保留现场供排查 */ }
+      throw new Error('跨卷复制完成但源删除失败：' + error.message + '；源目录完整，副本已回滚');
+    }
+    throw new Error('跨卷复制完成但源删除失败：' + error.message + '；完整副本保留在 ' + dest);
+  }
+  return { method: 'copy' };
+}
+
 function scanHubSkills(hubDir) {
   const root = path.resolve(hubDir);
   const result = [];
@@ -491,6 +651,7 @@ function linkSkills(options) {
   const results = [];
   const trashRoot = resolveTrashRoot(hubDir, opts);
   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));
   let prunedTrash = 0;
@@ -520,6 +681,7 @@ function linkSkills(options) {
       const moves = [];
       const skipped = [];
       let block = null;
+      let replaceExactLink = false;
 
       const evaluate = (copy, isExact) => {
         if (!copy) return;
@@ -532,7 +694,11 @@ function linkSkills(options) {
             return;
           }
           if (isExact) {
-            block = { status: 'conflict', note: '目标已存在指向 Hub 之外的链接（默认跳过；确认后可加 --force 替换）' };
+            if (force) {
+              replaceExactLink = true;
+            } else {
+              block = { status: 'conflict', note: '目标已存在指向 Hub 之外的链接（默认跳过；确认后可加 --force 替换）' };
+            }
           } else {
             skipped.push(copy.name + '（外部链接，保留）');
           }
@@ -593,7 +759,8 @@ function linkSkills(options) {
           slug,
           status: 'would-converge',
           target,
-          note: '将收敛 ' + moves.length + ' 份旧副本（移入回收站，保留 ' + TRASH_RETENTION_DAYS + ' 天）后建立链接：' +
+          note: '将收敛 ' + moves.length + ' 份旧副本（移入回收站，保留 ' + TRASH_RETENTION_DAYS + ' 天）' +
+            (replaceExactLink ? '并替换指向 Hub 之外的链接' : '') + '后建立链接：' +
             moves.map((item) => item.name).join('、'),
           moves: moves.map((item) => ({ from: item.dir, name: item.name, version: item.version || null })),
           trashDir: trashRoot,
@@ -601,11 +768,14 @@ function linkSkills(options) {
         continue;
       }
       if (moves.length === 0 && dryRun) {
-        results.push({ slug, status: 'would-link', target, note: '将建立链接' });
+        results.push(replaceExactLink
+          ? { slug, status: 'would-replace', target, note: '将替换指向 Hub 之外的链接并建立链接' }
+          : { slug, status: 'would-link', target, note: '将建立链接' });
         continue;
       }
       if (moves.length === 0) {
         try {
+          if (replaceExactLink) removeDirLink(target);
           makeLink(skill.dir, target);
           const index = links.findIndex((item) => item.slug === slug && samePath(item.dir || '', targetDir));
           const record = {
@@ -624,15 +794,25 @@ function linkSkills(options) {
             slug,
             status: 'linked',
             target,
-            note: '已建立链接' + (skipped.length ? '（保留：' + skipped.join('、') + '）' : ''),
+            note: (replaceExactLink
+              ? '已替换指向 Hub 之外的链接并建立链接（仅移除链接本身，目标目录未动）'
+              : '已建立链接') + (skipped.length ? '（保留：' + skipped.join('、') + '）' : ''),
+          });
+          appendAudit(hubDir, {
+            event: 'link',
+            slug,
+            target,
+            hubDir: skill.dir,
+            backup: null,
+            ...(replaceExactLink ? { replacedExternalLink: true } : {}),
           });
-          appendAudit(hubDir, { event: 'link', slug, target, hubDir: skill.dir, backup: null });
         } catch (error) {
           results.push({
             slug,
             status: 'error',
             target,
-            note: error.message + '（未静默降级为复制；请检查目录权限或改用 --dir 指定可写目录）',
+            note: (replaceExactLink ? '替换失败：' : '') + error.message +
+              '（未静默降级为复制；请检查目录权限或改用 --dir 指定可写目录）',
           });
         }
         continue;
@@ -642,10 +822,19 @@ function linkSkills(options) {
         for (const item of moves) {
           const dest = path.join(trashRoot, stamp, hostName, item.name);
           fs.mkdirSync(path.dirname(dest), { recursive: true });
-          fs.renameSync(item.dir, dest);
-          moved.push({ from: item.dir, to: dest, name: item.name, version: item.version || null });
+          const transfer = moveEntryAcrossDevices(item.dir, dest, { renameEntry });
+          moved.push({
+            from: item.dir,
+            to: dest,
+            name: item.name,
+            version: item.version || null,
+            method: transfer.method,
+          });
+        }
+        if (!exactHealthy) {
+          if (replaceExactLink) removeDirLink(target);
+          makeLink(skill.dir, target);
         }
-        if (!exactHealthy) makeLink(skill.dir, target);
         const index = links.findIndex((item) => item.slug === slug && samePath(item.dir || '', targetDir));
         const record = {
           slug,
@@ -660,11 +849,14 @@ function linkSkills(options) {
         };
         if (index >= 0) links[index] = record;
         else links.push(record);
+        const copiedCount = moved.filter((item) => item.method === 'copy').length;
         results.push({
           slug,
           status: 'linked',
           target,
           note: '已收敛 ' + moved.length + ' 份旧副本（回收站保留 ' + TRASH_RETENTION_DAYS + ' 天）并建立链接' +
+            (replaceExactLink ? '（已替换指向 Hub 之外的链接；仅移除链接本身）' : '') +
+            (copiedCount ? '（其中 ' + copiedCount + ' 份跨卷复制，校验通过）' : '') +
             (skipped.length ? '；保留：' + skipped.join('、') : ''),
           moved,
           trashDir: trashRoot,
@@ -677,13 +869,14 @@ function linkSkills(options) {
           hubVersion: skill.version,
           moved,
           trashDir: trashRoot,
+          ...(replaceExactLink ? { replacedExternalLink: true } : {}),
         });
       } catch (error) {
         let restored = true;
         for (const item of moved.slice().reverse()) {
           try {
             fs.mkdirSync(path.dirname(item.from), { recursive: true });
-            fs.renameSync(item.to, item.from);
+            moveEntryAcrossDevices(item.to, item.from, { renameEntry });
           } catch (_) { restored = false; }
         }
         results.push({
@@ -976,6 +1169,23 @@ function doctor(options) {
       link.status === 'ok' ? null : '运行 hub link --all 重建，或 hub unlink 清理断链');
   }
 
+  const scopeDirs = Array.isArray(opts.linkScopeDirs) ? opts.linkScopeDirs : null;
+  if (scopeDirs && scopeDirs.length > 0) {
+    const scope = new Set(scopeDirs.map((dir) => pathKey(dir)));
+    const outside = new Map();
+    for (const link of links) {
+      if (!link.dir) continue;
+      if (scope.has(pathKey(link.dir))) continue;
+      if (!outside.has(link.dir)) outside.set(link.dir, []);
+      outside.get(link.dir).push(link.slug);
+    }
+    for (const [dir, slugs] of outside) {
+      add('link_scope:' + dir, false, 'warning',
+        '链接位于默认范围之外: ' + dir + '（' + slugs.length + ' 条）',
+        '默认范围 = 已核实宿主；如需保留请用 hub link --dir 或 --include-discovered 显式重建，否则用 hub unlink --dir "' + dir + '" 清理');
+    }
+  }
+
   try {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
@@ -1009,6 +1219,7 @@ module.exports = {
   writeLinkState,
   appendAudit,
   hashTree,
+  moveEntryAcrossDevices,
   scanHubSkills,
   syncHubState,
   familySlugSet,

package/skills/yotta-skills/references/hub.md

@@ -23,12 +23,34 @@ symlink），升级只改真源，已链接宿主即时生效。
 2. 版本闸门：Hub 版本 ≥ 宿主副本版本才收敛；宿主更高 → 跳过并提示先 `hub update`；
    版本无法解析 → 跳过提示（fail-safe）；
 3. 旧副本移入回收站（保留 7 天、输出恢复路径）→ 建立指向 Hub 的链接；
+   跨盘（源目录在其它卷，或经 junction / symlink 落在其它卷）时 `rename`
+   会报 `EXDEV`，自动回退「复制 → 校验（treeHash + 文件数 + 字节数）→ 删除源」；
+   建链失败后的恢复同样支持跨盘回退，校验不通过不会删除源；
 4. 先移后链；建链失败自动尝试恢复已移动副本，恢复失败时报出回收站路径；
+   目标条目为指向 Hub 之外的链接时默认跳过；显式 `--force` 可替换为 Hub 链接
+   （仅移除链接本身，目标目录不动；dry-run 报 `would-replace`）；
 5. 外部技能保持原行为：同名冲突默认跳过，不自动删、不自动更新。
 
 落地后跑一次 `hub link --all` 即可完成现存收敛。`hub doctor` 的
 `single_source:*` 检查只读报告宿主中的多份副本与版本参差，不自动修改。
 
+## 链接范围（0.28.0 起）
+
+`hub hosts` 把发现的目录分为三类，`hub link --all` / `hub unlink --all` 的
+**默认范围只含已核实宿主**：
+
+- **已核实（verified）**：映射经公开宿主表（Vercel Labs `skills@1.7.0`）、官方
+  文档或本机自证（应用数据 / 配置 / 管理痕迹）核实 —— 默认链接；
+- **自动发现（discovered）**：文件系统启发式扫到的目录 —— 默认不链，
+  `--include-discovered` 显式纳入；
+- **桥接（bridge）**：`XDG_STATE_HOME/skills`（官方 skills CLI 锁目录）与
+  `XDG_DATA_HOME/skills`（数据桥接）—— 永不作为链接目标，`--dir` 指向时
+  也会被拒绝（fail-closed）。
+
+未核实映射（如无文档 / 无自证的宿主）默认不链，可用 `--dir <目录>` 显式指定。
+`hub doctor` 的 `link_scope:*` 检查只读报告「位于默认范围之外」的已建链接，
+并给出 `hub unlink --dir <目录>` 的清理提示；`hub hosts` 输出三类的本机计数。
+
 ## 命令
 
 ```bash
@@ -50,11 +72,14 @@ npx -y @yottameta/yotta-skills hub adopt --apply
 # 非元阁来源技能没有统一更新源：手动从指定目录刷新
 npx -y @yottameta/yotta-skills hub refresh my-skill --from <技能目录>
 
-# 分发到全部已发现宿主：元技能链接时收敛旧副本（回收站 7 天）；
+# 分发到全部已核实宿主（默认范围）：元技能链接时收敛旧副本（回收站 7 天）；
 # 外部技能同名真目录默认跳过（--force 才备份并替换）
 npx -y @yottameta/yotta-skills hub link --all
 
-# 只删除链接，不动 Hub 真源
+# 显式把自动发现目录一并纳入（桥接目录永不链接）
+npx -y @yottameta/yotta-skills hub link --all --include-discovered
+
+# 只删除链接，不动 Hub 真源；清理范围外链接用 --dir <目录> 精确指定
 npx -y @yottameta/yotta-skills hub unlink --all
 
 # 查看来源、版本、链接宿主与异常
@@ -64,11 +89,14 @@ npx -y @yottameta/yotta-skills hub doctor
 
 ## 宿主发现口径
 
-1. 已收录宿主映射（兼容 Vercel Labs `skills` CLI / SkillCat 的公开宿主表）；
+1. 已收录宿主映射（81 条；兼容 Vercel Labs `skills` CLI / SkillCat 的公开宿主表，
+   经 0.28.0 逐智能体核实：XDG 解析只覆盖 skills CLI 表确认的 `.config/agents`、
+   `.config/devin`、`.config/opencode` 三类 rel，其余 `.config/...` 按字面
+   `~/.config` 解析）；
 2. 环境变量覆盖（`CODEX_HOME`、`XDG_CONFIG_HOME`、`DSH_HOME`、
    `OPENCLAW_STATE_DIR`、`CLAUDE_CONFIG_DIR` 等）；
 3. 常见配置根启发式扫描；
-4. `YOTTA_SKILLS_DISCOVERY_ROOTS` 显式补充；
+4. `YOTTA_SKILLS_DISCOVERY_ROOTS` 显式补充（自动发现类，需 `--include-discovered`）；
 5. `--dir <path>` 精确指定非标准宿主。
 
 自动发现默认排除临时目录、`.bak`、candidate / staging、插件构建目录等噪声。

package/skills/yotta-skills/scripts/yotta-skills-mcp.py

@@ -27,7 +27,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.27.0"
+VERSION = "0.28.0"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"