@yottameta/yotta-skills-plugin 0.7.2 → 0.19.0

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.7.2",
+      "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.7.2",
+      "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.7.2",
+  "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.7.2",
+  "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.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.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` 附扫项目级目录 |
@@ -132,14 +148,30 @@ 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 路径 |
+| `--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 和本地注册表，得到一组可执行建议：
@@ -235,12 +302,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 +328,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） |