@actiondock/builder 2.17.0 → 2.18.0

package/README.md

@@ -46,8 +46,7 @@ ActionDock 2.x 构建规划、目录交付与技能导出包。
 - 显式外部依赖物化：支持 `bundleDeps` 选项。当显式开启且依赖闭包跨越外部已链接包时，自顶向下递归解析依赖链并将外部依赖包物理物化进产物根目录的 `packages/*` 子目录，展开为自包含的微型工作区产物结构；展开为复合形态时与过滤参数严格互斥（抛出 `FILTERS_UNSUPPORTED_FOR_COMPOSITE` 错误）。
 - 独立自包含 Node 目录型导出：支持 `standalone` 选项（等价于 `mode: "node"`），生成免全局 `ad` 命令行工具的自包含目录，内置独立运行脚本与说明书，配合 `vendorDeps` 可实现生产依赖完全内置。
 - 本地依赖完整性强校验：严格断言 Action 源码中的相对路径导入。若引用了未在 `actions` 且未在 `files` 字段中声明的本地模块，直接中断构建并抛出 `BuilderError`（错误码 `UNMET_LOCAL_DEPENDENCY`），彻底杜绝缺失依赖的产物分发。
-- 生成 SKILL.md 指令：提取 Playbook 规程内容与工具元数据，合成符合智能体规范的操作指南文档与声明头部。
-- 复合套件导出与说明书定制：支持 `exportCompositeSkill` 函数将工作区内的多个包统一导出为复合工作区技能套件；支持通过 `customMdPath` 注入插槽定制模板，通过 `skillMdOnly` 实现就地仅原位刷新说明书。
+- 说明书定制与复合套件导出：支持单包与复合套件通过 `customMdPath` 注入插槽定制模板（或放置 `SKILL.custom.md` 自动发现）；支持 `exportCompositeSkill` 函数将工作区内的多个包统一导出为复合工作区技能套件；支持通过 `skillMdOnly` 实现就地仅原位刷新说明书。
 - 压缩归档：支持 `archive` 选项将导出的技能目录打包为 `.zip` 或 `.tar.gz` 格式。
 
 ---

package/dist/build.js

@@ -12,7 +12,7 @@ import { generateNodeHostEntrySource, generateNodeSupervisorEntrySource } from "
 import { vendorDependencies } from "./vendor.js";
 import { generateStandaloneSkillMd } from "./skill/templates.js";
 import { writeRuntimeReferenceFile } from "./export-source.js";
-import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
+import { buildConfigForTemplates, resolveCustomSkillDeclaration, writeSkillMd, } from "./skill-md.js";
 import { createArchive, resolveArchiveFormat } from "./export-archive.js";
 export { copyPlanEntries } from "./stage-sources.js";
 /**
@@ -310,9 +310,22 @@ export async function exportNodeSkill(root, targetSkillDir, plan, options, pkgSl
         allowInstallScripts: options.allowInstallScripts,
         requireReproducible: options.requireReproducible,
     });
-    const usedExistingSkillMd = writeSkillMd(root, targetSkillDir, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => {
+    const customDeclaration = resolveCustomSkillDeclaration({
+        projectRoot: root,
+        customMdPath: options.customMdPath,
+        workspaceRoot: options.workspaceRoot,
+    });
+    const usedExistingSkillMd = writeSkillMd(root, targetSkillDir, {
+        skipSkillMd: options.skipSkillMd,
+        skillMdPath: options.skillMdPath,
+        pkgSlug,
+        hasCustomDeclaration: Boolean(customDeclaration),
+    }, () => {
         const configForTemplates = buildConfigForTemplates(plan, plan.actionsDir || "actions", plan.playbooksDir || "playbooks");
-        return generateStandaloneSkillMd(configForTemplates, plan.actions, plan.playbooks, "node ./entry.mjs");
+        return generateStandaloneSkillMd(configForTemplates, plan.actions, plan.playbooks, "node ./entry.mjs", {
+            customSections: customDeclaration?.sections,
+            description: customDeclaration?.description,
+        });
     });
     // 仅在使用自动模板时生成默认运行参考文件；Node 目录型使用自身入口，不要求全局安装 ad
     if (usedExistingSkillMd === undefined && !options.skipSkillMd) {

package/dist/export-composite.js

@@ -114,7 +114,9 @@ export async function exportCompositeImpl(options, exportSubpackage) {
                 playbooks: playbookIds,
             });
         }
-        existingSkillPath = skillMdOnly ? undefined : findExistingCompositeSkillMd(options);
+        const shouldCheckExisting = !skillMdOnly &&
+            (Boolean(options.skillMdPath) || !customDeclaration);
+        existingSkillPath = shouldCheckExisting ? findExistingCompositeSkillMd(options) : undefined;
         const description = options.description ||
             customDeclaration?.description ||
             `ActionDock 复合技能套件，聚合 ${packageInfos.map((p) => p.config.name).join("、")}`;

package/dist/export-source.js

@@ -8,7 +8,7 @@ import { getInternalDependencyVersion } from "./fs-utils.js";
 import { assertValidManifestActionIds, sanitizeExportDependencies, serializePlanManifest, } from "./manifest.js";
 import { copyPlanEntries } from "./stage-sources.js";
 import { isOwnAction } from "./types.js";
-import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
+import { buildConfigForTemplates, resolveCustomSkillDeclaration, writeSkillMd, } from "./skill-md.js";
 /**
  * 源码型 Skill 导出装配层。
  *
@@ -21,8 +21,21 @@ import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
 export function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
     const actionsDir = plan.actionsDir || "actions";
     const playbooksDir = plan.playbooksDir || "playbooks";
+    const customDeclaration = resolveCustomSkillDeclaration({
+        projectRoot: root,
+        customMdPath: options.customMdPath,
+        workspaceRoot: options.workspaceRoot,
+    });
     const configForTemplates = buildConfigForTemplates(plan, actionsDir, playbooksDir);
-    const usedExistingSkillMd = writeSkillMd(root, skillDir, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => generateSourceSkillMd(configForTemplates, plan.actions.filter((a) => isOwnAction(a)), plan.playbooks));
+    const usedExistingSkillMd = writeSkillMd(root, skillDir, {
+        skipSkillMd: options.skipSkillMd,
+        skillMdPath: options.skillMdPath,
+        pkgSlug,
+        hasCustomDeclaration: Boolean(customDeclaration),
+    }, () => generateSourceSkillMd(configForTemplates, plan.actions.filter((a) => isOwnAction(a)), plan.playbooks, {
+        customSections: customDeclaration?.sections,
+        description: customDeclaration?.description,
+    }));
     // 导出精简后的 actiondock.json 项目配置（项目元数据与清单的单一事实源）
     const exportedConfig = serializePlanManifest(plan, {
         omitEmptyConfig: true,

package/dist/exporter.js

@@ -24,6 +24,9 @@ export class SkillExporter {
      * @returns 导出产物详细描述
      */
     async export(options) {
+        if (options.skillMdPath && options.customMdPath) {
+            throw new BuilderError("Options 'skillMdPath' and 'customMdPath' cannot be used together. Specify 'skillMdPath' to reuse an existing static document, or 'customMdPath' to customize template generation with custom slots.", "INVALID_EXPORT_OPTIONS");
+        }
         const root = resolve(options.projectRoot);
         const mode = options.standalone === true || options.mode === "node" ? "node" : "source";
         // 调用 SelectionPlanner 执行声明式构建规划
@@ -122,6 +125,9 @@ export class SkillExporter {
      * 复合模式导出：将多个包聚合为一个统一的复合技能目录。
      */
     async exportComposite(options) {
+        if (options.skillMdPath && options.customMdPath) {
+            throw new BuilderError("Options 'skillMdPath' and 'customMdPath' cannot be used together. Specify 'skillMdPath' to reuse an existing static document, or 'customMdPath' to customize template generation with custom slots.", "INVALID_EXPORT_OPTIONS");
+        }
         return exportCompositeImpl(options, (opts) => this.export(opts));
     }
 }

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export { packProject } from "./pack.js";
 export { exportCompositeSkill, exportSkill, SkillExporter, } from "./exporter.js";
 export { allocatePackageDirName } from "./manifest.js";
 export { SelectionPlanner } from "./planner.js";
+export { COMPOSITE_CUSTOM_DECLARATION_FILE, COMPOSITE_CUSTOM_SLOTS, SKILL_CUSTOM_DECLARATION_FILE, SKILL_CUSTOM_SLOTS, parseCustomSections, parseCustomSkillDeclaration, } from "./skill/index.js";
+export type { CompositeCustomDeclaration, CompositeCustomSection, CompositeCustomSlot, SkillCustomDeclaration, SkillCustomSection, SkillCustomSlot, } from "./skill/index.js";
 export type { ArchiveFormat, BuildOptions, BuildPlan, BuildProjectWithPlanOptions, BuildResult, CompositeSkillExportOptions, CompositeSkillExportResult, ExportSkillOptions, ExportSkillResult, PackOptions, PackResult, SelectionPlan, SelectionPlannerOptions, SkillExporterOptions, SkillExportResult, } from "./types.js";

package/dist/index.js

@@ -11,3 +11,5 @@ export { exportCompositeSkill, exportSkill, SkillExporter, } from "./exporter.js
 export { allocatePackageDirName } from "./manifest.js";
 // 构建规划器
 export { SelectionPlanner } from "./planner.js";
+// 技能说明书自定义契约与解析
+export { COMPOSITE_CUSTOM_DECLARATION_FILE, COMPOSITE_CUSTOM_SLOTS, SKILL_CUSTOM_DECLARATION_FILE, SKILL_CUSTOM_SLOTS, parseCustomSections, parseCustomSkillDeclaration, } from "./skill/index.js";

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

@@ -1,20 +1,26 @@
 /**
- * 复合技能自定义说明书（SKILL.custom.md）的槽位，
+ * 自定义技能说明书（SKILL.custom.md）的槽位，
  * 决定自定义段落插入到官方模板生成结果中的位置。
+ * 单包导出与复合套件导出共用同一套槽位体系。
  */
 export type CompositeCustomSlot = "intro" | "after-init" | "after-describe" | "after-actions" | "after-playbooks" | "after-invoke" | "append";
+export type SkillCustomSlot = CompositeCustomSlot;
 export declare const COMPOSITE_CUSTOM_SLOTS: readonly CompositeCustomSlot[];
-/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
+export declare const SKILL_CUSTOM_SLOTS: readonly CompositeCustomSlot[];
+/** 约定俗成的自定义技能说明书文件名（单包与复合套件通用）。 */
 export declare const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
+export declare const SKILL_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
 export interface CompositeCustomSection {
     slot: CompositeCustomSlot;
     content: string;
 }
+export type SkillCustomSection = CompositeCustomSection;
 export interface CompositeCustomDeclaration {
     /** 自定义说明书 frontmatter 中声明的 description 覆盖值 */
     description?: string;
     sections: CompositeCustomSection[];
 }
+export type SkillCustomDeclaration = CompositeCustomDeclaration;
 export declare const CUSTOM_SLOT_MARKER_PATTERN: RegExp;
 /**
  * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。

package/dist/skill/custom-parser.js

@@ -8,8 +8,10 @@ export const COMPOSITE_CUSTOM_SLOTS = [
     "after-invoke",
     "append",
 ];
-/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
+export const SKILL_CUSTOM_SLOTS = COMPOSITE_CUSTOM_SLOTS;
+/** 约定俗成的自定义技能说明书文件名（单包与复合套件通用）。 */
 export const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
+export const SKILL_CUSTOM_DECLARATION_FILE = COMPOSITE_CUSTOM_DECLARATION_FILE;
 export const CUSTOM_SLOT_MARKER_PATTERN = /^\s*<!--\s*actiondock:slot\s+([a-zA-Z][a-zA-Z0-9-]*)\s*-->\s*$/;
 /**
  * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。

package/dist/skill/templates.d.ts

@@ -33,8 +33,14 @@ export declare function renderRuntimeReferenceContent(options: {
 }): string;
 /** 运行时参考文件的导出目录内相对路径（单一事实源） */
 export declare const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
-export declare function generateSourceSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[]): string;
-export declare function generateStandaloneSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[], binaryRelPath?: string): string;
+export declare function generateSourceSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[], options?: {
+    customSections?: CompositeCustomSection[];
+    description?: string;
+}): string;
+export declare function generateStandaloneSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[], binaryRelPath?: string, options?: {
+    customSections?: CompositeCustomSection[];
+    description?: string;
+}): string;
 export interface CompositeSkillPackageInfo {
     config: ProjectConfig;
     actions: Array<{

package/dist/skill/templates.js

@@ -1,7 +1,7 @@
 import { basename } from "node:path";
-function getCleanSkillMetadata(config) {
+function getCleanSkillMetadata(config, descriptionOverride) {
     const cleanName = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
-    const desc = config.description || `AI Agent skill for ${config.name} (${config.id})`;
+    const desc = descriptionOverride || config.description || `AI Agent skill for ${config.name} (${config.id})`;
     return { cleanName, desc };
 }
 /**
@@ -202,52 +202,53 @@ function renderTroubleshootingSection(referenceRelPath) {
 }
 /** 运行时参考文件的导出目录内相对路径（单一事实源） */
 export const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
-export function generateSourceSkillMd(config, actions, playbooks) {
-    const { cleanName, desc } = getCleanSkillMetadata(config);
+export function generateSourceSkillMd(config, actions, playbooks, options) {
+    const { cleanName, desc } = getCleanSkillMetadata(config, options?.description);
     const pkgId = config.id;
     const firstAction = actions[0]?.id || "sample.greet";
     const playbookSection = renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks");
     const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
-    return `---
+    const sIntro = `---
 name: ${cleanName}
 description: ${desc}
 ---
 
 # ${config.name} (${config.id})
 
-${desc}
-
-## ActionDock 运行时
+${desc}`;
+    const sInit = `## ActionDock 运行时
 
-本技能为 **ActionDock 源码型技能包**。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
+本技能为 ActionDock 源码型技能包。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
-### 注册与链接（全局调用）
+### 安装依赖与注册链接
 
-本技能面向全局挂载使用：在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
+本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为先安装生产依赖，再执行注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
 
 \`\`\`bash
+# 安装生产依赖
+cd "<skill_root>" && npm install --omit=dev
+
+# 注册并链接到 ActionDock
 ad link "<skill_root>"
 \`\`\`
 
-> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。若初次运行提示依赖缺失，可在 \`<skill_root>\` 目录下执行 \`npm install --omit=dev\` 安装生产依赖。
-
-### 动作参数契约按需调阅
+> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。若后续依赖发生变更，可重新执行上述安装依赖与链接命令更新环境。`;
+    const sDescribe = `### 动作参数契约按需调阅
 
 在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
 
 \`\`\`bash
 ad describe ${pkgId}/${firstAction}
-\`\`\`
-
-### 执行 Action
+\`\`\``;
+    const sInvoke = `### 执行 Action
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
 
 ${renderInvocationGuidance(`ad describe ${pkgId}/${firstAction}`, `ad run ${pkgId}/${firstAction}`)}
 
-${renderJsonEnvelopeSection("envelope")}
-${playbookSection}
----
+${renderJsonEnvelopeSection("envelope")}`;
+    const sPlaybooks = playbookSection.trim();
+    const sActions = `---
 
 ## Action 目录
 
@@ -267,41 +268,54 @@ ad config set KEY VALUE --package ${pkgId}
 # 查看与检索状态数据
 ad state list --package ${pkgId}
 ad state get KEY --package ${pkgId}
-\`\`\`
-
-${renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH)}
-`;
+\`\`\``;
+    const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);
+    const parts = [
+        { slot: "intro", text: sIntro },
+        { slot: "after-init", text: sInit },
+        { slot: "after-describe", text: sDescribe },
+        { slot: "after-invoke", text: sInvoke },
+        { slot: "after-playbooks", text: sPlaybooks },
+        { slot: "after-actions", text: sActions },
+        { slot: "append", text: sTroubleshooting },
+    ];
+    const customSections = options?.customSections ?? [];
+    for (const section of [...customSections].reverse()) {
+        const anchorIndex = parts.findIndex((p) => p.slot === section.slot);
+        parts.splice(anchorIndex + 1, 0, { slot: section.slot, text: section.content });
+    }
+    return (parts
+        .filter((p) => p.text.trim().length > 0)
+        .map((p) => p.text.trim())
+        .join("\n\n") + "\n");
 }
-export function generateStandaloneSkillMd(config, actions, playbooks, binaryRelPath = "./bin/action-bin") {
-    const { cleanName, desc } = getCleanSkillMetadata(config);
+export function generateStandaloneSkillMd(config, actions, playbooks, binaryRelPath = "./bin/action-bin", options) {
+    const { cleanName, desc } = getCleanSkillMetadata(config, options?.description);
     const firstAction = actions[0]?.id || "sample.greet";
     const playbookSection = renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks");
     const actionListMd = renderActionListMarkdown(actions);
-    return `---
+    const sIntro = `---
 name: ${cleanName}
 description: ${desc}
 ---
 
 # ${config.name} (${config.id})
 
-${desc}
-
-
-### 动作参数契约按需调阅
+${desc}`;
+    const sDescribe = `### 动作参数契约按需调阅
 
 在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
 
 \`\`\`bash
 ${binaryRelPath} describe ${firstAction}
-\`\`\`
-
-### 执行 Action
+\`\`\``;
+    const sInvoke = `### 执行 Action
 
 ${renderInvocationGuidance(`${binaryRelPath} describe ${firstAction}`, `${binaryRelPath} run ${firstAction}`)}
 
-${renderJsonEnvelopeSection("result")}
-${playbookSection}
----
+${renderJsonEnvelopeSection("result")}`;
+    const sPlaybooks = playbookSection.trim();
+    const sActions = `---
 
 ## Action 目录
 
@@ -321,9 +335,8 @@ ${binaryRelPath} config set KEY VALUE
 # 查看与检索状态数据
 ${binaryRelPath} state list
 ${binaryRelPath} state get KEY
-\`\`\`
-
----
+\`\`\``;
+    const sTroubleshooting = `---
 
 ## 故障排查与依赖自愈指引（按需查阅）
 
@@ -334,8 +347,25 @@ ${binaryRelPath} state get KEY
 npm install --omit=dev
 \`\`\`
 
-完整环境安装与自愈指引按需查阅：[${RUNTIME_REFERENCE_REL_PATH}](${RUNTIME_REFERENCE_REL_PATH})
-`;
+完整环境安装与自愈指引按需查阅：[${RUNTIME_REFERENCE_REL_PATH}](${RUNTIME_REFERENCE_REL_PATH})`;
+    const parts = [
+        { slot: "intro", text: sIntro },
+        { slot: "after-init", text: "" },
+        { slot: "after-describe", text: sDescribe },
+        { slot: "after-invoke", text: sInvoke },
+        { slot: "after-playbooks", text: sPlaybooks },
+        { slot: "after-actions", text: sActions },
+        { slot: "append", text: sTroubleshooting },
+    ];
+    const customSections = options?.customSections ?? [];
+    for (const section of [...customSections].reverse()) {
+        const anchorIndex = parts.findIndex((p) => p.slot === section.slot);
+        parts.splice(anchorIndex + 1, 0, { slot: section.slot, text: section.content });
+    }
+    return (parts
+        .filter((p) => p.text.trim().length > 0)
+        .map((p) => p.text.trim())
+        .join("\n\n") + "\n");
 }
 /**
  * 生成多包聚合的复合模式 SKILL.md 文档。
@@ -375,6 +405,23 @@ description: ${description}
 # ${bundleName} 复合技能套件
 
 ${description}`;
+    const sInit = `## ActionDock 运行时
+
+本技能为 ActionDock 复合技能套件，聚合了多个功能包。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
+
+### 安装依赖与注册链接
+
+本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为先安装复合套件聚合生产依赖，再执行注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
+
+\`\`\`bash
+# 安装复合套件聚合依赖
+cd "<skill_root>" && npm install --omit=dev
+
+# 注册并链接工作区子包到 ActionDock
+ad link "<skill_root>"
+\`\`\`
+
+> \`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。\`ad link\` 天然具备幂等性，可安全重复调用。若后续依赖发生变更，可重新执行上述安装依赖与链接命令更新环境。`;
     const sDescribe = `## 动作参数契约按需调阅
 
 为节省上下文开销，各 Action 的详细参数结构不静态内嵌在说明书中。在调用未知参数的 Action 前，可在终端执行命令查阅输入输出约束：
@@ -404,12 +451,12 @@ ${renderJsonEnvelopeSection("envelope", { withDescriptions: false })}`;
     const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);
     const parts = [
         { slot: "intro", text: sIntro },
+        { slot: "after-init", text: sInit },
         { slot: "after-describe", text: sDescribe },
         { slot: "after-actions", text: sActions },
         { slot: "after-playbooks", text: sPlaybooks },
         { slot: "after-invoke", text: sInvoke },
-        { slot: "after-init", text: sTroubleshooting },
-        { slot: "append", text: "" },
+        { slot: "append", text: sTroubleshooting },
     ];
     // 自定义段落按文件顺序插入到对应槽位（倒序插入保证同槽位多段保持先后）
     const customSections = options?.customSections ?? [];

package/dist/skill-md.d.ts

@@ -16,10 +16,15 @@ export declare function findExistingSingleSkillMd(projectRoot: string, explicitP
  */
 export declare function findExistingCompositeSkillMd(options: CompositeSkillExportOptions): string | undefined;
 /**
- * 解析复合技能自定义说明书：显式 customMdPath 优先（缺失即报错），
- * 否则按 `SKILL.custom.md` 约定名在工作区根目录与当前目录自动发现。
+ * 解析技能自定义说明书：显式 customMdPath 优先（缺失即报错），
+ * 否则单包导出按项目根目录，复合导出按工作区根目录与当前目录自动发现 `SKILL.custom.md`。
  */
-export declare function resolveCustomSkillDeclaration(options: CompositeSkillExportOptions): (CompositeCustomDeclaration & {
+export declare function resolveCustomSkillDeclaration(options: {
+    projectRoot?: string;
+    customMdPath?: string;
+    workspaceRoot?: string;
+    projectRoots?: string[];
+}): (CompositeCustomDeclaration & {
     file: string;
 }) | undefined;
 /**
@@ -30,6 +35,7 @@ export declare function writeSkillMd(root: string, destDir: string, options: {
     skipSkillMd?: boolean;
     skillMdPath?: string;
     pkgSlug: string;
+    hasCustomDeclaration?: boolean;
 }, generate: () => string): string | undefined;
 /**
  * 构造模板生成所需的 ProjectConfig 视图。

package/dist/skill-md.js

@@ -13,7 +13,10 @@ import { BuilderError } from "./errors.js";
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
 export function findExistingSingleSkillMd(projectRoot, explicitPath, pkgSlug) {
-    if (explicitPath && existsSync(explicitPath)) {
+    if (explicitPath) {
+        if (!existsSync(explicitPath)) {
+            throw new BuilderError(`Skill document file not found: '${explicitPath}'`);
+        }
         try {
             if (statSync(explicitPath).isFile())
                 return resolve(explicitPath);
@@ -21,6 +24,7 @@ export function findExistingSingleSkillMd(projectRoot, explicitPath, pkgSlug) {
         catch {
             // 忽略文件属性读取异常
         }
+        throw new BuilderError(`Skill document path is not a regular file: '${explicitPath}'`);
     }
     const candidates = [
         join(projectRoot, "SKILL.md"),
@@ -48,7 +52,10 @@ export function findExistingSingleSkillMd(projectRoot, explicitPath, pkgSlug) {
  * 检索复合套件工作区中已存在的 SKILL.md 文件。
  */
 export function findExistingCompositeSkillMd(options) {
-    if (options.skillMdPath && existsSync(options.skillMdPath)) {
+    if (options.skillMdPath) {
+        if (!existsSync(options.skillMdPath)) {
+            throw new BuilderError(`Skill document file not found: '${options.skillMdPath}'`);
+        }
         try {
             if (statSync(options.skillMdPath).isFile())
                 return resolve(options.skillMdPath);
@@ -56,6 +63,7 @@ export function findExistingCompositeSkillMd(options) {
         catch {
             // 忽略文件属性读取异常
         }
+        throw new BuilderError(`Skill document path is not a regular file: '${options.skillMdPath}'`);
     }
     const bundleSlug = getPackageSlug(options.bundleName);
     const searchDirs = new Set();
@@ -95,8 +103,8 @@ export function findExistingCompositeSkillMd(options) {
     return undefined;
 }
 /**
- * 解析复合技能自定义说明书：显式 customMdPath 优先（缺失即报错），
- * 否则按 `SKILL.custom.md` 约定名在工作区根目录与当前目录自动发现。
+ * 解析技能自定义说明书：显式 customMdPath 优先（缺失即报错），
+ * 否则单包导出按项目根目录，复合导出按工作区根目录与当前目录自动发现 `SKILL.custom.md`。
  */
 export function resolveCustomSkillDeclaration(options) {
     let filePath;
@@ -106,14 +114,52 @@ export function resolveCustomSkillDeclaration(options) {
         }
         filePath = resolve(options.customMdPath);
     }
+    else if (options.projectRoot) {
+        const root = resolve(options.projectRoot);
+        const candidates = [
+            join(root, COMPOSITE_CUSTOM_DECLARATION_FILE),
+            join(root, "skill.custom.md"),
+            join(root, "skills", COMPOSITE_CUSTOM_DECLARATION_FILE),
+            join(root, "skills", "skill.custom.md"),
+        ];
+        for (const candidate of candidates) {
+            if (existsSync(candidate)) {
+                try {
+                    if (statSync(candidate).isFile()) {
+                        filePath = candidate;
+                        break;
+                    }
+                }
+                catch {
+                    // 忽略文件属性读取异常
+                }
+            }
+        }
+    }
     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;
+            const candidates = [
+                join(resolve(dir), COMPOSITE_CUSTOM_DECLARATION_FILE),
+                join(resolve(dir), "skill.custom.md"),
+                join(resolve(dir), "skills", COMPOSITE_CUSTOM_DECLARATION_FILE),
+                join(resolve(dir), "skills", "skill.custom.md"),
+            ];
+            for (const candidate of candidates) {
+                if (existsSync(candidate)) {
+                    try {
+                        if (statSync(candidate).isFile()) {
+                            filePath = candidate;
+                            break;
+                        }
+                    }
+                    catch {
+                        // 忽略文件属性读取异常
+                    }
+                }
             }
+            if (filePath)
+                break;
         }
     }
     if (!filePath) {
@@ -129,9 +175,11 @@ export function resolveCustomSkillDeclaration(options) {
  * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
  */
 export function writeSkillMd(root, destDir, options, generate) {
-    const existingSkill = options.skipSkillMd
-        ? undefined
-        : findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug);
+    const shouldCheckExisting = !options.skipSkillMd &&
+        (Boolean(options.skillMdPath) || !options.hasCustomDeclaration);
+    const existingSkill = shouldCheckExisting
+        ? findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug)
+        : undefined;
     if (existingSkill) {
         const destSkillMd = join(destDir, "SKILL.md");
         if (resolve(existingSkill) !== resolve(destSkillMd)) {

package/dist/types.d.ts

@@ -340,7 +340,7 @@ export interface SkillExporterOptions {
     skipDependencyValidation?: boolean;
     /** 内部标识：是否作为复合套件子包导出（避免闭包再次触发嵌套 mini-workspace） */
     _isSubpackage?: boolean;
-    /** 自定义复合技能说明书文件路径 */
+    /** 自定义技能说明书（SKILL.custom.md）文件路径；缺省时自动在项目或工作区根目录下发现同名文件 */
     customMdPath?: string;
     /** 所属 Workspace 根目录（可选） */
     workspaceRoot?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "ActionDock Build Planner, distribution packaging, and Skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.17.0",
-    "@actiondock/sdk": "^2.17.0"
+    "@actiondock/core": "^2.18.0",
+    "@actiondock/sdk": "^2.18.0"
   },
   "keywords": [
     "actiondock",