@yottameta/yotta-skills 0.19.4 → 0.19.5

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## v0.19.5 (2026-09-15)
+
+**多源技能盘点版本修复**：
+
+- 同名技能多副本扫描新增 `variants` 明细，代表版本取合法版本中的最高 semver；版本差异持久化为 `conflicts`，不再由首个来源副本决定显示版本。
+- `--inventory` / `--route` 显示代表版本与多副本摘要；`doctor` 优先按目标目录匹配精确副本版本，旧注册表缺少 `variants` 时回退聚合版本。
+- 回归覆盖多副本 semver 选择、注册表幂等、CLI 文本/JSON 与 doctor 精确匹配；`npm test` 168/168。
+
 ## v0.19.4 (2026-09-14)
 
 **元造 0.1.2 清单同步**：

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.19.4
+version: 0.19.5
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么组合使用（安装与调用均由用户确认后执行）」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录（默认 --pin 锁死清单精确版本）；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工只建议跑本地 --reindex；更新检查走手动 --check 或后台 --check --scheduled）；运行时适配层：hook capabilities / evaluate / bind / unbind 按宿主能力矩阵执行六个统一事件并留证降级，元信 before_install 已接入安装管线；自包含零依赖，不依赖任何元技能；MCP 按需加载且需用户确认后写入配置（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin（默认）/ --range。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:

package/bin/yotta-skills.js

@@ -37,7 +37,7 @@ const hookAdapterLib = require('../lib/hook-adapter');
 const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.19.4';
+let VERSION = '0.19.5';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -1189,7 +1189,15 @@ function runRoute(opts) {
   out('');
   out('调用顺序:');
   for (const skill of result.skills) {
-    out('  ' + skill.order + '. ' + skill.slug + ' [' + (skill.installed ? '已装' : '缺失') + '] - ' + skill.role);
+    const status = skill.installed
+      ? '已装' + (skill.version ? ' v' + skill.version : '')
+      : '缺失';
+    const conflictHint = skill.conflicts && skill.conflicts.length
+      ? '（其他副本: ' + skill.conflicts
+        .map((item) => (item.source || '其他') + ' v' + (item.version || '?'))
+        .join('、') + '）'
+      : '';
+    out('  ' + skill.order + '. ' + skill.slug + ' [' + status + '] - ' + skill.role + conflictHint);
   }
   if (result.missing_skills.length) {
     out('');

package/lib/install-health.js

@@ -24,6 +24,20 @@ function readManifest(target, slug) {
   }
 }
 
+/** 优先读取目标目录对应的副本版本，旧注册表缺少 variants 时回退聚合版本。 */
+function registryVersionForTarget(record, target) {
+  const variants = Array.isArray(record.variants) ? record.variants : [];
+  const normalizedTarget = path.resolve(target);
+  const exact = variants.find((variant) => {
+    if (!variant || !variant.dir) return false;
+    return path.resolve(variant.dir) === normalizedTarget;
+  });
+  if (exact && exact.version) {
+    return { version: String(exact.version).trim(), scope: 'target' };
+  }
+  return { version: record.version ? String(record.version).trim() : '', scope: 'aggregate' };
+}
+
 function checkInstalledSkill(context) {
   const ctx = context || {};
   const slug = String(ctx.slug || '');
@@ -122,18 +136,22 @@ function checkInstalledSkill(context) {
       addCheck(checks, 'registry', false, '注册表未记录当前技能', 'warning');
       warnings.push('注册表未记录当前技能');
       fixes.push('运行 yotta-skills --reindex 重扫注册表');
-    } else if (version && record.version && record.version !== version) {
-      addCheck(
-        checks,
-        'registry',
-        false,
-        '注册表版本 v' + record.version + ' 与已安装 v' + version + ' 不一致',
-        'warning',
-      );
-      warnings.push('注册表版本 v' + record.version + ' 与已安装 v' + version + ' 不一致');
-      fixes.push('运行 yotta-skills --reindex 重扫注册表');
     } else {
-      addCheck(checks, 'registry', true, '注册表记录一致');
+      const registryVersion = registryVersionForTarget(record, target);
+      if (version && registryVersion.version && registryVersion.version !== version) {
+        const scopeText = registryVersion.scope === 'target' ? '注册表版本（目标副本）' : '注册表版本（聚合）';
+        addCheck(
+          checks,
+          'registry',
+          false,
+          scopeText + ' v' + registryVersion.version + ' 与已安装 v' + version + ' 不一致',
+          'warning',
+        );
+        warnings.push(scopeText + ' v' + registryVersion.version + ' 与已安装 v' + version + ' 不一致');
+        fixes.push('运行 yotta-skills --reindex 重扫注册表');
+      } else {
+        addCheck(checks, 'registry', true, '注册表记录一致');
+      }
     }
   }
 

package/lib/route.js

@@ -183,6 +183,8 @@ function routeRequest(request, options) {
       installed: isInstalled,
       version: isInstalled ? record.version || '' : '',
       sources: isInstalled ? record.sources || [] : [],
+      variants: isInstalled && Array.isArray(record.variants) ? record.variants : [],
+      conflicts: isInstalled && Array.isArray(record.conflicts) ? record.conflicts : [],
     };
   });
   const missingSkills = skills

package/lib/skills-scan.js

@@ -81,6 +81,67 @@ function parseFrontmatter(text) {
   return fm;
 }
 
+/** 解析 semver（用于多副本版本选择；无法解析时返回 null）。 */
+function parseSemver(value) {
+  const match = String(value || '').trim().match(
+    /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/,
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (!left.length && !right.length) return 0;
+  if (!left.length) return 1;
+  if (!right.length) return -1;
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    if (left[i] === undefined) return -1;
+    if (right[i] === undefined) return 1;
+    const a = left[i];
+    const b = right[i];
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+      const diff = Number(a) - Number(b);
+      if (diff) return diff;
+    } else if (aNumeric !== bNumeric) {
+      return aNumeric ? -1 : 1;
+    } else if (a !== b) {
+      return a < b ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** semver 比较：left > right 返回正数，left < right 返回负数。 */
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] - b[key];
+  }
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+/** 从多个安装副本中选择代表版本：优先合法版本中的最高 semver。 */
+function selectRepresentativeVariant(variants) {
+  let selected = null;
+  for (const variant of variants) {
+    if (!parseSemver(variant.version)) continue;
+    if (!selected || compareSemver(variant.version, selected.version) > 0) {
+      selected = variant;
+    }
+  }
+  return selected || variants.find((variant) => variant.version) || variants[0] || null;
+}
+
 /** 扫描单个技能目录：子目录含 SKILL.md 且 frontmatter 有 name 即视为技能。 */
 function scanSkillDir(dir) {
   const results = [];
@@ -179,21 +240,41 @@ function scanRoots(roots) {
     scanned.push({ dir: r.dir, label: r.label });
     for (const s of scanSkillDir(r.dir)) {
       const key = s.slug;
+      const variant = {
+        source: r.label,
+        dir: s.source_dir,
+        version: s.version || '',
+        description: s.description || '',
+      };
       const item = map.get(key);
       if (item) {
         if (!item.sources.includes(r.label)) item.sources.push(r.label);
         if (!item.source_dirs.includes(s.source_dir)) item.source_dirs.push(s.source_dir);
-        if (item.version && s.version && item.version !== s.version) {
-          item.conflicts = item.conflicts || [];
-          item.conflicts.push({ dir: s.source_dir, version: s.version });
-        }
+        item.variants.push(variant);
       } else {
         s.sources = [r.label];
         s.source_dirs = [s.source_dir];
+        s.variants = [variant];
         map.set(key, s);
       }
     }
   }
+  for (const item of map.values()) {
+    const representative = selectRepresentativeVariant(item.variants);
+    if (!representative) continue;
+    item.version = representative.version || '';
+    if (representative.description) item.description = representative.description;
+    item.source_dir = representative.dir || item.source_dir;
+    const conflicts = item.variants
+      .filter((variant) => variant.version && variant.version !== item.version)
+      .map((variant) => ({
+        source: variant.source,
+        dir: variant.dir,
+        version: variant.version,
+      }));
+    if (conflicts.length) item.conflicts = conflicts;
+    else delete item.conflicts;
+  }
   return {
     generated_at: new Date().toISOString(),
     skills: Array.from(map.values()).sort((a, b) => a.slug.localeCompare(b.slug)),
@@ -231,30 +312,33 @@ function mergeRegistry(scanResult, previous) {
   for (const s of scanResult.skills) {
     seen.add(s.slug);
     const old = prev[s.slug];
+    const variants = Array.isArray(s.variants) ? s.variants : [];
+    const conflicts = Array.isArray(s.conflicts) ? s.conflicts : [];
+    const nextRecord = old ? { ...old } : {
+      slug: s.slug,
+      first_seen: now,
+    };
+    nextRecord.version = s.version;
+    nextRecord.description = s.description;
+    nextRecord.sources = s.sources;
+    nextRecord.source_dirs = s.source_dirs;
+    nextRecord.last_seen = now;
+    nextRecord.status = 'known';
+    if (variants.length) nextRecord.variants = variants;
+    else delete nextRecord.variants;
+    if (conflicts.length) nextRecord.conflicts = conflicts;
+    else delete nextRecord.conflicts;
     if (!old) {
-      next[s.slug] = {
-        slug: s.slug,
-        version: s.version,
-        description: s.description,
-        sources: s.sources,
-        source_dirs: s.source_dirs,
-        first_seen: now,
-        last_seen: now,
-        status: 'known',
-      };
+      next[s.slug] = nextRecord;
       changes.added.push(s.slug);
     } else {
       const changed = old.version !== s.version
         || old.description !== s.description
-        || JSON.stringify(old.sources || []) !== JSON.stringify(s.sources);
-      next[s.slug] = {
-        ...old,
-        version: s.version,
-        description: s.description,
-        sources: s.sources,
-        source_dirs: s.source_dirs,
-        last_seen: now,
-      };
+        || JSON.stringify(old.sources || []) !== JSON.stringify(s.sources)
+        || JSON.stringify(old.source_dirs || []) !== JSON.stringify(s.source_dirs)
+        || JSON.stringify(old.variants || []) !== JSON.stringify(variants)
+        || JSON.stringify(old.conflicts || []) !== JSON.stringify(conflicts);
+      next[s.slug] = nextRecord;
       if (changed) changes.updated.push(s.slug);
     }
   }
@@ -295,7 +379,14 @@ function formatInventory(registry, filePath) {
   for (const s of skills) {
     const ver = s.version ? 'v' + s.version : '-';
     const src = (s.sources || []).join(',');
-    lines.push(`${s.slug}  ${ver}  ${s.description || ''}  [${src}]`);
+    const versions = new Set((s.variants || []).map((variant) => variant.version).filter(Boolean));
+    const variantHint = versions.size > 1
+      ? '  {多副本: ' + (s.variants || [])
+        .filter((variant) => variant.version)
+        .map((variant) => (variant.source || '其他') + ' v' + variant.version)
+        .join(', ') + '}'
+      : '';
+    lines.push(`${s.slug}  ${ver}  ${s.description || ''}  [${src}]${variantHint}`);
   }
   const rp = filePath || registryPath();
   lines.push(`共 ${skills.length} 个技能；注册表：${rp}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.19.4",
+  "version": "0.19.5",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [

package/scripts/yotta-skills-mcp.py

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

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-skills",
   "name": "元阁",
   "package": "@yottameta/yotta-skills",
-  "version": "0.19.4",
+  "version": "0.19.5",
   "trust": "yottameta",
   "install": {
     "idempotent": true