@yottameta/yotta-skills-plugin 0.23.3 → 0.24.0

package/skills/yotta-skills/lib/registry-fetch.js

@@ -0,0 +1,448 @@
+'use strict';
+/**
+ * lib/registry-fetch.js —— 无 npm 内置拉包通道（元阁 0.24.0，方案 A.1）。
+ *
+ * 零依赖：Node 内置 https/http 直连 registry，abbreviated packument 解析版本，
+ * tarball 下载 + integrity(sha512) / shasum(sha1) fail-closed 校验；
+ * 支持 HTTPS_PROXY / HTTP_PROXY（CONNECT 隧道简实现）与 NO_PROXY。
+ *
+ * 同步入口 fetchPackageSync 供安装管线（同步契约）使用：通过子进程执行同一套
+ * 异步核心（lib/registry-fetch-child.js），stdin/stdout 传 JSON，不落任何状态。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const tls = require('tls');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const OFFICIAL_REGISTRY = 'https://registry.npmjs.org/';
+const DEFAULT_TIMEOUT = 15000;
+const DEFAULT_DOWNLOAD_TIMEOUT = 120000;
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const INTEGRITY_RANK = { sha512: 1, sha384: 2, sha256: 3, sha1: 4 };
+
+function registryBase(opts) {
+  const raw = (opts && opts.registry) || process.env.YOTTA_SKILLS_REGISTRY || OFFICIAL_REGISTRY;
+  return String(raw).replace(/\/+$/, '') + '/';
+}
+
+function packumentUrl(pkg, opts) {
+  return registryBase(opts) + String(pkg).replace(/\//g, '%2f');
+}
+
+function tarballName(pkg, version) {
+  const parts = String(pkg).replace(/^@/, '').split('/');
+  const scope = parts.length > 1 ? parts[0] : '';
+  const bare = parts.length > 1 ? parts[1] : parts[0];
+  return (scope ? scope + '-' : '') + bare + '-' + version + '.tgz';
+}
+
+function majorRange(version) {
+  return String(version).split('.')[0] + '.x';
+}
+
+function compareSemver(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x - y;
+  }
+  return 0;
+}
+
+function parseIntegrity(value) {
+  const entries = String(value || '')
+    .split(/\s+/)
+    .map((token) => {
+      const match = token.match(/^(sha512|sha384|sha256|sha1)-(.+)$/);
+      return match ? { algo: match[1], base64: match[2] } : null;
+    })
+    .filter(Boolean);
+  if (!entries.length) return null;
+  entries.sort((a, b) => INTEGRITY_RANK[a.algo] - INTEGRITY_RANK[b.algo]);
+  return entries[0];
+}
+
+function noProxyMatch(hostname) {
+  const raw = process.env.NO_PROXY || process.env.no_proxy || '';
+  if (!raw) return false;
+  const host = String(hostname || '').toLowerCase();
+  return String(raw)
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean)
+    .some((entry) => {
+      if (entry === '*') return true;
+      const clean = entry.replace(/^\./, '').replace(/:\d+$/, '');
+      return host === clean || host.endsWith('.' + clean);
+    });
+}
+
+function proxyFor(url) {
+  if (noProxyMatch(url.hostname)) return null;
+  const raw = url.protocol === 'https:'
+    ? (process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy)
+    : (process.env.HTTP_PROXY || process.env.http_proxy);
+  if (!raw) return null;
+  try {
+    const parsed = new URL(/^[a-z]+:\/\//i.test(raw) ? raw : 'http://' + raw);
+    return { hostname: parsed.hostname, port: Number(parsed.port) || 80 };
+  } catch (_) {
+    return null;
+  }
+}
+
+function tunneledAgent(socket) {
+  const agent = new https.Agent({ keepAlive: false });
+  agent.createConnection = function createConnection(options, callback) {
+    if (typeof callback === 'function') callback(null, socket);
+    return socket;
+  };
+  return agent;
+}
+
+function requestStreamOnce(rawUrl, opts) {
+  return new Promise((resolve) => {
+    let url;
+    try {
+      url = new URL(rawUrl);
+    } catch (error) {
+      resolve({ ok: false, error: 'URL 解析失败: ' + error.message });
+      return;
+    }
+    const options = opts || {};
+    const timeoutMs = options.timeoutMs || DEFAULT_TIMEOUT;
+    const headers = Object.assign(
+      { 'user-agent': 'yotta-skills-fetch', accept: '*/*' },
+      options.headers || {},
+    );
+    const proxy = proxyFor(url);
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const fail = (error) => done({ ok: false, error: '网络错误: ' + ((error && error.message) || error) });
+    const arm = (req) => {
+      req.on('error', fail);
+      req.setTimeout(timeoutMs, () => req.destroy(new Error('网络超时（' + timeoutMs + 'ms）')));
+    };
+
+    if (url.protocol === 'https:' && proxy) {
+      const target = url.hostname + ':' + (url.port || 443);
+      const connectReq = http.request({
+        host: proxy.hostname,
+        port: proxy.port,
+        method: 'CONNECT',
+        path: target,
+        headers: { host: target },
+      });
+      connectReq.on('connect', (res, socket) => {
+        if (res.statusCode !== 200) {
+          socket.destroy();
+          done({ ok: false, error: '代理 CONNECT 失败: HTTP ' + res.statusCode });
+          return;
+        }
+        const tlsSocket = tls.connect({ socket, servername: url.hostname });
+        tlsSocket.once('secureConnect', () => {
+          const req = https.request({
+            host: url.hostname,
+            port: url.port || 443,
+            path: url.pathname + url.search,
+            method: 'GET',
+            headers,
+            agent: tunneledAgent(tlsSocket),
+          });
+          arm(req);
+          req.on('response', (res2) => done({ ok: true, res: res2 }));
+          req.end();
+        });
+        tlsSocket.once('error', fail);
+      });
+      connectReq.on('error', fail);
+      connectReq.setTimeout(timeoutMs, () => connectReq.destroy(new Error('代理连接超时')));
+      connectReq.end();
+      return;
+    }
+
+    if (url.protocol === 'http:' && proxy) {
+      const req = http.request({
+        host: proxy.hostname,
+        port: proxy.port,
+        method: 'GET',
+        path: url.href,
+        headers: Object.assign({ host: url.host }, headers),
+      });
+      arm(req);
+      req.on('response', (res) => done({ ok: true, res }));
+      req.end();
+      return;
+    }
+
+    const mod = url.protocol === 'https:' ? https : http;
+    const req = mod.request({
+      host: url.hostname,
+      port: url.port || undefined,
+      path: url.pathname + url.search,
+      method: 'GET',
+      headers,
+    });
+    arm(req);
+    req.on('response', (res) => done({ ok: true, res }));
+    req.end();
+  });
+}
+
+async function requestWithRedirects(url, opts, depth) {
+  const result = await requestStreamOnce(url, opts);
+  if (!result.ok) return result;
+  const res = result.res;
+  const location = res.headers && res.headers.location;
+  if (location && [301, 302, 303, 307, 308].includes(res.statusCode) && (depth || 0) < 3) {
+    res.resume();
+    let next;
+    try {
+      next = new URL(location, url).href;
+    } catch (_) {
+      return { ok: false, error: '重定向地址非法: ' + location };
+    }
+    return requestWithRedirects(next, opts, (depth || 0) + 1);
+  }
+  return result;
+}
+
+function collectBody(res, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let size = 0;
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    res.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        res.destroy();
+        done({ ok: false, error: '响应超过大小上限（' + maxBytes + ' 字节）' });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    res.on('error', (error) => done({ ok: false, error: '读取响应失败: ' + error.message }));
+    res.on('end', () => done({ ok: true, body: Buffer.concat(chunks), size }));
+  });
+}
+
+async function fetchPackument(pkg, opts) {
+  const options = opts || {};
+  const url = packumentUrl(pkg, options);
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const result = await requestWithRedirects(url, {
+      timeoutMs: options.timeoutMs || DEFAULT_TIMEOUT,
+      headers: { accept: 'application/vnd.npm.install-v1+json' },
+    }, 0);
+    if (!result.ok) {
+      lastError = result.error;
+      continue;
+    }
+    const body = await collectBody(result.res, 8 * 1024 * 1024);
+    if (!body.ok) {
+      lastError = body.error;
+      continue;
+    }
+    if (result.res.statusCode !== 200) {
+      lastError = 'registry 返回 HTTP ' + result.res.statusCode;
+      continue;
+    }
+    try {
+      return { ok: true, packument: JSON.parse(body.body.toString('utf8')), url };
+    } catch (error) {
+      lastError = '解析 registry 响应失败: ' + error.message;
+    }
+  }
+  return { ok: false, error: lastError || 'packument 获取失败' };
+}
+
+/** pin=true 取精确版本；pin=false 过滤同 major 取最高正式版本。 */
+function resolveVersion(packument, skill, pin) {
+  const versions = (packument && packument.versions) || {};
+  if (pin) {
+    const exact = versions[String(skill.version)];
+    if (!exact) {
+      const latest = (packument && packument['dist-tags'] && packument['dist-tags'].latest) || null;
+      return { error: 'registry 无 ' + skill.pkg + '@' + skill.version + (latest ? '（latest=' + latest + '）' : '') };
+    }
+    return { version: String(skill.version), dist: exact.dist || {} };
+  }
+  const major = String(skill.version).split('.')[0];
+  const matches = Object.keys(versions).filter((v) => (
+    /^[0-9]+\.[0-9]+\.[0-9]+$/.test(v) && v.split('.')[0] === major
+  ));
+  if (!matches.length) return { error: 'registry 无 ' + major + '.x 版本（' + skill.pkg + '）' };
+  matches.sort(compareSemver);
+  const best = matches[matches.length - 1];
+  return { version: best, dist: versions[best].dist || {} };
+}
+
+function streamToFile(res, destFile, options) {
+  return new Promise((resolve) => {
+    const hasher = crypto.createHash(options.algo);
+    const out = fs.createWriteStream(destFile);
+    let size = 0;
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const fail = (message) => {
+      if (settled) return;
+      res.destroy();
+      out.destroy();
+      done({ ok: false, error: message });
+    };
+    res.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > options.maxBytes) {
+        fail('下载超过大小上限（' + options.maxBytes + ' 字节）');
+        return;
+      }
+      hasher.update(chunk);
+      out.write(chunk);
+    });
+    res.on('aborted', () => fail('下载中断'));
+    res.on('error', (error) => fail('下载失败: ' + error.message));
+    out.on('error', (error) => fail('写入临时文件失败: ' + error.message));
+    res.on('end', () => {
+      if (settled) return;
+      out.end(() => {
+        if (settled) return;
+        done({ ok: true, size, digest: hasher.digest() });
+      });
+    });
+  });
+}
+
+async function downloadTarball(url, destFile, dist, opts) {
+  const options = opts || {};
+  const integrity = parseIntegrity(dist && dist.integrity);
+  const shasum = dist && dist.shasum ? String(dist.shasum).trim().toLowerCase() : null;
+  if (!integrity && !shasum) {
+    return { ok: false, error: 'registry 缺少 integrity / shasum（fail-closed 拒绝）' };
+  }
+  const result = await requestWithRedirects(url, {
+    timeoutMs: options.downloadTimeoutMs || DEFAULT_DOWNLOAD_TIMEOUT,
+  }, 0);
+  if (!result.ok) return { ok: false, error: result.error };
+  const res = result.res;
+  if (res.statusCode !== 200) {
+    res.resume();
+    return { ok: false, error: '下载失败：HTTP ' + res.statusCode };
+  }
+  const algo = integrity ? integrity.algo : 'sha1';
+  const saved = await streamToFile(res, destFile, {
+    maxBytes: options.maxBytes || DEFAULT_MAX_BYTES,
+    algo,
+  });
+  if (!saved.ok) {
+    fs.rmSync(destFile, { force: true });
+    return { ok: false, error: saved.error };
+  }
+  const expected = integrity ? integrity.base64 : shasum;
+  const got = integrity ? saved.digest.toString('base64') : saved.digest.toString('hex');
+  if (got !== expected) {
+    fs.rmSync(destFile, { force: true });
+    return { ok: false, error: 'integrity 校验失败（' + algo + '），已删除下载文件（fail-closed）' };
+  }
+  return { ok: true, size: saved.size, algo };
+}
+
+/** 异步核心：拉 packument → 解析版本 → 下载校验 → 落 packDir；返回 { ok, ... }。 */
+async function fetchPackage(skill, opts, packDir) {
+  const options = opts || {};
+  const pin = options.pin !== false;
+  const spec = skill.pkg + '@' + (pin ? skill.version : majorRange(skill.version));
+  const packument = await fetchPackument(skill.pkg, options);
+  if (!packument.ok) return { ok: false, error: 'packument 获取失败: ' + packument.error };
+  const resolved = resolveVersion(packument.packument, skill, pin);
+  if (resolved.error) return { ok: false, error: '版本解析失败: ' + resolved.error };
+  const dist = resolved.dist || {};
+  if (!dist.tarball) return { ok: false, error: 'registry 版本缺少 dist.tarball（' + spec + '）' };
+  fs.mkdirSync(packDir, { recursive: true });
+  const destFile = path.join(packDir, tarballName(skill.pkg, resolved.version));
+  const downloaded = await downloadTarball(dist.tarball, destFile, dist, options);
+  if (!downloaded.ok) return { ok: false, error: '下载失败: ' + downloaded.error };
+  return {
+    ok: true,
+    tarball: destFile,
+    resolved: resolved.version,
+    spec,
+    registry: registryBase(options),
+    integrity: dist.integrity || null,
+    shasum: dist.shasum || null,
+    size: downloaded.size,
+  };
+}
+
+/** 同步入口：子进程执行同一套异步核心（安装管线为同步契约）。 */
+function fetchPackageSync(skill, opts, packDir) {
+  const child = path.join(__dirname, 'registry-fetch-child.js');
+  const payload = JSON.stringify({
+    skill: { slug: skill.slug, pkg: skill.pkg, version: skill.version },
+    opts: { pin: opts.pin, registry: opts.registry || null },
+    packDir,
+  });
+  const result = spawnSync(process.execPath, [child], {
+    input: payload,
+    encoding: 'utf8',
+    timeout: 240000,
+    maxBuffer: 16 * 1024 * 1024,
+    env: process.env,
+  });
+  if (result.error) return { error: '内置拉包通道启动失败: ' + result.error.message };
+  const line = String(result.stdout || '').trim().split(/\r?\n/).filter(Boolean).pop();
+  let parsed = null;
+  if (line) {
+    try {
+      parsed = JSON.parse(line);
+    } catch (_) {
+      parsed = null;
+    }
+  }
+  if (!parsed) {
+    const brief = String(result.stderr || '').trim().split(/\r?\n/).filter(Boolean).slice(-2).join(' | ');
+    return { error: '内置拉包通道异常（exit ' + result.status + '）' + (brief ? ': ' + brief : '') };
+  }
+  if (!parsed.ok) return { error: parsed.error || '内置拉包失败' };
+  const out2 = parsed.result || {};
+  out2.channel = 'builtin';
+  return out2;
+}
+
+module.exports = {
+  OFFICIAL_REGISTRY,
+  registryBase,
+  packumentUrl,
+  tarballName,
+  majorRange,
+  parseIntegrity,
+  proxyFor,
+  noProxyMatch,
+  resolveVersion,
+  fetchPackument,
+  downloadTarball,
+  fetchPackage,
+  fetchPackageSync,
+};

package/skills/yotta-skills/lib/untar.js

@@ -0,0 +1,179 @@
+'use strict';
+/**
+ * lib/untar.js —— 零依赖内置解包（元阁 0.24.0，方案 A.2）。
+ *
+ * 只服务 npm 包形态的 tar.gz：必须 `package/` 前缀、拒绝链接条目与路径越界、
+ * 支持 ustar prefix / pax 扩展头 / GNU 长名；产出与 bin 的 extractTarball 相同契约
+ * （`{ pkgDir }` 或 `{ error }`）。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+/** 与 lib/install-pipeline.js 的 isSafeTarEntry 同口径（测试有 parity 断言）。 */
+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 cstring(buf, start, length) {
+  const slice = buf.subarray(start, start + length);
+  const end = slice.indexOf(0);
+  return slice.subarray(0, end === -1 ? slice.length : end).toString('utf8').trim();
+}
+
+function parseOctal(buf, start, length) {
+  const raw = cstring(buf, start, length).replace(/\0/g, '').trim();
+  if (!raw) return 0;
+  const value = parseInt(raw, 8);
+  return Number.isFinite(value) ? value : 0;
+}
+
+function parsePaxRecords(data) {
+  const map = {};
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = parseInt(data.subarray(offset, space).toString('utf8'), 10);
+    if (!Number.isFinite(length) || length <= 0 || offset + length > data.length) break;
+    const record = data.subarray(space + 1, offset + length).toString('utf8');
+    const eq = record.indexOf('=');
+    if (eq !== -1) map[record.slice(0, eq)] = record.slice(eq + 1).replace(/\n$/, '');
+    offset += length;
+  }
+  return map;
+}
+
+/**
+ * 解析 tar（不含 gzip）为条目数组。
+ * 返回 { entries } 或 { error }；条目形如 { name, mode, type, data }。
+ */
+function parseEntries(buffer) {
+  const entries = [];
+  let offset = 0;
+  let pendingPax = {};
+  let pendingLongName = null;
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512);
+    let allZero = true;
+    for (const byte of header) {
+      if (byte !== 0) {
+        allZero = false;
+        break;
+      }
+    }
+    if (allZero) break;
+
+    let name = cstring(header, 0, 100);
+    const prefix = cstring(header, 345, 155);
+    const mode = parseOctal(header, 100, 8);
+    const size = parseOctal(header, 124, 12);
+    const type = String.fromCharCode(header[156] || 0x30);
+    const dataStart = offset + 512;
+    const dataEnd = dataStart + size;
+    if (size < 0 || dataEnd > buffer.length) {
+      return { error: 'tar 结构损坏：条目数据越界（' + (name || '未命名') + '）' };
+    }
+    const data = buffer.subarray(dataStart, dataEnd);
+
+    if (type === 'x' || type === 'g') {
+      const records = parsePaxRecords(data);
+      if (type === 'x') pendingPax = Object.assign(pendingPax, records);
+      offset = dataStart + Math.ceil(size / 512) * 512;
+      continue;
+    }
+    if (type === 'L') {
+      pendingLongName = cstring(data, 0, data.length);
+      offset = dataStart + Math.ceil(size / 512) * 512;
+      continue;
+    }
+    if (prefix && type !== 'x' && type !== 'g') name = prefix + '/' + name;
+    if (pendingLongName) {
+      name = pendingLongName;
+      pendingLongName = null;
+    }
+    if (pendingPax.path) name = pendingPax.path;
+    if (pendingPax.size !== undefined && Number(pendingPax.size) !== size) {
+      return { error: 'tar 结构不支持：pax size 覆盖（' + name + '）' };
+    }
+    const entryMode = pendingPax.mode !== undefined ? parseInt(pendingPax.mode, 8) : mode;
+    pendingPax = {};
+
+    entries.push({ name, mode: Number.isFinite(entryMode) ? entryMode : mode, type, size, data: Buffer.from(data) });
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  return { entries };
+}
+
+function extractTarballBuiltin(tarball, extractDir) {
+  let compressed;
+  try {
+    compressed = fs.readFileSync(tarball);
+  } catch (error) {
+    return { error: '读取压缩包失败: ' + error.message };
+  }
+  let buffer;
+  try {
+    buffer = zlib.gunzipSync(compressed);
+  } catch (error) {
+    return { error: 'gzip 解压失败: ' + error.message };
+  }
+
+  const parsed = parseEntries(buffer);
+  if (parsed.error) return { error: parsed.error };
+
+  // fail-closed：先整体校验，再落盘（不允许部分写入）。
+  const root = path.resolve(extractDir);
+  for (const entry of parsed.entries) {
+    if (!isSafeTarEntry(entry.name)) return { error: '压缩包包含不安全路径: ' + entry.name };
+    if (entry.type === '1' || entry.type === '2') {
+      return { error: '压缩包包含链接条目（fail-closed 拒绝）: ' + entry.name };
+    }
+    if (!['0', '7', '5'].includes(entry.type)) {
+      return { error: '压缩包包含不支持的 tar 条目类型（' + entry.type + '）: ' + entry.name };
+    }
+    const target = path.resolve(extractDir, entry.name);
+    if (target !== root && !target.startsWith(root + path.sep)) {
+      return { error: '压缩包路径越界: ' + entry.name };
+    }
+  }
+
+  fs.mkdirSync(extractDir, { recursive: true });
+  try {
+    for (const entry of parsed.entries) {
+      const target = path.resolve(extractDir, entry.name);
+      if (entry.type === '5') {
+        fs.mkdirSync(target, { recursive: true });
+        continue;
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, entry.data);
+      if (entry.mode & 0o111) {
+        try {
+          fs.chmodSync(target, 0o755);
+        } catch (_) {
+          // Windows 上 chmod 基本无效；忽略即可，不阻断解包。
+        }
+      }
+    }
+  } catch (error) {
+    return { error: '写入解包产物失败: ' + error.message };
+  }
+
+  const pkgDir = path.join(extractDir, 'package');
+  if (!fs.existsSync(path.join(pkgDir, 'SKILL.md'))) {
+    return { error: '解压产物缺少 SKILL.md（' + tarball + '）' };
+  }
+  return { pkgDir, channel: 'builtin' };
+}
+
+module.exports = {
+  isSafeTarEntry,
+  parseEntries,
+  parsePaxRecords,
+  extractTarballBuiltin,
+};

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

@@ -8,9 +8,11 @@
 对每个待装技能：
 
 1. 读清单（`skills.json`，默认随包；`YOTTA_SKILLS_MANIFEST` 可覆盖）；
-2. `npm pack <pkg>@<spec> --pack-destination <临时目录>`（默认源返回 404 时自动改用官方源重试一次，
-   证据记 `npm_registry_fallback`）；
-3. 系统 `tar -xzf` 解压到临时目录（产物应有 `SKILL.md`）；
+2. 拉包：默认**内置通道**（Node 内置 https 直连 registry：abbreviated packument → 解析版本 → tarball
+   下载 + `integrity`(sha512) / `shasum`(sha1) fail-closed 校验），失败回退 `npm pack`
+   （默认源 404 时自动改用官方源重试一次，证据记 `npm_registry_fallback`）；通道记 `fetch_channel`；
+3. 解包：默认**内置通道**（Node 内置 zlib + tar 解析：ustar / pax / GNU 长名；路径安全与链接条目
+   fail-closed），失败回退系统 `tar -xzf`；通道记 `extract_channel`；产物应有 `SKILL.md`；
 4. 读取包内 `skill-manifest.json`；没有 manifest 时使用 `skills.json` 的家族默认契约；
 5. 校验 slug / package / version / 权限 / 生命周期脚本路径；
 6. 元信装前扫描：已有元信则直接扫描；没有则在本次已获用户确认的安装动作内自举元信自身，再扫描；
@@ -28,6 +30,20 @@
 因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
 安装器自身、测试夹具与 Python 字节码缓存。
 
+## 依赖与回退链
+
+| 依赖 | 角色 | 缺失时 |
+|---|---|---|
+| Node.js 18+ | 必需（CLI 本体） | 明确提示 + 按平台给安装命令 |
+| npm | 拉包回退通道（`YOTTA_SKILLS_NPM_FLAGS` / `--npm` 仍生效） | 不影响：内置拉包为主 |
+| 系统 tar | 解包回退通道 | 不影响：内置解包为主 |
+| Python 3.8+ | 元信装前扫描 | 门禁阻断（exitCode 5）；优先 `--python` / `YOTTA_SKILLS_PYTHON` 指向宿主自带 Python，或 `--skip-scan` 应急 |
+
+- 通道可用 `YOTTA_SKILLS_FETCH=builtin|npm` / `YOTTA_SKILLS_EXTRACT=builtin|tar` 强制；
+  强制单一通道失败时不回退，并给出明确报错；
+- 缺依赖时按需输出「需要什么 / 为什么 / 一条修复命令 / 不影响使用」，不常驻提醒；
+- `doctor` 新增依赖自检块（text + `--json` 的 `dependencies` 字段），只告警不失败、不改变退出码。
+
 ## manifest 与家族默认契约
 
 每个技能包可以自带根目录 `skill-manifest.json`。有 manifest 时：
@@ -63,6 +79,21 @@
 - 与清单 `version` 一致 → 跳过（幂等：第二次安装 27 个全部跳过）；
 - `--force` 强制重装；`update` 对「缺失 / 版本不一致」的技能重装。
 
+## 范围控制（接多少管多少）
+
+| 用法 | 范围 |
+|---|---|
+| `install`（无旗标） | 全量清单全部安装 |
+| `update`（无旗标） | 补齐缺失 + 升级已装（现状语义不变） |
+| `update --installed-only` | 只维护目标目录已安装的家族技能（不补装缺失；无匹配时退出码 0） |
+| `--only <a,b>` / `--domain <name>` | 只处理指定技能 / 家族；与 `--installed-only` 取交集 |
+| `update --check` / `--auto` | 只检查 / 维护已装技能，不补装缺失 |
+
+接管语义：接管范围 = 目标机器**已安装**的元技能（扫描目标目录得出），
+`skills.json` 只作身份 / 版本参照、不决定安装范围；宿主未装的技能一律不动作（不新增、不报错）；
+已管理且已最新 → 跳过（退出码 0）；非家族 / 未收录目录 → 忽略不报错。
+标准配方：`yotta-skills update --installed-only --dir <技能目录>`。
+
 ## 版本策略
 
 - 默认 pin：spec = `<pkg>@<清单精确版本>`，完全可复现，不跟随浮动版本；
@@ -80,6 +111,7 @@
 
 - 引擎查找：`--verify` → `YOTTA_SKILLS_VERIFY` → `<dest>/yotta-verify/scripts/yotta_verify.py`；
 - python 查找：`--python` → `YOTTA_SKILLS_PYTHON` → `python3` / `python` / `py`（win32）；
+  缺 Python 时输出统一人话提示（含「修复」与「不影响使用」，可指向宿主自带 Python 或 `--skip-scan` 应急）；
 - 执行：`python -B <engine> scan <解压目录> --json`（`-B` 禁止写 `__pycache__`，防止污染
   引擎所在目录）；
 - 元信缺失时：先按 `skills.json` 安装 `yotta-verify`，并记录 `gate_mode=trusted-bootstrap`
@@ -157,7 +189,8 @@ doctor 只读检查目录、`SKILL.md`、版本、manifest 身份、注册表记
 ```
 
 记录包含时间、事件、技能、包名、版本、`gate_mode`、verdict、decision
-和快照路径；不记录技能内容或用户数据，只写本机。
+、`fetch_channel`（builtin / npm）、`extract_channel`（builtin / tar）和快照路径；
+不记录技能内容或用户数据，只写本机。
 
 ## 退出码