@actiondock/cli 2.10.0 → 2.11.0

package/README.md

@@ -166,7 +166,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad remove <package>` | 卸载并更新锁定依赖，提供原子回滚保护 |
 | `ad info [patterns...]` | 检索包元数据与能力清单，支持模式匹配与树形展示 |
 | `ad list [patterns...]` | 列出包内所有已注册的 Action |
-| `ad describe <id>` | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引与建议赋值（别名 `ad show`） |
+| `ad describe <id>` | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引与建议赋值 |
 | `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--json` 输出标准信封） |
 | `ad validate [id]` | 校验 Action 规范与模式规范 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
@@ -174,7 +174,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad playbook list` / `show` | 查看智能体操作规程 Playbook |
 | `ad config list` / `get` / `set` | 管理包运行时配置与环境变量绑定 |
 | `ad state list` / `get` / `set` / `delete` / `clear` | 查看与维护 SQLite 持久化状态 |
-| `ad runs list` / `show` / `clear` | 查询任务执行历史与追踪记录，或按时间与数量策略清理历史数据 |
+| `ad runs list` / `show` / `watch` / `clear` | 查询任务执行历史、阻塞等待运行终态聚合退出，或按时间与数量策略清理历史数据；list 支持 `--request-id` 过滤，watch 支持按 `--request-id` 反查等待（后台派工场景主控无 runId 时使用） |
 | `ad test` | 执行快速单元测试 |
 | `ad build` | 构建 Node.js 目录交付产物（支持 `--vendor-deps` 与 `--archive`） |
 | `ad pack` | 打包为标准 npm tarball（`.tgz`），支持 `--dry-run` |

package/bin/ad.js

@@ -1,8 +1,26 @@
 #!/usr/bin/env node
+import { enableCompileCache } from "node:module";
+try {
+  enableCompileCache?.();
+} catch {}
+try {
+  await import("@actiondock/core/warning");
+} catch {
+  try {
+    const { resolve } = await import("node:path");
+    const { existsSync } = await import("node:fs");
+    const { pathToFileURL } = await import("node:url");
+    const coreWarningSrc = resolve(import.meta.dirname, "../../core/src/utils/warning.ts");
+    if (existsSync(coreWarningSrc)) {
+      await import(pathToFileURL(coreWarningSrc).href);
+    }
+  } catch {}
+}
+
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { resolve } from "node:path";
+import { resolve, dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const isBun = typeof process.versions.bun !== "undefined";
@@ -10,11 +28,206 @@ const hasTsx =
   process.execArgv.some((arg, i) => arg === "--import" && process.execArgv[i + 1]?.includes("tsx")) ||
   process.execArgv.some((arg) => arg.includes("tsx"));
 
-if (!isBun && !hasTsx) {
+const nodeMajor = parseInt(process.versions.node?.split(".")[0] || "0", 10);
+const hasNativeTypeStripping =
+  nodeMajor >= 24 ||
+  Boolean(process.features?.typescript) ||
+  process.execArgv.includes("--experimental-strip-types") ||
+  process.execArgv.includes("--experimental-transform-types") ||
+  Boolean(process.env.NODE_OPTIONS?.includes("--experimental-strip-types")) ||
+  Boolean(process.env.NODE_OPTIONS?.includes("--experimental-transform-types"));
+
+const ROUTINE_COMMANDS = new Set([
+  "list",
+  "info",
+  "describe",
+  "validate",
+  "config",
+  "doctor",
+  "state",
+  "runs",
+  "add",
+  "remove",
+  "init",
+  "new",
+  "link",
+  "unlink",
+  "pack",
+  "generate",
+  "profile",
+  "help",
+]);
+
+function findNearestProjectRoot(startDir = process.cwd()) {
+  let current;
+  try {
+    current = resolve(startDir);
+  } catch {
+    return startDir;
+  }
+  while (true) {
+    if (existsSync(join(current, "actiondock.json"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return startDir;
+}
+
+/**
+ * 决定是否需要派生 tsx 加载器：
+ * - 纯 TypeScript 工程在 Node 24 原生环境下直接执行，绝不派生进程；
+ * - 常规运维与元数据命令（ad -v、ad info、ad list、ad config 等）绝不派生；
+ * - 仅当环境显式要求、或直接执行的 Action / 工程配置声明了 JSX/TSX 等非标准语法时，按需派生 tsx。
+ */
+function checkNeedsTsx(rawArgv) {
+  if (isBun || hasTsx) {
+    return { needsTsx: false, projectRoot: process.cwd() };
+  }
+
+  const explicitTsx =
+    process.env.ACTIONDOCK_FORCE_TSX === "1" ||
+    process.env.ACTIONDOCK_FORCE_TSX === "true" ||
+    process.env.ACTIONDOCK_TSX === "1" ||
+    process.env.ACTIONDOCK_TSX === "true" ||
+    process.env.TSX === "1" ||
+    rawArgv.includes("--tsx") ||
+    rawArgv.includes("--force-tsx");
+
+  if (explicitTsx) {
+    return { needsTsx: true, projectRoot: process.cwd() };
+  }
+
+  if (!hasNativeTypeStripping) {
+    return { needsTsx: true, projectRoot: process.cwd() };
+  }
+
+  if (
+    rawArgv.length === 0 ||
+    rawArgv.includes("-v") ||
+    rawArgv.includes("--version") ||
+    rawArgv.includes("-V") ||
+    rawArgv.includes("-h") ||
+    rawArgv.includes("--help")
+  ) {
+    return { needsTsx: false, projectRoot: process.cwd() };
+  }
+
+  let mainCommand = null;
+  let actionTarget = null;
+  let targetDir = process.cwd();
+
+  for (let i = 0; i < rawArgv.length; i++) {
+    const token = rawArgv[i];
+    if (token === "--cwd" || token === "-C" || token === "--project" || token === "--dir") {
+      const next = rawArgv[i + 1];
+      if (next && !next.startsWith("-")) {
+        try {
+          targetDir = resolve(next);
+        } catch {}
+      }
+      i++;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      continue;
+    }
+    if (!mainCommand) {
+      mainCommand = token;
+      continue;
+    }
+    if (!actionTarget) {
+      actionTarget = token;
+      break;
+    }
+  }
+
+  if (!mainCommand || ROUTINE_COMMANDS.has(mainCommand)) {
+    return { needsTsx: false, projectRoot: targetDir };
+  }
+
+  if (mainCommand === "action") {
+    if (!actionTarget || actionTarget === "create") {
+      return { needsTsx: false, projectRoot: targetDir };
+    }
+  } else if (mainCommand === "playbook") {
+    if (!actionTarget || actionTarget === "list" || actionTarget === "show" || actionTarget === "validate" || actionTarget === "create") {
+      return { needsTsx: false, projectRoot: targetDir };
+    }
+  }
+
+  if (actionTarget && (actionTarget.endsWith(".tsx") || actionTarget.endsWith(".jsx"))) {
+    return { needsTsx: true, projectRoot: targetDir };
+  }
+
+  const projectRoot = findNearestProjectRoot(targetDir);
+
+  const manifestPath = join(projectRoot, "actiondock.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+      if (
+        manifest.jsx === true ||
+        manifest.tsx === true ||
+        manifest.transpile === true ||
+        manifest.runtime === "tsx" ||
+        manifest.runtime?.transpiler === "tsx" ||
+        Boolean(manifest.compilerOptions?.jsx)
+      ) {
+        return { needsTsx: true, projectRoot };
+      }
+
+      if (actionTarget && manifest.actions?.[actionTarget]?.entry) {
+        const entry = String(manifest.actions[actionTarget].entry);
+        if (entry.endsWith(".tsx") || entry.endsWith(".jsx")) {
+          return { needsTsx: true, projectRoot };
+        }
+      }
+
+      if (manifest.actions) {
+        for (const entry of Object.values(manifest.actions)) {
+          if (typeof entry?.entry === "string" && (entry.entry.endsWith(".tsx") || entry.entry.endsWith(".jsx"))) {
+            return { needsTsx: true, projectRoot };
+          }
+        }
+      }
+    } catch {}
+  }
+
+  const tsconfigPath = join(projectRoot, "tsconfig.json");
+  if (existsSync(tsconfigPath)) {
+    try {
+      const content = readFileSync(tsconfigPath, "utf-8");
+      if (/"jsx"\s*:/i.test(content)) {
+        return { needsTsx: true, projectRoot };
+      }
+    } catch {}
+  }
+
+  const pkgPath = join(projectRoot, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.jsx) {
+        return { needsTsx: true, projectRoot };
+      }
+    } catch {}
+  }
+
+  return { needsTsx: false, projectRoot };
+}
+
+const rawArgv = process.argv.slice(2);
+const { needsTsx, projectRoot } = checkNeedsTsx(rawArgv);
+
+if (needsTsx) {
   const require = createRequire(import.meta.url);
   let tsxSpecifier = null;
+  const searchPaths = [import.meta.dirname, process.cwd(), projectRoot];
   try {
-    tsxSpecifier = pathToFileURL(require.resolve("tsx", { paths: [import.meta.dirname, process.cwd()] })).href;
+    tsxSpecifier = pathToFileURL(require.resolve("tsx", { paths: searchPaths })).href;
   } catch {
     try {
       tsxSpecifier = pathToFileURL(require.resolve("tsx")).href;
@@ -24,9 +237,16 @@ if (!isBun && !hasTsx) {
   }
 
   if (tsxSpecifier) {
+    const extraFlags = [];
+    if (process.env.ACTIONDOCK_SILENCE_WARNINGS !== "0") {
+      extraFlags.push("--no-warnings=ExperimentalWarning");
+    }
+    if (nodeMajor >= 24) {
+      extraFlags.push("--no-strip-types");
+    }
     const child = spawn(
       process.execPath,
-      ["--import", tsxSpecifier, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+      [...extraFlags, "--import", tsxSpecifier, fileURLToPath(import.meta.url), ...rawArgv],
       {
         stdio: "inherit",
       }

package/dist/commands/action/create.d.ts

@@ -8,7 +8,7 @@ export declare function parseSchemaFields(rawFields?: string[] | string): {
     required: string[];
 } | null;
 /**
- * 注册 action 命令组（action create, action list, action describe, action run, action validate）。
+ * 注册 action 命令组（仅保留脚手架创建指令 action create）。
  *
  * @param program Commander 根程序对象
  * @param context 命令行上下文

package/dist/commands/action/create.js

@@ -4,10 +4,6 @@ import { assertPathWithinRoot, getPackageSlug, loadManifest, saveManifest, write
 import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
 import { ExecutionError, notInProjectError, wrapAsExecutionError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
-import { attachDescribeCommand } from "../describe.js";
-import { attachListCommand } from "../list.js";
-import { attachRunCommand } from "../run.js";
-import { attachValidateCommand } from "../validate.js";
 /**
  * 解析用户通过命令行传入的字段定义字符串（如 name:string, count?:number）。
  */
@@ -63,7 +59,7 @@ export function parseSchemaFields(rawFields) {
     return { properties, required };
 }
 /**
- * 注册 action 命令组（action create, action list, action describe, action run, action validate）。
+ * 注册 action 命令组（仅保留脚手架创建指令 action create）。
  *
  * @param program Commander 根程序对象
  * @param context 命令行上下文
@@ -71,7 +67,7 @@ export function parseSchemaFields(rawFields) {
 export function registerActionCommands(program, context) {
     const actionCmd = program
         .command("action")
-        .description("Manage Action definitions and lifecycle (create, list, describe, run, validate)");
+        .description("Manage Action definitions and scaffolding (create)");
     actionCmd
         .command("create <id>")
         .description("Scaffold a new Action definition file")
@@ -82,10 +78,6 @@ export function registerActionCommands(program, context) {
         .action(async (id, options) => {
         await handleActionCreate(id, options, context);
     });
-    attachListCommand(actionCmd, context);
-    attachDescribeCommand(actionCmd, context);
-    attachRunCommand(actionCmd, context);
-    attachValidateCommand(actionCmd, context);
 }
 export async function handleActionCreate(id, options, context) {
     const root = findProjectRoot();
@@ -204,11 +196,11 @@ ${returnBody}
         // 始终自动生成或更新类型声明文件，确保单一事实源即时生效
         writeActionTypes(root, manifest);
         writeStdout(`[OK] Created Action '${id}' at ${targetFullFile}`, context);
-        writeStdout(`\n查阅参数契约:`, context);
+        writeStdout(`\nParameter contract:`, context);
         writeStdout(`  ad describe ${id}`, context);
-        writeStdout(`\n调用方式:`, context);
-        writeStdout(`  根据 describe 输出的赋值模板传递参数：ad run ${id} --json -- ASSIGNMENT...`, context);
-        writeStdout(`  复杂输入或大段文本：ad run ${id} --json --input-file input.json`, context);
+        writeStdout(`\nUsage:`, context);
+        writeStdout(`  Pass parameters according to describe assignment template: ad run ${id} --json -- ASSIGNMENT...`, context);
+        writeStdout(`  Complex input or large text: ad run ${id} --json --input-file input.json`, context);
     }
     catch (err) {
         throw wrapAsExecutionError(err);

package/dist/commands/add.js

@@ -44,7 +44,7 @@ export function registerAddCommand(program, context) {
         const tx = await beginTransaction(root, `ad add ${packageSpec}`);
         try {
             // 调用包管理器执行安装（默认禁用生命周期安装脚本）
-            const installCmd = getInstallCommand(root);
+            const installCmd = await getInstallCommand(root);
             const pm = installCmd[0];
             const args = [];
             if (pm === "bun") {

package/dist/commands/config/delete.js

@@ -45,6 +45,8 @@ export function registerConfigDeleteCommand(configCmd, context) {
             const projConfig = loadProjectConfig(root);
             await service.management?.config.delete(projConfig.id, key);
             writeStdout(`[OK] Configuration '${key}' deleted for package '${projConfig.id}'`, context);
-        });
+        }, 
+        // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
+        { localRoot: root || undefined });
     });
 }

package/dist/commands/config/env.js

@@ -1,4 +1,5 @@
-import { fetchRemoteConfigEnv, resolveEnvValue, } from "@actiondock/core/profile";
+import { resolveEnvValue } from "@actiondock/core";
+import { fetchRemoteConfigEnv } from "@actiondock/core/profile";
 import { isSecretConfigKey, } from "@actiondock/core/project";
 import { renderConfigEnv, renderResult } from "../../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, resolveTargetFromOptions } from "../../utils/index.js";

package/dist/commands/config/get.js

@@ -89,6 +89,8 @@ export function registerConfigGetCommand(configCmd, context) {
                 humanFormatter: () => (displayValue !== undefined ? String(displayValue) : ""),
                 context,
             });
-        });
+        }, 
+        // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
+        { localRoot: root || undefined });
     });
 }

package/dist/commands/config/list.js

@@ -1,11 +1,10 @@
 import { fetchRemoteConfig, } from "@actiondock/core/profile";
-import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { loadProjectConfig, } from "@actiondock/core";
 import { filterWithFallbackInfo, isSecretConfigKey, maskSecretValue, } from "@actiondock/core/project";
-import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { packageNotFoundError } from "../../errors.js";
 import { renderConfigList, renderResult } from "../../renderer.js";
 import { buildMergedConfigEntries } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveTargetFromOptions, withService, } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, resolveTargetFromOptions, withService, } from "../../utils/index.js";
 /**
  * 构造单条配置项的展示视图（含掩码决策，reveal 为假且为敏感键时打码）。
  * 掩码决策收敛于命令层，renderer 仅负责值的字符串格式化。
@@ -58,9 +57,9 @@ export function registerConfigListCommand(configCmd, context) {
             });
             return;
         }
-        // 本地分支（通过 Service 门面统一访问）
+        // 本地分支（通过 Service 门面统一访问）：显式包寻址结果作为本地根目录传递（仅 local 分支求值）
         await withService(options, context, async (service) => {
-            const root = options.package ? resolvePackageRoot(options.package) : findProjectRoot();
+            const root = resolveLocalPackageRoot(options.package) || undefined;
             // 全局作用域分支：显式 --global 或无工程回退时仅列举全局配置
             if (options.global || !root) {
                 if (!options.global && options.package) {
@@ -85,6 +84,8 @@ export function registerConfigListCommand(configCmd, context) {
                 humanFormatter: () => renderConfigList(filterRes.items, `${projConfig.name} (${projConfig.id})`, filterRes.isFallback, effectiveIntent),
                 context,
             });
+        }, {
+            localRoot: () => resolveLocalPackageRoot(options.package) || undefined,
         });
     });
 }

package/dist/commands/config/set.js

@@ -79,6 +79,8 @@ export function registerConfigSetCommand(configCmd, context) {
             }
             await service.management?.config.set(projConfig.id, key, parsedVal);
             writeStdout(`[OK] Configuration '${key}' updated for package '${projConfig.id}'`, context);
-        });
+        }, 
+        // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
+        { localRoot: root || undefined });
     });
 }

package/dist/commands/describe.js

@@ -1,7 +1,7 @@
 import { ACTION_NOT_FOUND, PACKAGE_NOT_FOUND, NOT_FOUND, } from "@actiondock/core";
-import { buildActionDescribePayload, formatActionDetail, } from "@actiondock/core/project";
+import { buildActionDescribePayload, } from "@actiondock/core/project";
 import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
-import { renderResult } from "../renderer.js";
+import { formatActionDetail, renderResult } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withService, } from "../utils/index.js";
 /**
  * 挂载 describe 子命令至指定 Commander 节点。
@@ -12,7 +12,6 @@ import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withS
 export function attachDescribeCommand(parent, context) {
     const cmd = parent
         .command("describe <id>")
-        .alias("show")
         .description("Show action definition, schema, and description")
         .option("-P, --package <id>", "Target package ID or path");
     return applyTargetOptions(cmd)

package/dist/commands/export.js

@@ -1,7 +1,7 @@
-import { existsSync } from "node:fs";
-import { basename } from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import { discoverProjects, listLinkedPackages, resolvePackageRoot, } from "@actiondock/core/registry";
-import { findProjectRoot, } from "@actiondock/core";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
 import { ExecutionError, notInProjectError, packageNotFoundError, wrapAsExecutionError } from "../errors.js";
 import { renderResult, writeStdout } from "../renderer.js";
 import { getEffectiveOptions, parseListOption } from "../utils/index.js";
@@ -83,7 +83,7 @@ export function registerExportCommand(program, context) {
         }
         const isMachine = Boolean(options.json);
         try {
-            const { exportCompositeSkill, exportSkill, exportSkillBatch } = await import("@actiondock/builder");
+            const { allocatePackageDirName, exportCompositeSkill, exportSkill } = await import("@actiondock/builder");
             if (options.bundle !== undefined) {
                 const bundleName = typeof options.bundle === "string" && options.bundle.trim()
                     ? options.bundle.trim()
@@ -129,18 +129,36 @@ export function registerExportCommand(program, context) {
                 if (!isMachine) {
                     writeStdout(`Batch exporting ${roots.length} Skill packages...`);
                 }
-                const batchRes = await exportSkillBatch({
-                    projectRoots: roots,
-                    mode,
-                    outDir: options.out,
-                    archive: options.archive,
-                    playbooks: options.playbook,
-                    actions: options.actions,
-                    skillMdPath: options.skillMd,
-                    vendorDeps: options.vendorDeps,
-                    allowInstallScripts: options.allowInstallScripts,
-                    requireReproducible: options.requireReproducible,
-                });
+                const baseOutDir = resolve(options.out || join(process.cwd(), "dist", "skills"));
+                mkdirSync(baseOutDir, { recursive: true });
+                const usedDirNames = new Set();
+                const results = [];
+                for (const projectRoot of roots) {
+                    const config = loadProjectConfig(projectRoot);
+                    const pkgSlug = allocatePackageDirName(usedDirNames, config.id);
+                    const pkgOutDir = join(baseOutDir, `${pkgSlug}-skill`);
+                    const res = await exportSkill({
+                        projectRoot,
+                        mode,
+                        outDir: pkgOutDir,
+                        archive: options.archive,
+                        playbooks: options.playbook,
+                        actions: options.actions,
+                        skillMdPath: options.skillMd,
+                        vendorDeps: options.vendorDeps,
+                        allowInstallScripts: options.allowInstallScripts,
+                        requireReproducible: options.requireReproducible,
+                    });
+                    results.push(res);
+                }
+                const totalActions = results.reduce((sum, r) => sum + r.actionsCount, 0);
+                const totalPlaybooks = results.reduce((sum, r) => sum + r.playbooksCount, 0);
+                const batchRes = {
+                    results,
+                    outDir: baseOutDir,
+                    totalActions,
+                    totalPlaybooks,
+                };
                 renderResult(batchRes, {
                     json: isMachine,
                     humanFormatter: () => {

package/dist/commands/index.d.ts

@@ -1,31 +1,44 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
-import { registerActionCommands } from "./action/index.js";
-import { registerAddCommand } from "./add.js";
-import { registerBuildCommand } from "./build.js";
-import { registerConfigCommands } from "./config/index.js";
-import { registerDescribeCommand } from "./describe.js";
-import { registerDoctorCommand } from "./doctor.js";
-import { registerExportCommand } from "./export.js";
-import { registerGenerateCommands } from "./generate.js";
-import { registerInfoCommand } from "./info.js";
-import { registerInitCommand } from "./init.js";
-import { registerLinkCommands } from "./link.js";
-import { registerListCommand } from "./list.js";
-import { registerMcpCommands } from "./mcp.js";
-import { registerPackCommand } from "./pack.js";
-import { registerPlaybookCommands } from "./playbook.js";
-import { registerProfileCommands } from "./profile.js";
-import { registerRemoveCommand } from "./remove.js";
-import { registerRunCommand } from "./run.js";
-import { registerRunsCommands } from "./runs.js";
-import { registerServeCommand } from "./serve.js";
-import { registerStateCommands } from "./state.js";
-import { registerTestCommand } from "./test.js";
-import { registerValidateCommand } from "./validate.js";
 /**
  * CLI 版本号（来自 package.json 单一事实源）。
  */
 export declare const CLI_VERSION: string;
+/**
+ * 判断命令行参数数组是否以宿主运行环境（node、bun、tsx 等）及入口脚本为前置元素。
+ */
+export declare function isNodeArgv(argv: readonly string[]): boolean;
+/**
+ * 从命令行参数数组中解析出目标子命令名称（跳过全局选项与启动包装参数）。
+ *
+ * @param argv 命令行原始参数数组
+ * @param parseOptions Commander 解析选项（如 { from: 'user' }）
+ * @returns 目标子命令名称或 null
+ */
+export declare function resolveTargetSubcommand(argv: readonly string[], parseOptions?: {
+    from?: string;
+}): string | null;
 export declare function createCliProgram(context?: CliContext): Command;
-export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };
+export declare const registerActionCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerAddCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerBuildCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerConfigCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerDescribeCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerDoctorCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerExportCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerGenerateCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerInfoCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerInitCommand: (program: Command) => Promise<any>;
+export declare const registerLinkCommands: (program: Command) => Promise<any>;
+export declare const registerListCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerMcpCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerPackCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerPlaybookCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerProfileCommands: (program: Command) => Promise<any>;
+export declare const registerRemoveCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerRunCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerRunsCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerServeCommand: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerStateCommands: (program: Command, context?: CliContext) => Promise<any>;
+export declare const registerTestCommand: (program: Command) => Promise<any>;
+export declare const registerValidateCommand: (program: Command, context?: CliContext) => Promise<any>;