@actiondock/builder 2.14.0 → 2.16.0

package/dist/entry-generators.d.ts

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

package/dist/entry-generators.js

@@ -1,5 +1,4 @@
 import { STANDALONE_ASYNC_UNSUPPORTED } from "@actiondock/core";
-import { BuilderError } from "./errors.js";
 import { serializePlanManifest } from "./manifest.js";
 /**
  * 生成 Host 子进程入口脚本源码（负责运行 ActionDockHost，通过 Node IPC 暴露 Target）。
@@ -10,49 +9,24 @@ import { serializePlanManifest } from "./manifest.js";
  *   按需加载业务实现；跨包外部 Action 不混入本包源码，依赖调用继续经 Host 路由；
  * - 入口路径以产物包根目录为基准（import.meta.dirname），不依赖调用者当前工作目录。
  */
-export function generateNodeHostEntrySource(plan, options) {
+export function generateNodeHostEntrySource(plan) {
     // 复用 SelectionPlan 的清单序列化单一事实源（含包内动作筛选与 Schema 字段映射），
     // 不单独复制一份 Schema 字段映射
-    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,
-        })},
-    }`;
+    const manifestActions = serializePlanManifest(plan).actions;
     return `#!/usr/bin/env node
 // AUTO-GENERATED HOST ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
-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];
@@ -66,28 +40,33 @@ 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 = commandArgs.find((a) => !a.startsWith("-")) || "";
+const command = args.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: localPackages,
+  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)},
+      },
+    },
+  ],
   platform: createNodePlatform({ dataDir }),
   autoLoadCurrentProject: false,
   scanLinkedPackages: false,
@@ -98,7 +77,7 @@ await serveParentIpc(service);
 /**
  * 生成轻量监督父进程脚本源码（负责参数解析、诊断日志限流、退出码管理与标准输出隔离）。
  */
-export function generateNodeSupervisorEntrySource(plan, options) {
+export function generateNodeSupervisorEntrySource(plan) {
     return `#!/usr/bin/env node
 // AUTO-GENERATED SUPERVISOR ENTRYPOINT BY ACTIONDOCK BUILDER. DO NOT EDIT.
 import { spawn } from "node:child_process";
@@ -162,8 +141,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");
-  ${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("  <cmd> config list/get/set/delete            Manage package configuration");
+  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");
@@ -212,7 +191,6 @@ 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 形态），
- * 保留各子包 npm 依赖并生成复合根 package.json，并生成或复用复合 SKILL.md。
+ * 聚合各子包依赖生成复合根 package.json，并生成或复用复合 SKILL.md。
  */
 /** 子包导出回调：由 SkillExporter 注入自身导出能力，避免模块间循环依赖 */
 export type SubpackageExporter = (options: SkillExporterOptions) => Promise<SkillExportResult>;

package/dist/export-composite.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, 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,10 +6,9 @@ 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 } 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 { allocatePackageDirName, sanitizeExportDependencies } from "./manifest.js";
+import { SelectionPlanner } from "./planner.js";
+import { findExistingCompositeSkillMd, resolveCustomSkillDeclaration, } from "./skill-md.js";
 import { createArchive, resolveArchiveFormat } from "./export-archive.js";
 /**
  * 执行复合模式导出：将多个包聚合为一个统一的复合技能目录。
@@ -39,36 +38,30 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         mkdirSync(packagesDestDir, { recursive: true });
     }
     const packageInfos = [];
-    const localPackages = [];
     const packageSummaries = [];
     let existingSkillPath;
     try {
-        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");
+        // 收集并展开所有包含在依赖闭包中的外部项目根目录，确保 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));
+                        }
                     }
-                    usedNpmNames.add(name);
+                }
+                catch {
+                    // 忽略规划解析异常，由主循环处理
                 }
             }
         }
+        const usedDirNames = new Set();
         for (const projectRoot of effectiveRoots) {
-            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);
+            const config = loadProjectConfig(projectRoot);
             let pkgSlug;
             if (skillMdOnly) {
                 // 就地生成：规程链接基于工作区实际子目录名
@@ -78,49 +71,34 @@ 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 playbooks;
+            let playbookIds;
             let manifest;
             if (skillMdOnly) {
                 // 仅生成 SKILL.md：直接读取清单获取 Action 契约描述，不拷贝子包产物
                 manifest = loadManifest(projectRoot);
                 actionIds = manifest?.actions ? Object.keys(manifest.actions) : [];
-                playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+                playbookIds = Array.from(loadPlaybooks(projectRoot, config.playbooksDir).keys());
             }
             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);
+                manifest = loadManifest(destPkgDir) || loadManifest(projectRoot);
                 actionIds = singleExport.actions;
-                playbooks = loadPlaybooks(destPkgDir, manifest?.playbooksDir, manifest);
+                playbookIds = singleExport.playbooks;
             }
-            const playbookIds = Array.from(playbooks.keys());
+            const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
             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,
@@ -140,7 +118,6 @@ 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 复用逻辑），不产出完整套件目录
@@ -176,10 +153,9 @@ export async function exportCompositeImpl(options, exportSubpackage) {
         }
         if (existingSkillPath) {
             const destSkillMdPath = join(stagingDir, "SKILL.md");
-            writeFileSync(destSkillMdPath, readFileSync(existingSkillPath, "utf-8"), "utf-8");
-            appendLocalExecutionContract(destSkillMdPath, packageInfos.map((p) => ({
-                packageId: p.config.id, actions: p.actions,
-            })));
+            if (resolve(existingSkillPath) !== resolve(destSkillMdPath)) {
+                copyFileSync(existingSkillPath, destSkillMdPath);
+            }
         }
         else {
             writeFileSync(join(stagingDir, "SKILL.md"), compositeSkillMd, "utf-8");
@@ -188,19 +164,11 @@ export async function exportCompositeImpl(options, exportSubpackage) {
                 dependencyStepLabel: "安装复合技能聚合依赖",
                 relinkStepLabel: "完成安装后重新链接复合技能",
                 compositeLinkNote: true,
-                invocationStyle: "source-ad",
-                entryRelPath: 'node "<skill_root>/entry.mjs"',
+                invocationStyle: "global-ad",
             });
         }
-        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");
+        // 聚合所有子包依赖生成复合根目录 package.json
+        writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options);
         // 原子替换目标复合技能目录
         await replaceDirAtomic(stagingDir, targetSkillDir);
     }
@@ -227,77 +195,35 @@ export async function exportCompositeImpl(options, exportSubpackage) {
     };
 }
 /**
- * 复合根目录声明入口运行依赖，业务依赖保留在各工作区包中，由 npm 安装解析。
+ * 复合套件聚合各子包依赖并生成复合根目录 package.json。
+ * 依赖清洗统一复用 manifest 的 sanitizeExportDependencies 单一入口，与单包导出口径一致。
  */
-function writeCompositePkgJson(stagingDir, bundleSlug, options) {
-    // 子包保留各自依赖约束，由 npm workspaces 正常安装与多版本解析，不聚合覆盖。
-    const runtimeDeps = {
-        "@actiondock/core": getInternalDependencyVersion(),
+function writeCompositePkgJson(stagingDir, packagesDestDir, packageInfos, bundleSlug, options) {
+    const aggregatedDeps = {
         "@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: runtimeDeps,
+        dependencies: aggregatedDeps,
     };
     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,11 +1,8 @@
 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";
@@ -24,24 +21,18 @@ 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.filter((a) => !a.isExternal), plan.playbooks));
+    const usedExistingSkillMd = writeSkillMd(root, skillDir, { skipSkillMd: options.skipSkillMd, skillMdPath: options.skillMdPath, pkgSlug }, () => generateSourceSkillMd(configForTemplates, plan.actions, 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, options);
+    writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug);
     // 拷贝 tsconfig.json（若存在）
     const tsconfigPath = join(root, "tsconfig.json");
     if (existsSync(tsconfigPath)) {
@@ -51,27 +42,13 @@ 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: "source-ad",
-            entryRelPath: 'node "<skill_root>/entry.mjs"',
+            invocationStyle: "global-ad",
         });
     }
     return usedExistingSkillMd;
@@ -88,16 +65,15 @@ export function writeRuntimeReferenceFile(destDir, options) {
     mkdirSync(dirname(referencePath), { recursive: true });
     writeFileSync(referencePath, renderRuntimeReferenceContent(options), "utf-8");
 }
-function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug, options) {
+function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug) {
     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 || fallbackName,
+                name: parsed.name || pkgSlug,
                 version: plan.version || parsed.version || "0.1.0",
                 description: plan.description || parsed.description,
                 type: "module",
@@ -108,13 +84,12 @@ function writeSourceSkillPkgJson(root, skillDir, plan, pkgSlug, options) {
             if (err instanceof BuilderError) {
                 throw err;
             }
-            exportedPkg = fallbackSkillPkg(plan, fallbackName);
+            exportedPkg = fallbackSkillPkg(plan, pkgSlug);
         }
     }
     else {
-        exportedPkg = fallbackSkillPkg(plan, fallbackName);
+        exportedPkg = fallbackSkillPkg(plan, pkgSlug);
     }
-    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,11 +1,9 @@
 import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { getPackageSlug, loadManifest } from "@actiondock/core/project";
+import { getPackageSlug } 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";
@@ -28,35 +26,8 @@ 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,
@@ -68,7 +39,7 @@ export class SkillExporter {
         const defaultFolderName = `${pkgSlug}-skill`;
         const defaultSkillDir = join(root, "dist", defaultFolderName);
         const targetSkillDir = resolve(options.outDir || defaultSkillDir);
-        const hasExternalDeps = Boolean((packageGraph && packageGraph.packages.size > 1) || (plan.externalProjectRoots && plan.externalProjectRoots.length > 0));
+        const hasExternalDeps = Boolean(plan.externalProjectRoots && plan.externalProjectRoots.length > 0);
         // 单包源码导出若依赖闭包含外部包，导成 mini-workspace 形态（packages/ 下带齐依赖包），和 bundle 统一成一个交付形状
         // 该复合分支会展开全部依赖包，无法保留调用方传入的 actions/playbooks 过滤选项；
         // 静默丢弃过滤会导致产物全量导出，必须显式拒绝并给出调整指引（CLI 侧已有 roots>1 守卫，此处补齐 composite 分支守卫）
@@ -79,9 +50,8 @@ 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, ...Array.from(packageGraph.packages.values(), (p) => p.root)]));
+            const allProjectRoots = Array.from(new Set([root, ...plan.externalProjectRoots]));
             const compositeRes = await this.exportComposite({
-                packageGraph,
                 bundleName: plan.packageName || plan.packageId,
                 projectRoots: allProjectRoots,
                 outDir: targetSkillDir,

package/dist/planner.js

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
-import { ActionDockError, ACTION_NOT_FOUND, loadProjectConfig, } from "@actiondock/core";
+import { ActionDockError, ACTION_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, loadProjectConfig, } from "@actiondock/core";
 import { assertPathWithinRoot, traverseDirectory, loadManifest, loadPlaybooks, validateManifest, } from "@actiondock/core/project";
 import { DefaultActionCatalog, PackageGraphBuilder, resolveAction, } from "@actiondock/core/graph";
 import { PlannerError } from "./errors.js";
@@ -150,16 +150,13 @@ export class SelectionPlanner {
             selectedPlaybooks = Array.from(playbooksMap.values());
         }
         const manifestActions = manifest.actions || {};
-        // 若显式指定了 Action 列表，加入集合（保持本包短名与完全限定名解析契约）
+        // 若显式指定了 Action 列表，加入集合
         if (options?.actions && options.actions.length > 0) {
             for (const actId of options.actions) {
-                const localId = actId.startsWith(`${config.id}/`)
-                    ? actId.slice(config.id.length + 1)
-                    : actId;
-                if (!manifestActions[localId] && !manifestActions[actId]) {
+                if (!manifestActions[actId]) {
                     throw new PlannerError(`Action '${actId}' specified in build options was not found in manifest`, "ACTION_NOT_FOUND");
                 }
-                initialActionIds.add(manifestActions[localId] ? localId : actId);
+                initialActionIds.add(actId);
             }
         }
         // 若均未显式指定，默认包含清单中的全部 Action
@@ -168,87 +165,94 @@ export class SelectionPlanner {
                 initialActionIds.add(actId);
             }
         }
+        // 当前包在 actiondock.json 中声明的顶层 uses 直接依赖
+        const currentPkgUses = config?.uses;
+        if (Array.isArray(currentPkgUses)) {
+            for (const depId of currentPkgUses) {
+                if (typeof depId === "string" && depId.trim()) {
+                    initialActionIds.add(depId.trim());
+                }
+            }
+        }
         return { initialActionIds, selectedPlaybooks };
     }
     /**
      * 进行依赖闭包（uses）解析计算，自动处理环形依赖与传递依赖（支持当前清单与已链接外部包）。
      */
-    resolveClosure(root, manifest, config, initialActionIds, packageGraph) {
+    resolveClosure(root, manifest, config, initialActionIds) {
         const resolvedActionIds = new Set();
+        // queued 与 resolvedActionIds 联合判重，避免高入度节点在 uses 图中被重复入队导致 O(边数) 重复解析
+        const queued = new Set(initialActionIds);
+        const queue = Array.from(initialActionIds);
         const externalActionRoots = new Map();
         const externalActionEntries = new Map();
-        const graph = packageGraph ?? new PackageGraphBuilder({ root, manifest, allowDevLinks: true }).buildSync();
+        const manifestActions = manifest.actions || {};
+        const graph = new PackageGraphBuilder({ root, allowDevLinks: true }).buildSync();
         const catalog = new DefaultActionCatalog(graph);
-        const queue = [];
-        const visitedPackages = new Set();
-        const expandedPackages = new Set();
-        for (const id of initialActionIds) {
-            queue.push({ id, caller: config.id, isInitialAction: true });
-        }
-        const rawRootUses = manifest.uses ?? config.uses ?? [];
-        visitedPackages.add(config.id);
-        for (const use of rawRootUses) {
-            if (typeof use === "string" && use.trim()) {
-                queue.push({ id: use.trim(), caller: config.id, isInitialAction: false });
-            }
-        }
         while (queue.length > 0) {
-            const { id, caller, isInitialAction } = queue.shift();
-            // uses 支持包名与包级通配符；将其展开为该包的完整动作集合。
-            // 明确选中的初始动作不按包名展开；uses 中的裸包名和通配符仍按包级引用处理。
-            const isWildcard = id.endsWith("/*");
-            const packageId = isWildcard
-                ? id.slice(0, -2)
-                : !isInitialAction && graph.hasPackage(id)
-                    ? id
-                    : undefined;
-            if (packageId) {
-                const node = graph.getPackage(packageId);
-                if (!node)
-                    throw new PlannerError(`Package '${packageId}' referenced by uses was not found`, "PACKAGE_NOT_FOUND");
-                if (expandedPackages.has(packageId))
-                    continue;
-                expandedPackages.add(packageId);
-                if (!visitedPackages.has(packageId)) {
-                    visitedPackages.add(packageId);
-                    for (const use of node.manifest.uses || []) {
-                        queue.push({ id: use, caller: packageId, isInitialAction: false });
+            const currentId = queue.shift();
+            queued.delete(currentId);
+            if (resolvedActionIds.has(currentId)) {
+                continue;
+            }
+            let entry = manifestActions[currentId] || config?.actions?.[currentId];
+            let entryRoot = root;
+            if (!entry) {
+                const resolved = resolveAction(currentId, { graph, catalog, caller: config?.id });
+                const resolvedPkgId = resolved.package.id;
+                const resolvedActionId = resolved.ref.actionId;
+                const extNode = graph.packages.get(resolvedPkgId);
+                if (extNode && existsSync(extNode.root)) {
+                    const extRoot = extNode.root;
+                    let extConfig;
+                    try {
+                        extConfig = loadProjectConfig(extRoot);
+                    }
+                    catch {
+                        extConfig = {
+                            id: resolvedPkgId,
+                            name: resolvedPkgId,
+                            version: "0.1.0",
+                        };
+                    }
+                    const externalManifest = loadManifest(extRoot);
+                    const externalEntry = externalManifest?.actions?.[resolvedActionId] ||
+                        extConfig?.actions?.[resolvedActionId];
+                    if (!externalEntry) {
+                        throw new ActionDockError(UNDECLARED_ACTION_DEPENDENCY, `UNDECLARED_ACTION_DEPENDENCY: Action '${resolvedActionId}' is not declared in package '${resolvedPkgId}' manifest`);
+                    }
+                    entry = externalEntry;
+                    entryRoot = extRoot;
+                    // 依赖包 actiondock.json 中声明的传递依赖闭包（入队前查重，避免重复膨胀）
+                    const extPkgUses = extConfig?.uses;
+                    if (Array.isArray(extPkgUses)) {
+                        for (const u of extPkgUses) {
+                            const trimmedUse = typeof u === "string" ? u.trim() : "";
+                            if (trimmedUse &&
+                                !resolvedActionIds.has(trimmedUse) &&
+                                !queued.has(trimmedUse)) {
+                                queued.add(trimmedUse);
+                                queue.push(trimmedUse);
+                            }
+                        }
                     }
                 }
-                for (const actionId of Object.keys(node.manifest.actions || {})) {
-                    queue.push({ id: `${packageId}/${actionId}`, caller: packageId, isInitialAction: false });
-                }
-                continue;
             }
-            // 保持显式 config/manifest 的单包规划语义，不让磁盘图覆盖调用方清单。
-            const localId = id.startsWith(`${config.id}/`) ? id.slice(config.id.length + 1) : id;
-            const isLocal = (caller === config.id || id.startsWith(`${config.id}/`)) &&
-                Boolean(manifest.actions?.[localId] || config.actions?.[localId]);
-            const resolved = isLocal ? undefined : resolveAction(id, { graph, catalog, caller });
-            const pkgId = resolved?.package.id || config.id;
-            const actionId = resolved?.ref.actionId || localId;
-            const node = graph.getPackage(pkgId);
-            const canonicalId = pkgId === config.id ? actionId : `${pkgId}/${actionId}`;
-            if (resolvedActionIds.has(canonicalId))
-                continue;
-            const entry = pkgId === config.id
-                ? manifest.actions?.[actionId] || config.actions?.[actionId]
-                : node.manifest.actions?.[actionId];
-            if (!entry)
-                throw new ActionDockError(ACTION_NOT_FOUND, `Action '${id}' is not declared in manifest`);
-            resolvedActionIds.add(canonicalId);
-            if (pkgId !== config.id) {
-                externalActionRoots.set(canonicalId, node.root);
-                externalActionEntries.set(canonicalId, entry);
+            if (!entry) {
+                throw new ActionDockError(ACTION_NOT_FOUND, `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`);
             }
-            if (!visitedPackages.has(pkgId)) {
-                visitedPackages.add(pkgId);
-                for (const use of node?.manifest.uses || []) {
-                    queue.push({ id: use, caller: pkgId, isInitialAction: false });
-                }
+            if (entryRoot !== root) {
+                externalActionRoots.set(currentId, entryRoot);
+                externalActionEntries.set(currentId, entry);
             }
-            for (const use of entry.uses || []) {
-                queue.push({ id: use, caller: pkgId, isInitialAction: false });
+            resolvedActionIds.add(currentId);
+            if (entry.uses && Array.isArray(entry.uses)) {
+                for (const depId of entry.uses) {
+                    if (!resolvedActionIds.has(depId) && !queued.has(depId)) {
+                        queued.add(depId);
+                        queue.push(depId);
+                    }
+                }
             }
         }
         return { resolvedActionIds, externalActionRoots, externalActionEntries };
@@ -447,7 +451,7 @@ export class SelectionPlanner {
         const playbooksMap = this.collectPlaybooks(root, config, manifest);
         const { initialActionIds, selectedPlaybooks } = this.resolveInitialSelection(options, manifest, config, playbooksMap);
         // 依赖闭包解析与 Action 依赖结构物化
-        const closure = this.resolveClosure(root, manifest, config, initialActionIds, options?.packageGraph);
+        const closure = this.resolveClosure(root, manifest, config, initialActionIds);
         let finalPlaybooks = selectedPlaybooks;
         // 若指定了 Action 但未指定 Playbook，反向裁剪排除无法满足依赖的 Playbook
         if (options?.actions && options.actions.length > 0 && (!options.playbooks || options.playbooks.length === 0)) {

package/dist/skill/templates.d.ts

@@ -26,9 +26,9 @@ export declare function renderRuntimeReferenceContent(options: {
     relinkStepLabel: string;
     /** 是否在重新链接步骤末尾附加复合链接语义说明 */
     compositeLinkNote?: boolean;
-    /** 调用方式说明：源码型（source-ad）、Node 目录型（node-entry）与开发全局模式（global-ad） */
-    invocationStyle: "global-ad" | "source-ad" | "node-entry";
-    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 或 source-ad 时使用） */
+    /** 调用方式说明：源码型与 Node 目录型分化（如是否需要全局 ad） */
+    invocationStyle: "global-ad" | "node-entry";
+    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 时使用） */
     entryRelPath?: string;
 }): string;
 /** 运行时参考文件的导出目录内相对路径（单一事实源） */
@@ -54,8 +54,6 @@ export interface CompositeSkillPackageInfo {
  */
 export declare function generateCompositeSkillMd(bundleName: string, description: string, packages: CompositeSkillPackageInfo[], options?: {
     customSections?: CompositeCustomSection[];
-    /** 调用方式：开发全局模式（global-ad）、源码 Skill（source-ad）与独立 Node 目录型（node-entry） */
-    invocationStyle?: "global-ad" | "source-ad" | "node-entry";
     /** 规程链接的子包目录前缀：导出布局为 "packages"（默认）；就地生成时传 "." 使用工作区实际目录 */
     packagesBaseDir?: string;
 }): string;

package/dist/skill/templates.js

@@ -13,7 +13,7 @@ function renderActionListMarkdown(actions, options = {}) {
         .map((a) => {
         const aDesc = a.description ? ` - ${a.description}` : "";
         const idLabel = options.packageId
-            ? `\`${options.packageId}/${a.id}\``
+            ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
             : `\`${a.id}\``;
         const lines = [`- ${idLabel}${aDesc}`];
         // 标注元数据解析（安全标注不得从主说明移走）
@@ -124,60 +124,30 @@ function renderJsonEnvelopeSection(wording, options) {
  * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
  */
 export function renderRuntimeReferenceContent(options) {
-    if (options.invocationStyle === "node-entry") {
-        const entry = options.entryRelPath || "node ./entry.mjs";
-        return `# ActionDock 运行时环境参考
-
-本技能为独立 Node.js 运行目录交付，直接使用随附的 \`${entry}\` 入口执行，不要求全局安装 ActionDock 命令行工具，不读取 Registry 或当前工作目录项目。
-
-## 调用方式
-
-\`\`\`bash
-${entry} list
-${entry} describe <package-id>/<action-id>
-${entry} run <package-id>/<action-id> -- ASSIGNMENT...
-\`\`\`
-
-## 按需排查与依赖安装
-
-正常执行直接调用入口，不做前置体检。仅在模块缺失或运行环境报错时修复：
-
-- Node.js 版本要求大于等于 24.12.0。
-- ${options.dependencyStepLabel}：在技能根目录执行 \`npm install --omit=dev\`，由 npm 安装生产依赖。
-- 默认共享统一数据存储。仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
-- 验证就绪：执行 \`${entry} list\`。
-`;
-    }
-    if (options.invocationStyle === "source-ad") {
-        return `# ActionDock 运行时环境参考
-
-本技能通过 \`ad ... -P "<skill_root>"\` 执行，封闭加载本地包集合，不读取全局 Registry 或当前工作目录项目。
-
-## 调用方式
+    const relinkNote = options.compositeLinkNote
+        ? `\`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
+        : "";
+    const invocationSection = options.invocationStyle === "node-entry"
+        ? `本技能为 Node 目录型交付，可直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具：
 
 \`\`\`bash
-ad list -P "<skill_root>"
-ad describe <package-id>/<action-id> -P "<skill_root>"
-ad run <package-id>/<action-id> -P "<skill_root>" -- ASSIGNMENT...
+${options.entryRelPath || "node ./entry.mjs"} list
+${options.entryRelPath || "node ./entry.mjs"} describe <action-id>
+${options.entryRelPath || "node ./entry.mjs"} run <action-id> -- ASSIGNMENT...
 \`\`\`
 
-本地封闭执行不支持 \`--async\`。默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
-
-## 按需排查与依赖安装
-
-正常执行直接调用入口，不做前置体检。仅在模块缺失或运行环境报错时修复：
-
-- Node.js 版本要求大于等于 24.12.0。
-- ${options.dependencyStepLabel}：在技能根目录执行 \`npm install --omit=dev\`，由 npm 安装生产依赖。
-- 验证就绪：执行 \`ad list -P "<skill_root>"\`。
-`;
-    }
-    const relinkNote = options.compositeLinkNote
-        ? `\`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
-        : "";
-    const invocationSection = `本说明书用于开发工作区，通过全局安装的 \`ad\` 命令行工具执行，不代表完整技能导出。`;
-    const probePrinciple = `默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检；仅在终端明确报错提示命令不存在或依赖缺失时，方可按本文指引安装初始化。`;
-    const cliInstallSection = `- **环境要求**：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
@@ -205,7 +175,7 @@ ${cliInstallSection}
   cd "<skill_root>" && npm install --omit=dev
   \`\`\`
 - **验证就绪**：
-  ad --version
+  ${isNodeEntry ? `${options.entryRelPath || "node ./entry.mjs"} list` : "ad --version"}
 - **环境诊断与体检**（仅全局接入 \`ad\` 后适用）：
   安装完成后若仍遇到异常，执行体检命令排查：
   \`\`\`bash
@@ -234,9 +204,10 @@ function renderTroubleshootingSection(referenceRelPath) {
 export const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
 export function generateSourceSkillMd(config, actions, playbooks) {
     const { cleanName, desc } = getCleanSkillMetadata(config);
-    const firstAction = `${config.id}/${actions[0]?.id || "sample.greet"}`;
-    const defaultDescribe = `ad describe ${firstAction} -P "<skill_root>"`;
-    const defaultRun = `ad run ${firstAction} -P "<skill_root>"`;
+    const pkgId = config.id;
+    const firstAction = actions[0]?.id || "sample.greet";
+    const playbookSection = renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks");
+    const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
     return `---
 name: ${cleanName}
 description: ${desc}
@@ -246,32 +217,56 @@ description: ${desc}
 
 ${desc}
 
-## 本地执行
+## ActionDock 运行时
+
+本技能为 **ActionDock 源码型技能包**。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
+
+### 注册与链接（全局调用）
+
+本技能面向全局挂载使用：在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
+
+\`\`\`bash
+ad link "<skill_root>"
+\`\`\`
+
+> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。若初次运行提示依赖缺失，可在 \`<skill_root>\` 目录下执行 \`npm install --omit=dev\` 安装生产依赖。
 
-将本文件所在目录解析为 \`<skill_root>\`。默认通过 \`ad ... -P "<skill_root>"\` 执行，只加载随附的确定版本包，不读取 Registry 或当前工作目录项目，不需要 \`ad link\`。
-首次缺少依赖时，在技能根目录执行 \`npm install --omit=dev\`。
-默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
-本地封闭执行不支持 \`--async\`。
+### 动作参数契约按需调阅
 
-${renderInvocationGuidance(defaultDescribe, defaultRun)}
+在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
+
+\`\`\`bash
+ad describe ${pkgId}/${firstAction}
+\`\`\`
+
+### 执行 Action
+
+为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
+
+${renderInvocationGuidance(`ad describe ${pkgId}/${firstAction}`, `ad run ${pkgId}/${firstAction}`)}
 
 ${renderJsonEnvelopeSection("envelope")}
-${renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks")}
+${playbookSection}
+---
 
 ## Action 目录
 
-${renderActionListMarkdown(actions, { packageId: config.id })}
+${actionListMd}
+
+---
 
 ## 运行时配置与持久化状态
 
+如需检查或配置该 Package 的运行时参数与持久化数据：
+
 \`\`\`bash
 # 查看与设置配置项
-ad config list -P "<skill_root>"
-ad config set KEY VALUE -P "<skill_root>"
+ad config list --package ${pkgId}
+ad config set KEY VALUE --package ${pkgId}
 
 # 查看与检索状态数据
-ad state list -P "<skill_root>"
-ad state get KEY -P "<skill_root>"
+ad state list --package ${pkgId}
+ad state get KEY --package ${pkgId}
 \`\`\`
 
 ${renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH)}
@@ -367,8 +362,8 @@ export function generateCompositeSkillMd(bundleName, description, packages, opti
     for (const pkg of packages) {
         for (const pb of pkg.playbooks) {
             const relPath = packagesBaseDir === "."
-                ? `./${pkg.packageDir}/${pkg.config.playbooksDir || "playbooks"}/${basename(pb.filePath)}`
-                : `packages/${pkg.packageDir}/${pkg.config.playbooksDir || "playbooks"}/${basename(pb.filePath)}`;
+                ? `./${pkg.packageDir}/playbooks/${basename(pb.filePath)}`
+                : `packages/${pkg.packageDir}/playbooks/${basename(pb.filePath)}`;
             playbookEntries.push(`- [${pb.name || pb.id}](${relPath}): ${pb.description || "标准操作规程"}`);
         }
     }
@@ -380,36 +375,12 @@ description: ${description}
 # ${bundleName} 复合技能套件
 
 ${description}`;
-    const invocationStyle = options?.invocationStyle ?? "source-ad";
-    const isGlobalAd = invocationStyle === "global-ad";
-    const isNodeEntry = invocationStyle === "node-entry";
-    const describeCmd = isGlobalAd
-        ? `ad describe ${sampleActionId}`
-        : isNodeEntry
-            ? `node "<skill_root>/entry.mjs" describe ${sampleActionId}`
-            : `ad describe ${sampleActionId} -P "<skill_root>"`;
-    const runCmd = isGlobalAd
-        ? `ad run ${sampleActionId}`
-        : isNodeEntry
-            ? `node "<skill_root>/entry.mjs" run ${sampleActionId}`
-            : `ad run ${sampleActionId} -P "<skill_root>"`;
-    const localGuidance = isGlobalAd
-        ? ""
-        : isNodeEntry
-            ? `将本文件所在目录解析为 \`<skill_root>\`。直接使用随附的 \`node "<skill_root>/entry.mjs"\` 入口执行，不要求全局安装 \`ad\` 命令行工具，不读取 Registry 或当前工作目录项目。
-缺少依赖时，在技能根目录执行 \`npm install --omit=dev\`。默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
-本地封闭执行不支持 \`--async\`；复合技能不提供配置与状态管理子命令，配置覆盖使用 \`--config KEY=VALUE\`。`
-            : `将本文件所在目录解析为 \`<skill_root>\`。默认通过 \`ad ... -P "<skill_root>"\` 执行，仅使用本技能封闭包含的本地包集合，不通过 Registry 或当前工作目录项目执行，亦不需要 \`ad link\`。此执行约定优先于自定义正文中的历史调用说明。
-缺少依赖时，在技能根目录执行 \`npm install --omit=dev\`。默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
-本地封闭执行不支持 \`--async\`；复合技能不提供配置与状态管理子命令，配置覆盖使用 \`--config KEY=VALUE\`。`;
     const sDescribe = `## 动作参数契约按需调阅
 
-${localGuidance}
-
 为节省上下文开销，各 Action 的详细参数结构不静态内嵌在说明书中。在调用未知参数的 Action 前，可在终端执行命令查阅输入输出约束：
 
 \`\`\`bash
-${describeCmd}
+ad describe ${sampleActionId}
 \`\`\``;
     const sActions = `## 可用 Action 工具清单
 
@@ -426,8 +397,8 @@ ${playbookEntries.join("\n")}
 ---`
         : "";
     const sInvoke = `## 标准调用命令
-
-${renderInvocationGuidance(describeCmd, runCmd)}
+ 
+${renderInvocationGuidance(`ad describe ${sampleActionId}`, `ad run ${sampleActionId}`)}
 
 ${renderJsonEnvelopeSection("envelope", { withDescriptions: false })}`;
     const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);

package/dist/skill-md.d.ts

@@ -35,11 +35,3 @@ export declare function writeSkillMd(root: string, destDir: string, options: {
  * 构造模板生成所需的 ProjectConfig 视图。
  */
 export declare function buildConfigForTemplates(plan: SelectionPlan, actionsDir: string, playbooksDir: string): ProjectConfig;
-/** 刷新有边界标记的本地执行约定，保留生成块之外的用户正文。 */
-export declare function appendLocalExecutionContract(file: string, packages: Array<{
-    packageId: string;
-    actions: Array<{
-        id: string;
-        isExternal?: boolean;
-    }>;
-}>): void;

package/dist/skill-md.js

@@ -159,49 +159,3 @@ export function buildConfigForTemplates(plan, actionsDir, playbooksDir) {
         config: plan.configDefs,
     };
 }
-/** 刷新有边界标记的本地执行约定，保留生成块之外的用户正文。 */
-export function appendLocalExecutionContract(file, packages) {
-    const commands = packages.flatMap((pkg) => pkg.actions
-        .filter((action) => !action.isExternal)
-        .map((action) => `- \`${pkg.packageId}/${action.id}\``));
-    const content = readFileSync(file, "utf-8");
-    const block = `<!-- actiondock:local-execution -->
-## 本地执行约定
-
-本节为导出器根据实际包清单生成的执行约定，优先于上文保留的历史调用或初始化说明。
-将本文件所在目录解析为 \`<skill_root>\`。默认使用 \`ad ... -P "<skill_root>"\` 执行，仅加载本技能封闭包含的本地包集合，不通过 Registry、当前工作目录项目或 \`ad link\` 调度。
-
-\`\`\`bash
-cd "<skill_root>" && npm install --omit=dev
-ad list -P "<skill_root>"
-ad describe <package-id>/<action-id> -P "<skill_root>"
-ad run <package-id>/<action-id> -P "<skill_root>" -- ASSIGNMENT...
-\`\`\`
-
-默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`；封闭执行不支持 \`--async\`。
-
-### 本次导出的可用动作
-
-${commands.join("\n")}
-<!-- actiondock:local-execution:end -->`;
-    const startMarker = "<!-- actiondock:local-execution -->";
-    const endMarker = "<!-- actiondock:local-execution:end -->";
-    let cursor = 0;
-    let refreshed = "";
-    let found = false;
-    while (true) {
-        const start = content.indexOf(startMarker, cursor);
-        const end = content.indexOf(endMarker, cursor);
-        if (start < 0 && end < 0)
-            break;
-        const nextStart = start < 0 ? -1 : content.indexOf(startMarker, start + startMarker.length);
-        if (start < 0 || end < start || (nextStart >= 0 && nextStart < end)) {
-            throw new BuilderError("Incomplete or misordered local execution block markers; refusing to replace user content");
-        }
-        refreshed += content.slice(cursor, start) + (found ? "" : block);
-        found = true;
-        cursor = end + endMarker.length;
-    }
-    refreshed += content.slice(cursor);
-    writeFileSync(file, found ? refreshed : content + "\n\n" + block + "\n", "utf-8");
-}

package/dist/types.d.ts

@@ -1,5 +1,4 @@
 import type { ProjectConfig } from "@actiondock/core";
-import type { PackageGraph } from "@actiondock/core/graph";
 import type { ActionDockManifest } from "@actiondock/core/project";
 /**
  * 规划输入侧的项目配置扩展字段。
@@ -151,8 +150,6 @@ export type SelectionPlan = BuildPlan;
  * 声明式选择规划器配置选项。
  */
 export interface SelectionPlannerOptions {
-    /** 显式共享包图，提供时不再发现 Registry 或当前工程。 */
-    packageGraph?: PackageGraph;
     /** 项目根目录绝对路径 */
     projectRoot: string;
     /** 显式传入的项目配置（若未提供则从 actiondock.json 读取） */
@@ -307,8 +304,6 @@ export interface PackResult {
  * Skill 导出选项。
  */
 export interface SkillExporterOptions {
-    /** 复合导出共享的明确包集合。 */
-    packageGraph?: PackageGraph;
     /** 源码项目根目录绝对路径 */
     projectRoot: string;
     /** 导出模式：source 源码型 Skill 或 node 目录型 Skill（默认 source） */
@@ -341,8 +336,6 @@ export interface SkillExporterOptions {
     skipDependencyValidation?: boolean;
     /** 内部标识：是否作为复合套件子包导出（避免闭包再次触发嵌套 mini-workspace） */
     _isSubpackage?: boolean;
-    /** 复合套件子包缺省 npm 包名（当子包无 package.json 或缺少 name 时使用） */
-    defaultPackageName?: string;
     /** 自定义复合技能说明书文件路径 */
     customMdPath?: string;
     /** 所属 Workspace 根目录（可选） */
@@ -387,8 +380,6 @@ export type ExportSkillResult = SkillExportResult;
  * 复合 Skill 套件导出选项。
  */
 export interface CompositeSkillExportOptions {
-    /** 复用源码导出已解析的有效包图，避免丢失显式清单。 */
-    packageGraph?: PackageGraph;
     /** 复合技能套件名称 */
     bundleName: string;
     /** 参与聚合的项目根目录绝对路径列表 */

package/package.json

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

package/dist/derived-graph.d.ts

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

package/dist/derived-graph.js

@@ -1,30 +0,0 @@
-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/source-graph.d.ts

@@ -1,4 +0,0 @@
-import { type ActionDockManifest } from "@actiondock/core/project";
-import { type PackageGraph } from "@actiondock/core/graph";
-/** 源码导出只使用显式包与正式安装依赖；显式兄弟包优先于任何依赖查找。 */
-export declare function createSourcePackageGraph(projectRoots: string[], rootManifest?: ActionDockManifest): PackageGraph;

package/dist/source-graph.js

@@ -1,33 +0,0 @@
-import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
-import { ActionDockError } from "@actiondock/core";
-import { loadManifest } from "@actiondock/core/project";
-import { PackageGraphBuilder } from "@actiondock/core/graph";
-import { BuilderError } from "./errors.js";
-/** 源码导出只使用显式包与正式安装依赖；显式兄弟包优先于任何依赖查找。 */
-export function createSourcePackageGraph(projectRoots, rootManifest) {
-    const packages = new Map();
-    const register = (pkg) => {
-        const existing = packages.get(pkg.id);
-        if (existing && realpathSync(existing.root) !== realpathSync(pkg.root)) {
-            throw new ActionDockError("PACKAGE_ID_CONFLICT", `Package ID '${pkg.id}' is declared by multiple directories: '${existing.root}' and '${pkg.root}'`);
-        }
-        packages.set(pkg.id, pkg);
-    };
-    for (const [index, root] of projectRoots.entries()) {
-        const absRoot = resolve(root);
-        const manifest = index === 0 && rootManifest ? rootManifest : loadManifest(absRoot);
-        if (!manifest)
-            throw new BuilderError(`Missing actiondock.json at '${absRoot}'`);
-        register({ id: manifest.id, root: absRoot, manifest });
-    }
-    const packageRoots = Object.fromEntries(Array.from(packages.values(), (p) => [p.id, p.root]));
-    // 每个显式包的正式依赖均纳入闭包，统一查重后再构造供所有规划共享的图。
-    for (const pkg of Array.from(packages.values())) {
-        const graph = new PackageGraphBuilder({ root: pkg.root, manifest: pkg.manifest, packageRoots, allowDevLinks: false }).buildSync();
-        for (const node of graph.packages.values()) {
-            register({ id: node.packageId, root: node.root, manifest: node.manifest });
-        }
-    }
-    return new PackageGraphBuilder({ packages: Array.from(packages.values()), validateDependencies: true }).buildSync();
-}