@yottameta/yotta-skills 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## v0.8.0 (2026-09-12)
+
+**P0-2.1 安装编排与元信自举**：
+
+- 安装链路读取包内 `skill-manifest.json`，缺失时使用 `skills.json` 家族默认契约。
+- 元信缺失时自动自举，随后对所有家族包执行装前扫描。
+- `DO NOT INSTALL` 和扫描失败阻断安装；`CAUTION` / `REVIEW` 继续但显示风险。
+- 安装改为快照、暂存、原子切换，失败不删除旧版本。
+- 新增 `~/.yottaskills/install-log.jsonl` 安装证据。
+- `--skip-scan` 仅保留为人工应急路径，并记录 `explicit-unverified`。
+
 ## v0.7.2 (2026-09-10)
 
 skills.json 清单同步（元序路径模型澄清升版后，元阁安装清单随包更新）：
@@ -42,7 +53,6 @@ skills.json 清单同步（评测批 2 六技能升版后，元阁安装清单
 ## v0.5.1 (2026-09-06)
 
 skills.json 三处滞后同步修复（yotta-skills 0.5.0→0.5.1）：元真 0.1.2→0.1.3 / 元忆 0.8.5→0.10.1 / 元守 0.1.1→0.2.1 + updated 改期 2026-09-06 + yotta-skills 四件对齐 0.5.1 + 技能分发清单副本 + 插件同步。
-# 更新日志
 
 ## v0.5.0 (2026-08-31)
 

package/README.md

@@ -29,12 +29,12 @@ 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; quick to run at session start); <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 (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).
 - **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
-- **Pre-install summary** — if yotta-verify (元信) is available, each skill is scanned first; the verdict is informational only.
+- **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 and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. It never writes outside the target you specify.
+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>.
 
 ## Quick start
 
@@ -57,7 +57,7 @@ npx -y @yottameta/yotta-skills update --agent codex
 # Check for updates (read-only, no changes); good to run at session start
 npx -y @yottameta/yotta-skills update --check
 
-# Check and auto-update the installed YottaMeta family (pre-install summary applies; non-family skills untouched)
+# Check and auto-update the installed YottaMeta family (pre-install gate applies; non-family skills untouched)
 npx -y @yottameta/yotta-skills update --auto
 
 # Preview what would be installed (no network, no changes)
@@ -85,7 +85,7 @@ 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 --auto` | Check and automatically update the installed YottaMeta family to the latest (runs the pre-install summary; never auto-updates non-family skills) |
+| `update --auto` | Check and automatically update the installed YottaMeta family to the latest (runs the pre-install gate; never auto-updates non-family skills) |
 | `--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 |
@@ -94,9 +94,9 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `--dry-run` | Preview the install / update list; no network, no changes |
 | `--pin` | Lock the exact manifest versions (default: range, latest patch of the same major) |
 | `--force` | Reinstall even when already at the latest version |
-| `--skip-scan` | Skip the yotta-verify pre-install summary (auto-enabled when yotta-verify is installed) |
+| `--skip-scan` | Manual escape hatch: skip the verifier gate and mark the result `explicit-unverified`; never used by `update --auto` |
 | `--npm <path>` | Specify the npm executable |
-| `--python <path>` | Specify the python executable (used for the yotta-verify summary) |
+| `--python <path>` | Specify the python executable (used for yotta-verify scan) |
 | `--verify <path>` | Specify the yotta_verify.py path |
 | `-h, --help` / `-v, --version` | Help / version |
 
@@ -161,7 +161,7 @@ The full 22-skill manifest with Chinese names, package names, versions and descr
 
 ## How it works
 
-For each skill in the manifest: `npm pack <pkg>@<spec>` into a temp directory → `tar -xzf` → optional yotta-verify pre-install summary → replace `<dest>/<slug>` → summary report. After `install` / `update` finishes, the local skill registry is re-indexed automatically so newly installed skills show up in `--inventory` / `--reindex` (disable with `--no-reindex`). Details: `references/install-flow.md`; beginner tutorial (Chinese): `references/tutorial.md`.
+For each skill in the manifest: `npm pack <pkg>@<spec>` into a temp directory → `tar -xzf` → read the package manifest → run the yotta-verify pre-install gate (bootstrap yotta-verify first when missing) → snapshot the old version and stage the new one → atomically replace `<dest>/<slug>` → summary report. After `install` / `update` finishes, the local skill registry is re-indexed automatically so newly installed skills show up in `--inventory` / `--reindex` (disable with `--no-reindex`). Details: `references/install-flow.md`; beginner tutorial (Chinese): `references/tutorial.md`.
 
 ## Development & validation
 

package/README.zh-CN.md

@@ -32,13 +32,13 @@
 - **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
-- **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告（不改动，适合会话开工快速跑）；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
+- **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告（不改动，手动或由 doctor / 发布前检查触发）；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
-- **装前摘要**——若装了元信（yotta-verify），先对每个待装技能做一次装前扫描；verdict 仅提示、不拦截。
+- **装前门禁**——家族安装先读取包内 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>-g</code>
+全局安装；除目标目录外，会在 <code>~/.yottaskills</code> 下保留注册表、快照与安装证据。
 
 ## 快速使用
 
@@ -58,10 +58,10 @@ npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skil
 # 增量更新已装技能
 npx -y @yottameta/yotta-skills update --agent codex
 
-# 只读检查更新（不改动；适合会话开工快速跑）
+# 只读检查更新（不改动；手动或由 doctor / 发布前检查触发）
 npx -y @yottameta/yotta-skills update --check
 
-# 检查后自动更新已装元阁家族（含装前摘要；非元阁家族技能不自动更新）
+# 检查后自动更新已装元阁家族（含装前门禁；非元阁家族技能不自动更新）
 npx -y @yottameta/yotta-skills update --auto
 
 # 预览将安装清单（不联网、不改动）
@@ -89,7 +89,7 @@ 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 --auto` | 检查后自动更新已装元阁家族到最新（含装前摘要；非元阁家族技能绝不自动更新） |
+| `update --auto` | 检查后自动更新已装元阁家族到最新（含装前门禁；非元阁家族技能绝不自动更新） |
 | `--registry <url>` | 检查的 npm registry 地址（默认 https://registry.npmjs.org/；`YOTTA_SKILLS_REGISTRY` 覆盖） |
 | `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用；`--rescan` 同义）；`--json` 输出 JSON |
@@ -98,9 +98,9 @@ npx -y @yottameta/yotta-skills --reindex
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
-| `--skip-scan` | 跳过元信装前摘要（装了 yotta-verify 时默认自动启用） |
+| `--skip-scan` | 人工应急路径：跳过元信门禁并标记 `explicit-unverified`；`update --auto` 不使用该开关 |
 | `--npm <path>` | 指定 npm 可执行文件 |
-| `--python <path>` | 指定 python 可执行文件（元信摘要用） |
+| `--python <path>` | 指定 python 可执行文件（元信 scan 用） |
 | `--verify <path>` | 指定 yotta_verify.py 路径 |
 | `-h, --help` / `-v, --version` | 帮助 / 版本 |
 
@@ -169,8 +169,8 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 
 ## 工作原理
 
-对清单里每个技能：`npm pack <pkg>@<spec>` 到临时目录 → `tar -xzf` 解压 → 可选元信装前摘要 →
-替换 `<dest>/<slug>` → 汇总报告。`install` / `update` 完成后自动重扫本地技能注册表，
+对清单里每个技能：`npm pack <pkg>@<spec>` 到临时目录 → `tar -xzf` 解压 → 读取 manifest →
+元信装前门禁 → 快照旧版本并暂存新版本 → 原子替换 `<dest>/<slug>` → 汇总报告。`install` / `update` 完成后自动重扫本地技能注册表，
 新装技能随即出现在 `--inventory` / `--reindex` 里（可用 `--no-reindex` 关闭）。
 细节见 `references/install-flow.md`；新手中文教程见 `references/tutorial.md`。
 
@@ -181,7 +181,7 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 npm test
 ```
 
-测试覆盖 `--list`、临时目录安装断言、幂等、`--pin`、`update`、异常路径与元信 scan 集成
+测试覆盖 `--list`、临时目录安装断言、幂等、`--pin`、`update`、异常路径、manifest 校验、元信自举与装前门禁
 （用 fake npm 不联网）。
 
 ## 参考文档

package/SKILL.md

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

package/bin/yotta-skills.js

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

package/lib/install-evidence.js

@@ -0,0 +1,18 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function evidencePath(options) {
+  const home = (options && options.homeDir) || os.homedir();
+  return path.join(home, '.yottaskills', 'install-log.jsonl');
+}
+
+function appendEvidence(entry, options) {
+  const file = evidencePath(options);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+  return file;
+}
+
+module.exports = { evidencePath, appendEvidence };

package/lib/install-pipeline.js

@@ -0,0 +1,212 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const manifestLib = require('./manifest');
+const gateLib = require('./verify-gate');
+
+function nowTag() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function sleepSync(ms) {
+  const array = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(array, 0, 0, ms);
+}
+
+function renameWithRetry(from, to, options) {
+  const rename = (options && options.rename) || fs.renameSync;
+  const sleep = (options && options.sleep) || sleepSync;
+  let lastError;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return rename(from, to);
+    } catch (error) {
+      lastError = error;
+      if (!['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || attempt === 4) throw error;
+      sleep(100 * (attempt + 1));
+    }
+  }
+  throw lastError;
+}
+
+function isSafeTarEntry(entry) {
+  const value = String(entry || '').replace(/\\/g, '/');
+  if (value !== 'package' && !value.startsWith('package/')) return false;
+  if (value.startsWith('/') || /^[A-Za-z]:\//.test(value)) return false;
+  return !value.split('/').includes('..');
+}
+
+function copyTree(src, dst, copyDir) {
+  fs.rmSync(dst, { recursive: true, force: true });
+  fs.mkdirSync(dst, { recursive: true });
+  copyDir(src, dst);
+}
+
+function restoreBackup(target, backup) {
+  if (!backup || !fs.existsSync(backup)) return;
+  if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+  renameWithRetry(backup, target);
+}
+
+function createInstaller(deps) {
+  const homeDir = deps.homeDir || os.homedir();
+
+  function record(entry) {
+    return deps.appendEvidence(entry, { homeDir });
+  }
+
+  function safeRecord(entry) {
+    try {
+      return record(entry);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  return function installOne(skill, dest, opts) {
+    const target = path.join(dest, skill.slug);
+    const existingVersion = deps.readInstalledVersion(target);
+    if (!opts.force && existingVersion === skill.version) {
+      return { skill, status: 'skip', version: existingVersion, note: '已是最新', exitCode: 0 };
+    }
+
+    let tmp = null;
+    let staged = null;
+    let snapshot = null;
+    let backup = null;
+    try {
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'yotta-skills-'));
+      const packDir = path.join(tmp, 'pack');
+      fs.mkdirSync(packDir, { recursive: true });
+      const packed = deps.runNpmPack(skill, opts, packDir);
+      if (packed.error) {
+        safeRecord({ event: 'before_install', skill: skill.slug, decision: 'fail', error: packed.error });
+        return { skill, status: 'fail', version: null, note: packed.error, exitCode: 1 };
+      }
+
+      const extractDir = path.join(tmp, 'extract');
+      fs.mkdirSync(extractDir, { recursive: true });
+      const extracted = deps.extractTarball(packed.tarball, extractDir);
+      if (extracted.error) {
+        safeRecord({ event: 'before_install', skill: skill.slug, decision: 'fail', error: extracted.error });
+        return { skill, status: 'fail', version: packed.resolved, note: extracted.error, exitCode: 1 };
+      }
+
+      const resolvedSkill = { ...skill, version: packed.resolved || skill.version };
+      const loaded = manifestLib.loadManifest({ pkgDir: extracted.pkgDir, skill: resolvedSkill });
+      if (loaded.errors.length > 0) {
+        const note = loaded.errors.join('; ');
+        safeRecord({ event: 'manifest', skill: skill.slug, decision: 'block', errors: loaded.errors });
+        return { skill, status: 'fail', version: packed.resolved, note, exitCode: 6 };
+      }
+
+      let gate;
+      let scan;
+      if (opts.skipScan) {
+        gate = { ok: true, engine: null, mode: 'explicit-unverified' };
+        scan = { decision: 'unverified', verdict: null, counts: null, warn: true, mode: 'explicit-unverified' };
+      } else {
+        gate = deps.ensureGate({ skill, extracted, dest, opts });
+        if (!gate.ok) {
+          safeRecord({ event: 'before_install', skill: skill.slug, decision: 'block', error: gate.error });
+          return { skill, status: 'fail', version: packed.resolved, note: gate.error, exitCode: 5 };
+        }
+        const scanResult = deps.scanTarget(gate.engine, extracted.pkgDir);
+        if (!scanResult.ok) {
+          safeRecord({ event: 'before_install', skill: skill.slug, decision: 'block', error: scanResult.error });
+          return { skill, status: 'fail', version: packed.resolved, note: scanResult.error, exitCode: 5 };
+        }
+        const verdict = gateLib.evaluateVerdict(scanResult.verdict);
+        if (verdict.block) {
+          safeRecord({
+            event: 'before_install',
+            skill: skill.slug,
+            decision: 'block',
+            verdict: scanResult.verdict,
+            counts: scanResult.counts,
+          });
+          return {
+            skill,
+            status: 'fail',
+            version: packed.resolved,
+            note: '元信 verdict: ' + scanResult.verdict,
+            exitCode: 5,
+          };
+        }
+        scan = {
+          decision: verdict.decision,
+          verdict: scanResult.verdict,
+          counts: scanResult.counts,
+          warn: verdict.warn,
+        };
+      }
+
+      fs.mkdirSync(dest, { recursive: true });
+      const stagingRoot = path.join(dest, '.yottaskills-staging');
+      fs.mkdirSync(stagingRoot, { recursive: true });
+      staged = fs.mkdtempSync(path.join(stagingRoot, skill.slug + '-'));
+      copyTree(extracted.pkgDir, staged, deps.copyDir);
+
+      if (fs.existsSync(target)) {
+        const snapshotRoot = path.join(homeDir, '.yottaskills', 'snapshots', skill.slug);
+        fs.mkdirSync(snapshotRoot, { recursive: true });
+        snapshot = fs.mkdtempSync(path.join(snapshotRoot, nowTag() + '-' + (existingVersion || 'unknown') + '-'));
+        copyTree(target, snapshot, deps.copyDir);
+        backup = path.join(dest, '.yottaskills-backup-' + skill.slug + '-' + process.pid);
+        renameWithRetry(target, backup);
+      }
+
+      renameWithRetry(staged, target);
+      staged = null;
+
+      let evidence;
+      try {
+        evidence = record({
+          event: 'before_install',
+          skill: skill.slug,
+          package: skill.pkg,
+          version: packed.resolved || skill.version,
+          gate_mode: gate.mode,
+          bootstrap_scan: gate.mode === 'trusted-bootstrap' && skill.slug === 'yotta-verify' ? 'self' : null,
+          verdict: scan.verdict,
+          decision: scan.decision,
+          snapshot,
+        });
+      } catch (error) {
+        restoreBackup(target, backup);
+        backup = null;
+        return { skill, status: 'fail', version: packed.resolved, note: '证据写入失败: ' + error.message, exitCode: 1 };
+      }
+
+      if (backup && fs.existsSync(backup)) {
+        try {
+          fs.rmSync(backup, { recursive: true, force: true });
+        } catch (_) {
+          // The new version is already active; a stale backup is safer than a failed install.
+        }
+        backup = null;
+      }
+
+      return {
+        skill,
+        status: 'ok',
+        version: packed.resolved || skill.version,
+        note: null,
+        gate: { ...scan, mode: gate.mode },
+        evidence,
+        exitCode: 0,
+      };
+    } catch (error) {
+      restoreBackup(target, backup);
+      backup = null;
+      safeRecord({ event: 'install', skill: skill.slug, decision: 'fail', error: error.message });
+      return { skill, status: 'fail', version: null, note: error.message, exitCode: 1 };
+    } finally {
+      if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+      if (staged) fs.rmSync(staged, { recursive: true, force: true });
+    }
+  };
+}
+
+module.exports = { createInstaller, renameWithRetry, isSafeTarEntry };

package/lib/manifest.js

@@ -0,0 +1,131 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const MANIFEST_FILE = 'skill-manifest.json';
+
+function defaultManifest(skill) {
+  return {
+    manifestVersion: 1,
+    slug: skill.slug,
+    name: skill.name,
+    package: skill.pkg,
+    version: skill.version,
+    trust: 'yottameta',
+    install: {
+      idempotent: true,
+      network: 'registry',
+    },
+    permissions: {
+      filesystem: 'user-skills-dir',
+      network: 'registry',
+      process: 'child-process',
+      note: '仅调用本包内安装与自检脚本；默认无自定义脚本。',
+    },
+    auto_apply: {
+      mode: 'route',
+      note: '由元阁路由或用户显式调用。',
+    },
+  };
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function readSkillVersion(pkgDir) {
+  try {
+    const text = fs.readFileSync(path.join(pkgDir, 'SKILL.md'), 'utf8');
+    const match = text.match(/^version:\s*([0-9]+\.[0-9]+\.[0-9]+)/m);
+    return match ? match[1] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function isSafeRelativePath(value) {
+  if (typeof value !== 'string' || value.trim() === '') return false;
+  if (path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value)) return false;
+  const parts = value.split(/[\\/]+/);
+  return !parts.includes('..');
+}
+
+function validateManifest(manifest, context) {
+  const errors = [];
+  const skill = context.skill;
+  const pkgDir = context.pkgDir;
+  const required = ['manifestVersion', 'slug', 'name', 'package', 'version', 'trust', 'install', 'permissions'];
+  for (const key of required) {
+    if (manifest[key] === undefined) errors.push('缺少字段: ' + key);
+  }
+  if (manifest.manifestVersion !== 1) errors.push('manifestVersion 必须为 1');
+  if (manifest.slug !== skill.slug) errors.push('slug 与清单不一致');
+  if (manifest.package !== skill.pkg) errors.push('package 与清单不一致');
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(String(manifest.slug || ''))) errors.push('slug 格式非法');
+  if (!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/.test(String(manifest.version || ''))) {
+    errors.push('version 格式非法');
+  }
+  if (!['yottameta', 'third-party-verified', 'unknown'].includes(manifest.trust)) errors.push('trust 非法');
+  if (!manifest.install || manifest.install.idempotent !== true) errors.push('install.idempotent 必须为 true');
+  if (!manifest.permissions || typeof manifest.permissions !== 'object') errors.push('permissions 缺失');
+  if (manifest.permissions && !['none', 'user-skills-dir', 'project-dir', 'user-config', 'other'].includes(manifest.permissions.filesystem)) {
+    errors.push('permissions.filesystem 非法');
+  }
+  if (manifest.permissions && !['none', 'registry', 'allowlist', 'other'].includes(manifest.permissions.network)) {
+    errors.push('permissions.network 非法');
+  }
+
+  let packageMeta = null;
+  try {
+    packageMeta = readJson(path.join(pkgDir, 'package.json'));
+  } catch (error) {
+    errors.push('无法读取 package.json: ' + error.message);
+  }
+  if (packageMeta && packageMeta.name !== skill.pkg) errors.push('package.json.name 与清单不一致');
+  if (packageMeta && packageMeta.version !== manifest.version) {
+    errors.push('package.json.version 与 manifest.version 不一致');
+  }
+  const skillVersion = readSkillVersion(pkgDir);
+  if (skillVersion !== manifest.version) errors.push('SKILL.md.version 与 manifest.version 不一致');
+  for (const key of ['setup', 'doctor', 'rollback']) {
+    const rel = manifest.install && manifest.install[key];
+    if (rel !== undefined && !isSafeRelativePath(rel)) errors.push('install.' + key + ' 路径不安全');
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function loadManifest(context) {
+  const file = path.join(context.pkgDir, MANIFEST_FILE);
+  if (!fs.existsSync(file)) {
+    return {
+      manifest: defaultManifest(context.skill),
+      source: 'family-default',
+      errors: [],
+    };
+  }
+
+  let value;
+  try {
+    value = readJson(file);
+  } catch (error) {
+    return {
+      manifest: null,
+      source: 'package',
+      errors: ['无法解析 skill-manifest.json: ' + error.message],
+    };
+  }
+  const validation = validateManifest(value, context);
+  return {
+    manifest: value,
+    source: 'package',
+    errors: validation.errors,
+  };
+}
+
+module.exports = {
+  MANIFEST_FILE,
+  defaultManifest,
+  loadManifest,
+  validateManifest,
+  isSafeRelativePath,
+};

package/lib/verify-gate.js

@@ -0,0 +1,81 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const SAFE = 'SAFE TO INSTALL';
+const CAUTION = 'INSTALL WITH CAUTION';
+const REVIEW = 'REVIEW REQUIRED';
+const BLOCK = 'DO NOT INSTALL';
+
+function candidateVerifierPaths(dest, opts) {
+  const candidates = [];
+  if (opts && opts.verify) candidates.push(path.resolve(opts.verify));
+  if (process.env.YOTTA_SKILLS_VERIFY) candidates.push(path.resolve(process.env.YOTTA_SKILLS_VERIFY));
+  if (dest) candidates.push(path.join(dest, 'yotta-verify', 'scripts', 'yotta_verify.py'));
+  return candidates;
+}
+
+function findVerifier(context) {
+  const registry = context.registry;
+  const candidates = candidateVerifierPaths(context.dest, context.opts);
+  if (registry && registry.skills && registry.skills['yotta-verify']) {
+    for (const dir of registry.skills['yotta-verify'].source_dirs || []) {
+      candidates.push(path.join(dir, 'scripts', 'yotta_verify.py'));
+    }
+  }
+  for (const candidate of candidates) {
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch (_) {
+      // Try the next candidate.
+    }
+  }
+  return null;
+}
+
+function parseScanOutput(stdout) {
+  try {
+    const value = JSON.parse(String(stdout || ''));
+    if (!value || typeof value.verdict !== 'string') {
+      return { ok: false, verdict: null, counts: null, error: '扫描输出缺少 verdict' };
+    }
+    return { ok: true, verdict: value.verdict, counts: value.counts || {}, error: null };
+  } catch (error) {
+    return { ok: false, verdict: null, counts: null, error: error.message };
+  }
+}
+
+function evaluateVerdict(verdict) {
+  if (verdict === SAFE) return { decision: 'allow', block: false, warn: false };
+  if (verdict === CAUTION || verdict === REVIEW) return { decision: 'warn', block: false, warn: true };
+  return { decision: 'block', block: true, warn: true };
+}
+
+function runVerifier(engine, target, options) {
+  const result = options.spawnSync(options.python, ['-B', engine, 'scan', target, '--json'], {
+    encoding: 'utf8',
+    timeout: 60000,
+  });
+  if (result && result.error) {
+    return { ok: false, verdict: null, counts: null, error: result.error.message, exitCode: null };
+  }
+  if (!result || result.status === null) {
+    return { ok: false, verdict: null, counts: null, error: '元信 scan 执行失败', exitCode: null };
+  }
+  const parsed = parseScanOutput(result.stdout);
+  if (!parsed.ok) {
+    return { ok: false, verdict: null, counts: null, error: parsed.error, exitCode: result.status };
+  }
+  return { ok: true, verdict: parsed.verdict, counts: parsed.counts, error: null, exitCode: result.status };
+}
+
+module.exports = {
+  SAFE,
+  CAUTION,
+  REVIEW,
+  BLOCK,
+  findVerifier,
+  parseScanOutput,
+  evaluateVerdict,
+  runVerifier,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [

package/references/faq.md

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

package/references/install-flow.md

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

package/references/skill-list.md

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

package/references/tutorial.md

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

package/scripts/yotta-skills-mcp.py

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

package/skills.json

@@ -28,7 +28,7 @@
       "slug": "yotta-memory",
       "name": "元忆",
       "pkg": "@yottameta/yotta-memory",
-      "version": "0.11.0",
+      "version": "0.12.1",
       "desc": "有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT）"
     },
     {