@yottameta/yotta-skills-plugin 0.28.3 → 0.29.0

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([
@@ -103,6 +104,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 +125,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';
@@ -223,23 +235,65 @@ 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';
+}
+
 /**
  * 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) {
@@ -253,6 +307,23 @@ function discoverHosts(options) {
   for (const root of agentDirs.envRoots(options)) {
     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 || []) {
+    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,
@@ -265,6 +336,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,13 +362,16 @@ function discoverHosts(options) {
     installedSeen.add(key);
     installed.push({ label, source, hasSkillsDir: false });
   };
-  for (const name of installedMarkers(options)) {
+  for (const name of markers) {
     if (knownLabelMatches(name) || AGENT_HINT.test(name)) addInstalled(name, '应用标记');
   }
+  for (const host of roots) {
+    if (host.detection === 'user-registry') addInstalled(host.label, '用户注册');
+  }
   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 (!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;
@@ -303,4 +393,6 @@ module.exports = {
   discoverHosts,
   scanForSkillDirs,
   countSkills,
+  markerMatchesHost,
+  judgeHostState,
 };

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

@@ -44,6 +44,10 @@ 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: '--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: '原目录删除即断链；默认复制保真更安全' },
@@ -85,6 +89,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,7 +174,11 @@ 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: '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'] },
@@ -240,6 +262,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 +289,12 @@ 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 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,
+};

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

@@ -0,0 +1,197 @@
+'use strict';
+/**
+ * 用户级自定义宿主注册表（0.29.0 F2）—— <root>/hosts.json。
+ *
+ * root = YOTTA_SKILLS_HOME 或 ~/.yottaskills（与 self.json 同根，独立于 Hub 目录）。
+ * schema v1：{ version, hosts:[{ dir, label, agentId, scope:"verified", note,
+ * addedAt, source:"manual", manualState? }] }
+ *
+ * 注册只影响发现 / 分发 / 收编范围：不创建目录、不改宿主配置；
+ * 移除注册绝不删除目录。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hubLib = require('./hub');
+const agentDirsLib = require('./agent-dirs');
+
+const HOSTS_REGISTRY_VERSION = 1;
+const LABEL_MAX_LENGTH = 48;
+const MANUAL_STATES = ['available', 'orphan', 'ignored'];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function resolveSkillsRoot(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const explicit = options.skillsRoot || env.YOTTA_SKILLS_HOME;
+  if (explicit) return path.resolve(explicit);
+  return path.join(options.homeDir || os.homedir(), '.yottaskills');
+}
+
+function hostsRegistryPath(opts) {
+  return path.join(resolveSkillsRoot(opts), 'hosts.json');
+}
+
+function readHostsRegistry(opts) {
+  try {
+    const value = JSON.parse(fs.readFileSync(hostsRegistryPath(opts), 'utf8'));
+    if (value && typeof value === 'object' && Array.isArray(value.hosts)) {
+      return {
+        version: HOSTS_REGISTRY_VERSION,
+        hosts: value.hosts.filter((item) => item && typeof item.dir === 'string' && item.dir),
+      };
+    }
+  } catch (_) { /* missing or corrupt registry falls back to empty */ }
+  return { version: HOSTS_REGISTRY_VERSION, hosts: [] };
+}
+
+function writeHostsRegistry(opts, registry) {
+  const file = hostsRegistryPath(opts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify({
+    version: HOSTS_REGISTRY_VERSION,
+    hosts: registry.hosts,
+  }, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function safeRealpath(target) {
+  try {
+    return fs.realpathSync.native(target);
+  } catch (_) {
+    try {
+      return fs.realpathSync(target);
+    } catch (_) {
+      return path.resolve(target);
+    }
+  }
+}
+
+function samePath(left, right) {
+  const a = safeRealpath(left);
+  const b = safeRealpath(right);
+  if (process.platform === 'win32') return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/** fail-closed 校验：返回中文错误或 null。 */
+function validateHostDir(dir, opts) {
+  const target = path.resolve(dir);
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch (_) {
+    return '目录不存在：' + target;
+  }
+  if (!stat.isDirectory()) return '不是目录：' + target;
+  const hubDir = hubLib.resolveHubDir(opts);
+  if (samePath(target, hubDir) || isInside(hubDir, target)) {
+    return '指向 Hub 自身或子目录，不允许注册：' + target;
+  }
+  if (agentDirsLib.isBridgeOnlyDir(target, opts)) {
+    return '锁 / 数据桥接目录不允许注册：' + target;
+  }
+  return null;
+}
+
+function validateLabel(label) {
+  const value = String(label || '').trim();
+  if (!value) return 'label 不能为空';
+  if (/[\u0000-\u001f\u007f]/.test(value)) return 'label 含控制字符';
+  if (value.length > LABEL_MAX_LENGTH) return 'label 过长（最多 ' + LABEL_MAX_LENGTH + ' 字符）';
+  return null;
+}
+
+/** 注册自定义宿主目录（fail-closed；不创建目录、不改宿主配置）。 */
+function addHost(opts, input) {
+  const options = opts || {};
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  if (!dir) return { ok: false, error: '缺少目录：hub hosts add <dir>' };
+  const guard = validateHostDir(dir, options);
+  if (guard) return { ok: false, error: guard };
+  const label = String((input && input.label) || path.basename(dir)).trim();
+  const labelError = validateLabel(label);
+  if (labelError) return { ok: false, error: labelError };
+  const agentId = input && input.agentId ? String(input.agentId).trim().toLowerCase() : null;
+
+  const registry = readHostsRegistry(options);
+  const existing = registry.hosts.find((item) => samePath(item.dir, dir));
+  if (existing) {
+    return { ok: false, error: '该目录已注册：' + dir, existing };
+  }
+  const entry = {
+    dir,
+    label,
+    agentId,
+    scope: 'verified',
+    note: (input && input.note) || null,
+    addedAt: nowIso(),
+    source: 'manual',
+  };
+  registry.hosts.push(entry);
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+/** 移除注册（只移除登记，绝不删除目录）。 */
+function removeHost(opts, target) {
+  const options = opts || {};
+  const registry = readHostsRegistry(options);
+  const index = registry.hosts.findIndex((item) =>
+    (target && target.dir && samePath(item.dir, target.dir)) ||
+    (target && target.id && String(item.agentId || '').toLowerCase() === String(target.id).toLowerCase()));
+  if (index < 0) return { ok: false, error: '未找到注册项' };
+  const removed = registry.hosts.splice(index, 1)[0];
+  writeHostsRegistry(options, registry);
+  return { ok: true, removed, registry };
+}
+
+/** 手动标记宿主状态（可用 / 残留 / 忽略）；条目不存在时先注册。 */
+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）' };
+  }
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  if (!dir) return { ok: false, error: '缺少目录' };
+  const registry = readHostsRegistry(options);
+  let entry = registry.hosts.find((item) => samePath(item.dir, dir));
+  if (!entry) {
+    const added = addHost(options, { dir, label: input.label });
+    if (!added.ok) return added;
+    const refreshed = readHostsRegistry(options);
+    entry = refreshed.hosts.find((item) => samePath(item.dir, dir));
+    entry.manualState = state;
+    writeHostsRegistry(options, refreshed);
+    return { ok: true, entry, registry: refreshed };
+  }
+  entry.manualState = state;
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+module.exports = {
+  HOSTS_REGISTRY_VERSION,
+  MANUAL_STATES,
+  LABEL_MAX_LENGTH,
+  resolveSkillsRoot,
+  hostsRegistryPath,
+  readHostsRegistry,
+  writeHostsRegistry,
+  validateHostDir,
+  validateLabel,
+  addHost,
+  removeHost,
+  markHost,
+};