@yottameta/yotta-skills 0.23.2 → 0.24.0

package/install.sh

@@ -1,31 +1,30 @@
 #!/usr/bin/env bash
-# yotta-skills（元阁）多智能体安装脚本（YottaSkills）
-# 用途：把「元阁安装器技能」本身装进智能体/目录（它自带 SKILL.md，让代理能调用元阁）。
-# 注意：这**不是**把 27 个 yotta-* 技能一并装齐——装全家需再跑
-#       `node bin/yotta-skills.js install --agent <name>`（或 --dir <path>）。
+# yotta-skills 多智能体安装脚本（YottaSkills）
 # 用法:
-#   bash install.sh --agent <name>  # 把安装器技能装到智能体默认用户级目录
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
 #   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
 #   bash install.sh -g              # 装到全部已知智能体用户级目录
-#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh                 # 检测并安装到已存在的项目级目录
 #   bash install.sh --list          # 列出智能体 -> 默认目录
+#   bash install.sh --dry-run       # 只显示将写入的目标，不写文件
+#   bash install.sh --version       # 显示版本
+#   bash install.sh --help          # 显示帮助
+# 退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误
 set -euo pipefail
 
 SKILL_NAME="yotta-skills"
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_IS_WINDOWS=0
 case "$(uname -s)" in
   MINGW*|MSYS*)
     SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    _IS_WINDOWS=1
     ;;
+  CYGWIN*) _IS_WINDOWS=1 ;;
 esac
 
 # 智能体 -> 用户级默认目录（--agent 装到第一个）
 # .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
-# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
-_IS_WINDOWS=0
-case "$(uname -s)" in
-  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
-esac
 dirs_for() {
   case "$1" in
     claude)     echo ".claude/skills" ;;
@@ -63,46 +62,153 @@ resolve_user() {
   esac
 }
 
-install_to() {
-  local base="$1"
-  local dest
-  local item
-  case "$base" in
-    ""|"/") echo "安装失败：拒绝不安全的目标目录：'$base'" >&2; return 1 ;;
-  esac
-  if [ -L "$base" ]; then
-    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2; return 1
+skill_version() {
+  local pkg="$SOURCE_DIR/package.json" v=""
+  [ -f "$pkg" ] || return 0
+  if command -v awk >/dev/null 2>&1; then
+    v="$(awk -F'"' '{for (i=1;i<=NF;i++) if ($i=="version") {print $(i+2); exit}}' "$pkg" 2>/dev/null || true)"
   fi
-  mkdir -p "$base"
-  dest="$base/$SKILL_NAME"
-  if [ -L "$dest" ]; then
-    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2; return 1
+  if [ -z "$v" ]; then
+    v="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" 2>/dev/null | head -n 1 || true)"
   fi
-  if [ -e "$dest" ] && [ ! -d "$dest" ]; then
-    echo "安装失败：技能路径已存在且不是目录：$dest" >&2; return 1
+  printf '%s' "$v"
+}
+
+usage() {
+  echo "$SKILL_NAME 安装脚本（YottaSkills）"
+  echo ""
+  echo "用法:"
+  echo "  bash install.sh --agent <name>   按智能体默认用户级目录安装（推荐）"
+  echo "  bash install.sh --dir <path>     装到指定目录（用户改了目录的智能体）"
+  echo "  bash install.sh -g               安装到全部已知智能体用户级目录"
+  echo "  bash install.sh                  安装到检测到的项目级目录"
+  echo ""
+  echo "参数:"
+  echo "  --agent <name>  智能体键名，见 --list"
+  echo "  --dir <path>    自定义技能目录"
+  echo "  -g, --global    安装到全部已知用户级目录"
+  echo "  --list, -l      列出支持的智能体目录"
+  echo "  --dry-run       只显示将写入的目标，不写文件"
+  echo "  --version, -v   显示版本"
+  echo "  --help, -h      显示帮助"
+  echo "  --yes, -y       兼容参数（-g 不再强制要求）"
+  echo ""
+  echo "退出码: 0 成功 / 1 安装失败 / 2 用法错误 / 4 目标错误"
+}
+
+resolve_path() {
+  # 与 SOURCE_DIR 同一风格（Windows Git Bash 用 pwd -W），供路径包含判断使用
+  local p="$1"
+  if [ "$_IS_WINDOWS" = "1" ]; then
+    (cd "$p" 2>/dev/null && pwd -W)
+  else
+    (cd "$p" 2>/dev/null && pwd -P)
+  fi
+}
+
+assert_safe_target() {
+  local dest="$1" src_real dest_real parent
+  src_real="$(resolve_path "$SOURCE_DIR")" || return 0
+  if [ -d "$dest" ]; then
+    dest_real="$(resolve_path "$dest")" || return 0
+  else
+    parent="$(dirname "$dest")"
+    dest_real="$(resolve_path "$parent")" || return 0
+    dest_real="$dest_real/$(basename "$dest")"
   fi
-  mkdir -p "$dest"
+  case "$dest_real" in
+    "$src_real"|"$src_real"/*)
+      echo "安装失败：目标目录不能在技能源目录内（防止自装自毁）" >&2
+      return 1
+      ;;
+  esac
+  return 0
+}
 
-  # 只安装技能本体与运行时需要的 MCP/清单资产；只清副本内的固定子路径。
-  for item in .git .github .gitignore .npmignore bin lib test package.json package-lock.json install.sh; do
-    if [ -e "$dest/$item" ] && [ ! -L "$dest/$item" ]; then
-      rm -rf -- "$dest/$item"
+# 清理旧版安装残留（fail-closed 白名单）：仅在目标目录已存在且含 SKILL.md 时触发；
+# 只删顶层开发项 + 任意层级缓存；不整目录删除、不跟随符号链接。
+DEV_SKIP="package.json package-lock.json bin lib test .github .git .gitignore .npmignore .gitattributes .yotta .tmp install.sh node_modules"
+clean_residue() {
+  local dest="$1" name p
+  [ -d "$dest" ] || return 0
+  [ -f "$dest/SKILL.md" ] || return 0
+  for name in $DEV_SKIP; do
+    p="$dest/$name"
+    [ -L "$p" ] && continue
+    if [ -e "$p" ]; then
+      rm -rf -- "$p"
+      echo "已清理残留: $name"
     fi
   done
-  for item in SKILL.md skill-manifest.json references scripts assets skills.json scan-policy.json LICENSE NOTICE README.md README.zh-CN.md CHANGELOG.md USER_GUIDE.md; do
-    if [ -e "$SOURCE_DIR/$item" ]; then
-      cp -RP "$SOURCE_DIR/$item" "$dest/"
+  find "$dest" -type d \( -name '__pycache__' -o -name '.pytest_cache' -o -name '.mypy_cache' \) -prune -exec rm -rf -- {} + 2>/dev/null || true
+  find "$dest" -type f \( -name '*.pyc' -o -name '*.pyo' \) -delete 2>/dev/null || true
+}
+
+# 复制技能本体：顶层跳过开发件与运行时不相关目录（嵌套同名保留）；
+# 任意层级跳过缓存（__pycache__ / .pytest_cache / .mypy_cache / *.pyc / *.pyo）。
+copy_tree() {
+  local src="$1" dst="$2" top="$3" entry base
+  mkdir -p "$dst"
+  for entry in "$src"/* "$src"/.[!.]* "$src"/..?*; do
+    [ -e "$entry" ] || [ -L "$entry" ] || continue
+    base="$(basename "$entry")"
+    case "$base" in
+      __pycache__|.pytest_cache|.mypy_cache) continue ;;
+    esac
+    if [ "$top" = "1" ]; then
+      case " $DEV_SKIP " in
+        *" $base "*) continue ;;
+      esac
+    fi
+    if [ -d "$entry" ] && [ ! -L "$entry" ]; then
+      copy_tree "$entry" "$dst/$base" 0 || return 1
+    else
+      case "$base" in
+        *.pyc|*.pyo) continue ;;
+      esac
+      cp -RP "$entry" "$dst/$base" || return 1
     fi
   done
-  find "$dest" -type d -name '__pycache__' -prune -exec rm -rf {} + 2>/dev/null || true
-  find "$dest" -type f -name '*.pyc' -delete 2>/dev/null || true
+}
+
+install_to() {
+  local base="$1" dry="$2" dest
+  dest="$base/$SKILL_NAME"
+  if [ -L "$base" ]; then
+    echo "安装失败：目标目录是符号链接，拒绝跟随：$base" >&2
+    return 1
+  fi
+  if [ -e "$base" ] && [ ! -d "$base" ]; then
+    echo "安装失败：目标路径已存在且不是目录：$base" >&2
+    return 1
+  fi
+  if [ -L "$dest" ]; then
+    echo "安装失败：技能目录是符号链接，拒绝跟随：$dest" >&2
+    return 1
+  fi
+  if [ -e "$dest" ] && [ ! -d "$dest" ]; then
+    echo "安装失败：技能路径已存在且不是目录：$dest" >&2
+    return 1
+  fi
+  assert_safe_target "$dest" || return 1
+  if [ "$dry" = "1" ]; then
+    echo "[dry-run] 将安装到 -> $dest"
+    return 0
+  fi
+  clean_residue "$dest"
+  mkdir -p "$dest" || return 1
+  copy_tree "$SOURCE_DIR" "$dest" 1 || return 1
+  if [ ! -f "$dest/SKILL.md" ]; then
+    echo "安装失败：结果缺少 SKILL.md" >&2
+    return 1
+  fi
   echo "installed -> $dest"
 }
 
 list() {
   echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  local a dirs first
   for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-    local dirs first
     dirs="$(dirs_for "$a")"
     first="${dirs%% *}"
     case "$first" in
@@ -121,49 +227,101 @@ list() {
 }
 
 main() {
-  local agent="" dir="" global=0 show_list=0 assume_yes=0
+  local agent="" dir="" global=0 show_list=0 show_help=0 show_version=0 dry=0
   while [ $# -gt 0 ]; do
     case "$1" in
-      --agent) shift; agent="${1:-}" ;;
-      --dir)   shift; dir="${1:-}" ;;
-      -g|--global) global=1 ;;
-      -y|--yes) assume_yes=1 ;;
+      --help|-h) show_help=1 ;;
+      --version|-v) show_version=1 ;;
       --list|-l) show_list=1 ;;
+      -g|--global) global=1 ;;
+      --dry-run) dry=1 ;;
+      --yes|-y) : ;;
+      --agent)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --agent 需要一个非空名称" >&2
+          exit 2
+        fi
+        agent="$1"
+        ;;
+      --dir)
+        shift
+        if [ $# -eq 0 ] || [ -z "${1:-}" ]; then
+          echo "用法错误: --dir 需要一个非空路径" >&2
+          exit 2
+        fi
+        dir="$1"
+        ;;
       *) echo "未知参数: $1" >&2; exit 2 ;;
     esac
     shift
   done
 
-  if [ "$show_list" = "1" ]; then list; return; fi
-  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ "$show_help" = "1" ]; then usage; return 0; fi
+  if [ "$show_version" = "1" ]; then
+    local v
+    v="$(skill_version)"
+    if [ -z "$v" ]; then
+      echo "$SKILL_NAME 版本未知（未找到 package.json）" >&2
+      exit 1
+    fi
+    echo "$SKILL_NAME v$v"
+    return 0
+  fi
+  if [ "$show_list" = "1" ]; then list; return 0; fi
+
+  local selected=0
+  [ -n "$dir" ] && selected=$((selected + 1))
+  [ -n "$agent" ] && selected=$((selected + 1))
+  [ "$global" = "1" ] && selected=$((selected + 1))
+  if [ "$selected" -gt 1 ]; then
+    echo "用法错误: --dir / --agent / -g 只能选一个" >&2
+    exit 2
+  fi
+
+  if [ -n "$dir" ]; then
+    install_to "$dir" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
+  fi
   if [ -n "$agent" ]; then
     local dirs first
     if ! dirs="$(dirs_for "$agent")"; then
-      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+      echo "未收录智能体: $agent。可用 --list 查看，或 --dir <路径> 指定。" >&2
+      exit 2
     fi
     first="${dirs%% *}"
-    install_to "$(resolve_user "$first")"; echo "完成。"; return
+    install_to "$(resolve_user "$first")" "$dry" || exit 1
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   fi
   if [ "$global" = "1" ]; then
-    if [ "$assume_yes" != "1" ]; then
-      echo "批量安装到全部已知智能体目录会写入多个宿主目录，需要显式确认：请加 --yes（或用 --agent / --dir 指定单一目标）。" >&2
-      exit 2
-    fi
-    echo "安装到全部已知智能体用户级目录..."
-    local dirs rel
+    local a dirs rel seen=" "
     for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-      dirs="$(dirs_for "$a")"
-      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+      dirs="$(dirs_for "$a")" || continue
+      for rel in $dirs; do
+        case "$seen" in
+          *" $rel "*) continue ;;
+        esac
+        seen="$seen$rel "
+        install_to "$(resolve_user "$rel")" "$dry" || exit 1
+      done
     done
-    echo "完成。"; return
+    [ "$dry" = "1" ] || echo "完成。"
+    return 0
   fi
   local installed=0 d
   for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
-    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+    if [ -d "$d" ]; then
+      install_to "$d" "$dry" || exit 1
+      installed=1
+    fi
   done
   if [ "$installed" = "0" ]; then
-    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+    echo "目标错误: 未检测到项目级智能体目录。可用 --agent <name> 装到用户级，或用 --dir <路径> 指定目录。" >&2
+    exit 4
   fi
+  [ "$dry" = "1" ] || echo "完成。"
 }
 
 main "$@"

package/lib/deps.js

@@ -0,0 +1,173 @@
+'use strict';
+/**
+ * lib/deps.js —— 依赖缺口的统一人话提示（元阁 0.24.0，方案 B）。
+ *
+ * 约定：按需触发、不常驻；每条提示回答四件事：
+ *   需要什么 / 为什么 / 怎么办（一条可复制修复）/ 不影响使用。
+ * 依赖矩阵：Node 18+ 必需；npm 与系统 tar 是回退通道（内置拉包 / 内置解包为主）；
+ * 元信装前扫描需要 Python 3.8+，优先指向宿主自带 Python（--python / YOTTA_SKILLS_PYTHON）。
+ */
+
+const NEED = {
+  node: { label: 'Node 18+', need: '>=18', why: '运行元阁 CLI 本体' },
+  npm: { label: 'npm', need: '随 Node 安装', why: '拉包回退通道（内置拉包失败时的备用）' },
+  python: { label: 'Python 3.8+', need: '>=3.8', why: '元信装前安全扫描' },
+  tar: { label: 'tar', need: '可用即可', why: '解包回退通道（内置解包失败时的备用）' },
+};
+
+function fixFor(dep, platform) {
+  const p = platform || process.platform;
+  if (dep === 'node' || dep === 'npm') {
+    if (p === 'win32') return 'winget install OpenJS.NodeJS.LTS';
+    if (p === 'darwin') return 'brew install node';
+    return 'sudo apt install nodejs npm（或到 https://nodejs.org/ 下载 LTS）';
+  }
+  if (dep === 'python') {
+    if (p === 'win32') {
+      return '优先用 --python <路径> 或 YOTTA_SKILLS_PYTHON 指向宿主自带 Python；否则 winget install Python.Python.3.12';
+    }
+    if (p === 'darwin') {
+      return '优先用 --python <路径> 或 YOTTA_SKILLS_PYTHON 指向宿主自带 Python；否则 brew install python';
+    }
+    return '优先用 --python <路径> 或 YOTTA_SKILLS_PYTHON 指向宿主自带 Python；否则 sudo apt install python3';
+  }
+  if (dep === 'tar') {
+    if (p === 'win32') return 'Windows 10+ 自带 tar（缺失时可 winget install bsdtar）';
+    if (p === 'darwin') return 'macOS 自带 tar；或 brew install gnu-tar';
+    return 'sudo apt install tar';
+  }
+  return '';
+}
+
+/**
+ * 统一三行模板：
+ *   需要 <依赖>（用途：<为什么>）—— 装好后重跑：<原命令>
+ *   修复：<一条可复制命令>
+ *   或者：继续用宿主自带技能，不影响正常使用。<补充>
+ */
+function describe(dep, options) {
+  const meta = NEED[dep] || { label: dep, need: '', why: '' };
+  const opts = options || {};
+  const command = opts.command || 'yotta-skills <原命令>';
+  const status = opts.missing
+    ? '—— 未找到 ' + meta.label + '；装好后重跑：' + command
+    : '—— 装好后重跑：' + command;
+  const extra = opts.extra ? ' ' + opts.extra : '';
+  return [
+    '需要 ' + meta.label + '（用途：' + meta.why + '）' + status,
+    '修复：' + (opts.fix || fixFor(dep)),
+    '或者：继续用宿主自带技能，不影响正常使用。' + extra,
+  ].join('\n');
+}
+
+function semverAtLeast(version, minimum) {
+  const got = String(version || '').match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  const need = String(minimum || '').match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!got || !need) return null;
+  for (let i = 1; i <= 3; i += 1) {
+    const a = Number(got[i] || 0);
+    const b = Number(need[i] || 0);
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+  return true;
+}
+
+/** Node 版本自检；version 可注入用于测试。 */
+function nodeCheck(version) {
+  const current = version || process.versions.node;
+  return {
+    name: 'node',
+    found: true,
+    version: current,
+    ok: semverAtLeast(current, '18.0.0') === true,
+    need: NEED.node.need,
+    why: NEED.node.why,
+  };
+}
+
+/** npm 缺失错误识别（spawn ENOENT / 命令不存在的中英文提示）。 */
+function isNpmMissing(raw) {
+  const text = String(raw || '');
+  return /ENOENT|EINVAL|npm\.cmd'? ?(无法|不能被)|不是内部或外部命令|not recognized|系统找不到指定/i.test(text);
+}
+
+function versionLine(proc) {
+  if (!proc) return null;
+  const text = String((proc.stdout || '') + (proc.stderr || '')).trim();
+  if (!text) return null;
+  return text.split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0].slice(0, 80) || null;
+}
+
+/**
+ * doctor 依赖自检块（只告警不失败）。
+ * detected: { node:{version,ok}, npm:{found,version}, python:{found,version,path}, tar:{found,version} }
+ */
+function dependencyReport(detected) {
+  const d = detected || {};
+  const items = [];
+
+  const node = d.node || {};
+  const nodeVersion = node.version || process.versions.node;
+  const nodeOk = node.ok !== undefined ? !!node.ok : semverAtLeast(nodeVersion, '18.0.0') === true;
+  items.push({
+    name: 'node',
+    found: true,
+    version: 'v' + String(nodeVersion),
+    ok: nodeOk,
+    need: NEED.node.need,
+    why: NEED.node.why,
+    optional: false,
+    fix: nodeOk ? null : fixFor('node'),
+  });
+
+  const npm = d.npm || {};
+  items.push({
+    name: 'npm',
+    found: !!npm.found,
+    version: npm.version || null,
+    ok: !!npm.found,
+    need: NEED.npm.need,
+    why: NEED.npm.why,
+    optional: true,
+    fix: npm.found ? null : fixFor('npm'),
+  });
+
+  const py = d.python || {};
+  const pyVersionOk = py.found ? semverAtLeast(py.version || '', '3.8.0') : false;
+  items.push({
+    name: 'python',
+    found: !!py.found,
+    version: py.version || null,
+    ok: pyVersionOk === true,
+    need: NEED.python.need,
+    why: NEED.python.why,
+    optional: false,
+    fix: pyVersionOk === true ? null : fixFor('python'),
+  });
+
+  const tar = d.tar || {};
+  items.push({
+    name: 'tar',
+    found: !!tar.found,
+    version: tar.version || null,
+    ok: !!tar.found,
+    need: NEED.tar.need,
+    why: NEED.tar.why,
+    optional: true,
+    fix: tar.found ? null : fixFor('tar'),
+  });
+
+  return items;
+}
+
+module.exports = {
+  NEED,
+  fixFor,
+  describe,
+  nodeCheck,
+  isNpmMissing,
+  versionLine,
+  dependencyReport,
+  semverAtLeast,
+};

package/lib/install-pipeline.js

@@ -151,6 +151,7 @@ function createInstaller(deps) {
         const scanResult = deps.scanTarget(gate.engine, extracted.pkgDir, {
           slug: skill.slug,
           version: packed.resolved,
+          opts,
         });
         if (!scanResult.ok) {
           safeRecord({ event: 'before_install', skill: skill.slug, decision: 'block', error: scanResult.error });
@@ -338,6 +339,8 @@ function createInstaller(deps) {
           verdict: scan.verdict,
           decision: scan.decision,
           scan_policy: scan.policy || null,
+          fetch_channel: packed.channel || null,
+          extract_channel: extracted.channel || null,
           npm_registry_fallback: Boolean(packed.registryFallback),
           snapshot,
         });
@@ -351,6 +354,8 @@ function createInstaller(deps) {
         package: skill.pkg,
         version: packed.resolved || skill.version,
         decision: 'allow',
+        fetch_channel: packed.channel || null,
+        extract_channel: extracted.channel || null,
         snapshot,
         lifecycle: {
           setup: lifecycleSummary(lifecycle.setup),

package/lib/npm-pack.js

@@ -24,6 +24,12 @@ function briefOf(raw) {
   return lines.slice(-4).join(' | ');
 }
 
+/** 把 spawn 层错误（如 ENOENT：npm 缺失）并入原始错误文本，供上层人话提示识别。 */
+function rawOf(result) {
+  if (result && result.error && result.error.message) return String(result.error.message).trim();
+  return String((result && result.stderr) || (result && result.stdout) || 'npm pack 失败').trim();
+}
+
 function findTarball(stdout, packDir, readdirSync) {
   const lines = String(stdout || '')
     .split(/\r?\n/)
@@ -71,14 +77,14 @@ function createPackRunner(deps) {
     let result = attempt(baseArgs);
     let registryFallback = false;
     if (result.status !== 0) {
-      const raw = (result.stderr || result.stdout || 'npm pack 失败').trim();
+      const raw = rawOf(result);
       if (!fallbackDisabled() && !hasRegistryFlag(baseArgs) && isNotFound(raw)) {
         result = attempt([...baseArgs, '--registry', OFFICIAL_REGISTRY]);
         registryFallback = result.status === 0;
       }
     }
     if (result.status !== 0) {
-      const raw = (result.stderr || result.stdout || 'npm pack 失败').trim();
+      const raw = rawOf(result);
       const brief = briefOf(raw) || 'npm pack 失败';
       const hint = isNotFound(raw) ? '\n  ' + FALLBACK_HINT : '';
       return { error: brief + hint, detail: raw };

package/lib/registry-fetch-child.js

@@ -0,0 +1,29 @@
+'use strict';
+/**
+ * lib/registry-fetch-child.js —— 内置拉包的子进程入口（内部工具，勿直接调用）。
+ *
+ * 父进程（lib/registry-fetch.js fetchPackageSync）经 stdin 传入 JSON：
+ *   { skill: {slug, pkg, version}, opts: {pin, registry}, packDir }
+ * stdout 最后一行输出 JSON：{ ok: true, result } 或 { ok: false, error }。
+ * 这样安装管线保持同步契约，网络 I/O 仍走同一套异步核心。
+ */
+
+const fetchLib = require('./registry-fetch');
+
+async function main() {
+  let payload;
+  try {
+    payload = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+  } catch (error) {
+    process.stdout.write(JSON.stringify({ ok: false, error: '入参解析失败: ' + error.message }) + '\n');
+    return;
+  }
+  try {
+    const result = await fetchLib.fetchPackage(payload.skill, payload.opts || {}, payload.packDir);
+    process.stdout.write(JSON.stringify(result.ok ? { ok: true, result } : { ok: false, error: result.error }) + '\n');
+  } catch (error) {
+    process.stdout.write(JSON.stringify({ ok: false, error: '内置拉包异常: ' + (error && error.message ? error.message : String(error)) }) + '\n');
+  }
+}
+
+main();