@yottameta/yotta-skills 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v0.24.0 (2026-10-02)
+
+- 接管能力补缺口（A 无 npm 拉包 / B 依赖人话提示 / C 范围控制 / D 行为回归）：
+- A 内置拉包 / 解包：新增 `lib/registry-fetch.js`（Node 内置 https 直连 registry：abbreviated packument + 版本解析 + tarball 下载 + `integrity`(sha512) / `shasum`(sha1) fail-closed 校验 + `HTTPS_PROXY` / `HTTP_PROXY` CONNECT 隧道）与 `lib/untar.js`（zlib + ustar / pax / GNU 长名解析；路径越界与链接条目 fail-closed）；默认内置为主，npm 与系统 tar 仅作回退通道，`YOTTA_SKILLS_FETCH` / `YOTTA_SKILLS_EXTRACT` 可强制单通道；安装证据新增 `fetch_channel` / `extract_channel`。
+- B 依赖统一提示：新增 `lib/deps.js` 人话模板（需要什么 / 为什么 / 一条修复命令 / 不影响使用），接入拉包失败、缺 Python、双通道解包失败与 Node 版本检查；`doctor` 新增 `dependencies` 自检块（text + `--json`，只告警不失败）；顺手修 `--python` 旗标在扫描路径被忽略。
+- C 范围控制：`skills.json` 每条技能新增 `domain`（对齐家族索引 9 类），`references/skill-list.md` 同步补列；新增 `--only` / `--domain` 与 `update --installed-only`。接管语义：只维护目标目录已安装的家族技能，`skills.json` 只作身份 / 版本参照；未装不动作、不新增、不报错；已管理且已最新跳过（退出码 0）；无旗标时 install / update 语义不变。
+- D 回归与文档：新增 `test/update-scope.test.js` / `domain-filter.test.js` / `fetch-builtin.test.js` / `deps-message.test.js` / `python-flag.test.js`（含 PATH 隔离的 Node-only 端到端）；`references/install-flow.md` 补双通道流程、依赖矩阵与范围语义矩阵；`SKILL.md` / README 中英同步。
+
+## v0.23.3 (2026-10-01)
+
+- 安装器卫生批次：`install.sh` 统一（未知参数报错 exit 2、`--help` / `--version`、残留清理白名单）；`skills.json` 清单 pin 同步 27 项。
+
 ## v0.23.2 (2026-10-01)
 
 - 修复家族安装管线嵌套载荷丢失：复制原语的顶层跳过名单（`package.json` / `bin` / `node_modules` / `.git`）此前按条目名逐层生效，会把技能包内嵌套的同名载荷（如元造 `template/package.json`、`template/bin/install.js`）一并跳过——家族安装 / 更新元造后，其脚手架自检会失败（缺必需文件）。现改为仅顶层生效，与元造 0.1.3 的安装器修复对齐。

package/README.md

@@ -31,6 +31,7 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 - **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; <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).
+- **Works without npm** — fetching and extraction default to built-in Node channels (npm / system tar are fallbacks only); <code>update --installed-only</code> adopts only skills already installed on the machine and never backfills or errors on missing ones.
 - **Doctor / rollback** — <code>doctor</code> checks the installed skill directory, version, manifest, registry and custom doctor script without modifying it; <code>--dir</code> may point to a skills container or directly to a single skill package. <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.
@@ -67,6 +68,9 @@ 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
 
+# Adopt only the family skills already installed on this machine (no backfill)
+npx -y @yottameta/yotta-skills update --installed-only --dir ~/my-skills
+
 # Read-only health check (optionally with --slug / --json)
 npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --slug yotta-memory
 

package/README.zh-CN.md

@@ -38,6 +38,7 @@
 - **运行时 hook 适配层**——技能 manifest 只声明六个生命周期要求；<code>hook capabilities / evaluate / bind / unbind</code> 负责宿主能力探测、确定性决策、结构化证据和降级标注，不把 audit 能力夸大为强制。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前门禁**——家族安装先读取包内 manifest，元信（yotta-verify）缺失时自动自举，再逐个扫描。`DO NOT INSTALL` 阻断；`CAUTION` / `REVIEW` 继续但显示风险。旧版本会先做快照再替换。
+- **无 npm 也能接管**——拉包与解包默认走 Node 内置通道（npm / 系统 tar 仅作回退）；`update --installed-only` 只接管机器内已安装的元技能，不补装、不新增、不报错。
 - **盘点 / re-index**--扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</code>）；可用 <code>YOTTA_SKILLS_REGISTRY_FILE</code> 为不同 agent 指定独立注册表；自包含，不需要任何其他技能。新装技能自动被发现：<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>decide_memory</code> 五工具，配置见 <code>SKILL.md</code>。
 
 边界：只做「下载 + 落位 + 门禁 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
@@ -70,6 +71,9 @@ npx -y @yottameta/yotta-skills update --check --scheduled
 # 检查后自动更新已装元阁家族（含装前门禁；非元阁家族技能不自动更新）
 npx -y @yottameta/yotta-skills update --auto
 
+# 只接管机器内已装的元技能（不补装缺失；清单只作身份 / 版本参照）
+npx -y @yottameta/yotta-skills update --installed-only --dir ~/my-skills
+
 # 只读检查已装技能（可加 --slug / --json）
 npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --slug yotta-memory
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.23.2
+version: 0.24.0
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；M1 记忆裁决层：usage enable/mark 本地结构化记录 + decide-memory / MCP decide_memory 输出 promote / hold / demote 只读建议（需授权 provider；只建议不删除、不自动写元忆）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么组合使用（安装与调用均由用户确认后执行）」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录（默认 --pin 锁死清单精确版本）；盘点层：--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/decide_memory，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / usage 使用记录 / decide-memory 记忆裁决 / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin（默认）/ --range。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、判断哪些技能值得长期记忆、查看或记录技能使用信号、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/记忆裁决/技能该不该记住/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + M1 记忆裁决只读建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆、不自动删除技能或记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
@@ -163,6 +163,7 @@ openclaw skills update @yottameta/yotta-skills
 | `install --dir <path>` | 装全家到指定目录，每个技能落在 `<path>/<slug>` |
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
+| `update --installed-only [--agent <name> \| --dir <path>]` | 只维护目标目录**已安装**的家族技能（不补装缺失；无匹配时退出码 0）——接管现有元技能的标准配方 |
 | `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-* 自家家族，含装前安全扫描） |
@@ -184,6 +185,9 @@ openclaw skills update @yottameta/yotta-skills
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
 | `--skip-scan` | 人工应急路径：跳过元信门禁并标记 `explicit-unverified`；不得用于 `update --auto` |
+| `--only <a,b>` | install / update 只处理指定技能（与位置参数技能列表合并去重） |
+| `--domain <name>` | install / update 只处理指定家族（security / quality / memory / writing / workflow / entry / compliance / education / distribution） |
+| `--installed-only` | update 只维护目标目录已安装的技能（不补装缺失；无匹配时退出码 0） |
 | `--npm <path>` | 指定 npm 可执行文件 |
 | `--python <path>` | 指定 python 可执行文件（元信 scan 用） |
 | `--verify <path>` | 指定 yotta_verify.py 路径 |
@@ -192,6 +196,22 @@ openclaw skills update @yottameta/yotta-skills
 
 不带命令直接给技能名时，等价于 `install <skill>`。
 
+### 范围控制（接多少管多少）
+
+| 用法 | 范围 |
+|---|---|
+| `install` / `update`（无旗标） | 全量清单：install 安装全部；update 补齐缺失 + 升级已装（现状语义不变） |
+| `update --installed-only` | 只维护目标目录已安装的家族技能（不补装缺失；`skills.json` 只作身份 / 版本参照） |
+| `--only <a,b>` / `--domain <name>` | 只处理指定技能 / 家族（可与 `--installed-only` 取交集） |
+| `update --check` / `--auto` | 只检查 / 维护已装技能，不补装缺失 |
+
+已管理且已最新 → 跳过（退出码 0）；清单内但机器未装 → 不动作、不新增、不报错；
+非家族 / 未收录目录 → 忽略不报错。标准接管配方：
+
+```bash
+npx -y @yottameta/yotta-skills update --installed-only --dir <技能目录>
+```
+
 ## 运行时 hook 适配层
 
 技能 manifest 只声明六个统一事件的要求，元阁负责能力探测、确定性评估、证据留痕和降级标注：
@@ -407,6 +427,18 @@ npx -y @yottameta/yotta-skills usage reset --yes
 `workbuddy` `kiro` `trae` `trae-cn` `qwen` `comate` `codebuddy` `kimi` `agents`。
 未收录的智能体请用 `--dir` 指定其技能目录（`.agents/skills` 不是通用目录）。
 
+## 依赖与回退链
+
+| 依赖 | 角色 | 缺失时 |
+|---|---|---|
+| Node.js 18+ | 必需（CLI 本体） | 明确提示 + 按平台给安装命令 |
+| npm | 拉包**回退通道** | 不影响：内置拉包为主 |
+| 系统 tar | 解包**回退通道** | 不影响：内置解包为主 |
+| Python 3.8+ | 元信装前扫描 | 门禁阻断；优先用 `--python` / `YOTTA_SKILLS_PYTHON` 指向宿主自带 Python（如 YottaCode），确实没有时用 `--skip-scan` 应急（`explicit-unverified`） |
+
+缺依赖时按需给出「需要什么 / 为什么 / 一条修复命令 / 不影响使用」人话提示，不常驻提醒；
+`doctor` 的依赖自检块只告警不失败。
+
 ## 环境变量
 
 | 变量 | 作用 |
@@ -414,6 +446,9 @@ npx -y @yottameta/yotta-skills usage reset --yes
 | `YOTTA_SKILLS_NPM` | 指定 npm 可执行文件（同 `--npm`） |
 | `YOTTA_SKILLS_NPM_FLAGS` | 追加传给 `npm pack` 的参数（按空白拆分，如 `--registry=...`） |
 | `YOTTA_SKILLS_NO_FALLBACK` | 设为 `1` 时禁用「默认源 404 → 官方源重试」的自动回退 |
+| `YOTTA_SKILLS_FETCH` | 拉包通道：`builtin`（仅内置）/ `npm`（仅 npm）；缺省内置为主、失败回退 npm |
+| `YOTTA_SKILLS_EXTRACT` | 解包通道：`builtin`（仅内置）/ `tar`（仅系统 tar）；缺省内置为主、失败回退系统 tar |
+| `YOTTA_SKILLS_REGISTRY` | registry 地址（默认 `https://registry.npmjs.org/`；内置拉包与更新检查共用；支持 `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`） |
 | `YOTTA_SKILLS_PYTHON` | 指定 python 可执行文件（元信 scan 用，同 `--python`） |
 | `YOTTA_SKILLS_VERIFY` | 指定 yotta_verify.py 路径（同 `--verify`） |
 | `YOTTA_SKILLS_MANIFEST` | 指定技能清单 JSON 路径（默认随包 skills.json） |

package/bin/yotta-skills.js

@@ -16,7 +16,8 @@
  *   npx -y @yottameta/yotta-skills --dry-run              # 预览将安装清单（不联网、不改动）
  *
  * 版本策略：默认 `--pin` 锁死清单精确版本（可复现，不静默跟随浮动版本）；`--range` 才跟随同 major 最新 patch。
- * 依赖：Node.js 18+；npm（pack）；系统 tar（解压）；元信 scan 可选（装了 yotta-verify 自动启用）。
+ * 依赖：Node.js 18+（必需）；npm / 系统 tar 仅作回退通道（内置拉包 / 内置解包为主）；
+ *       元信 scan 需要 Python 3.8+（可 --python / YOTTA_SKILLS_PYTHON 指向宿主自带 Python）。
  * 边界：只做「清单 + 下载 + 落位 + 汇总」；不内置任何技能本体；不 -g 污染。
  */
 'use strict';
@@ -41,11 +42,14 @@ const usageJournalLib = require('../lib/usage-journal');
 const m1FeaturesLib = require('../lib/m1-features');
 const routeFeaturesLib = require('../lib/route-features');
 const routeDynamicLib = require('../lib/route-dynamic');
+const depsLib = require('../lib/deps');
+const untarLib = require('../lib/untar');
+const registryFetchLib = require('../lib/registry-fetch');
 const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 const { COPY_SKIP, copyDir } = require('../lib/copy-tree');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.23.2';
+let VERSION = '0.24.0';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -113,6 +117,12 @@ function out(s) { process.stdout.write(s + '\n'); }
 
 function tarBin() { return 'tar'; }
 
+/** 供依赖提示复制的「原命令」回显（尽力还原参数，仅作提示用）。 */
+function currentCommand() {
+  const args = process.argv.slice(2).map((a) => (/\s/.test(a) ? '"' + a + '"' : a));
+  return 'yotta-skills ' + args.join(' ');
+}
+
 // 解析 npm 调用方式（Windows 的 .cmd 不能直接 spawn：EINVAL；cmd /c 引号脆弱）。
 // 最优：定位 npm.cmd -> 读内容 -> 提取 node_modules/npm/bin/npm-cli.js -> 用 node 直接执行。
 // 兼容：--npm / YOTTA_SKILLS_NPM 可指向 .js（node 执行）、.cmd（同样解析）、或可执行文件。
@@ -159,6 +169,7 @@ function parseArgs(argv) {
     check: false, auto: false, scheduled: false, registry: null, slug: null,
     host: null, event: null, manifest: null, context: null,
     signal: null, yes: false, explain: false, promote: false,
+    only: [], domain: null, installedOnly: false,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
@@ -199,6 +210,15 @@ function parseArgs(argv) {
     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 === '--only') {
+      const value = take('--only');
+      for (const item of value.split(',')) {
+        const slug = item.trim().toLowerCase();
+        if (slug) opts.only.push(slug);
+      }
+    }
+    else if (a === '--domain') opts.domain = take('--domain').toLowerCase();
+    else if (a === '--installed-only') opts.installedOnly = true;
     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');
@@ -227,6 +247,12 @@ function parseArgs(argv) {
   if (opts.scheduled && (opts.command !== 'update' || !opts.check || opts.auto)) {
     die('--scheduled 只能与 update --check 一起使用', 2, '请使用 update --check --scheduled；自动更新不使用后台调度入口。');
   }
+  if (opts.installedOnly && opts.command !== 'update') {
+    die('--installed-only 只能与 update 一起使用', 2, '标准配方：yotta-skills update --installed-only --dir <技能目录>。');
+  }
+  if (opts.domain && !domainValues().includes(opts.domain)) {
+    die('未知 domain: ' + opts.domain + '。可用: ' + domainValues().join(', '), 2, 'domain 对齐家族索引 9 类；用 yotta-skills --list 查看技能清单。');
+  }
   return opts;
 }
 
@@ -240,15 +266,39 @@ function specOf(s, pin) {
 function findSkill(slug) {
   return MANIFEST.find(s => s.slug === slug || s.pkg === slug || s.pkg.replace('@yottameta/', '') === slug);
 }
+
+const KNOWN_DOMAINS = ['security', 'quality', 'memory', 'writing', 'workflow', 'entry', 'compliance', 'education', 'distribution'];
+
+function domainValues() {
+  const values = new Set(KNOWN_DOMAINS);
+  for (const s of MANIFEST) if (s.domain) values.add(s.domain);
+  return [...values].sort();
+}
+
 function selectSkills(opts) {
-  if (opts.skills.length === 0) return MANIFEST;
   const picked = [];
+  const seen = new Set();
+  const push = (s) => {
+    if (!seen.has(s.slug)) {
+      seen.add(s.slug);
+      picked.push(s);
+    }
+  };
   for (const slug of opts.skills) {
     const s = findSkill(slug);
     if (!s) die('未知技能: ' + slug + '（可用: yotta-skills --list）', 2, '请先运行 --list 查看技能名，或检查拼写。');
-    picked.push(s);
+    push(s);
+  }
+  for (const slug of opts.only || []) {
+    const s = findSkill(slug);
+    if (!s) die('未知技能（--only）: ' + slug + '（可用: yotta-skills --list）', 2, '请先运行 --list 查看技能名，或检查拼写。');
+    push(s);
   }
-  return picked;
+  let list = picked.length > 0 ? picked : MANIFEST.slice();
+  if (opts.domain) {
+    list = list.filter((s) => s.domain === opts.domain);
+  }
+  return list;
 }
 
 function readInstalledVersion(dir) {
@@ -577,19 +627,24 @@ function findPython(opts) {
   return null;
 }
 
-function runScan(engine, skillDir) {
-  const python = findPython({});
-  if (!python) return { ok: false, error: '未找到 Python（元信 scan 需要 Python 3.8+）' };
+function runScan(engine, skillDir, opts) {
+  const python = findPython(opts || {});
+  if (!python) {
+    return {
+      ok: false,
+      error: depsLib.describe('python', { command: currentCommand(), missing: true }),
+    };
+  }
   return gateLib.runVerifier(engine, skillDir, { python, spawnSync });
 }
 
 function scanTarget(engine, skillDir, context) {
-  const scan = runScan(engine, skillDir);
+  const ctx = context || {};
+  const scan = runScan(engine, skillDir, ctx.opts);
   if (!scan.ok) {
     out('  元信 scan: ' + scan.error);
     return scan;
   }
-  const ctx = context || {};
   const reviewed = scanPolicyLib.applyScanPolicy(scan, {
     slug: ctx.slug,
     version: ctx.version,
@@ -612,18 +667,75 @@ function scanTarget(engine, skillDir, context) {
   return reviewed;
 }
 
+/** doctor 依赖自检（只告警不失败）：node / npm / python / tar 四项。 */
+function probeDependencies(opts) {
+  const npm = resolveNpm(opts);
+  const npmProbe = spawnSync(npm.bin, [...npm.prefix, '--version'], {
+    encoding: 'utf8',
+    timeout: 15000,
+    shell: npm.shell,
+  });
+  const python = findPython(opts);
+  const pythonProbe = python
+    ? spawnSync(python, ['--version'], { encoding: 'utf8', timeout: 15000 })
+    : null;
+  const tarProbe = spawnSync(tarBin(), ['--version'], { encoding: 'utf8', timeout: 15000 });
+  return depsLib.dependencyReport({
+    node: depsLib.nodeCheck(),
+    npm: { found: !!(npmProbe && npmProbe.status === 0), version: depsLib.versionLine(npmProbe) },
+    python: { found: !!python, version: depsLib.versionLine(pythonProbe), path: python || null },
+    tar: { found: !!(tarProbe && tarProbe.status === 0), version: depsLib.versionLine(tarProbe) },
+  });
+}
+
 // ── 安装 ───────────────────────────────────────────────────────────────────
 const runNpmPackBase = npmPackLib.createPackRunner({ spawnSync, specOf, resolveNpm });
 
+function fetchMode() {
+  const raw = String(process.env.YOTTA_SKILLS_FETCH || 'auto').trim().toLowerCase();
+  return raw === 'builtin' || raw === 'npm' ? raw : 'auto';
+}
+
+function extractMode() {
+  const raw = String(process.env.YOTTA_SKILLS_EXTRACT || 'auto').trim().toLowerCase();
+  return raw === 'builtin' || raw === 'tar' ? raw : 'auto';
+}
+
+/**
+ * 拉包：默认内置通道（Node 内置 https，零 npm），失败回退 npm pack。
+ * YOTTA_SKILLS_FETCH=builtin 禁用回退；=npm 直接走 npm（显式选择 / 离线测试）。
+ */
 function runNpmPack(skill, opts, packDir) {
+  const mode = fetchMode();
+  let builtin = null;
+  if (mode !== 'npm') {
+    builtin = registryFetchLib.fetchPackageSync(skill, opts, packDir);
+    if (!builtin.error) return builtin;
+  }
+  if (mode === 'builtin') {
+    return { error: '内置拉包失败（YOTTA_SKILLS_FETCH=builtin 已禁用 npm 回退）: ' + builtin.error };
+  }
   const packed = runNpmPackBase(skill, opts, packDir);
+  if (packed.error) {
+    const detail = packed.detail || packed.error;
+    let message = '拉包失败（内置 + npm 双通道）: 内置=' + (builtin ? builtin.error : '未启用') + '；npm=' + packed.error;
+    if (depsLib.isNpmMissing(detail)) {
+      message += '\n' + depsLib.describe('npm', { command: currentCommand(), missing: true });
+    }
+    return { error: message, detail };
+  }
+  packed.channel = 'npm';
+  if (builtin) {
+    packed.fallbackFrom = builtin.error;
+    out('  ↳ 拉包通道：内置失败（' + builtin.error + '）→ npm 回退成功');
+  }
   if (packed.registryFallback) {
     out('  ↳ npm 默认源 404，已用官方源重试成功（' + npmPackLib.OFFICIAL_REGISTRY + '）');
   }
   return packed;
 }
 
-function extractTarball(tarball, extractDir) {
+function extractWithSystemTar(tarball, extractDir) {
   const packDir = path.dirname(tarball);
   const tarballName = path.basename(tarball);
   fs.mkdirSync(extractDir, { recursive: true });
@@ -643,6 +755,34 @@ function extractTarball(tarball, extractDir) {
   return { pkgDir };
 }
 
+/**
+ * 解包：默认内置（zlib + tar 解析），失败回退系统 tar；
+ * YOTTA_SKILLS_EXTRACT=builtin 禁用回退；=tar 直接走系统 tar。
+ */
+function extractTarball(tarball, extractDir) {
+  const mode = extractMode();
+  let builtin = null;
+  if (mode !== 'tar') {
+    builtin = untarLib.extractTarballBuiltin(tarball, extractDir);
+    if (!builtin.error) return builtin;
+  }
+  if (mode === 'builtin') {
+    return { error: '内置解包失败（YOTTA_SKILLS_EXTRACT=builtin 已禁用 tar 回退）: ' + builtin.error };
+  }
+  const fallback = extractWithSystemTar(tarball, extractDir);
+  if (fallback.error) {
+    const message = '解包失败（内置 + 系统 tar 双通道）: 内置=' + (builtin ? builtin.error : '未启用') + '；tar=' + fallback.error +
+      '\n' + depsLib.describe('tar', { command: currentCommand(), missing: true });
+    return { error: message };
+  }
+  if (builtin) {
+    out('  ↳ 解包通道：内置失败（' + builtin.error + '）→ 系统 tar 回退成功');
+    fallback.fallbackFrom = builtin.error;
+  }
+  fallback.channel = 'tar';
+  return fallback;
+}
+
 function ensureGate(context) {
   const { skill, extracted, dest, opts } = context;
   const current = findVerifyEngine(dest, opts);
@@ -707,6 +847,11 @@ const installOne = createInstaller({
 
 function runInstall(opts, dest) {
   const skills = selectSkills(opts);
+  if (skills.length === 0) {
+    out('过滤后没有匹配的技能（--only / --domain），未执行任何操作。');
+    process.exitCode = 2;
+    return { failed: 1, exitCode: 2 };
+  }
   out('yotta-skills（元阁）v' + VERSION + ' —— 安装 ' + skills.length + ' 个技能 -> ' + dest);
   out('版本策略: ' + (opts.pin ? 'pin（锁死清单精确版本，默认）' : 'range（' + skillRange(skills[0]) + '，跟随最新 patch）'));
   const results = [];
@@ -738,8 +883,21 @@ function runInstall(opts, dest) {
 }
 
 function runUpdate(opts, dest) {
-  const skills = selectSkills(opts);
+  let skills = selectSkills(opts);
   out('yotta-skills（元阁）v' + VERSION + ' —— 增量更新 -> ' + dest);
+  if (opts.installedOnly) {
+    const candidates = skills.length;
+    skills = skills.filter((s) => readInstalledVersion(path.join(dest, s.slug)) !== null);
+    out('范围: 仅已安装技能（--installed-only；候选 ' + candidates + ' / 已装 ' + skills.length + '）');
+    if (skills.length === 0) {
+      out('目标目录未发现已安装的元阁家族技能，无动作（退出码 0）。');
+      return { failed: 0, exitCode: 0 };
+    }
+  } else if (skills.length === 0) {
+    out('过滤后没有匹配的技能（--only / --domain），未执行任何操作。');
+    process.exitCode = 2;
+    return { failed: 1, exitCode: 2 };
+  }
   const results = [];
   let failed = 0;
   let exitCode = 0;
@@ -920,6 +1078,7 @@ function runDoctor(opts, dest) {
     fixes.push.apply(fixes, result.fixes);
   }
 
+  const dependencies = probeDependencies(opts);
   const payload = {
     ok: errors.length === 0,
     dir: dest,
@@ -928,6 +1087,7 @@ function runDoctor(opts, dest) {
     errors,
     warnings,
     fixes: Array.from(new Set(fixes)),
+    dependencies,
   };
   const code = doctorExitCode(payload);
   if (opts.json) {
@@ -942,6 +1102,15 @@ function runDoctor(opts, dest) {
         out('  ' + (check.ok ? '✔' : '✘') + ' ' + check.message + (check.hint ? '（修复: ' + check.hint + '）' : ''));
       }
     }
+    out('');
+    out('依赖自检（只告警不失败）:');
+    for (const dep of dependencies) {
+      const mark = dep.ok ? '✔' : (dep.optional ? '△' : '✘');
+      out('  ' + mark + ' ' + dep.name + (dep.version ? ' ' + dep.version : '') +
+        '（需要 ' + dep.need + (dep.optional ? '；回退通道，可选' : '') + '）' +
+        (dep.ok ? '' : ' —— 影响：' + dep.why));
+      if (!dep.ok && dep.fix) out('      修复：' + dep.fix);
+    }
     for (const item of warnings) out('[警告] ' + item);
     for (const item of fixes) out('[建议] ' + item);
     if (!payload.ok) out('doctor 未通过：请按上面的修复建议处理后重试。');
@@ -1121,6 +1290,7 @@ 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 --installed-only --dir <path>  只维护已装技能（接管现有元技能的标准配方）');
   out('  yotta-skills update --check         只读联网检查更新（退出码 0/3/1）');
   out('  yotta-skills update --check --scheduled  后台周检（未到期不联网；到期单次检查并写缓存）');
   out('  yotta-skills doctor --dir <path>    只读自检技能目录（可加 --slug / --json）');
@@ -1144,6 +1314,9 @@ function printHelp() {
   out('  --range          跟随同 major 最新 patch（非默认：显式指定后才浮动跟随）');
   out('  --force          已是最新也重装');
   out('  --skip-scan      跳过元信装前 scan（装了 yotta-verify 自动启用）');
+  out('  --only <a,b>     install / update 只处理指定技能（与位置参数技能列表合并去重）');
+  out('  --domain <name>  install / update 只处理指定家族（security / quality / memory / writing / workflow / entry / compliance / education / distribution）');
+  out('  --installed-only update 只维护目标目录已安装的技能（不补装缺失；无匹配时退出码 0）');
   out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
   out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
   out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
@@ -1169,7 +1342,8 @@ function printHelp() {
   out('  -v, --version    版本');
   out('');
   out('支持智能体: ' + Object.keys(AGENT_DIRS).join(', '));
-  out('依赖: Node.js 18+ / npm / 系统 tar；环境变量 YOTTA_SKILLS_NPM / YOTTA_SKILLS_PYTHON / YOTTA_SKILLS_VERIFY / YOTTA_SKILLS_NPM_FLAGS / YOTTA_SKILLS_REGISTRY_FILE 可覆盖。');
+  out('依赖: Node.js 18+（必需）；npm 与系统 tar 为回退通道（内置拉包 / 内置解包为主）；元信 scan 需要 Python 3.8+（--python / YOTTA_SKILLS_PYTHON 可指向宿主自带 Python）。');
+  out('环境变量: YOTTA_SKILLS_FETCH（builtin|npm）/ YOTTA_SKILLS_EXTRACT（builtin|tar）/ YOTTA_SKILLS_NPM / YOTTA_SKILLS_PYTHON / YOTTA_SKILLS_VERIFY / YOTTA_SKILLS_NPM_FLAGS / YOTTA_SKILLS_REGISTRY / YOTTA_SKILLS_REGISTRY_FILE / YOTTA_SKILLS_MANIFEST 可覆盖。');
 }
 
 
@@ -1628,6 +1802,11 @@ function runHook(opts) {
 
 // ── main ───────────────────────────────────────────────────────────────────
 function main() {
+  const node = depsLib.nodeCheck();
+  if (!node.ok) {
+    die('需要 Node 18+（用途：运行元阁 CLI 本体；当前 v' + node.version + '）', 4,
+      depsLib.fixFor('node') + '；装好后重跑：' + currentCommand());
+  }
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { printHelp(); return; }
   if (opts.version) { out('yotta-skills v' + VERSION); return; }
@@ -1660,7 +1839,17 @@ function main() {
   }
 
   if (opts.dryRun) {
-    const skills = selectSkills(opts);
+    let skills = selectSkills(opts);
+    if (command === 'update' && opts.installedOnly && dest) {
+      skills = skills.filter((s) => readInstalledVersion(path.join(dest, s.slug)) !== null);
+    }
+    if (skills.length === 0) {
+      out(opts.installedOnly
+        ? 'dry-run：目标目录没有可维护的已安装家族技能（无动作）。'
+        : 'dry-run：过滤后没有匹配的技能（--only / --domain）。');
+      process.exitCode = opts.installedOnly ? 0 : 2;
+      return;
+    }
     out('yotta-skills（元阁）v' + VERSION + ' —— dry-run（' + command + '，' + skills.length + ' 个技能）');
     out('目标: ' + (dest || '未指定（将检测项目级目录）'));
     out('版本策略: ' + (opts.pin ? 'pin（锁死）' : 'range（' + skillRange(skills[0]) + '）'));