@actiondock/builder 2.12.0 → 2.14.0

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, UNDECLARED_ACTION_DEPENDENCY, loadProjectConfig, } from "@actiondock/core";
+import { ActionDockError, ACTION_NOT_FOUND, 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,13 +150,16 @@ 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) {
-                if (!manifestActions[actId]) {
+                const localId = actId.startsWith(`${config.id}/`)
+                    ? actId.slice(config.id.length + 1)
+                    : actId;
+                if (!manifestActions[localId] && !manifestActions[actId]) {
                     throw new PlannerError(`Action '${actId}' specified in build options was not found in manifest`, "ACTION_NOT_FOUND");
                 }
-                initialActionIds.add(actId);
+                initialActionIds.add(manifestActions[localId] ? localId : actId);
             }
         }
         // 若均未显式指定，默认包含清单中的全部 Action
@@ -165,95 +168,88 @@ 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) {
+    resolveClosure(root, manifest, config, initialActionIds, packageGraph) {
         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 manifestActions = manifest.actions || {};
-        const graph = new PackageGraphBuilder({ root, allowDevLinks: true }).buildSync();
+        const graph = packageGraph ?? new PackageGraphBuilder({ root, manifest, allowDevLinks: true }).buildSync();
         const catalog = new DefaultActionCatalog(graph);
-        while (queue.length > 0) {
-            const currentId = queue.shift();
-            queued.delete(currentId);
-            if (resolvedActionIds.has(currentId)) {
-                continue;
+        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 });
             }
-            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);
-                            }
-                        }
+        }
+        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 });
                     }
                 }
+                for (const actionId of Object.keys(node.manifest.actions || {})) {
+                    queue.push({ id: `${packageId}/${actionId}`, caller: packageId, isInitialAction: false });
+                }
+                continue;
             }
-            if (!entry) {
-                throw new ActionDockError(ACTION_NOT_FOUND, `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`);
-            }
-            if (entryRoot !== root) {
-                externalActionRoots.set(currentId, entryRoot);
-                externalActionEntries.set(currentId, entry);
+            // 保持显式 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);
             }
-            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);
-                    }
+            if (!visitedPackages.has(pkgId)) {
+                visitedPackages.add(pkgId);
+                for (const use of node?.manifest.uses || []) {
+                    queue.push({ id: use, caller: pkgId, isInitialAction: false });
                 }
             }
+            for (const use of entry.uses || []) {
+                queue.push({ id: use, caller: pkgId, isInitialAction: false });
+            }
         }
         return { resolvedActionIds, externalActionRoots, externalActionEntries };
     }
@@ -451,7 +447,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);
+        const closure = this.resolveClosure(root, manifest, config, initialActionIds, options?.packageGraph);
         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;
-    /** 调用方式说明：源码型与 Node 目录型分化（如是否需要全局 ad） */
-    invocationStyle: "global-ad" | "node-entry";
-    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 时使用） */
+    /** 调用方式说明：源码型（source-ad）、Node 目录型（node-entry）与开发全局模式（global-ad） */
+    invocationStyle: "global-ad" | "source-ad" | "node-entry";
+    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 或 source-ad 时使用） */
     entryRelPath?: string;
 }): string;
 /** 运行时参考文件的导出目录内相对路径（单一事实源） */
@@ -54,6 +54,8 @@ 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}\` (或 \`${a.id}\`)`
+            ? `\`${options.packageId}/${a.id}\``
             : `\`${a.id}\``;
         const lines = [`- ${idLabel}${aDesc}`];
         // 标注元数据解析（安全标注不得从主说明移走）
@@ -67,12 +67,16 @@ ${describeCmd}
 
 # 调用语法格式（其中 ASSIGNMENT 根据 describe 查阅的参数契约提供）
 ${runCmd} -- ASSIGNMENT...
+
+# 管道原始文本绑定（FIELD 为 describe 查阅的字符串字段名）
+printf '整段原始文本' | ${runCmd} --stdin-field FIELD
 \`\`\`
 
-输入模式选择（三种输入模式严格互斥，仅选其一）：
+输入模式选择（原有三种输入方式严格互斥，仅选其一；\`--stdin-field\` 原始文本绑定可与扁平赋值组合）：
 
 - 扁平赋值为默认首选：参数项少且结构简单时，直接以 \`-- key="value" count:=10\` 形式内联传递。
 - 文件输入用于复杂参数：当参数含深层嵌套结构、大段文本或内容易被终端引号转义破坏时，将完整 JSON 写入文件并通过 \`--input-file input.json\` 传递。
+- 管道原始文本绑定：当只需向单个字符串字段（如 text、content、csv、diff）传入整段原始文本时，使用 \`--stdin-field <field>\` 绑定 stdin 正文，正文保持原样不解析类型，可与扁平赋值补充其他字段。
 
 输出模式选择（避免浪费上下文 token）：
 
@@ -120,30 +124,60 @@ function renderJsonEnvelopeSection(wording, options) {
  * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
  */
 export function renderRuntimeReferenceContent(options) {
-    const relinkNote = options.compositeLinkNote
-        ? `\`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
-        : "";
-    const invocationSection = options.invocationStyle === "node-entry"
-        ? `本技能为 Node 目录型交付，可直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具：
+    if (options.invocationStyle === "node-entry") {
+        const entry = options.entryRelPath || "node ./entry.mjs";
+        return `# ActionDock 运行时环境参考
+
+本技能为独立 Node.js 运行目录交付，直接使用随附的 \`${entry}\` 入口执行，不要求全局安装 ActionDock 命令行工具，不读取 Registry 或当前工作目录项目。
+
+## 调用方式
 
 \`\`\`bash
-${options.entryRelPath || "node ./entry.mjs"} list
-${options.entryRelPath || "node ./entry.mjs"} describe <action-id>
-${options.entryRelPath || "node ./entry.mjs"} run <action-id> -- ASSIGNMENT...
+${entry} list
+${entry} describe <package-id>/<action-id>
+${entry} run <package-id>/<action-id> -- ASSIGNMENT...
 \`\`\`
 
-若宿主环境已全局安装 \`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\` 确认）。
+## 按需排查与依赖安装
+
+正常执行直接调用入口，不做前置体检。仅在模块缺失或运行环境报错时修复：
+
+- 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 或当前工作目录项目。
+
+## 调用方式
+
+\`\`\`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...
+\`\`\`
+
+本地封闭执行不支持 \`--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\` 确认）。
 - **全局安装 ActionDock 命令行工具**：
   \`\`\`bash
   npm install -g @actiondock/cli
@@ -171,7 +205,7 @@ ${cliInstallSection}
   cd "<skill_root>" && npm install --omit=dev
   \`\`\`
 - **验证就绪**：
-  ${isNodeEntry ? `${options.entryRelPath || "node ./entry.mjs"} list` : "ad --version"}
+  ad --version
 - **环境诊断与体检**（仅全局接入 \`ad\` 后适用）：
   安装完成后若仍遇到异常，执行体检命令排查：
   \`\`\`bash
@@ -200,10 +234,9 @@ 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 pkgId = config.id;
-    const firstAction = actions[0]?.id || "sample.greet";
-    const playbookSection = renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks");
-    const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
+    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>"`;
     return `---
 name: ${cleanName}
 description: ${desc}
@@ -213,56 +246,32 @@ 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\` 安装生产依赖。
-
-### 动作参数契约按需调阅
-
-在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
-
-\`\`\`bash
-ad describe ${pkgId}/${firstAction}
-\`\`\`
-
-### 执行 Action
+## 本地执行
 
-为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
+将本文件所在目录解析为 \`<skill_root>\`。默认通过 \`ad ... -P "<skill_root>"\` 执行，只加载随附的确定版本包，不读取 Registry 或当前工作目录项目，不需要 \`ad link\`。
+首次缺少依赖时，在技能根目录执行 \`npm install --omit=dev\`。
+默认共享统一数据存储，仅在需要数据隔离等特殊场景下追加 \`--data-dir <path>\`。
+本地封闭执行不支持 \`--async\`。
 
-${renderInvocationGuidance(`ad describe ${pkgId}/${firstAction}`, `ad run ${pkgId}/${firstAction}`)}
+${renderInvocationGuidance(defaultDescribe, defaultRun)}
 
 ${renderJsonEnvelopeSection("envelope")}
-${playbookSection}
----
+${renderPlaybookSectionMarkdown(playbooks, config.playbooksDir || "playbooks")}
 
 ## Action 目录
 
-${actionListMd}
-
----
+${renderActionListMarkdown(actions, { packageId: config.id })}
 
 ## 运行时配置与持久化状态
 
-如需检查或配置该 Package 的运行时参数与持久化数据：
-
 \`\`\`bash
 # 查看与设置配置项
-ad config list --package ${pkgId}
-ad config set KEY VALUE --package ${pkgId}
+ad config list -P "<skill_root>"
+ad config set KEY VALUE -P "<skill_root>"
 
 # 查看与检索状态数据
-ad state list --package ${pkgId}
-ad state get KEY --package ${pkgId}
+ad state list -P "<skill_root>"
+ad state get KEY -P "<skill_root>"
 \`\`\`
 
 ${renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH)}
@@ -358,8 +367,8 @@ export function generateCompositeSkillMd(bundleName, description, packages, opti
     for (const pkg of packages) {
         for (const pb of pkg.playbooks) {
             const relPath = packagesBaseDir === "."
-                ? `./${pkg.packageDir}/playbooks/${basename(pb.filePath)}`
-                : `packages/${pkg.packageDir}/playbooks/${basename(pb.filePath)}`;
+                ? `./${pkg.packageDir}/${pkg.config.playbooksDir || "playbooks"}/${basename(pb.filePath)}`
+                : `packages/${pkg.packageDir}/${pkg.config.playbooksDir || "playbooks"}/${basename(pb.filePath)}`;
             playbookEntries.push(`- [${pb.name || pb.id}](${relPath}): ${pb.description || "标准操作规程"}`);
         }
     }
@@ -371,12 +380,36 @@ 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
-ad describe ${sampleActionId}
+${describeCmd}
 \`\`\``;
     const sActions = `## 可用 Action 工具清单
 
@@ -393,8 +426,8 @@ ${playbookEntries.join("\n")}
 ---`
         : "";
     const sInvoke = `## 标准调用命令
- 
-${renderInvocationGuidance(`ad describe ${sampleActionId}`, `ad run ${sampleActionId}`)}
+
+${renderInvocationGuidance(describeCmd, runCmd)}
 
 ${renderJsonEnvelopeSection("envelope", { withDescriptions: false })}`;
     const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);

package/dist/skill-md.d.ts

@@ -35,3 +35,11 @@ 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,3 +159,49 @@ 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/source-graph.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,33 @@
+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();
+}

package/dist/types.d.ts

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