@yottameta/yotta-skills-plugin 0.29.0 → 0.29.1

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

@@ -87,7 +87,9 @@ 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'], verified: false },
+  // YottaCode 自带三层技能管理（skill-inventory / skill / user-skills），
+  // 不纳入元阁接管：neverLink 表示发现 / 显示 / 链接全部跳过（0.29.1 U2）。
+  yottacode:         { label: 'YottaCode',             dirs: ['.yottacode/skills'], verified: false, neverLink: true },
   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'] },
@@ -167,6 +169,14 @@ function resolveUserDir(rel, options) {
   return path.join(home, rel);
 }
 
+const YOTTACODE_PATH_RE = /(^|[\\/])\.yottacode([\\/]|$)/i;
+
+/** YottaCode 路径判定（不接管红线；发现 / 链接 / 注册 / 标记统一 fail-closed）。 */
+function isYottaCodeDir(dir) {
+  if (!dir) return false;
+  return YOTTACODE_PATH_RE.test(path.resolve(dir));
+}
+
 /** All known agent skill directories, including missing ones. */
 function knownRoots(options) {
   const roots = [];
@@ -179,8 +189,11 @@ function knownRoots(options) {
     roots.push({ dir: resolved, agentId, label, known: true, verified: verified !== false });
   };
   for (const [agentId, info] of Object.entries(AGENT_DIRS)) {
+    if (info.neverLink) continue;
     for (const rel of info.dirs) {
-      add(resolveUserDir(rel, options), agentId, info.label, info.verified !== false);
+      const dir = resolveUserDir(rel, options);
+      if (isYottaCodeDir(dir)) continue;
+      add(dir, agentId, info.label, info.verified !== false);
     }
   }
   return roots;
@@ -213,7 +226,7 @@ function envRoots(options) {
   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）');
   add(envPath(env, 'CLAUDE_CONFIG_DIR') && path.join(env.CLAUDE_CONFIG_DIR, 'skills'), 'claude', 'Claude Code（CLAUDE_CONFIG_DIR）');
-  add(envPath(env, 'YOTTACODE_HOME') && path.join(env.YOTTACODE_HOME, 'skills'), 'yottacode', 'YottaCode（YOTTACODE_HOME）');
+  // YOTTACODE_HOME 不纳入元阁接管（YottaCode 自带三层技能管理，0.29.1 U2）。
 
   const extra = String(env.YOTTA_SKILLS_DISCOVERY_ROOTS || '')
     .split(path.delimiter)
@@ -255,4 +268,5 @@ module.exports = {
   envRoots,
   bridgeOnlyDirs,
   isBridgeOnlyDir,
+  isYottaCodeDir,
 };

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

@@ -82,6 +82,7 @@ function isNoisePath(dir, baseDir) {
     if (part === 'temp' || part === 'tmp') return true;
     if (/\.bak$/.test(part)) return true;
     if (part === 'plugin-sources' || part === 'plugins' || part === 'node_modules') return true;
+    if (part === '.yottacode') return true;
     if (part === 'candidate' || part.startsWith('candidate-') || part.includes('staging')) return true;
     if (part === 'memories' || part === 'connectors' || part === 'workspace') return true;
   }
@@ -192,7 +193,7 @@ function commonRoots(options) {
   add(env.OPENCLAW_STATE_DIR, 2);
   add(env.CLAUDE_CONFIG_DIR, 2);
   add(env.CODEX_HOME, 2);
-  add(env.YOTTACODE_HOME, 2);
+  // YOTTACODE_HOME 不扫描（YottaCode 自带三层技能管理，0.29.1 U2）。
 
   // A portable agent install often lives beside the current workspace. The
   // scanner only follows agent-looking branches, so this stays bounded.
@@ -286,6 +287,28 @@ function judgeHostState(host) {
   return 'missing';
 }
 
+/**
+ * 0.29.1 U2：installed 配对优先级 ——
+ * user-registry / 目录覆盖 / 已核实映射 > env > 未核实映射 > 自动发现。
+ */
+function hostPairingPriority(host) {
+  if (host.detection === 'user-registry' || host.registry) return 0;
+  if (host.detection === 'override') return 1;
+  if (host.verified && host.detection === 'mapping') return 1;
+  if (host.detection === 'env') return 2;
+  if (host.detection === 'mapping') return 3;
+  return 4;
+}
+
+/** 同级按技能数降序 + 路径稳定排序（消除 last-write-wins）。 */
+function compareHostCandidates(a, b) {
+  const priority = hostPairingPriority(a) - hostPairingPriority(b);
+  if (priority) return priority;
+  const count = (b.skillCount || 0) - (a.skillCount || 0);
+  if (count) return count;
+  return String(a.dir).localeCompare(String(b.dir));
+}
+
 /**
  * Discover hosts and their skill directories.
  *
@@ -301,19 +324,56 @@ function discoverHosts(options) {
   const seen = new Map();
   const errors = [];
 
+  // 0.29.1 U2：用户级「不接管」名单 + 目录覆盖（hosts.json；旧文件向后兼容）。
+  let registry = { hosts: [], excluded: [], overrides: [] };
+  try {
+    registry = hostsRegistry.readHostsRegistry(options);
+  } catch (_) { /* registry 读取失败不影响发现 */ }
+  const overridesByAgent = new Map(
+    (registry.overrides || []).map((item) => [String(item.agentId).toLowerCase(), item]),
+  );
+  const previousDirKeys = new Set();
+  for (const item of registry.overrides || []) {
+    for (const prev of item.previousDirs || []) previousDirKeys.add(normalizePath(prev).toLowerCase());
+  }
+  // YottaCode 不接管：.yottacode 路径 + YOTTACODE_HOME 整棵子树（含任意自定义目录名）。
+  const yottacodeHome = envObject(options).YOTTACODE_HOME
+    ? path.resolve(envObject(options).YOTTACODE_HOME)
+    : null;
+  const isYottaCodePath = (dir) => {
+    if (!dir) return false;
+    if (agentDirs.isYottaCodeDir(dir)) return true;
+    if (!yottacodeHome) return false;
+    const resolved = path.resolve(dir);
+    const relative = path.relative(yottacodeHome, resolved);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+  };
+  const isExcluded = (meta) => Boolean(hostsRegistry.excludedEntryFor(registry, meta || {}));
+  const skipDir = (dir, agentId) => isYottaCodePath(dir) || isExcluded({ dir, agentId });
+
   for (const root of agentDirs.knownRoots(options)) {
+    const override = root.agentId ? overridesByAgent.get(String(root.agentId).toLowerCase()) : null;
+    if (override) {
+      if (skipDir(override.dir, root.agentId)) continue;
+      addRoot(roots, seen, override.dir, {
+        ...root,
+        label: override.label || root.label,
+        verified: true,
+        detection: 'override',
+      });
+      continue;
+    }
+    if (skipDir(root.dir, root.agentId)) continue;
     addRoot(roots, seen, root.dir, { ...root, detection: 'mapping' });
   }
   for (const root of agentDirs.envRoots(options)) {
+    if (skipDir(root.dir, root.agentId)) continue;
     addRoot(roots, seen, root.dir, { ...root, detection: root.env ? 'env' : 'workspace' });
   }
   // 合并顺序：内置映射 → 环境变量 → 用户注册表（F2）→ 自动发现；
   // 同 realpath 用户注册优先（分类 = 已核实，detection = user-registry）。
-  let registry = { hosts: [] };
-  try {
-    registry = hostsRegistry.readHostsRegistry(options);
-  } catch (_) { /* registry 读取失败不影响发现 */ }
   for (const item of registry.hosts || []) {
+    if (skipDir(item.dir, item.agentId)) continue;
     addRoot(roots, seen, item.dir, {
       detection: 'user-registry',
       label: item.label || '自定义宿主',
@@ -329,6 +389,9 @@ function discoverHosts(options) {
       maxDepth: root.maxDepth,
       baseDir: options.homeDir || os.homedir(),
     })) {
+      if (skipDir(found.dir, null)) continue;
+      // 被目录覆盖替换掉的旧映射目录不再进入默认发现 / 链接。
+      if (previousDirKeys.has(normalizePath(found.dir).toLowerCase())) continue;
       addRoot(roots, seen, found.dir, {
         detection: 'discovered',
         label: '自动发现：' + path.basename(found.parent),
@@ -362,23 +425,44 @@ function discoverHosts(options) {
     installedSeen.add(key);
     installed.push({ label, source, hasSkillsDir: false });
   };
+  // 0.29.1 U2：不接管（excluded）/ neverLink（YottaCode）宿主的应用标记同样跳过显示。
+  const isMarkerSuppressed = (name) => {
+    for (const [agentId, info] of Object.entries(agentDirs.AGENT_DIRS)) {
+      if (!info.neverLink) continue;
+      if (markerMatchesHost(name, { agentId, label: info.label })) return true;
+    }
+    return (registry.excluded || []).some((item) => {
+      if (item.kind !== 'agent') return false;
+      const info = agentDirs.AGENT_DIRS[String(item.value).toLowerCase()] || {};
+      return markerMatchesHost(name, { agentId: item.value, label: info.label || item.value });
+    });
+  };
   for (const name of markers) {
+    if (isMarkerSuppressed(name)) continue;
     if (knownLabelMatches(name) || AGENT_HINT.test(name)) addInstalled(name, '应用标记');
   }
   for (const host of roots) {
     if (host.detection === 'user-registry') addInstalled(host.label, '用户注册');
   }
+  // 0.29.1 U2：配对确定性优选（先收集全部候选，再按优先级选定），消除 last-write-wins。
+  const pairCandidates = new Map();
   for (const host of roots) {
     if (!host.exists) continue;
     if (!host.markerEvidence && host.detection !== 'user-registry') continue;
-    const item = installed.find((entry) => markerMatchesHost(entry.label, host));
-    if (item) {
-      item.hasSkillsDir = true;
-      item.skillDir = host.dir;
-      item.skillCount = host.skillCount;
-      item.agentId = host.agentId;
+    for (const item of installed) {
+      if (!markerMatchesHost(item.label, host)) continue;
+      if (!pairCandidates.has(item)) pairCandidates.set(item, []);
+      pairCandidates.get(item).push(host);
     }
   }
+  for (const [item, hosts] of pairCandidates) {
+    hosts.sort(compareHostCandidates);
+    const host = hosts[0];
+    item.hasSkillsDir = true;
+    item.skillDir = host.dir;
+    item.skillCount = host.skillCount;
+    item.agentId = host.agentId;
+  }
 
   return {
     generatedAt: new Date().toISOString(),
@@ -388,6 +472,19 @@ function discoverHosts(options) {
   };
 }
 
+/**
+ * 0.29.1 U2：未配对且无技能目录的已安装标记（CLI / 面板共用单一真源）。
+ * 已配对（hasSkillsDir）或 label 与已显示宿主重复的标记不再出现在「无技能目录」区。
+ */
+function unpairedMarkers(discovery) {
+  const shown = new Set();
+  for (const host of (discovery && discovery.hosts) || []) {
+    if (host.exists || host.state === 'marker-only') shown.add(String(host.label).toLowerCase());
+  }
+  return ((discovery && discovery.installed) || []).filter((item) =>
+    !item.hasSkillsDir && !shown.has(String(item.label).toLowerCase()));
+}
+
 module.exports = {
   AGENT_HINT,
   discoverHosts,
@@ -395,4 +492,5 @@ module.exports = {
   countSkills,
   markerMatchesHost,
   judgeHostState,
+  unpairedMarkers,
 };

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

@@ -48,6 +48,7 @@ const CLI_GLOBAL_OPTIONS = [
   { flag: '--label', arg: '<名称>', what: 'hub hosts add 的显示名称（默认取目录名）', when: '注册自定义宿主时', caution: '最长 48 字符，禁控制字符' },
   { flag: '--id', arg: '<agentId>', what: 'hub hosts add / remove 的智能体标识', when: '按智能体注册或移除自定义宿主时', caution: '' },
   { flag: '--purge', arg: '', what: 'hub hosts remove 清理残留目录（默认预览；--yes 执行）', when: '清理实体未确认的残留技能目录时', caution: '只删指向 Hub 的链接；目录移入回收站保留 7 天' },
+  { flag: '--clear', arg: '', what: 'hub hosts set 恢复内置映射（删除目录覆盖）', when: '想撤销目录覆盖时', caution: '' },
   { flag: '--scan', arg: '', what: 'hub adopt 只读预演（默认行为）', when: '先看收编候选与冲突时', caution: '' },
   { flag: '--apply', arg: '', what: 'hub adopt 执行收编', when: '确认候选后执行时', caution: '执行时逐项运行元信扫描；high / critical 默认阻断' },
   { flag: '--in-place', arg: '', what: 'hub adopt 原地登记，不复制', when: '想让 Hub 直接指向原目录时', caution: '原目录删除即断链；默认复制保真更安全' },
@@ -78,7 +79,7 @@ const CLI_HELP_MODEL = [
       {
         name: 'update',
         usage: 'update [--agent <name> | --dir <path>] [--installed-only] [--check [--scheduled] | --auto] [--only <a,b> | --domain <name>]',
-        what: '增量更新已装技能（补齐缺失 / 升级版本不一致）',
+        what: '增量更新已装技能（补齐缺失 / 升级；只升不降：本地更高保留，--force 才显式降级）',
         when: '日常维护、只读检查更新、后台周检、自动跟进时',
         options: ['--agent', '--dir', '--installed-only', '--check', '--scheduled', '--auto', '--only', '--domain', '--dry-run', '--skip-scan'],
       },
@@ -179,8 +180,11 @@ const CLI_HELP_MODEL = [
           { 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 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: '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: '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'] },
@@ -293,6 +297,9 @@ const CLI_HELP_QUICK = [
       { cmd: 'hub hosts add', example: 'yotta-skills hub hosts add <技能目录>' },
       { 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|目录>' },
+      { cmd: 'hub hosts include', example: 'yotta-skills hub hosts include <agentId|目录>' },
+      { cmd: 'hub hosts set', example: 'yotta-skills hub hosts set <agentId> --dir <目录>' },
       { 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/hosts-registry.js

@@ -42,10 +42,19 @@ function readHostsRegistry(opts) {
       return {
         version: HOSTS_REGISTRY_VERSION,
         hosts: value.hosts.filter((item) => item && typeof item.dir === 'string' && item.dir),
+        // 0.29.1 U2：不接管名单 + 目录覆盖（可选字段，向后兼容旧文件）。
+        excluded: Array.isArray(value.excluded)
+          ? value.excluded.filter((item) => item && typeof item.value === 'string' && item.value &&
+              (item.kind === 'agent' || item.kind === 'dir'))
+          : [],
+        overrides: Array.isArray(value.overrides)
+          ? value.overrides.filter((item) => item && typeof item.agentId === 'string' && item.agentId &&
+              typeof item.dir === 'string' && item.dir)
+          : [],
       };
     }
   } catch (_) { /* missing or corrupt registry falls back to empty */ }
-  return { version: HOSTS_REGISTRY_VERSION, hosts: [] };
+  return { version: HOSTS_REGISTRY_VERSION, hosts: [], excluded: [], overrides: [] };
 }
 
 function writeHostsRegistry(opts, registry) {
@@ -55,6 +64,8 @@ function writeHostsRegistry(opts, registry) {
   fs.writeFileSync(tmp, JSON.stringify({
     version: HOSTS_REGISTRY_VERSION,
     hosts: registry.hosts,
+    excluded: registry.excluded || [],
+    overrides: registry.overrides || [],
   }, null, 2) + '\n', 'utf8');
   fs.renameSync(tmp, file);
   return file;
@@ -84,6 +95,14 @@ function isInside(root, target) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
+/** YottaCode 目标判定：.yottacode 路径或 YOTTACODE_HOME 子树（0.29.1 U2）。 */
+function isYottaCodeTarget(dir, opts) {
+  if (agentDirsLib.isYottaCodeDir(dir)) return true;
+  const env = (opts && opts.env) || process.env;
+  const ycHome = env.YOTTACODE_HOME ? path.resolve(env.YOTTACODE_HOME) : null;
+  return Boolean(ycHome && dir && isInside(ycHome, dir));
+}
+
 /** fail-closed 校验：返回中文错误或 null。 */
 function validateHostDir(dir, opts) {
   const target = path.resolve(dir);
@@ -101,6 +120,9 @@ function validateHostDir(dir, opts) {
   if (agentDirsLib.isBridgeOnlyDir(target, opts)) {
     return '锁 / 数据桥接目录不允许注册：' + target;
   }
+  if (isYottaCodeTarget(target, opts)) {
+    return 'YottaCode 自带三层技能管理（skill-inventory / skill / user-skills），不纳入元阁接管：' + target;
+  }
   return null;
 }
 
@@ -165,6 +187,9 @@ function markHost(opts, input) {
   }
   const dir = input && input.dir ? path.resolve(input.dir) : null;
   if (!dir) return { ok: false, error: '缺少目录' };
+  if (isYottaCodeTarget(dir, options)) {
+    return { ok: false, error: 'YottaCode 自带三层技能管理，不纳入元阁接管，不能标记：' + dir };
+  }
   const registry = readHostsRegistry(options);
   let entry = registry.hosts.find((item) => samePath(item.dir, dir));
   if (!entry) {
@@ -181,6 +206,118 @@ function markHost(opts, input) {
   return { ok: true, entry, registry };
 }
 
+/** 0.29.1 U2：不接管名单匹配（agentId 或目录）；返回命中条目或 null。 */
+function excludedEntryFor(registry, input) {
+  const agentId = input && input.agentId ? String(input.agentId).toLowerCase() : null;
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  for (const item of (registry && registry.excluded) || []) {
+    if (!item) continue;
+    if (item.kind === 'agent' && agentId && String(item.value).toLowerCase() === agentId) return item;
+    if (item.kind === 'dir' && dir && samePath(item.value, dir)) return item;
+  }
+  return null;
+}
+
+/** 目标归类：已收录 agentId -> agent；否则按目录。 */
+function classifyExcludeTarget(target) {
+  const value = String(target || '').trim();
+  const agentId = value.toLowerCase();
+  if (agentDirsLib.AGENT_DIRS[agentId]) return { kind: 'agent', value: agentId };
+  return { kind: 'dir', value: path.resolve(value) };
+}
+
+/**
+ * 加入「不接管」名单（0.29.1 U2）：发现 / 显示 / 链接三层全部跳过，
+ * `--include-discovered` 也不纳入；幂等。
+ */
+function excludeHost(opts, input) {
+  const options = opts || {};
+  const target = input && input.target ? String(input.target).trim() : '';
+  if (!target) return { ok: false, error: '缺少目标：hub hosts exclude <agentId|目录>' };
+  const { kind, value } = classifyExcludeTarget(target);
+  if (kind === 'dir') {
+    if (isYottaCodeTarget(value, options)) {
+      return { ok: false, error: 'YottaCode 自带三层技能管理，不纳入元阁接管，无需加入不接管名单：' + value };
+    }
+    if (agentDirsLib.isBridgeOnlyDir(value, options)) {
+      return { ok: false, error: '锁 / 数据桥接目录本就不参与链接，无需加入不接管名单：' + value };
+    }
+  }
+  const registry = readHostsRegistry(options);
+  const existing = excludedEntryFor(registry, { agentId: kind === 'agent' ? value : null, dir: kind === 'dir' ? value : null });
+  if (existing) return { ok: true, entry: existing, registry, already: true };
+  const label = input && input.label
+    ? String(input.label).trim()
+    : kind === 'agent'
+      ? ((agentDirsLib.AGENT_DIRS[value] || {}).label || value)
+      : path.basename(value);
+  const entry = { kind, value, label, addedAt: nowIso() };
+  registry.excluded = (registry.excluded || []).concat([entry]);
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+/** 移出「不接管」名单（恢复接管）。 */
+function includeHost(opts, input) {
+  const options = opts || {};
+  const target = input && input.target ? String(input.target).trim() : '';
+  if (!target) return { ok: false, error: '缺少目标：hub hosts include <agentId|目录>' };
+  const { kind, value } = classifyExcludeTarget(target);
+  const registry = readHostsRegistry(options);
+  const index = (registry.excluded || []).findIndex((item) => item.kind === kind &&
+    (kind === 'agent' ? String(item.value).toLowerCase() === value : samePath(item.value, value)));
+  if (index < 0) return { ok: false, error: '未在不接管名单：' + target };
+  const removed = registry.excluded.splice(index, 1)[0];
+  writeHostsRegistry(options, registry);
+  return { ok: true, removed, registry };
+}
+
+/**
+ * 目录覆盖（0.29.1 U2）：用户级覆盖已收录 agentId 的内置映射目录；
+ * 被覆盖的旧目录不再进入默认发现 / 链接。
+ */
+function setHostOverride(opts, input) {
+  const options = opts || {};
+  const agentId = input && input.agentId ? String(input.agentId).trim().toLowerCase() : '';
+  if (!agentId) return { ok: false, error: '缺少 agentId：hub hosts set <agentId> --dir <目录>（恢复默认用 --clear）' };
+  const info = agentDirsLib.AGENT_DIRS[agentId];
+  if (!info) return { ok: false, error: '未收录智能体: ' + agentId };
+  if (info.neverLink) return { ok: false, error: 'YottaCode 不纳入元阁接管，不能设置目录覆盖。' };
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  if (!dir) return { ok: false, error: '缺少目录：hub hosts set <agentId> --dir <目录>（恢复默认用 --clear）' };
+  const guard = validateHostDir(dir, options);
+  if (guard) return { ok: false, error: guard };
+  const label = input && input.label ? String(input.label).trim() : info.label;
+  const labelError = validateLabel(label);
+  if (labelError) return { ok: false, error: labelError };
+  const registry = readHostsRegistry(options);
+  const entry = {
+    agentId,
+    dir,
+    label,
+    previousDirs: (info.dirs || []).map((rel) => agentDirsLib.resolveUserDir(rel, options)),
+    addedAt: nowIso(),
+  };
+  const index = (registry.overrides || []).findIndex((item) => String(item.agentId).toLowerCase() === agentId);
+  if (index >= 0) registry.overrides[index] = entry;
+  else registry.overrides = (registry.overrides || []).concat([entry]);
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+/** 清除目录覆盖（恢复内置映射）。 */
+function clearHostOverride(opts, input) {
+  const options = opts || {};
+  const agentId = input && input.agentId ? String(input.agentId).trim().toLowerCase() : '';
+  if (!agentId) return { ok: false, error: '缺少 agentId：hub hosts set <agentId> --clear' };
+  const registry = readHostsRegistry(options);
+  const index = (registry.overrides || []).findIndex((item) => String(item.agentId).toLowerCase() === agentId);
+  if (index < 0) return { ok: false, error: '未找到目录覆盖：' + agentId };
+  const removed = registry.overrides.splice(index, 1)[0];
+  writeHostsRegistry(options, registry);
+  return { ok: true, removed, registry };
+}
+
 module.exports = {
   HOSTS_REGISTRY_VERSION,
   MANUAL_STATES,
@@ -194,4 +331,9 @@ module.exports = {
   addHost,
   removeHost,
   markHost,
+  excludedEntryFor,
+  excludeHost,
+  includeHost,
+  setHostOverride,
+  clearHostOverride,
 };

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

@@ -204,12 +204,17 @@ function hostsPayload(ctx) {
       brokenLinks: hostLinks.filter((link) => link.status !== 'ok').length,
     };
   });
+  const registry = hostsRegistryLib.readHostsRegistry({ homeDir: ctx.homeDir, env: ctx.env });
   return {
     generatedAt: found.generatedAt,
     hubDir: ctx.hubDir,
     standard: hubLib.STANDARD_ID,
     hosts,
     installed: found.installed,
+    // 0.29.1 U2：面板只渲染未配对标记（与 CLI hubHostLines 共用单一真源）。
+    unpaired: discoveryLib.unpairedMarkers(found),
+    excluded: registry.excluded || [],
+    overrides: registry.overrides || [],
     links,
     hubSkills,
     summary: {
@@ -219,6 +224,9 @@ function hostsPayload(ctx) {
       discovered: hosts.filter((host) => host.exists && !host.verified && !host.bridgeOnly).length,
       bridge: hosts.filter((host) => host.exists && host.bridgeOnly).length,
       installedMarks: found.installed.length,
+      unpairedMarks: discoveryLib.unpairedMarkers(found).length,
+      excluded: (registry.excluded || []).length,
+      overrides: (registry.overrides || []).length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
       // 0.29.0 F3：宿主生命周期状态细分（面板分组 / 筛选）。
@@ -603,6 +611,70 @@ function writeHostPurge(ctx, body) {
   };
 }
 
+// ── 宿主标记 / 目录覆盖 / 不接管（0.29.1 U2；与 CLI 同源 hosts.json） ─────────
+function writeHostMark(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const state = String(body.state || '').trim().toLowerCase();
+  const result = hostsRegistryLib.markHost({ homeDir: ctx.homeDir, env: ctx.env }, { dir, state });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, { event: 'hosts.mark', dir: result.entry.dir, state, via: 'view' });
+  return { code: 200, payload: { action: 'hosts.mark', entry: result.entry } };
+}
+
+function writeHostSet(ctx, body) {
+  const agentId = String(body.agentId || '').trim().toLowerCase();
+  if (!agentId) return { code: 400, payload: { error: '缺少 agentId。' } };
+  const registryOpts = { homeDir: ctx.homeDir, env: ctx.env };
+  if (body.clear) {
+    const result = hostsRegistryLib.clearHostOverride(registryOpts, { agentId });
+    if (!result.ok) return { code: 400, payload: { error: result.error } };
+    auditViewHostEvent(ctx, { event: 'hosts.set', agentId, cleared: true, dir: result.removed.dir, via: 'view' });
+    return { code: 200, payload: { action: 'hosts.set', cleared: true, removed: result.removed } };
+  }
+  const dir = String(body.dir || '').trim();
+  const result = hostsRegistryLib.setHostOverride(registryOpts, { agentId, dir, label: body.label });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.set',
+    agentId,
+    dir: result.entry.dir,
+    label: result.entry.label,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.set', entry: result.entry } };
+}
+
+function writeHostExclude(ctx, body) {
+  const target = String(body.target || '').trim();
+  if (!target) return { code: 400, payload: { error: '缺少 target（agentId 或目录）。' } };
+  const result = hostsRegistryLib.excludeHost({ homeDir: ctx.homeDir, env: ctx.env }, { target });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.exclude',
+    kind: result.entry.kind,
+    value: result.entry.value,
+    label: result.entry.label,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.exclude', entry: result.entry, already: Boolean(result.already) } };
+}
+
+function writeHostInclude(ctx, body) {
+  const target = String(body.target || '').trim();
+  if (!target) return { code: 400, payload: { error: '缺少 target（agentId 或目录）。' } };
+  const result = hostsRegistryLib.includeHost({ homeDir: ctx.homeDir, env: ctx.env }, { target });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.include',
+    kind: result.removed.kind,
+    value: result.removed.value,
+    label: result.removed.label,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.include', removed: result.removed } };
+}
+
 function json(res, code, value) {
   if (res.writableEnded) return;
   res.writeHead(code, {
@@ -764,6 +836,10 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/hosts/add') return writeHostAdd(ctx, body);
       if (pathname === '/api/hosts/remove') return writeHostRemove(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);
+      if (pathname === '/api/hosts/exclude') return writeHostExclude(ctx, body);
+      if (pathname === '/api/hosts/include') return writeHostInclude(ctx, body);
       return { code: 404, payload: { error: 'not found' } };
     };
     ctx.queue(run)

package/skills/yotta-skills/lib/install-pipeline.js

@@ -8,6 +8,7 @@ const lifecycleLib = require('./install-lifecycle');
 const healthLib = require('./install-health');
 const snapshotLib = require('./install-snapshot');
 const hookAdapterLib = require('./hook-adapter');
+const scanLib = require('./skills-scan');
 
 function nowTag() {
   return new Date().toISOString().replace(/[:.]/g, '-');
@@ -60,6 +61,15 @@ function restoreBackup(target, backup, hadTarget) {
   return false;
 }
 
+/** 0.29.1 U1「只升不降」跳过原因文案（equal / local-ahead / unknown）。 */
+function versionSkipNote(relation, installed, target) {
+  if (relation === 'equal') return '已是最新';
+  if (relation === 'local-ahead') {
+    return '本地领先 v' + installed + ' > 目标 v' + target + '，保留不降级（--force 可强制）';
+  }
+  return '无法比较版本（本地 v' + installed + ' / 目标 v' + target + '），保留（--force 可强制）';
+}
+
 function createInstaller(deps) {
   const homeDir = deps.homeDir || os.homedir();
   const runPhase = deps.runPhase || lifecycleLib.runPhase;
@@ -83,8 +93,18 @@ function createInstaller(deps) {
   return function installOne(skill, dest, opts) {
     const target = path.join(dest, skill.slug);
     const existingVersion = deps.readInstalledVersion(target);
-    if (!opts.force && existingVersion === skill.version) {
-      return { skill, status: 'skip', version: existingVersion, note: '已是最新', exitCode: 0 };
+    // 0.29.1 U1「只升不降」：pin 模式目标即最终版本，入口即可判定；
+    // range / latest 模式（目标非最终版本）在 npm pack 解析出精确版本后复判（见下方）。
+    const relation = scanLib.versionRelation(existingVersion, skill.version);
+    if (!opts.force && opts.pin !== false &&
+        (relation === 'equal' || relation === 'local-ahead' || relation === 'unknown')) {
+      return {
+        skill,
+        status: 'skip',
+        version: existingVersion,
+        note: versionSkipNote(relation, existingVersion, skill.version),
+        exitCode: 0,
+      };
     }
     if (opts.dryRun) {
       // 0.29.0 D1：只读预览 —— 不发网络请求、不写任何文件（含台账）。
@@ -124,6 +144,23 @@ function createInstaller(deps) {
         return { skill, status: 'fail', version: null, note: packed.error, exitCode: 1 };
       }
 
+      // 0.29.1 U1：解析出精确版本后、任何解压 / 快照 / 写入之前复判（latest / range 路径）。
+      const resolvedVersion = packed.resolved || (skill.version === 'latest' ? null : skill.version);
+      if (!opts.force && existingVersion) {
+        const resolvedRelation = resolvedVersion
+          ? scanLib.versionRelation(existingVersion, resolvedVersion)
+          : 'unknown';
+        if (resolvedRelation === 'equal' || resolvedRelation === 'local-ahead' || resolvedRelation === 'unknown') {
+          return {
+            skill,
+            status: 'skip',
+            version: existingVersion,
+            note: versionSkipNote(resolvedRelation, existingVersion, resolvedVersion || skill.version),
+            exitCode: 0,
+          };
+        }
+      }
+
       const extractDir = path.join(tmp, 'extract');
       fs.mkdirSync(extractDir, { recursive: true });
       extracted = deps.extractTarball(packed.tarball, extractDir);