@actiondock/builder 2.10.0 → 2.12.0

package/dist/pack.js

@@ -1,7 +1,6 @@
-import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { runNpmPack } from "./npm-pack.js";
 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, join, relative, resolve } from "node:path";
 import { loadProjectConfig } from "@actiondock/core";
@@ -16,8 +15,8 @@ import { copyPlanEntries } from "./stage-sources.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 打包参数选项
@@ -47,7 +46,6 @@ export async function packProject(options) {
     const stagingPkgDir = join(tempBase, "package");
     mkdirSync(stagingPkgDir, { recursive: true });
     try {
-        await compileTypeScript(root, stagingPkgDir, plan);
         stageSources(root, stagingPkgDir, plan);
         writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson);
         // 收集打包文件相对清单与摘要
@@ -123,129 +121,12 @@ export async function packProject(options) {
     }
 }
 /**
- * 判断文件路径是否为 TypeScript 源码。
- */
-function isTypeScriptSource(path) {
-    return path.endsWith(".ts") || path.endsWith(".mts");
-}
-/**
- * 解析项目本地 TypeScript 编译器（回退到打包工具自身依赖）。
- */
-async function resolveTypeScriptCompiler(root) {
-    try {
-        const req = createRequire(join(root, "package.json"));
-        const tsPath = req.resolve("typescript");
-        const imported = await import(tsPath);
-        return imported.default || imported;
-    }
-    catch {
-        try {
-            const imported = await import("typescript");
-            return imported.default || imported;
-        }
-        catch {
-            throw new BuilderError(`TypeScript is required to pack TypeScript Action packages, but 'typescript' could not be resolved from ${root}.`);
-        }
-    }
-}
-/**
- * 在暂存目录内执行 TypeScript 编译，产出 .js 与 .d.ts。
- * 仅在存在 TypeScript 源码时执行。
- */
-async function compileTypeScript(root, stagingPkgDir, plan) {
-    const hasTypeScript = plan.actions.some((a) => isTypeScriptSource(a.entry)) ||
-        plan.dependencies.modulesAndAssets.some((m) => (m.type === "module" || m.type === "file") && isTypeScriptSource(m.path));
-    if (!hasTypeScript) {
-        return;
-    }
-    const ts = await resolveTypeScriptCompiler(root);
-    const tsSourceFiles = new Set();
-    for (const act of plan.actions) {
-        if (!isOwnAction(act))
-            continue;
-        if (isTypeScriptSource(act.entry)) {
-            tsSourceFiles.add(act.resolvedPath);
-        }
-    }
-    for (const mod of plan.dependencies.modulesAndAssets) {
-        if ((mod.type === "module" || mod.type === "file") && isTypeScriptSource(mod.path)) {
-            tsSourceFiles.add(mod.resolvedPath);
-        }
-    }
-    const compilerOptions = {
-        target: ts.ScriptTarget.ES2022,
-        module: ts.ModuleKind.NodeNext,
-        moduleResolution: ts.ModuleResolutionKind.NodeNext,
-        declaration: true,
-        emitDeclarationOnly: false,
-        rewriteRelativeImportExtensions: true,
-        rootDir: root,
-        outDir: stagingPkgDir,
-        skipLibCheck: true,
-        esModuleInterop: true,
-        allowSyntheticDefaultImports: true,
-        allowJs: true,
-    };
-    const tsconfigPath = join(root, "tsconfig.json");
-    if (existsSync(tsconfigPath)) {
-        try {
-            const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
-            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，但必须输出显著告警：
-            // 用户配置的 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);
-    const program = ts.createProgram(Array.from(tsSourceFiles), compilerOptions, host);
-    const emitResult = program.emit();
-    const preEmitDiagnostics = ts.getPreEmitDiagnostics(program);
-    const allDiagnostics = [...preEmitDiagnostics, ...emitResult.diagnostics];
-    const errors = allDiagnostics.filter((d) => d.category === ts.DiagnosticCategory.Error);
-    if (errors.length > 0 || emitResult.emitSkipped) {
-        const diagnosticsToFormat = errors.length > 0 ? errors : allDiagnostics;
-        const formatted = ts.formatDiagnosticsWithColorAndContext(diagnosticsToFormat, {
-            getCanonicalFileName: (f) => f,
-            getCurrentDirectory: () => root,
-            getNewLine: () => "\n",
-        });
-        throw new BuilderError(`TypeScript compilation failed during pack:\n${formatted}`);
-    }
-}
-/**
- * 拷贝声明的非 TypeScript 模块、静态资产、原生 JavaScript 入口、Playbook 与基础文档到暂存目录。
- * 拷贝内核统一复用 stage-sources 的 copyPlanEntries，仅通过谓词分化编译排除差异。
+ * 拷贝声明的 Action 源码、模块、静态资产、Playbook 与基础文档到暂存目录。
+ * 依托 Node 24 原生类型擦除，完整保留 TypeScript 源码与声明资产。
  */
 function stageSources(root, stagingPkgDir, plan) {
     copyPlanEntries(stagingPkgDir, plan, {
-        // TypeScript 入口已由编译阶段生成 .js 与 .d.ts，不重复物化源文件
-        copyAction: (act) => !isTypeScriptSource(act.entry),
-        copyModule: (dep) => !isTypeScriptSource(dep.path),
-        // pack 产物保留源工程相对路径（与编译输出的目录结构一致）
+        // pack 产物保留源工程相对路径
         playbookRelPath: (pb) => relative(root, pb.filePath),
     });
     // 拷贝 README 等基础文档（若存在）
@@ -256,42 +137,22 @@ function stageSources(root, stagingPkgDir, plan) {
         }
     }
 }
-/**
- * 计算编译后的 Action 入口相对路径（.ts 转 .js、.mts 转 .mjs）。
- */
-function compiledEntryFor(action) {
-    if (action.entry.endsWith(".ts")) {
-        return action.entry.slice(0, -3) + ".js";
-    }
-    if (action.entry.endsWith(".mts")) {
-        return action.entry.slice(0, -4) + ".mjs";
-    }
-    return action.entry;
-}
 /**
  * 生成并写入严格校验后的 actiondock.json 与规范化 package.json。
  */
 function writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson) {
-    // 构建编译后的 Action 清单字典并严格校验入口扩展名
-    const compiledEntries = new Map();
     for (const act of plan.actions) {
         if (!isOwnAction(act))
             continue;
-        const destEntry = compiledEntryFor(act);
-        if (!destEntry.endsWith(".js") && !destEntry.endsWith(".mjs")) {
-            throw new BuilderError(`Action '${act.id}' entry '${destEntry}' must point to compiled .js or .mjs`);
-        }
-        if (!existsSync(join(stagingPkgDir, destEntry))) {
-            throw new BuilderError(`Compiled action entry file not found: ${destEntry}`);
+        if (!existsSync(join(stagingPkgDir, act.entry))) {
+            throw new BuilderError(`Action entry file not found: ${act.entry}`);
         }
-        compiledEntries.set(act.id, destEntry);
     }
     // 严格生成与校验 actiondock.json（严禁包含废弃 actionsDir 或 playbooksDir 字段）
     const packedConfig = serializePlanManifest(plan, {
         includeSchema: true,
         configBeforeActions: true,
         includePlaybooks: false,
-        actionEntryOverride: (act) => compiledEntries.get(act.id),
     });
     if ("actionsDir" in packedConfig || "playbooksDir" in packedConfig) {
         throw new BuilderError("Packed manifest must not contain deprecated fields 'actionsDir' or 'playbooksDir'.");
@@ -304,68 +165,3 @@ function writeManifestAndPkgJson(stagingPkgDir, plan, sourcePkgJson) {
     const normalizedPkg = normalizePkgExportsAndEngines(sourcePkgJson);
     writeFileSync(join(stagingPkgDir, "package.json"), JSON.stringify(normalizedPkg, null, 2) + "\n", "utf-8");
 }
-/**
- * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
- * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
- * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
- */
-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");
-        generatedName = packLines.pop()?.trim() || 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/planner.js

@@ -1,11 +1,12 @@
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
-import { loadProjectConfig, } from "@actiondock/core";
+import { ActionDockError, ACTION_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, 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";
+import { computeLockfileInfo } from "./lockfile-resolver.js";
+import { extractExternalDependencies, isIgnoredPath } from "./dependency-resolver.js";
 /**
  * 递归扫描指定目录下的文件，返回绝对路径列表。
  * 目录遍历统一复用 core 的 traverseDirectory 单一事实源，
@@ -14,83 +15,6 @@ import { assertRelativeDependenciesIntegrity } from "./dependency-check.js";
 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",
-];
-/**
- * 忽略的文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。
- */
-function isIgnoredPath(relPath) {
-    const normalized = relPath.replace(/\\/g, "/");
-    return (normalized.startsWith("node_modules/") ||
-        normalized.includes("/node_modules/") ||
-        normalized.startsWith(".git/") ||
-        normalized.startsWith("dist/") ||
-        normalized.startsWith(".actiondock/") ||
-        TEST_FILE_SUFFIXES.some((suffix) => normalized.endsWith(suffix)));
-}
-/**
- * 支持的包管理器锁文件候选列表。
- */
-const KNOWN_LOCKFILES = [
-    "package-lock.json",
-    "npm-shrinkwrap.json",
-    "bun.lockb",
-    "bun.lock",
-    "pnpm-lock.yaml",
-    "yarn.lock",
-];
-/**
- * 读取并计算项目锁文件元数据及 SHA-256 摘要。
- */
-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;
-}
 /**
  * 构造备用清单映射，仅读取文件系统条目与配置声明，杜绝 AST 源码分析与动态代码执行。
  */
@@ -141,46 +65,6 @@ function generateFallbackManifest(projectRoot, actionsDir = "actions", config) {
         actions,
     };
 }
-/**
- * 收集项目根目录 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");
-        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,
-            });
-        }
-    }
-    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)。
  * 仅读取 actiondock.json、锁文件与显式构建参数，彻底移除 TypeScript AST 源码扫描。
@@ -314,54 +198,48 @@ export class SelectionPlanner {
             let entry = manifestActions[currentId] || config?.actions?.[currentId];
             let entryRoot = root;
             if (!entry) {
-                try {
-                    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: resolved.package.id,
-                                name: resolved.package.id,
-                                version: "0.1.0",
-                            };
-                        }
-                        const externalManifest = loadManifest(extRoot);
-                        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?.[resolved.ref.actionId];
-                        }
-                        if (externalEntry) {
-                            entry = externalEntry;
-                            entryRoot = extRoot;
-                            // 依赖包 actiondock.json 中声明的传递依赖闭包（入队前查重，避免重复膨胀）
-                            const extPkgUses = extConfig?.uses;
-                            if (Array.isArray(extPkgUses)) {
-                                for (const u of extPkgUses) {
-                                    const trimmedUse = typeof u === "string" ? u.trim() : "";
-                                    if (trimmedUse &&
-                                        !resolvedActionIds.has(trimmedUse) &&
-                                        !queued.has(trimmedUse)) {
-                                        queued.add(trimmedUse);
-                                        queue.push(trimmedUse);
-                                    }
-                                }
+                const resolved = resolveAction(currentId, { graph, catalog, caller: config?.id });
+                const resolvedPkgId = resolved.package.id;
+                const resolvedActionId = resolved.ref.actionId;
+                const extNode = graph.packages.get(resolvedPkgId);
+                if (extNode && existsSync(extNode.root)) {
+                    const extRoot = extNode.root;
+                    let extConfig;
+                    try {
+                        extConfig = loadProjectConfig(extRoot);
+                    }
+                    catch {
+                        extConfig = {
+                            id: resolvedPkgId,
+                            name: resolvedPkgId,
+                            version: "0.1.0",
+                        };
+                    }
+                    const externalManifest = loadManifest(extRoot);
+                    const externalEntry = externalManifest?.actions?.[resolvedActionId] ||
+                        extConfig?.actions?.[resolvedActionId];
+                    if (!externalEntry) {
+                        throw new ActionDockError(UNDECLARED_ACTION_DEPENDENCY, `UNDECLARED_ACTION_DEPENDENCY: Action '${resolvedActionId}' is not declared in package '${resolvedPkgId}' manifest`);
+                    }
+                    entry = externalEntry;
+                    entryRoot = extRoot;
+                    // 依赖包 actiondock.json 中声明的传递依赖闭包（入队前查重，避免重复膨胀）
+                    const extPkgUses = extConfig?.uses;
+                    if (Array.isArray(extPkgUses)) {
+                        for (const u of extPkgUses) {
+                            const trimmedUse = typeof u === "string" ? u.trim() : "";
+                            if (trimmedUse &&
+                                !resolvedActionIds.has(trimmedUse) &&
+                                !queued.has(trimmedUse)) {
+                                queued.add(trimmedUse);
+                                queue.push(trimmedUse);
                             }
                         }
                     }
                 }
-                catch {
-                    // 外部包解析失败时交由下方缺失依赖报错统一透传
-                }
             }
             if (!entry) {
-                throw new PlannerError(`Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`, "MISSING_DEPENDENCY");
+                throw new ActionDockError(ACTION_NOT_FOUND, `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`);
             }
             if (entryRoot !== root) {
                 externalActionRoots.set(currentId, entryRoot);

package/dist/skill/custom-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 复合技能自定义说明书（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[];
+}
+export declare const CUSTOM_SLOT_MARKER_PATTERN: RegExp;
+/**
+ * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。
+ * 首个标记之前的内容归入 `append` 槽位；未知槽位名直接抛错，避免拼写错误被静默吞掉。
+ */
+export declare function parseCustomSections(source: string): CompositeCustomSection[];
+/**
+ * 解析复合技能自定义说明书文件：支持 YAML frontmatter 中的 `description` 覆盖，
+ * 正文按槽位标记解析为自定义段落。
+ */
+export declare function parseCustomSkillDeclaration(source: string): CompositeCustomDeclaration;

package/dist/skill/custom-parser.js

@@ -0,0 +1,61 @@
+import { BuilderError } from "../errors.js";
+export const COMPOSITE_CUSTOM_SLOTS = [
+    "intro",
+    "after-init",
+    "after-describe",
+    "after-actions",
+    "after-playbooks",
+    "after-invoke",
+    "append",
+];
+/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
+export const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
+export const CUSTOM_SLOT_MARKER_PATTERN = /^\s*<!--\s*actiondock:slot\s+([a-zA-Z][a-zA-Z0-9-]*)\s*-->\s*$/;
+/**
+ * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。
+ * 首个标记之前的内容归入 `append` 槽位；未知槽位名直接抛错，避免拼写错误被静默吞掉。
+ */
+export function parseCustomSections(source) {
+    const sections = [];
+    let currentSlot = "append";
+    let buffer = [];
+    const flush = () => {
+        const content = buffer.join("\n").trim();
+        buffer = [];
+        if (content) {
+            sections.push({ slot: currentSlot, content });
+        }
+    };
+    for (const line of source.split(/\r?\n/)) {
+        const match = line.match(CUSTOM_SLOT_MARKER_PATTERN);
+        if (match) {
+            flush();
+            const slot = match[1];
+            if (!COMPOSITE_CUSTOM_SLOTS.includes(slot)) {
+                throw new BuilderError(`Unknown ActionDock custom slot '${match[1]}'. Valid slots: ${COMPOSITE_CUSTOM_SLOTS.join(", ")}`, "UNKNOWN_CUSTOM_SLOT");
+            }
+            currentSlot = slot;
+            continue;
+        }
+        buffer.push(line);
+    }
+    flush();
+    return sections;
+}
+/**
+ * 解析复合技能自定义说明书文件：支持 YAML frontmatter 中的 `description` 覆盖，
+ * 正文按槽位标记解析为自定义段落。
+ */
+export function parseCustomSkillDeclaration(source) {
+    let body = source;
+    let description;
+    const frontmatter = source.match(/^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
+    if (frontmatter) {
+        body = source.slice(frontmatter[0].length);
+        const descLine = frontmatter[1].match(/^description:[ \t]*(.+?)[ \t]*$/m);
+        if (descLine) {
+            description = descLine[1].replace(/^["']/g, "").replace(/["']$/g, "");
+        }
+    }
+    return { description, sections: parseCustomSections(body) };
+}

package/dist/skill/index.d.ts

@@ -1 +1,2 @@
 export * from "./templates.js";
+export * from "./custom-parser.js";

package/dist/skill/index.js

@@ -1 +1,2 @@
 export * from "./templates.js";
+export * from "./custom-parser.js";