@yottameta/yotta-skills-plugin 0.8.0 → 0.19.0

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.8.0",
+      "version": "0.19.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.8.0",
+      "version": "0.19.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.8.0",
+  "version": "0.19.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.8.0",
+  "version": "0.19.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.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 阻断，非元阁家族包不自动安装。
+version: 0.19.0
+description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工只建议跑本地 --reindex；更新检查走手动 --check 或后台 --check --scheduled）；运行时适配层：hook capabilities / evaluate / bind / unbind 按宿主能力矩阵执行六个统一事件并留证降级，元信 before_install 已接入安装管线；自包含零依赖，不依赖任何元技能；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -16,8 +16,8 @@ metadata:
 **写入内容（逐字）**：
 
 > **元阁编排**：单技能是零件，组合才是系统。会话开工先跑一次 `yotta-skills --reindex`
-> （重扫本机技能注册表，新装技能自动被看见）；会话开工再跑一次 `yotta-skills update --check`
-> （联网只读检查本地已装技能是否有更新；有更新列清单，确认后 `update`，或 `update --auto` 仅自动更新自家 yotta-* 家族）。接到需求，先查「元阁编排策划」命中哪个组合
+> （重扫本机技能注册表，新装技能自动被看见）；更新检查走手动 `yotta-skills update --check`，
+> 或后台周检 `yotta-skills update --check --scheduled`（未到期不联网，到期单次检查并写缓存）。接到需求，先查「元阁编排策划」命中哪个组合
 > （输出呈现标准 / 长生命周期 / 交付质量门 / 装前安全门 / 造技能发版 / 安全事件响应 / 入口安装），
 > 再按需自动安装并应用。完整决策表见技能 `yotta-skills/references/orchestration.md`。
 
@@ -32,7 +32,7 @@ metadata:
 
 - **路由层（该用哪几个）**：`--route "<需求摘要>"` / MCP `route_request` 查本地注册表与静态编排 playbook，输出候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该怎么自动装并自动用起来。
-- **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`update --check` 只读检查更新、`update --auto` 家族自动更新、`--dry-run` 预览、`--pin` 锁版本。
+- **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`doctor` 只读自检、`rollback` 恢复快照、`--dry-run` 预览、`--pin` 锁版本。
 - **盘点层（已装了什么）**：`--inventory` / `--reindex` 扫描本机各智能体技能目录，生成/更新本地注册表；装技能后自动 re-index，新装技能自动被发现——自包含扫描，不依赖任何元技能。
 
 每个技能仍走各自独立的 npm 包（版本源唯一）；本包只做「清单 + 下载 + 落位 + 汇总」，**不内置任何技能本体**。
@@ -101,9 +101,19 @@ npx -y @yottameta/yotta-skills update --agent codex
 # 只读检查有没有更新（联网对 npm 最新，不改动；0=全部最新 / 3=有更新 / 1=查失败）
 npx -y @yottameta/yotta-skills update --check --agent codex
 
+# 后台周检入口（未到期不联网；到期只检查一次并写 ~/.yottaskills/update-check.json）
+npx -y @yottameta/yotta-skills update --check --scheduled --agent codex
+
 # 检查到家族更新后自动更新（仅 yotta-* 自家家族，含装前安全扫描）
 npx -y @yottameta/yotta-skills update --auto --agent codex
 
+# 只读检查已装技能（不修改目录；可加 --json 输出机器可读结果）
+npx -y @yottameta/yotta-skills doctor --agent codex
+
+# 查看可用快照 / 回滚最近一次安装或更新
+npx -y @yottameta/yotta-skills rollback --list --agent codex
+npx -y @yottameta/yotta-skills rollback --slug yotta-memory --agent codex
+
 # 预览将安装清单（不联网、不改动）
 npx -y @yottameta/yotta-skills --dry-run
 
@@ -124,7 +134,13 @@ npx -y @yottameta/yotta-skills --reindex
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
 | `update --check [--agent <name> \| --dir <path>]` | 只读检查更新：联网对 npm 最新，不改动；退出码 0=全部最新 / 3=有更新 / 1=查失败 |
+| `update --check --scheduled [--agent <name> \| --dir <path>]` | 后台周检入口：未到期不联网；到期只检查一次并写本地缓存；文本失败静默，`--json` 保留诊断；始终退出 0 |
 | `update --auto [--agent <name> \| --dir <path>]` | 检查到家族更新后自动更新（仅 yotta-* 自家家族，含装前安全扫描） |
+| `doctor [--agent <name> \| --dir <path>] [--slug <slug>]` | 只读自检：SKILL / 版本 / manifest / 注册表 / 自定义 doctor；`--json` 输出稳定字段 |
+| `rollback [--agent <name> \| --dir <path>] [--slug <slug>]` | 校验并恢复最近一次快照；`--list` 只列快照；`--json` 输出机器可读结果 |
+| `hook capabilities --host <name>` | 查看宿主六个统一事件的能力等级；未知宿主默认 `unsupported` |
+| `hook evaluate --host <name> --event <event> --manifest <file> --context <json>` | 评估 manifest hook 声明，输出 allow / block / warn / unverified，并写结构化证据 |
+| `hook bind --host <name> --manifest <file>` | 幂等注册 hook 声明；`hook unbind <id>` 反注册 |
 | `--inventory` | 盘点本机已装技能：扫描技能目录生成/更新注册表（自包含，不依赖元技能）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用）；`--json` 输出 JSON、`--project` 附扫项目级目录；`--rescan` 同义 |
 | `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；`--json` 输出 JSON、`--project` 附扫项目级目录 |
@@ -136,10 +152,26 @@ npx -y @yottameta/yotta-skills --reindex
 | `--npm <path>` | 指定 npm 可执行文件 |
 | `--python <path>` | 指定 python 可执行文件（元信 scan 用） |
 | `--verify <path>` | 指定 yotta_verify.py 路径 |
+| `--slug <slug>` | doctor / rollback 时只处理指定技能 |
 | `-h, --help` / `-v, --version` | 帮助 / 版本 |
 
 不带命令直接给技能名时，等价于 `install <skill>`。
 
+## 运行时 hook 适配层
+
+技能 manifest 只声明六个统一事件的要求，元阁负责能力探测、确定性评估、证据留痕和降级标注：
+
+```bash
+npx -y @yottameta/yotta-skills hook capabilities --host codex
+npx -y @yottameta/yotta-skills hook evaluate --host codex --event before_send --manifest ./skill-manifest.json --context '{"checks":{}}'
+npx -y @yottameta/yotta-skills hook bind --host codex --manifest ./skill-manifest.json
+npx -y @yottameta/yotta-skills hook unbind <binding-id>
+```
+
+证据写入 `~/.yottaskills/hook-log.jsonl`，绑定注册表写入
+`~/.yottaskills/hook-bindings.json`。`native-audit` 只表示可审计和一次纠偏，不表示动作前强制；
+`unsupported` 必须显示 `explicit-unverified`。本层只做本地确定性判断，不联网、不执行下载。
+
 ## 技能盘点（--inventory）
 
 元阁自带技能扫描核心（零依赖，不依赖任何元技能）：扫描各智能体技能目录，解析
@@ -175,14 +207,49 @@ npx -y @yottameta/yotta-skills --inventory --dir ~/my-skills --project
 （含元信装前安全扫描）自动更新。**非元阁家族（非 yotta-*）技能绝不自动更新**（默认保守：`--check` 列清单，
 用户确认后再 `update`）。
 
+`--check --scheduled` 是后台周检入口：默认 7 天加 0 到 24 小时随机抖动，未到期不联网；
+到期只检查一次并把结果写入 `~/.yottaskills/update-check.json`。文本模式网络失败静默，
+`--json` 可读取 `error` / `cache` 诊断字段。它不作为会话开工默认动作。
+
 ```bash
 # 只读检查（0=全部最新 / 3=有更新 / 1=查失败）
 npx -y @yottameta/yotta-skills update --check --agent codex
 
+# 后台周检入口（未到期不联网；到期单次检查并写缓存）
+npx -y @yottameta/yotta-skills update --check --scheduled --agent codex
+
 # 检查到家族更新后自动更新（仅自家家族）
 npx -y @yottameta/yotta-skills update --auto --agent codex
 ```
 
+## doctor 与 rollback
+
+`doctor` 是只读自检，不会修改技能目录或注册表。它检查目标技能目录、`SKILL.md`、
+frontmatter 版本、manifest 身份、本地注册表记录，以及包内声明的自定义 doctor 脚本。
+`--json` 返回稳定字段，适合脚本和智能体消费。
+
+```bash
+npx -y @yottameta/yotta-skills doctor --agent codex --slug yotta-memory
+npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --json
+```
+
+`rollback` 只恢复已经存在的本机快照。恢复前会校验快照（新快照校验 SHA-256 元数据，
+旧快照按结构校验）；恢复过程中先在同盘暂存，再替换目标，失败时保留当前目录。
+快照默认保留，不会被回滚操作删除。
+
+```bash
+# 查看当前有哪些快照（--slug 可只看一个技能）
+npx -y @yottameta/yotta-skills rollback --list --agent codex
+
+# 回滚最近一次安装或更新；也可用 --slug 指定技能
+npx -y @yottameta/yotta-skills rollback --slug yotta-memory --agent codex
+```
+
+包内 manifest 可声明 `install.setup`、`install.doctor`、`install.rollback`，
+值必须是包内相对路径。安装时先执行 setup，再执行内置 doctor 和自定义 doctor；
+任一步失败都会恢复旧版本并留下安装证据。元阁只执行元阁家族包内的生命周期脚本，
+不使用 shell，也不接受绝对路径或 `..` 路径。
+
 ## 编排路由（--route）
 
 把需求摘要交给静态编排 playbook 和本地注册表，得到一组可执行建议：

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 锁死精确版本。
@@ -26,10 +29,15 @@ 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() {
@@ -140,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++) {
@@ -169,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 {
@@ -187,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;
 }
 
@@ -287,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];
@@ -308,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;
     }
@@ -326,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) {
@@ -626,6 +755,296 @@ function runUpdate(opts, dest) {
   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;
+}
+
 // ── 展示 ───────────────────────────────────────────────────────────────────
 function printList(opts) {
   const skills = opts.skills.length ? selectSkills(opts) : MANIFEST;
@@ -648,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）');
@@ -662,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       帮助');
@@ -791,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 指定其技能目录。');
   }
 
@@ -823,13 +1357,14 @@ 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 {

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

@@ -4,7 +4,7 @@
 
 - **安装目标**：未指定目标怎么办 · 支持哪些智能体 · 装完为什么看不到
 - **网络与源**：国内访问慢 · 镜像延迟 · 网络失败
-- **更新**：`update --check` 退出码 · 自动更新边界 · 幂等
+- **更新**：`update --check` 退出码 · 后台周检缓存 · 自动更新边界 · 幂等
 - **版本**：`--pin` 与默认策略 · 清单漂移 · 单技能安装
 - **安全**：装前扫描 · 目标目录校验 · 失败恢复
 
@@ -43,6 +43,13 @@ YOTTA_SKILLS_NPM_FLAGS="--registry=https://registry.npmmirror.com" npx -y @yotta
 
 该命令只读，不修改文件。
 
+## 4.1 `update --check --scheduled` 什么时候用？
+
+它是后台周检入口：默认 7 天加 0 到 24 小时随机抖动，未到期不联网；到期只检查一次，
+结果写入 `~/.yottaskills/update-check.json`。文本模式网络失败静默并退出 0，
+`--json` 可读取 `error` / `cache` 诊断字段。会话开工只建议做本地 `--reindex`，
+不默认联网更新检查。
+
 ## 5. `update --auto` 会更新所有技能吗？
 
 只自动更新元阁家族内技能（`yotta-*` 且在清单中）。其他已装技能只提示，不自动改动。
@@ -76,8 +83,16 @@ npx -y @yottameta/yotta-skills install yotta-memory yotta-workflow --agent codex
 
 ## 11. 安装失败后如何恢复？
 
-查看汇总中的失败原因。旧版本快照保存在 `~/.yottaskills/snapshots/`，当前版本失败时
-新版本不会替换旧版本。先修复目录权限或网络，再单独安装失败技能：
+查看汇总中的失败原因。setup / doctor 失败时元阁会自动恢复旧版本；旧版本快照仍保存在
+`~/.yottaskills/snapshots/`。可以先用 `doctor` 自检，再用 `rollback` 恢复最近快照：
+
+```bash
+npx -y @yottameta/yotta-skills doctor --dir /path/to/skills --slug <slug>
+npx -y @yottameta/yotta-skills rollback --list --dir /path/to/skills
+npx -y @yottameta/yotta-skills rollback --slug <slug> --dir /path/to/skills
+```
+
+如果只是安装源或网络问题，再单独安装失败技能：
 
 ```bash
 npx -y @yottameta/yotta-skills install <slug> --dir /path/to/skills
@@ -86,3 +101,7 @@ npx -y @yottameta/yotta-skills install <slug> --dir /path/to/skills
 ## 12. 装完为什么智能体里看不到？
 
 确认安装目录与智能体实际读取目录一致；安装后通常需要重启会话或重新加载技能列表。
+
+## 13. `hook evaluate` 会真的拦截动作吗？
+
+不一定。适配层先探测宿主能力：`native-block` 才能声明动作前阻断；`native-audit` 只能审计并触发一次纠偏，结果会标记 `explicit-unverified`；`wrapper-only` 仅在 wrapper 注册后保证；未知宿主全部按 `unsupported` 处理。当前 Codex 已实测能力见 `hook capabilities --host codex`。

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

@@ -14,7 +14,7 @@
 5. 校验 slug / package / version / 权限 / 生命周期脚本路径；
 6. 元信装前扫描：已有元信则直接扫描；没有则自动安装元信自身，再扫描；
 7. 通过后创建旧版本快照，把新版本复制到同盘暂存目录，再原子切换到目标目录；
-8. setup / doctor 阶段执行内置检查；P0-2.1 不执行自定义生命周期脚本；
+8. 依次执行包内 setup、内置 doctor、包内自定义 doctor；任一步失败自动恢复旧版本；
 9. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；
 10. 全部成功后自动 re-index 本地技能注册表（`~/.yottaskills/registry.json`）：重扫技能根目录并增量合并，
    新装 / 更新的技能随即进入注册表（`--no-reindex` 可关闭；`--dry-run` 不触发）。
@@ -38,6 +38,16 @@
 没有 manifest 时使用家族默认契约：来源 `yottameta`、幂等安装、自动应用模式 `route`，
 不声明 MCP、hook 或自定义生命周期脚本。
 
+## 自定义生命周期脚本
+
+包内 `skill-manifest.json` 可声明 `install.setup` / `install.doctor` /
+`install.rollback`，值必须是包内相对路径，不能是绝对路径或包含 `..`。
+
+元阁用当前 Node.js 直接执行脚本，不经过 shell。脚本接收 `--skill-dir` /
+`--package-dir` / `--dest`，rollback 另接收 `--snapshot`，并始终追加 `--json`；
+脚本必须输出一个 JSON 对象，至少包含 `ok`。setup 或 doctor 失败时，先恢复旧版本，
+再在声明了 rollback 时调用它。生命周期结果、回滚结果和快照路径都会写入安装证据。
+
 ## re-index（装技能后自动重扫注册表）
 
 - `install` / `update` 完成后，CLI 自动调用 `--reindex`（同一套 `lib/skills-scan.js` 扫描核心）：
@@ -78,14 +88,53 @@
 - `--skip-scan` 只保留为人工应急路径，使用时输出 `explicit-unverified` 并写入证据；
 - `update --auto` 始终执行装前门禁，不接受 `--skip-scan`。
 
+## 更新检查缓存
+
+- 手动 `update --check`：每次联网，只读，保持退出码 0 / 3 / 1。
+- 后台周检 `update --check --scheduled`：默认 7 天加 0 到 24 小时随机抖动；未到期直接返回，
+  到期只检查一次；文本失败静默，`--json` 保留诊断。
+- 缓存文件：`~/.yottaskills/update-check.json`；按目标技能目录隔离记录，
+  字段包含 `last_checked`、`next_check`、`last_result`、`last_error`。
+- 本缓存只记录版本检查结果与网络错误，不记录技能内容或用户数据。
+
+## 运行时 hook 适配
+
+- `hook capabilities --host <name>`：查看六个统一事件的四档宿主能力；未知宿主默认 `unsupported`。
+- `hook evaluate --host <name> --event <event> --manifest <file> --context <json>`：按 manifest 顺序评估声明，输出 `allow` / `block` / `warn` / `unverified`。
+- `hook bind --manifest <file>` / `hook unbind <id>`：幂等注册或反注册声明，不直接改写宿主配置。
+- 评估证据写入 `~/.yottaskills/hook-log.jsonl`，绑定记录写入 `~/.yottaskills/hook-bindings.json`。
+- `native-audit` 不等于强制；缺少能力或证据时必须显示 `explicit-unverified`。
+
 ## 快照与回滚
 
 - 旧版本快照：`~/.yottaskills/snapshots/<slug>/<timestamp>-<version>-<随机后缀>/`；
+- 新快照同时写入 `<快照目录>.meta.json`，包含 SHA-256 摘要、版本、文件数和来源；
+- 无元数据的旧快照仍可按 `SKILL.md` 做结构校验；
 - 新版本先落在 `<dest>/.yottaskills-staging/<slug>-<随机后缀>/`；
 - 旧目标先重命名为同盘备份，再把暂存目录切到目标；切换失败时恢复备份；
 - 证据写入失败会触发回滚，不把安装标记为成功；
 - Windows 上对 `EPERM` / `EACCES` / `EBUSY` 做短重试，避免杀毒或索引服务造成的瞬时锁。
 
+回滚命令：
+
+```bash
+yotta-skills rollback --list --dir <skills-dir>
+yotta-skills rollback --slug <slug> --dir <skills-dir>
+```
+
+恢复前校验快照摘要；恢复时先在目标目录同盘暂存，再替换当前目录。恢复成功后执行
+内置 doctor 和自定义 doctor，并保留原快照供再次恢复。
+
+## doctor
+
+```bash
+yotta-skills doctor --dir <skills-dir> --slug <slug>
+yotta-skills doctor --dir <skills-dir> --json
+```
+
+doctor 只读检查目录、`SKILL.md`、版本、manifest 身份、注册表记录和自定义 doctor，
+不会修改目标目录或注册表。注册表版本不一致属于 warning，可用 `--reindex` 修复。
+
 ## 安装证据
 
 每次安装决策写入：

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

@@ -7,26 +7,26 @@
 |---|---|---|---|---|
 | `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.12.0 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.1 | 跨会话/跨项目通用工作流协议（状态就近存） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.13.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-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.2.3 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.3 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
-| `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.5 | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |
-| `yotta-guardian` | 元盾 | `@yottameta/yotta-guardian` | 0.1.2 | 跨智能体危险调用拦截护栏：确定性规则 + 可插拔意图验证 |
+| `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.6 | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |
+| `yotta-guardian` | 元盾 | `@yottameta/yotta-guardian` | 0.1.3 | 跨智能体危险调用拦截护栏：确定性规则 + 可插拔意图验证 |
 | `yotta-humanize` | 元真 | `@yottameta/yotta-humanize` | 0.2.0 | 去 AI 味中文写作编辑：检测器引擎 |
 | `yotta-logs` | 元史 | `@yottameta/yotta-logs` | 0.3.0 | 跨智能体历史会话 / 记忆日志检索 |
 | `yotta-security-testing` | 元测 | `@yottameta/yotta-security-testing` | 0.3.0 | 有纪律的 AI 安全测试方法论 + Scope Guard 五道防线 |
 | `yotta-agent-hardening` | 元安全 | `@yottameta/yotta-agent-hardening` | 0.2.4 | 防御向 AI 智能体自身安全加固（配置面静态扫描三域） |
-| `yotta-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.0 | 工坊「造」：端到端造技能脚手架 |
-| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.3.0 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
-| `yotta-logwatch` | 元察 | `@yottameta/yotta-logwatch` | 0.2.7 | 安全日志分析检测引擎（攻击链识别/告警聚合） |
+| `yotta-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.1 | 工坊「造」：端到端造技能脚手架 |
+| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.4.1 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
+| `yotta-logwatch` | 元察 | `@yottameta/yotta-logwatch` | 0.2.8 | 安全日志分析检测引擎（攻击链识别/告警聚合） |
 | `yotta-intel` | 元情 | `@yottameta/yotta-intel` | 0.2.0 | 威胁情报 IOC 提取与规范化引擎（STIX-lite） |
 | `yotta-secret` | 元钥 | `@yottameta/yotta-secret` | 0.2.0 | 密钥 / 凭据泄露源头扫描引擎 |
 | `yotta-chain` | 元链 | `@yottameta/yotta-chain` | 0.1.2 | 供应链依赖校验引擎 |
-| `yotta-triage` | 元鉴 | `@yottameta/yotta-triage` | 0.1.1 | 恶意样本静态初筛引擎（哈希/熵/字符串/PE-ELF） |
+| `yotta-triage` | 元鉴 | `@yottameta/yotta-triage` | 0.1.2 | 恶意样本静态初筛引擎（哈希/熵/字符串/PE-ELF） |
 | `yotta-prompt` | 元引 | `@yottameta/yotta-prompt` | 0.2.0 | 意图澄清 + 生态入口（常驻注入，map 串联元阁全家） |
-| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.2.2 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
+| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.3.0 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
 
 ## 家族分布
 

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

@@ -89,6 +89,15 @@ npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 人工应急
 `~/.yottaskills/install-log.jsonl`。`--skip-scan` 只用于人工应急，会输出
 `explicit-unverified` 并留证，`update --auto` 不会使用它。
 
+安装阶段还会按包内 manifest 执行 setup / doctor；setup 或 doctor 失败时自动恢复旧版本。
+可以用 `doctor` 只读自检，用 `rollback` 校验并恢复最近快照：
+
+```bash
+npx -y @yottameta/yotta-skills doctor --agent codex --slug yotta-memory
+npx -y @yottameta/yotta-skills rollback --list --agent codex
+npx -y @yottameta/yotta-skills rollback --slug yotta-memory --agent codex
+```
+
 ## 9. 验证安装结果
 
 - 看安装汇总：成功 N / 跳过 N / 失败 N；
@@ -108,6 +117,11 @@ npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 人工应急
 - **目标未指定**：当前目录没有项目级技能目录时报错（退出码 4），加 `--agent` 或
   `--dir`。
 - **已有旧版本**：默认按 range 覆盖升级到最新 patch；`--pin` 则锁定清单版本。
+- **doctor 报注册表版本不一致**：运行 `yotta-skills --reindex` 重扫注册表；doctor 本身不会写文件。
+- **需要撤销最近安装 / 更新**：先用 `rollback --list` 查看快照，再执行
+  `rollback --slug <slug>`；恢复前会自动校验快照。
+- **后台更新检查没有输出**：`update --check --scheduled` 在未到期、已最新或网络失败时
+  文本模式保持静默；需要诊断时加 `--json`。
 
 ## 11. 盘点已装技能与 re-index（新装技能自动被发现）
 
@@ -122,6 +136,9 @@ npx -y @yottameta/yotta-skills --reindex
 - `install` / `update` 完成后会自动重扫注册表（`~/.yottaskills/registry.json`），新装 / 更新的
   技能随即出现在 `--inventory` / `--reindex` 里；`--no-reindex` 可关闭自动重扫。
 - 建议每会话开工先跑一次 `--reindex`（快速增量，只合并变化），让后装的技能自动被看见。
+- 更新检查不再作为会话开工默认动作：手动检查用 `update --check`；后台周检用
+  `update --check --scheduled`，未到期不联网，到期只检查一次并写
+  `~/.yottaskills/update-check.json`。
 
 ## 编排路由（--route）
 
@@ -134,3 +151,16 @@ npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄"
 输出会告诉你命中哪个组合、按什么顺序调用、每个技能负责什么、哪些已装、哪些缺失，以及缺失技能的安装命令。元阁只给建议，不会自动安装；安装前请先做装前安全扫描，并由用户确认。
 - `--json` 输出机器可读结果（含新增 / 更新 / 消失），适合脚本与钩子。
 - 如果本机还装了非元阁家族技能，`--route` 会额外列出「其他已装技能候选」：只按 frontmatter description 与需求文本做本地机械匹配，标注来源、得分、命中词项与扫描状态（默认未扫描），不读取全文指令、不自动调用；使用/安装前请先做装前安全扫描。
+
+## 运行时 hook 适配（hook）
+
+技能 manifest 只声明六个统一事件的要求；元阁负责能力探测、确定性评估、证据留痕和降级标注：
+
+```bash
+npx -y @yottameta/yotta-skills hook capabilities --host codex --json
+npx -y @yottameta/yotta-skills hook evaluate --host codex --event before_send --manifest ./skill-manifest.json --context '{"checks":{}}' --json
+npx -y @yottameta/yotta-skills hook bind --host codex --manifest ./skill-manifest.json
+```
+
+`native-block` 才会显示动作前阻断；`native-audit` 只能审计并触发一次纠偏，结果标
+`explicit-unverified`；未知宿主全部按 `unsupported` 处理。本层不联网、不下载、不改宿主配置文件。

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

@@ -30,15 +30,23 @@ npx -y @yottameta/yotta-skills --agent codex
 npx -y @yottameta/yotta-skills update --check --agent codex
 ```
 
-2. 根据输出确认可更新清单。
+2. 如果由后台调度执行，改用周检入口：
 
-3. 执行增量更新：
+```bash
+npx -y @yottameta/yotta-skills update --check --scheduled --agent codex
+```
+
+未到期时不联网；到期只检查一次并把结果写入 `~/.yottaskills/update-check.json`。
+
+3. 根据输出确认可更新清单。
+
+4. 执行增量更新：
 
 ```bash
 npx -y @yottameta/yotta-skills update --agent codex
 ```
 
-4. 复核：已最新的技能应显示跳过，落后的技能显示更新；失败项单独重装。
+5. 复核：已最新的技能应显示跳过，落后的技能显示更新；失败项单独重装。
 
 ## 走查 3：按路由安装单个技能
 

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

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