@actiondock/builder 2.9.1 → 2.11.0

package/dist/skill/templates.d.ts

@@ -1,5 +1,6 @@
 import type { ActionSpec, ProjectConfig } from "@actiondock/core";
 import type { PlaybookDefinition } from "@actiondock/core/project";
+import type { CompositeCustomSection } from "./custom-parser.js";
 export type SkillActionItem = ActionSpec | {
     id: string;
     description?: string;
@@ -7,8 +8,33 @@ export type SkillActionItem = ActionSpec | {
     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 type SkillPlaybookItem = PlaybookDefinition | {
+    id: string;
+    filePath: string;
+    name?: string;
+    description?: string;
+    actions?: string[];
+};
+/**
+ * 渲染完整「运行时环境参考」正文：写入导出目录 references/actiondock-runtime.md，
+ * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
+ */
+export declare function renderRuntimeReferenceContent(options: {
+    /** 依赖安装步骤标题：source 为安装技能源码依赖，composite 为安装复合技能聚合依赖 */
+    dependencyStepLabel: string;
+    /** 重新链接步骤标题 */
+    relinkStepLabel: string;
+    /** 是否在重新链接步骤末尾附加复合链接语义说明 */
+    compositeLinkNote?: boolean;
+    /** 调用方式说明：源码型与 Node 目录型分化（如是否需要全局 ad） */
+    invocationStyle: "global-ad" | "node-entry";
+    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 时使用） */
+    entryRelPath?: string;
+}): 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 interface CompositeSkillPackageInfo {
     config: ProjectConfig;
     actions: Array<{
@@ -23,33 +49,6 @@ export interface CompositeSkillPackageInfo {
     }>;
     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 文档。
  */

package/dist/skill/templates.js

@@ -4,6 +4,10 @@ function getCleanSkillMetadata(config) {
     const desc = config.description || `AI Agent skill for ${config.name} (${config.id})`;
     return { cleanName, desc };
 }
+/**
+ * 动作摘要列表渲染：只承载能力路由信息（标识、原始业务描述、只读或破坏性标注），
+ * 不展开完整输入输出 Schema；完整契约由 describe 命令按需调阅。
+ */
 function renderActionListMarkdown(actions, options = {}) {
     return actions
         .map((a) => {
@@ -12,7 +16,7 @@ function renderActionListMarkdown(actions, options = {}) {
             ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
             : `\`${a.id}\``;
         const lines = [`- ${idLabel}${aDesc}`];
-        // 标注元数据解析
+        // 标注元数据解析（安全标注不得从主说明移走）
         if (a.annotations && typeof a.annotations === "object") {
             const annoList = [];
             if (a.annotations.readOnly === true) {
@@ -25,49 +29,6 @@ function renderActionListMarkdown(actions, options = {}) {
                 lines.push(`  - 属性标注: ${annoList.join(", ")}`);
             }
         }
-        // 输入参数模式解析
-        if (a.inputSchema &&
-            typeof a.inputSchema === "object" &&
-            a.inputSchema.properties) {
-            const props = a.inputSchema.properties;
-            const req = (a.inputSchema.required || []);
-            const propKeys = Object.keys(props);
-            if (propKeys.length > 0) {
-                lines.push("  - 输入参数:");
-                for (const k of propKeys) {
-                    const p = props[k] || {};
-                    const typeStr = p.type ? `\`${p.type}\`` : "`any`";
-                    const reqStr = req.includes(k) ? ", 必填" : "";
-                    const descStr = p.description ? `: ${p.description}` : "";
-                    const defStr = p.default !== undefined
-                        ? ` (默认值: \`${JSON.stringify(p.default)}\`)`
-                        : "";
-                    lines.push(`    - \`${k}\` (${typeStr}${reqStr})${descStr}${defStr}`);
-                }
-            }
-            else {
-                lines.push("  - 输入参数: 无");
-            }
-        }
-        else {
-            lines.push("  - 输入参数: 无");
-        }
-        // 输出字段模式解析
-        if (a.outputSchema &&
-            typeof a.outputSchema === "object" &&
-            a.outputSchema.properties) {
-            const outProps = a.outputSchema.properties;
-            const outKeys = Object.keys(outProps);
-            if (outKeys.length > 0) {
-                lines.push("  - 输出字段:");
-                for (const k of outKeys) {
-                    const p = outProps[k] || {};
-                    const typeStr = p.type ? `\`${p.type}\`` : "`any`";
-                    const descStr = p.description ? `: ${p.description}` : "";
-                    lines.push(`    - \`${k}\` (${typeStr})${descStr}`);
-                }
-            }
-        }
         return lines.join("\n");
     })
         .join("\n\n");
@@ -130,39 +91,63 @@ function renderJsonEnvelopeSection(wording, options) {
 \`\`\`${descriptionBlock}`;
 }
 /**
- * 渲染「故障排查与环境安装指引」整节：source 与 composite 共用完整安装指引，
- * 差异点（依赖安装步骤标题、重新链接步骤标题、复合链接语义说明）通过参数分化。
+ * 渲染完整「运行时环境参考」正文：写入导出目录 references/actiondock-runtime.md，
+ * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
  */
-function renderTroubleshootingSection(options) {
+export function renderRuntimeReferenceContent(options) {
     const relinkNote = options.compositeLinkNote
-        ? `\n  \`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
+        ? `\`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
         : "";
-    return `---
-
-## 故障排查与环境安装指引（按需查阅）
-
-> [!NOTE]
-> **按需排查原则**：默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，**严禁在任务启动前盲目进行前置环境检查或体检**；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）或提示依赖缺失时，方可按本节指引安装初始化。
-
-### 命令行工具与环境依赖未就绪时的安装指引
+    const invocationSection = options.invocationStyle === "node-entry"
+        ? `本技能为 Node 目录型交付，可直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具：
 
-若宿主环境未安装 \`ad\` 命令行工具或依赖缺失，请依次按如下步骤完成安装：
+\`\`\`bash
+${options.entryRelPath || "node ./entry.mjs"} list
+${options.entryRelPath || "node ./entry.mjs"} describe <action-id>
+${options.entryRelPath || "node ./entry.mjs"} run <action-id> --json --input-file input.json
+\`\`\`
 
-- **环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。
+若宿主环境已全局安装 \`ad\`，亦可将其链接后统一调度。`
+        : `本技能为源码型交付，通过全局安装的 \`ad\` 命令行工具执行。`;
+    const isNodeEntry = options.invocationStyle === "node-entry";
+    const probePrinciple = isNodeEntry
+        ? `默认宿主环境中已预置 Node.js 运行环境。本目录型交付直接使用自身入口执行，不依赖全局 \`ad\`；正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检；仅在入口报错提示模块缺失（如 \`Cannot find package\`）或 Node.js 版本不满足时，方可按本文指引修复。`
+        : `默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）或提示依赖缺失时，方可按本文指引安装初始化。`;
+    const cliInstallSection = isNodeEntry
+        ? `- **Node.js 环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。目录型交付不需要全局安装 \`ad\`；若需要接入全局调度，可另行安装：
+  \`\`\`bash
+  npm install -g @actiondock/cli
+  \`\`\``
+        : `- **环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。
 - **全局安装 ActionDock 命令行工具**：
   \`\`\`bash
   npm install -g @actiondock/cli
-  \`\`\`
+  \`\`\``;
+    return `# ActionDock 运行时环境参考
+
+> 本文件为技能主说明的按需参考，仅在环境未就绪或报错时查阅；正常执行流程无需阅读本文。
+
+## 调用方式
+
+${invocationSection}
+
+## 按需排查原则
+
+${probePrinciple}
+
+## 环境依赖未就绪时的安装指引
+
+若宿主环境依赖缺失，请依次按如下步骤完成安装：
+
+${cliInstallSection}
 - **${options.dependencyStepLabel}**：
   若在技能目录内调用时提示模块缺失，在 \`<skill_root>\` 目录下安装生产依赖：
   \`\`\`bash
   cd "<skill_root>" && npm install --omit=dev
   \`\`\`
-- **验证工具就绪**：
-  \`\`\`bash
-  ad --version
-  \`\`\`
-- **环境诊断与体检**：
+- **验证就绪**：
+  ${isNodeEntry ? `${options.entryRelPath || "node ./entry.mjs"} list` : "ad --version"}
+- **环境诊断与体检**（仅全局接入 \`ad\` 后适用）：
   安装完成后若仍遇到异常，执行体检命令排查：
   \`\`\`bash
   ad doctor
@@ -170,8 +155,24 @@ function renderTroubleshootingSection(options) {
 - **${options.relinkStepLabel}**：
   \`\`\`bash
   ad link "<skill_root>"
-  \`\`\`${relinkNote}`;
+  \`\`\`
+${relinkNote ? `  ${relinkNote}\n` : ""}`;
 }
+/**
+ * 渲染主说明中的「故障排查」精简入口：仅保留按需排查原则与参考文件链接。
+ */
+function renderTroubleshootingSection(referenceRelPath) {
+    return `---
+
+## 故障排查与环境安装指引（按需查阅）
+
+> [!NOTE]
+> **按需排查原则**：默认宿主环境中已预置运行环境与依赖，正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检。
+
+仅在报错提示命令不存在或依赖缺失时，按需查阅完整安装与自愈指引：[${referenceRelPath}](${referenceRelPath})`;
+}
+/** 运行时参考文件的导出目录内相对路径（单一事实源） */
+export const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
 export function generateSourceSkillMd(config, actions, playbooks) {
     const { cleanName, desc } = getCleanSkillMetadata(config);
     const pkgId = config.id;
@@ -191,9 +192,9 @@ ${desc}
 
 本技能为 **ActionDock 源码型技能包**。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
-### 注册与链接
+### 注册与链接（全局调用）
 
-在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册：
+本技能面向全局挂载使用：在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
 
 \`\`\`bash
 ad link "<skill_root>"
@@ -229,13 +230,6 @@ ad run ${pkgId}/${firstAction} --json -- ASSIGNMENT...
 ad run ${pkgId}/${firstAction} --json --input-file input.json
 \`\`\`
 
-> 免注册本地执行：
-> 若工作目录已位于本技能根目录，亦可直接免 link 执行：
-> \`\`\`bash
-> cd <skill_root>
-> ad run ${firstAction} --json
-> \`\`\`
-
 ${renderJsonEnvelopeSection("envelope")}
 ${playbookSection}
 ---
@@ -260,10 +254,7 @@ ad state list --package ${pkgId}
 ad state get KEY --package ${pkgId}
 \`\`\`
 
-${renderTroubleshootingSection({
-        dependencyStepLabel: "安装技能源码依赖",
-        relinkStepLabel: "完成安装后重新链接本技能",
-    })}
+${renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH)}
 `;
 }
 export function generateStandaloneSkillMd(config, actions, playbooks, binaryRelPath = "./bin/action-bin") {
@@ -335,73 +326,16 @@ ${binaryRelPath} state get KEY
 
 ## 故障排查与依赖自愈指引（按需查阅）
 
-若在宿主环境中执行时提示模块缺失，在技能根目录下安装生产依赖：
+本目录为 Node 目录型交付，直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具。
+若提示模块缺失，在技能根目录下安装生产依赖：
 
 \`\`\`bash
 npm install --omit=dev
 \`\`\`
+
+完整环境安装与自愈指引按需查阅：[${RUNTIME_REFERENCE_REL_PATH}](${RUNTIME_REFERENCE_REL_PATH})
 `;
 }
-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";
-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 Error(`Unknown ActionDock custom slot '${match[1]}'. Valid slots: ${COMPOSITE_CUSTOM_SLOTS.join(", ")}`);
-            }
-            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, "");
-        }
-    }
-    return { description, sections: parseCustomSections(body) };
-}
 /**
  * 生成多包聚合的复合模式 SKILL.md 文档。
  */
@@ -480,11 +414,7 @@ ad run ${sampleActionId} --json --input-file input.json
 \`\`\`
 
 ${renderJsonEnvelopeSection("envelope", { withDescriptions: false })}`;
-    const sTroubleshooting = renderTroubleshootingSection({
-        dependencyStepLabel: "安装复合技能聚合依赖",
-        relinkStepLabel: "完成安装后重新链接复合技能",
-        compositeLinkNote: true,
-    });
+    const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);
     const parts = [
         { slot: "intro", text: sIntro },
         { slot: "after-describe", text: sDescribe },

package/dist/skill-md.d.ts

@@ -1,5 +1,5 @@
-import { type PlaybookDefinition, type ProjectConfig } from "@actiondock/core/project";
-import { type CompositeCustomDeclaration, type SkillActionItem } from "./skill/index.js";
+import { type ProjectConfig } from "@actiondock/core/project";
+import { type CompositeCustomDeclaration } from "./skill/index.js";
 import type { CompositeSkillExportOptions, SelectionPlan } from "./types.js";
 /**
  * SKILL.md 发现、复用与模板视图适配层。
@@ -7,16 +7,6 @@ import type { CompositeSkillExportOptions, SelectionPlan } from "./types.js";
  * 职责单一聚焦：定位项目中已有的 SKILL.md（单包与复合套件两种检索策略）、
  * 解析自定义说明书声明，并将规划产物适配为模板生成所需视图。
  */
-/** 供模板生成使用的 SkillActionItem 兼容视图 */
-type PlanActionView = SkillActionItem;
-/**
- * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
- */
-export declare function toSkillActionItems(actions: SelectionPlan["actions"]): PlanActionView[];
-/**
- * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
- */
-export declare function toPlaybookDefinitions(playbooks: SelectionPlan["playbooks"]): PlaybookDefinition[];
 /**
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
@@ -36,7 +26,7 @@ export declare function resolveCustomSkillDeclaration(options: CompositeSkillExp
  * 复制或生成 SKILL.md 到目标目录。
  * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
  */
-export declare function writeSkillMd(root: string, destDir: string, plan: SelectionPlan, options: {
+export declare function writeSkillMd(root: string, destDir: string, options: {
     skipSkillMd?: boolean;
     skillMdPath?: string;
     pkgSlug: string;
@@ -45,4 +35,3 @@ export declare function writeSkillMd(root: string, destDir: string, plan: Select
  * 构造模板生成所需的 ProjectConfig 视图。
  */
 export declare function buildConfigForTemplates(plan: SelectionPlan, actionsDir: string, playbooksDir: string): ProjectConfig;
-export {};

package/dist/skill-md.js

@@ -4,17 +4,11 @@ import { getPackageSlug, } from "@actiondock/core/project";
 import { COMPOSITE_CUSTOM_DECLARATION_FILE, parseCustomSkillDeclaration, } from "./skill/index.js";
 import { BuilderError } from "./errors.js";
 /**
- * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
+ * SKILL.md 发现、复用与模板视图适配层。
+ *
+ * 职责单一聚焦：定位项目中已有的 SKILL.md（单包与复合套件两种检索策略）、
+ * 解析自定义说明书声明，并将规划产物适配为模板生成所需视图。
  */
-export function toSkillActionItems(actions) {
-    return actions;
-}
-/**
- * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
- */
-export function toPlaybookDefinitions(playbooks) {
-    return playbooks;
-}
 /**
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
@@ -134,7 +128,7 @@ export function resolveCustomSkillDeclaration(options) {
  * 复制或生成 SKILL.md 到目标目录。
  * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
  */
-export function writeSkillMd(root, destDir, plan, options, generate) {
+export function writeSkillMd(root, destDir, options, generate) {
     const existingSkill = options.skipSkillMd
         ? undefined
         : findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug);

package/dist/types.d.ts

@@ -206,6 +206,25 @@ export interface BuildOptions {
     /** 是否跳过本地相对依赖完整性校验（默认 false） */
     skipDependencyValidation?: boolean;
 }
+/**
+ * 基于已规划依赖图的目录型交付产物生成选项。
+ */
+export interface BuildProjectWithPlanOptions {
+    /** 目标项目根目录绝对路径（可选，缺省时使用规划内 projectRoot） */
+    projectRoot?: string;
+    /** 产物输出目录路径（默认输出至 dist 目录） */
+    outDir?: string;
+    /** 输出路径别名 */
+    outfile?: string;
+    /** 是否生成标准 zip 压缩归档交付产物 */
+    archive?: boolean;
+    /** 是否在干净暂存目录中物化锁定的生产依赖 */
+    vendorDeps?: boolean;
+    /** 是否允许执行依赖安装生命周期脚本（默认 false） */
+    allowInstallScripts?: boolean;
+    /** 是否强制要求构建可复现（默认 false） */
+    requireReproducible?: boolean;
+}
 /**
  * 目录型构建产物结果描述。
  */
@@ -357,26 +376,6 @@ export interface SkillExportResult {
  * 导出 Skill 结果契约（对齐标准接口命名）。
  */
 export type ExportSkillResult = SkillExportResult;
-/**
- * 批量 Skill 导出选项。
- */
-export interface BatchSkillExportOptions extends Omit<SkillExporterOptions, "projectRoot"> {
-    /** 待导出的项目根目录绝对路径列表 */
-    projectRoots: string[];
-}
-/**
- * 批量 Skill 导出结果。
- */
-export interface BatchSkillExportResult {
-    /** 各包独立导出结果列表 */
-    results: SkillExportResult[];
-    /** 批量导出根目录 */
-    outDir: string;
-    /** 导出的总 Action 数量 */
-    totalActions: number;
-    /** 导出的总 Playbook 数量 */
-    totalPlaybooks: number;
-}
 /**
  * 复合 Skill 套件导出选项。
  */

package/dist/vendor.d.ts

@@ -0,0 +1,5 @@
+import type { SelectionPlan } from "./types.js";
+/**
+ * 物化锁定生产依赖到产物 node_modules 目录（vendorDeps 开启时）。
+ */
+export declare function vendorDependencies(root: string, stagingDir: string, plan: SelectionPlan): void;

package/dist/vendor.js

@@ -0,0 +1,76 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/**
+ * 物化锁定生产依赖到产物 node_modules 目录（vendorDeps 开启时）。
+ */
+export function vendorDependencies(root, stagingDir, plan) {
+    const destNodeModules = join(stagingDir, "node_modules");
+    mkdirSync(destNodeModules, { recursive: true });
+    // 尝试复制本地已解析的生产依赖
+    const sourceCandidates = [
+        join(root, "node_modules"),
+        resolve(import.meta.dirname, "../../../node_modules"),
+    ];
+    // 嵌套 node_modules 不再跳过：多版本共存时传递依赖必须完整物化，
+    // 否则产物运行时 Cannot find module 且构建阶段无任何警告；
+    // 保留 .git、.bin 等目录排除（.bin 为平台相关的命令行 shim，不参与运行时模块解析）
+    const copyVendorPackage = (srcDir, destDir) => {
+        if (!existsSync(srcDir))
+            return;
+        mkdirSync(destDir, { recursive: true });
+        const entries = readdirSync(srcDir);
+        for (const entry of entries) {
+            if (entry === ".git" ||
+                entry === ".actiondock" ||
+                entry === ".bin" ||
+                entry === "test" ||
+                entry === "tests") {
+                continue;
+            }
+            const srcPath = join(srcDir, entry);
+            const destPath = join(destDir, entry);
+            try {
+                const stat = lstatSync(srcPath);
+                if (stat.isSymbolicLink()) {
+                    // 软链接不进行递归物理穿越，避免链接环路死锁
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    copyVendorPackage(srcPath, destPath);
+                }
+                else if (stat.isFile()) {
+                    copyFileSync(srcPath, destPath);
+                }
+            }
+            catch (err) {
+                // 防御与透明：记录系统读取异常日志
+                console.warn(`[actiondock] Warning: Failed to vendor file ${srcPath}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    for (const dep of plan.dependencies.external) {
+        if (dep.isDev)
+            continue;
+        for (const baseModules of sourceCandidates) {
+            const srcDep = join(baseModules, dep.name);
+            if (existsSync(srcDep)) {
+                const targetDep = join(destNodeModules, dep.name);
+                mkdirSync(dirname(targetDep), { recursive: true });
+                copyVendorPackage(srcDep, targetDep);
+                break;
+            }
+        }
+    }
+    // 复制 ActionDock 内部依赖
+    for (const internalPkg of ["@actiondock/core", "@actiondock/sdk"]) {
+        for (const baseModules of sourceCandidates) {
+            const srcDep = join(baseModules, internalPkg);
+            if (existsSync(srcDep)) {
+                const targetDep = join(destNodeModules, internalPkg);
+                mkdirSync(dirname(targetDep), { recursive: true });
+                copyVendorPackage(srcDep, targetDep);
+                break;
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.9.1",
+  "version": "2.11.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.9.1",
-    "@actiondock/sdk": "^2.9.1"
+    "@actiondock/core": "^2.11.0",
+    "@actiondock/sdk": "^2.11.0"
   },
   "keywords": [
     "actiondock",

package/dist/export-batch.d.ts

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

package/dist/export-batch.js

@@ -1,37 +0,0 @@
-import { mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { loadProjectConfig } from "@actiondock/core";
-import { BuilderError } from "./errors.js";
-import { allocatePackageDirName } from "./manifest.js";
-/**
- * 执行批量导出多个 Skill。
- */
-export async function exportBatchImpl(options, exportSingle) {
-    if (!options.projectRoots || options.projectRoots.length === 0) {
-        throw new BuilderError("No project roots provided for batch skill export.");
-    }
-    const results = [];
-    const baseOutDir = resolve(options.outDir || join(process.cwd(), "dist", "skills"));
-    mkdirSync(baseOutDir, { recursive: true });
-    const usedDirNames = new Set();
-    for (const projectRoot of options.projectRoots) {
-        const config = loadProjectConfig(projectRoot);
-        // 目录名分配统一复用 manifest 的 allocatePackageDirName，回退后仍冲突会追加数字后缀
-        const pkgSlug = allocatePackageDirName(usedDirNames, config.id);
-        const pkgOutDir = join(baseOutDir, `${pkgSlug}-skill`);
-        const res = await exportSingle({
-            ...options,
-            projectRoot,
-            outDir: pkgOutDir,
-        });
-        results.push(res);
-    }
-    const totalActions = results.reduce((sum, r) => sum + r.actionsCount, 0);
-    const totalPlaybooks = results.reduce((sum, r) => sum + r.playbooksCount, 0);
-    return {
-        results,
-        outDir: baseOutDir,
-        totalActions,
-        totalPlaybooks,
-    };
-}

package/dist/export-node.d.ts

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