@lark-apaas/miaoda-cli 0.1.4 → 0.1.5-alpha.2f1e0ff

package/dist/services/skills/status.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSkillsStatus = readSkillsStatus;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 扫描 <targetDir>/.agent/skills/steering/<stack>/，给出"当前装了什么"的快照。
+ * 不联网、不解析任何 SKILL.md 内容；只列目录名 + tech.md 是否在。
+ *
+ * stack 缺省（meta.json 缺 stack）时直接返回 present=false，
+ * 让 handler 把"先 init"的引导留给用户。
+ */
+function readSkillsStatus(opts) {
+    if (opts.stack === undefined || opts.stack === '') {
+        return { present: false, skills: [], techSynced: false };
+    }
+    const root = node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack);
+    if (!node_fs_1.default.existsSync(root)) {
+        return { present: false, skills: [], techSynced: false };
+    }
+    const skillsDir = node_path_1.default.join(root, 'skills');
+    const skills = node_fs_1.default.existsSync(skillsDir)
+        ? node_fs_1.default
+            .readdirSync(skillsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+        : [];
+    return {
+        present: true,
+        skills,
+        techSynced: node_fs_1.default.existsSync(node_path_1.default.join(root, 'tech.md')),
+    };
+}

package/dist/utils/coding-steering.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncCodingSteering = syncCodingSteering;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const npm_pack_1 = require("../utils/npm-pack");
+const logger_1 = require("../utils/logger");
+const STEERING_PACKAGE = '@lark-apaas/coding-steering';
+// 钉死稳定 alpha 版本而非跟 `alpha` dist-tag —— alpha 通道被多个团队共享，外部 prerelease
+// 时常打过去，自动跟 alpha 会把回归版本拉进 user app。维护这个常量比维护 alpha 通道可控。
+// 用户显式传具体版本（如 `miaoda skills sync 0.2.0`）仍 override 这个默认值。
+// 升基线时：跑端到端 smoke（init → skills sync → 看 skills 内容）→ 改这个常量。
+const DEFAULT_PINNED_VERSION = '0.1.6-alpha.10';
+function inferMode() {
+    // process.env.SANDBOX_ID 非空 → 沙箱；其他（undefined / 空串）→ 本地
+    return process.env.SANDBOX_ID ? 'sandbox' : 'local';
+}
+/**
+ * 把 coding-steering 包内 <stack>/skills_common + 专有层（skills 或 skills_local）同步到
+ * user app。
+ *
+ * 包内目录约定（每个 stack 三层）：
+ *   <stack>/skills_common  → 沙箱 + 本地都下发的共有层
+ *   <stack>/skills         → 沙箱专有（沙箱端 update-skills.sh / SANDBOX_ID 非空时拿）
+ *   <stack>/skills_local   → 本地专有（本地 dev / agent 环境拿）
+ *
+ * 下发组合（mode）：
+ *   mode='sandbox' → skills_common + skills
+ *   mode='local'   → skills_common + skills_local
+ *
+ * 目标路径形态（outputLayout）：
+ *   'nested' (默认，向后兼容)：拷到 .agent/skills/steering/<stack>/skills/，tech.md 同目录
+ *   'flat'：拷到 .agents/skills/（平铺），tech.md → .agents/tech.md，并创建 .claude/skills
+ *           软链指向 ../.agents/skills 让 Claude Code 识别同一份
+ *
+ * 同名 skill 覆盖顺序：common < 专有（专有覆盖 common 同名）。mode 缺省按 SANDBOX_ID env
+ * 推断（沙箱平台运行时注入应用所属沙箱 ID；空 / undefined 则视为本地）。
+ *
+ * 纯本地 atom（pull npm package + 拷贝文件），不属于任何 cli 域；放在 utils 让
+ * app init handler 与独立 skills sync handler 都能复用。
+ */
+function syncCodingSteering(opts) {
+    const logPrefix = opts.logPrefix ?? 'skills';
+    const effectiveVersion = opts.version ?? DEFAULT_PINNED_VERSION;
+    const mode = opts.mode ?? inferMode();
+    const layout = opts.outputLayout ?? 'nested';
+    (0, logger_1.log)(logPrefix, `Fetching ${STEERING_PACKAGE}@${effectiveVersion} (mode=${mode}, layout=${layout})...`);
+    const fetched = (0, npm_pack_1.fetchNpmPackage)({
+        packageName: STEERING_PACKAGE,
+        version: effectiveVersion,
+    });
+    try {
+        const steeringRoot = node_path_1.default.join(fetched.extractDir, 'steering');
+        const stackDir = node_path_1.default.join(steeringRoot, opts.stack);
+        // 目标路径按 layout 切：
+        //   nested → .agent/skills/steering/<stack>/{skills, tech.md}（老链路、stack 命名空间）
+        //   flat   → .agents/{skills, tech.md}（平铺，无 stack 命名空间，跟 .claude/skills 软链对齐）
+        const { dstSkillsDir, dstTechPath } = layout === 'flat'
+            ? {
+                dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agents', 'skills'),
+                dstTechPath: node_path_1.default.join(opts.targetDir, '.agents', 'tech.md'),
+            }
+            : {
+                dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'skills'),
+                dstTechPath: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'tech.md'),
+            };
+        node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
+        let techSynced = false;
+        const techSrc = node_path_1.default.join(stackDir, 'tech.md');
+        if (node_fs_1.default.existsSync(techSrc)) {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(dstTechPath), { recursive: true });
+            node_fs_1.default.copyFileSync(techSrc, dstTechPath);
+            techSynced = true;
+        }
+        const synced = [];
+        // 顺序拷贝，后者覆盖前者：skills_common 铺底，专有层（skills 或 skills_local）覆盖同名
+        const exclusiveLayer = mode === 'sandbox' ? 'skills' : 'skills_local';
+        const layers = [
+            { dir: node_path_1.default.join(stackDir, 'skills_common'), label: `${opts.stack}/skills_common` },
+            { dir: node_path_1.default.join(stackDir, exclusiveLayer), label: `${opts.stack}/${exclusiveLayer}` },
+        ];
+        for (const layer of layers) {
+            if (!node_fs_1.default.existsSync(layer.dir))
+                continue;
+            for (const name of node_fs_1.default.readdirSync(layer.dir)) {
+                const src = node_path_1.default.join(layer.dir, name);
+                if (!node_fs_1.default.statSync(src).isDirectory())
+                    continue;
+                const dst = node_path_1.default.join(dstSkillsDir, name);
+                if (node_fs_1.default.existsSync(dst))
+                    node_fs_1.default.rmSync(dst, { recursive: true, force: true });
+                copyDir(src, dst);
+                synced.push(`${layer.label}/${name}`);
+            }
+        }
+        let claudeSkillsLink;
+        if (layout === 'flat') {
+            claudeSkillsLink = ensureClaudeSkillsSymlink(opts.targetDir, logPrefix);
+        }
+        (0, logger_1.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'} (mode=${mode}, layout=${layout})`);
+        return {
+            version: fetched.version,
+            syncedSkills: synced,
+            techSynced,
+            ...(claudeSkillsLink !== undefined ? { claudeSkillsLink } : {}),
+        };
+    }
+    finally {
+        fetched.cleanup();
+    }
+}
+/**
+ * flat layout 下创建 `<targetDir>/.claude/skills` 软链 → `../.agents/skills`，让 Claude Code
+ * 默认的 skills 加载路径跟 user app 的 .agents/skills 是同一份内容。
+ *
+ * 用相对路径软链（不是 absolute）—— user app 移动目录 / clone 到别处不会断链。
+ *
+ * 处理 4 种已有状态：
+ *   - 已是软链且指向对的：noop
+ *   - 已是软链但指错地方：删旧的，建新的（updated）
+ *   - 已是普通目录 / 文件：不覆盖，警告并跳过（conflict）—— 用户可能手动放了别的 skills
+ *   - 不存在：建新的（created）
+ */
+function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
+    const linkPath = node_path_1.default.join(targetDir, '.claude', 'skills');
+    const linkTarget = node_path_1.default.join('..', '.agents', 'skills');
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(linkPath), { recursive: true });
+    let existing = null;
+    try {
+        existing = node_fs_1.default.lstatSync(linkPath);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (existing === null) {
+        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        (0, logger_1.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink created)`);
+        return 'created';
+    }
+    if (existing.isSymbolicLink()) {
+        const current = node_fs_1.default.readlinkSync(linkPath);
+        if (current === linkTarget) {
+            return 'noop';
+        }
+        node_fs_1.default.unlinkSync(linkPath);
+        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        (0, logger_1.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink updated, was → ${current})`);
+        return 'updated';
+    }
+    (0, logger_1.log)(logPrefix, `  ⚠ .claude/skills 已是普通目录/文件，跳过软链创建`);
+    return 'conflict';
+}
+function copyDir(src, dest) {
+    node_fs_1.default.mkdirSync(dest, { recursive: true });
+    for (const entry of node_fs_1.default.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = node_path_1.default.join(src, entry.name);
+        const destPath = node_path_1.default.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            node_fs_1.default.copyFileSync(srcPath, destPath);
+        }
+    }
+}

package/dist/utils/file-ops.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeLineFromFile = removeLineFromFile;
+exports.removeLineFromContent = removeLineFromContent;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("./logger");
+/**
+ * 从文件中移除匹配的行。
+ * 搬自 @lark-apaas/fullstack-cli/src/utils/file-ops.ts，行为完全对齐：精确匹配（trim 后）。
+ *
+ * @returns 是否真的移除过内容
+ */
+function removeLineFromFile(filePath, pattern, logPrefix = 'sync') {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${node_path_1.default.basename(filePath)} (not found)`);
+        return false;
+    }
+    const content = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    const trimmed = pattern.trim();
+    const lines = content.split('\n');
+    const filtered = lines.filter((line) => line.trim() !== trimmed);
+    if (filtered.length === lines.length) {
+        (0, logger_1.log)(logPrefix, `  ○ ${node_path_1.default.basename(filePath)} (pattern not found: ${pattern})`);
+        return false;
+    }
+    node_fs_1.default.writeFileSync(filePath, filtered.join('\n'));
+    (0, logger_1.log)(logPrefix, `  ✓ ${node_path_1.default.basename(filePath)} (removed: ${pattern})`);
+    return true;
+}
+/**
+ * 纯函数版本：便于单测，不读写文件。
+ */
+function removeLineFromContent(content, pattern) {
+    const trimmed = pattern.trim();
+    const lines = content.split('\n');
+    const filtered = lines.filter((line) => line.trim() !== trimmed);
+    return {
+        result: filtered.join('\n'),
+        changed: filtered.length !== lines.length,
+    };
+}

package/dist/utils/git.js

@@ -2,6 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCurrentGitBranch = getCurrentGitBranch;
 const node_child_process_1 = require("node:child_process");
+const GIT_LOCAL_ENV_KEYS = new Set([
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_CONFIG',
+    'GIT_CONFIG_PARAMETERS',
+    'GIT_CONFIG_COUNT',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_IMPLICIT_WORK_TREE',
+    'GIT_GRAFT_FILE',
+    'GIT_INDEX_FILE',
+    'GIT_NO_REPLACE_OBJECTS',
+    'GIT_REPLACE_REF_BASE',
+    'GIT_PREFIX',
+    'GIT_INTERNAL_SUPER_PREFIX',
+    'GIT_SHALLOW_FILE',
+    'GIT_COMMON_DIR',
+]);
+function withoutGitLocalEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter(([key]) => !GIT_LOCAL_ENV_KEYS.has(key)));
+}
 /**
  * 读取 cwd 所在仓库的当前分支名。
  *
@@ -13,6 +34,7 @@ function getCurrentGitBranch(cwd = process.cwd()) {
     try {
         result = (0, node_child_process_1.spawnSync)('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
             cwd,
+            env: withoutGitLocalEnv(),
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });

package/dist/utils/githooks.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activateGitHooks = activateGitHooks;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const logger_1 = require("../utils/logger");
+/**
+ * 把 `.githooks/` 注册为本仓库的 git hooks 目录，让 pre-commit 等 hook 立即生效。
+ *
+ * 三件事，都先检查再写（幂等）：
+ *   1. `.git` 存在（非 git 仓库直接跳）
+ *   2. `.githooks/pre-commit` 存在（没 hook 文件直接跳，且不写 git config 防止误指空目录）
+ *   3. `core.hooksPath` 是 `.githooks`（已经是就短路）
+ *
+ * 镜像 fullstack-cli `src/commands/sync/activate-hooks.ts`，逻辑保持一致；本地用户
+ * 通过 `miaoda app upgrade` 走的这一份，沙箱用户走 `npm run upgrade`（fullstack-cli sync）
+ * 那一份，两条通道结果应等价。
+ */
+function activateGitHooks(targetDir) {
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(targetDir, '.git'))) {
+        return { action: 'skipped-no-git' };
+    }
+    const hookFile = node_path_1.default.join(targetDir, '.githooks', 'pre-commit');
+    if (!node_fs_1.default.existsSync(hookFile)) {
+        return { action: 'skipped-no-hook-file' };
+    }
+    // copyFileSync 不保留 mode，确保 +x（重要：没 +x 时 git 不会执行 hook）
+    const currentMode = node_fs_1.default.statSync(hookFile).mode & 0o777;
+    if ((currentMode & 0o111) !== 0o111) {
+        node_fs_1.default.chmodSync(hookFile, 0o755);
+    }
+    const probe = (0, node_child_process_1.spawnSync)('git', ['config', '--get', 'core.hooksPath'], {
+        cwd: targetDir,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const currentHooksPath = probe.stdout.toString().trim();
+    if (currentHooksPath === '.githooks') {
+        return { action: 'already-active' };
+    }
+    const res = (0, node_child_process_1.spawnSync)('git', ['config', 'core.hooksPath', '.githooks'], {
+        cwd: targetDir,
+        stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    if (res.status !== 0) {
+        const stderr = res.stderr.toString().trim();
+        (0, logger_1.log)('githooks', `⚠️  failed to set core.hooksPath: ${stderr}`);
+        return { action: 'skipped-no-git' };
+    }
+    (0, logger_1.log)('githooks', `activated: core.hooksPath = .githooks`);
+    return { action: 'activated' };
+}

package/dist/utils/http.js

@@ -60,13 +60,27 @@ function createClient(opts) {
     instance.interceptors.request.use(applyCanaryHeader);
     return instance;
 }
-/** 若 MIAODA_CANARY_HEADER 已设置，注入 x-tt-env 小流量头 */
+/**
+ * 默认灰度泳道。当前 miaoda CLI 接入的新接口（modern deploy 等）只在该泳道生效，
+ * 缺省走这个。MIAODA_CANARY_HEADER 可显式覆盖；设为空字符串则去掉头。
+ */
+const DEFAULT_CANARY_HEADER = 'boe_miaoda_doubao';
+/**
+ * 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER。
+ *
+ * 当泳道形如 `ppe_xxx`（PPE 预发环境）时，额外加 `x-use-ppe: 1`；
+ * BOE 泳道（`boe_xxx`）只带 x-tt-env，不加该头。
+ */
 function applyCanaryHeader(reqConfig) {
-    const canary = process.env.MIAODA_CANARY_HEADER;
+    // env 显式设为空字符串视为"去掉灰度头"；未设置时用 DEFAULT_CANARY_HEADER
+    const canary = process.env.MIAODA_CANARY_HEADER ?? DEFAULT_CANARY_HEADER;
     if (!canary)
         return reqConfig;
     const headers = new Headers(reqConfig.headers);
     headers.set('x-tt-env', canary);
+    if (canary.startsWith('ppe_')) {
+        headers.set('x-use-ppe', '1');
+    }
     reqConfig.headers = headers;
     return reqConfig;
 }
@@ -103,14 +117,14 @@ async function handleInnerEnvelope(response, url, opts) {
         throw new error_1.HttpError(response.status, url, `${opts.errPrefix}: ${String(response.status)} ${response.statusText}`);
     }
     const result = await response.json();
+    // verbose: 把完整响应体打到 stderr，便于排查（业务错误 / 字段缺失等）
+    if ((0, config_1.getConfig)().verbose) {
+        (0, logger_1.debug)(`  resp: ${truncateForLog(safeStringify(result), 2000)}`);
+    }
     if (typeof result === 'object' && result !== null && 'status_code' in result) {
         const env = result;
         if (env.status_code !== undefined && env.status_code !== '0') {
             const msg = env.message ?? env.error_msg ?? 'unknown error';
-            // verbose: 把完整业务错误信封打到 stderr，便于追溯
-            if ((0, config_1.getConfig)().verbose) {
-                (0, logger_1.debug)(`  envelope: ${truncateForLog(safeStringify(env), 1000)}`);
-            }
             const mapped = opts.mapErr?.(env.status_code, msg);
             if (mapped)
                 throw mapped;
@@ -163,12 +177,8 @@ function logResponseFailure(method, url, err, startMs) {
     const msgPart = e.message ? ` (${e.message})` : '';
     (0, logger_1.debug)(`✗ ${method} ${url} ${statusPart} ${String(elapsedMs)}ms${logidPart}${msgPart}`);
 }
-/** BAM gateway 在不同 PSM/版本上 logid 落在不同 header；按命中顺序取第一个非空。 */
 function pickLogid(headers) {
-    return (headers.get('x-tt-logid') ??
-        headers.get('x-logid') ??
-        headers.get('logid') ??
-        headers.get('x-tt-trace-tag'));
+    return headers.get('x-tt-logid');
 }
 function safeStringify(v) {
     try {

package/dist/utils/merge-json.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Deep merge JSON 对象，支持按 key 去重合并数组。
+ *
+ * 搬自 @lark-apaas/fullstack-cli/src/utils/merge-json.ts，行为完全对齐：
+ *   - scalar（string / number / boolean / null）：template 覆盖
+ *   - object：递归 merge（template 字段覆盖，user 多出的字段保留）
+ *   - 在 arrayMerge 配置里的 array：按指定 key 去重合并（template item 覆盖同 key 的 user item，
+ *     user 多出的 item 保留）
+ *   - 不在 arrayMerge 配置里的 array：template 覆盖
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMergeJson = deepMergeJson;
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function mergeArrayByKey(userArr, templateArr, key) {
+    const result = [...userArr];
+    for (const templateItem of templateArr) {
+        if (!isPlainObject(templateItem))
+            continue;
+        const templateKey = templateItem[key];
+        const existingIndex = result.findIndex((item) => isPlainObject(item) && item[key] === templateKey);
+        if (existingIndex >= 0) {
+            result[existingIndex] = templateItem;
+        }
+        else {
+            result.push(templateItem);
+        }
+    }
+    return result;
+}
+function deepMergeJson(user, template, arrayMerge = {}, currentPath = '') {
+    const result = { ...user };
+    for (const key of Object.keys(template)) {
+        const fullPath = currentPath ? `${currentPath}.${key}` : key;
+        const templateValue = template[key];
+        const userValue = user[key];
+        if (Array.isArray(templateValue)) {
+            const cfg = Object.prototype.hasOwnProperty.call(arrayMerge, fullPath)
+                ? arrayMerge[fullPath]
+                : undefined;
+            if (cfg !== undefined && Array.isArray(userValue)) {
+                result[key] = mergeArrayByKey(userValue, templateValue, cfg.key);
+            }
+            else {
+                result[key] = templateValue;
+            }
+        }
+        else if (isPlainObject(templateValue)) {
+            if (isPlainObject(userValue)) {
+                result[key] = deepMergeJson(userValue, templateValue, arrayMerge, fullPath);
+            }
+            else {
+                result[key] = templateValue;
+            }
+        }
+        else {
+            result[key] = templateValue;
+        }
+    }
+    return result;
+}

package/dist/utils/npm-pack.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNpmPackage = fetchNpmPackage;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("./error");
+const logger_1 = require("./logger");
+const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
+/**
+ * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
+ * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。
+ */
+function fetchNpmPackage(opts) {
+    const registry = opts.registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
+    const version = opts.version ?? 'latest';
+    const pkgSpec = `${opts.packageName}@${version}`;
+    const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-pack-'));
+    try {
+        (0, logger_1.debug)(`npm pack ${pkgSpec} --registry ${registry} → ${tmpDir}`);
+        const stdout = (0, node_child_process_1.execFileSync)('npm', ['pack', pkgSpec, '--pack-destination', tmpDir, '--json', '--registry', registry], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const packInfo = JSON.parse(stdout);
+        const tgzFilename = packInfo[0]?.filename;
+        const pkgVersion = packInfo[0]?.version ?? version;
+        if (!tgzFilename) {
+            throw new error_1.AppError('NPM_PACK_FAILED', `npm pack 未返回 filename：${pkgSpec}`);
+        }
+        const tgzPath = node_path_1.default.join(tmpDir, tgzFilename);
+        const extractDir = node_path_1.default.join(tmpDir, 'extracted');
+        node_fs_1.default.mkdirSync(extractDir, { recursive: true });
+        (0, node_child_process_1.execFileSync)('tar', ['-xzf', tgzPath, '-C', extractDir], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return {
+            extractDir: node_path_1.default.join(extractDir, 'package'),
+            version: pkgVersion,
+            cleanup: () => {
+                node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        if (err instanceof error_1.AppError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new error_1.AppError('NPM_PACK_FAILED', `抓取 npm 包失败 (${pkgSpec}): ${msg}`, {
+            next_actions: [`确认包已发布到 registry：${registry}`, `检查版本号 / dist-tag 拼写`],
+        });
+    }
+}