@yottameta/yotta-skills 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 更新日志
 
+## v0.2.1 (2026-08-31)
+
+MCP 配置说明补全（按需加载口径）。
+
+- SKILL.md「技能盘点」节补「MCP：按需加载（可选）」：明确本技能与 MCP 均为按需触发、不走常驻；mcpServers 配置 JSON 示例、按需写入步骤（用后可移除）、重启/重载提示、未加载降级 CLI 兜底；frontmatter description 同步按需加载口径。
+- 测试：mcp-e2e serverInfo.version 断言改为动态读 package.json；python 探测加候选兜底（YOTTA_TEST_PYTHON / python / python3 / Scoop python38），Windows 无需手动设环境变量。
+- 版本升至 0.2.1。
+
+## v0.2.0 (2026-08-31)
+
+技能生态盘点层（阶段 A）：元阁从「编排策划 + 安装器」升级为「编排策划 + 安装器 + 技能盘点」。
+
+- 新增 lib/skills-scan.js：技能扫描核心（零依赖 Node.js 18+）——frontmatter 解析（含 YAML block scalar）、多根目录扫描、同名技能去重合并来源、注册表增量合并（新增/更新/消失，幂等）、原子写 ~/.yottaskills/registry.json。
+- 新增 CLI --inventory：盘点本机已装技能（文本表格 / --json 机器可读；--dir 追加目录；--project 附扫项目级目录），自包含输出不依赖任何元技能。
+- 新增 MCP scripts/yotta-skills-mcp.py：stdio JSON-RPC（零依赖），list_installed_skills / describe_skill / reindex 三工具，按需加载。
+- SKILL.md / README 中英同步「技能盘点」层与用法；frontmatter 触发语加「盘点技能 / 查看已装技能」。
+- 测试：skills-scan 7 + cli-inventory 2 + mcp-e2e 2（共 23 用例全绿）。
+- 版本升至 0.2.0。
+
 ## v0.1.3 (2026-08-31)
 
 编排策划层升级：元阁从「一键安装器」升级为「总编排策划 + 一键安装器」两层。

package/README.md

@@ -30,6 +30,7 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 - **Update** — incremental update: add missing skills, upgrade version-skewed ones.
 - **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
 - **Pre-install summary** — if yotta-verify (元信) is available, each skill is scanned first; the verdict is informational only.
+- **Inventory** — scan the skill directories on this machine and keep a local registry (<code>~/.yottaskills/registry.json</code>); self-contained, no other skills required. An optional <code>yotta-skills</code> MCP (on-demand, not resident) exposes <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code>; see <code>SKILL.md</code> for the config.
 
 Boundaries: it only downloads, places and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. It never writes outside the target you specify.
 
@@ -53,6 +54,9 @@ npx -y @yottameta/yotta-skills update --agent codex
 
 # Preview what would be installed (no network, no changes)
 npx -y @yottameta/yotta-skills --dry-run
+
+# Inventory installed skills on this machine (self-contained scan, no other skills needed)
+npx -y @yottameta/yotta-skills --inventory
 ```
 
 Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows 10+ / macOS / most Linux distributions).
@@ -66,6 +70,7 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `install --dir <path>` | Install everything into a directory; each skill lands in `<path>/<slug>` |
 | `install <skill>... [--agent <name> \| --dir <path>]` | Install only the given skills |
 | `update [--agent <name> \| --dir <path>]` | Incremental update: add missing, upgrade version-skewed |
+| `--inventory` | Inventory installed skills: scan skill directories and update the local registry (self-contained); `--json` for JSON, `--project` adds project-level dirs |
 | `--dry-run` | Preview the install / update list; no network, no changes |
 | `--pin` | Lock the exact manifest versions (default: range, latest patch of the same major) |
 | `--force` | Reinstall even when already at the latest version |

package/README.zh-CN.md

@@ -33,6 +33,7 @@
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前摘要**——若装了元信（yotta-verify），先对每个待装技能做一次装前扫描；verdict 仅提示、不拦截。
+- **盘点**——扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</code>）；自包含，不需要任何其他技能。可选 <code>yotta-skills</code> MCP（按需加载、不常驻）提供 <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> 三工具，配置见 <code>SKILL.md</code>。
 
 边界：只做「下载 + 落位 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
 全局安装；只在你指定的目标内写文件。
@@ -57,6 +58,9 @@ npx -y @yottameta/yotta-skills update --agent codex
 
 # 预览将安装清单（不联网、不改动）
 npx -y @yottameta/yotta-skills --dry-run
+
+# 盘点本机已装技能（自包含扫描，不依赖任何元技能）
+npx -y @yottameta/yotta-skills --inventory
 ```
 
 前置：Node.js 18+、npm、系统 tar（Windows 10+ / macOS / 多数 Linux 自带）。
@@ -70,6 +74,7 @@ npx -y @yottameta/yotta-skills --dry-run
 | `install --dir <path>` | 装全家到指定目录，每个技能落在 `<path>/<slug>` |
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失、升级版本不一致的技能 |
+| `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-skills
-version: 0.1.3
-description: 元阁 —— 元阁全家技能的总编排策划 + 一键安装器。策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能（当前 22 个）装进指定智能体或目录，支持 --list 清单 / install / update / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家 等。边界（Do NOT trigger）：只做「组合策划 + 清单 + 下载 + 落位 + 汇总」，不含技能本体、不做技能内容开发、不 -g 污染全局；装前摘要仅供参考，安装决策由用户确认。
+version: 0.2.1
+description: 元阁 —— 元阁全家技能的总编排策划 + 一键安装器 + 技能盘点。策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory 扫描本机已装技能生成注册表（自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex，不常驻，未加载降级 CLI）。支持 --list 清单 / install / update / --inventory / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、盘点或查看本机已装技能、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 清单 + 下载 + 落位 + 汇总 + 盘点」，不含技能本体、不做技能内容开发、不 -g 污染全局；装前摘要仅供参考，安装决策由用户确认。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -26,10 +26,11 @@ metadata:
 
 # 元阁（yotta-skills）
 
-**元阁全家的总编排策划 + 一键安装**，一句话两层：
+**元阁全家的总编排策划 + 一键安装 + 技能盘点**，一句话三层：
 
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该怎么自动装并自动用起来。
 - **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`--dry-run` 预览、`--pin` 锁版本。
+- **盘点层（已装了什么）**：`--inventory` 扫描本机各智能体技能目录，生成/更新本地注册表——自包含扫描，不依赖任何元技能。
 
 每个技能仍走各自独立的 npm 包（版本源唯一）；本包只做「清单 + 下载 + 落位 + 汇总」，**不内置任何技能本体**。
 > **本包不含技能本体**：拿到它只代表有了「编排策划 + 安装工具」；真正装齐需运行 `install`。
@@ -96,6 +97,9 @@ npx -y @yottameta/yotta-skills update --agent codex
 
 # 预览将安装清单（不联网、不改动）
 npx -y @yottameta/yotta-skills --dry-run
+
+# 盘点本机已装技能（自包含扫描，不依赖任何元技能）
+npx -y @yottameta/yotta-skills --inventory
 ```
 
 ## 命令与选项
@@ -107,6 +111,7 @@ npx -y @yottameta/yotta-skills --dry-run
 | `install --dir <path>` | 装全家到指定目录，每个技能落在 `<path>/<slug>` |
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
+| `--inventory` | 盘点本机已装技能：扫描技能目录生成/更新注册表（自包含，不依赖元技能）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
@@ -118,6 +123,51 @@ npx -y @yottameta/yotta-skills --dry-run
 
 不带命令直接给技能名时，等价于 `install <skill>`。
 
+## 技能盘点（--inventory）
+
+元阁自带技能扫描核心（零依赖，不依赖任何元技能）：扫描各智能体技能目录，解析
+`SKILL.md` frontmatter，生成/更新本地注册表 `~/.yottaskills/registry.json`，数据不出本机。
+适合「装了哪些技能、各干嘛、从哪来」的快速盘点。
+
+```bash
+# 盘点本机已装技能（文本表格）
+npx -y @yottameta/yotta-skills --inventory
+
+# 机器可读（JSON）
+npx -y @yottameta/yotta-skills --inventory --json
+
+# 追加扫描任意目录 / 当前项目级目录
+npx -y @yottameta/yotta-skills --inventory --dir ~/my-skills --project
+```
+
+注册表增量合并：新增（added）/ 更新（updated）/ 消失（gone）随输出列出；同名技能来自多个目录时合并来源，版本不一致记录冲突。
+
+### MCP：按需加载（可选）
+
+本技能自带一个 MCP server：`yotta-skills`（`scripts/yotta-skills-mcp.py`，零依赖、数据不出本机），
+提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）三个工具。
+
+**按需加载，不走常驻**：本技能与 MCP 均为按需触发。默认以 CLI 为主
+（`npx -y @yottameta/yotta-skills --inventory`）；需要让 AI 通过工具直接调用时，再按下面配置启用：
+
+1. **检查当前客户端的 `mcpServers`** 是否已有 `yotta-skills` 条目；已有 → 直接使用。
+2. **没有 → 按需写入**下面这一条 server 配置（用后可移除，不要求常驻）：
+   ```json
+   {
+     "mcpServers": {
+       "yotta-skills": {
+         "command": "python",
+         "args": ["<技能目录>/scripts/yotta-skills-mcp.py"]
+       }
+     }
+   }
+   ```
+   > `<技能目录>` = 本技能实际安装目录，**不要写死盘符路径**；Windows 用 `python`，Linux/macOS 用 `python3`。
+3. **提醒用户**：改 `mcpServers` 后多数客户端需**重启 / 重载一次** MCP server 才生效；加载后应看到
+   `list_installed_skills` / `describe_skill` / `reindex` 三个工具。
+4. **降级兜底（重要）**：若客户端未暴露 MCP 工具 / 无法改配置 / server 未加载，**自动降级 CLI**
+   （同一套扫描核心、结果一致）：`npx -y @yottameta/yotta-skills --inventory ...`。
+
 ## 版本策略
 
 - 默认 `range`：按清单 `major.x` 取 npm 最新 patch（如 `0.x`），维护性更新随最新；

package/bin/yotta-skills.js

@@ -22,7 +22,7 @@ const os = require('os');
 const { spawnSync } = require('child_process');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.1.3';
+let VERSION = '0.2.1';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -131,6 +131,7 @@ function parseArgs(argv) {
     list: false, dryRun: false, pin: false, skipScan: false, force: false,
     help: false, version: false, agent: null, dir: null, npm: null,
     python: null, verify: null, command: null, skill: null, rest: [],
+    inventory: false, rescan: false, json: false, project: false,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
@@ -143,6 +144,10 @@ function parseArgs(argv) {
     else if (a === '--force') opts.force = true;
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--version' || a === '-v') opts.version = true;
+    else if (a === '--inventory' || a === '--inv') opts.inventory = true;
+    else if (a === '--rescan') opts.rescan = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--project') opts.project = true;
     else if (a === '--agent') opts.agent = take('--agent').toLowerCase();
     else if (a === '--dir') opts.dir = take('--dir');
     else if (a === '--npm') opts.npm = take('--npm');
@@ -431,6 +436,7 @@ function printHelp() {
   out('  yotta-skills install <skill> --dir <path>  装单个技能（可多个）');
   out('  yotta-skills update --agent <name>  增量更新已装技能（补齐缺失 / 版本不一致）');
   out('  yotta-skills --dry-run              预览将安装清单（不联网、不改动）');
+  out('  yotta-skills --inventory            盘点本机已装技能（自研扫描，不依赖任何元技能）');
   out('');
   out('选项:');
   out('  --agent <name>   智能体键名（--list 可查看；未知智能体请用 --dir）');
@@ -441,6 +447,8 @@ function printHelp() {
   out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
   out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
   out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
+  out('  --json            inventory 时输出 JSON');
+  out('  --project         inventory 时附加扫描当前项目 .agents/skills / .codex/skills');
   out('  -h, --help       帮助');
   out('  -v, --version    版本');
   out('');
@@ -448,12 +456,43 @@ function printHelp() {
   out('依赖: Node.js 18+ / npm / 系统 tar；环境变量 YOTTA_SKILLS_NPM / YOTTA_SKILLS_PYTHON / YOTTA_SKILLS_VERIFY / YOTTA_SKILLS_NPM_FLAGS 可覆盖。');
 }
 
+
+
+// ── 技能盘点（--inventory，自研零依赖扫描） ────────────────────────────────
+function runInventory(opts) {
+  const scan = require('../lib/skills-scan');
+  const extraDirs = opts.dir ? [opts.dir] : [];
+  const roots = scan.defaultRoots({ extraDirs: extraDirs, project: opts.project });
+  const result = scan.scanRoots(roots);
+  const prev = scan.readRegistry();
+  const { registry, changes } = scan.mergeRegistry(result, prev);
+  scan.saveRegistry(registry);
+  if (opts.json) {
+    out(JSON.stringify({
+      generated_at: registry.updated,
+      note: registry.note,
+      scanned: result.scanned,
+      errors: result.errors,
+      changes: changes,
+      skills: Object.values(registry.skills).sort((a, b) => a.slug.localeCompare(b.slug)),
+    }, null, 2));
+    return;
+  }
+  out(scan.formatInventory(registry));
+  out('');
+  out('本次变化: 新增 ' + changes.added.length + ' / 更新 ' + changes.updated.length + ' / 消失 ' + changes.gone.length);
+  if (result.errors.length) {
+    out('跳过不存在目录 ' + result.errors.length + ' 个: ' + result.errors.map((e) => e.dir).join('; '));
+  }
+}
+
 // ── main ───────────────────────────────────────────────────────────────────
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { printHelp(); return; }
   if (opts.version) { out('yotta-skills v' + VERSION); return; }
   if (opts.list) { printList(opts); return; }
+  if (opts.inventory) { runInventory(opts); return; }
 
   const command = opts.command || 'install';
   let dest = resolveTargetDir(opts);

package/lib/skills-scan.js

@@ -0,0 +1,318 @@
+'use strict';
+/**
+ * yotta-skills 技能扫描核心（零依赖 Node.js 18+）
+ *
+ * 技能生态盘点：扫描各智能体技能目录，解析 SKILL.md frontmatter，
+ * 建立本地技能注册表（~/.yottaskills/registry.json）。
+ *
+ * 自包含原则：本模块只依赖 Node.js 标准库，不依赖任何元技能
+ * （不调用元信扫描、不调用元呈渲染、不调用元忆存储）；输出为
+ * 结构化 JSON / 简单文本，由调用方（CLI / MCP）自行呈现。
+ *
+ * 用法（由 bin/yotta-skills.js 与 scripts/yotta-skills-mcp.py 复用）：
+ *   const scan = require('../lib/skills-scan');
+ *   const result = scan.scanRoots(scan.defaultRoots({ extraDirs, project }));
+ *   scan.saveRegistry(result);  // 增量合并写 ~/.yottaskills/registry.json
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+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'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+/** 解析 SKILL.md 前部 YAML frontmatter（name/version/description 单行值）。 */
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  const lines = m[1].split(/\r?\n/);
+  let blockKey = null;
+  let blockChunks = [];
+  for (const raw of lines) {
+    if (blockKey) {
+      if (!raw.trim()) continue; // 空行：跳过并继续 block
+      if (/^\s/.test(raw)) { blockChunks.push(raw.trim()); continue; }
+      fm[blockKey] = blockChunks.join(' ');
+      blockKey = null;
+      blockChunks = [];
+    }
+    const t = raw.trim();
+    if (!t || t.startsWith('#') || t.startsWith('-')) continue;
+    const idx = t.indexOf(':');
+    if (idx <= 0) continue;
+    const key = t.slice(0, idx).trim();
+    let val = t.slice(idx + 1).trim();
+    if (!val) continue;
+    if (/^[>|][-+]?$/.test(val)) {
+      blockKey = key; // YAML block scalar（多行 description）
+      blockChunks = [];
+      continue;
+    }
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    fm[key] = val;
+  }
+  if (blockKey) fm[blockKey] = blockChunks.join(' ');
+  return fm;
+}
+
+/** 扫描单个技能目录：子目录含 SKILL.md 且 frontmatter 有 name 即视为技能。 */
+function scanSkillDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return results;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const skillDir = path.join(dir, e.name);
+    let text;
+    try {
+      text = fs.readFileSync(path.join(skillDir, SKILL_FILE), 'utf8');
+    } catch (_) {
+      continue;
+    }
+    const fm = parseFrontmatter(text);
+    if (!fm || !fm.name) continue;
+    results.push({
+      slug: String(fm.name).trim(),
+      version: fm.version ? String(fm.version).trim() : '',
+      description: fm.description ? String(fm.description).trim() : '',
+      source_dir: skillDir,
+    });
+  }
+  return results;
+}
+
+/** Codex 用户级技能目录：$CODEX_HOME/skills（默认 ~/.codex/skills）。 */
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+/** 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');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+/**
+ * 默认扫描根（agent-skill-dir-map 用户级目录）。
+ * opts: { extraDirs: string[], project: boolean }
+ * extraDirs 为任意额外技能目录；project 开启时附加当前项目
+ * .agents/skills / .codex/skills。
+ */
+function defaultRoots(opts) {
+  opts = opts || {};
+  const roots = [];
+  const seen = new Set();
+  const add = (dir, label) => {
+    if (!dir) return;
+    const norm = path.resolve(dir);
+    if (seen.has(norm)) return;
+    seen.add(norm);
+    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);
+  }
+  add(codexUserDir(), 'Codex');
+  add(opencodeUserDir(), 'OpenCode');
+  if (Array.isArray(opts.extraDirs)) {
+    for (const d of opts.extraDirs) add(d, '指定目录');
+  }
+  if (opts.project) {
+    add(path.join(process.cwd(), '.agents', 'skills'), '项目 .agents/skills');
+    add(path.join(process.cwd(), '.codex', 'skills'), '项目 .codex/skills');
+  }
+  return roots;
+}
+
+/**
+ * 扫描多根目录并去重合并。
+ * 同名技能（slug）合并：记录多个来源；版本不一致时记录 conflicts。
+ */
+function scanRoots(roots) {
+  const map = new Map();
+  const scanned = [];
+  const errors = [];
+  for (const r of roots) {
+    if (!fs.existsSync(r.dir)) {
+      errors.push({ dir: r.dir, label: r.label, reason: 'missing' });
+      continue;
+    }
+    scanned.push({ dir: r.dir, label: r.label });
+    for (const s of scanSkillDir(r.dir)) {
+      const key = s.slug;
+      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 });
+        }
+      } else {
+        s.sources = [r.label];
+        s.source_dirs = [s.source_dir];
+        map.set(key, s);
+      }
+    }
+  }
+  return {
+    generated_at: new Date().toISOString(),
+    skills: Array.from(map.values()).sort((a, b) => a.slug.localeCompare(b.slug)),
+    scanned,
+    errors,
+  };
+}
+
+/** 注册表文件路径：~/.yottaskills/registry.json。 */
+function registryPath() {
+  return path.join(os.homedir(), REGISTRY_DIR_NAME, REGISTRY_FILE_NAME);
+}
+
+/** 读取注册表（不存在返回 null）。 */
+function readRegistry(filePath) {
+  const p = filePath || registryPath();
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * 增量合并：把扫描结果合并进注册表。
+ * 新增（added） / 更新（updated，版本或来源变化） / 消失（gone，上次有本次无）。
+ * 幂等：技能仍存在且版本来源一致则保持原记录不动。
+ */
+function mergeRegistry(scanResult, previous) {
+  const prev = (previous && previous.skills) ? previous.skills : {};
+  const next = {};
+  const changes = { added: [], updated: [], gone: [] };
+  const now = new Date().toISOString();
+  const seen = new Set();
+  for (const s of scanResult.skills) {
+    seen.add(s.slug);
+    const old = prev[s.slug];
+    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',
+      };
+      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,
+      };
+      if (changed) changes.updated.push(s.slug);
+    }
+  }
+  for (const key of Object.keys(prev)) {
+    if (!seen.has(key)) {
+      const was = prev[key];
+      next[key] = { ...was, last_seen: now, status: 'gone' };
+      if (was.status !== 'gone') changes.gone.push(key);
+    }
+  }
+  const registry = {
+    updated: now,
+    note: '本地技能注册表（yotta-skills --inventory 生成）。数据不出本机。',
+    skills: next,
+  };
+  return { registry, changes };
+}
+
+/** 原子写注册表（tmp + rename，防写一半损坏）。 */
+function saveRegistry(registry, filePath) {
+  const p = filePath || registryPath();
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(registry, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+/** 把注册表渲染为自包含文本表格（不依赖元呈）。 */
+function formatInventory(registry, filePath) {
+  const skills = Object.values(registry.skills || {})
+    .filter((s) => s.status !== 'gone')
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+  const lines = [];
+  lines.push('已装技能盘点（yotta-skills --inventory）');
+  lines.push('技能名/版本/功能/来源');
+  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 rp = filePath || registryPath();
+  lines.push(`共 ${skills.length} 个技能；注册表：${rp}`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  AGENT_DIRS,
+  parseFrontmatter,
+  scanSkillDir,
+  defaultRoots,
+  scanRoots,
+  registryPath,
+  readRegistry,
+  mergeRegistry,
+  saveRegistry,
+  formatInventory,
+  REGISTRY_DIR_NAME,
+  REGISTRY_FILE_NAME,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "YuanGe (元阁) — one-command installer for the whole YottaMeta skill family: list, install, and update all published yotta-* skills into any agent (npx one-shot, zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [
@@ -22,6 +22,8 @@
     "references",
     "assets",
     "bin",
+    "lib",
+    "scripts",
     "skills.json",
     "!**/__pycache__",
     "!**/*.pyc"

package/scripts/yotta-skills-mcp.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""yotta-skills-mcp.py — 元阁（yotta-skills）技能盘点 MCP server。
+
+stdio MCP server（JSON-RPC 2.0，换行分隔），把元阁技能扫描核心暴露为 MCP 工具：
+  list_installed_skills  盘点本机已装技能（读本地注册表；未生成则先扫描一次）
+  describe_skill         查看单个技能详情（slug / 版本 / 功能 / 来源）
+  reindex                强制重新扫描并更新注册表
+
+自包含原则：扫描由元阁自带核心（bin/yotta-skills.js --inventory）完成，
+不依赖任何元技能；数据只写本机 ~/.yottaskills/registry.json，不出本机。
+
+运行：python scripts/yotta-skills-mcp.py
+MCP 客户端配置：
+  {"mcpServers":{"yotta-skills":{"command":"python",
+    "args":["<绝对路径>/scripts/yotta-skills-mcp.py"]}}}
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+VERSION = "0.2.1"
+TOOL_NAME = "yotta-skills"
+CN_NAME = "元阁"
+MCP_PROTOCOL = "2025-03-26"
+SERVERS = {TOOL_NAME: {"name": TOOL_NAME, "cn": CN_NAME, "version": VERSION}}
+
+_HERE = Path(__file__).resolve().parent
+BIN_JS = (_HERE.parent / "bin" / "yotta-skills.js").resolve()
+REGISTRY_FILE = Path(os.path.expanduser("~/.yottaskills/registry.json"))
+
+
+def _tool_error(message, extra=None):
+    payload = {"error": message}
+    if extra:
+        payload.update(extra)
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": True}
+
+
+def _tool_spec(name, description, properties, required=None):
+    return {
+        "name": name,
+        "description": description,
+        "inputSchema": {
+            "type": "object",
+            "properties": properties,
+            **({"required": required} if required else {}),
+        },
+    }
+
+
+def _run_cli(args):
+    """运行元阁 CLI（Node），返回 stdout 文本；失败抛 RuntimeError。"""
+    node = shutil.which("node")
+    if not node:
+        raise RuntimeError("未找到 node 可执行文件（元阁 CLI 依赖 Node.js 18+）")
+    proc = subprocess.run(
+        [node, str(BIN_JS)] + args,
+        capture_output=True, text=True, encoding="utf-8",
+        timeout=120,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError("yotta-skills CLI 失败（exit %s）：%s" % (proc.returncode, (proc.stderr or proc.stdout).strip()[:500]))
+    return proc.stdout
+
+
+def _read_registry():
+    if not REGISTRY_FILE.is_file():
+        return None
+    try:
+        return json.loads(REGISTRY_FILE.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _ensure_registry():
+    """注册表不存在时先扫描生成一次；返回注册表 dict。"""
+    reg = _read_registry()
+    if reg is not None:
+        return reg
+    _run_cli(["--inventory"])
+    reg = _read_registry()
+    if reg is None:
+        raise RuntimeError("技能注册表生成失败（~/.yottaskills/registry.json）")
+    return reg
+
+
+def _skills_list(registry):
+    return sorted(
+        [s for s in registry.get("skills", {}).values() if s.get("status") != "gone"],
+        key=lambda s: s.get("slug", ""),
+    )
+
+
+def _tool_list(arguments):  # noqa: ARG001
+    registry = _ensure_registry()
+    skills = _skills_list(registry)
+    payload = {
+        "count": len(skills),
+        "registry": str(REGISTRY_FILE),
+        "skills": skills,
+    }
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+def _tool_describe(arguments):
+    slug = str(arguments.get("slug") or "").strip()
+    if not slug:
+        return _tool_error("describe_skill 需要 slug 参数")
+    registry = _ensure_registry()
+    skill = registry.get("skills", {}).get(slug)
+    if not skill or skill.get("status") == "gone":
+        return _tool_error("未找到技能: %s" % slug)
+    payload = {"skill": skill}
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+def _tool_reindex(arguments):  # noqa: ARG001
+    stdout = _run_cli(["--inventory", "--json"])
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as e:
+        return _tool_error("reindex 输出解析失败：%s" % e)
+    payload = {
+        "count": len(data.get("skills", [])),
+        "changes": data.get("changes"),
+        "errors": data.get("errors"),
+        "registry": str(REGISTRY_FILE),
+    }
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+TOOL_HANDLERS = {
+    "list_installed_skills": _tool_list,
+    "describe_skill": _tool_describe,
+    "reindex": _tool_reindex,
+}
+
+
+def mcp_tools():
+    return [
+        _tool_spec(
+            "list_installed_skills",
+            "盘点本机已装技能：返回技能列表（slug / 版本 / 功能一句话 / 来源）。"
+            "读本地注册表 ~/.yottaskills/registry.json；未生成则先扫描一次。"
+            "扫描由元阁自带核心完成，不依赖任何其他技能。数据不出本机。",
+            {},
+            [],
+        ),
+        _tool_spec(
+            "describe_skill",
+            "查看单个技能的详情（slug / 版本 / 功能 / 来源目录）。",
+            {"slug": {"type": "string", "description": "技能 slug（如 yotta-memory）"}},
+            ["slug"],
+        ),
+        _tool_spec(
+            "reindex",
+            "强制重新扫描所有技能目录并更新本地注册表，返回本次变化（新增 / 更新 / 消失）。",
+            {},
+            [],
+        ),
+    ]
+
+
+def handle_message(msg):
+    """处理一行 JSON-RPC 消息，返回响应 dict；通知返回 None。"""
+    if not isinstance(msg, dict) or msg.get("jsonrpc") != "2.0":
+        rid = msg.get("id") if isinstance(msg, dict) else None
+        return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32600, "message": "invalid request"}}
+    method = msg.get("method")
+    rid = msg.get("id")
+    if rid is None:  # JSON-RPC 通知（无 id）不响应
+        return None
+    if method is None:
+        return None
+    params = msg.get("params") or {}
+
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0", "id": rid,
+            "result": {
+                "protocolVersion": MCP_PROTOCOL,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": TOOL_NAME, "version": VERSION},
+            },
+        }
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": rid, "result": {}}
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": rid, "result": {"tools": mcp_tools()}}
+    if method == "tools/call":
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        handler = TOOL_HANDLERS.get(name)
+        if not handler:
+            return {
+                "jsonrpc": "2.0", "id": rid,
+                "result": {"content": [{"type": "text", "text": "未知工具: %s" % name}], "isError": True},
+            }
+        try:
+            return {"jsonrpc": "2.0", "id": rid, "result": handler(arguments)}
+        except Exception as e:  # noqa: BLE001
+            return {
+                "jsonrpc": "2.0", "id": rid,
+                "result": {"content": [{"type": "text", "text": "工具执行异常：%s" % e}], "isError": True},
+            }
+    return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": "Method not found: " + str(method)}}
+
+
+def main():
+    """stdio 主循环：读行 -> JSON-RPC -> 响应行。"""
+    try:
+        sys.stdin.reconfigure(encoding="utf-8")
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            sys.stdout.write(json.dumps(
+                {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}},
+                ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+            continue
+        resp = handle_message(msg)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()