@yottameta/yotta-skills-plugin 0.29.3 → 0.29.5

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

@@ -61,6 +61,39 @@ function restoreBackup(target, backup, hadTarget) {
   return false;
 }
 
+/** 暂存子目录超过 1 小时视为崩溃残留（并发安装的暂存目录总是新鲜的）。 */
+const STAGING_STALE_MS = 60 * 60 * 1000;
+
+/** 清理目标目录 `.yottaskills-staging` 中的陈旧暂存（best-effort，返回清理数）。 */
+function pruneStaleStaging(stagingRoot, options) {
+  const opts = options || {};
+  const now = opts.now instanceof Date ? opts.now.getTime() : Date.now();
+  let entries;
+  try {
+    entries = fs.readdirSync(stagingRoot, { withFileTypes: true });
+  } catch (_) {
+    return 0;
+  }
+  let pruned = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const full = path.join(stagingRoot, entry.name);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch (_) {
+      continue;
+    }
+    if (now - stat.mtimeMs > STAGING_STALE_MS) {
+      try {
+        fs.rmSync(full, { recursive: true, force: true });
+        pruned += 1;
+      } catch (_) { /* 保留供下次清理 */ }
+    }
+  }
+  return pruned;
+}
+
 /** 0.29.1 U1「只升不降」跳过原因文案（equal / local-ahead / unknown）。 */
 function versionSkipNote(relation, installed, target) {
   if (relation === 'equal') return '已是最新';
@@ -128,6 +161,7 @@ function createInstaller(deps) {
 
     let tmp = null;
     let staged = null;
+    let stagingRoot = null;
     let snapshot = null;
     let backup = null;
     const hadTarget = fs.existsSync(target);
@@ -274,14 +308,24 @@ function createInstaller(deps) {
       }
 
       fs.mkdirSync(dest, { recursive: true });
-      const stagingRoot = path.join(dest, '.yottaskills-staging');
+      stagingRoot = path.join(dest, '.yottaskills-staging');
       fs.mkdirSync(stagingRoot, { recursive: true });
+      pruneStaleStaging(stagingRoot);
       staged = fs.mkdtempSync(path.join(stagingRoot, skill.slug + '-'));
       // Hub installs keep declared runtime payload (e.g. yotta-skills bin):
       // hosts linked to the Hub then inherit the runtime files (OpenCode contract).
-      const runtimePayload = (opts.hubScope && Array.isArray(resolvedSkill.runtimePayload))
-        ? resolvedSkill.runtimePayload
-        : [];
+      // 0.29.5 S4：`--dir` 托管目录更新保持既有运行时载荷（目标已带 bin/ 等 → 继续携带），
+      // 防更新后引擎缺 bin；新装 / 普通技能目录仍只落本体（§6.3 口径不变）。
+      let runtimePayload = [];
+      if (Array.isArray(resolvedSkill.runtimePayload) && resolvedSkill.runtimePayload.length > 0) {
+        if (opts.hubScope) {
+          runtimePayload = resolvedSkill.runtimePayload;
+        } else if (hadTarget) {
+          const carriesPayload = resolvedSkill.runtimePayload
+            .some((name) => fs.existsSync(path.join(target, name)));
+          if (carriesPayload) runtimePayload = resolvedSkill.runtimePayload;
+        }
+      }
       const copyWithRuntime = (src, dst) => deps.copyDir(src, dst, { keep: runtimePayload });
       copyTree(extracted.pkgDir, staged, copyWithRuntime);
 
@@ -454,8 +498,12 @@ function createInstaller(deps) {
     } finally {
       if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
       if (staged) fs.rmSync(staged, { recursive: true, force: true });
+      if (stagingRoot) {
+        // 结束（含失败）强制清理：目录为空时删除；并发安装留下的新鲜暂存则保留。
+        try { fs.rmdirSync(stagingRoot); } catch (_) { /* 非空 / 并发占用，保留 */ }
+      }
     }
   };
 }
 
-module.exports = { createInstaller, renameWithRetry, isSafeTarEntry };
+module.exports = { createInstaller, renameWithRetry, isSafeTarEntry, pruneStaleStaging, STAGING_STALE_MS };

package/skills/yotta-skills/lib/npm-pack.js

@@ -72,6 +72,9 @@ function createPackRunner(deps) {
       timeout: 180000,
       maxBuffer: 64 * 1024 * 1024,
       shell: npm.shell,
+      // 0.29.5 S4：显式继承调用方环境（YOTTA_SKILLS_REGISTRY_FILE / YOTTA_SKILLS_MANIFEST /
+      // npm_config_* 等必须传到 npm / npx 子进程；此前依赖 spawnSync 默认继承，行为不变）。
+      env: process.env,
     });
 
     let result = attempt(baseArgs);

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

@@ -1,9 +1,15 @@
 'use strict';
 /**
- * 用户级配置（0.29.2 U4）—— <root>/config.json。
+ * 用户级配置（0.29.2 U4；0.29.5 扩展 lastMigration / lastSwitch）—— <root>/config.json。
  *
  * root = YOTTA_SKILLS_HOME 或 ~/.yottaskills（与 hosts.json / self.json 同根，
- * 独立于 Hub 目录本身）。schema v1：{ version, hub: "<path>" | null }。
+ * 独立于 Hub 目录本身）。schema v1（向后兼容增量）：
+ *   { version, hub: "<path>" | null, lastMigration?: {...}, lastSwitch?: {...} }
+ *
+ * - lastMigration：最近一次成功切换位置的真实迁移（含回滚；from→to + 校验技能数 +
+ *   重链目录数 + 回收站路径），供 `hub config get` / 面板「最近一次迁移 + 一键回滚」。
+ * - lastSwitch：仅切换指针（未迁移）时记录的原位置，供面板提示
+ *   「旧 Hub 还有 N 个技能未迁移」。
  *
  * Hub 解析优先级：--hub flag > YOTTA_SKILLS_HUB env > config.hub > 默认 <root>/hub。
  * set 为 fail-closed 校验：不能是文件、不能与配置根 / 独立安装目录重叠、
@@ -39,20 +45,72 @@ function readConfig(opts) {
       return {
         version: CONFIG_VERSION,
         hub: typeof value.hub === 'string' && value.hub.trim() ? value.hub : null,
+        lastMigration: sanitizeMigration(value.lastMigration),
+        lastSwitch: sanitizeSwitch(value.lastSwitch),
       };
     }
   } catch (_) { /* missing or corrupt config falls back to empty */ }
-  return { version: CONFIG_VERSION, hub: null };
+  return { version: CONFIG_VERSION, hub: null, lastMigration: null, lastSwitch: null };
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
+function cleanCount(value) {
+  const num = Number(value);
+  return Number.isFinite(num) && num >= 0 ? num : 0;
+}
+
+/** 规范化 lastMigration（非法条目按缺失处理，绝不抛错）。 */
+function sanitizeMigration(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const from = cleanString(value.from);
+  const to = cleanString(value.to);
+  if (!from || !to) return null;
+  return {
+    kind: value.kind === 'rollback' ? 'rollback' : 'migrate',
+    from,
+    to,
+    at: cleanString(value.at),
+    verifiedSkills: cleanCount(value.verifiedSkills),
+    relinkDirs: cleanCount(value.relinkDirs),
+    incomplete: cleanCount(value.incomplete),
+    trashedTo: cleanString(value.trashedTo),
+    trashError: cleanString(value.trashError),
+    oldHubKept: cleanString(value.oldHubKept),
+    via: cleanString(value.via),
+  };
+}
+
+/** 规范化 lastSwitch（仅切换指针的记录）。 */
+function sanitizeSwitch(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const from = cleanString(value.from);
+  const to = cleanString(value.to);
+  if (!from || !to) return null;
+  return {
+    from,
+    to,
+    at: cleanString(value.at),
+    skills: cleanCount(value.skills),
+    via: cleanString(value.via),
+  };
 }
 
 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({
+  const payload = {
     version: CONFIG_VERSION,
     hub: config && config.hub ? config.hub : null,
-  }, null, 2) + '\n', 'utf8');
+  };
+  const migration = sanitizeMigration(config && config.lastMigration);
+  const switched = sanitizeSwitch(config && config.lastSwitch);
+  if (migration) payload.lastMigration = migration;
+  if (switched) payload.lastSwitch = switched;
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2) + '\n', 'utf8');
   fs.renameSync(tmp, file);
   return file;
 }
@@ -155,6 +213,39 @@ function clearHub(opts) {
   return { ok: true, removed, configFile: file };
 }
 
+/**
+ * 记录最近一次迁移（真实移动；kind=migrate / rollback）。
+ * 迁移完成即清除 lastSwitch（原位置内容已处理，不再提示）。
+ */
+function recordLastMigration(opts, migration) {
+  const options = opts || {};
+  const config = readConfig(options);
+  config.lastMigration = sanitizeMigration(migration);
+  config.lastSwitch = null;
+  const file = writeConfig(options, config);
+  return { ok: true, lastMigration: readConfig(options).lastMigration, configFile: file };
+}
+
+/** 记录「仅切换位置」（未迁移）：原位置留给面板提示「未迁移」。 */
+function recordLastSwitch(opts, info) {
+  const options = opts || {};
+  const config = readConfig(options);
+  config.lastSwitch = sanitizeSwitch(info);
+  const file = writeConfig(options, config);
+  return { ok: true, lastSwitch: readConfig(options).lastSwitch, configFile: file };
+}
+
+/** 清除「未迁移」提示（原位置已空 / 已迁移 / 用户处理）。 */
+function clearLastSwitch(opts) {
+  const options = opts || {};
+  const config = readConfig(options);
+  if (!config.lastSwitch) return { ok: false, cleared: null };
+  const cleared = config.lastSwitch;
+  config.lastSwitch = null;
+  const file = writeConfig(options, config);
+  return { ok: true, cleared, configFile: file };
+}
+
 module.exports = {
   CONFIG_VERSION,
   resolveSkillsRoot,
@@ -167,4 +258,7 @@ module.exports = {
   validateHubPath,
   setHub,
   clearHub,
+  recordLastMigration,
+  recordLastSwitch,
+  clearLastSwitch,
 };

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

@@ -197,6 +197,9 @@ function scanSkillDir(dir) {
     return results;
   }
   for (const e of entries) {
+    // 0.29.5 S4：点目录（.yottaskills-staging / .yottaskills-backup-* 等暂存残留）
+    // 绝不当作技能 slug。
+    if (e.name.startsWith('.')) continue;
     if (!e.isDirectory() && !e.isSymbolicLink()) continue;
     const skillDir = path.join(dir, e.name);
     try {

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

@@ -14,7 +14,7 @@ symlink），升级只改真源，已链接宿主即时生效。
 - 收敛回收站：`~/.yottaskills/trash/<时间戳>/<宿主>/<技能>/`（保留 7 天，可用 `YOTTA_SKILLS_TRASH` 覆盖）
 - 覆盖方式（优先级）：`--hub <dir>` > `YOTTA_SKILLS_HUB` > `config.json`（`hub config set`）> 默认
 
-## Hub 位置持久化（0.29.2 起）
+## Hub 位置持久化（0.29.2 起；0.29.5 迁移向导 / 回滚 / 残留清理）
 
 `hub config` 把 Hub 位置写进用户级配置（与 hosts.json / self.json 同根）：
 
@@ -22,15 +22,33 @@ symlink），升级只改真源，已链接宿主即时生效。
 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 rollback           # 回滚预览（上次迁移前的原位置）
+npx -y @yottameta/yotta-skills hub config rollback --yes     # 执行回滚（位置回退，用当前内容）
 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` 需重启后生效。
+- 目标目录只含元阁自己的空台账残留（`.yotta-hub.json` / `.yotta-hub-audit.jsonl`）时，`--move` 默认 fail-closed 并提示；确认后加 `--clean-residue`（残留移入回收站）再迁移。
+- 迁移记录：`config.json` 的 `lastMigration` 记录时间 / from→to / 校验技能数 / 重链目录数 / 回收站与剩余天数；`hub config get` 展示「最近一次迁移」块与回滚命令。
+- 回滚语义：`hub config rollback` 默认预览、`--yes` 执行 = 位置回退（把当前 Hub 内容复制校验回原位置，再重链、当前 Hub 入回收站 7 天）；**不是**恢复旧快照。目标非空 fail-closed（不合并）。
+- 仅切换指针（不带 `--move`）时，若旧 Hub 非空会记录「未迁移」并在面板提示「旧 Hub 还有 N 个技能未迁移」+ 一键迁移；执行迁移 / 回滚后该提示自动清除。
+- 面板「Hub 位置」区显示来源 / 配置覆盖 / 重启提示，并提供「设置新位置（迁移向导：迁移 / 仅切换，默认迁移）/ 最近一次迁移 + 一键回滚 / 清除覆盖」（写操作需页面令牌 + `hub-config` 确认串）；已在运行的 `view` 需重启后生效。
 - 误用防护：`--hub` 只允许与 `hub` / `view` / `where` 一起使用；其它命令（含裸 `--hub`）fail-closed 报错，不再静默忽略。
 
+## 备份 / 暂存残留清理（0.29.5 起）
+
+`hub link --force` 替换真目录时，旧副本移入回收站（不再原地留 `<name>.yottaskills-backup-*`，宿主不会把备份当技能扫描）。历史残留可用：
+
+```bash
+npx -y @yottameta/yotta-skills hub cleanup-backups          # 预览（Hub + 已核实宿主）
+npx -y @yottameta/yotta-skills hub cleanup-backups --yes    # 移入回收站（7 天可恢复）
+```
+
+- 识别标记：`.yottaskills-backup-*` / `.yottaskills-import-*` / `.yottaskills-rollback-*` / `.yottaskills-staging`。
+- `hub doctor` 会只读报告 `backup_residue:*` 警告并给出清理命令；`--dir` / `--agent` 可收窄范围。
+
 ## 元技能唯一性收敛（`hub link` 执行时）
 
 元技能（清单 27 + 特殊家族 5：元开 / 元伴 / 元呈 / 元阁本体 / 元信MCP）在
@@ -160,7 +178,7 @@ npx -y @yottameta/yotta-skills hub adopt --apply
 npx -y @yottameta/yotta-skills hub refresh my-skill --from <技能目录>
 
 # 分发到全部已核实宿主（默认范围）：元技能链接时收敛旧副本（回收站 7 天）；
-# 外部技能同名真目录默认跳过（--force 才备份并替换）
+# 外部技能同名真目录默认跳过（--force 才把旧副本移入回收站并替换）
 npx -y @yottameta/yotta-skills hub link --all
 
 # 显式把自动发现目录一并纳入（桥接目录永不链接）
@@ -240,7 +258,8 @@ install / update / refresh 只在高级 CLI 页给出可复制命令，不在网
 ## 安全边界
 
 - `unlink` 只删除 lstat 确认为链接、且 readlink 目标位于 Hub 内的路径。
-- 真目录 / 非 Hub 链接一律拒绝删除；`--force` 对真目录先备份再替换。
+- 真目录 / 非 Hub 链接一律拒绝删除；`--force` 对真目录把旧副本移入回收站（7 天）再替换；
+  替换失败会把旧副本移回原位（回收站路径随结果输出）。
 - `remove` 只删指向 Hub 的链接与 Hub 内目录；链接清理报错即中止、不删 Hub；
   Hub 目录入回收站保留 7 天，可恢复。
 - 收敛只动元技能在宿主目录中的旧副本：移入回收站（7 天）而非直删；

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

@@ -9,7 +9,7 @@
 | `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.3 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
-| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.2 | memory | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
+| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.3.0 | 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 判定 |
 | `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.8 | security | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |

package/skills/yotta-skills/scripts/yotta-skills-mcp.py

@@ -27,7 +27,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.29.3"
+VERSION = "0.29.5"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"

package/skills/yotta-skills/skills.json

@@ -40,9 +40,9 @@
       "slug": "yotta-learn",
       "name": "元习",
       "pkg": "@yottameta/yotta-learn",
-      "version": "0.2.2",
+      "version": "0.3.0",
       "domain": "memory",
-      "desc": "学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目"
+      "desc": "学习闭环 + 知识库 CLI：经验沉淀为 .learnings/ 条目；知识分类索引 + 关键词查询"
     },
     {
       "slug": "yotta-security-audit",