@actiondock/core 2.2.2 → 2.3.0

package/README.md

@@ -68,11 +68,16 @@ ActionDock 2.0 核心领域模型与调度引擎。
 - `transaction<T>(fn: () => T): T`：同步事务执行器，在出现异常时自动回滚，并在驱动层严格拦截异步 Promise 以避免事务泄漏。
 - `close(): void`：释放数据库连接与文件句柄。
 
-### ProcessExecutor 进程执行器接口
+### ProcessDriver 进程驱动契约与受管进程架构
 
-抽象跨平台的子进程操作：
+Core 层内置完整的工业级受管进程治理体系，全面解耦具体操作系统运行时：
 
-- `exec(command, args, options): Promise<ProcessResult>`：执行外部命令并捕获标准输出与标准错误流，支持标准输入流透传、执行超时控制、取消信号响应以及缓冲区防爆保护。
+- ProcessManager 进程调度引擎：承载受管进程全生命周期状态机（`starting`、`running`、`stopping`、`exited`、`failed`、`lost`），提供独占控制权令牌分配与续租排队、有界环形输出日志管理、输入队列异步调度、资源硬性限额与宿主/作用域配额审计。
+- ContextProcessAPI 运行上下文适配器：将 ProcessAPI 绑定至具体的 ActionContext 执行链路，自动注入所有者身份与运行标识，跟踪持有的控制令牌；当 Run 结束或异常而未显式释放控制权时，自动触发目标进程隔离或终止。
+- ProcessDriver 平台驱动契约：定义平台底层派生与进程控制的抽象接口（`getCapabilities`、`spawn`、`write`、`inputEOF`、`terminate` 等），屏蔽各操作系统底层实现差异。
+- ProcessOutputLog 有界环形输出日志：单进程独立的有界内存日志缓冲区，支持基于字节游标的分页查询与长轮询等待，自动识别缓冲区淘汰断层。
+- ProcessMetadataStore 元数据存储接口：提供进程运行记录与幂等请求键索引的持久化抽象，默认提供纯内存实现 MemoryProcessMetadataStore。
+- ProcessExecutor 进程执行器接口：抽象跨平台的子进程操作，向后兼容一次性命令执行。
 
 ---
 

package/dist/app/app.d.ts

@@ -10,6 +10,8 @@ import type { ActionDockApp, ActionDockAppOptions, ActionSpec, ActionSummary, Co
  */
 export declare class DefaultActionDockApp implements ActionDockApp {
     readonly packageId: string;
+    readonly packageInstanceId: string;
+    readonly generationId: string;
     readonly packageRoot?: string;
     readonly projectConfig: ProjectConfig;
     readonly platform: RuntimePlatform;

package/dist/app/app.js

@@ -15,6 +15,8 @@ import { decodeStateKey, SqliteRuntimeStorage } from "../storage/sqlite.js";
  */
 export class DefaultActionDockApp {
     packageId;
+    packageInstanceId;
+    generationId;
     packageRoot;
     projectConfig;
     platform;
@@ -57,6 +59,8 @@ export class DefaultActionDockApp {
         this.packageRoot = packageRoot;
         this.projectConfig = projectConfig;
         this.packageId = projectConfig.id;
+        this.packageInstanceId = options.packageInstanceId || projectConfig.packageInstanceId || this.packageId;
+        this.generationId = options.generationId || projectConfig.generationId || "1";
         // 2. 转换 Action 集合：委托归一化单一入口
         this.actionsMap = normalizeActionCollection(options.actions).actionsMap;
         // 3. 确定平台适配层
@@ -122,6 +126,8 @@ export class DefaultActionDockApp {
         // 6. 初始化唯一执行协调服务
         this.executionService = new DefaultExecutionService({
             packageId: this.packageId,
+            packageInstanceId: this.packageInstanceId,
+            generationId: this.generationId,
             hostSessionId: options.hostSessionId,
             storage: this.storage,
             globalStorage: this.globalStorage,

package/dist/app/types.d.ts

@@ -173,12 +173,20 @@ export interface ActionDockAppOptions {
         projectConfig?: ProjectConfig;
         storage: RuntimeStorage;
         actions?: Map<string, ActionDefinition>;
+        packageInstanceId?: string;
+        generationId?: string;
     } | undefined> | {
         projectRoot?: string;
         projectConfig?: ProjectConfig;
         storage: RuntimeStorage;
         actions?: Map<string, ActionDefinition>;
+        packageInstanceId?: string;
+        generationId?: string;
     } | undefined;
+    /** 包物理实例标识 */
+    packageInstanceId?: string;
+    /** 快照代次标识 */
+    generationId?: string;
     /** 临时配置覆写字典 */
     configOverrides?: Record<string, unknown>;
     /** 宿主所有者标识 */
@@ -207,6 +215,10 @@ export interface ActionDockAppOptions {
 export interface ActionDockApp {
     /** 包唯一标识 */
     readonly packageId: string;
+    /** 包物理实例标识 */
+    readonly packageInstanceId?: string;
+    /** 快照代次标识 */
+    readonly generationId?: string;
     /** 包根目录绝对物理路径 */
     readonly packageRoot?: string;
     /** 项目配置对象（actiondock.json 解析结果） */

package/dist/errors.d.ts

@@ -120,3 +120,41 @@ export declare function describeActionLoadFailure(err: unknown, context: ActionL
         hint: string | undefined;
     };
 };
+/** 访问被拒绝或缺少必要权限 */
+export declare const ACCESS_DENIED = "ACCESS_DENIED";
+/** 目标运行环境不支持所声明的能力 */
+export declare const UNSUPPORTED_CAPABILITY = "UNSUPPORTED_CAPABILITY";
+/** 控制权已被其他调用方持有处于忙碌状态 */
+export declare const CONTROL_BUSY = "CONTROL_BUSY";
+/** 控制权有效租约已过期 */
+export declare const CONTROL_EXPIRED = "CONTROL_EXPIRED";
+/** 控制权已被主动撤销或强制收回 */
+export declare const CONTROL_REVOKED = "CONTROL_REVOKED";
+/** 进程由于异常控制失效已进入隔离状态 */
+export declare const PROCESS_QUARANTINED = "PROCESS_QUARANTINED";
+/** 进程已被宿主标记丢失且状态不可恢复 */
+export declare const PROCESS_LOST = "PROCESS_LOST";
+/** 具有相同请求标识但携带不同负载的冲突操作 */
+export declare const REQUEST_CONFLICT = "REQUEST_CONFLICT";
+/** 输入交付结果不确定 */
+export declare const INPUT_OUTCOME_UNKNOWN = "INPUT_OUTCOME_UNKNOWN";
+/** 输出日志发生淘汰缺口且策略要求报错阻断 */
+export declare const OUTPUT_GAP = "OUTPUT_GAP";
+/** 历史输出已不可用 */
+export declare const OUTPUT_UNAVAILABLE = "OUTPUT_UNAVAILABLE";
+/** 游标格式错误或超出有效范围 */
+export declare const INVALID_CURSOR = "INVALID_CURSOR";
+/** 输入待写入队列已达容量上限 */
+export declare const QUEUE_FULL = "QUEUE_FULL";
+/** 资源使用超出配额限制 */
+export declare const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
+/** 输入通道已关闭拒绝继续写入 */
+export declare const INPUT_CLOSED = "INPUT_CLOSED";
+/**
+ * 进程领域结构化异常类。
+ */
+export declare class ProcessError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}

package/dist/errors.js

@@ -121,3 +121,47 @@ export function describeActionLoadFailure(err, context) {
         },
     };
 }
+/** 访问被拒绝或缺少必要权限 */
+export const ACCESS_DENIED = "ACCESS_DENIED";
+/** 目标运行环境不支持所声明的能力 */
+export const UNSUPPORTED_CAPABILITY = "UNSUPPORTED_CAPABILITY";
+/** 控制权已被其他调用方持有处于忙碌状态 */
+export const CONTROL_BUSY = "CONTROL_BUSY";
+/** 控制权有效租约已过期 */
+export const CONTROL_EXPIRED = "CONTROL_EXPIRED";
+/** 控制权已被主动撤销或强制收回 */
+export const CONTROL_REVOKED = "CONTROL_REVOKED";
+/** 进程由于异常控制失效已进入隔离状态 */
+export const PROCESS_QUARANTINED = "PROCESS_QUARANTINED";
+/** 进程已被宿主标记丢失且状态不可恢复 */
+export const PROCESS_LOST = "PROCESS_LOST";
+/** 具有相同请求标识但携带不同负载的冲突操作 */
+export const REQUEST_CONFLICT = "REQUEST_CONFLICT";
+/** 输入交付结果不确定 */
+export const INPUT_OUTCOME_UNKNOWN = "INPUT_OUTCOME_UNKNOWN";
+/** 输出日志发生淘汰缺口且策略要求报错阻断 */
+export const OUTPUT_GAP = "OUTPUT_GAP";
+/** 历史输出已不可用 */
+export const OUTPUT_UNAVAILABLE = "OUTPUT_UNAVAILABLE";
+/** 游标格式错误或超出有效范围 */
+export const INVALID_CURSOR = "INVALID_CURSOR";
+/** 输入待写入队列已达容量上限 */
+export const QUEUE_FULL = "QUEUE_FULL";
+/** 资源使用超出配额限制 */
+export const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
+/** 输入通道已关闭拒绝继续写入 */
+export const INPUT_CLOSED = "INPUT_CLOSED";
+/**
+ * 进程领域结构化异常类。
+ */
+export class ProcessError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ProcessError";
+        this.code = code;
+        this.details = details;
+        Object.setPrototypeOf(this, ProcessError.prototype);
+    }
+}

package/dist/execution/service.d.ts

@@ -11,6 +11,8 @@ export declare class DefaultExecutionService implements ExecutionService {
     private storage;
     private projectConfig?;
     readonly eventSink: EventSink;
+    readonly packageInstanceId: string;
+    readonly generationId: string;
     private maxActiveRuns;
     private ownerId;
     hostSessionId?: string;

package/dist/execution/service.js

@@ -12,6 +12,8 @@ export class DefaultExecutionService {
     storage;
     projectConfig;
     eventSink;
+    packageInstanceId;
+    generationId;
     maxActiveRuns;
     ownerId;
     hostSessionId;
@@ -30,6 +32,8 @@ export class DefaultExecutionService {
     constructor(options) {
         this.platform = options.platform;
         this.packageId = options.packageId;
+        this.packageInstanceId = options.packageInstanceId || this.packageId;
+        this.generationId = options.generationId || "1";
         this.hostSessionId = options.hostSessionId;
         this.projectConfig = options.projectConfig;
         this.eventSink = options.eventSink || options.platform?.eventSink || new InMemoryEventSink();
@@ -63,6 +67,8 @@ export class DefaultExecutionService {
         this.globalStorage = globalStorage;
         this._runner = new ActionRunner({
             packageId: this.packageId,
+            packageInstanceId: this.packageInstanceId,
+            generationId: this.generationId,
             hostSessionId: this.hostSessionId,
             storage: this.storage,
             globalStorage,
@@ -220,6 +226,11 @@ export class DefaultExecutionService {
                 logger: bridge.executionLogger,
                 process: options.process || options.platform?.process || this.process,
                 platform: options.platform || this.platform,
+                packageInstanceId: options.packageInstanceId,
+                generationId: options.generationId,
+                tenantId: options.tenantId,
+                principalId: options.principalId,
+                owner: options.owner,
             });
             const activeItem = {
                 runId: handle.runId,
@@ -394,9 +405,9 @@ export class DefaultExecutionService {
             rootRunId,
             parentRunId: options.parentRunId,
             packageId: targetPackageId,
-            packageInstanceId: targetPackageId,
+            packageInstanceId: options.packageInstanceId || target.runner.packageInstanceId || targetPackageId,
             actionId: targetActionId,
-            generationId: "1",
+            generationId: options.generationId || target.runner.generationId || "1",
             ownerId: this.ownerId,
             hostSessionId: options.hostSessionId || this.hostSessionId,
             status: "failed",

package/dist/execution/types.d.ts

@@ -5,6 +5,7 @@ import type { Clock } from "../runtime/clock.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimeStorage } from "../storage/types.js";
 import type { RuntimePlatform } from "../platform/types.js";
+import type { ProcessOwner } from "../process/process-manager.js";
 /**
  * 执行参数选项。
  */
@@ -33,6 +34,16 @@ export interface ExecuteOptions {
     platform?: RuntimePlatform;
     /** 执行宿主会话标识 */
     hostSessionId?: string;
+    /** 包物理实例标识 */
+    packageInstanceId?: string;
+    /** 快照代次标识 */
+    generationId?: string;
+    /** 租户标识 */
+    tenantId?: string;
+    /** 主体标识 */
+    principalId?: string;
+    /** 执行归属所有者契约 */
+    owner?: ProcessOwner;
 }
 /**
  * 统一执行协调服务配置选项。
@@ -55,17 +66,23 @@ export interface ExecutionServiceOptions {
     maxSubRuns?: number;
     ownerId?: string;
     actionResolver?: (ref: ActionRef | string) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
+    packageInstanceId?: string;
+    generationId?: string;
     getStorageForPackage?: (packageId: string, projectRoot?: string) => RuntimeStorage;
     packageContextResolver?: (packageId: string) => Promise<{
         projectRoot?: string;
         projectConfig?: ProjectConfig;
         storage: RuntimeStorage;
         actions?: Map<string, ActionDefinition>;
+        packageInstanceId?: string;
+        generationId?: string;
     } | undefined> | {
         projectRoot?: string;
         projectConfig?: ProjectConfig;
         storage: RuntimeStorage;
         actions?: Map<string, ActionDefinition>;
+        packageInstanceId?: string;
+        generationId?: string;
     } | undefined;
     customHome?: string;
     platform?: RuntimePlatform;

package/dist/host/host.js

@@ -17,6 +17,23 @@ function isActionDockApp(item) {
         "runAction" in item &&
         typeof item.runAction === "function");
 }
+/**
+ * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
+ *
+ * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
+ * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
+ */
+function isActionNotFoundLikeError(err) {
+    if (!err) {
+        return false;
+    }
+    if (err.code === ACTION_NOT_FOUND || err.code === "NOT_FOUND") {
+        return true;
+    }
+    const message = typeof err.message === "string" ? err.message : String(err);
+    return (message.startsWith("ACTION_NOT_FOUND:") ||
+        /Action '[^']*' not found in package/.test(message));
+}
 /**
  * ActionDock 统一多包宿主容器默认实现。
  * 负责聚合与调度多个 ActionDockApp 实例，提供跨包引用路由、依赖声明校验与资源配额控制。
@@ -216,6 +233,8 @@ export class DefaultActionDockHost {
             projectConfig: targetApp.projectConfig,
             storage: targetApp.storage,
             actions: targetApp.actionsMap,
+            packageInstanceId: targetApp.packageInstanceId,
+            generationId: targetApp.generationId,
         };
     }
     bindApp(app) {
@@ -338,8 +357,11 @@ export class DefaultActionDockHost {
                 const spec = await app.describeAction(parsed.actionId);
                 matches.push({ app, spec: { ...spec, packageId: app.packageId } });
             }
-            catch {
-                // 忽略未匹配的包
+            catch (err) {
+                // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
+                if (!isActionNotFoundLikeError(err)) {
+                    throw err;
+                }
             }
         }
         if (matches.length === 1) {
@@ -469,8 +491,11 @@ export class DefaultActionDockHost {
                     await app.describeAction(targetActionId);
                     matches.push(app);
                 }
-                catch {
-                    // 忽略未找到该 Action 的包
+                catch (err) {
+                    // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
+                    if (!isActionNotFoundLikeError(err)) {
+                        throw err;
+                    }
                 }
             }
             if (matches.length === 1) {
@@ -618,7 +643,23 @@ export class DefaultActionDockHost {
         if (parentRunId && effectiveRootRunId) {
             this.activeSubRunsPerRoot.set(effectiveRootRunId, (this.activeSubRunsPerRoot.get(effectiveRootRunId) || 0) + 1);
         }
-        const ticket = await targetApp.startAction(targetActionId, input, execOptions);
+        let ticket;
+        try {
+            ticket = await targetApp.startAction(targetActionId, input, execOptions);
+        }
+        catch (err) {
+            // 启动失败（并发上限、仓储不可用、幂等冲突等）时必须回滚配额计数，避免泄漏后误拒后续合法子任务
+            if (parentRunId && effectiveRootRunId) {
+                const cnt = this.activeSubRunsPerRoot.get(effectiveRootRunId) || 1;
+                if (cnt <= 1) {
+                    this.activeSubRunsPerRoot.delete(effectiveRootRunId);
+                }
+                else {
+                    this.activeSubRunsPerRoot.set(effectiveRootRunId, cnt - 1);
+                }
+            }
+            throw err;
+        }
         if (parentRunId && effectiveRootRunId && ticket.result) {
             const rootId = effectiveRootRunId;
             ticket.result = ticket.result.finally(() => {

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export * from "./app/index.js";
 export * from "./host/index.js";
 export * from "./target/index.js";
 export * from "./ipc/index.js";
+export * from "./process/index.js";
 export type { ModuleLoader } from "./runtime/index.js";

package/dist/index.js

@@ -18,3 +18,4 @@ export * from "./app/index.js";
 export * from "./host/index.js";
 export * from "./target/index.js";
 export * from "./ipc/index.js";
+export * from "./process/index.js";

package/dist/ipc/host.d.ts

@@ -2,6 +2,11 @@ import type { ActionDockTarget } from "../target/types.js";
 /**
  * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
  *
+ * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
+ * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
+ * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
+ * 调用完成后清理映射，确保取消信号全链路透传。
+ *
  * @param target 已构造好的 ActionDockTarget 实例
  */
 export declare function serveParentIpc(target: ActionDockTarget): Promise<void>;

package/dist/ipc/host.js

@@ -1,6 +1,12 @@
+import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./target.js";
 /**
  * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
  *
+ * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
+ * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
+ * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
+ * 调用完成后清理映射，确保取消信号全链路透传。
+ *
  * @param target 已构造好的 ActionDockTarget 实例
  */
 export async function serveParentIpc(target) {
@@ -20,6 +26,24 @@ export async function serveParentIpc(target) {
             // 忽略关闭异常
         }
     };
+    // 进行中调用的取消控制器映射：id -> AbortController
+    const activeControllers = new Map();
+    /**
+     * 反序列化执行选项：识别取消信号占位标记后重建 AbortController。
+     *
+     * @param id 当前调用唯一标识
+     * @param arg 待反序列化的参数值
+     * @returns 替换后的参数值（原样返回非标记对象）
+     */
+    const reviveIpcSignal = (id, arg) => {
+        if (!hasIpcSignalMarker(arg)) {
+            return arg;
+        }
+        const { [IPC_SIGNAL_MARKER]: _marker, ...rest } = arg;
+        const controller = new AbortController();
+        activeControllers.set(id, controller);
+        return { ...rest, signal: controller.signal };
+    };
     // 监听父进程断连或退出信号
     process.once("disconnect", async () => {
         await safeClose();
@@ -45,7 +69,9 @@ export async function serveParentIpc(target) {
                 if (typeof fn !== "function") {
                     throw new Error(`Target method '${method}' not found`);
                 }
-                const result = await fn.apply(target, args || []);
+                // 反序列化执行选项：识别取消信号占位标记并重建控制器接入取消链路
+                const revivedArgs = (args || []).map((arg) => reviveIpcSignal(id, arg));
+                const result = await fn.apply(target, revivedArgs);
                 const response = {
                     id,
                     type: "response",
@@ -72,6 +98,18 @@ export async function serveParentIpc(target) {
                     process.send(response);
                 }
             }
+            finally {
+                // 调用结束（无论成败）清理取消控制器映射，杜绝映射泄漏
+                activeControllers.delete(id);
+            }
+        }
+        else if (msg.type === "abort") {
+            // 跨进程取消：触发对应调用控制器中止；未知 id 防御性忽略（旧版或已完成的调用）
+            const abortMsg = msg;
+            const controller = activeControllers.get(abortMsg.id);
+            if (controller) {
+                controller.abort(new Error(abortMsg.reason || "Execution was aborted via IPC"));
+            }
         }
         else if (msg.type === "close") {
             await safeClose();
@@ -85,6 +123,10 @@ export async function serveParentIpc(target) {
                 process.send({ type: "pong" });
             }
         }
+        else {
+            // 向后兼容：旧版本对端可能推送未知消息类型，防御性忽略并记录诊断，不中断通道
+            process.stderr.write(`[IPC Host] Ignoring unknown IPC message type: ${JSON.stringify(msg.type)}\n`);
+        }
     });
     // 通知监督父进程：Host 已就绪
     if (process.send) {

package/dist/ipc/target.d.ts

@@ -3,6 +3,18 @@ import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, RunRecord }
 import type { ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
 import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
 import type { ActionDockTarget, ConfigValueView, IpcTargetOptions, StateScopeOptions, TargetInfo } from "../target/types.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export declare const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ *
+ * @param value 待检查的选项值
+ */
+export declare function hasIpcSignalMarker(value: unknown): value is Record<string, unknown>;
 /**
  * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
  *
@@ -28,6 +40,12 @@ export declare class IpcActionDockTarget implements ActionDockTarget {
      */
     get process(): ChildProcess;
     private callRemote;
+    /**
+     * 向宿主子进程发送跨进程取消通知，发送异常不阻断父侧调用链路。
+     *
+     * @param id 目标调用的唯一标识
+     */
+    private sendAbort;
     info(): Promise<TargetInfo>;
     listPackages(): Promise<PackageInfo[]>;
     listActions(options?: ListActionsOptions): Promise<ActionSummary[]>;

package/dist/ipc/target.js

@@ -2,6 +2,36 @@ import { randomUUID } from "node:crypto";
 import { fork } from "node:child_process";
 import { DiagnosticForwarder } from "./diagnostic.js";
 import { EXECUTION_ABORTED, HOST_PROCESS_EXITED } from "../errors.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ *
+ * @param value 待检查的选项值
+ */
+export function hasIpcSignalMarker(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[IPC_SIGNAL_MARKER] === true);
+}
+/**
+ * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
+ * 未携带 signal 时返回浅拷贝，避免消息通道直接持有调用方原始对象。
+ *
+ * @param options 原始执行选项
+ */
+function markIpcSignal(options) {
+    if (!options)
+        return undefined;
+    const { signal: _signal, ...rest } = options;
+    if (!_signal)
+        return rest;
+    return { ...rest, [IPC_SIGNAL_MARKER]: true };
+}
 /**
  * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
  *
@@ -126,7 +156,7 @@ export class IpcActionDockTarget {
     get process() {
         return this.child;
     }
-    async callRemote(method, args) {
+    async callRemote(method, args, signal) {
         if (this.isClosed || this.exitError) {
             if (method === "runAction") {
                 return {
@@ -147,6 +177,16 @@ export class IpcActionDockTarget {
             method,
             args,
         };
+        // 事件驱动跨进程取消：signal 存在且未中止时注册 abort 监听，
+        // 触发即向宿主子进程发送 abort 消息，由宿主侧中止同调用控制器；
+        // 调用结束（无论成败）后注销监听，避免监听器泄漏
+        let onAbort;
+        if (signal && !signal.aborted) {
+            onAbort = () => {
+                this.sendAbort(id);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
         return new Promise((resolve, reject) => {
             this.pendingCalls.set(id, { resolve, reject, method });
             try {
@@ -162,8 +202,31 @@ export class IpcActionDockTarget {
                 this.pendingCalls.delete(id);
                 reject(err);
             }
+        }).finally(() => {
+            if (onAbort && signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
         });
     }
+    /**
+     * 向宿主子进程发送跨进程取消通知，发送异常不阻断父侧调用链路。
+     *
+     * @param id 目标调用的唯一标识
+     */
+    sendAbort(id) {
+        if (this.isClosed)
+            return;
+        try {
+            const abortMsg = { id, type: "abort" };
+            if (this.child.send) {
+                this.child.send(abortMsg);
+            }
+        }
+        catch (err) {
+            // 通道已断开时发送失败属预期场景：宿主退出路径会另行以结构化错误回包
+            process.stderr.write(`[IPC Target] Failed to send abort for call '${id}': ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
     async info() {
         return this.callRemote("info", []);
     }
@@ -183,8 +246,7 @@ export class IpcActionDockTarget {
         return this.callRemote("describePlaybook", [id]);
     }
     async runAction(ref, input, options) {
-        const { signal, ...serializableOptions } = options || {};
-        if (signal?.aborted) {
+        if (options?.signal?.aborted) {
             return {
                 ok: false,
                 runId: randomUUID(),
@@ -194,11 +256,17 @@ export class IpcActionDockTarget {
                 },
             };
         }
-        return this.callRemote("runAction", [ref, input, serializableOptions]);
+        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
+        const serializableOptions = markIpcSignal(options);
+        return this.callRemote("runAction", [ref, input, serializableOptions], options?.signal);
     }
     async startAction(ref, input, options) {
-        const { signal, ...serializableOptions } = options || {};
-        return this.callRemote("startAction", [ref, input, serializableOptions]);
+        if (options?.signal?.aborted) {
+            throw new Error("Execution was aborted before starting");
+        }
+        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
+        const serializableOptions = markIpcSignal(options);
+        return this.callRemote("startAction", [ref, input, serializableOptions], options?.signal);
     }
     async getRun(runId) {
         const res = await this.callRemote("getRun", [runId]);

package/dist/ipc/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 监督进程向宿主子进程发送的跨进程取消通知。
+ * id 与对应 IpcCallMessage 的调用 id 一致，宿主侧据此中止同调用的 AbortController。
+ */
+export interface IpcAbortMessage {
+    id: string;
+    type: "abort";
+    reason?: string;
+}
 /**
  * 监督进程与宿主子进程间调用的 IPC 请求消息。
  */
@@ -39,4 +48,4 @@ export interface IpcReadyMessage {
 /**
  * 联合 IPC 消息类型。
  */
-export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcEventMessage | IpcReadyMessage;
+export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcAbortMessage | IpcEventMessage | IpcReadyMessage;