@actiondock/builder 2.5.0 → 2.6.0

package/README.md

@@ -12,11 +12,11 @@ ActionDock 2.0 构建规划、目录交付与技能导出包。
 
 ## 核心组件与能力
 
-### BuildPlanner 依赖闭包计算器
+### SelectionPlanner 依赖闭包计算器
 
 通过静态分析依赖关系与 Playbook 规程，无需执行任何业务代码，杜绝模块加载过程中的副作用：
 
-- 规划模型：[SelectionPlanner](./src/planner.ts)（别名 BuildPlanner）读取 `actiondock.json` 与 Playbook 的 YAML 头部，提取 Actions 与 Playbooks 映射。
+- 规划模型：[SelectionPlanner](./src/planner.ts) 读取 `actiondock.json` 与 Playbook 的 YAML 头部，提取 Actions 与 Playbooks 映射。
 - 递归依赖闭包：自顶向下递归解析 Action 的 `uses` 声明列表，构建完整的静态调用图。
 - 规程驱动按需剪枝：支持针对特定 Playbook 进行定向打包，自动计算并仅保留该 Playbook 直接或间接调用的最小 Action 集合，实现依赖按需裁剪。
 - 静态资产收集：自动识别并关联声明的静态资产文件。
@@ -55,11 +55,11 @@ ActionDock 2.0 构建规划、目录交付与技能导出包。
 ## 编程调用示例
 
 ```ts
-import { buildProject, packProject, SelectionPlanner, SkillExporter } from "@actiondock/builder";
+import { buildProject, packProject, SelectionPlanner, SkillExporter, exportSkill } from "@actiondock/builder";
 
 // 计算依赖规划闭包
 const planner = new SelectionPlanner({ projectRoot: "/path/to/project" });
-const plan = planner.createPlan({ playbookId: "review-pr" });
+const plan = planner.plan({ projectRoot: "/path/to/project", playbooks: ["review-pr"] });
 
 // 构建 Node.js 目录交付产物
 const buildResult = await buildProject({
@@ -74,11 +74,19 @@ const packResult = await packProject({
   outDir: "./dist/npm",
 });
 
-// 导出 Agent Skill 资产
-const exporter = new SkillExporter({ projectRoot: "/path/to/project" });
-const skillResult = await exporter.export({
-  outputDir: "./dist/skills",
-  playbookId: "review-pr",
+// 导出 Agent Skill 资产（顶层便捷入口，内部委托 SkillExporter 实例方法）
+const skillResult = await exportSkill({
+  projectRoot: "/path/to/project",
+  outDir: "./dist/skills",
+  playbooks: ["review-pr"],
+  mode: "source",
+});
+
+// 或直接实例化 SkillExporter 定制导出
+const exporter = new SkillExporter();
+const customResult = await exporter.export({
+  projectRoot: "/path/to/project",
+  outDir: "./dist/skills-custom",
   mode: "source",
 });
 ```

package/dist/build.js

@@ -178,7 +178,7 @@ const argv = process.argv.slice(2);
 
 // 1. 监督进程接管参数校验，明确拒绝 --async
 if (argv.includes("--async")) {
-  const isJson = argv.includes("--json") || argv.includes("--envelope");
+  const isJson = argv.includes("--json");
   if (isJson) {
     console.log(
       JSON.stringify(

package/dist/export-archive.d.ts

@@ -0,0 +1,20 @@
+import type { ArchiveFormat } from "./types.js";
+/**
+ * 导出产物归档辅助层。
+ *
+ * 归档压缩能力的单一事实源在 ./archive，此处仅承载面向导出流程的
+ * 目标路径推导与临时文件清理语义，严禁重复实现压缩逻辑。
+ */
+/**
+ * 执行归档压缩操作。
+ * 先压缩到临时路径，成功后原子重命名覆盖最终路径；失败时清理临时文件后透传原始异常，
+ * 避免旧档已删、新档半成品残留的中间态。
+ */
+export declare function createArchive(skillDir: string, format: ArchiveFormat): Promise<string>;
+/**
+ * 解析归档格式：显式 archiveFormat 优先，archive 字段直接携带格式时其次。
+ */
+export declare function resolveArchiveFormat(options: {
+    archive?: boolean | ArchiveFormat;
+    archiveFormat?: ArchiveFormat;
+}): ArchiveFormat;

package/dist/export-archive.js

@@ -0,0 +1,52 @@
+import { existsSync, rmSync, renameSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { createTarGzArchiveAsync, createZipArchiveAsync } from "./archive.js";
+import { BuilderError } from "./errors.js";
+/**
+ * 导出产物归档辅助层。
+ *
+ * 归档压缩能力的单一事实源在 ./archive，此处仅承载面向导出流程的
+ * 目标路径推导与临时文件清理语义，严禁重复实现压缩逻辑。
+ */
+/**
+ * 执行归档压缩操作。
+ * 先压缩到临时路径，成功后原子重命名覆盖最终路径；失败时清理临时文件后透传原始异常，
+ * 避免旧档已删、新档半成品残留的中间态。
+ */
+export 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 字段直接携带格式时其次。
+ */
+export function resolveArchiveFormat(options) {
+    if (options.archiveFormat === "tar.gz" || options.archive === "tar.gz") {
+        return "tar.gz";
+    }
+    return "zip";
+}

package/dist/export-batch.d.ts

@@ -0,0 +1,13 @@
+import type { BatchSkillExportOptions, BatchSkillExportResult, SkillExportResult, SkillExporterOptions } from "./types.js";
+/**
+ * 批量 Skill 导出装配层。
+ *
+ * 职责：按项目根目录列表逐一执行单包导出并聚合统计结果，
+ * 目录名冲突时回退为原始 Package ID 的安全形式。
+ */
+/** 单包导出回调：由 SkillExporter 注入自身导出能力，避免模块间循环依赖 */
+export type SingleSkillExporter = (options: SkillExporterOptions) => Promise<SkillExportResult>;
+/**
+ * 执行批量导出多个 Skill。
+ */
+export declare function exportBatchImpl(options: BatchSkillExportOptions, exportSingle: SingleSkillExporter): Promise<BatchSkillExportResult>;

package/dist/export-batch.js

@@ -0,0 +1,39 @@
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getPackageSlug, loadProjectConfig } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+/**
+ * 执行批量导出多个 Skill。
+ */
+export async function exportBatchImpl(options, exportSingle) {
+    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 exportSingle({
+            ...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,
+    };
+}

package/dist/export-composite.d.ts

@@ -0,0 +1,13 @@
+import type { CompositeSkillExportOptions, CompositeSkillExportResult, SkillExporterOptions, SkillExportResult } from "./types.js";
+/**
+ * 复合套件导出装配层。
+ *
+ * 职责：将多个包聚合为一个统一的复合技能目录（mini-workspace 形态），
+ * 聚合各子包依赖生成复合根 package.json，并生成或复用复合 SKILL.md。
+ */
+/** 子包导出回调：由 SkillExporter 注入自身导出能力，避免模块间循环依赖 */
+export type SubpackageExporter = (options: SkillExporterOptions) => Promise<SkillExportResult>;
+/**
+ * 执行复合模式导出：将多个包聚合为一个统一的复合技能目录。
+ */
+export declare function exportCompositeImpl(options: CompositeSkillExportOptions, exportSubpackage: SubpackageExporter): Promise<CompositeSkillExportResult>;

package/dist/export-composite.js

@@ -0,0 +1,225 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { generateCompositeSkillMd, getPackageSlug, loadManifest, loadPlaybooks, loadProjectConfig, } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+import { collectRelativeFiles, getInternalDependencyVersion, replaceDirAtomic } from "./fs-utils.js";
+import { assertNoFileProtocolDeps, resolveWorkspaceDepVersion } from "./manifest.js";
+import { SelectionPlanner } from "./planner.js";
+import { findExistingCompositeSkillMd, resolveCustomSkillDeclaration, } from "./skill-md.js";
+import { createArchive, resolveArchiveFormat } from "./export-archive.js";
+/**
+ * 执行复合模式导出：将多个包聚合为一个统一的复合技能目录。
+ */
+export async function exportCompositeImpl(options, exportSubpackage) {
+    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 exportSubpackage({
+                    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,
+    };
+}
+/**
+ * 复合套件聚合各子包依赖并生成复合根目录 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 parsed = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+                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");
+}

package/dist/export-node.d.ts

@@ -0,0 +1,11 @@
+import type { SelectionPlan, SkillExporterOptions, SkillExportResult } from "./types.js";
+/**
+ * Node 目录型 Skill 导出装配层。
+ *
+ * 职责：复用 Node 目录型构建产出可执行交付目录，
+ * 并在目录内生成调用该入口的 SKILL.md 说明书。
+ */
+/**
+ * 执行 Node 目录型 Skill 导出。
+ */
+export declare function exportNodeSkill(root: string, targetSkillDir: string, plan: SelectionPlan, options: SkillExporterOptions, pkgSlug: string): Promise<SkillExportResult>;

package/dist/export-node.js

@@ -0,0 +1,48 @@
+import { generateStandaloneSkillMd } from "@actiondock/core";
+import { buildProject } from "./build.js";
+import { collectRelativeFiles } from "./fs-utils.js";
+import { buildConfigForTemplates, toPlaybookDefinitions, toSkillActionItems, writeSkillMd, } from "./skill-md.js";
+import { createArchive, resolveArchiveFormat } from "./export-archive.js";
+/**
+ * Node 目录型 Skill 导出装配层。
+ *
+ * 职责：复用 Node 目录型构建产出可执行交付目录，
+ * 并在目录内生成调用该入口的 SKILL.md 说明书。
+ */
+/**
+ * 执行 Node 目录型 Skill 导出。
+ */
+export async function 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,
+    };
+}

package/dist/export-source.d.ts

@@ -0,0 +1,11 @@
+import type { SelectionPlan, SkillExporterOptions } from "./types.js";
+/**
+ * 源码型 Skill 导出装配层。
+ *
+ * 职责：在暂存目录内完成 SKILL.md、actiondock.json、package.json
+ * 与全部源码/资产/Playbook 文件的物化，产物保持源码形态可直接编辑。
+ */
+/**
+ * 源码型 Skill 的暂存阶段：生成 SKILL.md、actiondock.json、package.json 并拷贝源码。
+ */
+export declare function stageSourceSkill(root: string, skillDir: string, plan: SelectionPlan, options: SkillExporterOptions, pkgSlug: string): string | undefined;

package/dist/export-source.js

@@ -0,0 +1,134 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { generateSourceSkillMd } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
+import { getInternalDependencyVersion } from "./fs-utils.js";
+import { assertValidManifestActionIds, resolveWorkspaceDepVersion, serializePlanManifest, } from "./manifest.js";
+import { buildConfigForTemplates, toPlaybookDefinitions, toSkillActionItems, writeSkillMd, } from "./skill-md.js";
+/**
+ * 源码型 Skill 导出装配层。
+ *
+ * 职责：在暂存目录内完成 SKILL.md、actiondock.json、package.json
+ * 与全部源码/资产/Playbook 文件的物化，产物保持源码形态可直接编辑。
+ */
+/**
+ * 源码型 Skill 的暂存阶段：生成 SKILL.md、actiondock.json、package.json 并拷贝源码。
+ */
+export 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() },
+    };
+}