@yottameta/yotta-skills-plugin 0.7.2 → 0.8.0

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.7.2",
+      "version": "0.8.0",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.7.2",
+      "version": "0.8.0",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills-plugin",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "YuanGe (元阁) — orchestration and routing for the YottaMeta skill family, packaged as a YottaMeta Agent Plugin.",
   "license": "MIT",
   "keywords": [

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "yotta-skills",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "author": {
     "name": "YottaMeta",

package/skills/yotta-skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-skills
-version: 0.7.2
-description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工可先跑 --reindex 与 update --check（联网只读检查更新）；自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / update --check（只读检查）/ update --auto（家族自动更新）/ --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能；装前摘要仅供参考，安装决策由用户确认。
+version: 0.8.0
+description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工可先跑 --reindex 与 update --check（联网只读检查更新）；自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / update --check（只读检查）/ update --auto（家族自动更新）/ --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -132,9 +132,9 @@ npx -y @yottameta/yotta-skills --reindex
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
-| `--skip-scan` | 跳过元信装前摘要（装了 yotta-verify 时默认自动启用） |
+| `--skip-scan` | 人工应急路径：跳过元信门禁并标记 `explicit-unverified`；不得用于 `update --auto` |
 | `--npm <path>` | 指定 npm 可执行文件 |
-| `--python <path>` | 指定 python 可执行文件（元信摘要用） |
+| `--python <path>` | 指定 python 可执行文件（元信 scan 用） |
 | `--verify <path>` | 指定 yotta_verify.py 路径 |
 | `-h, --help` / `-v, --version` | 帮助 / 版本 |
 
@@ -235,12 +235,19 @@ npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄" --json
 - 是否「已是最新」由目标目录 `<slug>/SKILL.md` 的 frontmatter `version` 与清单比对，
   一致即跳过（幂等）。
 
-## 元信装前摘要
+## 元信装前门禁
+
+家族安装默认执行装前扫描。若本机没有元信（yotta-verify），元阁先按 `skills.json`
+安装元信自身，再扫描待装技能。安装前会先读取包内 manifest、校验身份，再进入元信门禁：
+
+- `SAFE TO INSTALL`：继续安装；
+- `INSTALL WITH CAUTION` / `REVIEW REQUIRED`：继续安装，但显示风险并写入证据；
+- `DO NOT INSTALL` 或扫描失败：阻断，不替换旧版本。
 
-安装时若检测到元信（yotta-verify）引擎，会对每个待装技能先跑一次装前摘要并打印 verdict
-与计数——仅提示、不拦截；verdict 为 DO NOT INSTALL 时会额外提示人工复核。
 引擎查找顺序：`--verify` 指定路径 → 环境变量 `YOTTA_SKILLS_VERIFY` → 目标目录下已装的
-`yotta-verify/scripts/yotta_verify.py`。可用 `--skip-scan` 关闭。
+`yotta-verify/scripts/yotta_verify.py`。`--skip-scan` 只保留为人工应急路径，使用时输出
+`explicit-unverified` 并写入 `~/.yottaskills/install-log.jsonl`；`update --auto` 不会使用
+该开关。
 
 ## 支持智能体
 
@@ -254,7 +261,7 @@ npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄" --json
 |---|---|
 | `YOTTA_SKILLS_NPM` | 指定 npm 可执行文件（同 `--npm`） |
 | `YOTTA_SKILLS_NPM_FLAGS` | 追加传给 `npm pack` 的参数（按空白拆分，如 `--registry=...`） |
-| `YOTTA_SKILLS_PYTHON` | 指定 python 可执行文件（元信摘要用，同 `--python`） |
+| `YOTTA_SKILLS_PYTHON` | 指定 python 可执行文件（元信 scan 用，同 `--python`） |
 | `YOTTA_SKILLS_VERIFY` | 指定 yotta_verify.py 路径（同 `--verify`） |
 | `YOTTA_SKILLS_MANIFEST` | 指定技能清单 JSON 路径（默认随包 skills.json） |
 

package/skills/yotta-skills/bin/yotta-skills.js

@@ -24,6 +24,9 @@ const os = require('os');
 const { spawnSync } = require('child_process');
 const http = require('http');
 const https = require('https');
+const evidenceLib = require('../lib/install-evidence');
+const gateLib = require('../lib/verify-gate');
+const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
 let VERSION = '0.2.1';
@@ -343,19 +346,27 @@ async function runUpdateAuto(opts, dest) {
   }
   out('');
   out('检测到 ' + r.updates + ' 个家族技能可更新，开始自动更新（安装管线，含装前安全扫描）：');
-  var ok = 0, failed2 = 0;
+  var ok = 0, failed2 = 0, autoExitCode = 0;
   for (var i = 0; i < r.rows.length; i++) {
     var row = r.rows[i];
     if (!row.hasUpdate) continue;
-    var res = installOne(Object.assign({}, row.family, { version: row.latest }), dest, Object.assign({}, opts, { force: true, pin: true }));
+    var res = installOne(
+      Object.assign({}, row.family, { version: row.latest }),
+      dest,
+      Object.assign({}, opts, { force: true, pin: true, skipScan: false }),
+    );
     if (res.status === 'ok') ok++;
     else if (res.status === 'skip') ok++;
-    else failed2++;
+    else {
+      failed2++;
+      autoExitCode = Math.max(autoExitCode, res.exitCode || 1);
+      out('  ✘ ' + row.slug + '  失败: ' + res.note);
+    }
   }
   out('');
   out('自动更新汇总: 成功 ' + ok + ' / 失败 ' + failed2);
-  maybeAutoReindex(opts, dest);
-  return { code: failed2 > 0 ? 1 : 0 };
+  if (failed2 === 0) maybeAutoReindex(opts, dest);
+  return { code: failed2 > 0 ? autoExitCode : 0 };
 }
 
 function shouldSkip(name, isFile) {
@@ -399,17 +410,12 @@ function detectProjectDir() {
   return null;
 }
 
-// ── 元信 scan（若可用）─────────────────────────────────────────────────────
+// ── 元信 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;
+  const registry = require('../lib/skills-scan').readRegistry();
+  return gateLib.findVerifier({ dest, opts, registry });
 }
+
 function findPython(opts) {
   const cands = [];
   if (opts.python) cands.push(opts.python);
@@ -424,19 +430,29 @@ function findPython(opts) {
   }
   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 输出无法解析' };
+  if (!python) return { ok: false, error: '未找到 Python（元信 scan 需要 Python 3.8+）' };
+  return gateLib.runVerifier(engine, skillDir, { python, spawnSync });
+}
+
+function scanTarget(engine, skillDir) {
+  const scan = runScan(engine, skillDir);
+  if (scan.ok) {
+    const counts = scan.counts || {};
+    const line = 'critical ' + (counts.critical || 0) + ' / high ' + (counts.high || 0) +
+      ' / medium ' + (counts.medium || 0) + ' / low ' + (counts.low || 0) +
+      ' / info ' + (counts.info || 0);
+    out('  元信 scan: ' + scan.verdict + '（' + line + '）');
+    if (scan.verdict === gateLib.BLOCK) out('  ⚠ 元信 verdict 为 DO NOT INSTALL，已阻断安装。');
+    else if (scan.verdict === gateLib.CAUTION || scan.verdict === gateLib.REVIEW) {
+      out('  ⚠ 元信 verdict 为 ' + scan.verdict + '，继续安装并保留风险证据。');
+    }
+  } else {
+    out('  元信 scan: ' + scan.error);
   }
+  return scan;
 }
 
 // ── 安装 ───────────────────────────────────────────────────────────────────
@@ -468,6 +484,13 @@ function runNpmPack(skill, opts, packDir) {
 }
 
 function extractTarball(tarball, extractDir) {
+  const listed = spawnSync(tarBin(), ['-tzf', tarball], { encoding: 'utf8', timeout: 120000, maxBuffer: 16 * 1024 * 1024 });
+  if (listed.status !== 0) {
+    return { error: (listed.stderr || listed.stdout || 'tar 列表读取失败').trim().split('\n').pop() };
+  }
+  const entries = String(listed.stdout || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const unsafe = entries.find((entry) => !isSafeTarEntry(entry));
+  if (unsafe) return { error: '压缩包包含不安全路径: ' + unsafe };
   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');
@@ -477,72 +500,94 @@ function extractTarball(tarball, extractDir) {
 
 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: '已是最新' };
+function ensureGate(context) {
+  const { skill, extracted, dest, opts } = context;
+  const current = findVerifyEngine(dest, opts);
+  if (current) {
+    return {
+      ok: true,
+      engine: current,
+      mode: opts.bootstrap ? 'trusted-bootstrap' : 'installed',
+    };
   }
+  if (skill.slug === 'yotta-verify') {
+    const engine = path.join(extracted.pkgDir, 'scripts', 'yotta_verify.py');
+    if (!fs.existsSync(engine)) return { ok: false, error: '元信包内缺少 scripts/yotta_verify.py' };
+    return { ok: true, engine, mode: 'trusted-bootstrap' };
+  }
+
+  const verifier = findSkill('yotta-verify');
+  if (!verifier) return { ok: false, error: 'skills.json 缺少 yotta-verify' };
   let tmp;
   try {
-    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'yotta-skills-'));
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'yotta-verify-bootstrap-'));
     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 packed = runNpmPack(verifier, opts, packDir);
+    if (packed.error) return { ok: false, error: '元信自举下载失败: ' + 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 };
+    const extractedVerifier = extractTarball(packed.tarball, extractDir);
+    if (extractedVerifier.error) return { ok: false, error: '元信自举解包失败: ' + extractedVerifier.error };
+    const engine = path.join(extractedVerifier.pkgDir, 'scripts', 'yotta_verify.py');
+    if (!fs.existsSync(engine)) return { ok: false, error: '元信包内缺少 scripts/yotta_verify.py' };
+
+    out('  元信未安装，使用可信源包自举并先自扫。');
+    const result = installOne(verifier, dest, {
+      ...opts,
+      force: true,
+      skipScan: false,
+      bootstrap: true,
+      verify: engine,
+    });
+    if (result.status !== 'ok') return { ok: false, error: '元信自举失败: ' + result.note };
+    const installedEngine = path.join(dest, 'yotta-verify', 'scripts', 'yotta_verify.py');
+    if (!fs.existsSync(installedEngine)) return { ok: false, error: '元信自举后未找到安装引擎' };
+    return { ok: true, engine: installedEngine, mode: 'trusted-bootstrap' };
   } finally {
     if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
   }
 }
 
+const installOne = createInstaller({
+  runNpmPack,
+  extractTarball,
+  copyDir: (src, dst) => copyDir(src, dst, COPY_SKIP),
+  readInstalledVersion,
+  ensureGate,
+  scanTarget,
+  appendEvidence: evidenceLib.appendEvidence,
+});
+
 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;
+  let exitCode = 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 || '?'));
+    if (r.status === 'ok') {
+      if (r.gate && r.gate.mode === 'explicit-unverified') {
+        out('  ⚠ ' + s.slug.padEnd(22) + '未执行装前扫描（explicit-unverified）');
+      }
+      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); }
+    else {
+      failed++;
+      exitCode = Math.max(exitCode, r.exitCode || 1);
+      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;
+  if (failed > 0) process.exitCode = exitCode || 1;
+  return { failed, exitCode };
 }
 
 function runUpdate(opts, dest) {
@@ -550,6 +595,7 @@ function runUpdate(opts, dest) {
   out('yotta-skills（元阁）v' + VERSION + ' —— 增量更新 -> ' + dest);
   const results = [];
   let failed = 0;
+  let exitCode = 0;
   for (const s of skills) {
     const existing = readInstalledVersion(path.join(dest, s.slug));
     if (existing === s.version) {
@@ -559,15 +605,25 @@ function runUpdate(opts, dest) {
     }
     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 + '）' : '（新装）'));
+    if (r.status === 'ok') {
+      if (r.gate && r.gate.mode === 'explicit-unverified') {
+        out('  ⚠ ' + s.slug.padEnd(22) + '未执行装前扫描（explicit-unverified）');
+      }
+      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); }
+    else {
+      failed++;
+      exitCode = Math.max(exitCode, r.exitCode || 1);
+      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;
+  if (failed > 0) process.exitCode = exitCode || 1;
+  return { failed, exitCode };
 }
 
 // ── 展示 ───────────────────────────────────────────────────────────────────
@@ -777,12 +833,12 @@ function main() {
         process.exitCode = r.code;
       });
     } else {
-      runUpdate(opts, dest);
-      maybeAutoReindex(opts, dest);
+      const result = runUpdate(opts, dest);
+      if (!result.failed) maybeAutoReindex(opts, dest);
     }
   } else {
-    runInstall(opts, dest);
-    maybeAutoReindex(opts, dest);
+    const result = runInstall(opts, dest);
+    if (!result.failed) maybeAutoReindex(opts, dest);
   }
 }
 

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

@@ -69,11 +69,15 @@ npx -y @yottameta/yotta-skills install yotta-memory yotta-workflow --agent codex
 
 ## 10. 安装前安全扫描怎么用？
 
-默认会查找可用的元信引擎并输出摘要；可用 `--verify <path>` 指定引擎，或 `--skip-scan` 关闭。扫描结果仅提示，不替代人工判断。
+家族安装默认执行元信门禁：没有元信时先自动自举，再扫描待装包。`DO NOT INSTALL`
+和扫描失败会阻断；`INSTALL WITH CAUTION` / `REVIEW REQUIRED` 会继续但显示风险。
+可用 `--verify <path>` 指定引擎。`--skip-scan` 只是人工应急路径，会标记
+`explicit-unverified`，`update --auto` 不使用它。
 
 ## 11. 安装失败后如何恢复？
 
-查看汇总中的失败原因，先修复目录权限或网络，再单独安装失败技能：
+查看汇总中的失败原因。旧版本快照保存在 `~/.yottaskills/snapshots/`，当前版本失败时
+新版本不会替换旧版本。先修复目录权限或网络，再单独安装失败技能：
 
 ```bash
 npx -y @yottameta/yotta-skills install <slug> --dir /path/to/skills

package/skills/yotta-skills/references/install-flow.md

@@ -10,10 +10,13 @@
 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。
-7. 全部完成后自动 re-index 本地技能注册表（`~/.yottaskills/registry.json`）：重扫技能根目录并增量合并，
+4. 读取包内 `skill-manifest.json`；没有 manifest 时使用 `skills.json` 的家族默认契约；
+5. 校验 slug / package / version / 权限 / 生命周期脚本路径；
+6. 元信装前扫描：已有元信则直接扫描；没有则自动安装元信自身，再扫描；
+7. 通过后创建旧版本快照，把新版本复制到同盘暂存目录，再原子切换到目标目录；
+8. setup / doctor 阶段执行内置检查；P0-2.1 不执行自定义生命周期脚本；
+9. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；
+10. 全部成功后自动 re-index 本地技能注册表（`~/.yottaskills/registry.json`）：重扫技能根目录并增量合并，
    新装 / 更新的技能随即进入注册表（`--no-reindex` 可关闭；`--dry-run` 不触发）。
 
 ## 复制跳过规则
@@ -24,6 +27,17 @@
 因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
 安装器自身、测试夹具与 Python 字节码缓存。
 
+## manifest 与家族默认契约
+
+每个技能包可以自带根目录 `skill-manifest.json`。有 manifest 时：
+
+- 校验 `slug` / `package` / `version` 与包目录、`package.json`、`SKILL.md` 一致；
+- 校验 `install.idempotent` 为 `true`；
+- 校验 setup / doctor / rollback 路径为包内相对路径，不能包含绝对路径或 `..`。
+
+没有 manifest 时使用家族默认契约：来源 `yottameta`、幂等安装、自动应用模式 `route`，
+不声明 MCP、hook 或自定义生命周期脚本。
+
 ## re-index（装技能后自动重扫注册表）
 
 - `install` / `update` 完成后，CLI 自动调用 `--reindex`（同一套 `lib/skills-scan.js` 扫描核心）：
@@ -51,14 +65,37 @@
   其它 → 直接执行；
 - `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 额外提示
-  人工复核；仅摘要、不拦截。
+- 元信缺失时：先按 `skills.json` 安装 `yotta-verify`，并记录 `gate_mode=trusted-bootstrap`
+  与 `bootstrap_scan=self`，随后用元信扫描其余家族包；
+- verdict 处置：`SAFE TO INSTALL` 继续；`INSTALL WITH CAUTION` / `REVIEW REQUIRED`
+  继续但显示风险并留证；`DO NOT INSTALL` 和扫描失败阻断，不替换目标；
+- `--skip-scan` 只保留为人工应急路径，使用时输出 `explicit-unverified` 并写入证据；
+- `update --auto` 始终执行装前门禁，不接受 `--skip-scan`。
+
+## 快照与回滚
+
+- 旧版本快照：`~/.yottaskills/snapshots/<slug>/<timestamp>-<version>-<随机后缀>/`；
+- 新版本先落在 `<dest>/.yottaskills-staging/<slug>-<随机后缀>/`；
+- 旧目标先重命名为同盘备份，再把暂存目录切到目标；切换失败时恢复备份；
+- 证据写入失败会触发回滚，不把安装标记为成功；
+- Windows 上对 `EPERM` / `EACCES` / `EBUSY` 做短重试，避免杀毒或索引服务造成的瞬时锁。
+
+## 安装证据
+
+每次安装决策写入：
+
+```text
+~/.yottaskills/install-log.jsonl
+```
+
+记录包含时间、事件、技能、包名、版本、`gate_mode`、verdict、decision
+和快照路径；不记录技能内容或用户数据，只写本机。
 
 ## 退出码
 
@@ -68,6 +105,8 @@
 | 1 | 安装 / 更新存在失败项 |
 | 2 | 用法错误（未知参数 / 未知技能 / 未收录智能体） |
 | 4 | 未指定目标且当前目录未检测到项目级技能目录 |
+| 5 | 装前 gate 阻断或元信不可用 |
+| 6 | manifest / 身份校验失败 |
 
 ## 目标目录解析
 

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

@@ -8,7 +8,7 @@
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.0 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
 | `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.0 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
 | `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.0 | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.11.0 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.12.0 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
 | `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.0 | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
 | `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.2.2 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.3 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |

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

@@ -8,7 +8,7 @@
 
 - 学会 `--list` / `install` / `update` / `--dry-run` / `--pin` / `--force` 的用法；
 - 理解版本策略（range 与 --pin）与幂等行为；
-- 掌握元信装前摘要的开关与配置；
+- 了解元信装前门禁、元信自举与 `--skip-scan` 的人工应急边界；
 - 前置：Node.js 18+、npm、系统 tar（Windows 10+ 自带）；网络可访问 npm 注册表
   （国内可配置镜像或代理）。
 
@@ -76,22 +76,26 @@ dry-run 只打印将要执行的清单（含目标与版本策略），不联网
 npx -y @yottameta/yotta-skills install --agent codex --pin
 ```
 
-## 8. 强制重装与跳过元信摘要
+## 8. 强制重装与元信门禁
 
 ```bash
 npx -y @yottameta/yotta-skills install --agent codex --force     # 已是最新也重装
-npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 跳过装前摘要
+npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 人工应急：显式未验证
 ```
 
-元信（yotta-verify）已安装时默认会对每个待装技能输出装前摘要（verdict + 计数），仅提示
-不拦截；verdict 为 DO NOT INSTALL 时会提示人工复核。
+家族安装默认执行元信门禁：没有元信时，元阁先按可信源安装元信自身，再扫描待装技能。
+`DO NOT INSTALL` 会阻断安装；`INSTALL WITH CAUTION` / `REVIEW REQUIRED` 会继续但显示风险。
+旧版本会先快照到 `~/.yottaskills/snapshots/`，安装决策写入
+`~/.yottaskills/install-log.jsonl`。`--skip-scan` 只用于人工应急，会输出
+`explicit-unverified` 并留证，`update --auto` 不会使用它。
 
 ## 9. 验证安装结果
 
 - 看安装汇总：成功 N / 跳过 N / 失败 N；
 - 抽查技能目录：`ls ~/.codex/skills/yotta-memory/SKILL.md`；
 - 复核版本：每个技能 SKILL.md 的 frontmatter `version` 应与 `--list` 一致（这也是幂等
-  判断的依据）。
+  判断的依据）；
+- 需要安全复核时，查看 `~/.yottaskills/install-log.jsonl` 中的 verdict 与 `gate_mode`。
 
 ## 10. 常见问题
 

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

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