@actiondock/builder 2.16.0 → 2.18.0

package/README.md

@@ -40,21 +40,28 @@ ActionDock 2.x 构建规划、目录交付与技能导出包。
 
 ### SkillExporter 与技能导出
 
-[SkillExporter](./src/exporter.ts) 与 `exportSkill` 导出函数将原子 Action 与操作规程 Playbook 打包导出为面向主流 AI 智能体生态的标准 Agent Skill 资产：
+[SkillExporter](./src/exporter.ts)、`exportSkill` 以及 `exportCompositeSkill` 导出函数将原子 Action 与操作规程 Playbook 打包导出为面向主流 AI 智能体生态的标准 Agent Skill 资产：
 
-- 生成 SKILL.md 指令：提取 Playbook 规程内容与工具元数据，合成符合智能体规范的操作指南文档与声明头部。
-- 源码模式技能导出：使用 `--mode source`（默认模式），保留 TypeScript 源码与依赖声明，适合具备 Node.js 运行环境的智能体容器直接运行。
+- 默认单包浅导出机制：默认采用单包源码浅闭包导出，仅复制当前包自身源码与规程，产物清单完整保留 `uses` 跨包逻辑契约，不物理拷贝外部包源码，单包结构纯粹透明，天然支持配合 `playbooks` 或 `actions` 执行规程驱动剪枝。
+- 显式外部依赖物化：支持 `bundleDeps` 选项。当显式开启且依赖闭包跨越外部已链接包时，自顶向下递归解析依赖链并将外部依赖包物理物化进产物根目录的 `packages/*` 子目录，展开为自包含的微型工作区产物结构；展开为复合形态时与过滤参数严格互斥（抛出 `FILTERS_UNSUPPORTED_FOR_COMPOSITE` 错误）。
+- 独立自包含 Node 目录型导出：支持 `standalone` 选项（等价于 `mode: "node"`），生成免全局 `ad` 命令行工具的自包含目录，内置独立运行脚本与说明书，配合 `vendorDeps` 可实现生产依赖完全内置。
 - 本地依赖完整性强校验：严格断言 Action 源码中的相对路径导入。若引用了未在 `actions` 且未在 `files` 字段中声明的本地模块，直接中断构建并抛出 `BuilderError`（错误码 `UNMET_LOCAL_DEPENDENCY`），彻底杜绝缺失依赖的产物分发。
-- 自包含 Node 目录技能导出：使用 `--mode node`，将自包含的 Node.js 交付目录与技能文档一体化打包，开箱即用。
-- 复合套件导出：支持 `--bundle` 选项将工作区内的多个包统一导出为复合工作区技能套件。
-- 压缩归档：支持 `--archive` 选项将导出的技能目录打包为 `.zip` 或 `.tar.gz` 格式。
+- 说明书定制与复合套件导出：支持单包与复合套件通过 `customMdPath` 注入插槽定制模板（或放置 `SKILL.custom.md` 自动发现）；支持 `exportCompositeSkill` 函数将工作区内的多个包统一导出为复合工作区技能套件；支持通过 `skillMdOnly` 实现就地仅原位刷新说明书。
+- 压缩归档：支持 `archive` 选项将导出的技能目录打包为 `.zip` 或 `.tar.gz` 格式。
 
 ---
 
 ## 编程调用示例
 
 ```ts
-import { buildProject, packProject, SelectionPlanner, SkillExporter, exportSkill } from "@actiondock/builder";
+import {
+  buildProject,
+  packProject,
+  SelectionPlanner,
+  SkillExporter,
+  exportSkill,
+  exportCompositeSkill,
+} from "@actiondock/builder";
 
 // 计算依赖规划闭包
 const planner = new SelectionPlanner({ projectRoot: "/path/to/project" });
@@ -73,20 +80,34 @@ const packResult = await packProject({
   outDir: "./dist/npm",
 });
 
-// 导出 Agent Skill 资产（顶层便捷入口，内部委托 SkillExporter 实例方法）
+// 默认源码单包浅导出（支持规程定向裁剪）
 const skillResult = await exportSkill({
   projectRoot: "/path/to/project",
-  outDir: "./dist/skills",
+  outDir: "./dist/skills/review-pr",
   playbooks: ["review-pr"],
-  mode: "source",
 });
 
-// 或直接实例化 SkillExporter 定制导出
-const exporter = new SkillExporter();
-const customResult = await exporter.export({
+// 显式物化外部依赖导出（展开为微型工作区）
+const bundledResult = await exportSkill({
   projectRoot: "/path/to/project",
-  outDir: "./dist/skills-custom",
-  mode: "source",
+  outDir: "./dist/skills/bundled",
+  bundleDeps: true,
+});
+
+// 独立自包含 Node.js 目录型导出（免全局 ad 命令行，物化生产依赖）
+const standaloneResult = await exportSkill({
+  projectRoot: "/path/to/project",
+  outDir: "./dist/skills/standalone",
+  standalone: true,
+  vendorDeps: true,
+});
+
+// 复合套件聚合导出与就地原位刷新说明书
+const compositeResult = await exportCompositeSkill({
+  bundleName: "vip-agent-tools",
+  projectRoots: ["/path/to/pkg-a", "/path/to/pkg-b"],
+  outDir: "./dist/composite-skill",
+  customMdPath: "/path/to/SKILL.custom.md",
 });
 ```
 

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/dependency-check.d.ts

@@ -1,4 +1,4 @@
-import type { SelectionPlan } from "./types.js";
+import { type SelectionPlan } from "./types.js";
 /**
  * 从源码中快速提取以相对路径（./ 或 ../）引入的静态或动态导入说明符。
  */

package/dist/dependency-check.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { isPathOutsideBoundary } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
+import { isOwnAction } from "./types.js";
 /**
  * 移除源码中的单行与多行注释，防止注释内的相对路径字符串误触发依赖解析。
  */
@@ -130,6 +131,8 @@ export function assertRelativeDependenciesIntegrity(projectRoot, plan) {
     // 收集已包含在构建规划中的全部文件物理绝对路径
     const collectedPaths = new Set();
     for (const act of plan.actions) {
+        if (!isOwnAction(act))
+            continue;
         if (act.resolvedPath) {
             collectedPaths.add(toRealPath(act.resolvedPath));
         }
@@ -142,6 +145,8 @@ export function assertRelativeDependenciesIntegrity(projectRoot, plan) {
     // 待校验文件队列（包括全部 Action 及其收集的 TS/JS 模块）
     const queue = [];
     for (const act of plan.actions) {
+        if (!isOwnAction(act))
+            continue;
         if (act.resolvedPath && existsSync(act.resolvedPath)) {
             queue.push({ file: toRealPath(act.resolvedPath), actionId: act.id });
         }

package/dist/export-composite.js

@@ -20,6 +20,9 @@ export async function exportCompositeImpl(options, exportSubpackage) {
     if (!options.bundleName || !options.bundleName.trim()) {
         throw new BuilderError("bundleName is required for composite skill export.");
     }
+    if (options.standalone) {
+        throw new BuilderError("Composite Skill export currently only supports source mode. Standalone mode is not supported for composite bundles.", "UNSUPPORTED_BUILD_MODE");
+    }
     const skillMdOnly = options.skillMdOnly === true;
     const customDeclaration = resolveCustomSkillDeclaration(options);
     const bundleSlug = getPackageSlug(options.bundleName);
@@ -41,11 +44,11 @@ export async function exportCompositeImpl(options, exportSubpackage) {
     const packageSummaries = [];
     let existingSkillPath;
     try {
-        // 收集并展开所有包含在依赖闭包中的外部项目根目录，确保 bundle 整包携带齐全部依赖
+        // 收集项目根目录；仅在显式指定 bundleDeps 时展开依赖闭包中的外部项目根目录
         const effectiveRoots = new Set();
         for (const r of options.projectRoots) {
             effectiveRoots.add(resolve(r));
-            if (!skillMdOnly) {
+            if (!skillMdOnly && options.bundleDeps === true) {
                 try {
                     const p = SelectionPlanner.plan({ projectRoot: r });
                     if (p.externalProjectRoots) {
@@ -111,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.d.ts

@@ -1,5 +1,5 @@
 import { renderRuntimeReferenceContent } from "./skill/templates.js";
-import type { SelectionPlan, SkillExporterOptions } from "./types.js";
+import { type SelectionPlan, type SkillExporterOptions } from "./types.js";
 /**
  * 源码型 Skill 导出装配层。
  *

package/dist/export-source.js

@@ -7,7 +7,8 @@ import { BuilderError } from "./errors.js";
 import { getInternalDependencyVersion } from "./fs-utils.js";
 import { assertValidManifestActionIds, sanitizeExportDependencies, serializePlanManifest, } from "./manifest.js";
 import { copyPlanEntries } from "./stage-sources.js";
-import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
+import { isOwnAction } from "./types.js";
+import { buildConfigForTemplates, resolveCustomSkillDeclaration, writeSkillMd, } from "./skill-md.js";
 /**
  * 源码型 Skill 导出装配层。
  *
@@ -20,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, 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,8 +24,11 @@ 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.mode === "node" ? "node" : "source";
+        const mode = options.standalone === true || options.mode === "node" ? "node" : "source";
         // 调用 SelectionPlanner 执行声明式构建规划
         const plan = SelectionPlanner.plan({
             projectRoot: root,
@@ -40,12 +43,12 @@ export class SkillExporter {
         const defaultSkillDir = join(root, "dist", defaultFolderName);
         const targetSkillDir = resolve(options.outDir || defaultSkillDir);
         const hasExternalDeps = Boolean(plan.externalProjectRoots && plan.externalProjectRoots.length > 0);
-        // 单包源码导出若依赖闭包含外部包，导成 mini-workspace 形态（packages/ 下带齐依赖包），和 bundle 统一成一个交付形状
+        // 单包源码导出若开启 bundleDeps 且依赖闭包含外部包，导成 mini-workspace 形态（packages/ 下带齐依赖包），和 bundle 统一成一个交付形状
         // 该复合分支会展开全部依赖包，无法保留调用方传入的 actions/playbooks 过滤选项；
         // 静默丢弃过滤会导致产物全量导出，必须显式拒绝并给出调整指引（CLI 侧已有 roots>1 守卫，此处补齐 composite 分支守卫）
         const hasFilters = Boolean((options.actions && options.actions.length > 0) ||
             (options.playbooks && options.playbooks.length > 0));
-        const willUseComposite = mode === "source" && !options._isSubpackage && hasExternalDeps;
+        const willUseComposite = mode === "source" && !options._isSubpackage && hasExternalDeps && options.bundleDeps === true;
         if (hasFilters && willUseComposite) {
             throw new BuilderError("Filtering options (--actions, --playbook) cannot be combined with a source export whose dependency closure spans external linked packages (composite mini-workspace output). Remove the filtering options to export the full closure, or adjust the 'uses' declarations so the closure stays within a single package.", "FILTERS_UNSUPPORTED_FOR_COMPOSITE");
         }
@@ -60,6 +63,7 @@ export class SkillExporter {
                 workspaceRoot: options.workspaceRoot,
                 skillMdPath: options.skillMdPath,
                 customMdPath: options.customMdPath,
+                bundleDeps: options.bundleDeps,
             });
             return {
                 packageId: plan.packageId,
@@ -121,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

@@ -308,6 +308,10 @@ export interface SkillExporterOptions {
     projectRoot: string;
     /** 导出模式：source 源码型 Skill 或 node 目录型 Skill（默认 source） */
     mode?: "source" | "node";
+    /** 独立自包含模式（若为 true 则将导出模式设为 node 目录型） */
+    standalone?: boolean;
+    /** 是否将跨包依赖物理物化为微型工作区复合结构（默认 false） */
+    bundleDeps?: boolean;
     /** 导出产物目标目录（默认输出至 dist 目录） */
     outDir?: string;
     /** 是否执行归档压缩，亦可直接指定归档格式 */
@@ -336,7 +340,7 @@ export interface SkillExporterOptions {
     skipDependencyValidation?: boolean;
     /** 内部标识：是否作为复合套件子包导出（避免闭包再次触发嵌套 mini-workspace） */
     _isSubpackage?: boolean;
-    /** 自定义复合技能说明书文件路径 */
+    /** 自定义技能说明书（SKILL.custom.md）文件路径；缺省时自动在项目或工作区根目录下发现同名文件 */
     customMdPath?: string;
     /** 所属 Workspace 根目录（可选） */
     workspaceRoot?: string;
@@ -386,6 +390,10 @@ export interface CompositeSkillExportOptions {
     projectRoots: string[];
     /** 复合套件输出目标目录（默认输出至 dist 目录） */
     outDir?: string;
+    /** 是否将外部依赖物理物化进复合产物（默认 false） */
+    bundleDeps?: boolean;
+    /** 独立自包含模式（复合导出暂不支持） */
+    standalone?: boolean;
     /** 复合技能描述信息 */
     description?: string;
     /** 是否执行归档压缩，亦可直接指定归档格式 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.16.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.16.0",
-    "@actiondock/sdk": "^2.16.0"
+    "@actiondock/core": "^2.18.0",
+    "@actiondock/sdk": "^2.18.0"
   },
   "keywords": [
     "actiondock",