@actiondock/builder 2.5.1 → 2.6.0

package/dist/exporter.js

@@ -1,387 +1,19 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { COMPOSITE_CUSTOM_DECLARATION_FILE, generateCompositeSkillMd, generateSourceSkillMd, generateStandaloneSkillMd, getPackageSlug, loadManifest, loadPlaybooks, loadProjectConfig, parseCustomSkillDeclaration, } from "@actiondock/core";
-import { createTarGzArchiveAsync, createZipArchiveAsync } from "./archive.js";
-import { buildProject } from "./build.js";
+import { getPackageSlug } from "@actiondock/core";
 import { BuilderError } from "./errors.js";
-import { collectRelativeFiles, getInternalDependencyVersion, replaceDirAtomic, } from "./fs-utils.js";
-import { assertNoFileProtocolDeps, assertValidManifestActionIds, resolveWorkspaceDepVersion, serializePlanManifest, } from "./manifest.js";
+import { replaceDirAtomic } from "./fs-utils.js";
+import { collectRelativeFiles } from "./fs-utils.js";
 import { SelectionPlanner } from "./planner.js";
+import { createArchive, resolveArchiveFormat } from "./export-archive.js";
+import { stageSourceSkill } from "./export-source.js";
+import { exportNodeSkill } from "./export-node.js";
+import { exportCompositeImpl } from "./export-composite.js";
+import { exportBatchImpl } from "./export-batch.js";
 /**
- * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
- */
-function toSkillActionItems(actions) {
-    return actions;
-}
-/**
- * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
- */
-function toPlaybookDefinitions(playbooks) {
-    return playbooks;
-}
-/**
- * 执行归档压缩操作。
- * 先压缩到临时路径，成功后原子重命名覆盖最终路径；失败时清理临时文件后透传原始异常，
- * 避免旧档已删、新档半成品残留的中间态。
- */
-async function createArchive(skillDir, format) {
-    const parentDir = dirname(skillDir);
-    const folderName = basename(skillDir);
-    const archiveName = `${folderName}.${format === "tar.gz" ? "tar.gz" : "zip"}`;
-    const archivePath = join(parentDir, archiveName);
-    const tempArchivePath = `${archivePath}.tmp`;
-    if (existsSync(tempArchivePath)) {
-        // 清理上次失败可能残留的临时文件（兼容目录形态，避免阻塞本次压缩）
-        rmSync(tempArchivePath, { force: true, recursive: true, maxRetries: 3, retryDelay: 50 });
-    }
-    try {
-        if (format === "tar.gz") {
-            await createTarGzArchiveAsync(skillDir, tempArchivePath);
-        }
-        else {
-            await createZipArchiveAsync(skillDir, tempArchivePath);
-        }
-        renameSync(tempArchivePath, archivePath);
-    }
-    catch (err) {
-        // 压缩失败：清理临时半成品，旧档保持原样，透传原始异常
-        if (existsSync(tempArchivePath)) {
-            rmSync(tempArchivePath, { force: true, recursive: true, maxRetries: 3, retryDelay: 50 });
-        }
-        throw new BuilderError(`Failed to create ${format} archive: ${err?.message || String(err)}`);
-    }
-    return archivePath;
-}
-/**
- * 解析归档格式：显式 archiveFormat 优先，archive 字段直接携带格式时其次。
- */
-function resolveArchiveFormat(options) {
-    if (options.archiveFormat === "tar.gz" || options.archive === "tar.gz") {
-        return "tar.gz";
-    }
-    return "zip";
-}
-/**
- * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
- */
-export function findExistingSingleSkillMd(projectRoot, explicitPath, pkgSlug) {
-    if (explicitPath && existsSync(explicitPath)) {
-        try {
-            if (statSync(explicitPath).isFile())
-                return resolve(explicitPath);
-        }
-        catch {
-            // 忽略文件属性读取异常
-        }
-    }
-    const candidates = [
-        join(projectRoot, "SKILL.md"),
-        join(projectRoot, "skill.md"),
-        join(projectRoot, "skills", "SKILL.md"),
-        join(projectRoot, "skills", "skill.md"),
-    ];
-    if (pkgSlug) {
-        candidates.push(join(projectRoot, "skills", pkgSlug, "SKILL.md"), join(projectRoot, "skills", pkgSlug, "skill.md"));
-    }
-    for (const candidate of candidates) {
-        if (existsSync(candidate)) {
-            try {
-                if (statSync(candidate).isFile())
-                    return resolve(candidate);
-            }
-            catch {
-                // 忽略文件属性读取异常
-            }
-        }
-    }
-    return undefined;
-}
-/**
- * 检索复合套件工作区中已存在的 SKILL.md 文件。
- */
-export function findExistingCompositeSkillMd(options) {
-    if (options.skillMdPath && existsSync(options.skillMdPath)) {
-        try {
-            if (statSync(options.skillMdPath).isFile())
-                return resolve(options.skillMdPath);
-        }
-        catch {
-            // 忽略文件属性读取异常
-        }
-    }
-    const bundleSlug = getPackageSlug(options.bundleName);
-    const searchDirs = new Set();
-    if (options.workspaceRoot && existsSync(options.workspaceRoot)) {
-        searchDirs.add(resolve(options.workspaceRoot));
-    }
-    searchDirs.add(process.cwd());
-    for (const root of options.projectRoots) {
-        const absRoot = resolve(root);
-        // 仅搜索父目录（工作区根）一级；祖父目录搜索可能命中毫不相关的全局 SKILL.md 并复制进产物
-        searchDirs.add(dirname(absRoot));
-    }
-    const candidateRelativePaths = [
-        join("skills", options.bundleName, "SKILL.md"),
-        join("skills", bundleSlug, "SKILL.md"),
-        join("skills", "SKILL.md"),
-        "SKILL.md",
-        join("skills", options.bundleName, "skill.md"),
-        join("skills", bundleSlug, "skill.md"),
-        join("skills", "skill.md"),
-        "skill.md",
-    ];
-    for (const dir of searchDirs) {
-        for (const rel of candidateRelativePaths) {
-            const fullPath = join(dir, rel);
-            if (existsSync(fullPath)) {
-                try {
-                    if (statSync(fullPath).isFile())
-                        return fullPath;
-                }
-                catch {
-                    // 忽略文件属性读取异常
-                }
-            }
-        }
-    }
-    return undefined;
-}
-/**
- * 解析复合技能自定义说明书：显式 customMdPath 优先（缺失即报错），
- * 否则按 `SKILL.custom.md` 约定名在工作区根目录与当前目录自动发现。
- */
-function resolveCustomSkillDeclaration(options) {
-    let filePath;
-    if (options.customMdPath) {
-        if (!existsSync(options.customMdPath)) {
-            throw new BuilderError(`Custom skill declaration file not found: '${options.customMdPath}'`);
-        }
-        filePath = resolve(options.customMdPath);
-    }
-    else {
-        const searchDirs = [options.workspaceRoot, process.cwd()].filter(Boolean);
-        for (const dir of searchDirs) {
-            const candidate = join(resolve(dir), COMPOSITE_CUSTOM_DECLARATION_FILE);
-            if (existsSync(candidate)) {
-                filePath = candidate;
-                break;
-            }
-        }
-    }
-    if (!filePath) {
-        return undefined;
-    }
-    return {
-        file: filePath,
-        ...parseCustomSkillDeclaration(readFileSync(filePath, "utf-8")),
-    };
-}
-/**
- * 复制或生成 SKILL.md 到目标目录。
- * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
- */
-function writeSkillMd(root, destDir, plan, options, generate) {
-    const existingSkill = options.skipSkillMd
-        ? undefined
-        : findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug);
-    if (existingSkill) {
-        const destSkillMd = join(destDir, "SKILL.md");
-        if (resolve(existingSkill) !== resolve(destSkillMd)) {
-            copyFileSync(existingSkill, destSkillMd);
-        }
-        return existingSkill;
-    }
-    if (!options.skipSkillMd) {
-        writeFileSync(join(destDir, "SKILL.md"), generate(), "utf-8");
-    }
-    return undefined;
-}
-/**
- * 构造模板生成所需的 ProjectConfig 视图。
- */
-function buildConfigForTemplates(plan, actionsDir, playbooksDir) {
-    return {
-        id: plan.packageId,
-        name: plan.packageName,
-        version: plan.version,
-        description: plan.description,
-        actionsDir,
-        playbooksDir,
-        // 声明性配置字典在规划侧为宽松结构，模板仅透传展示
-        config: plan.configDefs,
-    };
-}
-/**
- * 源码型 Skill 的暂存阶段：生成 SKILL.md、actiondock.json、package.json 并拷贝源码。
- */
-function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
-    const actionsDir = plan.actionsDir || "actions";
-    const playbooksDir = plan.playbooksDir || "playbooks";
-    const playbooksDestDir = join(skillDir, playbooksDir);
-    if (plan.playbooks.length > 0) {
-        mkdirSync(playbooksDestDir, { recursive: true });
-    }
-    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)));
-    // 导出精简后的 actiondock.json 项目配置（项目元数据与清单的单一事实源）
-    const exportedConfig = serializePlanManifest(plan, {
-        omitEmptyConfig: true,
-        includeDirs: { actionsDir, playbooksDir },
-    });
-    if (exportedConfig.actions && typeof exportedConfig.actions === "object") {
-        assertValidManifestActionIds(exportedConfig.actions);
-    }
-    writeFileSync(join(skillDir, "actiondock.json"), JSON.stringify(exportedConfig, null, 2) + "\n", "utf-8");
-    // 导出 package.json
-    writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug);
-    // 拷贝 tsconfig.json（若存在）
-    const tsconfigPath = join(root, "tsconfig.json");
-    if (existsSync(tsconfigPath)) {
-        copyFileSync(tsconfigPath, join(skillDir, "tsconfig.json"));
-    }
-    // 拷贝 Action 源码文件，保留相对路径（仅拷贝自有 Action，跨包依赖不物化进消费包目录）
-    for (const act of plan.actions) {
-        if (act.isExternal || act.id.includes("/")) {
-            continue;
-        }
-        if (existsSync(act.resolvedPath)) {
-            const destFile = join(skillDir, act.entry);
-            mkdirSync(dirname(destFile), { recursive: true });
-            copyFileSync(act.resolvedPath, destFile);
-        }
-    }
-    // 拷贝静态资产与代码模块文件，保留相对路径
-    for (const dep of plan.dependencies.modulesAndAssets) {
-        if ((dep.type === "asset" || dep.type === "module" || dep.type === "file") &&
-            existsSync(dep.resolvedPath)) {
-            const destAsset = join(skillDir, dep.path);
-            mkdirSync(dirname(destAsset), { recursive: true });
-            copyFileSync(dep.resolvedPath, destAsset);
-        }
-    }
-    // 拷贝 Playbook 规程文件
-    for (const pb of plan.playbooks) {
-        if (existsSync(pb.filePath)) {
-            const destPb = join(playbooksDestDir, basename(pb.filePath));
-            copyFileSync(pb.filePath, destPb);
-        }
-    }
-    return usedExistingSkillMd;
-}
-/**
- * 生成源码型 Skill 的 package.json（含依赖协议校验与 workspace 版本解析）。
- */
-function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug) {
-    const sanitizeDependencies = (deps) => {
-        const result = {};
-        if (deps && typeof deps === "object") {
-            for (const [k, v] of Object.entries(deps)) {
-                const verStr = String(v);
-                if (verStr.startsWith("file:")) {
-                    throw new BuilderError(`Unsupported file: dependency for '${k}'. Runtime dependencies must not use file: protocol in exported skill packages.`);
-                }
-                if (k.startsWith("@actiondock/")) {
-                    result[k] = getInternalDependencyVersion();
-                }
-                else if (verStr.startsWith("workspace:")) {
-                    result[k] = resolveWorkspaceDepVersion(root, k, verStr);
-                }
-                else {
-                    result[k] = verStr;
-                }
-            }
-        }
-        if (!result["@actiondock/sdk"]) {
-            result["@actiondock/sdk"] = getInternalDependencyVersion();
-        }
-        return result;
-    };
-    let exportedPkg;
-    const projectPkgPath = join(root, "package.json");
-    if (existsSync(projectPkgPath)) {
-        try {
-            const raw = readFileSync(projectPkgPath, "utf-8");
-            const parsed = JSON.parse(raw);
-            exportedPkg = {
-                name: parsed.name || pkgSlug,
-                version: plan.version || parsed.version || "0.1.0",
-                description: plan.description || parsed.description,
-                type: "module",
-                dependencies: sanitizeDependencies(parsed.dependencies),
-            };
-        }
-        catch (err) {
-            if (err instanceof BuilderError) {
-                throw err;
-            }
-            exportedPkg = fallbackSkillPkg(plan, pkgSlug);
-        }
-    }
-    else {
-        exportedPkg = fallbackSkillPkg(plan, pkgSlug);
-    }
-    writeFileSync(join(skillDir, "package.json"), JSON.stringify(exportedPkg, null, 2) + "\n", "utf-8");
-}
-/** 无 package.json 或解析失败时的兜底导出描述 */
-function fallbackSkillPkg(plan, pkgSlug) {
-    return {
-        name: pkgSlug,
-        version: plan.version,
-        description: plan.description,
-        type: "module",
-        dependencies: { "@actiondock/sdk": getInternalDependencyVersion() },
-    };
-}
-/**
- * 复合套件聚合各子包依赖并生成复合根目录 package.json。
- */
-function writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options) {
-    const aggregatedDeps = {
-        "@actiondock/sdk": getInternalDependencyVersion(),
-    };
-    for (const info of packageInfos) {
-        const pkgJsonPath = join(packagesDestDir, info.packageDir, "package.json");
-        if (existsSync(pkgJsonPath)) {
-            try {
-                const raw = readFileSync(pkgJsonPath, "utf-8");
-                const parsed = JSON.parse(raw);
-                if (parsed.dependencies && typeof parsed.dependencies === "object") {
-                    assertNoFileProtocolDeps(parsed.dependencies, "exported skill packages");
-                    for (const [dep, ver] of Object.entries(parsed.dependencies)) {
-                        const verStr = String(ver);
-                        if (dep.startsWith("@actiondock/")) {
-                            aggregatedDeps[dep] = getInternalDependencyVersion();
-                        }
-                        else if (verStr.startsWith("workspace:")) {
-                            aggregatedDeps[dep] = resolveWorkspaceDepVersion(join(packagesDestDir, info.packageDir), dep, verStr);
-                        }
-                        else {
-                            aggregatedDeps[dep] = verStr;
-                        }
-                    }
-                }
-            }
-            catch (err) {
-                if (err instanceof BuilderError)
-                    throw err;
-                // 复合导出缺依赖影响面大：读文件与解析失败必须显式报错，严禁静默吞掉导致聚合依赖缺失
-                throw new BuilderError(`Failed to read or parse package.json of exported subpackage '${info.packageDir}' (${pkgJsonPath}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    const compositePkg = {
-        name: `${bundleSlug}-composite-skill`,
-        version: "0.1.0",
-        description: options.description || `Composite Skill suite: ${options.bundleName}`,
-        type: "module",
-        workspaces: ["packages/*"],
-        dependencies: aggregatedDeps,
-    };
-    writeFileSync(join(stagingDir, "package.json"), JSON.stringify(compositePkg, null, 2) + "\n", "utf-8");
-}
-/**
- * Agent Skill 导出器。
- * 负责源码型 Skill 与 Node 目录型 Skill 的构建、打包与分发。
+ * Agent Skill 导出器门面。
+ * 仅承担编排职责：单包模式分派、复合/批量流程装配与结果组装，
+ * 各导出模式的具体装配逻辑由 export-* 单一职责模块承担。
  */
 export class SkillExporter {
     /**
@@ -451,47 +83,10 @@ export class SkillExporter {
             };
         }
         if (mode === "node") {
-            return this.exportNodeSkill(root, targetSkillDir, plan, options, pkgSlug);
+            return exportNodeSkill(root, targetSkillDir, plan, options, pkgSlug);
         }
         return this.exportSourceSkill(root, targetSkillDir, plan, options, pkgSlug);
     }
-    /**
-     * Node 目录型 Skill 导出：复用 Node 目录型构建，并在 Skill 内生成调用该入口的 SKILL.md。
-     */
-    async exportNodeSkill(root, targetSkillDir, plan, options, pkgSlug) {
-        await buildProject({
-            projectRoot: root,
-            outDir: targetSkillDir,
-            actions: options.actions,
-            playbooks: options.playbooks,
-            config: options.config,
-            manifest: options.manifest,
-            vendorDeps: Boolean(options.vendorDeps),
-            allowInstallScripts: options.allowInstallScripts,
-            requireReproducible: options.requireReproducible,
-        });
-        const usedExistingSkillMd = writeSkillMd(root, targetSkillDir, plan, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => {
-            const configForTemplates = buildConfigForTemplates(plan, plan.actionsDir || "actions", plan.playbooksDir || "playbooks");
-            return generateStandaloneSkillMd(configForTemplates, toSkillActionItems(plan.actions), toPlaybookDefinitions(plan.playbooks), "node ./entry.mjs");
-        });
-        let archivePath;
-        if (options.archive) {
-            archivePath = await createArchive(targetSkillDir, resolveArchiveFormat(options));
-        }
-        return {
-            packageId: plan.packageId,
-            version: plan.version,
-            mode: "node",
-            skillDir: targetSkillDir,
-            archivePath,
-            actionsCount: plan.actions.length,
-            playbooksCount: plan.playbooks.length,
-            actions: plan.actions.map((a) => a.id),
-            playbooks: plan.playbooks.map((p) => p.id),
-            files: collectRelativeFiles(targetSkillDir),
-            usedExistingSkillMd,
-        };
-    }
     /**
      * 源码型 Skill 导出：暂存目录内完成清单、说明书与源码装配后原子替换目标目录。
      */
@@ -529,255 +124,41 @@ export class SkillExporter {
             usedExistingSkillMd,
         };
     }
-    /**
-     * 静态辅助调用单个 Skill 导出方法。
-     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
-     */
-    static async export(options) {
-        const exporter = new SkillExporter();
-        return exporter.export(options);
-    }
     /**
      * 批量导出多个 Skill。
      */
     async exportBatch(options) {
-        if (!options.projectRoots || options.projectRoots.length === 0) {
-            throw new BuilderError("No project roots provided for batch skill export.");
-        }
-        const results = [];
-        const baseOutDir = resolve(options.outDir || join(process.cwd(), "dist", "skills"));
-        mkdirSync(baseOutDir, { recursive: true });
-        const usedDirNames = new Set();
-        for (const projectRoot of options.projectRoots) {
-            const config = loadProjectConfig(projectRoot);
-            let pkgSlug = getPackageSlug(config.id);
-            if (usedDirNames.has(pkgSlug)) {
-                pkgSlug = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/^-+|-+$/g, "");
-            }
-            usedDirNames.add(pkgSlug);
-            const pkgOutDir = join(baseOutDir, `${pkgSlug}-skill`);
-            const res = await this.export({
-                ...options,
-                projectRoot,
-                outDir: pkgOutDir,
-            });
-            results.push(res);
-        }
-        const totalActions = results.reduce((sum, r) => sum + r.actionsCount, 0);
-        const totalPlaybooks = results.reduce((sum, r) => sum + r.playbooksCount, 0);
-        return {
-            results,
-            outDir: baseOutDir,
-            totalActions,
-            totalPlaybooks,
-        };
-    }
-    /**
-     * 静态辅助调用批量导出方法。
-     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
-     */
-    static async exportBatch(options) {
-        const exporter = new SkillExporter();
-        return exporter.exportBatch(options);
+        return exportBatchImpl(options, (opts) => this.export(opts));
     }
     /**
      * 复合模式导出：将多个包聚合为一个统一的复合技能目录。
      */
     async exportComposite(options) {
-        if (!options.projectRoots || options.projectRoots.length === 0) {
-            throw new BuilderError("No project roots provided for composite skill export.");
-        }
-        if (!options.bundleName || !options.bundleName.trim()) {
-            throw new BuilderError("bundleName is required for composite skill export.");
-        }
-        const skillMdOnly = options.skillMdOnly === true;
-        const customDeclaration = resolveCustomSkillDeclaration(options);
-        const bundleSlug = getPackageSlug(options.bundleName);
-        const defaultSkillDir = join(process.cwd(), "dist", `${bundleSlug}-skill`);
-        const targetSkillDir = resolve(options.outDir || defaultSkillDir);
-        const parentDir = dirname(targetSkillDir);
-        mkdirSync(parentDir, { recursive: true });
-        const stagingDir = skillMdOnly
-            ? null
-            : join(parentDir, `.tmp-composite-${bundleSlug}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-        if (stagingDir) {
-            mkdirSync(stagingDir, { recursive: true });
-        }
-        const packagesDestDir = stagingDir ? join(stagingDir, "packages") : null;
-        if (packagesDestDir) {
-            mkdirSync(packagesDestDir, { recursive: true });
-        }
-        const packageInfos = [];
-        const packageSummaries = [];
-        let existingSkillPath;
-        try {
-            // 收集并展开所有包含在依赖闭包中的外部项目根目录，确保 bundle 整包携带齐全部依赖
-            const effectiveRoots = new Set();
-            for (const r of options.projectRoots) {
-                effectiveRoots.add(resolve(r));
-                if (!skillMdOnly) {
-                    try {
-                        const p = SelectionPlanner.plan({ projectRoot: r });
-                        if (p.externalProjectRoots) {
-                            for (const extRoot of p.externalProjectRoots) {
-                                effectiveRoots.add(resolve(extRoot));
-                            }
-                        }
-                    }
-                    catch {
-                        // 忽略规划解析异常，由主循环处理
-                    }
-                }
-            }
-            const usedDirNames = new Set();
-            for (const projectRoot of effectiveRoots) {
-                const config = loadProjectConfig(projectRoot);
-                let pkgSlug;
-                if (skillMdOnly) {
-                    // 就地生成：规程链接基于工作区实际子目录名
-                    pkgSlug = basename(resolve(projectRoot));
-                }
-                else {
-                    pkgSlug = getPackageSlug(config.id);
-                    if (usedDirNames.has(pkgSlug)) {
-                        pkgSlug = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/^-+|-+$/g, "");
-                    }
-                    usedDirNames.add(pkgSlug);
-                }
-                let actionIds;
-                let playbookIds;
-                let manifest;
-                if (skillMdOnly) {
-                    // 仅生成 SKILL.md：直接读取清单获取 Action 契约描述，不拷贝子包产物
-                    manifest = loadManifest(projectRoot);
-                    actionIds = manifest?.actions ? Object.keys(manifest.actions) : [];
-                    playbookIds = Array.from(loadPlaybooks(projectRoot, config.playbooksDir).keys());
-                }
-                else {
-                    const destPkgDir = join(packagesDestDir, pkgSlug);
-                    const singleExport = await this.export({
-                        projectRoot,
-                        outDir: destPkgDir,
-                        archive: false,
-                        skipSkillMd: true,
-                        mode: "source",
-                        _isSubpackage: true,
-                    });
-                    manifest = loadManifest(destPkgDir) || loadManifest(projectRoot);
-                    actionIds = singleExport.actions;
-                    playbookIds = singleExport.playbooks;
-                }
-                const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
-                const actionEntries = actionIds.map((actId) => ({
-                    id: actId,
-                    description: manifest?.actions?.[actId]?.description,
-                }));
-                packageInfos.push({
-                    config,
-                    actions: actionEntries,
-                    playbooks: Array.from(playbooks.values()),
-                    packageDir: pkgSlug,
-                });
-                packageSummaries.push({
-                    packageId: config.id,
-                    actions: actionIds,
-                    playbooks: playbookIds,
-                });
-            }
-            existingSkillPath = skillMdOnly ? undefined : findExistingCompositeSkillMd(options);
-            const description = options.description ||
-                customDeclaration?.description ||
-                `ActionDock 复合技能套件，聚合 ${packageInfos.map((p) => p.config.name).join("、")}`;
-            const compositeSkillMd = generateCompositeSkillMd(options.bundleName, description, packageInfos, {
-                customSections: customDeclaration?.sections,
-                packagesBaseDir: skillMdOnly ? "." : "packages",
-            });
-            if (skillMdOnly) {
-                // 就地仅重生成 SKILL.md：始终重新生成（忽略已有 SKILL.md 复用逻辑），不产出完整套件目录
-                const targetFile = options.outDir && options.outDir.toLowerCase().endsWith(".md")
-                    ? resolve(options.outDir)
-                    : resolve(options.outDir ? join(options.outDir, "SKILL.md") : join(process.cwd(), "SKILL.md"));
-                mkdirSync(dirname(targetFile), { recursive: true });
-                // 目标文件即将被覆盖时输出警告，避免无提示覆盖用户已有内容
-                if (existsSync(targetFile)) {
-                    console.warn(`[WARN] Existing SKILL.md will be overwritten: ${targetFile}`);
-                }
-                writeFileSync(targetFile, compositeSkillMd, "utf-8");
-                return {
-                    bundleName: options.bundleName,
-                    skillDir: dirname(targetFile),
-                    skillMdFile: targetFile,
-                    packagesCount: packageInfos.length,
-                    actionsCount: packageInfos.reduce((acc, p) => acc + p.actions.length, 0),
-                    playbooksCount: packageInfos.reduce((acc, p) => acc + p.playbooks.length, 0),
-                    packages: packageSummaries,
-                    files: [basename(targetFile)],
-                };
-            }
-            if (existingSkillPath) {
-                const destSkillMdPath = join(stagingDir, "SKILL.md");
-                if (resolve(existingSkillPath) !== resolve(destSkillMdPath)) {
-                    copyFileSync(existingSkillPath, destSkillMdPath);
-                }
-            }
-            else {
-                writeFileSync(join(stagingDir, "SKILL.md"), compositeSkillMd, "utf-8");
-            }
-            // 聚合所有子包依赖生成复合根目录 package.json
-            writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options);
-            // 原子替换目标复合技能目录
-            await replaceDirAtomic(stagingDir, targetSkillDir);
-        }
-        finally {
-            if (stagingDir && existsSync(stagingDir)) {
-                rmSync(stagingDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
-            }
-        }
-        let archivePath;
-        if (options.archive) {
-            archivePath = await createArchive(targetSkillDir, resolveArchiveFormat(options));
-        }
-        return {
-            bundleName: options.bundleName,
-            skillDir: targetSkillDir,
-            archivePath,
-            packagesCount: packageInfos.length,
-            actionsCount: packageInfos.reduce((acc, p) => acc + p.actions.length, 0),
-            playbooksCount: packageInfos.reduce((acc, p) => acc + p.playbooks.length, 0),
-            packages: packageSummaries,
-            files: collectRelativeFiles(targetSkillDir),
-            // 复用中段已计算的路径，避免结尾重复扫描
-            usedExistingSkillMd: existingSkillPath,
-        };
-    }
-    /**
-     * 静态辅助调用复合导出方法。
-     * @deprecated 实例方法的历史便捷入口，请直接使用实例方法，将在两个版本后移除。
-     */
-    static async exportComposite(options) {
-        const exporter = new SkillExporter();
-        return exporter.exportComposite(options);
+        return exportCompositeImpl(options, (opts) => this.export(opts));
     }
 }
 /**
- * 导出单个 Skill 产物的顶层便捷函数。
- * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
+ * 导出单个 Skill 产物的顶层公共入口函数。
+ * 内部创建 SkillExporter 实例并委托其实例导出方法，适合常规单次导出场景；
+ * 需要复用导出器或定制行为时可直接实例化 SkillExporter。
  */
 export async function exportSkill(options) {
     const exporter = new SkillExporter();
     return exporter.export(options);
 }
 /**
- * 批量导出多个 Skill 产物的顶层便捷函数。
- * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
+ * 批量导出多个 Skill 产物的顶层公共入口函数。
+ * 内部创建 SkillExporter 实例并委托其实例批量导出方法。
  */
 export async function exportSkillBatch(options) {
-    return SkillExporter.exportBatch(options);
+    const exporter = new SkillExporter();
+    return exporter.exportBatch(options);
 }
 /**
- * 导出复合技能套件的顶层便捷函数。
- * @deprecated SkillExporter 实例与静态方法之外的历史第三入口，请直接使用 SkillExporter 实例，将在两个版本后移除。
+ * 导出复合技能套件的顶层公共入口函数。
+ * 内部创建 SkillExporter 实例并委托其实例复合导出方法。
  */
 export async function exportCompositeSkill(options) {
-    return SkillExporter.exportComposite(options);
+    const exporter = new SkillExporter();
+    return exporter.exportComposite(options);
 }