@actiondock/builder 2.10.0 → 2.11.0

package/dist/entry-generators.js

@@ -0,0 +1,211 @@
+import { STANDALONE_ASYNC_UNSUPPORTED } from "@actiondock/core";
+import { serializePlanManifest } from "./manifest.js";
+/**
+ * 生成 Host 子进程入口脚本源码（负责运行 ActionDockHost，通过 Node IPC 暴露 Target）。
+ *
+ * 按需装配契约：
+ * - 不再静态导入全部包内 Action（消除发现路径的业务模块顶层副作用）；
+ * - 仅携带清单元数据，执行时由现有执行服务通过清单 entry 与 NodeModuleLoader
+ *   按需加载业务实现；跨包外部 Action 不混入本包源码，依赖调用继续经 Host 路由；
+ * - 入口路径以产物包根目录为基准（import.meta.dirname），不依赖调用者当前工作目录。
+ */
+export function generateNodeHostEntrySource(plan) {
+    // 复用 SelectionPlan 的清单序列化单一事实源（含包内动作筛选与 Schema 字段映射），
+    // 不单独复制一份 Schema 字段映射
+    const manifestActions = serializePlanManifest(plan).actions;
+    return `#!/usr/bin/env node
+// AUTO-GENERATED HOST ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
+import "@actiondock/core/warning";
+import {
+  createActionDock,
+  createNodePlatform,
+} from "@actiondock/core";
+import { serveParentIpc } from "@actiondock/core/server";
+
+// 产物包根目录：以入口文件自身位置为基准，不依赖调用者当前工作目录
+const packageRoot = import.meta.dirname;
+
+let dataDir;
+const configOverrides = {};
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--data-dir" && i + 1 < args.length) {
+    dataDir = args[++i];
+  } else if (args[i].startsWith("--data-dir=")) {
+    dataDir = args[i].slice(11);
+  } else if (args[i] === "--config" && i + 1 < args.length) {
+    const raw = args[++i];
+    const [k, ...v] = raw.split("=");
+    if (k) configOverrides[k] = v.join("=");
+  } else if (args[i].startsWith("--config=")) {
+    const raw = args[i].slice(9);
+    const [k, ...v] = raw.split("=");
+    if (k) configOverrides[k] = v.join("=");
+  }
+}
+
+// 复用既有命令分发结果确定访问性质：发现命令（list/describe/show）为旁观初始化，
+// 不创建数据库、不取目录锁、不收割遗留运行记录；执行与写入命令为持有者初始化
+const command = args.find((a) => !a.startsWith("-")) || "";
+const DISCOVERY_COMMANDS = new Set(["list", "describe", "show"]);
+const recoverOrphans = DISCOVERY_COMMANDS.has(command) ? false : undefined;
+
+const service = await createActionDock({
+  dataDir,
+  ...(recoverOrphans === false ? { recoverOrphans: false } : {}),
+  packages: [
+    {
+      packageRoot,
+      dataDir,
+      configOverrides,
+      projectConfig: {
+        id: ${JSON.stringify(plan.packageId)},
+        name: ${JSON.stringify(plan.packageName)},
+        version: ${JSON.stringify(plan.version)},
+        description: ${JSON.stringify(plan.description || "")},
+        config: ${JSON.stringify(plan.configDefs || {})},
+        actions: ${JSON.stringify(manifestActions)},
+      },
+    },
+  ],
+  platform: createNodePlatform({ dataDir }),
+  autoLoadCurrentProject: false,
+  scanLinkedPackages: false,
+});
+await serveParentIpc(service);
+`;
+}
+/**
+ * 生成轻量监督父进程脚本源码（负责参数解析、诊断日志限流、退出码管理与标准输出隔离）。
+ */
+export function generateNodeSupervisorEntrySource(plan) {
+    return `#!/usr/bin/env node
+// AUTO-GENERATED SUPERVISOR ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
+import "@actiondock/core/warning";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import {
+  STANDALONE_ASYNC_UNSUPPORTED,
+} from "@actiondock/core";
+
+import {
+  ExitCode,
+  IpcActionDockService,
+  StandaloneDispatcher,
+} from "@actiondock/core/server";
+
+const METADATA = {
+  packageId: ${JSON.stringify(plan.packageId)},
+  version: ${JSON.stringify(plan.version)},
+  description: ${JSON.stringify(plan.description || "")},
+};
+
+const argv = process.argv.slice(2);
+
+// 1. 监督进程接管参数校验，明确拒绝 --async
+if (argv.includes("--async")) {
+  const isJson = argv.includes("--json");
+  if (isJson) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: false,
+          error: {
+            code: ${JSON.stringify(STANDALONE_ASYNC_UNSUPPORTED)},
+            message:
+              "Async execution is not supported in standalone single-execution binaries. Use 'ad serve' or remote target.",
+          },
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(
+      "Error [" + STANDALONE_ASYNC_UNSUPPORTED + "]: Async execution is not supported in standalone single-execution binaries."
+    );
+  }
+  process.exit(ExitCode.FAILURE);
+}
+
+// 2. 静态元数据快速返回
+if (argv.includes("-v") || argv.includes("-V") || argv.includes("--version") || argv[0] === "version") {
+  console.log(\`\${METADATA.packageId} v\${METADATA.version}\`);
+  process.exit(ExitCode.SUCCESS);
+}
+
+if (argv.includes("-h") || argv.includes("--help") || argv[0] === "help") {
+  console.log(\`\${METADATA.packageId} (v\${METADATA.version})\`);
+  if (METADATA.description) console.log(METADATA.description + "\\n");
+  console.log("Usage:");
+  console.log("  <cmd> list [--json]                         List available actions");
+  console.log("  <cmd> describe <id> [--json]                Show action details and schemas");
+  console.log("  <cmd> run <id> [--input '<json>']           Execute action with JSON input");
+  console.log("  <cmd> config list/get/set/delete            Manage package configuration");
+  console.log("  <cmd> state list/get/set/delete             Manage shared state store");
+  console.log("\\nGlobal options:");
+  console.log("  --data-dir <path>                           Custom runtime database directory");
+  console.log("  --config <KEY=val>                          Temporary config override");
+  process.exit(ExitCode.SUCCESS);
+}
+
+// 3. 建立物理隔离监督边界，启动运行 ActionDockHost 的独立子进程
+const hostScript = join(import.meta.dirname, "entry-host.js");
+const warningFlags = process.env.ACTIONDOCK_SILENCE_WARNINGS !== "0" ? ["--no-warnings=ExperimentalWarning"] : [];
+const child = spawn(process.execPath, [...warningFlags, hostScript, ...argv], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: ["pipe", "pipe", "pipe", "ipc"],
+});
+
+// 4. 标准输出通道物理隔离与受控限流排空
+
+const service = new IpcActionDockService({
+  childProcess: child,
+  diagnosticTarget: process.stderr,
+});
+
+let cleanedUp = false;
+const cleanup = async () => {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  try {
+    await service.close();
+  } catch (err) {
+    // 防御与透明：服务关闭失败时告警输出至标准错误流，不阻塞退出流程
+    process.stderr.write(\`[Supervisor] Warning: Cleanup failed: \${err?.message || String(err)}\\n\`);
+  }
+};
+
+process.once("SIGINT", async () => {
+  await cleanup();
+  process.exit(ExitCode.SIGINT);
+});
+
+process.once("SIGTERM", async () => {
+  await cleanup();
+  process.exit(143);
+});
+
+const dispatcher = new StandaloneDispatcher({
+  packageId: METADATA.packageId,
+  version: METADATA.version,
+  description: METADATA.description,
+  service,
+});
+
+try {
+  const exitCode = await dispatcher.dispatch(argv);
+  await cleanup();
+  process.exit(exitCode);
+} catch (err) {
+  if (err?.code === "HOST_PROCESS_EXITED") {
+    console.error("[Supervisor] Host process exited unexpectedly:", err.message);
+  } else {
+    console.error("[Supervisor] Error:", err?.message || err);
+  }
+  await cleanup();
+  process.exit(ExitCode.FAILURE);
+}
+`;
+}

package/dist/export-composite.js

@@ -2,7 +2,8 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSyn
 import { basename, dirname, join, resolve } from "node:path";
 import { loadProjectConfig, } from "@actiondock/core";
 import { getPackageSlug, loadManifest, loadPlaybooks, } from "@actiondock/core/project";
-import { generateCompositeSkillMd } from "./skill/index.js";
+import { generateCompositeSkillMd, RUNTIME_REFERENCE_REL_PATH } from "./skill/index.js";
+import { writeRuntimeReferenceFile } from "./export-source.js";
 import { BuilderError } from "./errors.js";
 import { collectRelativeFiles, getInternalDependencyVersion, replaceDirAtomic } from "./fs-utils.js";
 import { allocatePackageDirName, sanitizeExportDependencies } from "./manifest.js";
@@ -128,6 +129,16 @@ export async function exportCompositeImpl(options, exportSubpackage) {
             if (existsSync(targetFile)) {
                 console.warn(`[WARN] Existing SKILL.md will be overwritten: ${targetFile}`);
             }
+            // 就地重生成只修改 SKILL.md：若参考文件尚未物化则同步写出，避免产生悬空链接
+            const referencePath = join(dirname(targetFile), RUNTIME_REFERENCE_REL_PATH);
+            if (!existsSync(referencePath)) {
+                writeRuntimeReferenceFile(dirname(targetFile), {
+                    dependencyStepLabel: "安装复合技能聚合依赖",
+                    relinkStepLabel: "完成安装后重新链接复合技能",
+                    compositeLinkNote: true,
+                    invocationStyle: "global-ad",
+                });
+            }
             writeFileSync(targetFile, compositeSkillMd, "utf-8");
             return {
                 bundleName: options.bundleName,
@@ -148,6 +159,13 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         }
         else {
             writeFileSync(join(stagingDir, "SKILL.md"), compositeSkillMd, "utf-8");
+            // 仅在使用自动模板时生成复合运行参考文件（含复合链接语义说明）
+            writeRuntimeReferenceFile(stagingDir, {
+                dependencyStepLabel: "安装复合技能聚合依赖",
+                relinkStepLabel: "完成安装后重新链接复合技能",
+                compositeLinkNote: true,
+                invocationStyle: "global-ad",
+            });
         }
         // 聚合所有子包依赖生成复合根目录 package.json
         writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options);

package/dist/export-source.d.ts

@@ -1,3 +1,4 @@
+import { renderRuntimeReferenceContent } from "./skill/templates.js";
 import type { SelectionPlan, SkillExporterOptions } from "./types.js";
 /**
  * 源码型 Skill 导出装配层。
@@ -9,3 +10,8 @@ import type { SelectionPlan, SkillExporterOptions } from "./types.js";
  * 源码型 Skill 的暂存阶段：生成 SKILL.md、actiondock.json、package.json 并拷贝源码。
  */
 export declare function stageSourceSkill(root: string, skillDir: string, plan: SelectionPlan, options: SkillExporterOptions, pkgSlug: string): string | undefined;
+/**
+ * 写出运行参考文件 references/actiondock-runtime.md。
+ * 与项目声明资产同路径冲突时报告错误，不覆盖用户文件。
+ */
+export declare function writeRuntimeReferenceFile(destDir: string, options: Parameters<typeof renderRuntimeReferenceContent>[0]): void;

package/dist/export-source.js

@@ -1,11 +1,13 @@
 import { copyFileSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { mkdirSync } from "node:fs";
 import { generateSourceSkillMd } from "./skill/index.js";
+import { RUNTIME_REFERENCE_REL_PATH, renderRuntimeReferenceContent, } from "./skill/templates.js";
 import { BuilderError } from "./errors.js";
 import { getInternalDependencyVersion } from "./fs-utils.js";
 import { assertValidManifestActionIds, sanitizeExportDependencies, serializePlanManifest, } from "./manifest.js";
 import { copyPlanEntries } from "./stage-sources.js";
-import { buildConfigForTemplates, toPlaybookDefinitions, toSkillActionItems, writeSkillMd, } from "./skill-md.js";
+import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
 /**
  * 源码型 Skill 导出装配层。
  *
@@ -19,7 +21,7 @@ export function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
     const actionsDir = plan.actionsDir || "actions";
     const playbooksDir = plan.playbooksDir || "playbooks";
     const configForTemplates = buildConfigForTemplates(plan, actionsDir, playbooksDir);
-    const usedExistingSkillMd = writeSkillMd(root, skillDir, plan, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => generateSourceSkillMd(configForTemplates, toSkillActionItems(plan.actions), toPlaybookDefinitions(plan.playbooks)));
+    const usedExistingSkillMd = writeSkillMd(root, skillDir, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => generateSourceSkillMd(configForTemplates, plan.actions, plan.playbooks));
     // 导出精简后的 actiondock.json 项目配置（项目元数据与清单的单一事实源）
     const exportedConfig = serializePlanManifest(plan, {
         omitEmptyConfig: true,
@@ -40,11 +42,29 @@ export function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
     copyPlanEntries(skillDir, plan, {
         playbookRelPath: (pb) => join(playbooksDir, basename(pb.filePath)),
     });
+    // 声明资产拷贝完成后再物化默认运行参考文件：仅在使用自动模板时生成；
+    // 与项目声明资产同路径冲突时报错不覆盖（拷贝在前，冲突检测能真实命中）
+    if (usedExistingSkillMd === undefined && !options.skipSkillMd) {
+        writeRuntimeReferenceFile(skillDir, {
+            dependencyStepLabel: "安装技能源码依赖",
+            relinkStepLabel: "完成安装后重新链接本技能",
+            invocationStyle: "global-ad",
+        });
+    }
     return usedExistingSkillMd;
 }
 /**
- * 生成源码型 Skill 的 package.json（依赖清洗统一复用 manifest 的 sanitizeExportDependencies 单一入口）。
+ * 写出运行参考文件 references/actiondock-runtime.md。
+ * 与项目声明资产同路径冲突时报告错误，不覆盖用户文件。
  */
+export function writeRuntimeReferenceFile(destDir, options) {
+    const referencePath = join(destDir, RUNTIME_REFERENCE_REL_PATH);
+    if (existsSync(referencePath)) {
+        throw new BuilderError(`Runtime reference file conflict: '${referencePath}' already exists (declared asset or user file). Refusing to overwrite user files.`);
+    }
+    mkdirSync(dirname(referencePath), { recursive: true });
+    writeFileSync(referencePath, renderRuntimeReferenceContent(options), "utf-8");
+}
 function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug) {
     let exportedPkg;
     const projectPkgPath = join(root, "package.json");

package/dist/exporter.d.ts

@@ -1,4 +1,4 @@
-import type { BatchSkillExportOptions, BatchSkillExportResult, CompositeSkillExportOptions, CompositeSkillExportResult, SkillExporterOptions, SkillExportResult } from "./types.js";
+import type { CompositeSkillExportOptions, CompositeSkillExportResult, SkillExporterOptions, SkillExportResult } from "./types.js";
 /**
  * Agent Skill 导出器门面。
  * 仅承担编排职责：单包模式分派、复合/批量流程装配与结果组装，
@@ -17,10 +17,6 @@ export declare class SkillExporter {
      * 源码型 Skill 导出：暂存目录内完成清单、说明书与源码装配后原子替换目标目录。
      */
     private exportSourceSkill;
-    /**
-     * 批量导出多个 Skill。
-     */
-    exportBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult>;
     /**
      * 复合模式导出：将多个包聚合为一个统一的复合技能目录。
      */
@@ -32,11 +28,6 @@ export declare class SkillExporter {
  * 需要复用导出器或定制行为时可直接实例化 SkillExporter。
  */
 export declare function exportSkill(options: SkillExporterOptions): Promise<SkillExportResult>;
-/**
- * 批量导出多个 Skill 产物的顶层公共入口函数。
- * 内部创建 SkillExporter 实例并委托其实例批量导出方法。
- */
-export declare function exportSkillBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult>;
 /**
  * 导出复合技能套件的顶层公共入口函数。
  * 内部创建 SkillExporter 实例并委托其实例复合导出方法。

package/dist/exporter.js

@@ -8,9 +8,8 @@ import { SelectionPlanner } from "./planner.js";
 import { isOwnAction } from "./types.js";
 import { createArchive, resolveArchiveFormat } from "./export-archive.js";
 import { stageSourceSkill } from "./export-source.js";
-import { exportNodeSkill } from "./export-node.js";
+import { exportNodeSkill } from "./build.js";
 import { exportCompositeImpl } from "./export-composite.js";
-import { exportBatchImpl } from "./export-batch.js";
 /**
  * Agent Skill 导出器门面。
  * 仅承担编排职责：单包模式分派、复合/批量流程装配与结果组装，
@@ -118,12 +117,6 @@ export class SkillExporter {
             usedExistingSkillMd,
         };
     }
-    /**
-     * 批量导出多个 Skill。
-     */
-    async exportBatch(options) {
-        return exportBatchImpl(options, (opts) => this.export(opts));
-    }
     /**
      * 复合模式导出：将多个包聚合为一个统一的复合技能目录。
      */
@@ -140,14 +133,6 @@ export async function exportSkill(options) {
     const exporter = new SkillExporter();
     return exporter.export(options);
 }
-/**
- * 批量导出多个 Skill 产物的顶层公共入口函数。
- * 内部创建 SkillExporter 实例并委托其实例批量导出方法。
- */
-export async function exportSkillBatch(options) {
-    const exporter = new SkillExporter();
-    return exporter.exportBatch(options);
-}
 /**
  * 导出复合技能套件的顶层公共入口函数。
  * 内部创建 SkillExporter 实例并委托其实例复合导出方法。

package/dist/fs-utils.js

@@ -1,6 +1,7 @@
 import { cpSync, existsSync, renameSync, rmSync } from "node:fs";
 import { ACTIONDOCK_VERSION } from "@actiondock/core";
 import { traverseDirectory } from "@actiondock/core/project";
+import { BuilderError } from "./errors.js";
 /**
  * builder 包内共享的文件系统基础设施。
  * 消除 pack / build / exporter 三个业务模块中成体系的重复实现，
@@ -112,7 +113,7 @@ export async function replaceDirAtomic(stagingDir, targetDir) {
                 await moveDirAtomic(backupDir, targetDir);
             }
             catch (rollbackErr) {
-                throw new Error(`Failed to promote directory to '${targetDir}' (${promoteErr instanceof Error ? promoteErr.message : String(promoteErr)}), and rollback from backup '${backupDir}' also failed: ${rollbackErr?.message || String(rollbackErr)}`);
+                throw new BuilderError(`Failed to promote directory to '${targetDir}' (${promoteErr instanceof Error ? promoteErr.message : String(promoteErr)}), and rollback from backup '${backupDir}' also failed: ${rollbackErr?.message || String(rollbackErr)}`, "FS_PROMOTE_FAILED");
             }
             throw promoteErr;
         }

package/dist/index.d.ts

@@ -3,8 +3,9 @@
  * 专注于暴露核心构建主接口与必要契约，低层内部工具作为包内模块封装。
  */
 export { BuilderError, PlannerError } from "./errors.js";
-export { buildProject } from "./build.js";
+export { buildProject, buildProjectWithPlan } from "./build.js";
 export { packProject } from "./pack.js";
-export { exportCompositeSkill, exportSkill, exportSkillBatch, SkillExporter, } from "./exporter.js";
+export { exportCompositeSkill, exportSkill, SkillExporter, } from "./exporter.js";
+export { allocatePackageDirName } from "./manifest.js";
 export { SelectionPlanner } from "./planner.js";
-export type { ArchiveFormat, BatchSkillExportOptions, BatchSkillExportResult, BuildOptions, BuildPlan, BuildResult, CompositeSkillExportOptions, CompositeSkillExportResult, ExportSkillOptions, ExportSkillResult, PackOptions, PackResult, SelectionPlan, SelectionPlannerOptions, SkillExporterOptions, SkillExportResult, } from "./types.js";
+export type { ArchiveFormat, BuildOptions, BuildPlan, BuildProjectWithPlanOptions, BuildResult, CompositeSkillExportOptions, CompositeSkillExportResult, ExportSkillOptions, ExportSkillResult, PackOptions, PackResult, SelectionPlan, SelectionPlannerOptions, SkillExporterOptions, SkillExportResult, } from "./types.js";

package/dist/index.js

@@ -5,8 +5,9 @@
 // 错误模型
 export { BuilderError, PlannerError } from "./errors.js";
 // 构建、打包与导出主接口
-export { buildProject } from "./build.js";
+export { buildProject, buildProjectWithPlan } from "./build.js";
 export { packProject } from "./pack.js";
-export { exportCompositeSkill, exportSkill, exportSkillBatch, SkillExporter, } from "./exporter.js";
+export { exportCompositeSkill, exportSkill, SkillExporter, } from "./exporter.js";
+export { allocatePackageDirName } from "./manifest.js";
 // 构建规划器
 export { SelectionPlanner } from "./planner.js";

package/dist/lockfile-resolver.d.ts

@@ -0,0 +1,9 @@
+import type { LockfileInfo } from "./types.js";
+/**
+ * 支持的包管理器锁文件候选列表。
+ */
+export declare const KNOWN_LOCKFILES: string[];
+/**
+ * 读取并计算项目锁文件元数据及 SHA-256 摘要。
+ */
+export declare function computeLockfileInfo(projectRoot: string, preferredLockfile?: string): LockfileInfo | undefined;

package/dist/lockfile-resolver.js

@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { assertPathWithinRoot } from "@actiondock/core/project";
+import { PlannerError } from "./errors.js";
+/**
+ * 支持的包管理器锁文件候选列表。
+ */
+export const KNOWN_LOCKFILES = [
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "bun.lockb",
+    "bun.lock",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+];
+/**
+ * 读取并计算项目锁文件元数据及 SHA-256 摘要。
+ */
+export function computeLockfileInfo(projectRoot, preferredLockfile) {
+    if (preferredLockfile) {
+        const lockPath = resolve(projectRoot, preferredLockfile);
+        assertPathWithinRoot(projectRoot, lockPath, "lockfile");
+        if (existsSync(lockPath) && statSync(lockPath).isFile()) {
+            const content = readFileSync(lockPath);
+            const sha256 = createHash("sha256").update(content).digest("hex");
+            return {
+                name: basename(lockPath),
+                path: lockPath,
+                sha256,
+            };
+        }
+        throw new PlannerError(`Specified lockfile not found on disk: ${preferredLockfile}`, "LOCKFILE_NOT_FOUND");
+    }
+    for (const lockFileName of KNOWN_LOCKFILES) {
+        const lockPath = join(projectRoot, lockFileName);
+        if (existsSync(lockPath)) {
+            try {
+                if (statSync(lockPath).isFile()) {
+                    const content = readFileSync(lockPath);
+                    const sha256 = createHash("sha256").update(content).digest("hex");
+                    return {
+                        name: lockFileName,
+                        path: lockPath,
+                        sha256,
+                    };
+                }
+            }
+            catch (err) {
+                // 存在但不可读：显式报错而非静默跳过，否则构建在无锁文件摘要状态下继续，可复现性校验形同虚设
+                throw new PlannerError(`Lockfile '${lockFileName}' exists but could not be read in ${projectRoot}: ${err?.message || String(err)}`, "LOCKFILE_READ_ERROR");
+            }
+        }
+    }
+    return undefined;
+}

package/dist/npm-pack.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
+ * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
+ * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ */
+export declare function runNpmPack(stagingPkgDir: string, packDestination: string, fallbackName: string): Promise<string>;

package/dist/npm-pack.js

@@ -0,0 +1,73 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { BuilderError } from "./errors.js";
+/**
+ * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
+ * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
+ * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ */
+export async function runNpmPack(stagingPkgDir, packDestination, fallbackName) {
+    const { stdout } = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", packDestination], {
+            cwd: stagingPkgDir,
+            shell: process.platform === "win32",
+        });
+        let stdoutBuf = "";
+        let stderrBuf = "";
+        child.stdout.on("data", (chunk) => (stdoutBuf += chunk));
+        child.stderr.on("data", (chunk) => (stderrBuf += chunk));
+        child.on("error", rejectPromise);
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolvePromise({ stdout: stdoutBuf, stderr: stderrBuf });
+            }
+            else {
+                rejectPromise(new BuilderError(`npm pack exited with code ${code}. Output:\n${stdoutBuf}\n${stderrBuf}`));
+            }
+        });
+    });
+    // 优先解析 --json 结构化输出中的压缩包文件名
+    let generatedName;
+    const trimmed = stdout.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            let items;
+            if (Array.isArray(parsed)) {
+                items = parsed;
+            }
+            else if (typeof parsed === "object" && parsed !== null) {
+                // npm >= 11 的 pack --json 输出为按包名索引的对象，取全部包含 filename 的条目
+                items = Object.values(parsed).filter((entry) => typeof entry === "object" && entry !== null && "filename" in entry);
+            }
+            else {
+                items = [];
+            }
+            // 多包输出时取最后一个 filename（npm 按依赖顺序逐包输出，末尾为当前项目产物）
+            const filenames = items
+                .map((item) => item.filename)
+                .filter((name) => typeof name === "string" && name.length > 0);
+            const filename = filenames[filenames.length - 1];
+            if (filename !== undefined) {
+                generatedName = filename;
+            }
+        }
+        catch {
+            // 回退到尾部行解析
+        }
+    }
+    if (!generatedName) {
+        const packLines = trimmed
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        const tgzLine = packLines.slice().reverse().find((line) => line.endsWith(".tgz"));
+        generatedName = tgzLine || packLines.pop() || fallbackName;
+    }
+    const generatedTarball = join(packDestination, generatedName);
+    if (!existsSync(generatedTarball)) {
+        throw new BuilderError(`npm pack did not produce expected tarball at ${generatedTarball}. Output:\n${stdout}`);
+    }
+    return generatedTarball;
+}

package/dist/pack.d.ts

@@ -3,8 +3,8 @@ import type { PackOptions, PackResult } from "./types.js";
  * 对 Action Package 执行打包并生成标准 npm Action 压缩包（.tgz）。
  *
  * 职责：
- * - 调用项目本地 TypeScript 编译（Node 执行），输出声明文件（.d.ts）与纯 JavaScript ESM 产物到临时暂存目录。
- * - 严格校验导出的 Manifest（入口全部指向编译后的 .js/.mjs，不得包含 actionsDir 或 playbooksDir 等废弃目录字段）。
+ * - 依托 Node 24 原生类型擦除特性，直接按规范收集并打包源码（.ts / .js 等）及资产文件到临时暂存目录。
+ * - 严格校验导出的 Manifest（不得包含 actionsDir 或 playbooksDir 等废弃目录字段）。
  * - 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz），严禁使用正则替换与自建 tar 压缩。
  *
  * @param options 打包参数选项