@actiondock/builder 2.0.10 → 2.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "ActionDock Build Planner, Bun standalone compiler, and Skill exporter",
   "type": "module",
   "main": "./src/index.ts",
@@ -27,8 +27,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@actiondock/core": "^2.0.10",
-    "@actiondock/sdk": "^2.0.10",
+    "@actiondock/core": "^2.0.11",
+    "@actiondock/sdk": "^2.0.11",
     "yaml": "^2.7.0"
   },
   "devDependencies": {

package/src/exporter.ts

@@ -1,18 +1,30 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import {
-  generateSkillJson,
+  generateCompositeSkillMd,
   generateSourceSkillMd,
   generateStandaloneEntrypoint,
   generateStandaloneSkillMd,
   getPackageSlug,
+  loadManifest,
+  loadPlaybooks,
+  loadProjectConfig,
+  type CompositeSkillPackageInfo,
   type ProjectConfig,
 } from "@actiondock/core";
 import { createTarGzArchive, createZipArchive } from "./archive";
 import { BunCompiler } from "./compiler";
 import { BuilderError } from "./errors";
 import { BuildPlanner } from "./planner";
-import type { ArchiveFormat, SkillExporterOptions, SkillExportResult } from "./types";
+import type {
+  ArchiveFormat,
+  BatchSkillExportOptions,
+  BatchSkillExportResult,
+  CompositeSkillExportOptions,
+  CompositeSkillExportResult,
+  SkillExporterOptions,
+  SkillExportResult,
+} from "./types";
 
 /**
  * 递归扫描生成目录中的所有相对文件路径。
@@ -65,6 +77,105 @@ function createArchive(
   return archivePath;
 }
 
+/**
+ * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
+ */
+export function findExistingSingleSkillMd(
+  projectRoot: string,
+  explicitPath?: string,
+  pkgSlug?: string
+): string | undefined {
+  if (explicitPath && existsSync(explicitPath)) {
+    try {
+      if (statSync(explicitPath).isFile()) return resolve(explicitPath);
+    } catch {
+      // 忽略文件属性读取异常
+    }
+  }
+
+  const candidates = [
+    join(projectRoot, "SKILL.md"),
+    join(projectRoot, "skill.md"),
+    join(projectRoot, "skills", "SKILL.md"),
+    join(projectRoot, "skills", "skill.md"),
+  ];
+
+  if (pkgSlug) {
+    candidates.push(
+      join(projectRoot, "skills", pkgSlug, "SKILL.md"),
+      join(projectRoot, "skills", pkgSlug, "skill.md")
+    );
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        if (statSync(candidate).isFile()) return resolve(candidate);
+      } catch {
+        // 忽略
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * 检索复合套件工作区中已存在的 SKILL.md 文件。
+ */
+export function findExistingCompositeSkillMd(
+  options: CompositeSkillExportOptions
+): string | undefined {
+  if (options.skillMdPath && existsSync(options.skillMdPath)) {
+    try {
+      if (statSync(options.skillMdPath).isFile()) return resolve(options.skillMdPath);
+    } catch {
+      // 忽略
+    }
+  }
+
+  const bundleSlug = getPackageSlug(options.bundleName);
+  const searchDirs = new Set<string>();
+
+  if (options.workspaceRoot && existsSync(options.workspaceRoot)) {
+    searchDirs.add(resolve(options.workspaceRoot));
+  }
+  searchDirs.add(process.cwd());
+
+  for (const root of options.projectRoots) {
+    const absRoot = resolve(root);
+    const parentDir = dirname(absRoot);
+    searchDirs.add(parentDir);
+    searchDirs.add(dirname(parentDir));
+  }
+
+  const candidateRelativePaths = [
+    join("skills", options.bundleName, "SKILL.md"),
+    join("skills", bundleSlug, "SKILL.md"),
+    join("skills", "SKILL.md"),
+    "SKILL.md",
+    join("skills", options.bundleName, "skill.md"),
+    join("skills", bundleSlug, "skill.md"),
+    join("skills", "skill.md"),
+    "skill.md",
+  ];
+
+  for (const dir of searchDirs) {
+    for (const rel of candidateRelativePaths) {
+      const fullPath = join(dir, rel);
+      if (existsSync(fullPath)) {
+        try {
+          if (statSync(fullPath).isFile()) return fullPath;
+        } catch {
+          // 忽略
+        }
+      }
+    }
+  }
+
+  return undefined;
+}
+
 /**
  * Agent Skill 导出器。
  * 负责源码型 Skill 与独立二进制型 Skill 的构建、打包与归档分发。
@@ -115,36 +226,32 @@ export class SkillExporter {
       config: plan.configDefs as any,
     };
 
+    let usedExistingSkillMd: string | undefined;
+
     if (mode === "source") {
       // ----------------------------------------------------
       // 源码 Skill 导出 (Source Skill Export)
-      // 包含: SKILL.md, actiondock.skill.json, actiondock.manifest.json, actiondock.json, package.json, 源码与资产
-      // ----------------------------------------------------
-
-      // 1. 生成 SKILL.md
-      const skillMd = generateSourceSkillMd(
-        configForTemplates,
-        plan.actions as any,
-        plan.playbooks as any
-      );
-      writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
-
-      // 2. 生成 actiondock.skill.json 工具清单
-      const skillJsonContent = generateSkillJson(
-        configForTemplates,
-        plan.actions as any,
-        {
-          mode: "source",
-          playbooks: plan.playbooks as any,
+      // 优先复用当前动作目录下已有的 SKILL.md；若不存在且未显式跳过，则动态生成
+      const existingSkill = !options.skipSkillMd
+        ? findExistingSingleSkillMd(root, options.skillMdPath, pkgSlug)
+        : undefined;
+
+      if (existingSkill) {
+        usedExistingSkillMd = existingSkill;
+        const destSkillMd = join(skillDir, "SKILL.md");
+        if (resolve(existingSkill) !== resolve(destSkillMd)) {
+          copyFileSync(existingSkill, destSkillMd);
         }
-      );
-      writeFileSync(
-        join(skillDir, "actiondock.skill.json"),
-        skillJsonContent,
-        "utf-8"
-      );
+      } else if (!options.skipSkillMd) {
+        const skillMd = generateSourceSkillMd(
+          configForTemplates,
+          plan.actions as any,
+          plan.playbooks as any
+        );
+        writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
+      }
 
-      // 3. 导出精简后的 actiondock.manifest.json 清单
+      // - 导出精简后的 actiondock.manifest.json 清单
       const manifestActions: Record<string, unknown> = {};
       for (const a of plan.actions) {
         manifestActions[a.id] = {
@@ -156,6 +263,12 @@ export class SkillExporter {
           tags: a.tags,
           annotations: a.annotations,
         };
+        if (a.id.includes("/")) {
+          const shortId = a.id.slice(a.id.lastIndexOf("/") + 1);
+          if (!manifestActions[shortId]) {
+            manifestActions[shortId] = manifestActions[a.id];
+          }
+        }
       }
       const exportedManifest = {
         schemaVersion: 1,
@@ -168,7 +281,7 @@ export class SkillExporter {
         "utf-8"
       );
 
-      // 4. 导出精简后的 actiondock.json 项目配置
+      // - 导出精简后的 actiondock.json 项目配置
       const exportedConfig = {
         id: plan.packageId,
         name: plan.packageName,
@@ -184,7 +297,7 @@ export class SkillExporter {
         "utf-8"
       );
 
-      // 5. 导出 package.json
+      // - 导出 package.json
       const projectPkgPath = join(root, "package.json");
       let exportedPkg: any;
       if (existsSync(projectPkgPath)) {
@@ -225,13 +338,13 @@ export class SkillExporter {
         "utf-8"
       );
 
-      // 6. 拷贝 tsconfig.json（若存在）
+      // - 拷贝 tsconfig.json（若存在）
       const tsconfigPath = join(root, "tsconfig.json");
       if (existsSync(tsconfigPath)) {
         copyFileSync(tsconfigPath, join(skillDir, "tsconfig.json"));
       }
 
-      // 7. 拷贝 Action 源码文件，完整保留相对路径
+      // - 拷贝 Action 源码文件，完整保留相对路径
       for (const act of plan.actions) {
         if (existsSync(act.resolvedPath)) {
           const destFile = join(skillDir, act.entry);
@@ -240,16 +353,16 @@ export class SkillExporter {
         }
       }
 
-      // 8. 拷贝静态资产文件，完整保留相对路径
+      // - 拷贝静态资产与代码模块文件，完整保留相对路径
       for (const dep of plan.dependencies.modulesAndAssets) {
-        if (dep.type === "asset" && existsSync(dep.resolvedPath)) {
+        if ((dep.type === "asset" || dep.type === "module") && existsSync(dep.resolvedPath)) {
           const destAsset = join(skillDir, dep.path);
           mkdirSync(dirname(destAsset), { recursive: true });
           copyFileSync(dep.resolvedPath, destAsset);
         }
       }
 
-      // 9. 拷贝 Playbook 文件
+      // - 拷贝 Playbook 规程文件
       for (const pb of plan.playbooks) {
         if (existsSync(pb.filePath)) {
           const destPb = join(playbooksDestDir, basename(pb.filePath));
@@ -259,7 +372,7 @@ export class SkillExporter {
     } else {
       // ----------------------------------------------------
       // 独立二进制 Skill 导出 (Standalone Binary Skill Export)
-      // 包含: SKILL.md, actiondock.skill.json, bin/<binary>, playbooks/*, assets/*
+      // 包含: SKILL.md, bin/<binary>, playbooks/*, assets/*
       // ----------------------------------------------------
       const binDir = join(skillDir, "bin");
       mkdirSync(binDir, { recursive: true });
@@ -304,33 +417,28 @@ export class SkillExporter {
 
       const actualBinaryName = basename(compileRes.executablePath);
 
-      // 1. 生成独立模式 SKILL.md
-      const skillMd = generateStandaloneSkillMd(
-        configForTemplates,
-        plan.actions as any,
-        plan.playbooks as any,
-        `./bin/${actualBinaryName}`
-      );
-      writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
-
-      // 2. 生成 actiondock.skill.json
-      const skillJsonContent = generateSkillJson(
-        configForTemplates,
-        plan.actions as any,
-        {
-          mode: "standalone",
-          executable: `./bin/${actualBinaryName}`,
-          target,
-          playbooks: plan.playbooks as any,
+      // - 生成独立模式 SKILL.md（若未显式跳过）
+      const existingSkill = !options.skipSkillMd
+        ? findExistingSingleSkillMd(root, options.skillMdPath, pkgSlug)
+        : undefined;
+
+      if (existingSkill) {
+        usedExistingSkillMd = existingSkill;
+        const destSkillMd = join(skillDir, "SKILL.md");
+        if (resolve(existingSkill) !== resolve(destSkillMd)) {
+          copyFileSync(existingSkill, destSkillMd);
         }
-      );
-      writeFileSync(
-        join(skillDir, "actiondock.skill.json"),
-        skillJsonContent,
-        "utf-8"
-      );
+      } else if (!options.skipSkillMd) {
+        const skillMd = generateStandaloneSkillMd(
+          configForTemplates,
+          plan.actions as any,
+          plan.playbooks as any,
+          `./bin/${actualBinaryName}`
+        );
+        writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
+      }
 
-      // 3. 拷贝 Playbook
+      // - 拷贝 Playbook 规程文件
       for (const pb of plan.playbooks) {
         if (existsSync(pb.filePath)) {
           const destPb = join(playbooksDestDir, basename(pb.filePath));
@@ -338,7 +446,7 @@ export class SkillExporter {
         }
       }
 
-      // 4. 拷贝静态资产
+      // - 拷贝静态资产
       for (const dep of plan.dependencies.modulesAndAssets) {
         if (dep.type === "asset" && existsSync(dep.resolvedPath)) {
           const destAsset = join(skillDir, dep.path);
@@ -374,9 +482,172 @@ export class SkillExporter {
       actions: plan.actions.map((a) => a.id),
       playbooks: plan.playbooks.map((p) => p.id),
       files,
+      usedExistingSkillMd,
+    };
+  }
+
+  /**
+   * 批量导出多个 Skill。
+   */
+  public async exportBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult> {
+    if (!options.projectRoots || options.projectRoots.length === 0) {
+      throw new BuilderError("No project roots provided for batch skill export.");
+    }
+
+    const results: SkillExportResult[] = [];
+    const baseOutDir = resolve(options.outDir || join(process.cwd(), "dist", "skills"));
+    mkdirSync(baseOutDir, { recursive: true });
+
+    const usedDirNames = new Set<string>();
+    for (const projectRoot of options.projectRoots) {
+      const config = loadProjectConfig(projectRoot);
+      let pkgSlug = getPackageSlug(config.id);
+      if (usedDirNames.has(pkgSlug)) {
+        pkgSlug = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/^-+|-+$/g, "");
+      }
+      usedDirNames.add(pkgSlug);
+
+      const pkgOutDir = join(baseOutDir, `${pkgSlug}-skill`);
+
+      const res = await this.export({
+        ...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,
+    };
+  }
+
+  /**
+   * 静态辅助调用批量导出方法。
+   */
+  public static async exportBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult> {
+    const exporter = new SkillExporter();
+    return exporter.exportBatch(options);
+  }
+
+  /**
+   * 复合模式导出：将多个包聚合为一个统一的复合技能目录。
+   */
+  public async exportComposite(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult> {
+    if (!options.projectRoots || options.projectRoots.length === 0) {
+      throw new BuilderError("No project roots provided for composite skill export.");
+    }
+    if (!options.bundleName || !options.bundleName.trim()) {
+      throw new BuilderError("bundleName is required for composite skill export.");
+    }
+
+    const bundleSlug = getPackageSlug(options.bundleName);
+    const defaultSkillDir = join(process.cwd(), "dist", `${bundleSlug}-skill`);
+    const skillDir = resolve(options.outDir || defaultSkillDir);
+
+    mkdirSync(skillDir, { recursive: true });
+    const packagesDestDir = join(skillDir, "packages");
+    mkdirSync(packagesDestDir, { recursive: true });
+
+    const packageInfos: CompositeSkillPackageInfo[] = [];
+    const packageSummaries: Array<{ packageId: string; actions: string[]; playbooks: string[] }> = [];
+
+    const usedDirNames = new Set<string>();
+    for (const projectRoot of options.projectRoots) {
+      const config = loadProjectConfig(projectRoot);
+      let pkgSlug = getPackageSlug(config.id);
+      if (usedDirNames.has(pkgSlug)) {
+        pkgSlug = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/^-+|-+$/g, "");
+      }
+      usedDirNames.add(pkgSlug);
+
+      const destPkgDir = join(packagesDestDir, pkgSlug);
+
+      const singleExport = await this.export({
+        projectRoot,
+        outDir: destPkgDir,
+        archive: false,
+        skipSkillMd: true,
+      });
+
+      const manifest = loadManifest(destPkgDir) || loadManifest(projectRoot);
+      const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+
+      const actionEntries = singleExport.actions.map((actId) => ({
+        id: actId,
+        description: manifest?.actions?.[actId]?.description,
+      }));
+
+      packageInfos.push({
+        config,
+        actions: actionEntries,
+        playbooks: Array.from(playbooks.values()),
+        packageDir: pkgSlug,
+      });
+
+      packageSummaries.push({
+        packageId: config.id,
+        actions: singleExport.actions,
+        playbooks: singleExport.playbooks,
+      });
+    }
+
+    const existingSkillPath = findExistingCompositeSkillMd(options);
+    if (existingSkillPath) {
+      const destSkillMdPath = join(skillDir, "SKILL.md");
+      if (resolve(existingSkillPath) !== resolve(destSkillMdPath)) {
+        copyFileSync(existingSkillPath, destSkillMdPath);
+      }
+    } else {
+      const description =
+        options.description ||
+        `ActionDock 复合技能套件，聚合 ${packageInfos.map((p) => p.config.name).join("、")}`;
+      const compositeSkillMd = generateCompositeSkillMd(options.bundleName, description, packageInfos);
+      writeFileSync(join(skillDir, "SKILL.md"), compositeSkillMd, "utf-8");
+    }
+
+    let archivePath: string | undefined;
+    if (options.archive) {
+      let format: ArchiveFormat = "zip";
+      if (options.archiveFormat === "tar.gz" || options.archive === "tar.gz") {
+        format = "tar.gz";
+      } else if (options.archiveFormat === "zip" || options.archive === "zip") {
+        format = "zip";
+      }
+      archivePath = createArchive(skillDir, format);
+    }
+
+    const files = scanRelativeFiles(skillDir);
+    const totalActions = packageSummaries.reduce((sum, p) => sum + p.actions.length, 0);
+    const totalPlaybooks = packageSummaries.reduce((sum, p) => sum + p.playbooks.length, 0);
+
+    return {
+      bundleName: options.bundleName,
+      skillDir,
+      archivePath,
+      packagesCount: packageInfos.length,
+      actionsCount: totalActions,
+      playbooksCount: totalPlaybooks,
+      packages: packageSummaries,
+      files,
+      usedExistingSkillMd: existingSkillPath,
     };
   }
 
+  /**
+   * 静态辅助调用复合导出方法。
+   */
+  public static async exportComposite(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult> {
+    const exporter = new SkillExporter();
+    return exporter.exportComposite(options);
+  }
+
   /**
    * 静态辅助调用方法。
    */
@@ -392,3 +663,18 @@ export class SkillExporter {
 export async function exportSkill(options: SkillExporterOptions): Promise<SkillExportResult> {
   return SkillExporter.export(options);
 }
+
+/**
+ * 快捷批量导出多个 Skill 产物函数。
+ */
+export async function exportSkillBatch(options: BatchSkillExportOptions): Promise<BatchSkillExportResult> {
+  return SkillExporter.exportBatch(options);
+}
+
+/**
+ * 快捷复合模式导出 Skill 产物函数。
+ */
+export async function exportCompositeSkill(options: CompositeSkillExportOptions): Promise<CompositeSkillExportResult> {
+  return SkillExporter.exportComposite(options);
+}
+

package/src/planner.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import YAML from "yaml";
 import {
   type ActionDockManifest,
@@ -8,6 +8,7 @@ import {
   loadProjectConfig,
   type PlaybookDefinition,
   type ProjectConfig,
+  resolveActionProjectSync,
   validateManifest,
 } from "@actiondock/core";
 import { PlannerError } from "./errors";
@@ -40,6 +41,199 @@ function walkDirectory(dir: string): string[] {
   return results;
 }
 
+/**
+ * 忽略的模块路径与文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。
+ */
+function isIgnoredModulePath(relPath: string): boolean {
+  const normalized = relPath.replace(/\\/g, "/");
+  return (
+    normalized.startsWith("node_modules/") ||
+    normalized.includes("/node_modules/") ||
+    normalized.startsWith(".git/") ||
+    normalized.startsWith("dist/") ||
+    normalized.startsWith(".actiondock/") ||
+    normalized.endsWith(".test.ts") ||
+    normalized.endsWith(".test.js") ||
+    normalized.endsWith(".test.tsx") ||
+    normalized.endsWith(".test.jsx") ||
+    normalized.endsWith(".spec.ts") ||
+    normalized.endsWith(".spec.js") ||
+    normalized.endsWith(".spec.tsx") ||
+    normalized.endsWith(".spec.jsx") ||
+    normalized.endsWith(".d.ts")
+  );
+}
+
+/**
+ * 提取源码文本中的所有相对路径模块引用说明符（如 ./... 与 ../...）。
+ * 采用纯正则静态提取，杜绝动态 import 与代码执行。
+ */
+function extractRelativeImports(source: string): string[] {
+  // 移除多行注释与单行注释，避免注释中的无效相对路径被误提取
+  const stripped = source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/[^\n]*/g, "");
+
+  const specifiers = new Set<string>();
+
+  // 匹配 from "..."、from '...'、from `...`
+  const fromRegex = /\bfrom\s*["'`]([^"'`]+)["'`]/g;
+  let match: RegExpExecArray | null;
+  while ((match = fromRegex.exec(stripped)) !== null) {
+    const spec = match[1].trim();
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      specifiers.add(spec);
+    }
+  }
+
+  // 匹配 import(...) 或 import "..."
+  const importRegex = /\bimport\s*(?:\(\s*)?["'`]([^"'`]+)["'`]/g;
+  while ((match = importRegex.exec(stripped)) !== null) {
+    const spec = match[1].trim();
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      specifiers.add(spec);
+    }
+  }
+
+  // 匹配 require(...)
+  const requireRegex = /\brequire\s*\(\s*["'`]([^"'`]+)["'`]/g;
+  while ((match = requireRegex.exec(stripped)) !== null) {
+    const spec = match[1].trim();
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      specifiers.add(spec);
+    }
+  }
+
+  return Array.from(specifiers);
+}
+
+const CANDIDATE_EXTENSIONS = [
+  "",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+  ".json",
+];
+
+/**
+ * 在文件系统上探测解析相对导入说明符所对应的物理源文件。
+ * 兼容 NodeNext 规范中将 .js / .mjs / .cjs 说明符解析映射到 .ts / .mts / .cts 源文件。
+ */
+function resolveLocalModulePath(baseDir: string, specifier: string): string | null {
+  const candidate = resolve(baseDir, specifier);
+
+  // 1. 若候选路径直接存在且为文件
+  if (existsSync(candidate)) {
+    try {
+      if (statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      // 忽略文件属性读取异常
+    }
+  }
+
+  // 2. NodeNext / ESM 规范映射：若导入说明符以 .js / .mjs / .cjs 结尾，优先尝试对应 TypeScript 源码文件
+  if (candidate.endsWith(".js")) {
+    const tsPath = candidate.slice(0, -3) + ".ts";
+    if (existsSync(tsPath)) return tsPath;
+    const tsxPath = candidate.slice(0, -3) + ".tsx";
+    if (existsSync(tsxPath)) return tsxPath;
+  } else if (candidate.endsWith(".mjs")) {
+    const mtsPath = candidate.slice(0, -4) + ".mts";
+    if (existsSync(mtsPath)) return mtsPath;
+  } else if (candidate.endsWith(".cjs")) {
+    const ctsPath = candidate.slice(0, -4) + ".cts";
+    if (existsSync(ctsPath)) return ctsPath;
+  }
+
+  // 3. 尝试追加常见扩展名
+  for (const ext of CANDIDATE_EXTENSIONS) {
+    if (!ext) continue;
+    const withExt = candidate + ext;
+    if (existsSync(withExt)) {
+      try {
+        if (statSync(withExt).isFile()) {
+          return withExt;
+        }
+      } catch {
+        // 忽略
+      }
+    }
+  }
+
+  // 4. 若为目录，尝试 index 文件
+  if (existsSync(candidate)) {
+    try {
+      if (statSync(candidate).isDirectory()) {
+        for (const ext of [".ts", ".tsx", ".js", ".mjs", ".json"]) {
+          const indexFile = join(candidate, `index${ext}`);
+          if (existsSync(indexFile)) {
+            return indexFile;
+          }
+        }
+      }
+    } catch {
+      // 忽略
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 从一组入口文件出发，静态深度追踪所有相对路径引用的本地源码模块闭包。
+ */
+function traceLocalModuleDependencies(
+  entryFiles: string[],
+  projectRoot: string
+): string[] {
+  const visited = new Set<string>();
+  const modules = new Set<string>();
+  const queue = [...entryFiles];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    const relToRoot = relative(projectRoot, current);
+    if (relToRoot.startsWith("..") || isAbsolute(relToRoot)) {
+      continue;
+    }
+
+    let content = "";
+    try {
+      content = readFileSync(current, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const specifiers = extractRelativeImports(content);
+    const dir = dirname(current);
+
+    for (const spec of specifiers) {
+      const resolved = resolveLocalModulePath(dir, spec);
+      if (resolved) {
+        const rel = relative(projectRoot, resolved);
+        if (!rel.startsWith("..") && !isAbsolute(rel) && !isIgnoredModulePath(rel)) {
+          modules.add(resolved);
+          if (!visited.has(resolved)) {
+            queue.push(resolved);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(modules);
+}
+
 /**
  * 纯文本解析 Playbook Markdown 文件，提取 YAML Frontmatter，不执行任何业务代码。
  */
@@ -281,9 +475,11 @@ export class BuildPlanner {
       }
     }
 
-    // 5. 进行依赖闭包（uses）解析计算，自动处理环形依赖与传递依赖
+    // 5. 进行依赖闭包（uses）解析计算，自动处理环形依赖与传递依赖（支持当前清单与已链接外部包）
     const resolvedActionIds = new Set<string>();
     const queue = Array.from(initialActionIds);
+    const externalActionRoots = new Map<string, string>();
+    const externalActionEntries = new Map<string, ActionManifestEntry>();
 
     while (queue.length > 0) {
       const currentId = queue.shift()!;
@@ -291,14 +487,37 @@ export class BuildPlanner {
         continue;
       }
 
-      const entry = manifest.actions[currentId];
+      let entry = manifest.actions[currentId];
+      let entryRoot = root;
+
+      if (!entry) {
+        try {
+          const resolvedExternal = resolveActionProjectSync(currentId, root);
+          if (resolvedExternal && existsSync(resolvedExternal.projectRoot)) {
+            const externalManifest = loadManifest(resolvedExternal.projectRoot);
+            const externalEntry = externalManifest?.actions?.[resolvedExternal.actionId];
+            if (externalEntry) {
+              entry = externalEntry;
+              entryRoot = resolvedExternal.projectRoot;
+            }
+          }
+        } catch {
+          // 忽略
+        }
+      }
+
       if (!entry) {
         throw new PlannerError(
-          `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest`,
+          `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`,
           "MISSING_DEPENDENCY"
         );
       }
 
+      if (entryRoot !== root) {
+        externalActionRoots.set(currentId, entryRoot);
+        externalActionEntries.set(currentId, entry);
+      }
+
       resolvedActionIds.add(currentId);
 
       if (entry.uses && Array.isArray(entry.uses)) {
@@ -321,8 +540,15 @@ export class BuildPlanner {
     // 7. 构造 Action 依赖结构
     const actionDependencies: ActionDependency[] = [];
     for (const actId of resolvedActionIds) {
-      const entry = manifest.actions[actId];
-      const resolvedPath = resolve(root, entry.entry);
+      const entry = manifest.actions[actId] || externalActionEntries.get(actId);
+      const entryRoot = externalActionRoots.get(actId) || root;
+      if (!entry) {
+        throw new PlannerError(
+          `Action '${actId}' entry not found`,
+          "ENTRY_FILE_NOT_FOUND"
+        );
+      }
+      const resolvedPath = resolve(entryRoot, entry.entry);
       if (!existsSync(resolvedPath)) {
         throw new PlannerError(
           `Action '${actId}' entry file not found on disk: ${entry.entry}`,
@@ -345,6 +571,58 @@ export class BuildPlanner {
     // 8. 构造模块与资产依赖结构
     const modulesAndAssets: AssetDependency[] = [];
     const assetPathSet = new Set<string>();
+    const modulePathSet = new Set<string>();
+    const actionPathSet = new Set(actionDependencies.map((a) => a.resolvedPath));
+
+    // 静态递归追踪 Action 源码引用的本地模块代码（如 lib/、辅助工具等）
+    const rootActionsMap = new Map<string, string[]>();
+    for (const act of actionDependencies) {
+      const actRoot = externalActionRoots.get(act.id) || root;
+      if (!rootActionsMap.has(actRoot)) {
+        rootActionsMap.set(actRoot, []);
+      }
+      rootActionsMap.get(actRoot)!.push(act.resolvedPath);
+    }
+
+    for (const [actRoot, files] of rootActionsMap) {
+      const tracedModulePaths = traceLocalModuleDependencies(files, actRoot);
+      for (const modPath of tracedModulePaths) {
+        if (!actionPathSet.has(modPath)) {
+          const rel = relative(actRoot, modPath).replace(/\\/g, "/");
+          if (!modulePathSet.has(rel) && !isIgnoredModulePath(rel)) {
+            modulePathSet.add(rel);
+            modulesAndAssets.push({
+              path: rel,
+              resolvedPath: modPath,
+              type: "module",
+            });
+          }
+        }
+      }
+    }
+
+    // 若未显式过滤 Action 与 Playbook（全量构建模式），且存在根目录 lib 目录，自动全量扫描 lib 源码
+    const isSelective =
+      Boolean(options?.actions && options.actions.length > 0) ||
+      Boolean(options?.playbooks && options.playbooks.length > 0);
+
+    if (!isSelective) {
+      const defaultLibDir = join(root, "lib");
+      if (existsSync(defaultLibDir)) {
+        const libFiles = walkDirectory(defaultLibDir);
+        for (const file of libFiles) {
+          const rel = relative(root, file).replace(/\\/g, "/");
+          if (!isIgnoredModulePath(rel) && !actionPathSet.has(file) && !modulePathSet.has(rel)) {
+            modulePathSet.add(rel);
+            modulesAndAssets.push({
+              path: rel,
+              resolvedPath: file,
+              type: "module",
+            });
+          }
+        }
+      }
+    }
 
     // 清单声明资产
     if (manifest.assets && Array.isArray(manifest.assets)) {

package/src/types.ts

@@ -231,6 +231,10 @@ export interface SkillExporterOptions {
   config?: ProjectConfig;
   /** 预置的声明式清单（可选） */
   manifest?: ActionDockManifest;
+  /** 是否跳过生成 SKILL.md（多包聚合时避免子包重复生成，对外保持唯一定义） */
+  skipSkillMd?: boolean;
+  /** 显式指定的已有 SKILL.md 文件路径（若提供或存在则直接使用，不再动态生成） */
+  skillMdPath?: string;
 }
 
 /**
@@ -259,4 +263,75 @@ export interface SkillExportResult {
   playbooks: string[];
   /** 导出的文件相对路径清单 */
   files: string[];
+  /** 若复用了已有的 SKILL.md 文件，返回该文件的绝对路径 */
+  usedExistingSkillMd?: string;
 }
+
+/**
+ * 批量 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 套件导出选项。
+ */
+export interface CompositeSkillExportOptions {
+  /** 复合技能套件名称 */
+  bundleName: string;
+  /** 参与聚合的项目根目录绝对路径列表 */
+  projectRoots: string[];
+  /** 复合套件输出目标目录（默认输出至 dist 目录） */
+  outDir?: string;
+  /** 复合技能描述信息 */
+  description?: string;
+  /** 是否执行归档压缩，亦可直接指定归档格式 */
+  archive?: boolean | ArchiveFormat;
+  /** 归档压缩格式（zip 或 tar.gz） */
+  archiveFormat?: ArchiveFormat;
+  /** 工作区根目录（用于检索工作区现有的 SKILL.md 等资产，默认基于 cwd 与项目目录推导） */
+  workspaceRoot?: string;
+  /** 显式指定的已有 SKILL.md 文件路径（若存在则直接使用，不再动态生成） */
+  skillMdPath?: string;
+}
+
+/**
+ * 复合 Skill 套件导出结果。
+ */
+export interface CompositeSkillExportResult {
+  /** 复合技能套件名称 */
+  bundleName: string;
+  /** 生成的复合 Skill 目录绝对路径 */
+  skillDir: string;
+  /** 生成的归档文件绝对路径（若开启压缩） */
+  archivePath?: string;
+  /** 包含的 Package 数量 */
+  packagesCount: number;
+  /** 包含的总 Action 数量 */
+  actionsCount: number;
+  /** 包含的总 Playbook 数量 */
+  playbooksCount: number;
+  /** 各包的摘要明细 */
+  packages: Array<{ packageId: string; actions: string[]; playbooks: string[] }>;
+  /** 生成的文件清单 */
+  files: string[];
+  /** 若复用了已有的 SKILL.md 文件，返回该文件的绝对路径 */
+  usedExistingSkillMd?: string;
+}
+