@yottameta/yotta-skills-plugin 0.28.3 → 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

@@ -15,6 +15,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const agentDirs = require('./agent-dirs');
+const hostsRegistry = require('./hosts-registry');
 
 const SKILL_FILE = 'SKILL.md';
 const SKIP_DIRS = new Set([
@@ -81,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;
   }
@@ -103,6 +105,15 @@ function addRoot(list, seen, dir, meta) {
     if (meta && meta.label && existing.label === '自动发现目录') existing.label = meta.label;
     if (meta && meta.verified) existing.verified = true;
     if (meta && meta.bridgeOnly) existing.bridgeOnly = true;
+    // 用户注册优先：覆盖分类与手动标记（0.29.0 F2/F3）。
+    if (meta && meta.registry) {
+      existing.registry = true;
+      existing.verified = true;
+      existing.detection = 'user-registry';
+      if (meta.label) existing.label = meta.label;
+      if (meta.agentId) existing.agentId = meta.agentId;
+      if (meta.manualState) existing.manualState = meta.manualState;
+    }
     return;
   }
   const record = {
@@ -115,6 +126,8 @@ function addRoot(list, seen, dir, meta) {
     bridgeOnly: Boolean(meta && meta.bridgeOnly),
     detection: (meta && meta.detection) || 'mapping',
     exists: isDirectory(resolved),
+    registry: Boolean(meta && meta.registry),
+    manualState: (meta && meta.manualState) || null,
   };
   record.skillCount = record.exists ? countSkills(resolved) : 0;
   record.status = record.exists ? 'skills-dir' : 'missing';
@@ -180,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.
@@ -223,23 +236,87 @@ function installedMarkers(options) {
     env['ProgramFiles(x86)'],
   ];
   for (const root of roots) collectMarkerNames(root, 2, names, 800);
-  return [...names].filter((name) => AGENT_HINT.test(name) && !INSTALLED_NOISE.test(name));
+  // 标记过滤：已收录宿主的 label 双向匹配 + 启发式关键词；排除卸载器 / 运行时噪音。
+  return [...names].filter((name) =>
+    (knownLabelMatches(name) || AGENT_HINT.test(name)) && !INSTALLED_NOISE.test(name));
+}
+
+function normalizeLabel(value) {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
 }
 
+/** 标记名与已收录宿主 label 的双向词边界包含（"Trae" ↔ "Trae Code CLI"）。 */
 function knownLabelMatches(name) {
-  const normalized = String(name || '').toLowerCase();
+  const normalized = normalizeLabel(name);
+  if (!normalized) return false;
   for (const info of Object.values(agentDirs.AGENT_DIRS)) {
-    if (normalized.includes(String(info.label).toLowerCase())) return true;
+    const label = normalizeLabel(info.label);
+    if (!label) continue;
+    if (normalized === label) return true;
+    if (normalized.startsWith(label + ' ') || normalized.endsWith(' ' + label) || normalized.includes(' ' + label + ' ')) return true;
+    if (label.startsWith(normalized + ' ') || label.endsWith(' ' + normalized) || label.includes(' ' + normalized + ' ')) return true;
   }
   return false;
 }
 
+/**
+ * 应用标记与宿主匹配：label / agentId 与标记名按词边界双向包含。
+ * 例："Claude" 匹配 "Claude Code"；"Trae" 匹配 "Trae Code CLI"；
+ * 避免 "Pi" 误配 "Pilot" 这类裸子串。
+ */
+function markerMatchesHost(markerName, host) {
+  const marker = normalizeLabel(markerName);
+  if (!marker) return false;
+  const candidates = [host && host.label, host && host.agentId].filter(Boolean).map(normalizeLabel);
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    if (marker === candidate) return true;
+    if (marker.startsWith(candidate + ' ') || marker.endsWith(' ' + candidate) || marker.includes(' ' + candidate + ' ')) return true;
+    if (candidate.startsWith(marker + ' ') || candidate.endsWith(' ' + marker) || candidate.includes(' ' + marker + ' ')) return true;
+  }
+  return false;
+}
+
+/** F3 状态判定：目录 × 实体证据（应用标记 / 用户注册 / 手动标记）。 */
+function judgeHostState(host) {
+  if (host.manualState) return host.manualState; // 手动覆盖（available / orphan / ignored）
+  const entity = Boolean(host.markerEvidence || (host.evidence && host.evidence.registry));
+  if (host.exists && entity) return 'available';
+  if (host.exists) return 'orphan';
+  if (entity) return 'marker-only';
+  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.
  *
  * Returns:
  *   hosts    - all candidate skill roots (existing and missing known mappings)
- *   installed - installed app markers, including hosts without a skills dir
+ *   installed - entity evidence (app markers + user registry), including hosts
+ *               without a skills dir; plain directory existence is NOT an
+ *               installed marker (0.29.0 F3)
  *   errors   - non-fatal discovery errors
  */
 function discoverHosts(options) {
@@ -247,17 +324,74 @@ 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）。
+  for (const item of registry.hosts || []) {
+    if (skipDir(item.dir, item.agentId)) continue;
+    addRoot(roots, seen, item.dir, {
+      detection: 'user-registry',
+      label: item.label || '自定义宿主',
+      agentId: item.agentId || null,
+      verified: true,
+      known: false,
+      registry: true,
+      manualState: item.manualState || null,
+    });
+  }
   for (const root of commonRoots(options)) {
     for (const found of scanForSkillDirs(root.dir, {
       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),
@@ -265,6 +399,22 @@ function discoverHosts(options) {
     }
   }
 
+  // F3：目录证据与实体证据分开记录，判定生命周期状态。
+  const markers = installedMarkers(options);
+  for (const host of roots) {
+    const markerEvidence = markers.some((name) => markerMatchesHost(name, host));
+    host.markerEvidence = markerEvidence;
+    host.dirEvidence = host.exists;
+    host.evidence = {
+      dir: host.exists,
+      marker: markerEvidence,
+      registry: Boolean(host.registry),
+      manual: Boolean(host.manualState),
+    };
+    host.stateSource = host.manualState ? 'manual' : 'auto';
+    host.state = judgeHostState(host);
+  }
+
   const installed = [];
   const installedSeen = new Set();
   const addInstalled = (name, source) => {
@@ -275,20 +425,44 @@ function discoverHosts(options) {
     installedSeen.add(key);
     installed.push({ label, source, hasSkillsDir: false });
   };
-  for (const name of installedMarkers(options)) {
+  // 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;
-    addInstalled(host.label, host.known ? '已知宿主' : '自动发现');
-    const item = installed.find((entry) => entry.label.toLowerCase() === String(host.label).toLowerCase());
-    if (item) {
-      item.hasSkillsDir = true;
-      item.skillDir = host.dir;
-      item.skillCount = host.skillCount;
-      item.agentId = host.agentId;
+    if (!host.markerEvidence && host.detection !== 'user-registry') continue;
+    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(),
@@ -298,9 +472,25 @@ 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,
   scanForSkillDirs,
   countSkills,
+  markerMatchesHost,
+  judgeHostState,
+  unpairedMarkers,
 };

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

@@ -44,6 +44,11 @@ const CLI_GLOBAL_OPTIONS = [
   { 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: '默认只链已核实宿主；桥接目录永不链接' },
+  { flag: '--state', arg: '<state>', what: 'hub hosts 状态过滤（available / orphan / missing / marker-only / ignored）；hub hosts mark 时为手动状态', when: '只看某类宿主、或手动标记宿主状态时', caution: '' },
+  { 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: '原目录删除即断链；默认复制保真更安全' },
@@ -74,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'],
       },
@@ -85,6 +90,20 @@ const CLI_HELP_MODEL = [
         when: '执行前先确认影响面时',
         options: ['--dry-run'],
       },
+      {
+        name: 'install-self',
+        usage: 'install-self [--dir <path>] [--dry-run] [--force] [--json]',
+        what: '元阁独立安装：把管理引擎装到独立位置（默认 ~/.yottaskills/yotta-skills），与 Hub / 宿主分离',
+        when: '想把元阁装成独立 CLI（不依赖任何智能体）时',
+        options: ['--dir', '--dry-run', '--force', '--json'],
+      },
+      {
+        name: 'where',
+        usage: 'where [--json]',
+        what: '查看元阁位置：运行中 CLI / 独立安装目录（标记当前运行项）/ Hub 真源',
+        when: '确认元阁装在哪、是否独立安装时',
+        options: ['--json', '--hub'],
+      },
     ],
   },
   {
@@ -156,9 +175,16 @@ const CLI_HELP_MODEL = [
         when: '多智能体共享技能、统一管理技能目录时',
         options: ['--hub', '--all', '--include-discovered', '--dry-run', '--json'],
         subcommands: [
-          { name: 'hosts', usage: 'hub hosts [--json]', what: '发现本机已装智能体与技能目录（已核实 / 自动发现 / 桥接）', when: '先看这台机器有哪些宿主目录时', options: ['--json'] },
+          { 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 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'] },
@@ -240,6 +266,8 @@ const CLI_HELP_QUICK = [
       { cmd: 'update', example: 'yotta-skills update --check' },
       { cmd: 'update', example: 'yotta-skills update --auto' },
       { cmd: '--dry-run', example: 'yotta-skills install --dry-run --agent codex' },
+      { cmd: 'install-self', example: 'yotta-skills install-self' },
+      { cmd: 'where', example: 'yotta-skills where' },
     ],
   },
   {
@@ -265,6 +293,15 @@ const CLI_HELP_QUICK = [
     items: [
       { cmd: 'hub', example: 'yotta-skills hub' },
       { 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 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' },
       { cmd: 'hub update', example: 'yotta-skills hub update' },
       { cmd: 'hub adopt', example: 'yotta-skills hub adopt --scan' },

package/skills/yotta-skills/lib/host-purge.js

@@ -0,0 +1,167 @@
+'use strict';
+/**
+ * 残留目录清理核心（0.29.0 F3）：CLI 与面板共用。
+ *
+ * 只处理 state=orphan 的宿主目录 —— 全量 unlink（只删指向 Hub 的链接，含死链）
+ * → 目录移入回收站（保留 7 天，跨卷走复制 + 校验 + 删源）→ 清注册 / 链接台账
+ * → 写审计。非 Hub 链接 / 非链接内容保留并报告。
+ *
+ * fail-closed：Hub 真源 / 子目录、锁与数据桥接目录、非残留状态（可用 / 仅标记 /
+ * 未创建 / 已忽略）一律拒绝；需要人工确认时先 hub hosts mark --state orphan。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hubLib = require('./hub');
+const agentDirsLib = require('./agent-dirs');
+const agentDiscoveryLib = require('./agent-discovery');
+const hostsRegistryLib = require('./hosts-registry');
+
+function purgeStamp(now) {
+  const d = now instanceof Date ? now : new Date();
+  const pad = (value) => String(value).padStart(2, '0');
+  return d.getFullYear() + pad(d.getMonth() + 1) + pad(d.getDate()) + '-' +
+    pad(d.getHours()) + pad(d.getMinutes()) + pad(d.getSeconds()) + '-' + process.pid;
+}
+
+function safeOrphanName(value) {
+  const cleaned = String(value || '')
+    .replace(/[\\/:*?"<>|\s]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return cleaned || 'host';
+}
+
+function pathKey(dir) {
+  let real = path.resolve(dir);
+  try {
+    real = fs.realpathSync.native(real);
+  } catch (_) {
+    try { real = fs.realpathSync(real); } catch (_) { /* keep resolved */ }
+  }
+  return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/** 只读预检 + 清理计划（不写任何文件）。 */
+function planHostPurge(options) {
+  const opts = options || {};
+  const hubDir = path.resolve(opts.hubDir);
+  const target = path.resolve(opts.dir);
+  const homeDir = opts.homeDir || os.homedir();
+  const env = opts.env || process.env;
+
+  if (!fs.existsSync(target)) {
+    return { ok: false, code: 400, error: '目录不存在: ' + target };
+  }
+  if (isInside(hubDir, target)) {
+    return { ok: false, code: 400, error: '该目录不允许残留清理（Hub 真源 / 子目录）: ' + target };
+  }
+  if (agentDirsLib.isBridgeOnlyDir(target, { homeDir, env })) {
+    return { ok: false, code: 400, error: '锁 / 数据桥接目录不参与残留清理: ' + target };
+  }
+
+  const discovery = opts.discovery || agentDiscoveryLib.discoverHosts({ homeDir, env });
+  const host = discovery.hosts.find((item) => pathKey(item.dir) === pathKey(target));
+  const state = host ? host.state : null;
+  if (state !== 'orphan') {
+    return {
+      ok: false,
+      code: 400,
+      state,
+      error: '目标不是「残留（实体未确认）」状态' + (state ? '（当前: ' + state + '）' : '（不在发现列表）'),
+    };
+  }
+
+  const linkSlugs = [];
+  let keptLinks = 0;
+  let keptEntries = 0;
+  let entries = [];
+  try { entries = fs.readdirSync(target, { withFileTypes: true }); } catch (_) { entries = []; }
+  for (const entry of entries) {
+    const full = path.join(target, entry.name);
+    const cls = hubLib.classifyTarget(full, hubDir);
+    if (cls.kind === 'link') {
+      if (cls.inHub) linkSlugs.push(entry.name);
+      else keptLinks++;
+    } else if (cls.kind !== 'missing') {
+      keptEntries++;
+    }
+  }
+  const trashRoot = hubLib.resolveTrashRoot(hubDir, opts);
+  const label = host && host.label ? host.label : path.basename(target);
+  const trashPath = path.join(trashRoot, purgeStamp(opts.now), 'orphan-' + safeOrphanName(label));
+  return {
+    ok: true,
+    hubDir,
+    target,
+    state,
+    label,
+    linkSlugs,
+    keptLinks,
+    keptEntries,
+    trashRoot,
+    trashPath,
+  };
+}
+
+/** 执行清理：unlink → trash → 清注册 / 台账 → 审计。 */
+function applyHostPurge(options) {
+  const opts = options || {};
+  const plan = planHostPurge(opts);
+  if (!plan.ok) return plan;
+
+  const unlinkResult = hubLib.unlinkSkills({
+    hubDir: plan.hubDir,
+    targetDir: plan.target,
+    slugs: plan.linkSlugs,
+    dryRun: false,
+  });
+  const unlinkedCount = (unlinkResult.results || [])
+    .filter((item) => item.status === 'unlinked').length;
+
+  fs.mkdirSync(path.dirname(plan.trashPath), { recursive: true });
+  hubLib.moveEntryAcrossDevices(plan.target, plan.trashPath);
+  try {
+    hubLib.pruneTrash(plan.trashRoot, { days: hubLib.TRASH_RETENTION_DAYS });
+  } catch (_) { /* best-effort */ }
+
+  const registryOpts = { homeDir: opts.homeDir, env: opts.env, hub: opts.hub };
+  const registry = hostsRegistryLib.readHostsRegistry(registryOpts);
+  if (registry.hosts.some((item) => pathKey(item.dir) === pathKey(plan.target))) {
+    hostsRegistryLib.removeHost(registryOpts, { dir: plan.target });
+  }
+
+  try {
+    hubLib.appendAudit(plan.hubDir, {
+      event: 'hosts.purge',
+      dir: plan.target,
+      label: plan.label,
+      state: plan.state,
+      trashedTo: plan.trashPath,
+      unlinked: unlinkedCount,
+      keptLinks: plan.keptLinks,
+      keptEntries: plan.keptEntries,
+    });
+  } catch (_) { /* 审计失败不阻断 */ }
+
+  return {
+    ok: true,
+    dir: plan.target,
+    state: plan.state,
+    unlinkCount: unlinkedCount,
+    keptLinks: plan.keptLinks,
+    keptEntries: plan.keptEntries,
+    trashedTo: plan.trashPath,
+  };
+}
+
+module.exports = {
+  planHostPurge,
+  applyHostPurge,
+  purgeStamp,
+  safeOrphanName,
+};