@actiondock/core 2.19.0 → 2.21.0

package/dist/host/types.d.ts

@@ -1,12 +1,13 @@
 import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord } from "@actiondock/sdk";
 import type { PackageInfo, PackageRuntime, PackageRuntimeOptions, ActionSpec, ActionSummary, ListActionsOptions, PlaybookSpec, PlaybookSummary } from "../package/types.js";
 import type { CancelResult, ExecutionTicket } from "../execution/types.js";
-import type { RunOptions } from "../invocation/types.js";
+import type { LocalPackagePreparer, RunOptions } from "../invocation/types.js";
 import type { Clock } from "../storage/clock.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform } from "../platform/types.js";
 import type { ActionDockService, ConfigValueView, EventsPort, ListRunsOptions, StateScopeOptions } from "../service/types.js";
 import type { StateEntry } from "../storage/types.js";
+import type { ActionBindings } from "../invocation/bindings.js";
 /**
  * 宿主事件服务端口（既作为独立方法调用，又满足 EventsPort 规范）。
  */
@@ -21,6 +22,8 @@ export interface HostEventsPort extends EventsPort {
  * ActionDock 宿主容器初始化配置选项。
  */
 export interface ActionDockHostOptions {
+    /** 按调用方包覆盖运行时命名绑定；未覆盖的包读取其 .actiondock/bindings.json。 */
+    actionBindings?: Readonly<Record<string, ActionBindings>>;
     /** 显式预注册的包列表（PackageRuntime 实例、PackageRuntimeOptions 配置或包目录物理路径）。Host 统一管理其生命周期，关闭时统一释放。 */
     packages?: Array<PackageRuntime | PackageRuntimeOptions | string>;
     /** 当前工程根目录绝对物理路径 */
@@ -57,6 +60,13 @@ export interface ActionDockHostOptions {
     eventSink?: EventSink;
     /** 是否开启配置与状态管理端口（默认 true） */
     enableManagement?: boolean;
+    /**
+     * 是否允许执行依赖自动安装（主要控制启动与事务恢复中的依赖安装；
+     * 本地包运行期准备由 prepareLocalPackage 注入器根据自身配置决定，Host 不约束外部注入函数副作用）。
+     */
+    allowInstall?: boolean;
+    /** 本地包准备协调器回调，在 Action 执行前准备本地包环境 */
+    prepareLocalPackage?: LocalPackagePreparer;
 }
 /**
  * ActionDock 多包宿主容器领域契约。
@@ -66,6 +76,8 @@ export interface ActionDockHostOptions {
 export interface ActionDockHost extends ActionDockService {
     /** 宿主容器初始化配置项（只读） */
     readonly options?: ActionDockHostOptions;
+    /** 是否允许依赖安装（主要控制启动与事务恢复） */
+    readonly allowInstall?: boolean;
     /** 统一事件订阅端口（兼作原生订阅函数与事件服务端口） */
     readonly events: HostEventsPort;
     /** 获取所有已注册包的元数据信息列表 */

package/dist/index.d.ts

@@ -7,21 +7,29 @@
  */
 export { ACTIONDOCK_VERSION } from "./version.js";
 export { createActionDock, connectActionDock, } from "./service/factory.js";
-export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, RunReadOptions, StateScopeOptions, } from "./service/types.js";
+export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ConfigSource, ListRunsOptions, RunReadOptions, StateScopeOptions, } from "./service/types.js";
 export { isTerminalRunStatus, DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, } from "./storage/types.js";
 export { isRunHostDead } from "./storage/run-liveness.js";
 export type { TerminalRunStatus } from "./storage/types.js";
 export { parseDuration } from "./utils/index.js";
 export { toSnakeUpperCase, resolveEnvValue } from "./runtime/env.js";
 export type { ResolvedEnv } from "./runtime/env.js";
-export type { ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, RunOrigin, ExecutionEvent, } from "@actiondock/sdk";
+export type { ActionInvokeOptions, ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, RunOrigin, ExecutionEvent, } from "@actiondock/sdk";
 export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
+export type { ActionBindings, ActionBindingTarget } from "./invocation/bindings.js";
+export type { LocalPackagePreparationTarget, LocalPackagePreparationContext, LocalPackagePreparer, } from "./invocation/types.js";
 export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";
 export { createNodePlatform, } from "./platform/node.js";
 export { startActionDockServer, } from "./server/server.js";
 export type { ServerOptions, ServerOptions as ActionDockServerOptions, ActionDockServerInstance, } from "./server/types.js";
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { ensureProjectDependencies, } from "./project/dependencies.js";
+export type { EnsureProjectDependenciesOptions, EnsureProjectDependenciesResult, } from "./project/dependencies.js";
 export type { ProjectConfig, } from "./project/types.js";
 export type { PackageGraph, } from "./catalog/graph.js";
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, DEPENDENCIES_NOT_READY, DEPENDENCY_INSTALL_FAILED, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, CONFIG_ENCRYPTION_ERROR, CONFIG_DECRYPT_FAILED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { executeCommand } from "./process/command-executor.js";
+export type { ExecuteCommandOptions, CommandExecutionResult, } from "./process/command-executor.js";
+export type { ConfigEncryptionKey, ConfigKeyProvider, } from "./security/config-cipher.js";
+export { createConfigKeyProvider } from "./security/config-key.js";

package/dist/index.js

@@ -19,5 +19,9 @@ export { startActionDockServer, } from "./server/server.js";
 // 6. 核心工程辅助
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { ensureProjectDependencies, } from "./project/dependencies.js";
 // 8. 统一错误模型与核心标准错误码常量
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, CONFIG_VALUE_INVALID, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, DEPENDENCIES_NOT_READY, DEPENDENCY_INSTALL_FAILED, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, CONFIG_ENCRYPTION_ERROR, CONFIG_DECRYPT_FAILED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";
+// 一次性工程命令执行工具
+export { executeCommand } from "./process/command-executor.js";
+export { createConfigKeyProvider } from "./security/config-key.js";

package/dist/input/config-override.d.ts

@@ -0,0 +1,5 @@
+/** 配置赋值只识别等号左侧的 :=，不物化路径，也不把解析失败回退为字符串。 */
+export declare function parseConfigOverrideAssignment(pair: string): {
+    key: string;
+    value: unknown;
+};

package/dist/input/config-override.js

@@ -0,0 +1,23 @@
+import { ActionDockError, INVALID_ARGUMENT } from "../errors.js";
+import { assertConcreteConfigKey } from "../project/config-declarations.js";
+import { parseJson } from "./input-resolver.js";
+/** 配置赋值只识别等号左侧的 :=，不物化路径，也不把解析失败回退为字符串。 */
+export function parseConfigOverrideAssignment(pair) {
+    const equals = pair.indexOf("=");
+    if (equals < 0) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Expected configuration assignment 'KEY=value' or 'KEY:=json'");
+    }
+    const json = equals > 0 && pair[equals - 1] === ":";
+    const key = pair.slice(0, json ? equals - 1 : equals);
+    assertConcreteConfigKey(key);
+    const rawValue = pair.slice(equals + 1);
+    if (!json)
+        return { key, value: rawValue };
+    try {
+        return { key, value: parseJson(rawValue, "configuration override") };
+    }
+    catch {
+        // JSON.parse 和通用输入校验的诊断可能含输入片段，不能直接回显或挂载 cause。
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid JSON configuration override for '${key}'`);
+    }
+}

package/dist/input/input-resolver.d.ts

@@ -16,7 +16,7 @@ export interface InputResolutionPolicy {
     sanitizeInputErrors?: boolean;
     /** 是否仅允许字节流输入（默认 false） */
     byteStreamOnly?: boolean;
-    /** 原始 stdin 文本模式：保留开头 BOM，UTF-8 编码失败视为读取失败（默认 false，仅作用于 stdinField） */
+    /** 原始 stdin 文本模式：保留开头 BOM，UTF-8 编码失败视为读取失败（stdinField 默认启用） */
     stdinRawText?: boolean;
 }
 /**
@@ -26,19 +26,21 @@ export interface InputResolutionPolicy {
  */
 export declare function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;
 /**
- * Action 执行输入解析选项。
+ * 通用 JSON 值输入解析选项；扁平参数与字段绑定产生对象，完整 JSON 可以是任意合法值。
  */
-export interface ResolveActionInputOptions {
+export interface ResolveInputOptions {
     input?: string;
     inputFile?: string;
     flatArgs?: string[];
-    /** 将 stdin 完整原始文本绑定为指定顶层入参字段的字符串值（与 input / inputFile 互斥，可与 flatArgs 组合） */
+    /** 将 stdin 完整原始文本绑定为指定顶层字段的字符串值（与 input / inputFile 互斥，可与 flatArgs 组合） */
     stdinField?: string;
     stdin?: NodeJS.ReadableStream;
     flatOptions?: FlatParserOptions & FlatMaterializerOptions;
     policy?: InputResolutionPolicy;
     signal?: AbortSignal;
 }
+/** Action 输入沿用通用解码选项，Action 专属契约校验由执行边界负责。 */
+export type ResolveActionInputOptions = ResolveInputOptions;
 /**
  * 解析完整 JSON 文档字符串。
  * 若解析失败抛出 INVALID_JSON 异常。
@@ -49,7 +51,12 @@ export interface ResolveActionInputOptions {
  */
 export declare function parseJson(text: string, source: string, policy?: InputResolutionPolicy): JsonValue;
 /**
- * 统一解析 Action 执行入参。
+ * 解析一个完整值：合法 JSON 解码为对应类型，非 JSON 文本保留为字符串。
+ * 只有语法错误允许回退；大小、深度、有限数和危险属性校验失败必须透传。
+ */
+export declare function parseValueLiteral(text: string, policy?: InputResolutionPolicy): JsonValue;
+/**
+ * 统一解析 JSON 值及结构化输入，不承担 Action、配置或状态的业务校验。
  *
  * 输入模式仲裁规则（Input Mode Arbitration）：
  * - effectiveFlat: flatArgs 存在且 length > 0
@@ -66,6 +73,16 @@ export declare function parseJson(text: string, source: string, policy?: InputRe
  * - stdinField 的 stdin 读取为原始文本绑定：不做 JSON 解析、不剥 BOM、保留首尾空白，空 stdin 得到空字符串。
  *
  * @param options 输入解析选项
- * @returns 解析后的 JSON 对象
+ * @returns 解析后的 JSON 值
  */
-export declare function resolveActionInput(options: ResolveActionInputOptions): Promise<JsonValue>;
+export declare function resolveInput(options: ResolveInputOptions): Promise<JsonValue>;
+/** Action 入参复用同一解码器，避免各命令的扁平路径与 stdin 绑定语义漂移。 */
+export declare const resolveActionInput: typeof resolveInput;
+/** 完整值写入的输入选项；业务层仍负责声明校验与整键替换。 */
+export interface ResolveValueInputOptions extends Pick<ResolveInputOptions, "flatArgs" | "stdinField" | "stdin" | "signal" | "policy" | "flatOptions"> {
+    value?: string;
+    fromStdin?: boolean;
+}
+export declare function hasValueInput(input: ResolveValueInputOptions): boolean;
+/** 先仲裁来源再读流，配置、状态及独立运行入口使用同一完整值解码规则。 */
+export declare function resolveValueInput(options: ResolveValueInputOptions): Promise<JsonValue>;

package/dist/input/input-resolver.js

@@ -2,7 +2,7 @@ import { inputConflict, inputLimitExceeded, inputPathConflict, invalidFlatArgume
 import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
 import { decodeFlatInput } from "./flat-decode.js";
 import { assertTopLevelLeafAvailable, assertMaterializedInputWithinLimits, } from "./flat-materializer.js";
-import { validateJsonValue, DEFAULT_MAX_JSON_DEPTH, } from "../value-validator.js";
+import { validateJsonValue, hasDangerousKeys, DEFAULT_MAX_JSON_DEPTH, } from "../value-validator.js";
 import { scanJsonDepth } from "./json-depth-scanner.js";
 import { decodeUtf8Strict, stripBom } from "./utf8.js";
 import { readRegularFileBounded, DEFAULT_MAX_INPUT_BYTES, } from "./file-input.js";
@@ -203,8 +203,29 @@ export function parseJson(text, source, policy) {
     }
     return parsed;
 }
+function checkValueProperties(value) {
+    if (hasDangerousKeys(value)) {
+        throw invalidJson("Input value contains prohibited prototype pollution properties", { reason: "FORBIDDEN_PROPERTY" });
+    }
+    return value;
+}
 /**
- * 统一解析 Action 执行入参。
+ * 解析一个完整值：合法 JSON 解码为对应类型，非 JSON 文本保留为字符串。
+ * 只有语法错误允许回退；大小、深度、有限数和危险属性校验失败必须透传。
+ */
+export function parseValueLiteral(text, policy) {
+    try {
+        return checkValueProperties(parseJson(text, "value", policy));
+    }
+    catch (error) {
+        if (error instanceof InputError && error.code === "INVALID_JSON" && !Array.isArray(error.details) && error.details?.reason === "SYNTAX_ERROR") {
+            return text;
+        }
+        throw policy?.sanitizeInputErrors ? sanitizeError(error, "inline-json") : error;
+    }
+}
+/**
+ * 统一解析 JSON 值及结构化输入，不承担 Action、配置或状态的业务校验。
  *
  * 输入模式仲裁规则（Input Mode Arbitration）：
  * - effectiveFlat: flatArgs 存在且 length > 0
@@ -221,16 +242,16 @@ export function parseJson(text, source, policy) {
  * - stdinField 的 stdin 读取为原始文本绑定：不做 JSON 解析、不剥 BOM、保留首尾空白，空 stdin 得到空字符串。
  *
  * @param options 输入解析选项
- * @returns 解析后的 JSON 对象
+ * @returns 解析后的 JSON 值
  */
-export async function resolveActionInput(options) {
+export async function resolveInput(options) {
     const effectiveFlat = (options.flatArgs?.length ?? 0) > 0;
     const hasInlineJson = options.input !== undefined;
     const hasFileJson = options.inputFile !== undefined;
     const hasStdinField = options.stdinField !== undefined;
     // stdin 字段绑定与完整 JSON 来源（内联 / 文件 / stdin JSON）严格互斥
     if (hasStdinField && (hasInlineJson || hasFileJson)) {
-        const err = inputConflict("Input options conflict: --stdin-field binds raw stdin text to an action input field and cannot be combined with inline JSON (-i/--input) or file input (-f/--input-file).", {
+        const err = inputConflict("Input options conflict: --stdin-field binds raw stdin text to a top-level field and cannot be combined with inline JSON (-i/--input) or file input (-f/--input-file).", {
             reason: "MULTIPLE_INPUT_MODES",
             hasFlatArgs: effectiveFlat,
             hasInput: hasInlineJson,
@@ -371,3 +392,50 @@ export async function resolveActionInput(options) {
     }
     return {};
 }
+/** Action 入参复用同一解码器，避免各命令的扁平路径与 stdin 绑定语义漂移。 */
+export const resolveActionInput = resolveInput;
+export function hasValueInput(input) {
+    return input.value !== undefined || input.flatArgs !== undefined || Boolean(input.fromStdin) || input.stdinField !== undefined;
+}
+/** 先仲裁来源再读流，配置、状态及独立运行入口使用同一完整值解码规则。 */
+export async function resolveValueInput(options) {
+    options.signal?.throwIfAborted();
+    const wholeModes = Number(options.value !== undefined) + Number(Boolean(options.fromStdin));
+    const structured = options.flatArgs !== undefined || options.stdinField !== undefined;
+    if (wholeModes + Number(structured) > 1) {
+        throw inputConflict("Complete value, --stdin, and structured input are mutually exclusive; --stdin-field may only be combined with flat assignments.", { reason: "MULTIPLE_INPUT_MODES" });
+    }
+    if (structured) {
+        if (options.stdinField === undefined && options.flatArgs?.length === 0) {
+            throw invalidFlatArgument("At least one flat assignment is required after '--'.", { reason: "MISSING_ASSIGNMENT" });
+        }
+        const value = checkValueProperties(await resolveInput(options));
+        options.signal?.throwIfAborted();
+        return value;
+    }
+    let text = options.value;
+    if (options.fromStdin) {
+        try {
+            text = await readStdinBounded(options.stdin || process.stdin, {
+                maxInputBytes: options.policy?.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES,
+                signal: options.signal,
+                strictUtf8: options.policy?.strictUtf8 ?? false,
+                rawText: true,
+                byteStreamOnly: options.policy?.byteStreamOnly,
+            });
+            // 完整 stdin 值保留原配置命令的末尾换行裁剪；字段绑定则原样保留文本。
+            text = text.replace(/[\r\n]+$/, "");
+        }
+        catch (error) {
+            throw options.policy?.sanitizeInputErrors ? sanitizeError(error, "stdin") : error;
+        }
+        if (text.length === 0)
+            throw invalidFlatArgument("No data received from standard input", { reason: "MISSING_VALUE" });
+    }
+    if (text === undefined) {
+        throw invalidFlatArgument("A complete value, flat assignments, --stdin, or --stdin-field is required.", { reason: "MISSING_VALUE" });
+    }
+    const value = parseValueLiteral(text, options.policy);
+    options.signal?.throwIfAborted();
+    return value;
+}

package/dist/invocation/bindings.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 动作绑定目标描述。
+ */
+export type ActionBindingTarget = {
+    type: "local";
+} | {
+    type: "remote";
+    profile: string;
+};
+/**
+ * 动作命名绑定字典单一事实源类型。
+ */
+export type ActionBindings = Readonly<Record<string, Readonly<Record<string, ActionBindingTarget>>>>;
+/** 绑定文件名与目录常量 */
+export declare const BINDINGS_DIR_NAME = ".actiondock";
+export declare const BINDINGS_FILE_NAME = "bindings.json";
+/** 绑定名称正则约束（稳定简单标识符） */
+export declare const ACTION_BINDING_NAME_REGEX: RegExp;
+/** 环境配置名称正则约束 */
+export declare const PROFILE_NAME_REGEX: RegExp;
+/**
+ * 校验并规范化完全限定的动作引用字符串。
+ * 铁律：必须为完全限定包与动作，禁止通配符、路径逃逸、空白与冒号。
+ */
+export declare function validateCanonicalActionRef(ref: unknown): string;
+/**
+ * 校验绑定名称合法性。
+ */
+export declare function validateBindingName(name: unknown, actionRef?: string): string;
+/**
+ * 校验单个绑定目标对象的合法性并返回深拷贝冻结快照。
+ */
+export declare function validateBindingTarget(target: unknown, bindingName: string, actionRef: string): ActionBindingTarget;
+/**
+ * 校验并深拷贝冻结动作绑定配置快照。
+ */
+export declare function validateActionBindings(value: unknown): ActionBindings;
+/**
+ * 从调用方项目目录读取动作绑定配置。
+ * 若文件不存在则返回空冻结映射，其余 IO 或 JSON 异常统一转换为 ActionDockError 透传。
+ */
+export declare function loadActionBindings(projectRoot: string): ActionBindings;
+/**
+ * 解析目标动作引用在当前项目中的具体绑定。
+ * 未显式传入 binding 则仅检索 default；若 default 亦不存在则返回 undefined。
+ * 若显式传入的 binding 不存在，抛出 ActionDockError(NOT_FOUND) 并在 details 中携带 action 与 binding。
+ */
+export declare function resolveActionBinding(bindings: ActionBindings, ref: string, binding?: string): ActionBindingTarget | undefined;
+/**
+ * 检测指定动作是否存在任意 remote 类型的命名绑定。
+ * 仅做完全限定精确匹配，供构建工具快速识别可外置的跨节点依赖。
+ */
+export declare function hasRemoteActionBinding(bindings: ActionBindings, ref: string): boolean;

package/dist/invocation/bindings.js

@@ -0,0 +1,248 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ActionDockError, INVALID_ACTION_REF, INVALID_ARGUMENT, INVALID_JSON, NOT_FOUND, } from "../errors.js";
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { PACKAGE_ID_REGEX } from "../utils/index.js";
+import { ACTION_ID_REGEX } from "../project/manifest.js";
+/** 绑定文件名与目录常量 */
+export const BINDINGS_DIR_NAME = ".actiondock";
+export const BINDINGS_FILE_NAME = "bindings.json";
+/** 绑定名称正则约束（稳定简单标识符） */
+export const ACTION_BINDING_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** 环境配置名称正则约束 */
+export const PROFILE_NAME_REGEX = /^[a-zA-Z0-9_\-\.]+$/;
+/** 空冻结绑定快照单一事实源 */
+const EMPTY_ACTION_BINDINGS = Object.freeze(Object.create(null));
+/**
+ * 校验并规范化完全限定的动作引用字符串。
+ * 铁律：必须为完全限定包与动作，禁止通配符、路径逃逸、空白与冒号。
+ */
+export function validateCanonicalActionRef(ref) {
+    if (typeof ref !== "string") {
+        throw new ActionDockError(INVALID_ACTION_REF, "Invalid action reference: must be a string");
+    }
+    if (ref.length === 0 || /\s/.test(ref)) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': cannot be empty or contain whitespace`);
+    }
+    if (ref.includes(":")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': colon syntax is not permitted, use '/'`);
+    }
+    if (ref.includes("*") || ref.includes("?")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': wildcards are not permitted`);
+    }
+    if (ref.includes("..")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': path traversal is not permitted`);
+    }
+    if (!ref.includes("/")) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': must be fully qualified with package and action (e.g. 'pkg/action')`);
+    }
+    const parsed = parseActionRef(ref);
+    if (!parsed.packageId || !parsed.actionId) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action reference '${ref}': must be fully qualified with package and action`);
+    }
+    const isScoped = /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(parsed.packageId);
+    if (!PACKAGE_ID_REGEX.test(parsed.packageId) && !isScoped) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid package ID '${parsed.packageId}' in action reference '${ref}'`);
+    }
+    if (!ACTION_ID_REGEX.test(parsed.actionId)) {
+        throw new ActionDockError(INVALID_ACTION_REF, `Invalid action ID '${parsed.actionId}' in action reference '${ref}'`);
+    }
+    return `${parsed.packageId}/${parsed.actionId}`;
+}
+/**
+ * 校验绑定名称合法性。
+ */
+export function validateBindingName(name, actionRef) {
+    if (typeof name !== "string") {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid binding name: must be a string");
+    }
+    if (name.length === 0 || /\s/.test(name)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}': cannot be empty or contain whitespace`);
+    }
+    if (name === "__proto__" || name === "constructor" || name === "prototype") {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}': prototype property names are forbidden`);
+    }
+    if (!ACTION_BINDING_NAME_REGEX.test(name)) {
+        const actionMsg = actionRef ? ` for action '${actionRef}'` : "";
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding name '${name}'${actionMsg}: must match ${ACTION_BINDING_NAME_REGEX}`);
+    }
+    return name;
+}
+/**
+ * 校验单个绑定目标对象的合法性并返回深拷贝冻结快照。
+ */
+export function validateBindingTarget(target, bindingName, actionRef) {
+    if (target === null || typeof target !== "object" || Array.isArray(target)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid binding target for action '${actionRef}' binding '${bindingName}': expected a JSON object`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(target, "type")) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Missing 'type' in binding '${bindingName}' for action '${actionRef}'`);
+    }
+    const keys = Object.keys(target);
+    const type = target.type;
+    if (type === "local") {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(target, key))
+                continue;
+            if (key !== "type") {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid property '${key}' in local binding '${bindingName}' for action '${actionRef}': local targets do not permit extra properties`);
+            }
+        }
+        return Object.freeze({ type: "local" });
+    }
+    if (type === "remote") {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(target, key))
+                continue;
+            if (key !== "type" && key !== "profile") {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid property '${key}' in remote binding '${bindingName}' for action '${actionRef}': remote targets only permit 'type' and 'profile'`);
+            }
+        }
+        if (!Object.prototype.hasOwnProperty.call(target, "profile")) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Missing 'profile' in remote binding '${bindingName}' for action '${actionRef}'`);
+        }
+        const profile = target.profile;
+        if (typeof profile !== "string" ||
+            profile.length === 0 ||
+            /\s/.test(profile) ||
+            !PROFILE_NAME_REGEX.test(profile)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Invalid profile '${String(profile)}' in remote binding '${bindingName}' for action '${actionRef}': profile must be non-empty and cannot contain whitespace`);
+        }
+        return Object.freeze({ type: "remote", profile });
+    }
+    throw new ActionDockError(INVALID_ARGUMENT, `Invalid target type '${String(type)}' in binding '${bindingName}' for action '${actionRef}': expected 'local' or 'remote'`);
+}
+/**
+ * 校验并深拷贝冻结动作绑定配置快照。
+ */
+export function validateActionBindings(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid action bindings: expected a JSON object");
+    }
+    const result = Object.create(null);
+    for (const rawRef of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(value, rawRef)) {
+            continue;
+        }
+        const canonicalRef = validateCanonicalActionRef(rawRef);
+        const rawGroup = value[rawRef];
+        if (rawGroup === null || typeof rawGroup !== "object" || Array.isArray(rawGroup)) {
+            throw new ActionDockError(INVALID_ARGUMENT, `Invalid bindings group for action '${canonicalRef}': expected a JSON object`);
+        }
+        const group = Object.create(null);
+        for (const rawBindingName of Object.keys(rawGroup)) {
+            if (!Object.prototype.hasOwnProperty.call(rawGroup, rawBindingName)) {
+                continue;
+            }
+            const bindingName = validateBindingName(rawBindingName, canonicalRef);
+            const rawTarget = rawGroup[rawBindingName];
+            const target = validateBindingTarget(rawTarget, bindingName, canonicalRef);
+            group[bindingName] = target;
+        }
+        result[canonicalRef] = Object.freeze(group);
+    }
+    return Object.freeze(result);
+}
+/**
+ * 从调用方项目目录读取动作绑定配置。
+ * 若文件不存在则返回空冻结映射，其余 IO 或 JSON 异常统一转换为 ActionDockError 透传。
+ */
+export function loadActionBindings(projectRoot) {
+    if (typeof projectRoot !== "string" || projectRoot.length === 0) {
+        throw new ActionDockError(INVALID_ARGUMENT, "Invalid projectRoot: must be a non-empty string");
+    }
+    const filePath = join(projectRoot, BINDINGS_DIR_NAME, BINDINGS_FILE_NAME);
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            return EMPTY_ACTION_BINDINGS;
+        }
+        throw new ActionDockError(INVALID_ARGUMENT, `Failed to read action bindings at ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ActionDockError(INVALID_JSON, `Failed to parse action bindings JSON at ${filePath}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid action bindings format in ${filePath}: expected a JSON object`);
+    }
+    const rootKeys = Object.keys(parsed);
+    for (const key of rootKeys) {
+        if (!Object.prototype.hasOwnProperty.call(parsed, key)) {
+            continue;
+        }
+        if (key === "bindings") {
+            continue;
+        }
+        if (key === "schemaVersion") {
+            const v = parsed.schemaVersion;
+            if (v !== 1) {
+                throw new ActionDockError(INVALID_ARGUMENT, `Invalid schemaVersion '${String(v)}' in ${filePath}: only schemaVersion 1 is supported`);
+            }
+            continue;
+        }
+        throw new ActionDockError(INVALID_ARGUMENT, `Unknown property '${key}' in ${filePath}: only 'bindings' is allowed`);
+    }
+    if (!Object.prototype.hasOwnProperty.call(parsed, "bindings")) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Missing 'bindings' property in ${filePath}`);
+    }
+    return validateActionBindings(parsed.bindings);
+}
+/**
+ * 解析目标动作引用在当前项目中的具体绑定。
+ * 未显式传入 binding 则仅检索 default；若 default 亦不存在则返回 undefined。
+ * 若显式传入的 binding 不存在，抛出 ActionDockError(NOT_FOUND) 并在 details 中携带 action 与 binding。
+ */
+export function resolveActionBinding(bindings, ref, binding) {
+    const canonicalRef = validateCanonicalActionRef(ref);
+    const group = bindings &&
+        typeof bindings === "object" &&
+        Object.prototype.hasOwnProperty.call(bindings, canonicalRef)
+        ? bindings[canonicalRef]
+        : undefined;
+    if (binding === undefined) {
+        if (!group) {
+            return undefined;
+        }
+        return Object.prototype.hasOwnProperty.call(group, "default")
+            ? group["default"]
+            : undefined;
+    }
+    if (!group || !Object.prototype.hasOwnProperty.call(group, binding)) {
+        throw new ActionDockError(NOT_FOUND, `Action binding '${binding}' not found for action '${canonicalRef}'`, { action: canonicalRef, binding });
+    }
+    return group[binding];
+}
+/**
+ * 检测指定动作是否存在任意 remote 类型的命名绑定。
+ * 仅做完全限定精确匹配，供构建工具快速识别可外置的跨节点依赖。
+ */
+export function hasRemoteActionBinding(bindings, ref) {
+    const canonicalRef = validateCanonicalActionRef(ref);
+    if (!bindings || typeof bindings !== "object") {
+        return false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(bindings, canonicalRef)) {
+        return false;
+    }
+    const group = bindings[canonicalRef];
+    if (!group || typeof group !== "object") {
+        return false;
+    }
+    for (const name of Object.keys(group)) {
+        if (!Object.prototype.hasOwnProperty.call(group, name)) {
+            continue;
+        }
+        const target = group[name];
+        if (target?.type === "remote") {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/invocation/policy.d.ts

@@ -1,5 +1,7 @@
 import { type ErrorCode } from "../errors.js";
 import type { PackageGraph } from "../catalog/graph.js";
+/** 动作调用栈键的单一事实源，执行目标作用域不占用额外深度。 */
+export declare function createActionCallKey(actionId: string, packageId?: string, targetScope?: string): string;
 /**
  * 调用治理策略初始化选项。
  */
@@ -32,6 +34,8 @@ export interface CallerActionInfo {
 export interface TargetActionInfo {
     packageId: string;
     actionId: string;
+    /** 跨执行目标时，即使同名包也必须显式声明依赖。 */
+    requiresExplicitUses?: boolean;
 }
 /**
  * 调用治理策略错误描述。
@@ -127,7 +131,7 @@ export declare class InvocationPolicy {
      * @param currentPackageId 当前执行发起方包标识
      * @returns 包含规范化 callKey 与可选错误的结构体
      */
-    checkCycle(callStack: readonly string[], targetActionId: string, targetPackageId?: string, currentPackageId?: string): CycleCheckResult;
+    checkCycle(callStack: readonly string[], targetActionId: string, targetPackageId?: string, currentPackageId?: string, targetScope?: string): CycleCheckResult;
     /**
      * 并发活跃子任务配额检查（Sub-Run Quota Policy）。
      *