@yottameta/yotta-skills-plugin 0.24.2 → 0.25.1

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

@@ -17,33 +17,15 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const agentDirs = require('./agent-dirs');
 
 const REGISTRY_DIR_NAME = '.yottaskills';
 const REGISTRY_FILE_NAME = 'registry.json';
 const SKILL_FILE = 'SKILL.md';
 
-// 智能体 -> 用户级默认技能目录（与 bin/yotta-skills.js AGENT_DIRS 同源；
-// 依据 agent-skill-dir-map 权威映射，2026-08-23 核实）
-const AGENT_DIRS = {
-  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
-  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
-  codex:     { label: 'Codex',            dirs: [] }, // 特判：$CODEX_HOME/skills
-  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
-  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
-  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
-  opencode:  { label: 'OpenCode',         dirs: [] }, // 特判：$XDG_CONFIG_HOME
-  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
-  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
-  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
-  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
-  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
-  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
-  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
-  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
-  openclaw:  { label: 'OpenClaw / QClaw', dirs: ['.openclaw/skills'] }, // 特判：$OPENCLAW_STATE_DIR
-  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
-};
+// 智能体 -> 用户级默认技能目录。单一真源在 lib/agent-dirs.js
+// （兼容 Vercel Labs `skills` CLI / agentskills.io 的宿主表，MIT）。
+const AGENT_DIRS = agentDirs.AGENT_DIRS;
 
 /** 解析 SKILL.md 前部 YAML frontmatter（name/version/description 单行值）。 */
 function parseFrontmatter(text) {
@@ -153,8 +135,13 @@ function scanSkillDir(dir) {
     return results;
   }
   for (const e of entries) {
-    if (!e.isDirectory()) continue;
+    if (!e.isDirectory() && !e.isSymbolicLink()) continue;
     const skillDir = path.join(dir, e.name);
+    try {
+      if (!fs.statSync(skillDir).isDirectory()) continue;
+    } catch (_) {
+      continue;
+    }
     let text;
     try {
       text = fs.readFileSync(path.join(skillDir, SKILL_FILE), 'utf8');
@@ -175,27 +162,21 @@ function scanSkillDir(dir) {
 
 /** Codex 用户级技能目录：$CODEX_HOME/skills（默认 ~/.codex/skills）。 */
 function codexUserDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'skills');
+  return agentDirs.resolveUserDir('.codex/skills', { homeDir: os.homedir(), env: process.env });
 }
 
 /** OpenCode 用户级技能目录：$XDG_CONFIG_HOME/opencode/skills。 */
 function opencodeUserDir() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(base, 'opencode', 'skills');
+  return agentDirs.resolveUserDir('.config/opencode/skills', { homeDir: os.homedir(), env: process.env });
 }
 
 /** OpenClaw / QClaw 用户级技能目录：$OPENCLAW_STATE_DIR/skills（默认 ~/.openclaw/skills）。 */
 function openclawUserDir() {
-  const base = process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), '.openclaw');
-  return path.join(base, 'skills');
+  return agentDirs.resolveUserDir('.openclaw/skills', { homeDir: os.homedir(), env: process.env });
 }
 
 function resolveUserDir(rel) {
-  if (rel === '.codex/skills') return codexUserDir();
-  if (rel === '.config/opencode/skills') return opencodeUserDir();
-  if (rel === '.openclaw/skills') return openclawUserDir();
-  return path.join(os.homedir(), rel);
+  return agentDirs.resolveUserDir(rel, { homeDir: os.homedir(), env: process.env });
 }
 
 /**
@@ -216,12 +197,9 @@ function defaultRoots(opts) {
     roots.push({ dir: norm, label });
   };
   const home = os.homedir();
-  for (const key of Object.keys(AGENT_DIRS)) {
-    const info = AGENT_DIRS[key];
-    for (const rel of info.dirs) add(resolveUserDir(rel), info.label);
+  for (const root of agentDirs.knownRoots({ homeDir: home, env: process.env })) {
+    add(root.dir, root.label);
   }
-  add(codexUserDir(), 'Codex');
-  add(opencodeUserDir(), 'OpenCode');
   if (Array.isArray(opts.extraDirs)) {
     for (const d of opts.extraDirs) add(d, '指定目录');
   }
@@ -268,6 +246,11 @@ function scanRoots(roots) {
     }
   }
   for (const item of map.values()) {
+    item.variants.sort((a, b) => {
+      const byVersion = compareSemver(a.version, b.version);
+      if (byVersion) return byVersion;
+      return String(a.source || '').localeCompare(String(b.source || ''));
+    });
     const representative = selectRepresentativeVariant(item.variants);
     if (!representative) continue;
     item.version = representative.version || '';
@@ -282,6 +265,13 @@ function scanRoots(roots) {
       }));
     if (conflicts.length) item.conflicts = conflicts;
     else delete item.conflicts;
+    if (item.conflicts) {
+      item.conflicts.sort((a, b) => {
+        const byVersion = compareSemver(a.version, b.version);
+        if (byVersion) return byVersion;
+        return String(a.source || '').localeCompare(String(b.source || ''));
+      });
+    }
   }
   return {
     generated_at: new Date().toISOString(),

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

@@ -0,0 +1,66 @@
+# Hub（本机单点安装 + 链接分发）
+
+## 它解决什么
+
+多智能体各自维护技能目录时，同一技能会被复制多份，升级后容易版本漂移。Hub 把
+技能集中到本机一份真源，再按宿主建立链接（Windows junction / macOS·Linux
+symlink），升级只改真源，已链接宿主即时生效。
+
+## 默认位置
+
+- Hub 真源：`~/.yottaskills/hub`
+- 技能台账：`<hub>/.yotta-hub.json`
+- 链接台账：`<hub>/.yotta-links.json`
+- 覆盖方式：`--hub <dir>` 或 `YOTTA_SKILLS_HUB`
+
+## 命令
+
+```bash
+# 发现本机已装智能体与技能目录（文件系统优先；不读元忆 / 注册表）
+npx -y @yottameta/yotta-skills hub hosts
+
+# 安装 / 更新 Hub 真源
+npx -y @yottameta/yotta-skills hub install
+npx -y @yottameta/yotta-skills hub update
+
+# 接管各宿主现有技能：先只读预演，再复制收编（原目录保留）
+npx -y @yottameta/yotta-skills hub adopt --scan
+npx -y @yottameta/yotta-skills hub adopt --apply
+
+# 非元阁来源技能没有统一更新源：手动从指定目录刷新
+npx -y @yottameta/yotta-skills hub refresh my-skill --from <技能目录>
+
+# 分发到全部已发现宿主（默认不覆盖真目录；--force 才备份并替换）
+npx -y @yottameta/yotta-skills hub link --all
+
+# 只删除链接，不动 Hub 真源
+npx -y @yottameta/yotta-skills hub unlink --all
+
+# 查看来源、版本、链接宿主与异常
+npx -y @yottameta/yotta-skills hub status
+npx -y @yottameta/yotta-skills hub doctor
+```
+
+## 宿主发现口径
+
+1. 已收录宿主映射（兼容 Vercel Labs `skills` CLI / SkillCat 的公开宿主表）；
+2. 环境变量覆盖（`CODEX_HOME`、`XDG_CONFIG_HOME`、`DSH_HOME`、
+   `OPENCLAW_STATE_DIR`、`CLAUDE_CONFIG_DIR` 等）；
+3. 常见配置根启发式扫描；
+4. `YOTTA_SKILLS_DISCOVERY_ROOTS` 显式补充；
+5. `--dir <path>` 精确指定非标准宿主。
+
+自动发现默认排除临时目录、`.bak`、candidate / staging、插件构建目录等噪声。
+
+## 兼容标准
+
+- 技能格式：`agentskills.io` Agent Skills（`SKILL.md` + `name` / `description`）。
+- 通用投影：`~/.agents/skills`、`$XDG_CONFIG_HOME/agents/skills`。
+- 官方锁文件：只读兼容 Vercel Labs `skills` CLI 的 `.skill-lock.json` v3
+  （`$XDG_STATE_HOME/skills/` 或 `~/.agents/`）。
+
+## 安全边界
+
+- `unlink` 只删除 lstat 确认为链接、且 readlink 目标位于 Hub 内的路径。
+- 真目录 / 非 Hub 链接一律拒绝删除；`--force` 对真目录先备份再替换。
+- Hub 仅本机使用，不对外分发技能内容。

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

@@ -6,7 +6,7 @@
 | slug | 中文名 | npm 包 | 清单版本 | 家族 | 说明 |
 |---|---|---|---|---|
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.2 | quality | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
-| `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.2 | quality | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
+| `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.21.1 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
 | `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.2 | memory | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |

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

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

package/skills/yotta-skills/skills.json

@@ -15,7 +15,7 @@
       "slug": "yotta-code-quality",
       "name": "元质",
       "pkg": "@yottameta/yotta-code-quality",
-      "version": "0.4.2",
+      "version": "0.4.3",
       "domain": "quality",
       "desc": "结对式代码质量评审（十二类腐化风险 + 0-100 健康分）"
     },