@yottameta/yotta-skills 0.1.2 → 0.2.0

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.2",
+  "version": "0.2.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": [
@@ -22,6 +22,8 @@
     "references",
     "assets",
     "bin",
+    "lib",
+    "scripts",
     "skills.json",
     "!**/__pycache__",
     "!**/*.pyc"

package/references/install-flow.md

@@ -1,68 +1,68 @@
-# 安装器工作原理（install-flow）
-
-> 面向想了解 yotta-skills 内部机制的开发者；日常使用请读 `SKILL.md` 或中文教程
-> （`references/tutorial.md`）。
-
-## 总体流程
-
-对每个待装技能：
-
-1. 读清单（`skills.json`，默认随包；`YOTTA_SKILLS_MANIFEST` 可覆盖）；
-2. `npm pack <pkg>@<spec> --pack-destination <临时目录>`；
-3. 系统 `tar -xzf` 解压到临时目录（产物应有 `SKILL.md`）；
-4. 元信装前摘要（若引擎可用；`--skip-scan` 关闭）；
-5. 删除目标 `<dest>/<slug>` 后重新复制（跳过规则见下）；
-6. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；有失败项时退出码 1。
-
-## 复制跳过规则
-
-- 顶层跳过：`package.json` / `bin` / `node_modules` / `.git` / `__pycache__`；
-- 任意层级跳过：`.pytest_cache` / `.mypy_cache` 目录、`*.pyc` / `*.pyo` 文件。
-
-因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
-安装器自身、测试夹具与 Python 字节码缓存。
-
-## 幂等与版本判断
-
-- 读取目标 `<dest>/<slug>/SKILL.md` 的 frontmatter `version`；
-- 与清单 `version` 一致 → 跳过（幂等：第二次安装 22 个全部跳过）；
-- `--force` 强制重装；`update` 对「缺失 / 版本不一致」的技能重装。
-
-## 版本策略
-
-- 默认 range：spec = `<pkg>@<major>.x`（如 `0.x`），`npm pack` 取同 major 最新 patch；
-- `--pin`：spec = `<pkg>@<清单精确版本>`。
-
-## npm 解析（Windows）
-
-- 优先：`where.exe npm.cmd` → 读同目录 `node_modules/npm/bin/npm-cli.js` → 用 node 直接执行
-  （npm.cmd 直跑在 Windows 有 EINVAL，`cmd /c` 引号脆弱；npm-cli.js 直跑无 shell 变量坑）；
-- `--npm` / `YOTTA_SKILLS_NPM`：`.js` → node 执行；`.cmd/.bat` → 同样解析 npm-cli.js；
-  其它 → 直接执行；
-- `YOTTA_SKILLS_NPM_FLAGS` 追加到 `npm pack` 参数。
-
-## 元信装前摘要
-
-- 引擎查找：`--verify` → `YOTTA_SKILLS_VERIFY` → `<dest>/yotta-verify/scripts/yotta_verify.py`；
-- python 查找：`--python` → `YOTTA_SKILLS_PYTHON` → `python3` / `python` / `py`（win32）；
-- 执行：`python -B <engine> scan <解压目录> --json`（`-B` 禁止写 `__pycache__`，防止污染
-  引擎所在目录）；
-- 输出 verdict + counts（critical / high / medium / low / info）；DO NOT INSTALL 额外提示
-  人工复核；仅摘要、不拦截。
-
-## 退出码
-
-| 退出码 | 含义 |
-|---|---|
-| 0 | 成功（含全部跳过） |
-| 1 | 安装 / 更新存在失败项 |
-| 2 | 用法错误（未知参数 / 未知技能 / 未收录智能体） |
-| 4 | 未指定目标且当前目录未检测到项目级技能目录 |
-
-## 目标目录解析
-
-- `--dir`：直接使用（技能落在 `<dir>/<slug>`）；
-- `--agent`：查内置 17 智能体表（codex 特判 `$CODEX_HOME/skills`；opencode 特判
-  `$XDG_CONFIG_HOME/opencode/skills`；其余 `~/.<agent>/skills` 或 `~/.config/...`）；
-- 都未指定：检测当前目录是否存在项目级技能目录（`.claude/skills`、`.codex/skills`、
-  `.agents/skills` 等 17 个），存在则用之；否则退出码 4。
+# 安装器工作原理（install-flow）
+
+> 面向想了解 yotta-skills 内部机制的开发者；日常使用请读 `SKILL.md` 或中文教程
+> （`references/tutorial.md`）。
+
+## 总体流程
+
+对每个待装技能：
+
+1. 读清单（`skills.json`，默认随包；`YOTTA_SKILLS_MANIFEST` 可覆盖）；
+2. `npm pack <pkg>@<spec> --pack-destination <临时目录>`；
+3. 系统 `tar -xzf` 解压到临时目录（产物应有 `SKILL.md`）；
+4. 元信装前摘要（若引擎可用；`--skip-scan` 关闭）；
+5. 删除目标 `<dest>/<slug>` 后重新复制（跳过规则见下）；
+6. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；有失败项时退出码 1。
+
+## 复制跳过规则
+
+- 顶层跳过：`package.json` / `bin` / `node_modules` / `.git` / `__pycache__`；
+- 任意层级跳过：`.pytest_cache` / `.mypy_cache` 目录、`*.pyc` / `*.pyo` 文件。
+
+因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
+安装器自身、测试夹具与 Python 字节码缓存。
+
+## 幂等与版本判断
+
+- 读取目标 `<dest>/<slug>/SKILL.md` 的 frontmatter `version`；
+- 与清单 `version` 一致 → 跳过（幂等：第二次安装 22 个全部跳过）；
+- `--force` 强制重装；`update` 对「缺失 / 版本不一致」的技能重装。
+
+## 版本策略
+
+- 默认 range：spec = `<pkg>@<major>.x`（如 `0.x`），`npm pack` 取同 major 最新 patch；
+- `--pin`：spec = `<pkg>@<清单精确版本>`。
+
+## npm 解析（Windows）
+
+- 优先：`where.exe npm.cmd` → 读同目录 `node_modules/npm/bin/npm-cli.js` → 用 node 直接执行
+  （npm.cmd 直跑在 Windows 有 EINVAL，`cmd /c` 引号脆弱；npm-cli.js 直跑无 shell 变量坑）；
+- `--npm` / `YOTTA_SKILLS_NPM`：`.js` → node 执行；`.cmd/.bat` → 同样解析 npm-cli.js；
+  其它 → 直接执行；
+- `YOTTA_SKILLS_NPM_FLAGS` 追加到 `npm pack` 参数。
+
+## 元信装前摘要
+
+- 引擎查找：`--verify` → `YOTTA_SKILLS_VERIFY` → `<dest>/yotta-verify/scripts/yotta_verify.py`；
+- python 查找：`--python` → `YOTTA_SKILLS_PYTHON` → `python3` / `python` / `py`（win32）；
+- 执行：`python -B <engine> scan <解压目录> --json`（`-B` 禁止写 `__pycache__`，防止污染
+  引擎所在目录）；
+- 输出 verdict + counts（critical / high / medium / low / info）；DO NOT INSTALL 额外提示
+  人工复核；仅摘要、不拦截。
+
+## 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 成功（含全部跳过） |
+| 1 | 安装 / 更新存在失败项 |
+| 2 | 用法错误（未知参数 / 未知技能 / 未收录智能体） |
+| 4 | 未指定目标且当前目录未检测到项目级技能目录 |
+
+## 目标目录解析
+
+- `--dir`：直接使用（技能落在 `<dir>/<slug>`）；
+- `--agent`：查内置 17 智能体表（codex 特判 `$CODEX_HOME/skills`；opencode 特判
+  `$XDG_CONFIG_HOME/opencode/skills`；其余 `~/.<agent>/skills` 或 `~/.config/...`）；
+- 都未指定：检测当前目录是否存在项目级技能目录（`.claude/skills`、`.codex/skills`、
+  `.agents/skills` 等 17 个），存在则用之；否则退出码 4。

package/references/orchestration.md

@@ -0,0 +1,72 @@
+# 元阁编排策划（orchestration）
+
+> 元阁（yotta-skills）的**编排层**：告诉 AI 智能体「什么时候该组合哪几个元技能、组合起来比单用强在哪、怎么自动安装并按组合契约用起来」。
+> 本页是「每个场景 → 选哪几个技能 → 为什么 → 怎么自动装 + 自动用」的决策表，供 AI 智能体在接到需求时查表执行。
+> 配套：全家清单见 `skill-list.md`；安装用法见 SKILL.md「快速使用」。
+
+---
+
+## 一、技能家族全景（24 技能 / 8 家族）
+
+| 家族 | 技能（中文名 / slug） | 一句话能力 |
+|---|---|---|
+| 入口与引导 | 元引 yotta-prompt | 意图澄清，串联到对应的元阁技能 |
+| 覆盖与安装 | 元阁 yotta-skills | 全家 / 按需一键安装与更新 |
+| 呈现与表达 | 元呈 yotta-present、元真 yotta-humanize | 输出判型渲染成可复制 Markdown/纯文本；去 AI 味 |
+| 记忆与上下文 | 元忆 yotta-memory、元习 yotta-learn、元史 yotta-logs | 权限记忆、学习沉淀、历史检索 |
+| 工作流与跨会话 | 元序 yotta-workflow | 开工读状态 / 状态就近存 / 会话结束留记录 |
+| 质量与工程 | 元谨 yotta-anti-shallow、元质 yotta-code-quality、元造 yotta-skill-creator、元守 yotta-publish-guard | 防敷衍、代码评审、造技能、发布守门 |
+| 安全与信任 | 元信 yotta-verify（+元信MCP）、元审 yotta-vetter、元安 yotta-security-audit、元链 yotta-chain、元钥 yotta-secret、元鉴 yotta-triage、元察 yotta-logwatch、元情 yotta-intel、元析 yotta-recon、元测 yotta-security-testing、元盾 yotta-guardian、元安全 yotta-agent-hardening | 装前扫描、审查协议、静态检测、供应链、密钥、样本、日志、IOC、侦察、测试、拦截、加固 |
+| 分发与汇总 | 元引（串联）、元阁（安装） | —— |
+
+---
+
+## 二、组合矩阵（哪些和哪些组合，强在哪）
+
+> 原则：**单技能是零件，组合才是系统**。下面每个组合给出「一起用效果、单用差在哪、典型场景」。
+
+| 组合 | 成员（slug） | 一起用强在哪 | 单用缺什么 |
+|---|---|---|---|
+| **① 输出呈现标准** | yotta-present + yotta-humanize | 先判型渲染成规范、可复制、可复用的输出，再检测 AI 味改写，交付统一且读感自然 | 只有 yotta-present：规范但不祛 AI 味；只有 yotta-humanize：祛 AI 味但输出形态不规整 |
+| **② 长生命周期智能体** | yotta-workflow + yotta-memory + yotta-learn + yotta-logs | 开工恢复上下文、权限记忆、沉淀学习、检索历史，智能体活过会话、越用越懂你 | 缺 yotta-workflow：状态无处放；缺 yotta-memory：记忆无权限边界；缺 yotta-learn：错不沉淀；缺 yotta-logs：历史查不到 |
+| **③ 交付质量门** | yotta-anti-shallow + yotta-code-quality + yotta-publish-guard | 防敷衍、结对评审、发布前守门，交付前多层把关 | 缺 yotta-anti-shallow：容易停留表面；缺 yotta-code-quality：代码质量无人审；缺 yotta-publish-guard：发版无守门 |
+| **④ 装前安全门** | yotta-verify（或元信MCP）+ yotta-vetter + yotta-security-audit | 确定性扫描 + 协议审查 + 深检，装其他来源技能/插件/MCP 前给出可信判定 | 缺 yotta-verify：无确定性扫描；缺 yotta-vetter：无协议审查；缺 yotta-security-audit：无深检兜底 |
+| **⑤ 造技能 / 发版** | yotta-skill-creator + yotta-publish-guard | 脚手架生成合规技能目录，发布前守门 | 缺 yotta-skill-creator：造技能无模板；缺 yotta-publish-guard：造完不知能否发 |
+| **⑥ 安全事件响应** | yotta-logwatch + yotta-intel + yotta-triage + yotta-secret + yotta-chain + yotta-recon | 日志检测攻击链、提取 IOC、初筛样本、扫密钥、校验供应链、侦察资产 | 每项只管一环，单用看不到全链路 |
+| **⑦ 入口 + 安装** | yotta-prompt + yotta-skills | 元引澄清需求串联到对应技能，元阁按场景把组合一口气装好 | 缺 yotta-prompt：需求模糊时不知该用哪个；缺 yotta-skills：要一个个装 |
+
+---
+
+## 三、场景 → 组合映射（AI 接到需求时查表）
+
+| 用户场景（触发词） | 该组合 | 自动装 / 自动用动作 |
+|---|---|---|
+| 「让 AI 长期帮我做项目 / 别忘了我 / 跨会话」 | ② 长生命周期 | 装 yotta-workflow yotta-memory yotta-learn yotta-logs；开工恢复上下文、状态就近存、会话结束留记录 |
+| 「帮我写/润色，让输出规范、别 AI 味」 | ① 输出呈现标准 | 装 yotta-present yotta-humanize；默认先判型渲染，检测 AI 味再改写 |
+| 「检查这段代码/报告质量，别糊弄」 | ③ 交付质量门 | 装 yotta-anti-shallow yotta-code-quality yotta-publish-guard；按对应协议执行 |
+| 「我要装一个其他来源技能/插件/MCP」 | ④ 装前安全门 | 装 yotta-verify(+MCP) yotta-vetter yotta-security-audit；装前必扫 |
+| 「我要造一个新 skill 并发布」 | ⑤ 造技能/发版 | 装 yotta-skill-creator yotta-publish-guard；生成 + 守门 |
+| 「我怀疑日志/资产有问题」 | ⑥ 安全事件响应 | 装 yotta-logwatch yotta-intel yotta-triage yotta-secret yotta-chain yotta-recon；按需调用 |
+| 「不知道怎么说 / 一堆技能该用哪个」 | ⑦ 入口+安装 | 装 yotta-prompt yotta-skills；元引澄清→串联→元阁按组合装 |
+
+> 组合不是死板套餐：命中「入口+安装」或「输出呈现标准」这类**默认契约**时，AI 应自动应用，不需用户逐次说；命中安全/发版这类**高风险动作**时，AI 应装技能并给出执行方案，由用户确认后执行。
+
+---
+
+## 四、AI 自动安装与组合规则（金标准）
+
+1. **查表**：接到需求，先在「场景→组合映射」里定位命中组合。
+2. **查已装**：检查当前智能体的技能目录是否存在对应 `<slug>/SKILL.md`；存在即已装，缺失即待装。
+3. **自动装**：缺失的技能用
+   `npx -y @yottameta/yotta-skills install <slug>... [--agent <name> | --dir <path>]`
+   一次性补齐（只装组合所需，不装全家，避免过度安装）。
+4. **自动用（默认契约）**：命中的是「输出呈现标准」「长生命周期」这类**默认行为契约**时，装完即按组合契约自动调用（如：所有输出先过 yotta-present；开工先恢复上下文 + 读状态文件）。不需用户逐次提醒。
+5. **用户触发（高风险）**：命中「安全 / 发版 / 造技能」这类**高风险或目的不明**时，AI 装技能 + 给出执行方案，**先征询用户确认**再执行；拿不准就当未装，给出安装命令。
+6. **边界**：不 `-g` 全局安装；不向未指定位置写文件；拿不准某技能是否已装 → 视为未装并给提示；网络不可用 → 明确报错，不伪造结果。
+
+---
+
+## 五、安装与入口
+
+- 安装 CLI 用法见 `SKILL.md`「快速使用」；全家清单见 `skill-list.md`。
+- 版本策略 / 元信装前摘要 / 支持的智能体 / 环境变量 同 SKILL.md。

package/references/skill-list.md

@@ -1,40 +1,40 @@
-# 全家技能清单（22 个）
-
-> 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
-> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-08-29。
-
-| slug | 中文名 | npm 包 | 清单版本 | 说明 |
-|---|---|---|---|---|
-| `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.3.4 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
-| `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.3.4 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
-| `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.2.6 | 跨会话/跨项目通用工作流协议（状态就近存 .workflow） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.8.4 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
-| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.1.4 | 学习闭环 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
-| `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.1.7 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
-| `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.1.5 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
-| `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.5 | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |
-| `yotta-guardian` | 元盾 | `@yottameta/yotta-guardian` | 0.1.2 | 跨智能体危险调用拦截护栏：确定性规则 + 可插拔意图验证 |
-| `yotta-humanize` | 元真 | `@yottameta/yotta-humanize` | 0.1.2 | 去 AI 味中文写作编辑：检测器引擎 |
-| `yotta-logs` | 元史 | `@yottameta/yotta-logs` | 0.2.2 | 跨智能体历史会话 / 记忆日志检索 |
-| `yotta-security-testing` | 元测 | `@yottameta/yotta-security-testing` | 0.1.0 | 有纪律的 AI 安全测试方法论 + Scope Guard 五道防线 |
-| `yotta-agent-hardening` | 元安全 | `@yottameta/yotta-agent-hardening` | 0.1.0 | 防御向 AI 智能体自身安全加固（配置面静态扫描三域） |
-| `yotta-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.0 | 工坊「造」：端到端造技能脚手架 |
-| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.1.1 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
-| `yotta-logwatch` | 元察 | `@yottameta/yotta-logwatch` | 0.2.7 | 安全日志分析检测引擎（攻击链识别/告警聚合） |
-| `yotta-intel` | 元情 | `@yottameta/yotta-intel` | 0.1.1 | 威胁情报 IOC 提取与规范化引擎（STIX-lite） |
-| `yotta-secret` | 元钥 | `@yottameta/yotta-secret` | 0.1.2 | 密钥 / 凭据泄露源头扫描引擎 |
-| `yotta-chain` | 元链 | `@yottameta/yotta-chain` | 0.1.2 | 供应链依赖校验引擎 |
-| `yotta-triage` | 元鉴 | `@yottameta/yotta-triage` | 0.1.1 | 恶意样本静态初筛引擎（哈希/熵/字符串/PE-ELF） |
-| `yotta-prompt` | 元引 | `@yottameta/yotta-prompt` | 0.1.1 | 意图澄清 + 生态入口（常驻注入，map 串联元阁全家） |
-| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.1.1 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
-
-## 家族分布
-
-- 安全与护栏（12）：元安 / 元审 / 元析 / 元盾 / 元测 / 元安全 / 元察 / 元情 / 元钥 / 元链 / 元鉴 / 元信
-- 质量与工程（4）：元谨 / 元质 / 元造 / 元守
-- 记忆与上下文（3）：元忆 / 元史 / 元习
-- 写作与表达（1）：元真
-- 工作流（1）：元序
-- 入口与引导（1）：元引
-
-合计 22 个已发布技能；本安装器自身（yotta-skills / 元阁）归「分发与安装」家族。
+# 全家技能清单（22 个）
+
+> 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
+> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-08-29。
+
+| slug | 中文名 | npm 包 | 清单版本 | 说明 |
+|---|---|---|---|---|
+| `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.3.4 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
+| `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.3.4 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
+| `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.2.6 | 跨会话/跨项目通用工作流协议（状态就近存） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.8.4 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.1.4 | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
+| `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.1.7 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
+| `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.1.5 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
+| `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.5 | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |
+| `yotta-guardian` | 元盾 | `@yottameta/yotta-guardian` | 0.1.2 | 跨智能体危险调用拦截护栏：确定性规则 + 可插拔意图验证 |
+| `yotta-humanize` | 元真 | `@yottameta/yotta-humanize` | 0.1.2 | 去 AI 味中文写作编辑：检测器引擎 |
+| `yotta-logs` | 元史 | `@yottameta/yotta-logs` | 0.2.2 | 跨智能体历史会话 / 记忆日志检索 |
+| `yotta-security-testing` | 元测 | `@yottameta/yotta-security-testing` | 0.1.0 | 有纪律的 AI 安全测试方法论 + Scope Guard 五道防线 |
+| `yotta-agent-hardening` | 元安全 | `@yottameta/yotta-agent-hardening` | 0.1.0 | 防御向 AI 智能体自身安全加固（配置面静态扫描三域） |
+| `yotta-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.0 | 工坊「造」：端到端造技能脚手架 |
+| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.1.1 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
+| `yotta-logwatch` | 元察 | `@yottameta/yotta-logwatch` | 0.2.7 | 安全日志分析检测引擎（攻击链识别/告警聚合） |
+| `yotta-intel` | 元情 | `@yottameta/yotta-intel` | 0.1.1 | 威胁情报 IOC 提取与规范化引擎（STIX-lite） |
+| `yotta-secret` | 元钥 | `@yottameta/yotta-secret` | 0.1.2 | 密钥 / 凭据泄露源头扫描引擎 |
+| `yotta-chain` | 元链 | `@yottameta/yotta-chain` | 0.1.2 | 供应链依赖校验引擎 |
+| `yotta-triage` | 元鉴 | `@yottameta/yotta-triage` | 0.1.1 | 恶意样本静态初筛引擎（哈希/熵/字符串/PE-ELF） |
+| `yotta-prompt` | 元引 | `@yottameta/yotta-prompt` | 0.1.1 | 意图澄清 + 生态入口（常驻注入，map 串联元阁全家） |
+| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.1.1 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
+
+## 家族分布
+
+- 安全与护栏（12）：元安 / 元审 / 元析 / 元盾 / 元测 / 元安全 / 元察 / 元情 / 元钥 / 元链 / 元鉴 / 元信
+- 质量与工程（4）：元谨 / 元质 / 元造 / 元守
+- 记忆与上下文（3）：元忆 / 元史 / 元习
+- 写作与表达（1）：元真
+- 工作流（1）：元序
+- 入口与引导（1）：元引
+
+合计 22 个已发布技能；本安装器自身（yotta-skills / 元阁）归「分发与安装」家族。