@actiondock/core 2.0.11 → 2.0.12

package/dist/registry/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 本地软链接（Link）注册的 Package 实体记录。
+ */
+export interface LinkedPackageEntry {
+    /** Package 唯一 ID */
+    id: string;
+    /** 展示名称 */
+    name: string;
+    /** 版本号 */
+    version: string;
+    /** 源码物理目录绝对路径 */
+    path: string;
+    /** 建立软链接的时间戳（ISO 8601） */
+    linkedAt: string;
+    /** 所属 Workspace 根目录（如果是通过 Workspace 自动关联的） */
+    workspaceRoot?: string;
+}
+/**
+ * 本地软链接（Link）注册的 Workspace 工作区目录记录。
+ */
+export interface LinkedWorkspaceEntry {
+    /** 工作区物理目录绝对路径 */
+    path: string;
+    /** 建立软链接的时间戳（ISO 8601） */
+    linkedAt: string;
+}
+/**
+ * 全局 Registry 数据结构（~/.actiondock/registry.json）。
+ */
+export interface GlobalRegistryData {
+    version: string;
+    packages: Record<string, LinkedPackageEntry>;
+    workspaces?: Record<string, LinkedWorkspaceEntry>;
+}
+/**
+ * Link 操作返回结果。
+ */
+export interface LinkResult {
+    id: string;
+    name: string;
+    version: string;
+    path: string;
+    linkedAt: string;
+    isWorkspace?: boolean;
+    entries: LinkedPackageEntry[];
+    workspace?: LinkedWorkspaceEntry;
+}
+/**
+ * Unlink 操作返回结果。
+ */
+export interface UnlinkResult {
+    type: "package" | "workspace";
+    id: string;
+    path: string;
+    packagesCount?: number;
+    removedPackage?: LinkedPackageEntry;
+    removedWorkspace?: LinkedWorkspaceEntry;
+}
+/**
+ * 注册表树形层级节点。
+ */
+export interface RegistryTreeItem {
+    type: "workspace" | "package";
+    id: string;
+    name?: string;
+    version?: string;
+    path: string;
+    status: "active" | "stale";
+    packagesCount?: number;
+    children?: Array<{
+        id: string;
+        name: string;
+        version: string;
+        path: string;
+        status: "active" | "stale";
+    }>;
+}
+/**
+ * 注册表健康状态与列表报告。
+ */
+export interface RegistryStatusReport {
+    workspaces: RegistryTreeItem[];
+    packages: RegistryTreeItem[];
+    staleCount: number;
+    totalPackagesCount: number;
+}
+/**
+ * 失效清理结果。
+ */
+export interface PruneResult {
+    prunedPackages: LinkedPackageEntry[];
+    prunedWorkspaces: LinkedWorkspaceEntry[];
+}
+/**
+ * Action 归属项目解析结果。
+ */
+export interface ResolvedActionProject {
+    /** 所在项目的根目录绝对路径 */
+    projectRoot: string;
+    /** 所属 Package ID */
+    packageId: string;
+    /** 匹配到的 Action ID */
+    actionId: string;
+}
+/**
+ * Playbook 归属项目解析结果。
+ */
+export interface ResolvedPlaybookProject {
+    /** 所在项目的根目录绝对路径 */
+    projectRoot: string;
+    /** 所属 Package ID */
+    packageId: string;
+    /** 匹配到的 Playbook ID */
+    playbookId: string;
+    /** Playbook 实体数据 */
+    playbook: import("../project/types").PlaybookDefinition;
+}

package/dist/runtime/clock.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 统一时间与时钟接口。
+ */
+export interface Clock {
+    /** 获取当前系统墙上时间 */
+    now(): Date;
+    /** 获取单调递增时间戳（单位：毫秒） */
+    monotonic(): number;
+    /** 异步休眠指定毫秒 */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * 生产环境系统时钟实现。
+ */
+export declare class SystemClock implements Clock {
+    now(): Date;
+    monotonic(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare function getSystemClock(): Clock;
+export declare function setSystemClock(clock: Clock): void;

package/dist/runtime/context.d.ts

@@ -0,0 +1,75 @@
+import type { ActionContext, ActionDefinition, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
+import type { ProjectConfig } from "../project/types";
+import type { RuntimeStorage } from "../storage/types";
+/**
+ * 生产级配置解析器实现。
+ * 严格践行 5 层配置解析优先级链：
+ * 1. CLI 临时参数覆写 (Overrides)
+ * 2. 本地项目持久化存储 (Local SQLite: .actiondock/runtime.db)
+ * 3. 全局共享持久化存储 (Global SQLite: ~/.actiondock/global.db)
+ * 4. 操作系统环境变量 (process.env: 显式绑定 / 包名前缀 / SNAKE_CASE / 类型转换)
+ * 5. 项目默认配置 (actiondock.json 中的 default 字段)
+ * 6. 代码级默认回退值 (fallback)
+ */
+export declare class RuntimeConfig implements Config {
+    private overrides;
+    private storage;
+    private projectConfig?;
+    private globalStorage?;
+    constructor(storage: RuntimeStorage, overrides?: Record<string, unknown>, projectConfig?: ProjectConfig, globalStorage?: RuntimeStorage);
+    get<T = unknown>(key: string): T | undefined;
+    get<T = unknown>(key: string, defaultValue: T): T;
+    has(key: string): boolean;
+}
+/**
+ * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
+ */
+export declare class RuntimeStateStore implements StateStore {
+    private storage;
+    private namespace;
+    constructor(storage: RuntimeStorage, namespace?: string);
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(prefix?: string): Promise<number>;
+    keys(prefix?: string): Promise<string[]>;
+    scope(namespace: string): StateStore;
+}
+/**
+ * 标准 Stderr 日志记录器实现。
+ * 遵循 Unix 哲学：所有诊断与追踪日志输出至 stderr，确保 stdout 纯净保留 JSON 信封。
+ */
+export declare class StderrLogger implements Logger {
+    private prefix;
+    constructor(prefix?: string);
+    private format;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * 创建 ActionContext 上下文所需的选项集合。
+ */
+export interface ContextOptions {
+    storage: RuntimeStorage;
+    globalStorage?: RuntimeStorage;
+    overrides?: Record<string, unknown>;
+    projectConfig?: ProjectConfig;
+    parentRunId?: string;
+    runId?: string;
+    rootRunId?: string;
+    callStack?: string[];
+    signal?: AbortSignal;
+    process?: ProcessAPI;
+    progress?: ProgressReporter;
+    logger?: Logger;
+    onActionInvoke?: (action: ActionDefinition | ActionRef | string, input: unknown, parentRunId?: string) => Promise<unknown>;
+}
+/**
+ * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。
+ *
+ * @param options 上下文构建参数
+ * @returns 组装完毕的 ActionContext 实例
+ */
+export declare function createActionContext(options: ContextOptions): ActionContext;

package/dist/runtime/env.d.ts

@@ -0,0 +1,54 @@
+import type { ConfigItemDefinition, ConfigValueType } from "../project/types";
+/**
+ * 从环境变量成功解析后的结构体。
+ */
+export interface ResolvedEnv {
+    /** 转换类型后的配置值 */
+    value: unknown;
+    /** 命中的具体环境变量键名 */
+    envKey: string;
+    /** 数据来源标识 */
+    source: "env";
+}
+/**
+ * 将任意命名格式的字符串转换为标准的大写蛇形命名（UPPER_SNAKE_CASE）。
+ * 兼容处理 camelCase、kebab-case、点号分隔、斜杠以及 @ 作用域符号。
+ *
+ * @param str 输入字符串，如 "apiKey"、"@team4u/github-tools"
+ * @returns 转换后的字符串，如 "API_KEY"、"TEAM4U_GITHUB_TOOLS"
+ */
+export declare function toSnakeUpperCase(str: string): string;
+/**
+ * 当未显式声明类型时，根据默认值的值类型智能推断目标配置类型。
+ *
+ * @param defaultVal 默认值
+ * @returns 推断出的 ConfigValueType 或 undefined
+ */
+export declare function inferTypeFromDefault(defaultVal: unknown): ConfigValueType | undefined;
+/**
+ * 将从 process.env 获取的原始字符串安全转换为目标类型。
+ *
+ * 支持类型：
+ * - boolean: "true"/"1"/"yes"/"on" -> true; "false"/"0"/"no"/"off" -> false
+ * - number: 自动转换为数字，非数字时回退为原始字符串
+ * - object / array: 自动尝试 JSON.parse 反序列化
+ * - 自动探测: 当 targetType 未指定时，自动识别布尔值及 JSON 对象/数组
+ *
+ * @param rawValue process.env 中的原始字符串
+ * @param targetType 期望转换的目标类型
+ */
+export declare function coerceEnvValue(rawValue: string, targetType?: ConfigValueType): unknown;
+/**
+ * 从操作系统环境变量 (process.env) 中解析配置值。
+ * 严格遵循多层回退候选链：
+ * 1. actiondock.json 中声明的显式环境变量绑定 (itemDef.env)
+ * 2. 带包名前缀的变量: `ACTIONDOCK_<PACKAGE>_<KEY>` 以及 `<PACKAGE>_<KEY>`
+ * 3. 标准大写蛇形变量: `<KEY>` (SNAKE_CASE)
+ * 4. 原始键名原样匹配
+ *
+ * @param key 配置键名
+ * @param itemDef 配置项元数据定义
+ * @param packageId 所属包 ID
+ * @returns 命中的 ResolvedEnv 对象或 undefined
+ */
+export declare function resolveEnvValue(key: string, itemDef?: ConfigItemDefinition, packageId?: string): ResolvedEnv | undefined;

package/dist/runtime/events.d.ts

@@ -0,0 +1,61 @@
+import type { ExecutionEvent } from "@actiondock/sdk";
+export interface EventSink {
+    emit(event: ExecutionEvent): void;
+    subscribe(runId: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }): AsyncIterable<ExecutionEvent>;
+    clear(runId: string): void;
+}
+export interface InMemoryEventSinkOptions {
+    /** 单个运行最大缓冲事件数（默认 1024） */
+    maxEventsPerRun?: number;
+    /** 单个运行最大缓冲字节数（默认 1024 * 1024 = 1MiB） */
+    maxBytesPerRun?: number;
+    /** 全局最大缓存运行数（默认 500） */
+    maxRuns?: number;
+}
+/**
+ * 进程内有界事件缓冲区实现。
+ * 遵循设计规范：
+ * 1. 单运行双配额保护：上限 1024 条事件或 1MiB 字节数，优先淘汰日志与进度，保护终态。
+ * 2. 全局有界回收：限制最大运行数（默认 500），溢出时优先淘汰已完成运行。
+ * 3. 原子订阅衔接：先注册实时队列再回放历史快照，去重并杜绝并发丢事件窗口。
+ * 4. 严格生命周期清理：迭代退出或中断时彻底注销监听器与 AbortSignal 事件。
+ */
+export declare class InMemoryEventSink implements EventSink {
+    private runs;
+    private listeners;
+    private wakeups;
+    private evictions;
+    private evictedRuns;
+    private maxEventsPerRun;
+    private maxBytesPerRun;
+    private maxRuns;
+    constructor(options?: InMemoryEventSinkOptions);
+    emit(event: ExecutionEvent): void;
+    subscribe(runId: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }): AsyncIterable<ExecutionEvent>;
+    clear(runId: string): void;
+    /**
+     * 获取指定运行的事件统计信息（调试与测试用）。
+     */
+    getRunStats(runId: string): {
+        count: number;
+        bytes: number;
+        isTerminal: boolean;
+    } | undefined;
+    /**
+     * 获取全局缓存的运行数。
+     */
+    getRunCount(): number;
+    /**
+     * 淘汰最久未活跃的运行记录。
+     * 优先淘汰已终态运行；若无终态运行则淘汰最旧活动运行，严格保证 runs.size <= maxRuns。
+     */
+    private evictOldestRun;
+}
+export declare function getDefaultEventSink(): EventSink;
+export declare function setDefaultEventSink(sink: EventSink): void;

package/dist/runtime/execution-manager.d.ts

@@ -0,0 +1,48 @@
+import type { ExecutionHandle } from "./runner";
+/**
+ * 内存中活跃执行句柄（In-flight Execution Handles）生命周期管理器。
+ *
+ * 职责：
+ * 1. 集中追踪正在执行的异步 Action 任务句柄。
+ * 2. 任务完成（无论成功或失败）后通过 Promise.finally 自动注销，防止内存泄漏。
+ * 3. 支持依据 runId 查询、遍历或主动发送取消信号（cancel）。
+ */
+export declare class ExecutionManager {
+    private active;
+    /**
+     * 注册一个活跃的执行句柄。
+     * 当底层 Promise 完成结算（resolve/reject）时，自动从活跃映射表中移除。
+     *
+     * @param handle 执行句柄对象
+     */
+    register(handle: ExecutionHandle): void;
+    /**
+     * 根据 runId 检索正在执行的任务句柄。
+     *
+     * @param runId 运行 ID
+     * @returns 匹配的 ExecutionHandle 或 undefined
+     */
+    get(runId: string): ExecutionHandle | undefined;
+    /**
+     * 向指定 runId 的在途执行任务发送取消信号。
+     *
+     * @param runId 目标运行 ID
+     * @param reason 取消原因描述
+     * @returns 若句柄存在且成功触发中断返回 true；若任务不存在或已完成返回 false
+     */
+    cancel(runId: string, reason?: string): boolean;
+    /**
+     * 手动从活跃集合中移除执行句柄。
+     *
+     * @param runId 运行 ID
+     */
+    remove(runId: string): void;
+    /**
+     * 获取当前系统中所有正在执行的活跃句柄列表。
+     */
+    list(): ExecutionHandle[];
+    /**
+     * 清空所有活跃执行句柄。
+     */
+    clear(): void;
+}

package/{src/runtime/index.ts → dist/runtime/index.d.ts}

@@ -7,4 +7,3 @@ export * from "./clock";
 export * from "./process";
 export * from "./events";
 export * from "./module-loader";
-

package/dist/runtime/module-loader.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 统一源码模块加载器接口。
+ * 解耦 Action 与各类扩展模块的具体加载机制（如 ECMAScript 原生 import、tsx 动态转译加载等）。
+ */
+export interface ModuleLoader {
+    /**
+     * 解析模块标识符为绝对路径或完整 URL。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起解析的父级文件或目录路径
+     */
+    resolve?(specifier: string, parentPath?: string): string;
+    /**
+     * 动态加载模块并返回命名空间全量导出对象。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    load<T = any>(specifier: string, parentPath?: string): Promise<T>;
+    /**
+     * 加载模块并解包其默认导出（default 或 action 属性）。
+     *
+     * @param specifier 模块规范说明符或物理路径
+     * @param parentPath 发起加载的父级文件或目录路径
+     */
+    loadDefault?<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}
+/**
+ * 基于标准 ECMAScript 动态 import 的默认模块加载器。
+ */
+export declare class DefaultModuleLoader implements ModuleLoader {
+    load<T = any>(specifier: string, _parentPath?: string): Promise<T>;
+    loadDefault<T = any>(specifier: string, parentPath?: string): Promise<T>;
+}
+/**
+ * 注册全局模块加载器实现。
+ */
+export declare function setModuleLoader(loader: ModuleLoader): void;
+/**
+ * 获取当前全局模块加载器，若未显式注册则回退使用 DefaultModuleLoader。
+ */
+export declare function getModuleLoader(): ModuleLoader;

package/dist/runtime/process.d.ts

@@ -0,0 +1,11 @@
+import type { DetachedProcessOptions, DetachedProcessResult, ProcessAPI, ProcessExecOptions, ProcessResult } from "@actiondock/sdk";
+export type ProcessExecutor = ProcessAPI;
+export declare function setProcessExecutor(executor: ProcessExecutor): void;
+export declare function getProcessExecutor(): ProcessExecutor;
+/**
+ * 基于 Node.js 标准 child_process 实现的基础进程执行器。
+ */
+export declare class DefaultProcessExecutor implements ProcessExecutor {
+    exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+    spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult>;
+}

package/dist/runtime/runner.d.ts

@@ -0,0 +1,186 @@
+import type { ActionDefinition, ActionRef, ExecutionResult, Logger, ProcessAPI, ProgressReporter } from "@actiondock/sdk";
+import type { ProjectConfig } from "../project/types";
+import type { RuntimeStorage } from "../storage/types";
+import type { Clock } from "./clock";
+/**
+ * ActionRunner 初始化配置选项。
+ */
+export interface RunnerOptions {
+    /** 运行所属的 Package ID */
+    packageId: string;
+    /** 持久化运行时存储实例（SQLite） */
+    storage: RuntimeStorage;
+    /** 全局共享持久化存储实例（SQLite，用于单例池化避免泄漏） */
+    globalStorage?: RuntimeStorage;
+    /** 项目根目录绝对路径 */
+    projectRoot?: string;
+    /** 项目元数据配置 */
+    projectConfig?: ProjectConfig;
+    /** CLI 或上层注入的临时配置覆盖项 */
+    configOverrides?: Record<string, unknown>;
+    /** 预加载的 Action 映射表 */
+    actions?: Map<string, ActionDefinition>;
+    /** 外部注入的进程执行器 */
+    process?: ProcessAPI;
+    /** 可选的时间与时钟源（默认使用存储内嵌时钟或系统时间） */
+    clock?: Clock;
+    /** 动态解析跨包或未注册 Action 的委托函数 */
+    actionResolver?: (ref: ActionRef | string, currentPackageId?: string) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
+    /** 最大调用嵌套深度限制（防死循环/过深调用链，默认 16） */
+    maxCallDepth?: number;
+    /** 最大并发子任务数限制（默认 64） */
+    maxSubRuns?: number;
+    /** 跨包存储工厂 */
+    getStorageForPackage?: (packageId: string, projectRoot?: string) => RuntimeStorage;
+    /** 跨包运行上下文解析委托函数 */
+    packageContextResolver?: (packageId: string) => Promise<{
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined> | {
+        projectRoot?: string;
+        projectConfig?: ProjectConfig;
+        storage: RuntimeStorage;
+        actions?: Map<string, ActionDefinition>;
+    } | undefined;
+    /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
+    customHome?: string;
+}
+/** ActionRunnerOptions 别名兼容 */
+export type ActionRunnerOptions = RunnerOptions;
+/**
+ * 启动 Action 执行时的可选控制参数。
+ */
+export interface ExecutionStartOptions {
+    /** 显式指定的运行 ID */
+    runId?: string;
+    /** 根运行 ID */
+    rootRunId?: string;
+    /** 父级运行 ID（嵌套调用场景下建立调用链树） */
+    parentRunId?: string;
+    /** 包物理实例标识 */
+    packageInstanceId?: string;
+    /** 快照代次标识 */
+    generationId?: string;
+    /** 执行所有者标识 */
+    ownerId?: string;
+    /** 调用栈数组（用于检测 A -> B -> A 环路死锁） */
+    callStack?: string[];
+    /** 外部传入的 AbortSignal 取消信号 */
+    signal?: AbortSignal;
+    /** 最大超时时间（毫秒），超时将自动中止执行并标记为 ACTION_TIMEOUT */
+    timeoutMs?: number;
+    /** 最大调用深度覆盖 */
+    maxCallDepth?: number;
+    /** 外部注入的进程执行器 */
+    process?: ProcessAPI;
+    /** 外部注入的进度报告器 */
+    progress?: ProgressReporter;
+    /** 外部注入的日志记录器 */
+    logger?: Logger;
+    /** 执行级临时配置覆盖项 */
+    configOverrides?: Record<string, unknown>;
+}
+/**
+ * 异步执行句柄，支持获取执行结果 Promise 与主动取消操作。
+ */
+export interface ExecutionHandle {
+    /** 本次执行生成的全局唯一运行 ID */
+    runId: string;
+    /** 最终执行结果信封 Promise */
+    result: Promise<ExecutionResult>;
+    /**
+     * 取消当前正在执行的任务
+     * @param reason 取消原因
+     * @returns 是否成功触发取消
+     */
+    cancel(reason?: string): boolean;
+}
+/**
+ * Action 解析结果判别联合类型。
+ */
+export type ActionResolution = {
+    status: "found";
+    action: ActionDefinition;
+} | {
+    status: "not_found";
+    reason?: string;
+} | {
+    status: "load_failed";
+    error: Error;
+    packageId: string;
+    projectRoot: string;
+};
+/**
+ * ActionDock 核心执行引擎（ActionRunner）。
+ *
+ * 职责：
+ * 1. 负责 Action 执行的全生命周期管理（校验、隔离、跟踪、落库）。
+ * 2. 入参 (inputSchema) 与出参 (outputSchema) 的 JSON Schema 严格校验。
+ * 3. 嵌套 Action 相互调用的环路检测（Cycle Detection）。
+ * 4. 超时 (Timeout) 与中断信号 (AbortSignal) 竞态控制。
+ * 5. 自动记录并持久化 RunRecord 运行记录至 SQLite 存储。
+ */
+export declare class ActionRunner {
+    private packageId;
+    private storage;
+    private globalStorage?;
+    private projectRoot?;
+    private projectConfig?;
+    private configOverrides;
+    private actions;
+    private clock?;
+    private process?;
+    private maxCallDepth;
+    private maxSubRuns;
+    private activeSubRuns;
+    private packageRunners;
+    private actionResolver?;
+    private getStorageForPackage?;
+    private packageContextResolver?;
+    private customHome?;
+    constructor(options: RunnerOptions);
+    getStorage(): RuntimeStorage;
+    getPackageRunners(): Map<string, ActionRunner>;
+    /**
+     * 注册单个 Action 到当前 Runner。
+     */
+    registerAction(action: ActionDefinition): void;
+    /**
+     * 根据 ID 检索注册的 Action。
+     */
+    getAction(id: string): ActionDefinition | undefined;
+    /**
+     * 动态解析 Action（支持本地注册表、自定义解析器委托与已链接包目录索引检索）。
+     *
+     * @param actionOrRef Action 定义对象、引用或标识符
+     * @returns 解析判别联合结果（found | not_found | load_failed）
+     */
+    resolveAction(actionOrRef: ActionDefinition | ActionRef | string): Promise<ActionResolution>;
+    /**
+     * 获取当前 Runner 已注册的所有 Action 列表。
+     */
+    listActions(): ActionDefinition[];
+    /**
+     * 跨包运行时解析与获取（确保跨包执行具备独立的配置、存储、状态与 Action 注册表）。
+     */
+    resolveTargetPackageRunner(targetPackageId: string): Promise<ActionRunner | undefined>;
+    /**
+     * 异步启动 Action 的执行并立即返回 ExecutionHandle 句柄。
+     *
+     * @param actionOrId Action 定义对象、引用或标识符
+     * @param input 传递给 Action 的输入数据
+     * @param options 执行控制选项（超时、取消信号、父运行 ID 等）
+     * @returns 包含 runId、result Promise 和 cancel 方法的执行句柄
+     */
+    start(actionOrId: ActionDefinition | ActionRef | string, input?: unknown, options?: ExecutionStartOptions): ExecutionHandle;
+    /**
+     * 同步等待方式执行指定 Action，直接返回 ExecutionResult 信封结果。
+     *
+     * @param actionOrId Action 定义对象、引用或标识符
+     * @param input 输入参数
+     * @param options 执行控制选项
+     */
+    execute(actionOrId: ActionDefinition | ActionRef | string, input?: unknown, options?: ExecutionStartOptions): Promise<ExecutionResult>;
+}

package/dist/runtime/standalone.d.ts

@@ -0,0 +1,40 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import type { ConfigItemDefinition } from "../project/types";
+/**
+ * 独立编译可执行文件运行时的初始化选项。
+ */
+export interface StandaloneRuntimeOptions {
+    /** 所属 Package ID */
+    packageId: string;
+    /** 版本号 */
+    version: string;
+    /** 描述信息 */
+    description?: string;
+    /** 声明的配置依赖定义 */
+    config?: Record<string, ConfigItemDefinition>;
+    /** 打包内置的 Action 动作定义列表 */
+    actions: ActionDefinition[];
+}
+/**
+ * 独立二进制可执行文件运行时（Standalone Runtime）。
+ *
+ * 职责：
+ * 1. 作为由 `ad build` 编译生成的单文件独立可执行文件（Standalone Binary）的运行时入口。
+ * 2. 保证与开发态（`ad run` / `ad action`）在输出信封、配置优先级、状态存储等方面的 100% 行为一致性。
+ * 3. 自带轻量 CLI 分发器，支持 `list`, `describe`, `run`, `config`, `state`, `version`, `help` 子命令。
+ */
+export declare class StandaloneRuntime {
+    private packageId;
+    private version;
+    private description?;
+    private configDefs?;
+    private actionsMap;
+    constructor(options: StandaloneRuntimeOptions);
+    /**
+     * 解析命令行参数并执行对应的独立二进制子命令。
+     *
+     * @param argv 命令行参数数组（通常为 process.argv.slice(2)）
+     */
+    run(argv: string[]): Promise<void>;
+}
+export declare function createStandaloneRuntime(options: StandaloneRuntimeOptions): StandaloneRuntime;