@actiondock/builder 2.16.0 → 2.17.0

package/README.md

@@ -40,21 +40,29 @@ 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` 格式。
+- 生成 SKILL.md 指令：提取 Playbook 规程内容与工具元数据，合成符合智能体规范的操作指南文档与声明头部。
+- 复合套件导出与说明书定制：支持 `exportCompositeSkill` 函数将工作区内的多个包统一导出为复合工作区技能套件；支持通过 `customMdPath` 注入插槽定制模板，通过 `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 +81,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/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) {

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,6 +7,7 @@ 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 { isOwnAction } from "./types.js";
 import { buildConfigForTemplates, writeSkillMd, } from "./skill-md.js";
 /**
  * 源码型 Skill 导出装配层。
@@ -21,7 +22,7 @@ export function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
     const actionsDir = plan.actionsDir || "actions";
     const playbooksDir = plan.playbooksDir || "playbooks";
     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 }, () => generateSourceSkillMd(configForTemplates, plan.actions.filter((a) => isOwnAction(a)), plan.playbooks));
     // 导出精简后的 actiondock.json 项目配置（项目元数据与清单的单一事实源）
     const exportedConfig = serializePlanManifest(plan, {
         omitEmptyConfig: true,

package/dist/exporter.js

@@ -25,7 +25,7 @@ export class SkillExporter {
      */
     async 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 +40,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 +60,7 @@ export class SkillExporter {
                 workspaceRoot: options.workspaceRoot,
                 skillMdPath: options.skillMdPath,
                 customMdPath: options.customMdPath,
+                bundleDeps: options.bundleDeps,
             });
             return {
                 packageId: plan.packageId,

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;
     /** 是否执行归档压缩，亦可直接指定归档格式 */
@@ -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.17.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.17.0",
+    "@actiondock/sdk": "^2.17.0"
   },
   "keywords": [
     "actiondock",