@actiondock/builder 2.13.0 → 2.15.0

package/dist/derived-graph.d.ts

@@ -0,0 +1,4 @@
+import { type ActionDockManifest, type PlaybookSourceManifest } from "@actiondock/core/project";
+import { type PackageGraph } from "@actiondock/core/graph";
+/** 仅从共享包集合派生有效清单图，不修改调用方图或重新发现外部包。 */
+export declare function deriveEffectivePackageGraph(baseGraph: PackageGraph, root: string, effectiveManifest?: ActionDockManifest | PlaybookSourceManifest): PackageGraph;

package/dist/derived-graph.js

@@ -0,0 +1,30 @@
+import { resolve } from "node:path";
+import { computeManifestDigest } from "@actiondock/core/project";
+import { PackageGraphBuilder } from "@actiondock/core/graph";
+import { BuilderError } from "./errors.js";
+/** 仅从共享包集合派生有效清单图，不修改调用方图或重新发现外部包。 */
+export function deriveEffectivePackageGraph(baseGraph, root, effectiveManifest) {
+    const packages = Array.from(baseGraph.packages.values());
+    const target = packages.find((pkg) => resolve(pkg.root) === resolve(root));
+    if (!target) {
+        throw new BuilderError(`Project root '${root}' not found in provided packageGraph.`, "PACKAGE_NOT_FOUND");
+    }
+    if (!effectiveManifest)
+        return baseGraph;
+    if (effectiveManifest.id !== target.packageId) {
+        throw new BuilderError(`Cannot change package identity from '${target.packageId}' to '${effectiveManifest.id}' in shared package graph.`, "CANNOT_CHANGE_PACKAGE_IDENTITY");
+    }
+    // 合并配置可能仅创建等价对象；相同声明继续复用共享图。
+    if (computeManifestDigest(effectiveManifest) === target.manifestDigest)
+        return baseGraph;
+    return new PackageGraphBuilder({
+        packages: packages.map((pkg) => ({
+            id: pkg.packageId,
+            root: pkg.root,
+            manifest: pkg === target ? effectiveManifest : pkg.manifest,
+            isCurrentProject: pkg === target,
+        })),
+        root: target.root,
+        validateDependencies: true,
+    }).buildSync();
+}

package/dist/entry-generators.d.ts

@@ -8,8 +8,15 @@ import type { SelectionPlan } from "./types.js";
  *   按需加载业务实现；跨包外部 Action 不混入本包源码，依赖调用继续经 Host 路由；
  * - 入口路径以产物包根目录为基准（import.meta.dirname），不依赖调用者当前工作目录。
  */
-export declare function generateNodeHostEntrySource(plan: SelectionPlan): string;
+export declare function generateNodeHostEntrySource(plan: SelectionPlan | undefined, options?: {
+    localPackages: Array<{
+        packageId: string;
+        relativeRoot: string;
+    }>;
+}): string;
 /**
  * 生成轻量监督父进程脚本源码（负责参数解析、诊断日志限流、退出码管理与标准输出隔离）。
  */
-export declare function generateNodeSupervisorEntrySource(plan: SelectionPlan): string;
+export declare function generateNodeSupervisorEntrySource(plan: Pick<SelectionPlan, "packageId" | "version" | "description">, options?: {
+    multiPackage?: boolean;
+}): string;

package/dist/entry-generators.js

@@ -1,4 +1,5 @@
 import { STANDALONE_ASYNC_UNSUPPORTED } from "@actiondock/core";
+import { BuilderError } from "./errors.js";
 import { serializePlanManifest } from "./manifest.js";
 /**
  * 生成 Host 子进程入口脚本源码（负责运行 ActionDockHost，通过 Node IPC 暴露 Target）。
@@ -9,25 +10,49 @@ import { serializePlanManifest } from "./manifest.js";
  *   按需加载业务实现；跨包外部 Action 不混入本包源码，依赖调用继续经 Host 路由；
  * - 入口路径以产物包根目录为基准（import.meta.dirname），不依赖调用者当前工作目录。
  */
-export function generateNodeHostEntrySource(plan) {
+export function generateNodeHostEntrySource(plan, options) {
     // 复用 SelectionPlan 的清单序列化单一事实源（含包内动作筛选与 Schema 字段映射），
     // 不单独复制一份 Schema 字段映射
-    const manifestActions = serializePlanManifest(plan).actions;
+    if (!options && !plan)
+        throw new BuilderError("A plan or explicit local packages are required for the Host entry");
+    const manifestActions = options ? undefined : serializePlanManifest(plan).actions;
+    const packageEntries = options
+        ? options.localPackages.map((pkg) => `{
+      packageRoot: resolve(packageRoot, ${JSON.stringify(pkg.relativeRoot)}),
+      projectConfig: loadLocalConfig(${JSON.stringify(pkg.packageId)}, ${JSON.stringify(pkg.relativeRoot)}),
+      dataDir,
+      configOverrides,
+    }`).join(",\n")
+        : `{
+      packageRoot, dataDir, configOverrides,
+      projectConfig: ${JSON.stringify({
+            id: plan.packageId, name: plan.packageName, version: plan.version,
+            description: plan.description || "", config: plan.configDefs || {}, actions: manifestActions,
+        })},
+    }`;
     return `#!/usr/bin/env node
 // AUTO-GENERATED HOST ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
-import "@actiondock/core/warning";
+import { resolve } from "node:path";
 import {
+  loadProjectConfig,
   createActionDock,
   createNodePlatform,
+  validateLocalSkillPackages,
 } from "@actiondock/core";
 import { serveParentIpc } from "@actiondock/core/server";
 
 // 产物包根目录：以入口文件自身位置为基准，不依赖调用者当前工作目录
 const packageRoot = import.meta.dirname;
+${options ? `function loadLocalConfig(expectedId, relativeRoot) {
+  const config = loadProjectConfig(resolve(packageRoot, relativeRoot));
+  if (config.id !== expectedId) throw new Error("Local package ID mismatch: expected " + expectedId + ", found " + config.id);
+  return config;
+}` : ""}
 
 let dataDir;
 const configOverrides = {};
 const args = process.argv.slice(2);
+const commandArgs = [];
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--data-dir" && i + 1 < args.length) {
     dataDir = args[++i];
@@ -41,33 +66,28 @@ for (let i = 0; i < args.length; i++) {
     const raw = args[i].slice(9);
     const [k, ...v] = raw.split("=");
     if (k) configOverrides[k] = v.join("=");
+  } else {
+    commandArgs.push(args[i]);
   }
 }
 
 // 复用既有命令分发结果确定访问性质：发现命令（list/describe/show）为旁观初始化，
 // 不创建数据库、不取目录锁、不收割遗留运行记录；执行与写入命令为持有者初始化
-const command = args.find((a) => !a.startsWith("-")) || "";
+const command = commandArgs.find((a) => !a.startsWith("-")) || "";
 const DISCOVERY_COMMANDS = new Set(["list", "describe", "show"]);
 const recoverOrphans = DISCOVERY_COMMANDS.has(command) ? false : undefined;
 
+const localPackages = [${packageEntries}];
+validateLocalSkillPackages(localPackages.map((p) => ({
+  packageId: p.projectConfig.id,
+  packageRoot: p.packageRoot,
+  projectConfig: p.projectConfig,
+})));
+
 const service = await createActionDock({
   dataDir,
   ...(recoverOrphans === false ? { recoverOrphans: false } : {}),
-  packages: [
-    {
-      packageRoot,
-      dataDir,
-      configOverrides,
-      projectConfig: {
-        id: ${JSON.stringify(plan.packageId)},
-        name: ${JSON.stringify(plan.packageName)},
-        version: ${JSON.stringify(plan.version)},
-        description: ${JSON.stringify(plan.description || "")},
-        config: ${JSON.stringify(plan.configDefs || {})},
-        actions: ${JSON.stringify(manifestActions)},
-      },
-    },
-  ],
+  packages: localPackages,
   platform: createNodePlatform({ dataDir }),
   autoLoadCurrentProject: false,
   scanLinkedPackages: false,
@@ -78,10 +98,9 @@ await serveParentIpc(service);
 /**
  * 生成轻量监督父进程脚本源码（负责参数解析、诊断日志限流、退出码管理与标准输出隔离）。
  */
-export function generateNodeSupervisorEntrySource(plan) {
+export function generateNodeSupervisorEntrySource(plan, options) {
     return `#!/usr/bin/env node
 // AUTO-GENERATED SUPERVISOR ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
-import "@actiondock/core/warning";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
 import {
@@ -143,8 +162,8 @@ if (argv.includes("-h") || argv.includes("--help") || argv[0] === "help") {
   console.log("  <cmd> run <id> [--input '<json>']           Execute action with JSON input");
   console.log("  <cmd> run <id> [--stdin-field <field>] [-- <assignments...>]");
   console.log("                                             Bind raw stdin text to an input field");
-  console.log("  <cmd> config list/get/set/delete            Manage package configuration");
-  console.log("  <cmd> state list/get/set/delete             Manage shared state store");
+  ${options?.multiPackage ? 'console.log("  Multi-package config/state management is unavailable; use --config overrides.");'
+        : 'console.log("  <cmd> config list/get/set/delete            Manage package configuration");\n  console.log("  <cmd> state list/get/set/delete             Manage shared state store");'}
   console.log("\\nGlobal options:");
   console.log("  --data-dir <path>                           Custom runtime database directory");
   console.log("  --config <KEY=val>                          Temporary config override");
@@ -153,8 +172,7 @@ if (argv.includes("-h") || argv.includes("--help") || argv[0] === "help") {
 
 // 3. 建立物理隔离监督边界，启动运行 ActionDockHost 的独立子进程
 const hostScript = join(import.meta.dirname, "entry-host.js");
-const warningFlags = process.env.ACTIONDOCK_SILENCE_WARNINGS !== "0" ? ["--no-warnings=ExperimentalWarning"] : [];
-const child = spawn(process.execPath, [...warningFlags, hostScript, ...argv], {
+const child = spawn(process.execPath, [hostScript, ...argv], {
   cwd: process.cwd(),
   env: process.env,
   stdio: ["pipe", "pipe", "pipe", "ipc"],
@@ -194,6 +212,7 @@ const dispatcher = new StandaloneDispatcher({
   version: METADATA.version,
   description: METADATA.description,
   service,
+  multiPackage: ${JSON.stringify(options?.multiPackage === true)},
 });
 
 try {

package/dist/export-composite.d.ts

@@ -3,7 +3,7 @@ import type { CompositeSkillExportOptions, CompositeSkillExportResult, SkillExpo
  * 复合套件导出装配层。
  *
  * 职责：将多个包聚合为一个统一的复合技能目录（mini-workspace 形态），
- * 聚合各子包依赖生成复合根 package.json，并生成或复用复合 SKILL.md。
+ * 保留各子包 npm 依赖并生成复合根 package.json，并生成或复用复合 SKILL.md。
  */
 /** 子包导出回调：由 SkillExporter 注入自身导出能力，避免模块间循环依赖 */
 export type SubpackageExporter = (options: SkillExporterOptions) => Promise<SkillExportResult>;

package/dist/export-composite.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { loadProjectConfig, } from "@actiondock/core";
 import { getPackageSlug, loadManifest, loadPlaybooks, } from "@actiondock/core/project";
@@ -6,9 +6,10 @@ import { generateCompositeSkillMd, RUNTIME_REFERENCE_REL_PATH } from "./skill/in
 import { writeRuntimeReferenceFile } from "./export-source.js";
 import { BuilderError } from "./errors.js";
 import { collectRelativeFiles, getInternalDependencyVersion, replaceDirAtomic } from "./fs-utils.js";
-import { allocatePackageDirName, sanitizeExportDependencies } from "./manifest.js";
-import { SelectionPlanner } from "./planner.js";
-import { findExistingCompositeSkillMd, resolveCustomSkillDeclaration, } from "./skill-md.js";
+import { allocatePackageDirName } from "./manifest.js";
+import { createSourcePackageGraph } from "./source-graph.js";
+import { generateNodeHostEntrySource, generateNodeSupervisorEntrySource } from "./entry-generators.js";
+import { findExistingCompositeSkillMd, resolveCustomSkillDeclaration, appendLocalExecutionContract, } from "./skill-md.js";
 import { createArchive, resolveArchiveFormat } from "./export-archive.js";
 /**
  * 执行复合模式导出：将多个包聚合为一个统一的复合技能目录。
@@ -38,30 +39,36 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         mkdirSync(packagesDestDir, { recursive: true });
     }
     const packageInfos = [];
+    const localPackages = [];
     const packageSummaries = [];
     let existingSkillPath;
     try {
-        // 收集并展开所有包含在依赖闭包中的外部项目根目录，确保 bundle 整包携带齐全部依赖
-        const effectiveRoots = new Set();
-        for (const r of options.projectRoots) {
-            effectiveRoots.add(resolve(r));
-            if (!skillMdOnly) {
-                try {
-                    const p = SelectionPlanner.plan({ projectRoot: r });
-                    if (p.externalProjectRoots) {
-                        for (const extRoot of p.externalProjectRoots) {
-                            effectiveRoots.add(resolve(extRoot));
-                        }
+        const packageGraph = skillMdOnly ? undefined : options.packageGraph ?? createSourcePackageGraph(options.projectRoots);
+        const effectiveRoots = skillMdOnly
+            ? new Set(options.projectRoots.map((root) => resolve(root)))
+            : new Set(Array.from(packageGraph.packages.values(), (pkg) => pkg.root));
+        const usedDirNames = new Set();
+        const usedNpmNames = new Set();
+        const sourceNpmNames = new Map();
+        if (!skillMdOnly) {
+            // 先保留全部真实 npm 名，缺省名不得覆盖尚未导出的兄弟包身份。
+            for (const projectRoot of effectiveRoots) {
+                const pkgJsonPath = join(projectRoot, "package.json");
+                const name = existsSync(pkgJsonPath) ? readWorkspacePackageName(pkgJsonPath) : undefined;
+                sourceNpmNames.set(projectRoot, name);
+                if (name) {
+                    if (usedNpmNames.has(name)) {
+                        throw new BuilderError(`Duplicate npm workspace package name '${name}'.`, "DUPLICATE_WORKSPACE_PACKAGE_NAME");
                     }
-                }
-                catch {
-                    // 忽略规划解析异常，由主循环处理
+                    usedNpmNames.add(name);
                 }
             }
         }
-        const usedDirNames = new Set();
         for (const projectRoot of effectiveRoots) {
-            const config = loadProjectConfig(projectRoot);
+            const graphManifest = packageGraph && Array.from(packageGraph.packages.values()).find((p) => resolve(p.root) === resolve(projectRoot))?.manifest;
+            const config = graphManifest
+                ? { ...graphManifest, name: graphManifest.name || graphManifest.id, version: graphManifest.version || "0.1.0" }
+                : loadProjectConfig(projectRoot);
             let pkgSlug;
             if (skillMdOnly) {
                 // 就地生成：规程链接基于工作区实际子目录名
@@ -71,34 +78,49 @@ export async function exportCompositeImpl(options, exportSubpackage) {
                 // 目录名分配统一复用 manifest 的 allocatePackageDirName，回退后仍冲突会追加数字后缀
                 pkgSlug = allocatePackageDirName(usedDirNames, config.id);
             }
+            let defaultPackageName;
+            if (!skillMdOnly && !sourceNpmNames.get(projectRoot)) {
+                const baseName = normalizeNpmPackageName(pkgSlug);
+                let candidate = baseName;
+                let suffix = 2;
+                while (usedNpmNames.has(candidate))
+                    candidate = `${baseName}-${suffix++}`;
+                defaultPackageName = candidate;
+                usedNpmNames.add(candidate);
+            }
             let actionIds;
-            let playbookIds;
+            let playbooks;
             let manifest;
             if (skillMdOnly) {
                 // 仅生成 SKILL.md：直接读取清单获取 Action 契约描述，不拷贝子包产物
                 manifest = loadManifest(projectRoot);
                 actionIds = manifest?.actions ? Object.keys(manifest.actions) : [];
-                playbookIds = Array.from(loadPlaybooks(projectRoot, config.playbooksDir).keys());
+                playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
             }
             else {
                 const destPkgDir = join(packagesDestDir, pkgSlug);
                 const singleExport = await exportSubpackage({
                     projectRoot,
+                    packageGraph,
+                    config,
+                    manifest: graphManifest || undefined,
                     outDir: destPkgDir,
                     archive: false,
                     skipSkillMd: true,
                     mode: "source",
                     _isSubpackage: true,
+                    defaultPackageName,
                 });
-                manifest = loadManifest(destPkgDir) || loadManifest(projectRoot);
+                manifest = loadManifest(destPkgDir);
                 actionIds = singleExport.actions;
-                playbookIds = singleExport.playbooks;
+                playbooks = loadPlaybooks(destPkgDir, manifest?.playbooksDir, manifest);
             }
-            const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+            const playbookIds = Array.from(playbooks.keys());
             const actionEntries = actionIds.map((actId) => ({
                 id: actId,
                 description: manifest?.actions?.[actId]?.description,
             }));
+            localPackages.push({ packageId: config.id, relativeRoot: `packages/${pkgSlug}` });
             packageInfos.push({
                 config,
                 actions: actionEntries,
@@ -118,6 +140,7 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         const compositeSkillMd = generateCompositeSkillMd(options.bundleName, description, packageInfos, {
             customSections: customDeclaration?.sections,
             packagesBaseDir: skillMdOnly ? "." : "packages",
+            invocationStyle: skillMdOnly ? "global-ad" : "source-ad",
         });
         if (skillMdOnly) {
             // 就地仅重生成 SKILL.md：始终重新生成（忽略已有 SKILL.md 复用逻辑），不产出完整套件目录
@@ -153,9 +176,10 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         }
         if (existingSkillPath) {
             const destSkillMdPath = join(stagingDir, "SKILL.md");
-            if (resolve(existingSkillPath) !== resolve(destSkillMdPath)) {
-                copyFileSync(existingSkillPath, destSkillMdPath);
-            }
+            writeFileSync(destSkillMdPath, readFileSync(existingSkillPath, "utf-8"), "utf-8");
+            appendLocalExecutionContract(destSkillMdPath, packageInfos.map((p) => ({
+                packageId: p.config.id, actions: p.actions,
+            })));
         }
         else {
             writeFileSync(join(stagingDir, "SKILL.md"), compositeSkillMd, "utf-8");
@@ -164,11 +188,19 @@ export async function exportCompositeImpl(options, exportSubpackage) {
                 dependencyStepLabel: "安装复合技能聚合依赖",
                 relinkStepLabel: "完成安装后重新链接复合技能",
                 compositeLinkNote: true,
-                invocationStyle: "global-ad",
+                invocationStyle: "source-ad",
+                entryRelPath: 'node "<skill_root>/entry.mjs"',
             });
         }
-        // 聚合所有子包依赖生成复合根目录 package.json
-        writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options);
+        if (packagesDestDir) {
+            assertUniqueWorkspacePackageNames(packagesDestDir);
+        }
+        // npm workspaces 保留各包依赖约束，根目录仅声明入口运行依赖。
+        writeCompositePkgJson(stagingDir, bundleSlug, options);
+        const entryMetadata = { packageId: options.bundleName, version: "0.1.0", description };
+        writeFileSync(join(stagingDir, "entry.mjs"), generateNodeSupervisorEntrySource(entryMetadata, { multiPackage: true }), "utf-8");
+        // Host 生成仍复用单包生成器，但源码包元数据只从自身相对路径读取。
+        writeFileSync(join(stagingDir, "entry-host.js"), generateNodeHostEntrySource(undefined, { localPackages }), "utf-8");
         // 原子替换目标复合技能目录
         await replaceDirAtomic(stagingDir, targetSkillDir);
     }
@@ -195,35 +227,77 @@ export async function exportCompositeImpl(options, exportSubpackage) {
     };
 }
 /**
- * 复合套件聚合各子包依赖并生成复合根目录 package.json。
- * 依赖清洗统一复用 manifest 的 sanitizeExportDependencies 单一入口，与单包导出口径一致。
+ * 复合根目录声明入口运行依赖，业务依赖保留在各工作区包中，由 npm 安装解析。
  */
-function writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options) {
-    const aggregatedDeps = {
+function writeCompositePkgJson(stagingDir, bundleSlug, options) {
+    // 子包保留各自依赖约束，由 npm workspaces 正常安装与多版本解析，不聚合覆盖。
+    const runtimeDeps = {
+        "@actiondock/core": getInternalDependencyVersion(),
         "@actiondock/sdk": getInternalDependencyVersion(),
     };
-    for (const info of packageInfos) {
-        const pkgJsonPath = join(packagesDestDir, info.packageDir, "package.json");
-        if (existsSync(pkgJsonPath)) {
-            try {
-                const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
-                Object.assign(aggregatedDeps, sanitizeExportDependencies(join(packagesDestDir, info.packageDir), parsed.dependencies, "exported skill packages", false));
-            }
-            catch (err) {
-                if (err instanceof BuilderError)
-                    throw err;
-                // 复合导出缺依赖影响面大：读文件与解析失败必须显式报错，严禁静默吞掉导致聚合依赖缺失
-                throw new BuilderError(`Failed to read or parse package.json of exported subpackage '${info.packageDir}' (${pkgJsonPath}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
     const compositePkg = {
         name: `${bundleSlug}-composite-skill`,
         version: "0.1.0",
         description: options.description || `Composite Skill suite: ${options.bundleName}`,
         type: "module",
         workspaces: ["packages/*"],
-        dependencies: aggregatedDeps,
+        dependencies: runtimeDeps,
     };
     writeFileSync(join(stagingDir, "package.json"), JSON.stringify(compositePkg, null, 2) + "\n", "utf-8");
 }
+/**
+ * 规范化包目录标识为合法 npm 包名（小写字母、数字、连字符、下划线与点号）。
+ */
+function normalizeNpmPackageName(name) {
+    const normalized = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-_.]/g, "-")
+        .replace(/^[._]+/, "");
+    return normalized || "package";
+}
+/** 工作区清单读取失败必须透明报告，只有缺省 name 才允许自动分配。 */
+function readWorkspacePackageName(path) {
+    const raw = readFileSync(path, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new BuilderError(`Invalid package.json at '${path}': ${String(err)}`, "INVALID_PACKAGE_JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new BuilderError(`Invalid package.json at '${path}': expected an object.`, "INVALID_PACKAGE_JSON");
+    }
+    const name = parsed.name;
+    if (name === undefined || name === "")
+        return undefined;
+    if (typeof name !== "string" || !name.trim() || name !== name.trim()) {
+        throw new BuilderError(`Invalid npm workspace package name at '${path}'.`, "INVALID_PACKAGE_JSON");
+    }
+    return name;
+}
+/**
+ * 校验复合暂存目录中所有子包导出的 package.json.name 唯一性。
+ * 若已有真实 npm 名确实冲突，在发布产物前明确抛出 BuilderError。
+ */
+function assertUniqueWorkspacePackageNames(packagesDir) {
+    const seenNames = new Map();
+    const entries = readdirSync(packagesDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pkgJsonPath = join(packagesDir, entry.name, "package.json");
+        if (!existsSync(pkgJsonPath))
+            continue;
+        const name = readWorkspacePackageName(pkgJsonPath);
+        if (!name) {
+            throw new BuilderError(`Missing npm workspace package name at '${pkgJsonPath}'.`, "INVALID_PACKAGE_JSON");
+        }
+        const existing = seenNames.get(name);
+        if (existing) {
+            throw new BuilderError(`Duplicate npm workspace package name '${name}' found in packages/${existing} and packages/${entry.name}.`, "DUPLICATE_WORKSPACE_PACKAGE_NAME");
+        }
+        seenNames.set(name, entry.name);
+    }
+}

package/dist/export-source.js

@@ -1,8 +1,11 @@
 import { copyFileSync, existsSync, readFileSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { mkdirSync } from "node:fs";
+import { generateNodeHostEntrySource, generateNodeSupervisorEntrySource } from "./entry-generators.js";
+import { appendLocalExecutionContract } from "./skill-md.js";
 import { generateSourceSkillMd } from "./skill/index.js";
 import { RUNTIME_REFERENCE_REL_PATH, renderRuntimeReferenceContent, } from "./skill/templates.js";
+import { loadManifest } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 import { getInternalDependencyVersion } from "./fs-utils.js";
 import { assertValidManifestActionIds, sanitizeExportDependencies, serializePlanManifest, } from "./manifest.js";
@@ -21,18 +24,24 @@ 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) => !a.isExternal), plan.playbooks));
     // 导出精简后的 actiondock.json 项目配置（项目元数据与清单的单一事实源）
     const exportedConfig = serializePlanManifest(plan, {
         omitEmptyConfig: true,
         includeDirs: { actionsDir, playbooksDir },
     });
+    const originalManifest = options.manifest || loadManifest(root);
+    if (originalManifest?.dependencies)
+        exportedConfig.dependencies = originalManifest.dependencies;
+    const packageUses = originalManifest?.uses;
+    if (packageUses)
+        exportedConfig.uses = packageUses;
     if (exportedConfig.actions && typeof exportedConfig.actions === "object") {
         assertValidManifestActionIds(exportedConfig.actions);
     }
     writeFileSync(join(skillDir, "actiondock.json"), JSON.stringify(exportedConfig, null, 2) + "\n", "utf-8");
     // 导出 package.json
-    writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug);
+    writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug, options);
     // 拷贝 tsconfig.json（若存在）
     const tsconfigPath = join(root, "tsconfig.json");
     if (existsSync(tsconfigPath)) {
@@ -42,13 +51,27 @@ export function stageSourceSkill(root, skillDir, plan, options, pkgSlug) {
     copyPlanEntries(skillDir, plan, {
         playbookRelPath: (pb) => join(playbooksDir, basename(pb.filePath)),
     });
+    if (!options._isSubpackage) {
+        for (const name of ["entry.mjs", "entry-host.js"]) {
+            if (existsSync(join(skillDir, name))) {
+                throw new BuilderError(`Source Skill entry conflict: '${name}' is reserved for the local runtime entry; refusing to overwrite a declared file.`, "SOURCE_ENTRY_CONFLICT");
+            }
+        }
+        writeFileSync(join(skillDir, "entry.mjs"), generateNodeSupervisorEntrySource(plan), "utf-8");
+        writeFileSync(join(skillDir, "entry-host.js"), generateNodeHostEntrySource(undefined, {
+            localPackages: [{ packageId: plan.packageId, relativeRoot: "." }],
+        }), "utf-8");
+        if (usedExistingSkillMd)
+            appendLocalExecutionContract(join(skillDir, "SKILL.md"), [plan]);
+    }
     // 声明资产拷贝完成后再物化默认运行参考文件：仅在使用自动模板时生成；
     // 与项目声明资产同路径冲突时报错不覆盖（拷贝在前，冲突检测能真实命中）
     if (usedExistingSkillMd === undefined && !options.skipSkillMd) {
         writeRuntimeReferenceFile(skillDir, {
             dependencyStepLabel: "安装技能源码依赖",
             relinkStepLabel: "完成安装后重新链接本技能",
-            invocationStyle: "global-ad",
+            invocationStyle: "source-ad",
+            entryRelPath: 'node "<skill_root>/entry.mjs"',
         });
     }
     return usedExistingSkillMd;
@@ -65,15 +88,16 @@ export function writeRuntimeReferenceFile(destDir, options) {
     mkdirSync(dirname(referencePath), { recursive: true });
     writeFileSync(referencePath, renderRuntimeReferenceContent(options), "utf-8");
 }
-function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug) {
+function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug, options) {
     let exportedPkg;
+    const fallbackName = options?.defaultPackageName || pkgSlug;
     const projectPkgPath = join(root, "package.json");
     if (existsSync(projectPkgPath)) {
         try {
             const raw = readFileSync(projectPkgPath, "utf-8");
             const parsed = JSON.parse(raw);
             exportedPkg = {
-                name: parsed.name || pkgSlug,
+                name: parsed.name || fallbackName,
                 version: plan.version || parsed.version || "0.1.0",
                 description: plan.description || parsed.description,
                 type: "module",
@@ -84,12 +108,13 @@ function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug) {
             if (err instanceof BuilderError) {
                 throw err;
             }
-            exportedPkg = fallbackSkillPkg(plan, pkgSlug);
+            exportedPkg = fallbackSkillPkg(plan, fallbackName);
         }
     }
     else {
-        exportedPkg = fallbackSkillPkg(plan, pkgSlug);
+        exportedPkg = fallbackSkillPkg(plan, fallbackName);
     }
+    exportedPkg.dependencies["@actiondock/core"] ??= getInternalDependencyVersion();
     writeFileSync(join(skillDir, "package.json"), JSON.stringify(exportedPkg, null, 2) + "\n", "utf-8");
 }
 /** 无 package.json 或解析失败时的兜底导出描述 */

package/dist/exporter.js

@@ -1,9 +1,11 @@
 import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { getPackageSlug } from "@actiondock/core/project";
+import { getPackageSlug, loadManifest } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 import { replaceDirAtomic } from "./fs-utils.js";
 import { collectRelativeFiles } from "./fs-utils.js";
+import { createSourcePackageGraph } from "./source-graph.js";
+import { deriveEffectivePackageGraph } from "./derived-graph.js";
 import { SelectionPlanner } from "./planner.js";
 import { isOwnAction } from "./types.js";
 import { createArchive, resolveArchiveFormat } from "./export-archive.js";
@@ -26,8 +28,35 @@ export class SkillExporter {
     async export(options) {
         const root = resolve(options.projectRoot);
         const mode = options.mode === "node" ? "node" : "source";
+        // 共享图、规划与源码清单使用同一有效声明；显式 manifest 不从磁盘继承依赖。
+        if (mode === "source" && (options.config || options.manifest)) {
+            const graphNode = options.packageGraph && Array.from(options.packageGraph.packages.values()).find((p) => resolve(p.root) === root);
+            const baseManifest = options.manifest || graphNode?.manifest || loadManifest(root) || {};
+            const manifest = {
+                ...baseManifest,
+                ...options.config,
+                ...options.manifest,
+                // 保持既有 config 元数据优先级；动作、dependencies、uses 使用有效清单声明。
+                ...Object.fromEntries([
+                    "id", "name", "version", "description", "config", "actionsDir", "playbooksDir",
+                ].map((key) => [key, options.config?.[key]]).filter(([, value]) => value !== undefined)),
+            };
+            options = {
+                ...options,
+                manifest,
+                config: { ...manifest, name: manifest.name || manifest.id, version: manifest.version || "0.1.0" },
+            };
+        }
         // 调用 SelectionPlanner 执行声明式构建规划
+        const packageGraph = mode === "source" && options.packageGraph
+            ? deriveEffectivePackageGraph(options.packageGraph, root, options.manifest)
+            : options.packageGraph ?? (mode === "source" ? createSourcePackageGraph([root], options.manifest) : undefined);
+        options = {
+            ...options,
+            packageGraph,
+        };
         const plan = SelectionPlanner.plan({
+            packageGraph,
             projectRoot: root,
             config: options.config,
             manifest: options.manifest,
@@ -39,7 +68,7 @@ export class SkillExporter {
         const defaultFolderName = `${pkgSlug}-skill`;
         const defaultSkillDir = join(root, "dist", defaultFolderName);
         const targetSkillDir = resolve(options.outDir || defaultSkillDir);
-        const hasExternalDeps = Boolean(plan.externalProjectRoots && plan.externalProjectRoots.length > 0);
+        const hasExternalDeps = Boolean((packageGraph && packageGraph.packages.size > 1) || (plan.externalProjectRoots && plan.externalProjectRoots.length > 0));
         // 单包源码导出若依赖闭包含外部包，导成 mini-workspace 形态（packages/ 下带齐依赖包），和 bundle 统一成一个交付形状
         // 该复合分支会展开全部依赖包，无法保留调用方传入的 actions/playbooks 过滤选项；
         // 静默丢弃过滤会导致产物全量导出，必须显式拒绝并给出调整指引（CLI 侧已有 roots>1 守卫，此处补齐 composite 分支守卫）
@@ -50,8 +79,9 @@ export class SkillExporter {
             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");
         }
         if (willUseComposite) {
-            const allProjectRoots = Array.from(new Set([root, ...plan.externalProjectRoots]));
+            const allProjectRoots = Array.from(new Set([root, ...Array.from(packageGraph.packages.values(), (p) => p.root)]));
             const compositeRes = await this.exportComposite({
+                packageGraph,
                 bundleName: plan.packageName || plan.packageId,
                 projectRoots: allProjectRoots,
                 outDir: targetSkillDir,