@yottameta/yotta-skills 0.8.0 → 0.19.0

package/CHANGELOG.md

@@ -1,3 +1,100 @@
+## v0.19.0 (2026-09-13)
+
+**元守家族分类假阳性修复**：
+
+- 元守 0.4.1 内置分类副本补入 `yotta-skills` 非安全家族排除，消除元阁 Defense Triple 假阳性。
+- `skills.json` / `references/skill-list.md` 同步 yotta-publish-guard 0.4.1。
+
+## v0.18.0 (2026-09-13)
+
+**Advisory 仓库文档 hygiene 清理**：
+
+- 元察 0.2.8 / 元析 0.1.6 / 元安 0.2.3 / 元造 0.1.1 / 元鉴 0.1.2 清理历史公开文档中的内部表述。
+- 五个技能 preflight、validate、测试与 pack 全部通过。
+- `skills.json` / `references/skill-list.md` 同步五个版本。
+
+## v0.17.0 (2026-09-13)
+
+**P0-6 全家族铺开覆盖验收**：
+
+- 新增 26 技能 manifest 覆盖测试：全部技能必须能解析包内 manifest 或家族默认契约。
+- 强制 8 技能必须提供包内 manifest 和 hook 声明；补齐 `yotta-verify-mcp` 与 `yotta-skills` 两个缺口。
+- 版本与发布件同步 0.17.0。
+
+## v0.16.0 (2026-09-13)
+
+**P0-4.6 元忆 after_milestone 试点**：
+
+- 元忆 manifest 声明 `after_milestone` / `remember_commit` / `fallback: explicit-unverified`。
+- 元阁真实 manifest 回归验证：有记忆文件证据时 allow/verified；缺证据或写入失败时 `explicit-unverified` + 一次纠偏。
+- `skills.json` / `references/skill-list.md` 同步 yotta-memory 0.13.0。
+
+## v0.15.0 (2026-09-13)
+
+**P0-4.5 元守 before_publish 试点**：
+
+- 元守 manifest 声明 `before_publish` / `publish_gate` / `fallback: wrapper`。
+- 元阁真实 manifest 回归验证：wrapper 已注册且门禁失败时 block；wrapper 未注册时 `explicit-unverified`。
+- `skills.json` / `references/skill-list.md` 同步 yotta-publish-guard 0.4.0。
+
+## v0.14.0 (2026-09-13)
+
+**P0-4.4 元序 before_start / after_milestone 试点**：
+
+- 元序 manifest 声明 `before_start` / `read_state` 与 `after_milestone` / `write_state`。
+- 元阁真实 manifest 回归验证：有状态文件证据时 allow；缺证据或落盘失败时 `explicit-unverified` + 一次纠偏。
+- `skills.json` / `references/skill-list.md` 同步 yotta-workflow 0.4.1。
+
+## v0.13.0 (2026-09-13)
+
+**P0-4.3 元盾 before_tool 试点**：
+
+- 元盾 manifest 声明 `before_tool` / `guard_check` / `fallback: explicit-unverified`。
+- 元阁真实 manifest 回归验证 Codex `native-audit` 只输出纠偏与 `unverified`，不宣称动作前硬拦截。
+- `skills.json` / `references/skill-list.md` 同步 yotta-guardian 0.1.3。
+
+## v0.12.0 (2026-09-13)
+
+**P0-4.1 元信 before_install 试点**：
+
+- 安装管线接入统一 hook 适配器：包内 `before_install` 声明在落位前评估，manifest 声明 `on_fail: block` 时扫描失败会阻断并保留旧版本。
+- 适配器证据写入 `~/.yottaskills/hook-log.jsonl`；`--skip-scan` 仍走人工应急路径，标记 `explicit-unverified`，不会被误报为已验证。
+- `skills.json` / `references/skill-list.md` 同步 yotta-verify 0.3.0。
+- 新增安装管线 hook 阻断回归；真实 yotta-verify manifest 随 0.3.0 发布。
+
+## v0.11.0 (2026-09-13)
+
+**P0-3 运行时 hook 适配层**：
+
+- 新增 `lib/hook-adapter.js`：六个统一事件、Codex 四档能力矩阵、manifest hook 声明校验、四档决策聚合和 `explicit-unverified` 降级。
+- 新增 `hook capabilities / evaluate / bind / unbind` CLI：可查看宿主能力、评估事件、写入结构化证据、幂等注册与反注册声明。
+- 证据写入 `~/.yottaskills/hook-log.jsonl`；绑定注册表写入 `~/.yottaskills/hook-bindings.json`，不直接改写宿主配置。
+- `native-audit` 不宣称强制；失败时输出 `explicit-unverified` 与纠偏信号。未核验宿主一律 `unsupported`。
+- 新增 `test/hook-adapter.test.js` 与 `test/hook-cli.test.js`；全量测试 131/131。
+- 本版只交付适配器内核，具体技能接入留待 P0-4 试点。
+
+## v0.10.0 (2026-09-13)
+
+**更新检查缓存与后台周检**：
+
+- 新增 `update --check --scheduled`：默认 7 天加 0 到 24 小时随机抖动，未到期不联网；到期只检查一次并把结果写入 `~/.yottaskills/update-check.json`。
+- 后台周检网络失败时文本模式静默、退出码 0；`--json` 保留 `error` / `cache` 诊断字段，不把后台调度失败变成用户噪音。
+- 手动 `update --check` 保持每次联网和 0 / 3 / 1 退出码；检查结果同样写入本地缓存，避免手动检查后立即重复周检。
+- `update --auto` 继续复用完整安装管线，`--skip-scan` 不能绕过元信门禁；`DO NOT INSTALL` 阻断、保留旧版本并写入证据。
+- SKILL / README / FAQ / 教程 / 走查同步：移除“会话开工默认联网检查”，明确手动检查与后台周检边界。
+- 新增 `lib/update-check.js`、`test/update-check-state.test.js`，并扩展 scheduled / auto 门禁回归。
+
+## v0.9.0 (2026-09-13)
+
+**doctor / rollback 与自定义生命周期**：
+
+- 新增 `doctor`：只读检查技能目录、`SKILL.md`、版本、manifest 身份、注册表一致性和自定义 doctor 脚本；支持 `--json`。
+- 新增 `rollback`：列出并校验快照，恢复最近一次安装或更新；恢复前后都保留快照与安装证据。
+- 安装管线接入包内 `setup` / `doctor` / `rollback` 生命周期脚本；setup 或 doctor 失败时自动恢复旧版本，脚本路径只能指向包内相对路径。
+- 新快照写入 SHA-256 元数据；旧快照仍可按结构校验和恢复。
+- `--slug` 用于 doctor / rollback 定向处理单个技能。
+- 新增生命周期、doctor、快照完整性与 CLI 回归测试。
+
 ## v0.8.0 (2026-09-12)
 
 **P0-2.1 安装编排与元信自举**：

package/README.md

@@ -29,12 +29,14 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 - **Orchestration routing** - <code>--route</code> turns a task summary into a candidate combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install command; it only suggests installation and never installs automatically.
 - **Install** — install everything (or a subset) into an agent's default user-level directory or any directory.
 - **Update** — incremental update: add missing skills, upgrade version-skewed ones.
-- **Update check / auto-update** — <code>update --check</code> compares installed skill versions against the npm registry and reports (no changes; run manually or from doctor / release checks); <code>update --auto</code> upgrades the installed YottaMeta family to the latest (non-family skills are never auto-updated).
+- **Update check / auto-update** — <code>update --check</code> compares installed skill versions against the npm registry and reports; <code>update --check --scheduled</code> is the weekly background entry with a local cache and jitter, so it stays offline until due; <code>update --auto</code> upgrades the installed YottaMeta family to the latest (non-family skills are never auto-updated).
+- **Doctor / rollback** — <code>doctor</code> checks the installed skill directory, version, manifest, registry and custom doctor script without modifying it; <code>rollback</code> validates a snapshot and restores the latest install or update.
+- **Runtime hook adapter** — manifests declare six lifecycle requirements; <code>hook capabilities / evaluate / bind / unbind</code> probe host support, apply deterministic decisions, record evidence, and never overstate audit-only hosts as enforced.
 - **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
 - **Pre-install gate** — family installs read the package manifest, bootstrap yotta-verify (元信) when it is missing, then scan each package. <code>DO NOT INSTALL</code> blocks; caution/review continue with visible risk. Old versions are snapshotted before replacement.
 - **Inventory / re-index** - scan the skill directories on this machine and keep a local registry (<code>~/.yottaskills/registry.json</code>); self-contained, no other skills required. Newly installed skills are discovered automatically: <code>install</code> / <code>update</code> re-index the registry afterwards, and <code>--reindex</code> re-scans on demand (e.g. at session start). An optional <code>yotta-skills</code> MCP (on-demand, not resident) exposes <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> / <code>route_request</code>; see <code>SKILL.md</code> for the config.
 
-Boundaries: it only downloads, places, gates and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. Besides the target directory, it keeps its registry, snapshots and install evidence under <code>~/.yottaskills</code>.
+Boundaries: it only downloads, places, gates and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. Besides the target directory, it keeps its registry, snapshots, install evidence and update-check cache under <code>~/.yottaskills</code>.
 
 ## Quick start
 
@@ -54,12 +56,26 @@ npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skil
 # Incrementally update installed skills
 npx -y @yottameta/yotta-skills update --agent codex
 
-# Check for updates (read-only, no changes); good to run at session start
+# Check for updates manually (read-only, no changes)
 npx -y @yottameta/yotta-skills update --check
 
+# Weekly background entry (stays offline until due; writes ~/.yottaskills/update-check.json)
+npx -y @yottameta/yotta-skills update --check --scheduled
+
 # Check and auto-update the installed YottaMeta family (pre-install gate applies; non-family skills untouched)
 npx -y @yottameta/yotta-skills update --auto
 
+# Read-only health check (optionally with --slug / --json)
+npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --slug yotta-memory
+
+# List snapshots; restore the latest install or update
+npx -y @yottameta/yotta-skills rollback --list --dir ~/my-skills
+npx -y @yottameta/yotta-skills rollback --slug yotta-memory --dir ~/my-skills
+
+# Inspect host hook capability and evaluate one manifest event
+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 --json
+
 # Preview what would be installed (no network, no changes)
 npx -y @yottameta/yotta-skills --dry-run
 
@@ -85,7 +101,11 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `install <skill>... [--agent <name> \| --dir <path>]` | Install only the given skills |
 | `update [--agent <name> \| --dir <path>]` | Incremental update: add missing, upgrade version-skewed |
 | `update --check` | Read-only update check: compare installed versions against the npm registry and report (exit 0 = up to date, 3 = updates available, 1 = could not check; run with `--registry <url>` to target a mirror); no changes |
+| `update --check --scheduled` | Weekly background entry: no network until due, then one check and a local cache write; text mode stays quiet on failure, `--json` keeps diagnostics; always exits 0 |
 | `update --auto` | Check and automatically update the installed YottaMeta family to the latest (runs the pre-install gate; never auto-updates non-family skills) |
+| `hook capabilities --host <name>` | Show the six-event host capability matrix; unknown hosts stay <code>unsupported</code> |
+| `hook evaluate --host <name> --event <event> --manifest <file> --context <json>` | Evaluate a manifest hook event, return allow / block / warn / unverified, and append structured evidence |
+| `hook bind --host <name> --manifest <file>` / `hook unbind <id>` | Idempotently register or remove hook declarations |
 | `--registry <url>` | npm registry to check against (default https://registry.npmjs.org/; `YOTTA_SKILLS_REGISTRY` overrides) |
 | `--inventory` | Inventory installed skills: scan skill directories and update the local registry (self-contained); `--json` for JSON, `--project` adds project-level dirs |
 | `--reindex` | Re-index the registry: re-scan skill directories and merge changes incrementally (session start / after installing skills; `--rescan` is a synonym); `--json` for JSON |

package/README.zh-CN.md

@@ -32,13 +32,15 @@
 - **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
-- **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告（不改动，手动或由 doctor / 发布前检查触发）；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
+- **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告；<code>update --check --scheduled</code> 是后台周检入口，用本地缓存和随机抖动做到未到期不联网；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
+- **自检 / 回滚**——<code>doctor</code> 只读检查技能目录、版本、manifest、注册表和自定义 doctor；<code>rollback</code> 校验快照后恢复最近一次安装或更新，恢复失败不会覆盖当前目录。
+- **运行时 hook 适配层**——技能 manifest 只声明六个生命周期要求；<code>hook capabilities / evaluate / bind / unbind</code> 负责宿主能力探测、确定性决策、结构化证据和降级标注，不把 audit 能力夸大为强制。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前门禁**——家族安装先读取包内 manifest，元信（yotta-verify）缺失时自动自举，再逐个扫描。`DO NOT INSTALL` 阻断；`CAUTION` / `REVIEW` 继续但显示风险。旧版本会先做快照再替换。
 - **盘点 / re-index**--扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</code>）；自包含，不需要任何其他技能。新装技能自动被发现：<code>install</code> / <code>update</code> 完成后自动重扫注册表，<code>--reindex</code> 可随时手动重扫（如会话开工）。可选 <code>yotta-skills</code> MCP（按需加载、不常驻）提供 <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> / <code>route_request</code> 四工具，配置见 <code>SKILL.md</code>。
 
 边界：只做「下载 + 落位 + 门禁 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
-全局安装；除目标目录外，会在 <code>~/.yottaskills</code> 下保留注册表、快照与安装证据。
+全局安装；除目标目录外，会在 <code>~/.yottaskills</code> 下保留注册表、快照、安装证据与更新检查缓存。
 
 ## 快速使用
 
@@ -61,9 +63,23 @@ npx -y @yottameta/yotta-skills update --agent codex
 # 只读检查更新（不改动；手动或由 doctor / 发布前检查触发）
 npx -y @yottameta/yotta-skills update --check
 
+# 后台周检入口（未到期不联网；到期单次检查并写缓存）
+npx -y @yottameta/yotta-skills update --check --scheduled
+
 # 检查后自动更新已装元阁家族（含装前门禁；非元阁家族技能不自动更新）
 npx -y @yottameta/yotta-skills update --auto
 
+# 只读检查已装技能（可加 --slug / --json）
+npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --slug yotta-memory
+
+# 查看快照；恢复最近一次安装或更新
+npx -y @yottameta/yotta-skills rollback --list --dir ~/my-skills
+npx -y @yottameta/yotta-skills rollback --slug yotta-memory --dir ~/my-skills
+
+# 查看宿主 hook 能力并评估一次 manifest 事件
+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 --json
+
 # 预览将安装清单（不联网、不改动）
 npx -y @yottameta/yotta-skills --dry-run
 
@@ -89,7 +105,11 @@ npx -y @yottameta/yotta-skills --reindex
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失、升级版本不一致的技能 |
 | `update --check` | 只读更新检查：比对已装版本与 npm 注册表并报告（退出码 0=最新 / 3=有更新 / 1=无法检查；可用 `--registry <url>` 指定镜像）；不改动 |
+| `update --check --scheduled` | 后台周检入口：未到期不联网；到期只检查一次并写本地缓存；文本失败静默，`--json` 保留诊断；始终退出 0 |
 | `update --auto` | 检查后自动更新已装元阁家族到最新（含装前门禁；非元阁家族技能绝不自动更新） |
+| `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 unbind <id>` | 幂等注册或反注册 hook 声明 |
 | `--registry <url>` | 检查的 npm registry 地址（默认 https://registry.npmjs.org/；`YOTTA_SKILLS_REGISTRY` 覆盖） |
 | `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用；`--rescan` 同义）；`--json` 输出 JSON |
@@ -170,7 +190,8 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 ## 工作原理
 
 对清单里每个技能：`npm pack <pkg>@<spec>` 到临时目录 → `tar -xzf` 解压 → 读取 manifest →
-元信装前门禁 → 快照旧版本并暂存新版本 → 原子替换 `<dest>/<slug>` → 汇总报告。`install` / `update` 完成后自动重扫本地技能注册表，
+元信装前门禁 → 快照旧版本并暂存新版本 → 原子替换 `<dest>/<slug>` → setup / doctor → 汇总报告；
+任一步失败会恢复旧版本。`rollback` 可校验并恢复已有快照。`install` / `update` 完成后自动重扫本地技能注册表，
 新装技能随即出现在 `--inventory` / `--reindex` 里（可用 `--no-reindex` 关闭）。
 细节见 `references/install-flow.md`；新手中文教程见 `references/tutorial.md`。
 

package/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 和本地注册表，得到一组可执行建议：