@yottameta/yotta-skills-plugin 0.29.10 → 0.30.0

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

@@ -179,24 +179,25 @@ const CLI_HELP_MODEL = [
         subcommands: [
           { name: 'hosts', usage: 'hub hosts [--json] [--state <state>]', what: '发现宿主与技能目录（可用 / 残留 / 未创建 / 仅标记 / 桥接）', when: '先看这台机器有哪些宿主目录时', options: ['--json', '--state'] },
           { name: 'hosts add', usage: 'hub hosts add <dir> [--label <名称>] [--id <agentId>] [--json]', what: '注册自定义宿主目录（纳入发现 / 分发 / 收编；不创建目录）', when: '宿主未被自动识别或识别错误时', options: ['--label', '--id', '--json'] },
-          { name: 'hosts remove', usage: 'hub hosts remove <dir | --id <agentId>> [--purge [--yes]] [--json]', what: '移除注册（绝不删目录）；--purge = 清理残留目录（默认预览，--yes 执行）', when: '注销自定义宿主、清理残留目录时', options: ['--id', '--purge', '--yes', '--json'] },
-          { name: 'hosts list', usage: 'hub hosts list [--json]', what: '查看自定义宿主注册表（hosts.json）', when: '核对已注册的自定义目录时', options: ['--json'] },
-          { name: 'hosts mark', usage: 'hub hosts mark <dir> --state <available|orphan|ignored> [--json]', what: '手动标记宿主状态（可用 / 残留 / 忽略）', when: '实体证据不足需要人工确认时', options: ['--state', '--json'] },
-          { name: 'hosts exclude', usage: 'hub hosts exclude <agentId|dir> [--json]', what: '加入「不接管」名单（发现 / 显示 / 链接三层跳过）', when: '某宿主 / 目录不归元阁管理时', options: ['--json'] },
+          { name: 'hosts rename', usage: 'hub hosts rename <dir | --id <agentId>> --label <名称> [--json]', what: '一步改名（只改显示名；目录与手动状态保持）', when: '自定义宿主显示名不合适时', options: ['--label', '--id', '--json'] },
+          { name: 'hosts remove', usage: 'hub hosts remove <dir | --id <agentId>> [--purge [--yes]] [--json]', what: '移除注册（绝不删目录）；--purge = 清理残留目录（默认预览，--yes 执行）', when: '注销自定义宿主、清理残留目录时', options: ['--id', '--purge', '--yes', '--json'], impact: '影响面：只移除注册表条目（目录保留）；--purge 会把残留目录移入回收站（保留 7 天）；不会自动清理该目录里已有的 Hub 链接。', alternative: '替代路径：只想暂停接管用 hub hosts exclude；清理该目录链接用 hub unlink --dir "<目录>"。' },
+          { name: 'hosts list', usage: 'hub hosts list [--json]', what: '查看自定义宿主注册表（仅手动 add 的目录；全部宿主用 hub hosts）', when: '核对已注册的自定义目录时', options: ['--json'] },
+          { name: 'hosts mark', usage: 'hub hosts mark <dir> --state <available|orphan|ignored> [--json]', what: '手动标记宿主状态（可用 / 残留 / 隐藏标记）；隐藏标记只影响显示，不拦截行为', when: '实体证据不足需要人工确认、或想让某行从列表淡化时', options: ['--state', '--json'], impact: '影响面：纯状态标记（available / orphan / ignored），不移动目录、不改链接。真正拦截行为的是「不接管」（hosts exclude）。' },
+          { name: 'hosts exclude', usage: 'hub hosts exclude <agentId|dir> [--json]', what: '加入「不接管」名单（发现 / 显示 / 链接三层跳过）', when: '某宿主 / 目录不归元阁管理时', options: ['--json'], impact: '影响面：发现 / 显示 / 链接三层全部跳过（--include-discovered 也不纳入）；已有链接不动。', alternative: '替代路径：只淡化显示用 hub hosts mark --state ignored；恢复接管用 hub hosts include。' },
           { 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 [--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: 'config rollback', usage: 'hub config rollback [--yes] [--clean-residue]', what: '回滚到上次迁移前的 Hub 位置（位置回退，用当前内容；反向迁移同内核）', when: '迁移后想退回原位置时', options: ['--yes', '--clean-residue', '--json'], impact: '影响面：位置回退（用当前内容复制回原位置并重链，不恢复旧快照）；目标非空时 fail-closed 阻断。', alternative: '替代路径：只查看历史迁移用 hub config get；继续当前位置则不需要操作。' },
+          { name: 'config clear', usage: 'hub config clear [--yes] [--json]', what: '清除配置覆盖，恢复 flag > env > 默认；当前 Hub 有技能时默认阻断，--yes 显式确认', when: '撤销持久 Hub 位置时', options: ['--yes', '--json'], impact: '影响面：清除后生效位置回落到默认（可能是空目录）；Hub 真源与宿主链接不移动，但元阁命令将按新位置工作（表现为台账 / 链接空转）。', alternative: '替代路径：迁移位置用 hub config set --hub "<新路径>" --move；想回原位置用 hub config set --hub "<原路径>"。' },
           { 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'] },
           { name: 'refresh', usage: 'hub refresh <slug> --from <path>', what: '手动同步非元阁技能（无统一更新源）', when: '外部技能更新后刷新 Hub 副本时', options: ['--from'] },
           { name: 'link', usage: 'hub link [skill...] [--all | --agent <id> | --dir <path>] [--include-discovered] [--dry-run]', what: '把 Hub 技能链接到宿主目录（指定智能体 / 全量）', when: '分发技能到各智能体时', options: ['--all', '--agent', '--dir', '--include-discovered', '--force', '--dry-run'] },
-          { name: 'unlink', usage: 'hub unlink [skill...] [--all | --agent <id> | --dir <path>] [--dry-run]', what: '只删除链接，不动 Hub 真源（fail-closed）', when: '解除某个 / 全部宿主的链接时', options: ['--all', '--agent', '--dir', '--include-discovered', '--dry-run'] },
-          { name: 'remove', usage: 'hub remove <slug> [--dry-run] [--include-discovered]', what: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站 + 清台账 + 审计', when: '彻底删除某个 Hub 技能时', options: ['--dry-run', '--include-discovered', '--json'] },
+          { name: 'unlink', usage: 'hub unlink [skill...] [--all | --agent <id> | --dir <path>] [--dry-run]', what: '只删除链接，不动 Hub 真源（fail-closed；--dir 无 slug 时以文件系统为真源清理该目录全部 Hub 链接）', when: '解除某个 / 全部宿主的链接时', options: ['--all', '--agent', '--dir', '--include-discovered', '--dry-run'], impact: '影响面：只删除宿主目录中的链接（Hub 真源保留）；只处理指向当前 Hub 的链接，指向其它位置的链接 fail-closed 不动并给出错位警告。', alternative: '替代路径：删除整个技能用 hub remove <slug>；重建链接用 hub link --dir "<目录>" --force。' },
+          { name: 'remove', usage: 'hub remove <slug> [--dry-run] [--include-discovered]', what: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站 + 清台账 + 审计', when: '彻底删除某个 Hub 技能时', options: ['--dry-run', '--include-discovered', '--json'], impact: '影响面：全宿主清理该技能链接（含死链）→ Hub 目录移入回收站（保留 7 天）→ 清台账；影响范围大。', alternative: '替代路径：只想解除某宿主链接用 hub unlink；只想清死链用 hub remove <slug> --agent/--dir（目标缺失时）。' },
           { name: 'status', usage: 'hub status [--json]', what: '查看 Hub 技能 / 来源 / 版本 / 链接 / 宿主', when: '核对 Hub 现状时', options: ['--json'] },
           { name: 'doctor', usage: 'hub doctor [--json]', what: '检查断链 / 目标缺失 / slug 不一致 / 单一真源 / 链接范围', when: 'Hub 异常后排查时', options: ['--json'] },
         ],
@@ -302,6 +303,7 @@ const CLI_HELP_QUICK = [
       { cmd: 'hub hosts', example: 'yotta-skills hub hosts' },
       { cmd: 'hub hosts', example: 'yotta-skills hub hosts --state orphan' },
       { cmd: 'hub hosts add', example: 'yotta-skills hub hosts add <技能目录>' },
+      { cmd: 'hub hosts rename', example: 'yotta-skills hub hosts rename <技能目录> --label <新名称>', note: '只改显示名；目录与手动状态保持' },
       { cmd: 'hub hosts list', example: 'yotta-skills hub hosts list' },
       { cmd: 'hub hosts mark', example: 'yotta-skills hub hosts mark <技能目录> --state orphan' },
       { cmd: 'hub hosts exclude', example: 'yotta-skills hub hosts exclude <agentId|目录>' },
@@ -310,9 +312,9 @@ const CLI_HELP_QUICK = [
       { 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 config clear', example: 'yotta-skills hub config clear', danger: true, note: '清除持久覆盖，恢复默认解析；当前 Hub 有技能时默认阻断，确认影响后加 --yes' },
       { 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 <技能目录>', note: '只移除注册，不删目录；该目录已有链接不清理（用 hub unlink --dir）' },
       { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录> --purge', danger: true, note: '清理残留目录：先预览，--yes 才执行；目录入回收站保留 7 天' },
       { cmd: 'hub install', example: 'yotta-skills hub install' },
       { cmd: 'hub update', example: 'yotta-skills hub update' },
@@ -322,6 +324,7 @@ const CLI_HELP_QUICK = [
       { cmd: 'hub link', example: 'yotta-skills hub link --all' },
       { cmd: 'hub link', example: 'yotta-skills hub link <技能> --agent codex', note: '针对指定智能体分发' },
       { cmd: 'hub unlink', example: 'yotta-skills hub unlink <技能> --agent codex', note: '只解除该智能体的链接，Hub 真源保留' },
+      { cmd: 'hub unlink', example: 'yotta-skills hub unlink --dir <技能目录>', note: '清理该目录全部指向当前 Hub 的链接（文件系统为真源；其它位置链接不动）' },
       { cmd: 'hub unlink', example: 'yotta-skills hub unlink --all' },
       { cmd: 'hub remove', example: 'yotta-skills hub remove <技能> --dry-run', danger: true, note: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站（7 天）+ 清台账；先 --dry-run 看影响' },
       { cmd: 'hub status', example: 'yotta-skills hub status' },

package/skills/yotta-skills/lib/hosts-registry.js

@@ -183,7 +183,7 @@ function markHost(opts, input) {
   const options = opts || {};
   const state = input && input.state ? String(input.state).toLowerCase() : null;
   if (!MANUAL_STATES.includes(state)) {
-    return { ok: false, error: '未知手动状态：' + state + '（可用 available / 残留 orphan / 忽略 ignored）' };
+    return { ok: false, error: '未知手动状态：' + state + '（可用 available / 残留 orphan / 隐藏标记 ignored）' };
   }
   const dir = input && input.dir ? path.resolve(input.dir) : null;
   if (!dir) return { ok: false, error: '缺少目录' };
@@ -206,6 +206,33 @@ function markHost(opts, input) {
   return { ok: true, entry, registry };
 }
 
+/** 一步改名：只改显示名 label，不动目录 / 手动状态 / 覆盖（0.30.0 UX-08）。 */
+function renameHost(opts, input) {
+  const options = opts || {};
+  const label = String((input && input.label) || '').trim();
+  const labelError = validateLabel(label);
+  if (labelError) return { ok: false, error: labelError };
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  const id = input && input.id ? String(input.id).trim().toLowerCase() : null;
+  if (!dir && !id) return { ok: false, error: '缺少目标：hub hosts rename <目录> --label <名称> 或 --id <agentId>' };
+  const registry = readHostsRegistry(options);
+  const entry = registry.hosts.find((item) =>
+    (dir && samePath(item.dir, dir)) ||
+    (id && String(item.agentId || '').toLowerCase() === id));
+  if (!entry) {
+    return {
+      ok: false,
+      error: '未找到注册项' + (dir ? '：' + dir : '：' + id),
+      hint: '本命令只改自定义注册表（hub hosts list）里的显示名；未注册目录先 hub hosts add <目录> --label <名称>，内置映射改名用 hub hosts set <agentId> --label <名称>。',
+    };
+  }
+  const previous = entry.label;
+  entry.label = label;
+  entry.updatedAt = nowIso();
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, previous, registry };
+}
+
 /** 0.29.1 U2：不接管名单匹配（agentId 或目录）；返回命中条目或 null。 */
 function excludedEntryFor(registry, input) {
   const agentId = input && input.agentId ? String(input.agentId).toLowerCase() : null;
@@ -331,6 +358,7 @@ module.exports = {
   addHost,
   removeHost,
   markHost,
+  renameHost,
   excludedEntryFor,
   excludeHost,
   includeHost,

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

@@ -314,7 +314,18 @@ function refreshFrom(options) {
     }
     scan = opts.scan(source, { slug });
     if (!scan.ok) return { ok: false, slug, error: scan.error || '扫描失败' };
-    if (scan.block && !opts.allowUnverified) return { ok: false, slug, error: '元信 verdict: ' + scan.verdict };
+    if (scan.block && !opts.allowUnverified) {
+      return {
+        ok: false, slug, error: '元信 verdict: ' + scan.verdict, blocked: true,
+        // 0.30.0 OPT-05：附带扫描明细，供 CLI 输出「与上一已审版本」差异摘要。
+        scan: {
+          verdict: scan.verdict,
+          counts: scan.counts || null,
+          findings: scan.findings || null,
+          excluded: (scan.policy && scan.policy.excludedFindings) || [],
+        },
+      };
+    }
   }
   let backup = null;
   let tmp = null;

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

@@ -117,6 +117,7 @@ function hubScanSkill(hubDir, discovery, opts, skillDir, context) {
     counts: reviewed.counts,
     block: verdict.block,
     policy: reviewed.policy || null,
+    findings: reviewed.findings || null,
   };
 }
 

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

@@ -204,6 +204,7 @@ function overviewPayload(ctx) {
       configured: hubNow.configured,
       configFile: hubNow.configFile,
       effectiveNow: hubNow.dir,
+      defaultDir: skillsConfigLib.defaultHubDir({ homeDir: ctx.homeDir, env: ctx.env }),
       restartRequired: !ctx.hubFlag && !sameDir(hubNow.dir, ctx.hubDir),
     },
     standard: hubLib.STANDARD_ID,
@@ -278,9 +279,25 @@ function hostsPayload(ctx) {
   }));
   const hosts = found.hosts.map((host) => {
     const hostLinks = links.filter((link) => sameDir(link.dir, host.dir));
+    const ledgerOk = hostLinks.filter((link) => link.status === 'ok').length;
+    // 0.30.0 OPT-03：「指向当前 Hub」以文件系统为真源（台账辅助）；指向其它
+    // 位置的链接单独计数（只统计能识别为「其它 Hub」的目标），用于配置错位预警。
+    let scan = null;
+    if (host.exists && !host.bridgeOnly) {
+      try {
+        scan = hubLib.scanDirForHubLinks(host.dir, ctx.hubDir);
+      } catch (_) {
+        scan = null;
+      }
+    }
+    const otherHubLinks = scan ? scan.otherLinks.filter((item) => item.root) : [];
+    const otherHubRoots = [...new Set(otherHubLinks.map((item) => item.root))];
     return {
       ...host,
-      hubLinks: hostLinks.filter((link) => link.status === 'ok').length,
+      hubLinks: scan ? scan.hubSlugs.length : ledgerOk,
+      hubLinksLedger: ledgerOk,
+      hubLinksOther: otherHubLinks.length,
+      hubLinksOtherRoots: otherHubRoots.slice(0, 3),
       brokenLinks: hostLinks.filter((link) => link.status !== 'ok').length,
     };
   });
@@ -309,6 +326,7 @@ function hostsPayload(ctx) {
       overrides: (registry.overrides || []).length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
+      otherHubLinks: hosts.reduce((sum, host) => sum + (host.hubLinksOther || 0), 0),
       // 0.29.0 F3：宿主生命周期状态细分（面板分组 / 筛选）。
       states: {
         available: hosts.filter((host) => host.state === 'available').length,
@@ -664,6 +682,27 @@ function writeHostRemove(ctx, body) {
   return { code: 200, payload: { action: 'hosts.remove', removed: result.removed } };
 }
 
+function writeHostRename(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  const id = String(body.id || '').trim();
+  const label = String(body.label || '').trim();
+  if (!label) return { code: 400, payload: { error: '缺少新名称。' } };
+  if (!dir && !id) return { code: 400, payload: { error: '缺少目标目录或 agentId。' } };
+  const result = hostsRegistryLib.renameHost(
+    { homeDir: ctx.homeDir, env: ctx.env },
+    { dir, id, label },
+  );
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.rename',
+    dir: result.entry.dir,
+    from: result.previous,
+    to: result.entry.label,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.rename', entry: result.entry, previous: result.previous } };
+}
+
 function writeHostPurge(ctx, body) {
   if (String(body.confirm || '') !== CONFIRM.purge) {
     return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
@@ -1117,6 +1156,7 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/skills/remove') return writeRemove(ctx, body);
       if (pathname === '/api/hosts/add') return writeHostAdd(ctx, body);
       if (pathname === '/api/hosts/remove') return writeHostRemove(ctx, body);
+      if (pathname === '/api/hosts/rename') return writeHostRename(ctx, body);
       if (pathname === '/api/hosts/purge') return writeHostPurge(ctx, body);
       if (pathname === '/api/hosts/mark') return writeHostMark(ctx, body);
       if (pathname === '/api/hosts/set') return writeHostSet(ctx, body);

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

@@ -749,6 +749,47 @@ function classifyTarget(target, hubDir) {
   return { kind: 'file' };
 }
 
+/**
+ * 0.30.0 UX-02 / OPT-01：以文件系统为真源扫描目标目录内的链接。
+ * - hubSlugs：指向当前 Hub 的链接（可安全清理）
+ * - otherLinks：指向其它位置的链接（fail-closed，不动；供错位警告）
+ */
+function scanDirForHubLinks(targetDir, hubDir) {
+  const hubSlugs = [];
+  const otherLinks = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  } catch (_) {
+    return { hubSlugs, otherLinks, scanned: 0, readable: false };
+  }
+  for (const entry of entries) {
+    const target = path.join(targetDir, entry.name);
+    const current = classifyTarget(target, hubDir);
+    if (current.kind !== 'link') continue;
+    if (current.inHub) hubSlugs.push(entry.name);
+    else otherLinks.push({ slug: entry.name, target: current.target, root: foreignHubRoot(current.target) });
+  }
+  return { hubSlugs, otherLinks, scanned: entries.length, readable: true };
+}
+
+/**
+ * 解析链接目标所属的「其它 Hub」根目录：宿主链接通常指向 <hub>/<slug>，
+ * 因此先看目标本身、再看父目录是否含元阁 Hub 台账标记；都不是则返回 null。
+ */
+function foreignHubRoot(target) {
+  if (!target) return null;
+  const resolved = path.resolve(target);
+  for (const dir of [resolved, path.dirname(resolved)]) {
+    try {
+      if (fs.existsSync(path.join(dir, STATE_FILE))) return dir;
+      if (fs.existsSync(path.join(dir, LINKS_FILE))) return dir;
+      if (fs.existsSync(path.join(dir, AUDIT_FILE))) return dir;
+    } catch (_) { /* 单个候选失败继续 */ }
+  }
+  return null;
+}
+
 function linkSkills(options) {
   const opts = options || {};
   const hubDir = path.resolve(opts.hubDir);
@@ -1125,13 +1166,32 @@ function unlinkSkills(options) {
   const hubDir = path.resolve(opts.hubDir);
   const targetDir = path.resolve(opts.targetDir);
   const dryRun = Boolean(opts.dryRun);
-  const slugs = Array.isArray(opts.slugs) && opts.slugs.length > 0
-    ? opts.slugs
-    : readLinkState(hubDir).links
+  const linkState = readLinkState(hubDir);
+  let slugs = null;
+  let discovery = null;
+  if (Array.isArray(opts.slugs) && opts.slugs.length > 0) {
+    slugs = opts.slugs;
+  } else {
+    // 0.30.0 UX-02 / OPT-01：无 slug 时以文件系统为真源扫描目标目录
+    // （台账仅作辅助），保证「指向当前 Hub 的链接」即使台账缺失也能被清理；
+    // 同时记录指向其它位置的链接数，供调用方输出错位警告。
+    const ledgerSlugs = linkState.links
       .filter((item) => samePath(item.dir || '', targetDir))
       .map((item) => item.slug);
+    const scan = scanDirForHubLinks(targetDir, hubDir);
+    slugs = [...new Set(ledgerSlugs.concat(scan.hubSlugs))];
+    discovery = {
+      source: 'filesystem+ledger',
+      fromLedger: ledgerSlugs.length,
+      fromFilesystem: scan.hubSlugs.length,
+      scannedEntries: scan.scanned,
+      dirReadable: scan.readable,
+      otherLinks: scan.otherLinks.length,
+      otherTargets: [...new Set(scan.otherLinks.map((item) => item.root || item.target))].slice(0, 5),
+    };
+  }
   const unique = [...new Set(slugs)];
-  const links = readLinkState(hubDir).links.slice();
+  const links = linkState.links.slice();
   const results = [];
 
   for (const slug of unique) {
@@ -1165,7 +1225,7 @@ function unlinkSkills(options) {
     }
   }
   if (!dryRun) writeLinkState(hubDir, { links });
-  return { hubDir, targetDir, dryRun, results };
+  return { hubDir, targetDir, dryRun, results, discovery };
 }
 
 /**
@@ -1640,6 +1700,39 @@ function doctor(options) {
     }
   }
 
+  // 0.30.0 UX-03：宿主链接目标 vs 当前 Hub 一致性（配置错位提前发现）。
+  if (scopeDirs && scopeDirs.length > 0) {
+    const foreign = new Map();
+    for (const dir of scopeDirs) {
+      let entries = [];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch (_) {
+        continue;
+      }
+      for (const entry of entries) {
+        const target = path.join(dir, entry.name);
+        const current = classifyTarget(target, hubDir);
+        if (current.kind !== 'link' || current.inHub) continue;
+        const root = foreignHubRoot(current.target);
+        if (!root) continue;
+        if (!foreign.has(root)) {
+          foreign.set(root, { count: 0, dirs: new Set(), slugs: new Set() });
+        }
+        const rec = foreign.get(root);
+        rec.count += 1;
+        rec.dirs.add(dir);
+        rec.slugs.add(entry.name);
+      }
+    }
+    for (const [target, rec] of foreign) {
+      add('hub_mismatch:' + pathKey(target), false, 'warning',
+        '发现 ' + rec.count + ' 条链接指向其它 Hub: ' + target + '（当前 Hub: ' + hubDir + '）',
+        '核对位置来源: yotta-skills hub config get；恢复配置 = hub config set --hub "' + target +
+        '"，或重链到当前 Hub = hub link --all --force。');
+    }
+  }
+
   try {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
@@ -1711,6 +1804,7 @@ module.exports = {
   createDirLink,
   removeDirLink,
   classifyTarget,
+  scanDirForHubLinks,
   linkSkills,
   unlinkSkills,
   removeSkills,

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

@@ -24,7 +24,7 @@ npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub"        # 只换
 npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub" --move # 迁移：复制校验 → 重链 → 旧 Hub 入回收站
 npx -y @yottameta/yotta-skills hub config rollback           # 回滚预览（上次迁移前的原位置）
 npx -y @yottameta/yotta-skills hub config rollback --yes     # 执行回滚（位置回退，用当前内容）
-npx -y @yottameta/yotta-skills hub config clear              # 清除覆盖，回到 flag > env > 默认
+npx -y @yottameta/yotta-skills hub config clear              # 清除覆盖（有技能时默认阻断，确认影响后加 --yes）
 ```
 
 - 配置文件：`<YOTTA_SKILLS_HOME>/config.json`（默认 `~/.yottaskills/config.json`；schema v1，原子写）。
@@ -34,6 +34,7 @@ npx -y @yottameta/yotta-skills hub config clear              # 清除覆盖，
 - 迁移记录：`config.json` 的 `lastMigration` 记录时间 / from→to / 校验技能数 / 重链目录数 / 回收站与剩余天数；`hub config get` 展示「最近一次迁移」块与回滚命令。
 - 回滚语义：`hub config rollback` 默认预览、`--yes` 执行 = 位置回退（把当前 Hub 内容复制校验回原位置，再重链、当前 Hub 入回收站 7 天）；**不是**恢复旧快照。目标非空 fail-closed（不合并）。
 - 仅切换指针（不带 `--move`）时，若旧 Hub 非空会记录「未迁移」并在面板提示「旧 Hub 还有 N 个技能未迁移」+ 一键迁移；执行迁移 / 回滚后该提示自动清除。
+- `hub config clear` 影响面防护（0.30.0）：当前配置 Hub 仍有技能时默认阻断（fail-closed），输出影响面（回落默认位置、真源与链接不移动）、替代路径（`hub config set --hub <新路径> --move`）与 `--yes` 指引；确认后加 `--yes` 执行。`hub config get` 若检测到运行中的 `view` 面板仍用旧位置，会提示重启面板生效。
 - 面板「Hub 位置」区显示来源 / 配置覆盖 / 重启提示，并提供「设置新位置（迁移向导：迁移 / 仅切换，默认迁移）/ 最近一次迁移 + 一键回滚 / 清除覆盖」（写操作需页面令牌 + `hub-config` 确认串）；已在运行的 `view` 需重启后生效。
 - 误用防护：`--hub` 只允许与 `hub` / `view` / `where` 一起使用；其它命令（含裸 `--hub`）fail-closed 报错，不再静默忽略。
 
@@ -99,6 +100,7 @@ Hub 真源对清单声明了 `runtimePayload` 的技能（元忆 / 元阁：`bin
   可显式清理；文案统一「实体未确认」，不判定「已卸载」；
 - **未创建**：目录不存在且无实体证据 —— 安装宿主后自动出现；
 - **仅标记**：已装实体、技能目录未创建 —— `hub link --agent <id>` 会创建目录并链接。
+- **隐藏标记**（`ignored`）：只影响列表显示，不拦截任何行为；真正拦截发现 / 显示 / 链接的是「不接管」（`hosts exclude`）。
 
 `hub doctor` 的 `host_state:*` 检查对残留 / 仅标记给 info 提示，不判 fail。
 自定义宿主目录可用 `hub hosts add` 注册进发现 / 分发 / 收编范围（只注册，
@@ -107,10 +109,11 @@ Hub 真源对清单声明了 `runtimePayload` 的技能（元忆 / 元阁：`bin
 ```bash
 # 注册 / 查看 / 移除自定义宿主（realpath 去重；Hub / 桥接目录拒绝注册）
 npx -y @yottameta/yotta-skills hub hosts add ~/my-agent/skills --label "我的宿主"
+npx -y @yottameta/yotta-skills hub hosts rename ~/my-agent/skills --label "新名字"   # 一步改名（只改显示名）
 npx -y @yottameta/yotta-skills hub hosts list
 npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills
 
-# 手动标记状态（实体证据不足时）：available / orphan / ignored
+# 手动标记状态（实体证据不足时）：available / orphan / ignored（隐藏标记，只影响显示）
 npx -y @yottameta/yotta-skills hub hosts mark ~/my-agent/skills --state orphan
 
 # 清理残留目录：默认预览；--yes 执行 —— 只删指向 Hub 的链接（含死链），
@@ -121,6 +124,7 @@ npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills --purge --yes
 
 注册表 = `<root>/hosts.json`（root = `YOTTA_SKILLS_HOME` 或 `~/.yottaskills`，schema v1，
 可 diff）；面板「宿主矩阵 → 添加自定义目录」等价可用，写操作需页面令牌与确认串。
+移除注册 / 不接管后若该目录仍有 Hub 链接，CLI 会提示剩余条数与 `hub unlink --dir` 清理指引（面板确认框同源显示）。
 
 ## 不接管与目录覆盖（0.29.1 起）
 
@@ -141,7 +145,7 @@ npx -y @yottameta/yotta-skills hub hosts set box --dir "D:\box-agent\skills"
 npx -y @yottameta/yotta-skills hub hosts set box --clear     # 恢复内置映射
 ```
 
-面板「宿主矩阵」提供等价动作：行内「不接管 / 编辑目录 / 标记可用 / 忽略」，
+面板「宿主矩阵」提供等价动作：行内「不接管 / 编辑目录 / 标记可用 / 隐藏标记 / 重命名（自定义注册）」，
 底部「不接管名单」区可「恢复接管」；写操作均写 Hub 审计。
 
 **YottaCode 不纳入接管**：YottaCode 自带三层技能管理（skill-inventory / skill /
@@ -184,7 +188,7 @@ npx -y @yottameta/yotta-skills hub link --all
 # 显式把自动发现目录一并纳入（桥接目录永不链接）
 npx -y @yottameta/yotta-skills hub link --all --include-discovered
 
-# 只删除链接，不动 Hub 真源；清理范围外链接用 --dir <目录> 精确指定
+# 只删除链接，不动 Hub 真源；--dir 不带 slug 时以文件系统为真源清理该目录全部 Hub 链接
 npx -y @yottameta/yotta-skills hub unlink --all
 
 # 指定智能体分发 / 解除（只影响该宿主；Hub 真源保留）
@@ -257,7 +261,7 @@ install / update / refresh 只在高级 CLI 页给出可复制命令，不在网
 
 ## 安全边界
 
-- `unlink` 只删除 lstat 确认为链接、且 readlink 目标位于 Hub 内的路径。
+- `unlink` 只删除 lstat 确认为链接、且 readlink 目标位于当前 Hub 内的路径；`--dir` 不带 slug 时以文件系统为真源枚举该目录（台账缺失也能清理），指向其它位置的链接 fail-closed 不动并给出错位警告。
 - 真目录 / 非 Hub 链接一律拒绝删除；`--force` 对真目录把旧副本移入回收站（7 天）再替换；
   替换失败会把旧副本移回原位（回收站路径随结果输出）。
 - `remove` 只删指向 Hub 的链接与 Hub 内目录；链接清理报错即中止、不删 Hub；

package/skills/yotta-skills/references/skill-list.md

@@ -8,8 +8,8 @@
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.2 | quality | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
 | `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.3 | quality | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
 | `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.3 | workflow | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.7 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
-| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.4.0 | memory | 学习闭环 + 知识库（CLI / MCP / 本地面板）：经验沉淀为 .learnings/ 条目；知识分类索引 + 关键词查询 |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.8 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.5.0 | memory | 学习闭环 + 知识库（CLI / MCP / 本地面板）：经验沉淀为 .learnings/ 条目；知识分类索引 + 关键词查询 |
 | `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.3.1 | security | 安全扫描引擎：13 类检测器 + 系统安全基线 + 学生数据隐私（教育版） |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.7 | security | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
 | `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.8 | security | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |

package/skills/yotta-skills/scan-policy.json

@@ -197,10 +197,10 @@
       ]
     },
     "yotta-memory": {
-      "version": "0.22.7",
-      "treeHash": "sha256:b7f7bb38b869df332563e4743c7b4ca71a9314371ff7194d1681554e8ba1ffcb",
+      "version": "0.22.8",
+      "treeHash": "sha256:809772e0b9a057c6099e5ae4b5b88bb3c1b907c7e4864d07265234d5ef5a2bab",
       "files": 18,
-      "bytes": 1344854,
+      "bytes": 1350968,
       "mode": "strict",
       "exceptions": [
         {

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

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

package/skills/yotta-skills/skills.json

@@ -31,7 +31,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "pkg": "@yottameta/yotta-memory",
-  "version": "0.22.7",
+  "version": "0.22.8",
     "domain": "memory",
     "runtimePayload": ["bin"],
     "desc": "有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT）"
@@ -40,7 +40,7 @@
       "slug": "yotta-learn",
       "name": "元习",
       "pkg": "@yottameta/yotta-learn",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "domain": "memory",
       "desc": "学习闭环 + 知识库（CLI / MCP / 本地面板）：经验沉淀为 .learnings/ 条目；知识分类索引 + 关键词查询"
     },