@yottameta/yotta-skills-plugin 0.7.2 → 0.19.0

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

@@ -9,7 +9,10 @@
  *   npx -y @yottameta/yotta-skills install <skill> --dir <path>  # 装单个技能
  *   npx -y @yottameta/yotta-skills update --agent <name>  # 增量更新已装技能（补齐缺失/版本不一致）
  *   npx -y @yottameta/yotta-skills update --check         # 只读检查更新（联网对 npm 最新，不改动；退出码 0/3/1）
+ *   npx -y @yottameta/yotta-skills update --check --scheduled  # 后台周检（未到期不联网，到期单次检查并写缓存）
  *   npx -y @yottameta/yotta-skills update --auto          # 检查到家族更新后自动更新（仅 yotta-* 家族，含装前扫描）
+ *   npx -y @yottameta/yotta-skills hook capabilities      # 查看宿主六事件能力矩阵
+ *   npx -y @yottameta/yotta-skills hook evaluate --event before_send --manifest <file>  # 评估并留证
  *   npx -y @yottameta/yotta-skills --dry-run              # 预览将安装清单（不联网、不改动）
  *
  * 版本策略：清单锁定 `major.x`（不锁死 patch，维护性更新随最新）；--pin 锁死精确版本。
@@ -24,9 +27,17 @@ 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 healthLib = require('../lib/install-health');
+const lifecycleLib = require('../lib/install-lifecycle');
+const snapshotLib = require('../lib/install-snapshot');
+const updateCheckLib = require('../lib/update-check');
+const hookAdapterLib = require('../lib/hook-adapter');
+const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.2.1';
+let VERSION = '0.19.0';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -137,7 +148,8 @@ function parseArgs(argv) {
     help: false, version: false, agent: null, dir: null, npm: null,
     python: null, verify: null, command: null, skill: null, rest: [],
     inventory: false, reindex: false, noReindex: false, json: false, project: false, route: null,
-    check: false, auto: false, registry: null,
+    check: false, auto: false, scheduled: false, registry: null, slug: null,
+    host: null, event: null, manifest: null, context: null,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
@@ -166,15 +178,27 @@ function parseArgs(argv) {
     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 === '--slug') {
+      const value = take('--slug').toLowerCase();
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+        die('--slug 格式非法', 2, '只允许小写字母、数字和连字符，例如 yotta-memory。');
+      }
+      opts.slug = value;
+    }
     else if (a === '--check') opts.check = true;
     else if (a === '--auto') opts.auto = true;
+    else if (a === '--scheduled') opts.scheduled = true;
     else if (a === '--registry') opts.registry = take('--registry');
+    else if (a === '--host') opts.host = take('--host').toLowerCase();
+    else if (a === '--event') opts.event = take('--event').toLowerCase();
+    else if (a === '--manifest') opts.manifest = take('--manifest');
+    else if (a === '--context') opts.context = take('--context');
     else if (a.startsWith('-')) die('未知参数: ' + a, 2, '可用 --help 查看支持的选项。');
     else positionals.push(a);
   }
-  // 命令解析：install / update，其余位置参数 = 技能 slug（可多个）
+  // 命令解析：install / update / doctor / rollback，其余位置参数 = 技能 slug（可多个）
   for (const p of positionals) {
-    if (p === 'install' || p === 'update') {
+    if (p === 'install' || p === 'update' || p === 'doctor' || p === 'rollback' || p === 'hook') {
       if (opts.command && opts.command !== p) die('命令冲突：' + opts.command + ' 与 ' + p);
       opts.command = p;
     } else {
@@ -184,6 +208,9 @@ function parseArgs(argv) {
   // 直接给 slug 且无命令 → 视为 install 单个/多个
   if (!opts.command && opts.rest.length > 0) opts.command = 'install';
   opts.skills = opts.rest.map(s => s.toLowerCase());
+  if (opts.scheduled && (opts.command !== 'update' || !opts.check || opts.auto)) {
+    die('--scheduled 只能与 update --check 一起使用', 2, '请使用 update --check --scheduled；自动更新不使用后台调度入口。');
+  }
   return opts;
 }
 
@@ -284,15 +311,69 @@ async function runUpdateCheck(opts, dest) {
   var lines = [];
   var quiet = !!opts.json;
   function say(s) { if (!quiet) lines.push(s); }
-  say('yotta-skills（元阁）v' + VERSION + ' —— 检查更新（只读，不改动） -> ' + dest);
-  say('版本源: ' + (opts.registry || process.env.YOTTA_SKILLS_REGISTRY || 'https://registry.npmjs.org/'));
-  say('');
+  var scheduled = !!opts.scheduled;
+  var cache = updateCheckLib.readCache();
+  var target = cache.targets[updateCheckLib.targetKey(dest)] || null;
+  var due = updateCheckLib.isDue(target, Date.now());
+  if (!scheduled) {
+    say('yotta-skills（元阁）v' + VERSION + ' —— 检查更新（只读，不改动） -> ' + dest);
+    say('版本源: ' + (opts.registry || process.env.YOTTA_SKILLS_REGISTRY || 'https://registry.npmjs.org/'));
+    say('');
+  }
+  if (scheduled && !due) {
+    var cachedRows = (target && target.last_result && target.last_result.rows) || [];
+    var cachedPayload = {
+      dest: dest,
+      scheduled: true,
+      due: false,
+      checked: false,
+      updatable: cachedRows.filter(function (x) { return x.hasUpdate; }),
+      updates: (target && target.last_result && target.last_result.updates) || 0,
+      latest: (target && target.last_result && target.last_result.latest) || 0,
+      failed: 0,
+      nonFamily: (target && target.last_result && target.last_result.nonFamily) || 0,
+      cache: target,
+      error: null,
+    };
+    if (opts.json) out(JSON.stringify(cachedPayload, null, 2));
+    return {
+      code: 0,
+      scheduled: true,
+      due: false,
+      checked: false,
+      rows: cachedRows,
+      updates: cachedPayload.updates,
+      latest: cachedPayload.latest,
+      failed: 0,
+      nonFamily: cachedPayload.nonFamily,
+    };
+  }
   var installed = scanInstalledSlugs(dest);
   if (installed.length === 0) {
-    say('（' + dest + ' 下未发现已装技能目录）');
-    return { code: 0, rows: [], updates: 0, latest: 0, failed: 0, nonFamily: 0 };
+    var emptyResult = { updates: 0, latest: 0, failed: 0, nonFamily: 0, rows: [], errors: [] };
+    var emptyCacheRecord = null;
+    try {
+      emptyCacheRecord = updateCheckLib.recordCheck(os.homedir(), dest, { result: emptyResult, error: null });
+    } catch (_) { /* 缓存是后台优化的 best-effort，不阻断检查结果 */ }
+    if (!scheduled) {
+      say('（' + dest + ' 下未发现已装技能目录）');
+      for (var emptyIndex = 0; emptyIndex < lines.length; emptyIndex++) out(lines[emptyIndex]);
+    }
+    return {
+      code: 0,
+      scheduled: scheduled,
+      due: true,
+      checked: true,
+      rows: [],
+      updates: 0,
+      latest: 0,
+      failed: 0,
+      nonFamily: 0,
+      cache: emptyCacheRecord,
+    };
   }
   var rows = [];
+  var failures = [];
   var updates = 0, latest = 0, failed = 0, nonFamily = 0;
   for (var i = 0; i < installed.length; i++) {
     var it = installed[i];
@@ -305,6 +386,7 @@ async function runUpdateCheck(opts, dest) {
     var res = await fetchRegistryLatest(fam.pkg, opts);
     if (!res.ok) {
       failed++;
+      failures.push({ slug: it.slug, error: res.error });
       say('  ✘ ' + it.slug.padEnd(22) + '检查失败: ' + res.error);
       continue;
     }
@@ -323,11 +405,61 @@ async function runUpdateCheck(opts, dest) {
     }
     rows.push({ slug: it.slug, installed: cur, latest: current, pkg: fam.pkg, hasUpdate: !isUp, family: fam });
   }
-  say('');
-  say('汇总: 有更新 ' + updates + ' / 已最新 ' + latest + ' / 检查失败 ' + failed + ' / 非家族跳过 ' + nonFamily);
-  for (var j = 0; j < lines.length; j++) out(lines[j]);
+  var result = {
+    updates: updates,
+    latest: latest,
+    failed: failed,
+    nonFamily: nonFamily,
+    rows: rows,
+    errors: failures,
+  };
+  var lastError = failures.length > 0
+    ? failures.map(function (x) { return x.slug + ': ' + x.error; }).join('; ')
+    : null;
+  var cacheRecord = null;
+  try {
+    cacheRecord = updateCheckLib.recordCheck(os.homedir(), dest, { result: result, error: lastError });
+  } catch (_) { /* 缓存是后台优化的 best-effort，不阻断检查结果 */ }
   var code = (failed > 0) ? 1 : (updates > 0 ? 3 : 0);
-  return { code: code, rows: rows, updates: updates, latest: latest, failed: failed, nonFamily: nonFamily };
+  var updatable = rows.filter(function (x) { return x.hasUpdate; });
+  if (scheduled) {
+    if (updates > 0) {
+      for (var j = 0; j < updatable.length; j++) {
+        out('  ' + updatable[j].slug + '：本地 v' + (updatable[j].installed || '未知') + ' -> 最新 v' + updatable[j].latest);
+      }
+    }
+    if (opts.json) {
+      out(JSON.stringify({
+        dest: dest,
+        scheduled: true,
+        due: true,
+        checked: true,
+        updatable: updatable,
+        updates: updates,
+        latest: latest,
+        failed: failed,
+        nonFamily: nonFamily,
+        cache: cacheRecord,
+        error: lastError,
+      }, null, 2));
+    }
+    return { code: 0, scheduled: true, due: true, checked: true, rows: rows, updates: updates, latest: latest, failed: failed, nonFamily: nonFamily };
+  }
+  say('汇总: 有更新 ' + updates + ' / 已最新 ' + latest + ' / 检查失败 ' + failed + ' / 非家族跳过 ' + nonFamily);
+  for (var lineIndex = 0; lineIndex < lines.length; lineIndex++) out(lines[lineIndex]);
+  if (opts.json) {
+    out(JSON.stringify({
+      dest: dest,
+      updatable: updatable,
+      updates: updates,
+      latest: latest,
+      failed: failed,
+      nonFamily: nonFamily,
+      cache: cacheRecord,
+      error: lastError,
+    }, null, 2));
+  }
+  return { code: code, scheduled: false, due: true, checked: true, rows: rows, updates: updates, latest: latest, failed: failed, nonFamily: nonFamily };
 }
 
 async function runUpdateAuto(opts, dest) {
@@ -343,19 +475,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 +539,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 +559,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 +613,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 +629,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 +724,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 +734,315 @@ 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 };
+}
+
+// ── doctor / rollback ─────────────────────────────────────────────────────
+function readInstalledManifest(target) {
+  const file = path.join(target, 'skill-manifest.json');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function runCustomDoctor(skillDir, dest) {
+  const manifest = readInstalledManifest(skillDir);
+  if (!manifest || !manifest.install || !manifest.install.doctor) {
+    return { ok: true, skipped: true, error: null, result: null };
+  }
+  if (manifest.trust !== 'yottameta') {
+    return {
+      ok: false,
+      skipped: false,
+      error: 'manifest trust 不是 yottameta，拒绝执行自定义 doctor',
+      result: null,
+    };
+  }
+  return lifecycleLib.runPhase(skillDir, manifest, 'doctor', {
+    skillDir,
+    packageDir: skillDir,
+    dest,
+  });
+}
+
+function doctorTargets(opts, dest) {
+  if (opts.slug) {
+    const skill = familySkillFor(opts.slug);
+    return skill ? [skill] : [];
+  }
+  if (opts.skills.length) {
+    return opts.skills.map((slug) => familySkillFor(slug)).filter(Boolean);
+  }
+  const found = [];
+  let entries;
+  try { entries = fs.readdirSync(dest, { withFileTypes: true }); } catch (_) { return found; }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^yotta-/.test(entry.name)) continue;
+    const skill = familySkillFor(entry.name);
+    if (skill) found.push(skill);
+  }
+  return found;
+}
+
+function doctorExitCode(payload) {
+  if (payload.ok) return 0;
+  const manifestFailure = payload.results.some((result) =>
+    (result.checks || []).some((check) =>
+      (check.id === 'manifest' || check.id === 'manifest_trust') && !check.ok));
+  return manifestFailure ? 6 : 1;
+}
+
+function runDoctor(opts, dest) {
+  const scan = require('../lib/skills-scan');
+  const registry = scan.readRegistry();
+  const targets = doctorTargets(opts, dest);
+  const results = [];
+  const errors = [];
+  const warnings = [];
+  const fixes = [];
+
+  if (targets.length === 0) {
+    errors.push(opts.slug ? '未找到技能: ' + opts.slug : '目标目录下没有可检查的元阁家族技能');
+  }
+
+  for (const skill of targets) {
+    const target = path.join(dest, skill.slug);
+    const result = healthLib.checkInstalledSkill({
+      slug: skill.slug,
+      target,
+      expectedVersion: skill.version || null,
+      expectedPackage: skill.pkg || null,
+      registry,
+    });
+    const custom = runCustomDoctor(target, dest);
+    result.custom_doctor = {
+      ok: !!custom.ok,
+      skipped: !!custom.skipped,
+      error: custom.error || null,
+      result: custom.result || null,
+    };
+    if (!custom.ok) {
+      result.ok = false;
+      result.errors.push('自定义 doctor 失败: ' + (custom.error || '未知错误'));
+      result.checks.push({
+        id: 'custom_doctor',
+        ok: false,
+        severity: 'error',
+        message: '自定义 doctor 失败: ' + (custom.error || '未知错误'),
+        hint: '修复技能包内的 doctor 脚本后重试',
+      });
+    } else if (!custom.skipped) {
+      result.checks.push({
+        id: 'custom_doctor',
+        ok: true,
+        severity: 'info',
+        message: '自定义 doctor 通过',
+        hint: null,
+      });
+    }
+    results.push(result);
+    errors.push.apply(errors, result.errors);
+    warnings.push.apply(warnings, result.warnings);
+    fixes.push.apply(fixes, result.fixes);
+  }
+
+  const payload = {
+    ok: errors.length === 0,
+    dir: dest,
+    checked: results.length,
+    results,
+    errors,
+    warnings,
+    fixes: Array.from(new Set(fixes)),
+  };
+  const code = doctorExitCode(payload);
+  if (opts.json) {
+    out(JSON.stringify(payload, null, 2));
+  } else {
+    out('yotta-skills（元阁）v' + VERSION + ' —— doctor');
+    out('目标: ' + dest);
+    for (const result of results) {
+      out('');
+      out((result.ok ? '✔ ' : '✘ ') + result.slug + ' v' + (result.version || '未知'));
+      for (const check of result.checks) {
+        out('  ' + (check.ok ? '✔' : '✘') + ' ' + check.message + (check.hint ? '（修复: ' + check.hint + '）' : ''));
+      }
+    }
+    for (const item of warnings) out('[警告] ' + item);
+    for (const item of fixes) out('[建议] ' + item);
+    if (!payload.ok) out('doctor 未通过：请按上面的修复建议处理后重试。');
+  }
+  process.exitCode = code;
+  return payload;
+}
+
+function latestRollbackTarget(home) {
+  const file = path.join(home, '.yottaskills', 'install-log.jsonl');
+  let lines;
+  try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/).filter(Boolean); } catch (_) { return null; }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let entry;
+    try { entry = JSON.parse(lines[i]); } catch (_) { continue; }
+    if (!entry.skill || !entry.snapshot) continue;
+    if (!fs.existsSync(entry.snapshot)) continue;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(entry.skill)) continue;
+    const expectedRoot = path.resolve(snapshotLib.snapshotRoot(home, entry.skill)) + path.sep;
+    if (!path.resolve(entry.snapshot).startsWith(expectedRoot)) continue;
+    const validation = snapshotLib.validateSnapshot(entry.snapshot);
+    if (validation.ok) return { slug: entry.skill, snapshot: entry.snapshot };
+  }
+  return null;
+}
+
+function runRollback(opts, dest) {
+  const home = os.homedir();
+  const requestedSlug = opts.slug || (opts.skills.length ? opts.skills[0] : null);
+
+  if (opts.list) {
+    const rows = snapshotLib.listSnapshots(home, requestedSlug);
+    const payload = {
+      ok: true,
+      dir: dest || null,
+      slug: requestedSlug || null,
+      count: rows.filter((row) => row.valid).length,
+      snapshots: rows,
+    };
+    if (opts.json) out(JSON.stringify(payload, null, 2));
+    else {
+      out('yotta-skills（元阁）v' + VERSION + ' —— rollback 快照');
+      for (const row of rows) {
+        out('  ' + (row.valid ? '✔' : '✘') + ' ' + row.slug + ' v' + (row.version || '未知') + '  ' + row.path + (row.reason ? '（' + row.reason + '）' : ''));
+      }
+      out('可用快照: ' + payload.count + ' / ' + rows.length);
+    }
+    return payload;
+  }
+
+  let slug = requestedSlug;
+  let selected = null;
+  if (slug) {
+    const rows = snapshotLib.listSnapshots(home, slug);
+    selected = rows.find((row) => row.valid) || rows[0] || null;
+  } else {
+    const latest = latestRollbackTarget(home);
+    if (latest) {
+      slug = latest.slug;
+      selected = snapshotLib.listSnapshots(home, slug).find((row) => row.path === latest.snapshot && row.valid) || null;
+    }
+  }
+
+  if (!slug) {
+    const payload = { ok: false, dir: dest, slug: null, errors: ['安装记录中没有可回滚的技能快照'] };
+    if (opts.json) out(JSON.stringify(payload, null, 2));
+    else out('回滚失败：安装记录中没有可回滚的技能快照。');
+    process.exitCode = 1;
+    return payload;
+  }
+  if (!selected || !selected.valid) {
+    const payload = {
+      ok: false,
+      dir: dest,
+      slug,
+      errors: [selected && selected.reason ? '选中的快照不可用: ' + selected.reason : '没有可用快照'],
+    };
+    if (opts.json) out(JSON.stringify(payload, null, 2));
+    else out('回滚失败：' + payload.errors[0]);
+    process.exitCode = 1;
+    return payload;
+  }
+
+  const target = path.join(dest, slug);
+  const restored = snapshotLib.restoreSnapshot(selected.path, target);
+  if (!restored.ok) {
+    const payload = { ok: false, dir: dest, slug, snapshot: selected.path, errors: [restored.error] };
+    if (opts.json) out(JSON.stringify(payload, null, 2));
+    else out('回滚失败：' + restored.error);
+    process.exitCode = 1;
+    return payload;
+  }
+
+  const family = familySkillFor(slug);
+  const scan = require('../lib/skills-scan');
+  const doctor = healthLib.checkInstalledSkill({
+    slug,
+    target,
+    expectedVersion: restored.version && restored.version !== 'unknown' ? restored.version : null,
+    expectedPackage: family ? family.pkg : null,
+    registry: scan.readRegistry(),
+  });
+  const custom = runCustomDoctor(target, dest);
+  if (!custom.ok) {
+    doctor.ok = false;
+    doctor.errors.push('自定义 doctor 失败: ' + (custom.error || '未知错误'));
+  }
+
+  const payload = {
+    ok: doctor.ok,
+    dir: dest,
+    slug,
+    snapshot: selected.path,
+    version: restored.version,
+    doctor,
+    errors: doctor.errors,
+    warnings: doctor.warnings,
+    fixes: doctor.fixes,
+    reindexed: false,
+  };
+  try {
+    evidenceLib.appendEvidence({
+      event: 'rollback',
+      skill: slug,
+      package: family ? family.pkg : null,
+      version: restored.version,
+      decision: doctor.ok ? 'ok' : 'fail',
+      snapshot: selected.path,
+    }, { homeDir: home });
+  } catch (error) {
+    payload.ok = false;
+    payload.errors.push('回滚证据写入失败: ' + error.message);
+  }
+  if (payload.ok && !opts.noReindex) {
+    try {
+      reindexRegistry({ ...opts, dir: dest });
+      payload.reindexed = true;
+    } catch (error) {
+      payload.warnings.push('回滚完成，但注册表重扫失败: ' + error.message);
+    }
+  }
+
+  if (opts.json) {
+    out(JSON.stringify(payload, null, 2));
+  } else {
+    out('yotta-skills（元阁）v' + VERSION + ' —— rollback');
+    out('技能: ' + slug);
+    out('快照: ' + selected.path);
+    out('结果: ' + (payload.ok ? '✔ 已恢复 v' + (restored.version || '未知') : '✘ 恢复后 doctor 未通过'));
+    if (payload.errors.length) out('错误: ' + payload.errors.join('; '));
+    if (payload.warnings.length) out('警告: ' + payload.warnings.join('; '));
+    if (payload.reindexed) out('已重扫本地技能注册表。');
+  }
+  process.exitCode = payload.ok ? 0 : 1;
+  return payload;
 }
 
 // ── 展示 ───────────────────────────────────────────────────────────────────
@@ -592,10 +1067,18 @@ function printHelp() {
   out('  yotta-skills install --dir <path>   装全家到指定目录');
   out('  yotta-skills install <skill> --dir <path>  装单个技能（可多个）');
   out('  yotta-skills update --agent <name>  增量更新已装技能（补齐缺失 / 版本不一致）');
+  out('  yotta-skills update --check         只读联网检查更新（退出码 0/3/1）');
+  out('  yotta-skills update --check --scheduled  后台周检（未到期不联网；到期单次检查并写缓存）');
+  out('  yotta-skills doctor --dir <path>    只读自检技能目录（可加 --slug / --json）');
+  out('  yotta-skills rollback --dir <path>  回滚最近一次技能安装或更新（--list 查看快照）');
   out('  yotta-skills --dry-run              预览将安装清单（不联网、不改动）');
   out('  yotta-skills --inventory            盘点本机已装技能（自研扫描，不依赖任何元技能）');
   out('  yotta-skills --reindex              重扫注册表（会话开工 / 装技能后自动调用；增量合并）');
   out('  yotta-skills --route "<需求摘要>"   给出场景组合、调用顺序、缺失技能安装建议');
+  out('  yotta-skills hook capabilities       查看宿主六事件能力矩阵');
+  out('  yotta-skills hook evaluate --event <event> --manifest <file>  评估 hook 声明并留证');
+  out('  yotta-skills hook bind --manifest <file>  注册 hook 声明（幂等）');
+  out('  yotta-skills hook unbind <binding-id>  反注册 hook 声明');
   out('');
   out('选项:');
   out('  --agent <name>   智能体键名（--list 可查看；未知智能体请用 --dir）');
@@ -606,11 +1089,17 @@ function printHelp() {
   out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
   out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
   out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
-  out('  --json            inventory / reindex / route 时输出 JSON');
+  out('  --json            inventory / reindex / route / doctor / rollback 时输出 JSON');
+  out('  --slug <slug>     doctor / rollback 时只处理指定技能');
   out('  --route <需求>    静态编排路由（输出组合 / 顺序 / 依据 / 缺失技能建议）');
   out('  --check            update 时仅只读检查更新（联网对 npm 最新版本，不改动；退出码 0/3/1）');
+  out('  --scheduled        与 update --check 合用：后台周检入口（未到期不联网；到期单次检查并写缓存）');
   out('  --auto             update 时检查到家族更新后自动更新（仅 yotta-* 家族，含装前扫描）');
   out('  --registry <url>  npm registry 地址（默认 https://registry.npmjs.org/；YOTTA_SKILLS_REGISTRY 覆盖）');
+  out('  --host <name>     hook 适配宿主名（默认 generic；当前已实测 codex）');
+  out('  --event <event>   hook 六事件之一（before_start / before_tool / before_install / before_publish / after_milestone / before_send）');
+  out('  --manifest <file> hook evaluate / bind 使用的 skill-manifest.json 路径');
+  out('  --context <json>  hook evaluate 的检查结果 JSON（checks / wrapperRegistered / evidence）');
   out('  --project         inventory / reindex 时附加扫描当前项目 .agents/skills / .codex/skills');
   out('  --no-reindex      安装 / 更新后不自动重扫注册表');
   out('  -h, --help       帮助');
@@ -735,20 +1224,121 @@ function maybeAutoReindex(opts, dest) {
   }
 }
 
+// ── 运行时 hook 适配层（P0-3） ───────────────────────────────────────────────
+function readJsonFile(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    die(label + ' 读取失败: ' + error.message, 2, '请确认文件存在且为合法 JSON。');
+  }
+}
+
+function runHook(opts) {
+  const action = opts.rest[0] || 'capabilities';
+  const host = opts.host || 'generic';
+  const adapter = hookAdapterLib.createHookAdapter({ host });
+
+  if (action === 'capabilities') {
+    const payload = { host, capabilities: adapter.capabilities() };
+    if (opts.json) out(JSON.stringify(payload, null, 2));
+    else {
+      out('yotta-skills（元阁）v' + VERSION + ' —— hook capabilities');
+      out('宿主: ' + host);
+      hookAdapterLib.EVENTS.forEach((event) => out('  ' + event.padEnd(18) + payload.capabilities[event]));
+    }
+    return;
+  }
+
+  if (action === 'evaluate') {
+    if (!opts.event) die('hook evaluate 缺少 --event', 2, '请提供六个统一事件之一。');
+    if (!opts.manifest) die('hook evaluate 缺少 --manifest', 2, '请提供 skill-manifest.json 路径。');
+    const manifest = readJsonFile(opts.manifest, 'manifest');
+    let context = {};
+    if (opts.context) {
+      try {
+        context = JSON.parse(opts.context);
+      } catch (error) {
+        die('--context 不是合法 JSON: ' + error.message, 2, '请传入 JSON 对象。');
+      }
+    }
+    if (!context || typeof context !== 'object' || Array.isArray(context)) {
+      die('--context 必须是 JSON 对象', 2);
+    }
+    const result = adapter.evaluate(opts.event, manifest, context);
+    const entries = result.results.length > 0
+      ? result.results
+      : [{ event: opts.event, skill: manifest.slug, action: null, decision: result.decision, evidence: {}, capability: adapter.capabilities()[opts.event] || 'unsupported', reason: result.user_message }];
+    for (const entry of entries) {
+      hookAdapterLib.appendHookEvidence({
+        event: entry.event,
+        skill: entry.skill,
+        action: entry.action,
+        result: entry.decision,
+        capability: entry.capability,
+        evidence: entry.evidence,
+        reason: entry.reason,
+      }, { homeDir: os.homedir() });
+    }
+    if (opts.json) out(JSON.stringify({ host, event: opts.event, ...result }, null, 2));
+    else {
+      out('yotta-skills（元阁）v' + VERSION + ' —— hook evaluate');
+      out('宿主: ' + host + ' / 事件: ' + opts.event);
+      out('决策: ' + result.decision + ' / verified: ' + result.verified);
+      out(result.user_message);
+      for (const entry of result.results) out('  ' + entry.action + ': ' + entry.decision + '（' + entry.capability + '）');
+    }
+    process.exitCode = result.decision === 'block' ? 3 : 0;
+    return;
+  }
+
+  if (action === 'bind') {
+    if (!opts.manifest) die('hook bind 缺少 --manifest', 2, '请提供 skill-manifest.json 路径。');
+    const manifest = readJsonFile(opts.manifest, 'manifest');
+    const bindings = adapter.bind(manifest, opts.event || null);
+    if (opts.json) out(JSON.stringify({ host, bindings }, null, 2));
+    else {
+      out('yotta-skills（元阁）v' + VERSION + ' —— hook bind');
+      out('宿主: ' + host + ' / 绑定 ' + bindings.length + ' 项');
+      for (const binding of bindings) out('  ' + binding.id + '  ' + binding.event + '  ' + binding.action + '  ' + binding.capability);
+    }
+    return;
+  }
+
+  if (action === 'unbind') {
+    const id = opts.rest[1];
+    if (!id) die('hook unbind 缺少 binding id', 2, '先用 hook bind / list 获取 id。');
+    const removed = adapter.unbind(id);
+    if (opts.json) out(JSON.stringify({ host, id, removed }, null, 2));
+    else out(removed ? '已解除绑定: ' + id : '未找到绑定: ' + id);
+    process.exitCode = removed ? 0 : 1;
+    return;
+  }
+
+  die('未知 hook 子命令: ' + action, 2, '支持 capabilities / evaluate / bind / unbind。');
+}
+
 // ── 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.list && !opts.command) { printList(opts); return; }
   if (opts.inventory && !opts.command) { runInventory(opts); return; }
   if (opts.reindex && !opts.command) { runReindex(opts); return; }
   if (opts.route && !opts.command) { runRoute(opts); return; }
 
   const command = opts.command || 'install';
+  if (command === 'hook') {
+    runHook(opts);
+    return;
+  }
+  if (command === 'rollback' && opts.list) {
+    runRollback(opts, null);
+    return;
+  }
   let dest = resolveTargetDir(opts);
   if (!dest && !opts.dryRun) dest = detectProjectDir();
-  if (!dest && command === 'install' && !opts.dryRun) {
+  if (!dest && (command === 'install' || command === 'doctor' || command === 'rollback') && !opts.dryRun) {
     die('未指定目标：请用 --agent <name> 或 --dir <path>（当前目录未检测到项目级技能目录）。', 4, '未收录智能体也可用 --dir 指定其技能目录。');
   }
 
@@ -767,22 +1357,23 @@ function main() {
     return;
   }
 
-  if (command === 'update') {
+  if (command === 'doctor') {
+    runDoctor(opts, dest);
+  } else if (command === 'rollback') {
+    runRollback(opts, dest);
+  } else if (command === 'update') {
     if (opts.check || opts.auto) {
       var runFn = opts.auto ? runUpdateAuto : runUpdateCheck;
       runFn(opts, dest).then(function (r) {
-        if (opts.json && !opts.auto) {
-          out(JSON.stringify({ dest: dest, updatable: r.rows.filter(function (x) { return x.hasUpdate; }), updates: r.updates, latest: r.latest, failed: r.failed, nonFamily: r.nonFamily }, null, 2));
-        }
         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);
   }
 }