@actiondock/builder 2.19.0 → 2.21.0

package/dist/dependency-resolver.d.ts

@@ -3,6 +3,8 @@ import type { ExternalDependency } from "./types.js";
  * 测试与类型声明文件后缀常量（供 fallback 清单过滤与 isIgnoredPath 共享同一口径）。
  */
 export declare const TEST_FILE_SUFFIXES: string[];
+/** 运行环境配置不得进入分发产物；普通业务 bindings.json 不受影响。 */
+export declare function isRuntimeConfigFile(relPath: string): boolean;
 /**
  * 忽略的文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。
  */

package/dist/dependency-resolver.js

@@ -15,6 +15,41 @@ export const TEST_FILE_SUFFIXES = [
     ".spec.jsx",
     ".d.ts",
 ];
+/**
+ * ActionDock 配置加密主密钥与身份标记的规范文件名（位于密钥目录 keys 内）。
+ *
+ * 命名事实源为 core/security/config-key.ts 的 resolveKeyPaths：
+ * 密钥文件 config.key、身份标记 config.key.id。
+ */
+const CONFIG_KEY_FILE_NAMES = ["config.key", "config.key.id"];
+/**
+ * 判断文件名是否为 ActionDock 配置加密密钥资产。
+ *
+ * 密钥发布采用原子硬链接，临时文件名为 .{原名}.tmp.{pid}.{uuid}
+ * （core/security/config-key.ts 的 publishAtomically）；失败清理为尽力而为，
+ * 残留临时名同样可能出现在密钥目录内，须一并识别。
+ */
+function isConfigKeyArtifactName(fileName) {
+    for (const name of CONFIG_KEY_FILE_NAMES) {
+        if (fileName === name || fileName.startsWith(`.${name}.tmp.`)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** 运行环境配置不得进入分发产物；普通业务 bindings.json 不受影响。 */
+export function isRuntimeConfigFile(relPath) {
+    const segments = relPath.replace(/\\/g, "/").split("/");
+    const fileName = segments.at(-1) ?? "";
+    if (segments.includes(".actiondock") || fileName === "profiles.json") {
+        return true;
+    }
+    // 配置加密主密钥仅落在密钥目录 keys 内：dataDir 定位为 <dataDir>/keys，
+    // 主目录定位为 .actiondock/keys（后者已被上方 .actiondock 分支覆盖）。
+    // 仅在 keys 目录上下文下精确排除，普通业务 keys 目录内的其他文件
+    // （如 keys/data.json、keys/api.key）与密钥目录外的同名业务资产不受影响。
+    return segments.at(-2) === "keys" && isConfigKeyArtifactName(fileName);
+}
 /**
  * 忽略的文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。
  */
@@ -24,7 +59,7 @@ export function isIgnoredPath(relPath) {
         normalized.includes("/node_modules/") ||
         normalized.startsWith(".git/") ||
         normalized.startsWith("dist/") ||
-        normalized.startsWith(".actiondock/") ||
+        isRuntimeConfigFile(normalized) ||
         TEST_FILE_SUFFIXES.some((suffix) => normalized.endsWith(suffix)));
 }
 /**

package/dist/npm-pack.d.ts

@@ -1,6 +1,7 @@
+import { type RunPackageManagerOptions } from "@actiondock/core/project";
 /**
  * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
- * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
- * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ * 使用 --json=false 确保标准输出仅输出单行压缩包文件名（显式覆盖 npm_config_json 等环境配置）。
+ * 复用统一包管理器启动解析与驱动底座，以 shell: false 执行，完整保留路径参数与特殊字符边界。
  */
-export declare function runNpmPack(stagingPkgDir: string, packDestination: string, fallbackName: string): Promise<string>;
+export declare function runNpmPack(stagingPkgDir: string, packDestination: string, _fallbackName?: string, options?: RunPackageManagerOptions): Promise<string>;

package/dist/npm-pack.js

@@ -1,69 +1,47 @@
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { runPackageManager } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 /**
  * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
- * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
- * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ * 使用 --json=false 确保标准输出仅输出单行压缩包文件名（显式覆盖 npm_config_json 等环境配置）。
+ * 复用统一包管理器启动解析与驱动底座，以 shell: false 执行，完整保留路径参数与特殊字符边界。
  */
-export async function runNpmPack(stagingPkgDir, packDestination, fallbackName) {
-    const { stdout } = await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", packDestination], {
+export async function runNpmPack(stagingPkgDir, packDestination, _fallbackName, options) {
+    const args = [
+        "pack",
+        "--ignore-scripts",
+        "--json=false",
+        "--pack-destination",
+        packDestination,
+    ];
+    let procResult;
+    try {
+        procResult = await runPackageManager("npm", args, {
+            ...options,
             cwd: stagingPkgDir,
-            shell: process.platform === "win32",
         });
-        let stdoutBuf = "";
-        let stderrBuf = "";
-        child.stdout.on("data", (chunk) => (stdoutBuf += chunk));
-        child.stderr.on("data", (chunk) => (stderrBuf += chunk));
-        child.on("error", rejectPromise);
-        child.on("close", (code) => {
-            if (code === 0) {
-                resolvePromise({ stdout: stdoutBuf, stderr: stderrBuf });
-            }
-            else {
-                rejectPromise(new BuilderError(`npm pack exited with code ${code}. Output:\n${stdoutBuf}\n${stderrBuf}`));
-            }
-        });
-    });
-    // 优先解析 --json 结构化输出中的压缩包文件名
-    let generatedName;
-    const trimmed = stdout.trim();
-    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
-        try {
-            const parsed = JSON.parse(trimmed);
-            let items;
-            if (Array.isArray(parsed)) {
-                items = parsed;
-            }
-            else if (typeof parsed === "object" && parsed !== null) {
-                // npm >= 11 的 pack --json 输出为按包名索引的对象，取全部包含 filename 的条目
-                items = Object.values(parsed).filter((entry) => typeof entry === "object" && entry !== null && "filename" in entry);
-            }
-            else {
-                items = [];
-            }
-            // 多包输出时取最后一个 filename（npm 按依赖顺序逐包输出，末尾为当前项目产物）
-            const filenames = items
-                .map((item) => item.filename)
-                .filter((name) => typeof name === "string" && name.length > 0);
-            const filename = filenames[filenames.length - 1];
-            if (filename !== undefined) {
-                generatedName = filename;
-            }
-        }
-        catch {
-            // 回退到尾部行解析
-        }
     }
-    if (!generatedName) {
-        const packLines = trimmed
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-        const tgzLine = packLines.slice().reverse().find((line) => line.endsWith(".tgz"));
-        generatedName = tgzLine || packLines.pop() || fallbackName;
+    catch (err) {
+        throw new BuilderError(`npm pack failed to execute: ${err?.message || String(err)}`);
+    }
+    if (procResult.status !== 0) {
+        throw new BuilderError(`npm pack exited with code ${procResult.status}. Output:\n${procResult.stdout}\n${procResult.stderr}`);
+    }
+    const stdout = procResult.stdout;
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        throw new BuilderError(`npm pack produced empty stdout; expected tarball filename. Output:\n${stdout}\nStderr:\n${procResult.stderr}`);
+    }
+    if (lines.length > 1) {
+        throw new BuilderError(`npm pack produced unexpected multi-line output; expected single tarball filename. Output:\n${stdout}`);
+    }
+    const generatedName = lines[0];
+    if (!generatedName.endsWith(".tgz")) {
+        throw new BuilderError(`npm pack produced unexpected output line '${generatedName}'; expected .tgz filename. Output:\n${stdout}`);
     }
     const generatedTarball = join(packDestination, generatedName);
     if (!existsSync(generatedTarball)) {

package/dist/planner.js

@@ -1,12 +1,12 @@
 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 { assertPathWithinRoot, traverseDirectory, loadManifest, loadPlaybooks, validateManifest, } from "@actiondock/core/project";
+import { ActionDockError, ACTION_NOT_FOUND, PACKAGE_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, loadProjectConfig, } from "@actiondock/core";
+import { assertPathWithinRoot, traverseDirectory, loadManifest, loadPlaybooks, validateManifest, loadActionBindings, hasRemoteActionBinding, validateCanonicalActionRef, } from "@actiondock/core/project";
 import { DefaultActionCatalog, PackageGraphBuilder, resolveAction, } from "@actiondock/core/graph";
 import { PlannerError } from "./errors.js";
 import { assertRelativeDependenciesIntegrity } from "./dependency-check.js";
 import { computeLockfileInfo } from "./lockfile-resolver.js";
-import { extractExternalDependencies, isIgnoredPath } from "./dependency-resolver.js";
+import { extractExternalDependencies, isIgnoredPath, isRuntimeConfigFile } from "./dependency-resolver.js";
 /**
  * 递归扫描指定目录下的文件，返回绝对路径列表。
  * 目录遍历统一复用 core 的 traverseDirectory 单一事实源，
@@ -15,6 +15,19 @@ import { extractExternalDependencies, isIgnoredPath } from "./dependency-resolve
 function walkDirectory(dir) {
     return traverseDirectory(dir).map((entry) => entry.fullPath);
 }
+/**
+ * 判断动作引用是否为完全限定标识符（包含包命名空间与动作名，且不含通配符与非法字符）。
+ * 统一复用 core 的 validateCanonicalActionRef 单一事实源。
+ */
+function isFullyQualifiedActionRef(ref) {
+    try {
+        validateCanonicalActionRef(ref);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 构造备用清单映射，仅读取文件系统条目与配置声明，杜绝 AST 源码分析与动态代码执行。
  */
@@ -181,81 +194,138 @@ export class SelectionPlanner {
      */
     resolveClosure(root, manifest, config, initialActionIds) {
         const resolvedActionIds = new Set();
-        // queued 与 resolvedActionIds 联合判重，避免高入度节点在 uses 图中被重复入队导致 O(边数) 重复解析
-        const queued = new Set(initialActionIds);
-        const queue = Array.from(initialActionIds);
+        const remoteActionRefs = new Set();
+        const visitedEdges = new Set();
+        const queuedEdges = new Set();
+        const queue = [];
+        const enqueueDependency = (ref, callerRoot, callerPkgId) => {
+            const edgeKey = `${callerRoot}:::${ref}`;
+            if (!visitedEdges.has(edgeKey) && !queuedEdges.has(edgeKey)) {
+                queuedEdges.add(edgeKey);
+                queue.push({ ref, callerRoot, callerPkgId });
+            }
+        };
+        for (const id of initialActionIds) {
+            enqueueDependency(id, root, config?.id);
+        }
         const externalActionRoots = new Map();
         const externalActionEntries = new Map();
         const manifestActions = manifest.actions || {};
         const graph = new PackageGraphBuilder({ root, allowDevLinks: true }).buildSync();
         const catalog = new DefaultActionCatalog(graph);
         while (queue.length > 0) {
-            const currentId = queue.shift();
-            queued.delete(currentId);
-            if (resolvedActionIds.has(currentId)) {
-                continue;
-            }
-            let entry = manifestActions[currentId] || config?.actions?.[currentId];
-            let entryRoot = root;
+            const currentItem = queue.shift();
+            const currentId = currentItem.ref;
+            const currentCallerRoot = currentItem.callerRoot;
+            const currentCallerPkgId = currentItem.callerPkgId;
+            const currentEdgeKey = `${currentCallerRoot}:::${currentId}`;
+            queuedEdges.delete(currentEdgeKey);
+            visitedEdges.add(currentEdgeKey);
+            let entry = currentCallerRoot === root
+                ? (manifestActions[currentId] || config?.actions?.[currentId])
+                : undefined;
+            let entryRoot = currentCallerRoot;
+            let targetPkgId = currentCallerRoot === root ? config?.id : undefined;
             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",
-                        };
+                let localResolved = null;
+                let resolveError = null;
+                try {
+                    localResolved = resolveAction(currentId, {
+                        graph,
+                        catalog,
+                        caller: currentCallerPkgId || config?.id,
+                    });
+                }
+                catch (err) {
+                    resolveError = err;
+                }
+                if (localResolved) {
+                    const resolvedPkgId = localResolved.package.id;
+                    const resolvedActionId = localResolved.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) {
+                            resolveError = new ActionDockError(UNDECLARED_ACTION_DEPENDENCY, `UNDECLARED_ACTION_DEPENDENCY: Action '${resolvedActionId}' is not declared in package '${resolvedPkgId}' manifest`);
+                        }
+                        else {
+                            entry = externalEntry;
+                            entryRoot = extRoot;
+                            targetPkgId = resolvedPkgId;
+                            // 依赖包 actiondock.json 中声明的传递依赖闭包（按外部包自身作用域入队，不继承根配置）
+                            const extPkgUses = extConfig?.uses;
+                            if (Array.isArray(extPkgUses)) {
+                                for (const u of extPkgUses) {
+                                    const trimmedUse = typeof u === "string" ? u.trim() : "";
+                                    if (trimmedUse) {
+                                        enqueueDependency(trimmedUse, extRoot, resolvedPkgId);
+                                    }
+                                }
+                            }
+                        }
                     }
-                    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`);
+                }
+                if (!entry) {
+                    // 仅在明确为包未找到或动作未找到时允许回退至远端绑定检查；严禁掩盖损坏清单、无效引用或版本冲突等非缺失异常
+                    const isMissing = !resolveError ||
+                        (resolveError instanceof ActionDockError &&
+                            (resolveError.code === PACKAGE_NOT_FOUND ||
+                                resolveError.code === ACTION_NOT_FOUND));
+                    if (!isMissing) {
+                        throw resolveError;
                     }
-                    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);
-                            }
+                    // 仅对完全限定依赖（pkg/action），且发起调用的当前包根目录绑定配置中包含精确 remote 条目时，识别为远端依赖
+                    if (isFullyQualifiedActionRef(currentId)) {
+                        const bindings = loadActionBindings(currentCallerRoot);
+                        if (hasRemoteActionBinding(bindings, currentId)) {
+                            remoteActionRefs.add(currentId);
+                            continue;
                         }
                     }
+                    if (resolveError) {
+                        throw resolveError;
+                    }
+                    throw new ActionDockError(ACTION_NOT_FOUND, `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`);
                 }
             }
-            if (!entry) {
-                throw new ActionDockError(ACTION_NOT_FOUND, `Action '${currentId}' referenced in dependency closure (uses) was not found in manifest or linked packages`);
+            // 验证本地 entry 文件物理存在，不得跳过本地 entry 缺失
+            const resolvedPath = resolve(entryRoot, entry.entry);
+            if (!existsSync(resolvedPath)) {
+                throw new PlannerError(`Action '${currentId}' entry file not found on disk: ${entry.entry}`, "ENTRY_FILE_NOT_FOUND");
             }
             if (entryRoot !== root) {
                 externalActionRoots.set(currentId, entryRoot);
                 externalActionEntries.set(currentId, entry);
             }
+            // 物化 action 按既有唯一集合去重，若已物化则跳过重复 uses 展开
+            if (resolvedActionIds.has(currentId)) {
+                continue;
+            }
             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);
+                    const trimmedDep = typeof depId === "string" ? depId.trim() : "";
+                    if (trimmedDep) {
+                        enqueueDependency(trimmedDep, entryRoot, targetPkgId || currentCallerPkgId);
                     }
                 }
             }
         }
-        return { resolvedActionIds, externalActionRoots, externalActionEntries };
+        return { resolvedActionIds, externalActionRoots, externalActionEntries, remoteActionRefs };
     }
     /**
      * 构造 Action 依赖结构（闭包结果物化为 ActionDependency 列表）。
@@ -312,6 +382,9 @@ export class SelectionPlanner {
                 declaredFiles.add(f);
         }
         for (const declaredRel of declaredFiles) {
+            if (isRuntimeConfigFile(declaredRel)) {
+                throw new PlannerError(`Runtime configuration file '${declaredRel}' cannot be explicitly declared as build asset or file`, "RESTRICTED_CONFIG_ASSET");
+            }
             const resolvedFile = resolve(root, declaredRel);
             assertPathWithinRoot(root, resolvedFile, "files");
             if (!existsSync(resolvedFile)) {
@@ -322,7 +395,10 @@ export class SelectionPlanner {
                 const walked = walkDirectory(resolvedFile);
                 for (const f of walked) {
                     const rel = relative(root, f).replace(/\\/g, "/");
-                    if (!isIgnoredPath(rel) && !actionPathSet.has(f) && !filePathSet.has(rel)) {
+                    if (!isIgnoredPath(rel) &&
+                        !isRuntimeConfigFile(rel) &&
+                        !actionPathSet.has(f) &&
+                        !filePathSet.has(rel)) {
                         filePathSet.add(rel);
                         modulesAndAssets.push({
                             path: rel,
@@ -334,7 +410,10 @@ export class SelectionPlanner {
             }
             else if (stat.isFile()) {
                 const rel = relative(root, resolvedFile).replace(/\\/g, "/");
-                if (!actionPathSet.has(resolvedFile) && !filePathSet.has(rel)) {
+                if (!isIgnoredPath(rel) &&
+                    !isRuntimeConfigFile(rel) &&
+                    !actionPathSet.has(resolvedFile) &&
+                    !filePathSet.has(rel)) {
                     filePathSet.add(rel);
                     modulesAndAssets.push({
                         path: rel,
@@ -359,6 +438,9 @@ export class SelectionPlanner {
                 declaredAssets.add(a);
         }
         for (const declaredRel of declaredAssets) {
+            if (isRuntimeConfigFile(declaredRel)) {
+                throw new PlannerError(`Runtime configuration file '${declaredRel}' cannot be explicitly declared as build asset or file`, "RESTRICTED_CONFIG_ASSET");
+            }
             const resolvedAsset = resolve(root, declaredRel);
             assertPathWithinRoot(root, resolvedAsset, "assets");
             if (!existsSync(resolvedAsset)) {
@@ -369,7 +451,7 @@ export class SelectionPlanner {
                 const walked = walkDirectory(resolvedAsset);
                 for (const f of walked) {
                     const rel = relative(root, f).replace(/\\/g, "/");
-                    if (!assetPathSet.has(rel)) {
+                    if (!isIgnoredPath(rel) && !isRuntimeConfigFile(rel) && !assetPathSet.has(rel)) {
                         assetPathSet.add(rel);
                         modulesAndAssets.push({
                             path: rel,
@@ -381,7 +463,7 @@ export class SelectionPlanner {
             }
             else if (stat.isFile()) {
                 const rel = relative(root, resolvedAsset).replace(/\\/g, "/");
-                if (!assetPathSet.has(rel)) {
+                if (!isIgnoredPath(rel) && !isRuntimeConfigFile(rel) && !assetPathSet.has(rel)) {
                     assetPathSet.add(rel);
                     modulesAndAssets.push({
                         path: rel,
@@ -397,7 +479,7 @@ export class SelectionPlanner {
             const assetFiles = walkDirectory(defaultAssetsDir);
             for (const file of assetFiles) {
                 const rel = relative(root, file).replace(/\\/g, "/");
-                if (!assetPathSet.has(rel)) {
+                if (!isIgnoredPath(rel) && !isRuntimeConfigFile(rel) && !assetPathSet.has(rel)) {
                     assetPathSet.add(rel);
                     modulesAndAssets.push({
                         path: rel,
@@ -458,7 +540,7 @@ export class SelectionPlanner {
             finalPlaybooks = selectedPlaybooks.filter((pb) => {
                 if (!pb.actions || pb.actions.length === 0)
                     return true;
-                return pb.actions.every((a) => closure.resolvedActionIds.has(a));
+                return pb.actions.every((a) => closure.resolvedActionIds.has(a) || closure.remoteActionRefs.has(a));
             });
         }
         const actionDependencies = this.buildActionDependencies(root, closure, manifest);
@@ -498,6 +580,7 @@ export class SelectionPlanner {
             configDefs: config.config,
             lockfile: lockfileInfo,
             externalProjectRoots: externalRoots,
+            remoteActionRefs: Array.from(closure.remoteActionRefs || []).sort(),
             metadata: {
                 plannedAt: new Date().toISOString(),
                 schemaVersion: 2,

package/dist/skill/templates.js

@@ -220,19 +220,24 @@ ${desc}`;
 
 本技能为 ActionDock 源码型技能包。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
-### 安装依赖与注册链接
+### 注册链接至全局路由表
 
-本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为先安装生产依赖，再执行注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
+本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为执行注册链接，将其登记至全局路由表：
 
 \`\`\`bash
-# 安装生产依赖
-cd "<skill_root>" && npm install --omit=dev
-
 # 注册并链接到 ActionDock
 ad link "<skill_root>"
 \`\`\`
 
-> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。若后续依赖发生变更，可重新执行上述安装依赖与链接命令更新环境。`;
+> 登记后，在任意工作目录通过完全限定 ID 本地调用 \`ad run\` 时，主动作与宿主快照中已有的本地子动作均会在实际调用前按需准备依赖。\`ad link\` 天然具备幂等性，可安全重复调用。
+
+### 显式手动预装依赖（可选）
+
+使用者明确要求预先准备环境或修复已有依赖时，按项目实际使用的包管理器手动安装生产依赖。若本次调用指定了 \`--no-install\` 或 \`ACTIONDOCK_AUTO_INSTALL=false\`，整条调用链均保持禁装策略并报告依赖未就绪，智能体不能擅自执行安装命令绕过策略。以下为 npm 项目的预装示例：
+
+\`\`\`bash
+cd "<skill_root>" && npm install --omit=dev
+\`\`\``;
     const sDescribe = `### 动作参数契约按需调阅
 
 在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：

package/dist/types.d.ts

@@ -131,6 +131,8 @@ export interface BuildPlan {
     configDefs?: Record<string, unknown>;
     /** 依赖闭包包含的外部已链接包项目根目录列表（去重） */
     externalProjectRoots?: string[];
+    /** 经由远端绑定配置解析的外部依赖 Action 引用列表（只读展示，不加入本地源码构建闭包） */
+    remoteActionRefs?: string[];
     /** 检测到的锁文件信息 */
     lockfile?: LockfileInfo;
     /** 规划元数据 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.19.0",
+  "version": "2.21.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.19.0",
-    "@actiondock/sdk": "^2.19.0"
+    "@actiondock/core": "^2.21.0",
+    "@actiondock/sdk": "^2.21.0"
   },
   "keywords": [
     "actiondock",