@yottameta/yotta-skills 0.1.0

package/bin/yotta-skills.js

@@ -0,0 +1,484 @@
+#!/usr/bin/env node
+/**
+ * yotta-skills（元阁）—— 全家技能一键安装 CLI（YottaSkills 合集）
+ *
+ * 用法:
+ *   npx -y @yottameta/yotta-skills --list                 # 列出全家技能 + 版本 + 说明
+ *   npx -y @yottameta/yotta-skills install --agent <name> # 装全家到智能体默认用户级目录（推荐）
+ *   npx -y @yottameta/yotta-skills install --dir <path>   # 装全家到指定目录
+ *   npx -y @yottameta/yotta-skills install <skill> --dir <path>  # 装单个技能
+ *   npx -y @yottameta/yotta-skills update --agent <name>  # 增量更新已装技能（补齐缺失/版本不一致）
+ *   npx -y @yottameta/yotta-skills --dry-run              # 预览将安装清单（不联网、不改动）
+ *
+ * 版本策略：清单锁定 `major.x`（不锁死 patch，维护性更新随最新）；--pin 锁死精确版本。
+ * 依赖：Node.js 18+；npm（pack）；系统 tar（解压）；元信 scan 可选（装了 yotta-verify 自动启用）。
+ * 边界：只做「清单 + 下载 + 落位 + 汇总」；不内置任何技能本体；不 -g 污染。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.join(__dirname, '..');
+let VERSION = '0.1.0';
+try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
+
+function loadManifest() {
+  const file = process.env.YOTTA_SKILLS_MANIFEST || path.join(PKG_ROOT, 'skills.json');
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    die('无法读取技能清单: ' + file + '（' + e.message + '）');
+  }
+  const list = Array.isArray(data) ? data : data.skills;
+  if (!Array.isArray(list) || list.length === 0) die('技能清单为空: ' + file);
+  for (const s of list) {
+    for (const f of ['slug', 'name', 'pkg', 'version']) {
+      if (!s[f]) die('技能清单字段缺失 ' + f + '：' + JSON.stringify(s));
+    }
+  }
+  return list;
+}
+
+const MANIFEST = loadManifest();
+
+// 智能体 -> 用户级默认技能目录（与各技能 install.js 同源；.agents/skills 并非通用目录）
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$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: ['.config/opencode/skills'] }, // 特判：$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'] },
+};
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, '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);
+}
+
+// ── 工具函数 ───────────────────────────────────────────────────────────────
+function die(msg, code) {
+  process.stderr.write('错误：' + msg + '\n');
+  process.exit(code === undefined ? 2 : code);
+}
+function out(s) { process.stdout.write(s + '\n'); }
+
+function tarBin() { return 'tar'; }
+
+// 解析 npm 调用方式（Windows 的 .cmd 不能直接 spawn：EINVAL；cmd /c 引号脆弱）。
+// 最优：定位 npm.cmd -> 读内容 -> 提取 node_modules/npm/bin/npm-cli.js -> 用 node 直接执行。
+// 兼容：--npm / YOTTA_SKILLS_NPM 可指向 .js（node 执行）、.cmd（同样解析）、或可执行文件。
+// 标准 npm 安装器布局：npm-cli.js 恒在 npm.cmd 同目录 node_modules/npm/bin/ 下（不解析 cmd 脚本内容，
+// 避免 %dp0% 等 cmd 变量干扰；找不到则返回 null 走 shell 回退）
+function npmCliFromCmd(cmdFile) {
+  try {
+    const p = path.join(path.dirname(cmdFile), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    return fs.existsSync(p) ? p : null;
+  } catch (_) { return null; }
+}
+function resolveNpm(opts) {
+  const custom = opts.npm || process.env.YOTTA_SKILLS_NPM;
+  if (custom) {
+    if (/\.js$/i.test(custom)) return { bin: process.execPath, prefix: [custom], shell: false };
+    if (/\.(cmd|bat)$/i.test(custom)) {
+      const cli = npmCliFromCmd(custom);
+      if (cli) return { bin: process.execPath, prefix: [cli], shell: false };
+      return { bin: custom, prefix: [], shell: true };
+    }
+    return { bin: custom, prefix: [], shell: false };
+  }
+  if (process.platform === 'win32') {
+    try {
+      const w = spawnSync('where.exe', ['npm.cmd'], { encoding: 'utf8', timeout: 15000 });
+      const line = (w.stdout || '').split(/\r?\n/).map(s => s.trim()).find(Boolean);
+      if (line) {
+        const cli = npmCliFromCmd(line);
+        if (cli) return { bin: process.execPath, prefix: [cli], shell: false };
+      }
+    } catch (_) { /* fallthrough */ }
+    return { bin: 'npm.cmd', prefix: [], shell: true };
+  }
+  return { bin: 'npm', prefix: [], shell: false };
+}
+
+
+function parseArgs(argv) {
+  const opts = {
+    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: [],
+  };
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const take = (name) => { const v = argv[i + 1]; if (v === undefined || v.startsWith('--')) die(name + ' 缺少参数值'); i++; return v; };
+    if (a === '--list' || a === '-l') opts.list = true;
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--pin') opts.pin = true;
+    else if (a === '--skip-scan') opts.skipScan = true;
+    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 === '--agent') opts.agent = take('--agent').toLowerCase();
+    else if (a === '--dir') opts.dir = take('--dir');
+    else if (a === '--npm') opts.npm = take('--npm');
+    else if (a === '--python') opts.python = take('--python');
+    else if (a === '--verify') opts.verify = take('--verify');
+    else if (a.startsWith('-')) die('未知参数: ' + a);
+    else positionals.push(a);
+  }
+  // 命令解析：install / update，其余位置参数 = 技能 slug（可多个）
+  for (const p of positionals) {
+    if (p === 'install' || p === 'update') {
+      if (opts.command && opts.command !== p) die('命令冲突：' + opts.command + ' 与 ' + p);
+      opts.command = p;
+    } else {
+      opts.rest.push(p);
+    }
+  }
+  // 直接给 slug 且无命令 → 视为 install 单个/多个
+  if (!opts.command && opts.rest.length > 0) opts.command = 'install';
+  opts.skills = opts.rest.map(s => s.toLowerCase());
+  return opts;
+}
+
+function skillRange(s) {
+  const major = String(s.version).split('.')[0];
+  return major + '.x';
+}
+function specOf(s, pin) {
+  return s.pkg + '@' + (pin ? s.version : skillRange(s));
+}
+function findSkill(slug) {
+  return MANIFEST.find(s => s.slug === slug || s.pkg === slug || s.pkg.replace('@yottameta/', '') === slug);
+}
+function selectSkills(opts) {
+  if (opts.skills.length === 0) return MANIFEST;
+  const picked = [];
+  for (const slug of opts.skills) {
+    const s = findSkill(slug);
+    if (!s) die('未知技能: ' + slug + '（可用: yotta-skills --list）');
+    picked.push(s);
+  }
+  return picked;
+}
+
+function readInstalledVersion(dir) {
+  const f = path.join(dir, 'SKILL.md');
+  try {
+    const text = fs.readFileSync(f, 'utf8');
+    const m = text.match(/^version:\s*([0-9]+\.[0-9]+\.[0-9]+)/m);
+    return m ? m[1] : null;
+  } catch (_) { return null; }
+}
+
+function shouldSkip(name, isFile) {
+  if (name === '__pycache__' || name === '.pytest_cache' || name === '.mypy_cache') return true;
+  if (isFile && (name.endsWith('.pyc') || name.endsWith('.pyo'))) return true;
+  return false;
+}
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name) || shouldSkip(entry.name, entry.isFile())) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function resolveTargetDir(opts) {
+  if (opts.dir) return path.resolve(opts.dir);
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
+    if (!info) die('未收录智能体: ' + opts.agent + '。可用: ' + Object.keys(AGENT_DIRS).join(', ') + '；或改用 --dir <路径>。');
+    return resolveUserDir(info.dirs[0]);
+  }
+  return null; // 未指定目标（项目级检测由调用方处理）
+}
+
+function detectProjectDir() {
+  const PROJECT_DIRS = [
+    '.claude/skills', '.cursor/skills', '.codex/skills', '.config/goose/skills',
+    '.config/agents/skills', '.opencode/skills', '.codeium/windsurf/skills',
+    '.workbuddy/skills', '.kiro/skills', '.traecli/skills', '.gemini/skills',
+    '.trae-cn/skills', '.qwen/skills', '.comate/skills', '.codebuddy/skills',
+    '.kimi/skills', '.agents/skills',
+  ];
+  for (const d of PROJECT_DIRS) if (fs.existsSync(d)) return path.resolve(d);
+  return null;
+}
+
+// ── 元信 scan（若可用）─────────────────────────────────────────────────────
+function findVerifyEngine(dest, opts) {
+  const cands = [];
+  if (opts.verify) cands.push(path.resolve(opts.verify));
+  if (process.env.YOTTA_SKILLS_VERIFY) cands.push(path.resolve(process.env.YOTTA_SKILLS_VERIFY));
+  if (dest) cands.push(path.join(dest, 'yotta-verify', 'scripts', 'yotta_verify.py'));
+  for (const c of cands) {
+    try { if (fs.statSync(c).isFile()) return c; } catch (_) { /* next */ }
+  }
+  return null;
+}
+function findPython(opts) {
+  const cands = [];
+  if (opts.python) cands.push(opts.python);
+  if (process.env.YOTTA_SKILLS_PYTHON) cands.push(process.env.YOTTA_SKILLS_PYTHON);
+  cands.push('python3', 'python');
+  if (process.platform === 'win32') cands.push('py');
+  for (const c of cands) {
+    try {
+      const r = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 10000 });
+      if (r.status === 0) return c;
+    } catch (_) { /* next */ }
+  }
+  return null;
+}
+function runScan(engine, skillDir) {
+  const python = findPython({});
+  if (!python) return { ok: false, note: '未找到 python（元信 scan 需要 Python 3.8+）' };
+  // -B：禁止 Python 写 __pycache__（否则会在引擎所在目录（可能是已装技能）留下 .pyc 污染）
+  const r = spawnSync(python, ['-B', engine, 'scan', skillDir, '--json'], { encoding: 'utf8', timeout: 60000 });
+  if (r.status === null) return { ok: false, note: '元信 scan 执行失败' };
+  try {
+    const j = JSON.parse(r.stdout);
+    const c = j.counts || {};
+    return { ok: true, verdict: j.verdict, counts: c };
+  } catch (_) {
+    return { ok: false, note: '元信 scan 输出无法解析' };
+  }
+}
+
+// ── 安装 ───────────────────────────────────────────────────────────────────
+function runNpmPack(skill, opts, packDir) {
+  const spec = specOf(skill, opts.pin);
+  const args = ['pack', spec, '--pack-destination', packDir];
+  const flags = (process.env.YOTTA_SKILLS_NPM_FLAGS || '').trim();
+  if (flags) args.push(...flags.split(/\s+/));
+  const npm = resolveNpm(opts);
+  const r = spawnSync(npm.bin, [...npm.prefix, ...args], { encoding: 'utf8', timeout: 180000, maxBuffer: 64 * 1024 * 1024, shell: npm.shell });
+  if (r.status !== 0) {
+    const raw = (r.stderr || r.stdout || 'npm pack 失败').trim();
+    const ll = raw.split(/\r?\n/).filter(Boolean);
+    const brief = ll.slice(-4).join(' | ');
+    return { error: brief || 'npm pack 失败', detail: raw };
+  }
+  const lines = (r.stdout || '').split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  let tarball = null;
+  for (const l of lines) if (/\.tgz$/.test(l)) tarball = l;
+  if (!tarball) {
+    try {
+      const found = fs.readdirSync(packDir).filter(f => f.endsWith('.tgz'));
+      if (found.length === 1) tarball = found[0];
+    } catch (_) { /* ignore */ }
+  }
+  if (!tarball) return { error: '未找到 npm pack 产物（' + spec + '）' };
+  const vm = String(tarball).match(/-([0-9]+\.[0-9]+\.[0-9]+)\.tgz$/);
+  return { tarball: path.join(packDir, tarball), resolved: vm ? vm[1] : null, spec };
+}
+
+function extractTarball(tarball, extractDir) {
+  const r = spawnSync(tarBin(), ['-xzf', tarball, '-C', extractDir], { encoding: 'utf8', timeout: 120000 });
+  if (r.status !== 0) return { error: (r.stderr || r.stdout || 'tar 解压失败').trim().split('\n').pop() };
+  const pkgDir = path.join(extractDir, 'package');
+  if (!fs.existsSync(path.join(pkgDir, 'SKILL.md'))) return { error: '解压产物缺少 SKILL.md（' + tarball + '）' };
+  return { pkgDir };
+}
+
+const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '__pycache__']);
+
+function installOne(skill, dest, opts) {
+  const target = path.join(dest, skill.slug);
+  const existing = readInstalledVersion(target);
+  if (!opts.force && existing === skill.version) {
+    return { skill, status: 'skip', version: existing, note: '已是最新' };
+  }
+  let tmp;
+  try {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'yotta-skills-'));
+    const packDir = path.join(tmp, 'pack');
+    fs.mkdirSync(packDir, { recursive: true });
+    const packed = runNpmPack(skill, opts, packDir);
+    if (packed.error) {
+      if (packed.detail) out('    ' + packed.detail.split(/\r?\n/).filter(Boolean).slice(-12).join('\n    '));
+      return { skill, status: 'fail', version: null, note: packed.error };
+    }
+    const extractDir = path.join(tmp, 'extract');
+    fs.mkdirSync(extractDir, { recursive: true });
+    const extracted = extractTarball(packed.tarball, extractDir);
+    if (extracted.error) return { skill, status: 'fail', version: packed.resolved, note: extracted.error };
+
+    // 元信 scan（若可用）：装前摘要，不拦截
+    if (!opts.skipScan) {
+      const engine = findVerifyEngine(dest, opts);
+      if (engine) {
+        const scan = runScan(engine, extracted.pkgDir);
+        if (scan.ok) {
+          const c = scan.counts;
+          const line = 'critical ' + (c.critical || 0) + ' / high ' + (c.high || 0) + ' / medium ' + (c.medium || 0) +
+                       ' / low ' + (c.low || 0) + ' / info ' + (c.info || 0);
+          out('  元信 scan: ' + scan.verdict + '（' + line + '）');
+          if (scan.verdict && /DO NOT INSTALL/.test(scan.verdict)) out('  ⚠ 元信 verdict 为 DO NOT INSTALL，请人工复核后再使用。');
+        } else {
+          out('  元信 scan: ' + scan.note);
+        }
+      }
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(extracted.pkgDir, target, COPY_SKIP);
+    return { skill, status: 'ok', version: packed.resolved || skill.version, note: null };
+  } catch (e) {
+    return { skill, status: 'fail', version: null, note: e.message };
+  } finally {
+    if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function runInstall(opts, dest) {
+  const skills = selectSkills(opts);
+  out('yotta-skills（元阁）v' + VERSION + ' —— 安装 ' + skills.length + ' 个技能 -> ' + dest);
+  out('版本策略: ' + (opts.pin ? 'pin（锁死清单精确版本）' : 'range（' + skillRange(skills[0]) + '，跟随最新 patch；--pin 锁死）'));
+  const results = [];
+  let failed = 0;
+  for (const s of skills) {
+    const r = installOne(s, dest, opts);
+    results.push(r);
+    if (r.status === 'ok') out('  ✔ ' + s.slug.padEnd(22) + s.name + '  -> ' + (r.version || '?'));
+    else if (r.status === 'skip') out('  - ' + s.slug.padEnd(22) + s.name + '  （' + r.note + '，v' + r.version + '）');
+    else { failed++; out('  ✘ ' + s.slug.padEnd(22) + s.name + '  失败: ' + r.note); }
+  }
+  const ok = results.filter(r => r.status === 'ok').length;
+  const skip = results.filter(r => r.status === 'skip').length;
+  out('');
+  out('汇总: 成功 ' + ok + ' / 跳过(已是最新) ' + skip + ' / 失败 ' + failed + '（共 ' + results.length + '）');
+  if (failed > 0) process.exitCode = 1;
+}
+
+function runUpdate(opts, dest) {
+  const skills = selectSkills(opts);
+  out('yotta-skills（元阁）v' + VERSION + ' —— 增量更新 -> ' + dest);
+  const results = [];
+  let failed = 0;
+  for (const s of skills) {
+    const existing = readInstalledVersion(path.join(dest, s.slug));
+    if (existing === s.version) {
+      out('  - ' + s.slug.padEnd(22) + s.name + '  （已是最新，v' + existing + '）');
+      results.push({ skill: s, status: 'skip', version: existing });
+      continue;
+    }
+    const r = installOne(s, dest, opts);
+    results.push(r);
+    if (r.status === 'ok') out('  ✔ ' + s.slug.padEnd(22) + s.name + '  -> ' + (r.version || '?') + (existing ? '（原 v' + existing + '）' : '（新装）'));
+    else if (r.status === 'skip') out('  - ' + s.slug.padEnd(22) + s.name + '  （' + r.note + '）');
+    else { failed++; out('  ✘ ' + s.slug.padEnd(22) + s.name + '  失败: ' + r.note); }
+  }
+  const ok = results.filter(r => r.status === 'ok').length;
+  const skip = results.filter(r => r.status === 'skip').length;
+  out('');
+  out('汇总: 更新 ' + ok + ' / 已是最新 ' + skip + ' / 失败 ' + failed);
+  if (failed > 0) process.exitCode = 1;
+}
+
+// ── 展示 ───────────────────────────────────────────────────────────────────
+function printList(opts) {
+  const skills = opts.skills.length ? selectSkills(opts) : MANIFEST;
+  out('yotta-skills（元阁）v' + VERSION + ' —— 全家技能清单（' + skills.length + ' 个）');
+  out('版本策略: ' + (opts.pin ? 'pin（精确锁定）' : 'range（' + skillRange(skills[0]) + ' 起，跟随最新 patch；--pin 锁死）'));
+  out('');
+  for (const s of skills) {
+    out('  ' + s.slug.padEnd(22) + s.name.padEnd(5) + ' ' + specOf(s, opts.pin).padEnd(52) + ' ' + s.version + '  ' + s.desc);
+  }
+  out('');
+  out('安装: yotta-skills install --agent <name> 或 --dir <path>；预览: --dry-run；更新: update。');
+}
+
+function printHelp() {
+  out('yotta-skills（元阁）v' + VERSION + ' —— npx 一次装齐全家技能');
+  out('');
+  out('用法:');
+  out('  yotta-skills --list                 列出全家技能 + 版本 + 说明');
+  out('  yotta-skills install --agent <name> 装全家到智能体默认用户级目录（推荐）');
+  out('  yotta-skills install --dir <path>   装全家到指定目录');
+  out('  yotta-skills install <skill> --dir <path>  装单个技能（可多个）');
+  out('  yotta-skills update --agent <name>  增量更新已装技能（补齐缺失 / 版本不一致）');
+  out('  yotta-skills --dry-run              预览将安装清单（不联网、不改动）');
+  out('');
+  out('选项:');
+  out('  --agent <name>   智能体键名（--list 可查看；未知智能体请用 --dir）');
+  out('  --dir <path>     目标技能目录（技能会装到 <path>/<slug>）');
+  out('  --pin            锁死清单精确版本（默认 range：跟随同 major 最新 patch）');
+  out('  --force          已是最新也重装');
+  out('  --skip-scan      跳过元信装前 scan（装了 yotta-verify 自动启用）');
+  out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
+  out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
+  out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
+  out('  -h, --help       帮助');
+  out('  -v, --version    版本');
+  out('');
+  out('支持智能体: ' + Object.keys(AGENT_DIRS).join(', '));
+  out('依赖: Node.js 18+ / npm / 系统 tar；环境变量 YOTTA_SKILLS_NPM / YOTTA_SKILLS_PYTHON / YOTTA_SKILLS_VERIFY / YOTTA_SKILLS_NPM_FLAGS 可覆盖。');
+}
+
+// ── 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; }
+
+  const command = opts.command || 'install';
+  let dest = resolveTargetDir(opts);
+  if (!dest && !opts.dryRun) dest = detectProjectDir();
+  if (!dest && command === 'install' && !opts.dryRun) {
+    die('未指定目标：请用 --agent <name> 或 --dir <path>（当前目录未检测到项目级技能目录）。', 4);
+  }
+
+  if (opts.dryRun) {
+    const skills = selectSkills(opts);
+    out('yotta-skills（元阁）v' + VERSION + ' —— dry-run（' + command + '，' + skills.length + ' 个技能）');
+    out('目标: ' + (dest || '未指定（将检测项目级目录）'));
+    out('版本策略: ' + (opts.pin ? 'pin（锁死）' : 'range（' + skillRange(skills[0]) + '）'));
+    out('');
+    for (const s of skills) {
+      const tag = command === 'update' ? '将检查/更新' : '将安装';
+      out('  [' + tag + '] ' + s.slug.padEnd(22) + s.name.padEnd(5) + ' ' + specOf(s, opts.pin).padEnd(52) + ' ' + s.version + '  ' + s.desc);
+    }
+    out('');
+    out('（dry-run 未执行任何下载/写入）');
+    return;
+  }
+
+  if (command === 'update') runUpdate(opts, dest);
+  else runInstall(opts, dest);
+}
+
+main();

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-skills（元阁）多智能体安装脚本（YottaSkills）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-skills"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@yottameta/yotta-skills",
+  "version": "0.1.0",
+  "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": [
+    "agent-skills",
+    "yotta-skills",
+    "yottaskills",
+    "installer",
+    "bundle",
+    "skill-family"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "install.sh",
+    "references",
+    "assets",
+    "bin",
+    "skills.json",
+    "!**/__pycache__",
+    "!**/*.pyc"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YottaMeta/yotta-skills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-skills": "bin/yotta-skills.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"**/*.test.js\""
+  }
+}