@yottameta/yotta-skills-plugin 0.28.3 → 0.29.1

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

@@ -0,0 +1,339 @@
+'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),
+        // 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: [], excluded: [], overrides: [] };
+}
+
+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,
+    excluded: registry.excluded || [],
+    overrides: registry.overrides || [],
+  }, 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));
+}
+
+/** 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);
+  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;
+  }
+  if (isYottaCodeTarget(target, opts)) {
+    return 'YottaCode 自带三层技能管理（skill-inventory / skill / user-skills），不纳入元阁接管：' + 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: '缺少目录' };
+  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) {
+    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 };
+}
+
+/** 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,
+  LABEL_MAX_LENGTH,
+  resolveSkillsRoot,
+  hostsRegistryPath,
+  readHostsRegistry,
+  writeHostsRegistry,
+  validateHostDir,
+  validateLabel,
+  addHost,
+  removeHost,
+  markHost,
+  excludedEntryFor,
+  excludeHost,
+  includeHost,
+  setHostOverride,
+  clearHostOverride,
+};

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

@@ -33,6 +33,8 @@ const routeDynamicLib = require('./route-dynamic');
 const providerLib = require('./provider');
 const usageLib = require('./usage-journal');
 const cliHelpLib = require('./cli-help');
+const hostsRegistryLib = require('./hosts-registry');
+const hostPurgeLib = require('./host-purge');
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8789;
@@ -42,7 +44,7 @@ const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 500;
 const TOKEN_HEADER = 'x-yotta-view-token';
 const TOKEN_PLACEHOLDER = '__YOTTA_VIEW_TOKEN__';
-const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove' };
+const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove', purge: 'purge' };
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 function nowIso() {
@@ -202,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: {
@@ -217,8 +224,19 @@ 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：宿主生命周期状态细分（面板分组 / 筛选）。
+      states: {
+        available: hosts.filter((host) => host.state === 'available').length,
+        orphan: hosts.filter((host) => host.state === 'orphan').length,
+        missing: hosts.filter((host) => host.state === 'missing').length,
+        markerOnly: hosts.filter((host) => host.state === 'marker-only').length,
+        ignored: hosts.filter((host) => host.state === 'ignored').length,
+      },
     },
   };
 }
@@ -525,6 +543,138 @@ function writeRollback(ctx, body) {
   return { code: result.error ? (result.code || 400) : 200, payload: result };
 }
 
+// ── 宿主注册与残留清理（0.29.0 F2/F3） ─────────────────────────────────────
+function auditViewHostEvent(ctx, entry) {
+  try {
+    if (fs.existsSync(ctx.hubDir)) hubLib.appendAudit(ctx.hubDir, entry);
+  } catch (_) { /* 审计失败不阻断主流程 */ }
+}
+
+function writeHostAdd(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const label = String(body.label || '').trim();
+  const result = hostsRegistryLib.addHost(
+    { homeDir: ctx.homeDir, env: ctx.env },
+    { dir, label: label || undefined },
+  );
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.add',
+    dir: result.entry.dir,
+    label: result.entry.label,
+    agentId: result.entry.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.add', entry: result.entry } };
+}
+
+function writeHostRemove(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostsRegistryLib.removeHost({ homeDir: ctx.homeDir, env: ctx.env }, { dir });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.remove',
+    dir: result.removed.dir,
+    label: result.removed.label,
+    agentId: result.removed.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.remove', removed: result.removed } };
+}
+
+function writeHostPurge(ctx, body) {
+  if (String(body.confirm || '') !== CONFIRM.purge) {
+    return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
+  }
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostPurgeLib.applyHostPurge({
+    hubDir: ctx.hubDir,
+    dir,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  });
+  if (!result.ok) return { code: result.code || 400, payload: { error: result.error, state: result.state || null } };
+  return {
+    code: 200,
+    payload: {
+      action: 'hosts.purge',
+      dir: result.dir,
+      state: result.state,
+      unlinkCount: result.unlinkCount,
+      keptLinks: result.keptLinks,
+      keptEntries: result.keptEntries,
+      trashedTo: result.trashedTo,
+    },
+  };
+}
+
+// ── 宿主标记 / 目录覆盖 / 不接管（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, {
@@ -632,6 +782,25 @@ function handleGet(ctx, pathname, url, res) {
     return json(res, 200, removePlanPayload(ctx, slug));
   }
   if (pathname === '/api/hosts') return json(res, 200, hostsPayload(ctx));
+  if (pathname === '/api/hosts/purge-plan') {
+    const dir = url.searchParams.get('dir') || '';
+    if (!dir) return json(res, 400, { error: '缺少 dir 参数（目标宿主目录）。' });
+    const plan = hostPurgeLib.planHostPurge({
+      hubDir: ctx.hubDir,
+      dir,
+      homeDir: ctx.homeDir,
+      env: ctx.env,
+    });
+    if (!plan.ok) return json(res, plan.code || 400, { error: plan.error, state: plan.state || null });
+    return json(res, 200, {
+      dir: plan.target,
+      state: plan.state,
+      unlinkCount: plan.linkSlugs.length,
+      keptLinks: plan.keptLinks,
+      keptEntries: plan.keptEntries,
+      trashedTo: plan.trashPath,
+    });
+  }
   if (pathname === '/api/adopt/scan') return json(res, 200, adoptScanPayload(ctx));
   if (pathname === '/api/links') return json(res, 200, linksPayload(ctx));
   if (pathname === '/api/links/plan') {
@@ -664,6 +833,13 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/links/remove') return writeUnlink(ctx, body);
       if (pathname === '/api/rollback/apply') return writeRollback(ctx, body);
       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/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/hub.js

@@ -1461,6 +1461,22 @@ function doctor(options) {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
 
+  // F3（0.29.0）：宿主状态细分只读检查 —— 残留 / 仅标记给 info 提示，不 fail。
+  if (opts.discovery) {
+    for (const host of opts.discovery.hosts || []) {
+      if (!host || !host.dir) continue;
+      if (host.state === 'orphan') {
+        add('host_state:' + pathKey(host.dir), true, 'info',
+          '宿主目录疑似残留（实体未确认）: ' + host.label + ' — ' + host.dir,
+          '确认宿主已卸载后可清理：yotta-skills hub hosts remove "' + host.dir + '" --purge（默认预览，--yes 执行）');
+      } else if (host.state === 'marker-only') {
+        add('host_state:' + pathKey(host.dir), true, 'info',
+          '已装实体但技能目录未创建: ' + host.label,
+          '需要分发时运行 yotta-skills hub link --agent ' + (host.agentId || '<id>'));
+      }
+    }
+  }
+
   const errors = checks.filter((check) => !check.ok && check.severity === 'error');
   const warnings = checks.filter((check) => !check.ok && check.severity === 'warning');
   return {

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,37 @@ 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：只读预览 —— 不发网络请求、不写任何文件（含台账）。
+      const latestUnresolved = skill.version === 'latest';
+      const planned = existingVersion ? 'update' : 'install';
+      return {
+        skill,
+        status: 'planned',
+        planned,
+        version: latestUnresolved ? 'latest' : skill.version,
+        installedVersion: existingVersion,
+        latestUnresolved,
+        note: latestUnresolved
+          ? 'latest（预览不解析）'
+          : planned === 'update'
+            ? '将更新 v' + existingVersion + ' -> v' + skill.version
+            : '将安装 v' + skill.version,
+        exitCode: 0,
+      };
     }
 
     let tmp = null;
@@ -105,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);