@actiondock/core 2.0.10 → 2.0.11-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.0.10",
+  "version": "2.0.11-beta.0",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./src/index.ts",
@@ -27,7 +27,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@actiondock/sdk": "^2.0.10",
+    "@actiondock/sdk": "2.0.11-beta.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "yaml": "^2.7.0"

package/src/export/templates.ts

@@ -144,6 +144,14 @@ ad link "<skill_root>"
 
 > \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。
 
+### 动作参数契约按需调阅
+
+在调用未知参数的 Action 前，可在终端执行命令按需查阅该 Action 的输入输出模式与详细说明：
+
+\`\`\`bash
+ad action show ${pkgId}/${firstAction}
+\`\`\`
+
 ### 执行 Action
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
@@ -376,6 +384,125 @@ export function generateSkillMd(
   return generateStandaloneSkillMd(config, actions, playbooks, optionsOrBinaryPath.binaryRelPath || "./bin/action-bin");
 }
 
+export interface CompositeSkillPackageInfo {
+  config: ProjectConfig;
+  actions: Array<{ id: string; description?: string }>;
+  playbooks: Array<{ id: string; name?: string; description?: string; filePath: string }>;
+  packageDir: string;
+}
+
+/**
+ * 生成多包聚合的复合模式 SKILL.md 文档。
+ */
+export function generateCompositeSkillMd(
+  bundleName: string,
+  description: string,
+  packages: CompositeSkillPackageInfo[]
+): string {
+  const cleanName = bundleName.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
+  const samplePkg = packages.find((p) => p.actions && p.actions.length > 0);
+  const sampleActionId = samplePkg
+    ? `${samplePkg.config.id}/${samplePkg.actions[0].id}`
+    : "sample.greet";
+
+  const actionSections = packages
+    .map((pkg) => {
+      const actList = pkg.actions
+        .map((a) => {
+          const desc = a.description ? `: ${a.description}` : "";
+          return `- \`${pkg.config.id}/${a.id}\`${desc}`;
+        })
+        .join("\n");
+      return `### ${pkg.config.name} (${pkg.config.id})\n${actList || "- 无可用 Action"}`;
+    })
+    .join("\n\n");
+
+  const playbookEntries: string[] = [];
+  for (const pkg of packages) {
+    for (const pb of pkg.playbooks) {
+      const relPath = `packages/${pkg.packageDir}/playbooks/${basename(pb.filePath)}`;
+      playbookEntries.push(`- [${pb.name || pb.id}](${relPath}): ${pb.description || "标准操作规程"}`);
+    }
+  }
+
+  const playbookSection =
+    playbookEntries.length > 0
+      ? `## 推荐操作规程\n\n涉及多步骤或业务流程时，优先遵循以下原位规程：\n\n${playbookEntries.join("\n")}\n\n---\n`
+      : "";
+
+  return `---
+name: ${cleanName}
+description: ${description}
+---
+
+# ${bundleName} 复合技能套件
+
+${description}
+
+## ActionDock 运行时初始化
+
+本技能为 **ActionDock 复合工作区技能包**，聚合了多个功能包。智能体在初次调用或初始化时，在当前技能根目录执行注册命令：
+
+\`\`\`bash
+ad link "<skill_root>"
+\`\`\`
+
+> \`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。
+
+## 动作参数契约按需调阅
+
+为节省上下文开销，各 Action 的详细参数结构不静态内嵌在说明书中。在调用未知参数的 Action 前，可在终端执行命令查阅输入输出约束：
+
+\`\`\`bash
+ad action show ${sampleActionId}
+\`\`\`
+
+## 可用 Action 工具清单
+
+${actionSections}
+
+---
+
+${playbookSection}
+## 标准调用命令
+
+推荐使用参数文件传递内容，杜绝终端引号转义问题：
+
+\`\`\`bash
+cat << 'EOF' > /tmp/input.json
+{
+  "param": "value"
+}
+EOF
+ad run ${sampleActionId} --input-file /tmp/input.json
+\`\`\`
+
+### 结构化响应解析
+
+所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON 信封：
+
+\`\`\`json
+// 执行成功响应 (ok 为 true)
+{
+  "ok": true,
+  "runId": "01J...",
+  "data": { ... }
+}
+
+// 执行失败响应 (ok 为 false)
+{
+  "ok": false,
+  "runId": "01J...",
+  "error": {
+    "code": "ACTION_EXECUTION_FAILED",
+    "message": "错误详细描述信息"
+  }
+}
+\`\`\`
+`;
+}
+
+
 export interface GenerateSkillJsonOptions {
   mode?: "source" | "standalone";
   executable?: string;

package/src/project/init.ts

@@ -108,10 +108,10 @@ export function initProject(targetDir: string, options: InitOptions = {}): void
       node: ">=22.12.0",
     },
     dependencies: {
-      "@actiondock/sdk": "^2.0.10",
+      "@actiondock/sdk": "2.0.11-beta.0",
     },
     devDependencies: {
-      "@actiondock/testing": "^2.0.10",
+      "@actiondock/testing": "2.0.11-beta.0",
       "@types/node": "^22.12.0",
       "tsx": "^4.19.0",
       "typescript": "^5.7.0",

package/src/registry/registry.ts

@@ -348,6 +348,149 @@ async function projectHasAction(
   }
 }
 
+function projectHasActionSync(
+  projectRoot: string,
+  actionsDir: string | undefined,
+  actionId: string
+): boolean {
+  const manifest = loadManifest(projectRoot);
+  if (manifest?.actions && actionId in manifest.actions) {
+    return true;
+  }
+  const dir = join(projectRoot, actionsDir || "actions");
+  if (!existsSync(dir)) {
+    return false;
+  }
+  if (actionId.includes("..") || actionId.startsWith("/") || actionId.startsWith("\\")) {
+    return false;
+  }
+  if (existsSync(join(dir, `${actionId}.ts`)) || existsSync(join(dir, `${actionId}.js`))) {
+    return true;
+  }
+  const relFile = actionId.replace(/\./g, "/");
+  if (existsSync(join(dir, `${relFile}.ts`)) || existsSync(join(dir, `${relFile}.js`))) {
+    return true;
+  }
+  return false;
+}
+
+export function resolveActionProjectSync(
+  actionIdentifier: string,
+  cwd: string = process.cwd(),
+  customHome?: string
+): ResolvedActionProject {
+  // 1. Check current directory / parent project
+  const currentRoot = findProjectRoot(cwd);
+  if (currentRoot) {
+    try {
+      const config = loadProjectConfig(currentRoot);
+      if (projectHasActionSync(currentRoot, config.actionsDir, actionIdentifier)) {
+        return {
+          projectRoot: currentRoot,
+          packageId: config.id,
+          actionId: actionIdentifier,
+        };
+      }
+    } catch {
+      // Ignore and proceed to registry lookup
+    }
+  }
+
+  // 2. Check if scoped format: <package-id>/<action-id> or <package-id>:<action-id>
+  let targetPackage: string | undefined;
+  let pureActionId = actionIdentifier;
+
+  if (actionIdentifier.includes("/")) {
+    const slashIdx = actionIdentifier.lastIndexOf("/");
+    targetPackage = actionIdentifier.slice(0, slashIdx);
+    pureActionId = actionIdentifier.slice(slashIdx + 1);
+  } else if (actionIdentifier.includes(":")) {
+    const colonIdx = actionIdentifier.lastIndexOf(":");
+    targetPackage = actionIdentifier.slice(0, colonIdx);
+    pureActionId = actionIdentifier.slice(colonIdx + 1);
+  }
+
+  const linkedList = listLinkedPackages(customHome);
+
+  if (targetPackage) {
+    let targetRoot: string | undefined;
+    let targetPkgId = targetPackage;
+
+    const pkg = linkedList.find(
+      (p) => p.id === targetPackage || getPackageSlug(p.id) === targetPackage
+    );
+    if (pkg && existsSync(pkg.path)) {
+      targetRoot = pkg.path;
+      targetPkgId = pkg.id;
+    } else if (currentRoot) {
+      try {
+        const config = loadProjectConfig(currentRoot);
+        if (config.id === targetPackage || getPackageSlug(config.id) === targetPackage) {
+          targetRoot = currentRoot;
+          targetPkgId = config.id;
+        }
+      } catch {
+        // Ignore
+      }
+    }
+
+    if (!targetRoot || !existsSync(targetRoot)) {
+      throw new Error(
+        `Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ad link' in the package directory.`
+      );
+    }
+
+    const config = loadProjectConfig(targetRoot);
+    if (!projectHasActionSync(targetRoot, config.actionsDir, pureActionId)) {
+      throw new Error(`Action '${pureActionId}' not found in package '${targetPkgId}' (${targetRoot})`);
+    }
+
+    return {
+      projectRoot: targetRoot,
+      packageId: targetPkgId,
+      actionId: pureActionId,
+    };
+  }
+
+  // 3. Search across all linked packages
+  const matches: Array<{ entry: LinkedPackageEntry; actionId: string }> = [];
+
+  for (const pkg of linkedList) {
+    if (!existsSync(pkg.path)) continue;
+    try {
+      const config = loadProjectConfig(pkg.path);
+      if (projectHasActionSync(pkg.path, config.actionsDir, actionIdentifier)) {
+        matches.push({ entry: pkg, actionId: actionIdentifier });
+      }
+    } catch {
+      // Ignore invalid linked package
+    }
+  }
+
+  if (matches.length === 1) {
+    return {
+      projectRoot: matches[0].entry.path,
+      packageId: matches[0].entry.id,
+      actionId: matches[0].actionId,
+    };
+  }
+
+  if (matches.length > 1) {
+    const pkgList = matches.map((m) => `'${m.entry.id}'`).join(", ");
+    throw new Error(
+      `Action '${actionIdentifier}' is provided by multiple linked packages: ${pkgList}. Please specify using '<package-id>/${actionIdentifier}'.`
+    );
+  }
+
+  if (currentRoot) {
+    throw new Error(`Action '${actionIdentifier}' not found in current project or any linked packages`);
+  } else {
+    throw new Error(
+      `Action '${actionIdentifier}' not found. You are not in an ActionDock project, and no linked package provides '${actionIdentifier}'. Use 'ad link' to register your package.`
+    );
+  }
+}
+
 export async function resolveActionProject(
   actionIdentifier: string,
   cwd: string = process.cwd(),
@@ -375,11 +518,11 @@ export async function resolveActionProject(
   let pureActionId = actionIdentifier;
 
   if (actionIdentifier.includes("/")) {
-    const slashIdx = actionIdentifier.indexOf("/");
+    const slashIdx = actionIdentifier.lastIndexOf("/");
     targetPackage = actionIdentifier.slice(0, slashIdx);
     pureActionId = actionIdentifier.slice(slashIdx + 1);
   } else if (actionIdentifier.includes(":")) {
-    const colonIdx = actionIdentifier.indexOf(":");
+    const colonIdx = actionIdentifier.lastIndexOf(":");
     targetPackage = actionIdentifier.slice(0, colonIdx);
     pureActionId = actionIdentifier.slice(colonIdx + 1);
   }

package/src/runtime/context.ts

@@ -3,6 +3,7 @@ import type {
   ActionContext,
   ActionDefinition,
   ActionInvoker,
+  ActionRef,
   Config,
   Logger,
   ProcessAPI,
@@ -196,7 +197,7 @@ export interface ContextOptions {
   progress?: ProgressReporter;
   logger?: Logger;
   onActionInvoke?: (
-    action: ActionDefinition,
+    action: ActionDefinition | ActionRef | string,
     input: unknown,
     parentRunId?: string
   ) => Promise<unknown>;
@@ -221,7 +222,10 @@ export function createActionContext(options: ContextOptions): ActionContext {
   const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
 
   const invoker: ActionInvoker = {
-    async invoke<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O> {
+    async invoke<I, O>(
+      action: ActionDefinition<I, O> | ActionRef | string,
+      input?: I
+    ): Promise<O> {
       if (options.onActionInvoke) {
         return (await options.onActionInvoke(
           action as any,

package/src/runtime/runner.ts

@@ -1,7 +1,9 @@
+import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import type {
   ActionContext,
   ActionDefinition,
+  ActionRef,
   ExecutionResult,
   JsonValue,
   Logger,
@@ -10,7 +12,10 @@ import type {
   RuntimeError,
   RunRecord,
 } from "@actiondock/sdk";
+import { ActionResolver } from "../catalog/action-resolver";
+import { loadActions, loadProjectConfig } from "../project/loader";
 import type { ProjectConfig } from "../project/types";
+import { resolveActionProject } from "../registry/registry";
 import { validateSchema } from "../schema/validator";
 import type { RuntimeStorage, TerminalRunStatus } from "../storage/types";
 import { createActionContext, StderrLogger } from "./context";
@@ -31,6 +36,11 @@ export interface RunnerOptions {
   actions?: Map<string, ActionDefinition>;
   /** 外部注入的进程执行器 */
   process?: ProcessAPI;
+  /** 动态解析跨包或未注册 Action 的委托函数 */
+  actionResolver?: (
+    ref: ActionRef | string,
+    currentPackageId?: string
+  ) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
 }
 
 /**
@@ -95,6 +105,10 @@ export class ActionRunner {
   private projectConfig?: ProjectConfig;
   private configOverrides: Record<string, unknown>;
   private actions: Map<string, ActionDefinition>;
+  private actionResolver?: (
+    ref: ActionRef | string,
+    currentPackageId?: string
+  ) => ActionDefinition | undefined | Promise<ActionDefinition | undefined>;
 
   constructor(options: RunnerOptions) {
     this.packageId = options.packageId;
@@ -102,6 +116,7 @@ export class ActionRunner {
     this.projectConfig = options.projectConfig;
     this.configOverrides = options.configOverrides || {};
     this.actions = options.actions || new Map();
+    this.actionResolver = options.actionResolver;
   }
 
   /**
@@ -118,6 +133,86 @@ export class ActionRunner {
     return this.actions.get(id);
   }
 
+  /**
+   * 动态解析 Action（支持本地注册表、自定义解析器委托与已链接包目录索引检索）。
+   * 
+   * @param actionOrRef Action 定义对象、引用或标识符
+   * @returns 解析出的 ActionDefinition，若未找到则返回 undefined
+   */
+  public async resolveAction(
+    actionOrRef: ActionDefinition | ActionRef | string
+  ): Promise<ActionDefinition | undefined> {
+    if (
+      typeof actionOrRef === "object" &&
+      "run" in actionOrRef &&
+      typeof (actionOrRef as any).run === "function"
+    ) {
+      return actionOrRef as ActionDefinition;
+    }
+
+    const ref = actionOrRef as ActionRef | string;
+    const parsed = ActionResolver.parseRef(ref);
+    const targetActionId = parsed.actionId;
+    const targetPackageId = parsed.packageId;
+
+    // 1. 本地 actions 映射表优先检索
+    if (targetPackageId && targetPackageId !== this.packageId) {
+      if (this.actions.has(`${targetPackageId}/${targetActionId}`)) {
+        return this.actions.get(`${targetPackageId}/${targetActionId}`);
+      }
+    } else {
+      if (this.actions.has(targetActionId)) {
+        return this.actions.get(targetActionId);
+      }
+      if (this.packageId && this.actions.has(`${this.packageId}/${targetActionId}`)) {
+        return this.actions.get(`${this.packageId}/${targetActionId}`);
+      }
+    }
+
+    // 2. 外部注入的自定义 actionResolver 调度
+    if (this.actionResolver) {
+      const customResolved = await this.actionResolver(ref, this.packageId);
+      if (customResolved) {
+        if (targetPackageId && targetPackageId !== this.packageId) {
+          this.actions.set(`${targetPackageId}/${targetActionId}`, customResolved);
+        } else {
+          this.actions.set(targetActionId, customResolved);
+          if (this.packageId) {
+            this.actions.set(`${this.packageId}/${targetActionId}`, customResolved);
+          }
+        }
+        return customResolved;
+      }
+    }
+
+    // 3. 基于全局链接注册表与目录索引的动态寻址与按需加载
+    try {
+      const identifier = targetPackageId
+        ? `${targetPackageId}/${targetActionId}`
+        : targetActionId;
+      const resolved = await resolveActionProject(identifier);
+      if (resolved && existsSync(resolved.projectRoot)) {
+        const config = loadProjectConfig(resolved.projectRoot);
+        const actionsMap = await loadActions(resolved.projectRoot, config.actionsDir, {
+          autoInstall: false,
+        });
+        const matched = actionsMap.get(resolved.actionId);
+        if (matched) {
+          this.actions.set(`${resolved.packageId}/${resolved.actionId}`, matched);
+          // 仅当目标包就是当前项目时才注册短标识符，避免跨包动态载入污染全局短标识符
+          if (!targetPackageId || resolved.packageId === this.packageId) {
+            this.actions.set(resolved.actionId, matched);
+          }
+          return matched;
+        }
+      }
+    } catch {
+      // 忽略寻址异常并返回 undefined
+    }
+
+    return undefined;
+  }
+
   /**
    * 获取当前 Runner 已注册的所有 Action 列表。
    */
@@ -128,13 +223,13 @@ export class ActionRunner {
   /**
    * 异步启动 Action 的执行并立即返回 ExecutionHandle 句柄。
    * 
-   * @param actionOrId Action 定义对象或已注册的 Action ID
+   * @param actionOrId Action 定义对象、引用或标识符
    * @param input 传递给 Action 的输入数据
    * @param options 执行控制选项（超时、取消信号、父运行 ID 等）
    * @returns 包含 runId、result Promise 和 cancel 方法的执行句柄
    */
   start(
-    actionOrId: ActionDefinition | string,
+    actionOrId: ActionDefinition | ActionRef | string,
     input: unknown = {},
     options: ExecutionStartOptions = {}
   ): ExecutionHandle {
@@ -142,30 +237,47 @@ export class ActionRunner {
     const startedAt = new Date().toISOString();
     const callStack = [...(options.callStack || [])];
 
-    let action: ActionDefinition;
-    if (typeof actionOrId === "string") {
-      const found = this.actions.get(actionOrId);
-      if (!found) {
-        const error: RuntimeError = {
-          code: "ACTION_NOT_FOUND",
-          message: `Action '${actionOrId}' not found in registry`,
-        };
-        return {
-          runId,
-          result: Promise.resolve({ ok: false, runId, error }),
-          cancel: () => false,
-        };
-      }
-      action = found;
+    let action: ActionDefinition | undefined;
+    let targetActionId: string;
+    let targetPackageId: string = this.packageId;
+
+    if (
+      typeof actionOrId === "object" &&
+      "run" in actionOrId &&
+      typeof (actionOrId as any).run === "function"
+    ) {
+      action = actionOrId as ActionDefinition;
+      targetActionId = action.id;
     } else {
-      action = actionOrId;
+      const parsed = ActionResolver.parseRef(actionOrId as ActionRef | string);
+      targetActionId = parsed.actionId;
+      if (parsed.packageId) {
+        targetPackageId = parsed.packageId;
+      }
+
+      if (parsed.packageId && parsed.packageId !== this.packageId) {
+        action = this.actions.get(`${parsed.packageId}/${targetActionId}`);
+      } else {
+        action =
+          this.actions.get(targetActionId) ||
+          (this.packageId ? this.actions.get(`${this.packageId}/${targetActionId}`) : undefined);
+      }
     }
 
     // 1. 环路死锁检测 (Cycle Detection)
-    if (callStack.includes(action.id)) {
+    const isExternal = Boolean(targetPackageId && targetPackageId !== this.packageId);
+    const callKey = isExternal
+      ? `${targetPackageId}/${targetActionId}`
+      : targetActionId;
+
+    const hasCycle = isExternal
+      ? callStack.includes(callKey)
+      : (callStack.includes(callKey) || (this.packageId ? callStack.includes(`${this.packageId}/${targetActionId}`) : false));
+
+    if (hasCycle) {
       const error: RuntimeError = {
         code: "ACTION_CYCLE_DETECTED",
-        message: `Cycle detected in action invocation: ${callStack.join(" -> ")} -> ${action.id}`,
+        message: `Cycle detected in action invocation: ${callStack.join(" -> ")} -> ${callKey}`,
       };
       return {
         runId,
@@ -173,10 +285,10 @@ export class ActionRunner {
         cancel: () => false,
       };
     }
-    callStack.push(action.id);
+    callStack.push(callKey);
 
-    // 2. 输入参数 JSON Schema 校验
-    if (action.inputSchema) {
+    // 2. 输入参数 JSON Schema 校验（若 action 已就绪）
+    if (action?.inputSchema) {
       const val = validateSchema(action.inputSchema, input);
       if (!val.valid) {
         const error: RuntimeError = {
@@ -197,9 +309,9 @@ export class ActionRunner {
       id: runId,
       rootRunId: options.rootRunId || options.parentRunId || runId,
       parentRunId: options.parentRunId,
-      packageId: this.packageId,
-      packageInstanceId: options.packageInstanceId || this.packageId,
-      actionId: action.id,
+      packageId: targetPackageId,
+      packageInstanceId: options.packageInstanceId || targetPackageId,
+      actionId: targetActionId,
       generationId: options.generationId || "1",
       ownerId: options.ownerId || "local",
       status: "running",
@@ -257,7 +369,7 @@ export class ActionRunner {
       signal: controller.signal,
       process: options.process,
       progress: options.progress,
-      logger: options.logger || new StderrLogger(action.id),
+      logger: options.logger || new StderrLogger(action?.id || targetActionId),
       onActionInvoke: async (childAction, childInput, parentRunId) => {
         const childResult = await this.execute(childAction, childInput, {
           rootRunId: initialRun.rootRunId,
@@ -293,18 +405,44 @@ export class ActionRunner {
 
     const executionPromise = (async (): Promise<ExecutionResult> => {
       try {
+        let currentAction = action;
+        if (!currentAction) {
+          currentAction = await this.resolveAction(actionOrId);
+          if (!currentAction) {
+            const error: RuntimeError = {
+              code: "ACTION_NOT_FOUND",
+              message: `Action '${targetActionId}' not found in registry or linked packages`,
+            };
+            finalizeRun("failed", undefined, error);
+            return { ok: false, runId, error };
+          }
+
+          if (currentAction.inputSchema) {
+            const val = validateSchema(currentAction.inputSchema, input);
+            if (!val.valid) {
+              const error: RuntimeError = {
+                code: "INPUT_VALIDATION_FAILED",
+                message: `Input schema validation failed for action '${currentAction.id}'`,
+                details: val.errors,
+              };
+              finalizeRun("failed", undefined, error);
+              return { ok: false, runId, error };
+            }
+          }
+        }
+
         const rawOutput = await Promise.race([
-          Promise.resolve().then(() => action.run(input, ctx)),
+          Promise.resolve().then(() => currentAction!.run(input, ctx)),
           abortPromise,
         ]);
 
         // 输出结果 Schema 校验
-        if (action.outputSchema) {
-          const outVal = validateSchema(action.outputSchema, rawOutput);
+        if (currentAction.outputSchema) {
+          const outVal = validateSchema(currentAction.outputSchema, rawOutput);
           if (!outVal.valid) {
             const error: RuntimeError = {
               code: "OUTPUT_VALIDATION_FAILED",
-              message: `Output schema validation failed for action '${action.id}'`,
+              message: `Output schema validation failed for action '${currentAction.id}'`,
               details: outVal.errors,
             };
             finalizeRun("failed", undefined, error);
@@ -375,12 +513,12 @@ export class ActionRunner {
   /**
    * 同步等待方式执行指定 Action，直接返回 ExecutionResult 信封结果。
    * 
-   * @param actionOrId Action 定义对象或 ID
+   * @param actionOrId Action 定义对象、引用或标识符
    * @param input 输入参数
    * @param options 执行控制选项
    */
   async execute(
-    actionOrId: ActionDefinition | string,
+    actionOrId: ActionDefinition | ActionRef | string,
     input: unknown = {},
     options: ExecutionStartOptions = {}
   ): Promise<ExecutionResult> {