@yottameta/yotta-skills-plugin 0.29.1 → 0.29.2

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

@@ -40,7 +40,8 @@ const CLI_GLOBAL_OPTIONS = [
   { flag: '--yes', arg: '', what: 'usage reset 的确认开关', when: '确认清空本地使用记录时', caution: '会清空记录文件' },
   { flag: '--explain', arg: '', what: 'decide-memory 文本报告追加信号明细', when: '想看裁决依据时', caution: '' },
   { flag: '--promote', arg: '', what: 'decide-memory 只写本地建议文件（不写元忆）', when: '想留下裁决建议文件时', caution: '不会写元忆、不会删除任何内容' },
-  { flag: '--hub', arg: '<path>', what: 'Hub 目录（默认 ~/.yottaskills/hub）', when: '使用自定义 Hub 位置时', caution: 'YOTTA_SKILLS_HUB 环境变量同样可覆盖' },
+  { flag: '--hub', arg: '<path>', what: 'Hub 目录（默认 ~/.yottaskills/hub；持久配置见 hub config）', when: '使用自定义 Hub 位置时', caution: '覆盖顺序：--hub > YOTTA_SKILLS_HUB > config.json > 默认' },
+  { flag: '--move', arg: '', what: 'hub config set 迁移：复制校验旧 Hub → 重链宿主 → 旧 Hub 入回收站（7 天）', when: '换 Hub 位置并带上已有技能时', caution: 'fail-closed：校验失败不切配置；重链失败保留旧 Hub' },
   { 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: '默认只链已核实宿主；桥接目录永不链接' },
@@ -183,6 +184,9 @@ const CLI_HELP_MODEL = [
           { 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: 'config get', usage: 'hub config get [--json]', what: '查看生效 Hub 位置与来源（--hub / YOTTA_SKILLS_HUB / config.json / 默认）', when: '确认当前 Hub 与配置覆盖时', options: ['--json'] },
+          { name: 'config set', usage: 'hub config set --hub <path> [--move]', what: '持久化 Hub 位置；--move 迁移旧 Hub（复制校验 → 重链 → 回收站 7 天）', when: '换 Hub 存储位置时', options: ['--hub', '--move', '--json'] },
+          { name: 'config clear', usage: 'hub config clear [--json]', what: '清除配置覆盖，恢复 flag > env > 默认', when: '撤销持久 Hub 位置时', options: ['--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'] },
@@ -300,6 +304,9 @@ const CLI_HELP_QUICK = [
       { 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 config get', example: 'yotta-skills hub config get', note: '查看生效位置与来源' },
+      { cmd: 'hub config set', example: 'yotta-skills hub config set --hub <Hub目录>', note: '持久化 Hub 位置；迁移旧 Hub 加 --move' },
+      { cmd: 'hub config clear', example: 'yotta-skills hub config clear', note: '清除持久覆盖，恢复默认解析' },
       { 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/hub-adopt.js

@@ -269,7 +269,7 @@ function refreshFrom(options) {
       updatedAt: new Date().toISOString(),
     });
     hubLib.appendAudit(hubDir, { event: 'refresh', slug, source, verdict: scan.verdict, backup });
-    return { ok: true, slug, source, backup, verdict: scan.verdict };
+    return { ok: true, slug, source, backup, verdict: scan.verdict, scanPolicy: scan.policy || null };
   } catch (error) {
     if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
     return { ok: false, slug, error: error.message };

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

@@ -0,0 +1,183 @@
+'use strict';
+/**
+ * Hub 迁移（0.29.2 U4）—— `hub config set --hub <new> --move` 的两段式实现。
+ *
+ * 1) stageHubCopy({ from, to })：复制旧 Hub → 逐技能 treeHash 校验；失败
+ *    fail-closed（清理暂存副本、旧 Hub 不动、配置不切换）。
+ * 2) relinkAndRetireOldHub({ from, to, targets })：`hub link` 以新 Hub 为源、
+ *    --force 重链各宿主 → 全部成功才把旧 Hub 移入回收站（7 天）；有失败则
+ *    保留旧 Hub 供重试（此时新旧内容一致，链接混合指向两个 Hub 均可用）。
+ *
+ * 配置切换（config.json 写入）由调用方在两段之间执行；写入失败时调用
+ * discardStagedCopy() 清理暂存副本。
+ */
+const fs = require('fs');
+const path = require('path');
+const hubLib = require('./hub');
+
+function nowStamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+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));
+}
+
+function listEntries(dir) {
+  try {
+    return fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+}
+
+/** 清理暂存副本（仅在 stage 阶段失败或配置写入失败时调用）。 */
+function discardStagedCopy(options) {
+  const opts = options || {};
+  const to = path.resolve(opts.to);
+  try {
+    if (opts.existed) {
+      for (const name of listEntries(to)) fs.rmSync(path.join(to, name), { recursive: true, force: true });
+    } else {
+      fs.rmSync(to, { recursive: true, force: true });
+    }
+  } catch (_) { /* 保留现场供排查 */ }
+}
+
+/** 复制 + 校验（不切配置）。返回 { ok, error?, from, to, existed, verifiedSkills }。 */
+function stageHubCopy(options) {
+  const opts = options || {};
+  const from = path.resolve(opts.from);
+  const to = path.resolve(opts.to);
+  if (samePath(from, to)) return { ok: false, error: '新旧 Hub 路径相同：' + from };
+  if (isInside(from, to) || isInside(to, from)) return { ok: false, error: '新旧 Hub 不能互相嵌套：' + from + ' / ' + to };
+  let stat = null;
+  try {
+    stat = fs.statSync(from);
+  } catch (_) { /* handled below */ }
+  if (!stat || !stat.isDirectory()) return { ok: false, error: '旧 Hub 不存在或不是目录：' + from };
+  const existed = fs.existsSync(to);
+  if (existed && listEntries(to).length > 0) {
+    return { ok: false, error: '新 Hub 目录非空（fail-closed，不合并）：' + to };
+  }
+
+  try {
+    fs.mkdirSync(to, { recursive: true });
+    fs.cpSync(from, to, { recursive: true });
+  } catch (error) {
+    discardStagedCopy({ to, existed });
+    return { ok: false, error: '复制失败：' + error.message };
+  }
+
+  const mismatches = [];
+  for (const name of listEntries(from)) {
+    if (!fs.existsSync(path.join(to, name))) mismatches.push('entry:' + name);
+  }
+  const skills = hubLib.scanHubSkills(from);
+  for (const skill of skills) {
+    let sourceStat = null;
+    try {
+      sourceStat = fs.lstatSync(skill.dir);
+    } catch (_) {
+      continue;
+    }
+    // in-place / 外部链接条目：随链接原样复制，不做内容校验。
+    if (sourceStat.isSymbolicLink() || !isInside(from, skill.dir)) continue;
+    const copied = path.join(to, path.relative(from, skill.dir));
+    let copiedStat = null;
+    try {
+      copiedStat = fs.lstatSync(copied);
+    } catch (_) { /* mismatch below */ }
+    if (!copiedStat || !copiedStat.isDirectory()) {
+      mismatches.push(skill.slug);
+      continue;
+    }
+    try {
+      if (hubLib.hashTree(skill.dir) !== hubLib.hashTree(copied)) mismatches.push(skill.slug);
+    } catch (_) {
+      mismatches.push(skill.slug);
+    }
+  }
+  if (mismatches.length > 0) {
+    discardStagedCopy({ to, existed });
+    return {
+      ok: false,
+      error: '迁移校验失败（未切换配置；已清理暂存副本）：' + mismatches.slice(0, 8).join(', ') +
+        (mismatches.length > 8 ? ' 等 ' + mismatches.length + ' 项' : ''),
+    };
+  }
+  return { ok: true, from, to, existed, verifiedSkills: skills.length };
+}
+
+/** 重链（新 Hub 为源）+ 旧 Hub 入回收站（仅当重链无失败）。 */
+function relinkAndRetireOldHub(options) {
+  const opts = options || {};
+  const from = path.resolve(opts.from);
+  const to = path.resolve(opts.to);
+  const targets = Array.isArray(opts.targets) ? opts.targets : [];
+  const relink = [];
+  let incomplete = 0;
+  for (const target of targets) {
+    if (!target || !target.dir) continue;
+    if (samePath(target.dir, from) || samePath(target.dir, to)) continue;
+    const result = hubLib.linkSkills({
+      hubDir: to,
+      targetDir: target.dir,
+      agentId: target.agentId,
+      label: target.label,
+      force: true,
+      manifest: opts.manifest,
+      homeDir: opts.homeDir,
+      env: opts.env,
+    });
+    const notLinked = result.results.filter((item) => item.status !== 'linked' && item.status !== 'missing');
+    incomplete += notLinked.length;
+    relink.push({
+      dir: target.dir,
+      label: target.label,
+      linked: result.results.filter((item) => item.status === 'linked').length,
+      incomplete: notLinked.map((item) => item.slug + ': ' + item.note),
+    });
+  }
+
+  let trashedTo = null;
+  let trashError = null;
+  if (incomplete === 0) {
+    try {
+      const trashRoot = hubLib.resolveTrashRoot(from, { env: opts.env });
+      const dest = path.join(trashRoot, 'hub-migrate-' + nowStamp(), path.basename(from));
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      hubLib.moveEntryAcrossDevices(from, dest);
+      trashedTo = dest;
+    } catch (error) {
+      trashError = error.message;
+    }
+  }
+  return { ok: incomplete === 0, from, to, relink, incomplete, trashedTo, trashError };
+}
+
+module.exports = {
+  discardStagedCopy,
+  stageHubCopy,
+  relinkAndRetireOldHub,
+};

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

@@ -13,6 +13,10 @@ const { spawnSync } = require('child_process');
 const depsLib = require('./deps');
 const gateLib = require('./verify-gate');
 const trustedVerifierLib = require('./trusted-verifier');
+const scanPolicyLib = require('./scan-policy');
+const hubLib = require('./hub');
+
+const POLICY_PATH = path.join(__dirname, '..', 'scan-policy.json');
 
 function currentCommand() {
   const args = process.argv.slice(2).map((a) => (/\s/.test(a) ? '"' + a + '"' : a));
@@ -52,6 +56,21 @@ function runScan(engine, skillDir, opts) {
   return gateLib.runVerifier(engine, skillDir, { python, spawnSync });
 }
 
+/**
+ * 复用安装管线的 scanPolicy 复核（0.29.2）：版本 + treeHash 绑定，fail-closed。
+ * 未命中例外表 / 绑定不匹配时返回原始 scan（不豁免任何发现）。
+ */
+function reviewScanWithPolicy(scan, context) {
+  const ctx = context || {};
+  const policy = scanPolicyLib.loadPolicy(ctx.policyPath || POLICY_PATH);
+  return scanPolicyLib.applyScanPolicy(scan, {
+    slug: ctx.slug,
+    version: ctx.version,
+    pkgDir: ctx.pkgDir,
+    policy,
+  });
+}
+
 /** Hub adopt scan engine: Hub itself first, then every discovered host dir. */
 function scanEngineForHub(hubDir, discovery, opts) {
   const direct = findVerifyEngine(hubDir, opts);
@@ -69,7 +88,7 @@ function scanEngineForHub(hubDir, discovery, opts) {
  * Scan one candidate directory for Hub adoption.
  * Returns { ok, verdict, counts, block } or { ok:false, error }.
  */
-function hubScanSkill(hubDir, discovery, opts, skillDir) {
+function hubScanSkill(hubDir, discovery, opts, skillDir, context) {
   const options = opts || {};
   if (options.skipScan) {
     return { ok: true, verdict: 'explicit-unverified', counts: null, block: false };
@@ -83,8 +102,22 @@ function hubScanSkill(hubDir, discovery, opts, skillDir) {
   }
   const scan = runScan(engine, skillDir, options);
   if (!scan.ok) return scan;
-  const verdict = gateLib.evaluateVerdict(scan.verdict);
-  return { ok: true, verdict: scan.verdict, counts: scan.counts, block: verdict.block };
+  const ctx = context || {};
+  const meta = hubLib.readSkillMeta(skillDir);
+  const reviewed = reviewScanWithPolicy(scan, {
+    slug: ctx.slug || (meta && (meta.slug || meta.name)) || null,
+    version: ctx.version || (meta && meta.version) || null,
+    pkgDir: skillDir,
+    policyPath: options.policyPath,
+  });
+  const verdict = gateLib.evaluateVerdict(reviewed.verdict);
+  return {
+    ok: true,
+    verdict: reviewed.verdict,
+    counts: reviewed.counts,
+    block: verdict.block,
+    policy: reviewed.policy || null,
+  };
 }
 
 module.exports = {
@@ -92,6 +125,7 @@ module.exports = {
   findVerifyEngine,
   findPython,
   runScan,
+  reviewScanWithPolicy,
   scanEngineForHub,
   hubScanSkill,
 };

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

@@ -35,6 +35,7 @@ const usageLib = require('./usage-journal');
 const cliHelpLib = require('./cli-help');
 const hostsRegistryLib = require('./hosts-registry');
 const hostPurgeLib = require('./host-purge');
+const skillsConfigLib = require('./skills-config');
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8789;
@@ -44,7 +45,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', purge: 'purge' };
+const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove', purge: 'purge', hubConfig: 'hub-config' };
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 function nowIso() {
@@ -164,9 +165,19 @@ function overviewPayload(ctx) {
     discovery: discovery(ctx),
   });
   const audit = readJsonlTail(hubAuditPath(ctx.hubDir), 8);
+  const hubNow = skillsConfigLib.resolveHub({ homeDir: ctx.homeDir, env: ctx.env });
   return {
     version: ctx.version,
     hubDir: ctx.hubDir,
+    // 0.29.2 U4：Hub 位置来源 / 配置覆盖 / 重启提示（面板「Hub 位置」区）。
+    hub: {
+      dir: ctx.hubDir,
+      source: ctx.hubSource || 'default',
+      configured: hubNow.configured,
+      configFile: hubNow.configFile,
+      effectiveNow: hubNow.dir,
+      restartRequired: !ctx.hubFlag && !sameDir(hubNow.dir, ctx.hubDir),
+    },
     standard: hubLib.STANDARD_ID,
     generatedAt: nowIso(),
     status: {
@@ -675,6 +686,46 @@ function writeHostInclude(ctx, body) {
   return { code: 200, payload: { action: 'hosts.include', removed: result.removed } };
 }
 
+/** 0.29.2 U4：面板「Hub 位置」设置 / 清除（写 config.json；重启 view 生效）。 */
+function writeHubConfig(ctx, body) {
+  if (String(body.confirm || '') !== CONFIRM.hubConfig) {
+    return { code: 400, payload: { error: '确认串不匹配（需要 "' + CONFIRM.hubConfig + '"）。' } };
+  }
+  const configOpts = { homeDir: ctx.homeDir, env: ctx.env };
+  const current = skillsConfigLib.resolveHub(configOpts);
+  if (body.clear) {
+    const result = skillsConfigLib.clearHub(configOpts);
+    if (!result.ok) return { code: 400, payload: { error: result.error } };
+    if (fs.existsSync(current.dir)) {
+      try {
+        hubLib.appendAudit(current.dir, { event: 'config.clear', removed: result.removed, via: 'view' });
+      } catch (_) { /* best-effort */ }
+    }
+    return { code: 200, payload: { action: 'config.clear', removed: result.removed, restartRequired: true } };
+  }
+  const hub = String(body.hub || '').trim();
+  const guard = skillsConfigLib.validateHubPath(hub, configOpts);
+  if (!guard.ok) return { code: 400, payload: { error: guard.error } };
+  const result = skillsConfigLib.setHub(configOpts, { hub });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  const auditDir = fs.existsSync(result.hub) ? result.hub : current.dir;
+  if (fs.existsSync(auditDir)) {
+    try {
+      hubLib.appendAudit(auditDir, { event: 'config.set', hub: result.hub, previousHub: current.dir, via: 'view' });
+    } catch (_) { /* best-effort */ }
+  }
+  return {
+    code: 200,
+    payload: {
+      action: 'config.set',
+      hub: result.hub,
+      previous: current.dir,
+      configFile: result.configFile,
+      restartRequired: true,
+    },
+  };
+}
+
 function json(res, code, value) {
   if (res.writableEnded) return;
   res.writeHead(code, {
@@ -840,6 +891,7 @@ function handlePost(ctx, pathname, req, res) {
       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);
+      if (pathname === '/api/hub/config') return writeHubConfig(ctx, body);
       return { code: 404, payload: { error: 'not found' } };
     };
     ctx.queue(run)
@@ -857,6 +909,8 @@ function createHubViewServer(options) {
   let chain = Promise.resolve();
   const ctx = {
     hubDir: path.resolve(opts.hubDir || hubLib.resolveHubDir({})),
+    hubSource: opts.hubSource || 'default',
+    hubFlag: Boolean(opts.hubFlag),
     homeDir: opts.homeDir || os.homedir(),
     env: opts.env || process.env,
     manifest: opts.manifest || [],

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

@@ -14,6 +14,7 @@ const os = require('os');
 const path = require('path');
 const scanLib = require('./skills-scan');
 const skillsCliLock = require('./skills-cli-lock');
+const skillsConfigLib = require('./skills-config');
 
 const STANDARD_ID = 'yotta-skills-hub/v1';
 const STATE_VERSION = 1;
@@ -45,11 +46,13 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+/** 解析生效 Hub（含来源）：--hub > YOTTA_SKILLS_HUB > config.json > 默认。 */
+function resolveHub(opts) {
+  return skillsConfigLib.resolveHub(opts);
+}
+
 function resolveHubDir(opts) {
-  const options = opts || {};
-  const explicit = options.hub || process.env.YOTTA_SKILLS_HUB;
-  if (explicit) return path.resolve(explicit);
-  return path.join(options.homeDir || os.homedir(), '.yottaskills', 'hub');
+  return resolveHub(opts).dir;
 }
 
 function hubPaths(hubDir) {
@@ -1498,6 +1501,7 @@ module.exports = {
   AUDIT_FILE,
   TRASH_RETENTION_DAYS,
   HUB_FAMILY_EXTRAS,
+  resolveHub,
   resolveHubDir,
   hubPaths,
   readHubState,

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

@@ -194,12 +194,16 @@ function whereInfo(opts) {
   const options = opts || {};
   const running = safeRealpath(process.argv[1] || '');
   const registry = readSelfRegistry(options);
+  const hubResolved = hubLib.resolveHub(options);
   return {
     action: 'where',
     running,
     version: readPackageVersion(packageRoot()),
     defaultDir: defaultSelfDir(options),
-    hubDir: hubLib.resolveHubDir(options),
+    hubDir: hubResolved.dir,
+    hubSource: hubResolved.source,
+    hubConfigured: hubResolved.configured,
+    hubConfigFile: hubResolved.configFile,
     registry: selfRegistryPath(options),
     installs: registry.installs.map((item) => ({
       dir: item.dir,

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

@@ -0,0 +1,170 @@
+'use strict';
+/**
+ * 用户级配置（0.29.2 U4）—— <root>/config.json。
+ *
+ * root = YOTTA_SKILLS_HOME 或 ~/.yottaskills（与 hosts.json / self.json 同根，
+ * 独立于 Hub 目录本身）。schema v1：{ version, hub: "<path>" | null }。
+ *
+ * Hub 解析优先级：--hub flag > YOTTA_SKILLS_HUB env > config.hub > 默认 <root>/hub。
+ * set 为 fail-closed 校验：不能是文件、不能与配置根 / 独立安装目录重叠、
+ * 不能是锁 / 数据桥接目录；路径不存在时允许（首次使用时创建）。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const agentDirsLib = require('./agent-dirs');
+
+const CONFIG_VERSION = 1;
+
+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 configPath(opts) {
+  return path.join(resolveSkillsRoot(opts), 'config.json');
+}
+
+function defaultHubDir(opts) {
+  return path.join(resolveSkillsRoot(opts), 'hub');
+}
+
+function readConfig(opts) {
+  try {
+    const value = JSON.parse(fs.readFileSync(configPath(opts), 'utf8'));
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return {
+        version: CONFIG_VERSION,
+        hub: typeof value.hub === 'string' && value.hub.trim() ? value.hub : null,
+      };
+    }
+  } catch (_) { /* missing or corrupt config falls back to empty */ }
+  return { version: CONFIG_VERSION, hub: null };
+}
+
+function writeConfig(opts, config) {
+  const file = configPath(opts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify({
+    version: CONFIG_VERSION,
+    hub: config && config.hub ? config.hub : null,
+  }, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** 解析生效 Hub：返回 { dir, source, configured, configFile, defaultDir }。 */
+function resolveHub(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const config = readConfig(options);
+  const base = {
+    configured: config.hub,
+    configFile: configPath(options),
+    defaultDir: defaultHubDir(options),
+  };
+  if (options.hub) return { dir: path.resolve(options.hub), source: 'flag', ...base };
+  if (env.YOTTA_SKILLS_HUB) return { dir: path.resolve(env.YOTTA_SKILLS_HUB), source: 'env', ...base };
+  if (config.hub) return { dir: path.resolve(config.hub), source: 'config', ...base };
+  return { dir: base.defaultDir, source: 'default', ...base };
+}
+
+function sourceLabel(source) {
+  if (source === 'flag') return '--hub 参数';
+  if (source === 'env') return 'YOTTA_SKILLS_HUB 环境变量';
+  if (source === 'config') return 'config.json 配置';
+  return '默认位置';
+}
+
+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 校验 Hub 路径；返回 { ok:true, dir } 或 { ok:false, error }。 */
+function validateHubPath(input, opts) {
+  const options = opts || {};
+  const raw = String(input == null ? '' : input).trim();
+  if (!raw) return { ok: false, error: '缺少路径：hub config set --hub <path>' };
+  const dir = path.resolve(raw);
+  let stat = null;
+  try {
+    stat = fs.statSync(dir);
+  } catch (_) { /* 不存在允许：首次使用时创建 */ }
+  if (stat && !stat.isDirectory()) return { ok: false, error: '不是目录：' + dir };
+  const root = resolveSkillsRoot(options);
+  if (isInside(dir, root)) {
+    return {
+      ok: false,
+      error: 'Hub 不能与配置根相同或包含配置根（' + root + '）：config.json / hosts.json / self.json 需保持独立',
+    };
+  }
+  const selfDir = path.join(root, 'yotta-skills');
+  if (samePath(dir, selfDir) || isInside(selfDir, dir) || isInside(dir, selfDir)) {
+    return { ok: false, error: 'Hub 不能与独立安装目录重叠（' + selfDir + '）' };
+  }
+  if (agentDirsLib.isBridgeOnlyDir(dir, options)) {
+    return { ok: false, error: '锁 / 数据桥接目录不能作为 Hub：' + dir };
+  }
+  return { ok: true, dir };
+}
+
+/** 写入持久 Hub 覆盖；返回 { ok, hub, configFile, previous }。 */
+function setHub(opts, input) {
+  const options = opts || {};
+  const guard = validateHubPath(input && input.hub, options);
+  if (!guard.ok) return guard;
+  const config = readConfig(options);
+  const previous = config.hub;
+  config.hub = guard.dir;
+  const file = writeConfig(options, config);
+  return { ok: true, hub: guard.dir, configFile: file, previous };
+}
+
+/** 清除持久 Hub 覆盖（恢复 flag > env > 默认）。 */
+function clearHub(opts) {
+  const options = opts || {};
+  const config = readConfig(options);
+  if (!config.hub) return { ok: false, error: '没有可清除的 Hub 配置覆盖（当前来源不是 config.json）' };
+  const removed = config.hub;
+  config.hub = null;
+  const file = writeConfig(options, config);
+  return { ok: true, removed, configFile: file };
+}
+
+module.exports = {
+  CONFIG_VERSION,
+  resolveSkillsRoot,
+  configPath,
+  defaultHubDir,
+  readConfig,
+  writeConfig,
+  resolveHub,
+  sourceLabel,
+  validateHubPath,
+  setHub,
+  clearHub,
+};

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

@@ -12,7 +12,24 @@ symlink），升级只改真源，已链接宿主即时生效。
 - 技能台账：`<hub>/.yotta-hub.json`
 - 链接台账：`<hub>/.yotta-links.json`
 - 收敛回收站：`~/.yottaskills/trash/<时间戳>/<宿主>/<技能>/`（保留 7 天，可用 `YOTTA_SKILLS_TRASH` 覆盖）
-- 覆盖方式：`--hub <dir>` 或 `YOTTA_SKILLS_HUB`
+- 覆盖方式（优先级）：`--hub <dir>` > `YOTTA_SKILLS_HUB` > `config.json`（`hub config set`）> 默认
+
+## Hub 位置持久化（0.29.2 起）
+
+`hub config` 把 Hub 位置写进用户级配置（与 hosts.json / self.json 同根）：
+
+```bash
+npx -y @yottameta/yotta-skills hub config get                # 生效位置 + 来源 + 配置文件
+npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub"        # 只换指针（旧 Hub 保留）
+npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub" --move # 迁移：复制校验 → 重链 → 旧 Hub 入回收站
+npx -y @yottameta/yotta-skills hub config clear              # 清除覆盖，回到 flag > env > 默认
+```
+
+- 配置文件：`<YOTTA_SKILLS_HOME>/config.json`（默认 `~/.yottaskills/config.json`；schema v1，原子写）。
+- 校验（fail-closed）：路径不能是文件、不能与配置根 / 独立安装目录重叠、不能是锁 / 数据桥接目录；路径不存在允许（首次使用时创建）。
+- `--move` 语义：旧 Hub 复制到新位置 → 逐技能 treeHash 校验 → 切换配置 → `hub link` 以新 Hub 为源 `--force` 重链 → 旧 Hub 入回收站（保留 7 天）。校验失败不切配置；重链未全部完成时旧 Hub 保留供重试（新旧内容一致，混合链接均可用）。
+- 面板「Hub 位置」区显示来源 / 配置覆盖 / 重启提示，并提供「设置新位置 / 清除覆盖」（写操作需页面令牌 + `hub-config` 确认串）；已在运行的 `view` 需重启后生效。
+- 误用防护：`--hub` 只允许与 `hub` / `view` / `where` 一起使用；其它命令（含裸 `--hub`）fail-closed 报错，不再静默忽略。
 
 ## 元技能唯一性收敛（`hub link` 执行时）
 

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

@@ -1,14 +1,14 @@
 # 全家技能清单（27 个）
 
 > 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
-> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-10-03。
+> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-10-05。
 
 | slug | 中文名 | npm 包 | 清单版本 | 家族 | 说明 |
 |---|---|---|---|---|
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.2 | quality | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
 | `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.3 | quality | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
 | `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.3 | workflow | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.2 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.3 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
 | `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.2 | memory | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
 | `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.3.1 | security | 安全扫描引擎：13 类检测器 + 系统安全基线 + 学生数据隐私（教育版） |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.7 | security | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |