@actiondock/builder 2.7.0 → 2.8.0

package/dist/manifest.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { ACTION_ID_REGEX } from "@actiondock/core";
+import { ACTION_ID_REGEX, getPackageSlug } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 import { getInternalDependencyVersion } from "./fs-utils.js";
+import { isOwnAction } from "./types.js";
 /**
  * 校验清单 actions 字典中的所有 Action ID 是否符合规范。
  * 强制写入端契约自检，杜绝非法 Action ID 落盘。
@@ -57,7 +58,7 @@ export function serializePlanManifest(plan, options = {}) {
     const manifestActions = {};
     for (const act of plan.actions) {
         // 仅序列化包自有 Action，跨包依赖不写入包清单
-        if (act.isExternal || act.id.includes("/")) {
+        if (!isOwnAction(act)) {
             continue;
         }
         const serialized = serializeManifestAction(act);
@@ -174,6 +175,70 @@ export function resolveWorkspaceDepVersion(root, depName, ver) {
     }
     throw new BuilderError(`Failed to resolve workspace dependency '${depName}' (${ver}) in '${root}'. Target package version could not be found.`);
 }
+/**
+ * 为导出子包分配互不冲突的目录名。
+ *
+ * 首选 Package ID 尾段（getPackageSlug）；冲突时回退为 ID 全量的安全形式，
+ * 回退后仍冲突（如两个同尾段 ID 回退值相同）则追加数字后缀直至唯一，
+ * 严禁仅加入 used 集合而不二次消歧导致目录互相覆盖。
+ *
+ * @param used 已占用的目录名集合（函数内部会登记分配结果）
+ * @param configId 待分配目录名的 Package ID
+ */
+export function allocatePackageDirName(used, configId) {
+    let name = getPackageSlug(configId);
+    if (used.has(name)) {
+        name = configId.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/^-+|-+$/g, "");
+    }
+    if (!name) {
+        name = getPackageSlug(configId) || "package";
+    }
+    if (used.has(name)) {
+        let suffix = 2;
+        while (used.has(`${name}-${suffix}`)) {
+            suffix++;
+        }
+        name = `${name}-${suffix}`;
+    }
+    used.add(name);
+    return name;
+}
+/**
+ * 导出产物依赖清洗单一入口。
+ *
+ * 清洗规则（单包源码导出与复合套件聚合导出共用同一事实源）：
+ * - file: 本地协议拒绝（经 assertNoFileProtocolDeps）；
+ * - @actiondock/* 内部依赖覆写为内部版本规则；
+ * - workspace: 前缀解析为真实版本（经 resolveWorkspaceDepVersion）；
+ * - 其余依赖原样保留。
+ *
+ * @param root 解析 workspace 依赖时的参照根目录
+ * @param deps 待清洗的依赖字典（可选）
+ * @param context 错误消息中的场景描述
+ * @param ensureSdk 是否保证 @actiondock/sdk 依赖存在（单包导出需要，复合根目录已预置）
+ */
+export function sanitizeExportDependencies(root, deps, context, ensureSdk = true) {
+    const result = {};
+    assertNoFileProtocolDeps(deps, context);
+    if (deps && typeof deps === "object") {
+        for (const [depName, depVer] of Object.entries(deps)) {
+            const verStr = String(depVer);
+            if (depName.startsWith("@actiondock/")) {
+                result[depName] = getInternalDependencyVersion();
+            }
+            else if (verStr.startsWith("workspace:")) {
+                result[depName] = resolveWorkspaceDepVersion(root, depName, verStr);
+            }
+            else {
+                result[depName] = verStr;
+            }
+        }
+    }
+    if (ensureSdk && !result["@actiondock/sdk"]) {
+        result["@actiondock/sdk"] = getInternalDependencyVersion();
+    }
+    return result;
+}
 /**
  * 读取并解析 package.json，解析失败抛出 BuilderError。
  */

package/dist/pack.js

@@ -3,12 +3,15 @@ import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import { getPackageSlug, loadProjectConfig } from "@actiondock/core";
+import { basename, join, relative, resolve } from "node:path";
+import { loadProjectConfig } from "@actiondock/core";
+import { getPackageSlug } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 import { assertNoFileProtocolDeps, assertValidManifestActionIds, normalizePkgExportsAndEngines, readPackageJson, serializePlanManifest, } from "./manifest.js";
 import { collectRelativeFiles } from "./fs-utils.js";
 import { SelectionPlanner } from "./planner.js";
+import { isOwnAction } from "./types.js";
+import { copyPlanEntries } from "./stage-sources.js";
 /**
  * 对 Action Package 执行打包并生成标准 npm Action 压缩包（.tgz）。
  *
@@ -158,7 +161,7 @@ async function compileTypeScript(root, stagingPkgDir, plan) {
     const ts = await resolveTypeScriptCompiler(root);
     const tsSourceFiles = new Set();
     for (const act of plan.actions) {
-        if (act.isExternal || act.id.includes("/"))
+        if (!isOwnAction(act))
             continue;
         if (isTypeScriptSource(act.entry)) {
             tsSourceFiles.add(act.resolvedPath);
@@ -187,27 +190,34 @@ async function compileTypeScript(root, stagingPkgDir, plan) {
     if (existsSync(tsconfigPath)) {
         try {
             const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
-            if (!configFile.error) {
-                const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, root);
-                // tsc 不会改写 import 说明符：paths 路径别名在产物中无法解析，必须显式拒绝而非静默编译出坏产物
-                if (parsedConfig.options.paths && Object.keys(parsedConfig.options.paths).length > 0) {
-                    throw new BuilderError(`tsconfig.json 'paths' aliases are not supported in packed output: TypeScript does not rewrite import specifiers, so the packed artifact would contain unresolvable module specifiers. Replace path aliases with relative imports, or pre-build the project and pack the compiled output instead.`, "PATHS_ALIAS_UNSUPPORTED");
-                }
-                Object.assign(compilerOptions, parsedConfig.options, {
-                    outDir: stagingPkgDir,
-                    rootDir: root,
-                    declaration: true,
-                    emitDeclarationOnly: false,
-                    rewriteRelativeImportExtensions: true,
-                    noEmit: false,
-                });
+            if (configFile.error) {
+                throw new Error(ts.formatDiagnostic(configFile.error));
             }
+            const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, root);
+            if (parsedConfig.errors && parsedConfig.errors.length > 0) {
+                throw new Error(ts.formatDiagnostics(parsedConfig.errors));
+            }
+            // tsc 不会改写 import 说明符：paths 路径别名在产物中无法解析，必须显式拒绝而非静默编译出坏产物
+            if (parsedConfig.options.paths && Object.keys(parsedConfig.options.paths).length > 0) {
+                throw new BuilderError(`tsconfig.json 'paths' aliases are not supported in packed output: TypeScript does not rewrite import specifiers, so the packed artifact would contain unresolvable module specifiers. Replace path aliases with relative imports, or pre-build the project and pack the compiled output instead.`, "PATHS_ALIAS_UNSUPPORTED");
+            }
+            Object.assign(compilerOptions, parsedConfig.options, {
+                outDir: stagingPkgDir,
+                rootDir: root,
+                declaration: true,
+                emitDeclarationOnly: false,
+                rewriteRelativeImportExtensions: true,
+                noEmit: false,
+            });
         }
         catch (err) {
             if (err instanceof BuilderError) {
                 throw err;
             }
-            // 忽略 tsconfig 解析失败，回退到标准 compilerOptions
+            // tsconfig 解析失败回退默认 compilerOptions，但必须输出显著告警：
+            // 用户配置的 strict、target 等被丢弃可能编译出行为不同的产物，严禁无提示
+            const reason = err instanceof Error ? err.message : String(err);
+            console.warn(`[actiondock] Warning: Failed to parse tsconfig.json at ${tsconfigPath}; falling back to default compiler options for packed output. Root cause: ${reason}`);
         }
     }
     const host = ts.createCompilerHost(compilerOptions);
@@ -228,36 +238,16 @@ async function compileTypeScript(root, stagingPkgDir, plan) {
 }
 /**
  * 拷贝声明的非 TypeScript 模块、静态资产、原生 JavaScript 入口、Playbook 与基础文档到暂存目录。
+ * 拷贝内核统一复用 stage-sources 的 copyPlanEntries，仅通过谓词分化编译排除差异。
  */
 function stageSources(root, stagingPkgDir, plan) {
-    // 拷贝声明的非 TypeScript 模块与静态资产
-    for (const dep of plan.dependencies.modulesAndAssets) {
-        if ((dep.type === "asset" || dep.type === "module" || dep.type === "file") &&
-            existsSync(dep.resolvedPath)) {
-            if (isTypeScriptSource(dep.path)) {
-                continue; // 已由 TypeScript 编译生成 .js 与 .d.ts
-            }
-            const destPath = join(stagingPkgDir, dep.path);
-            mkdirSync(dirname(destPath), { recursive: true });
-            copyFileSync(dep.resolvedPath, destPath);
-        }
-    }
-    // 拷贝原生 JavaScript Action 入口（若存在）
-    for (const act of plan.actions) {
-        if (!isTypeScriptSource(act.entry)) {
-            const destPath = join(stagingPkgDir, act.entry);
-            mkdirSync(dirname(destPath), { recursive: true });
-            copyFileSync(act.resolvedPath, destPath);
-        }
-    }
-    // 拷贝 Playbook 规程文件
-    for (const pb of plan.playbooks) {
-        if (existsSync(pb.filePath)) {
-            const destPb = join(stagingPkgDir, relative(root, pb.filePath));
-            mkdirSync(dirname(destPb), { recursive: true });
-            copyFileSync(pb.filePath, destPb);
-        }
-    }
+    copyPlanEntries(stagingPkgDir, plan, {
+        // TypeScript 入口已由编译阶段生成 .js 与 .d.ts，不重复物化源文件
+        copyAction: (act) => !isTypeScriptSource(act.entry),
+        copyModule: (dep) => !isTypeScriptSource(dep.path),
+        // pack 产物保留源工程相对路径（与编译输出的目录结构一致）
+        playbookRelPath: (pb) => relative(root, pb.filePath),
+    });
     // 拷贝 README 等基础文档（若存在）
     for (const doc of ["README.md", "readme.md", "LICENSE", "license"]) {
         const srcDoc = join(root, doc);
@@ -285,7 +275,7 @@ function writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson) {
     // 构建编译后的 Action 清单字典并严格校验入口扩展名
     const compiledEntries = new Map();
     for (const act of plan.actions) {
-        if (act.isExternal || act.id.includes("/"))
+        if (!isOwnAction(act))
             continue;
         const destEntry = compiledEntryFor(act);
         if (!destEntry.endsWith(".js") && !destEntry.endsWith(".mjs")) {

package/dist/planner.js

@@ -1,64 +1,33 @@
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
-import { assertPathWithinRoot, loadManifest, loadPlaybooks, loadProjectConfig, resolveActionProjectSync, validateManifest, } from "@actiondock/core";
+import { loadProjectConfig, } from "@actiondock/core";
+import { assertPathWithinRoot, traverseDirectory, loadManifest, loadPlaybooks, validateManifest, } from "@actiondock/core/project";
+import { DefaultActionCatalog, PackageGraphBuilder, resolveAction, } from "@actiondock/core/graph";
 import { PlannerError } from "./errors.js";
 import { assertRelativeDependenciesIntegrity } from "./dependency-check.js";
 /**
  * 递归扫描指定目录下的文件，返回绝对路径列表。
- * 通过安全路径边界能力校验，阻止越界并避免符号链接逃逸。
+ * 目录遍历统一复用 core 的 traverseDirectory 单一事实源，
+ * 自带软链接越界防护与循环拦截。
  */
-function walkDirectory(dir, rootDir = dir, visited = new Set()) {
-    if (!existsSync(dir))
-        return [];
-    const results = [];
-    const entries = readdirSync(dir);
-    for (const entry of entries) {
-        const fullPath = join(dir, entry);
-        if (rootDir) {
-            try {
-                assertPathWithinRoot(rootDir, fullPath, "planner path");
-            }
-            catch {
-                continue;
-            }
-        }
-        let real;
-        try {
-            real = existsSync(fullPath) ? realpathSync(fullPath) : fullPath;
-        }
-        catch {
-            continue;
-        }
-        if (rootDir) {
-            try {
-                assertPathWithinRoot(rootDir, real, "planner path");
-            }
-            catch {
-                // 忽略并跳过指向项目根目录外部的软链接
-                continue;
-            }
-        }
-        if (visited.has(real)) {
-            continue;
-        }
-        visited.add(real);
-        try {
-            const stat = statSync(fullPath);
-            if (stat.isDirectory()) {
-                results.push(...walkDirectory(fullPath, rootDir, visited));
-            }
-            else if (stat.isFile()) {
-                results.push(fullPath);
-            }
-        }
-        catch {
-            // 忽略无法访问或损坏的文件/符号链接
-            continue;
-        }
-    }
-    return results;
+function walkDirectory(dir) {
+    return traverseDirectory(dir).map((entry) => entry.fullPath);
 }
+/**
+ * 测试与类型声明文件后缀常量（供 fallback 清单过滤与 isIgnoredPath 共享同一口径）。
+ */
+const TEST_FILE_SUFFIXES = [
+    ".test.ts",
+    ".test.js",
+    ".test.tsx",
+    ".test.jsx",
+    ".spec.ts",
+    ".spec.js",
+    ".spec.tsx",
+    ".spec.jsx",
+    ".d.ts",
+];
 /**
  * 忽略的文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。
  */
@@ -69,15 +38,7 @@ function isIgnoredPath(relPath) {
         normalized.startsWith(".git/") ||
         normalized.startsWith("dist/") ||
         normalized.startsWith(".actiondock/") ||
-        normalized.endsWith(".test.ts") ||
-        normalized.endsWith(".test.js") ||
-        normalized.endsWith(".test.tsx") ||
-        normalized.endsWith(".test.jsx") ||
-        normalized.endsWith(".spec.ts") ||
-        normalized.endsWith(".spec.js") ||
-        normalized.endsWith(".spec.tsx") ||
-        normalized.endsWith(".spec.jsx") ||
-        normalized.endsWith(".d.ts"));
+        TEST_FILE_SUFFIXES.some((suffix) => normalized.endsWith(suffix)));
 }
 /**
  * 支持的包管理器锁文件候选列表。
@@ -122,8 +83,9 @@ function computeLockfileInfo(projectRoot, preferredLockfile) {
                     };
                 }
             }
-            catch {
-                continue;
+            catch (err) {
+                // 存在但不可读：显式报错而非静默跳过，否则构建在无锁文件摘要状态下继续，可复现性校验形同虚设
+                throw new PlannerError(`Lockfile '${lockFileName}' exists but could not be read in ${projectRoot}: ${err?.message || String(err)}`, "LOCKFILE_READ_ERROR");
             }
         }
     }
@@ -153,12 +115,13 @@ function generateFallbackManifest(projectRoot, actionsDir = "actions", config) {
             }
         }
     }
-    // 若 actions 目录存在，基于文件名建立默认映射
+    // 若 actions 目录存在，基于文件名建立默认映射（过滤规则与 isIgnoredPath 保持同一口径）
     if (existsSync(dir)) {
-        const files = walkDirectory(dir, projectRoot).filter((f) => (f.endsWith(".ts") || f.endsWith(".js")) &&
-            !f.endsWith(".d.ts") &&
-            !f.endsWith(".test.ts") &&
-            !f.endsWith(".spec.ts"));
+        const files = walkDirectory(dir).filter((f) => {
+            const rel = relative(projectRoot, f).replace(/\\/g, "/");
+            return ((f.endsWith(".ts") || f.endsWith(".js")) &&
+                !isIgnoredPath(rel));
+        });
         for (const file of files) {
             const relPath = relative(projectRoot, file).replace(/\\/g, "/");
             const filename = basename(file);
@@ -180,38 +143,43 @@ function generateFallbackManifest(projectRoot, actionsDir = "actions", config) {
 }
 /**
  * 收集项目根目录 package.json 中声明的外部 npm 依赖。
+ *
+ * 防御与透明原则：文件不存在返回空集合（合法的无依赖工程）；
+ * 文件存在但不可读或 JSON 损坏时抛 PlannerError 并携带路径与原因，
+ * 严禁静默吞掉导致后续 build 的生产依赖、pack 的产物依赖与 vendorDeps 全部无声缺失。
  */
 function extractExternalDependencies(projectRoot) {
     const pkgPath = join(projectRoot, "package.json");
     if (!existsSync(pkgPath))
         return [];
+    let parsed;
     try {
         const raw = readFileSync(pkgPath, "utf-8");
-        const parsed = JSON.parse(raw);
-        const deps = [];
-        if (parsed.dependencies && typeof parsed.dependencies === "object") {
-            for (const [name, versionRange] of Object.entries(parsed.dependencies)) {
-                deps.push({
-                    name,
-                    versionRange: String(versionRange),
-                    isDev: false,
-                });
-            }
-        }
-        if (parsed.devDependencies && typeof parsed.devDependencies === "object") {
-            for (const [name, versionRange] of Object.entries(parsed.devDependencies)) {
-                deps.push({
-                    name,
-                    versionRange: String(versionRange),
-                    isDev: true,
-                });
-            }
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new PlannerError(`Failed to read or parse package.json at ${pkgPath}: ${err?.message || String(err)}`, "EXTRACT_DEPS_ERROR");
+    }
+    const deps = [];
+    if (parsed.dependencies && typeof parsed.dependencies === "object") {
+        for (const [name, versionRange] of Object.entries(parsed.dependencies)) {
+            deps.push({
+                name,
+                versionRange: String(versionRange),
+                isDev: false,
+            });
         }
-        return deps;
     }
-    catch {
-        return [];
+    if (parsed.devDependencies && typeof parsed.devDependencies === "object") {
+        for (const [name, versionRange] of Object.entries(parsed.devDependencies)) {
+            deps.push({
+                name,
+                versionRange: String(versionRange),
+                isDev: true,
+            });
+        }
     }
+    return deps;
 }
 /**
  * 声明式选择集与构建规划器 (SelectionPlanner)。
@@ -335,6 +303,8 @@ export class SelectionPlanner {
         const externalActionRoots = new Map();
         const externalActionEntries = new Map();
         const manifestActions = manifest.actions || {};
+        const graph = new PackageGraphBuilder({ root, allowDevLinks: true }).buildSync();
+        const catalog = new DefaultActionCatalog(graph);
         while (queue.length > 0) {
             const currentId = queue.shift();
             queued.delete(currentId);
@@ -345,26 +315,27 @@ export class SelectionPlanner {
             let entryRoot = root;
             if (!entry) {
                 try {
-                    const resolvedExternal = resolveActionProjectSync(currentId, root);
-                    if (resolvedExternal && existsSync(resolvedExternal.projectRoot)) {
-                        const extRoot = resolvedExternal.projectRoot;
+                    const resolved = resolveAction(currentId, { graph, catalog, caller: config?.id });
+                    const extNode = graph.packages.get(resolved.package.id);
+                    if (extNode && existsSync(extNode.root)) {
+                        const extRoot = extNode.root;
                         let extConfig;
                         try {
                             extConfig = loadProjectConfig(extRoot);
                         }
                         catch {
                             extConfig = {
-                                id: resolvedExternal.packageId,
-                                name: resolvedExternal.packageId,
+                                id: resolved.package.id,
+                                name: resolved.package.id,
                                 version: "0.1.0",
                             };
                         }
                         const externalManifest = loadManifest(extRoot);
-                        let externalEntry = externalManifest?.actions?.[resolvedExternal.actionId] ||
-                            extConfig?.actions?.[resolvedExternal.actionId];
+                        let externalEntry = externalManifest?.actions?.[resolved.ref.actionId] ||
+                            extConfig?.actions?.[resolved.ref.actionId];
                         if (!externalEntry) {
                             const staticManifest = generateFallbackManifest(extRoot, extConfig.actionsDir || "actions", extConfig);
-                            externalEntry = staticManifest.actions?.[resolvedExternal.actionId];
+                            externalEntry = staticManifest.actions?.[resolved.ref.actionId];
                         }
                         if (externalEntry) {
                             entry = externalEntry;
@@ -470,7 +441,7 @@ export class SelectionPlanner {
             }
             const stat = statSync(resolvedFile);
             if (stat.isDirectory()) {
-                const walked = walkDirectory(resolvedFile, root);
+                const walked = walkDirectory(resolvedFile);
                 for (const f of walked) {
                     const rel = relative(root, f).replace(/\\/g, "/");
                     if (!isIgnoredPath(rel) && !actionPathSet.has(f) && !filePathSet.has(rel)) {
@@ -517,7 +488,7 @@ export class SelectionPlanner {
             }
             const stat = statSync(resolvedAsset);
             if (stat.isDirectory()) {
-                const walked = walkDirectory(resolvedAsset, root);
+                const walked = walkDirectory(resolvedAsset);
                 for (const f of walked) {
                     const rel = relative(root, f).replace(/\\/g, "/");
                     if (!assetPathSet.has(rel)) {
@@ -545,7 +516,7 @@ export class SelectionPlanner {
         // 默认 assets 目录扫描
         const defaultAssetsDir = join(root, "assets");
         if (existsSync(defaultAssetsDir)) {
-            const assetFiles = walkDirectory(defaultAssetsDir, root);
+            const assetFiles = walkDirectory(defaultAssetsDir);
             for (const file of assetFiles) {
                 const rel = relative(root, file).replace(/\\/g, "/");
                 if (!assetPathSet.has(rel)) {

package/dist/skill/index.d.ts

@@ -0,0 +1 @@
+export * from "./templates.js";

package/dist/skill/index.js

@@ -0,0 +1 @@
+export * from "./templates.js";

package/dist/skill/templates.d.ts

@@ -0,0 +1,60 @@
+import type { ActionSpec, ProjectConfig } from "@actiondock/core";
+import type { PlaybookDefinition } from "@actiondock/core/project";
+export type SkillActionItem = ActionSpec | {
+    id: string;
+    description?: string;
+    inputSchema?: any;
+    outputSchema?: any;
+    annotations?: any;
+};
+export declare function generateSourceSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: PlaybookDefinition[]): string;
+export declare function generateStandaloneSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: PlaybookDefinition[], binaryRelPath?: string): string;
+export interface CompositeSkillPackageInfo {
+    config: ProjectConfig;
+    actions: Array<{
+        id: string;
+        description?: string;
+    }>;
+    playbooks: Array<{
+        id: string;
+        name?: string;
+        description?: string;
+        filePath: string;
+    }>;
+    packageDir: string;
+}
+/**
+ * 复合技能自定义说明书（SKILL.custom.md）的槽位，
+ * 决定自定义段落插入到官方模板生成结果中的位置。
+ */
+export type CompositeCustomSlot = "intro" | "after-init" | "after-describe" | "after-actions" | "after-playbooks" | "after-invoke" | "append";
+export declare const COMPOSITE_CUSTOM_SLOTS: readonly CompositeCustomSlot[];
+/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
+export declare const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
+export interface CompositeCustomSection {
+    slot: CompositeCustomSlot;
+    content: string;
+}
+export interface CompositeCustomDeclaration {
+    /** 自定义说明书 frontmatter 中声明的 description 覆盖值 */
+    description?: string;
+    sections: CompositeCustomSection[];
+}
+/**
+ * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。
+ * 首个标记之前的内容归入 `append` 槽位；未知槽位名直接抛错，避免拼写错误被静默吞掉。
+ */
+export declare function parseCustomSections(source: string): CompositeCustomSection[];
+/**
+ * 解析复合技能自定义说明书文件：支持 YAML frontmatter 中的 `description` 覆盖，
+ * 正文按槽位标记解析为自定义段落。
+ */
+export declare function parseCustomSkillDeclaration(source: string): CompositeCustomDeclaration;
+/**
+ * 生成多包聚合的复合模式 SKILL.md 文档。
+ */
+export declare function generateCompositeSkillMd(bundleName: string, description: string, packages: CompositeSkillPackageInfo[], options?: {
+    customSections?: CompositeCustomSection[];
+    /** 规程链接的子包目录前缀：导出布局为 "packages"（默认）；就地生成时传 "." 使用工作区实际目录 */
+    packagesBaseDir?: string;
+}): string;