@actiondock/cli 2.6.0 → 2.7.0

package/README.md

@@ -51,10 +51,13 @@ ad add @actiondock/example-tools
 
 - 本地执行 Action：
 ```bash
-# 简单参数直接内联传递
-ad run sample.greet --input '{"name": "Alice"}'
+# 扁平参数赋值（规范语法，推荐）
+ad run sample.greet -- name=Alice
 
-# 复杂参数或对象从文件读取
+# 传递 JSON 标量与结构（数值校验为有限数）
+ad run sample.greet -- name=Alice count:=1
+
+# 复杂参数或对象从文件读取（与扁平参数互斥）
 ad run sample.greet --input-file input.json
 
 # 自动化与脚本通过标准输入传递
@@ -109,20 +112,31 @@ ad pack
 
 ### Action 执行入参契约
 
-执行 Action 支持两种互斥的传参方式：
-
-- 简单内联参数：使用 `--input <json>` 直接解析 JSON 字符串，适合简易标量入参。
-- 复杂对象文件：使用 `--input-file <path>` 读取文件并解析 JSON，避免各类终端的引号转义损坏。
-- 标准输入管道：使用 `--input-file -` 从标准输入读取全部数据并解析 JSON，适合跨进程协同与 CI 自动化脚本。
-- 默认无输入：未指定 `--input` 与 `--input-file` 时，入参默认提供 `{}`。
-- 严格互斥：`--input` 与 `--input-file` 互斥，同时提供时直接报错并退出。
-- 统一解析：无论内联参数、文件还是标准输入，解析前均自动剔除 UTF-8 BOM 标记，且不设人为大小上限。
+执行 Action 推荐使用扁平参数赋值协议，同时支持传统选项，三者之间严格互斥：
+
+- 规范调用语法：`ad run <action> [control-options] -- <assignments...>`。
+- 协议边界：`--` 分隔符作为控制平面选项（如 `--json`、`--config`、`--data-dir`、`--profile` 等）与数据平面（Action 入参）的协议边界。
+- 两种赋值操作符语义：
+  - `path=value`：严格保留为字符串，不执行 JSON 解析与类型猜测。
+  - `path:=json`：严格解析为 JSON 值，递归校验所有数值为有限数（`Number.isFinite`）。
+- 路径语法规则：
+  - 命名段（`^[A-Za-z_][A-Za-z0-9_-]*$`）表示对象属性。
+  - 纯数字段（`^(0|[1-9][0-9]*)$`）表示数组索引，数组索引必须从 0 开始连续编号，拒绝稀疏数组。
+  - 根节点始终物化为对象。
+  - 路径冲突（叶节点与容器冲突、对象与数组冲突、重复赋值）严格拒绝（`INPUT_PATH_CONFLICT`）。
+  - 拦截原型污染敏感属性（`__proto__`、`constructor`、`prototype`）。
+- 三种输入模式互斥：扁平参数、`--input` 与 `--input-file` 严格互斥，不可混用（`INPUT_CONFLICT`）；未指定输入时默认为 `{}`。
+- 传统输入选项：
+  - 简单内联参数：使用 `--input <json>` 直接解析 JSON 字符串。
+  - 复杂对象文件：使用 `--input-file <path>` 读取文件并解析 JSON，避免各类终端的引号转义损坏。
+  - 标准输入管道：使用 `--input-file -` 从标准输入读取全部数据并解析 JSON。
+  - 统一解析：解析前均自动剔除 UTF-8 BOM 标记，且不设人为大小上限。
 
 ### Windows 与多终端传参建议
 
 针对 Windows PowerShell、cmd 以及各终端中复杂 JSON 容易遇到的双引号转义问题，推荐按以下规范传参：
 
-- 简单入参：使用 `--input`，如 `ad run greet --input '{"name":"Alice"}'`。
+- 扁平参数传参（推荐）：使用 `--` 分隔并传参，如 `ad run greet -- name=Alice` 或 `ad run greet -- name=Alice count:=1`。
 - 复杂结构：推荐先保存为 JSON 文件并使用 `--input-file`，如 `ad run complex-action --input-file input.json`。
 - 动态生成输入：通过管道输出配合 `--input-file -` 传递，在 PowerShell 中可执行：
 
@@ -138,8 +152,8 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 
 ### Action 输出模式与机器模式
 
-- **默认原始纯文本输出**：`ad run` 默认采用面向终端人类阅读与 LLM Agent 上下文消费的原始输出模式。直接将执行结果正文内容（如文件 `content`、`text`、`message` 或标量字符串）输出至 stdout（保留真实换行且无 JSON 转义），相关元数据（如文件路径、行号范围、截断标记）独立输出至 stderr，符合 Unix 管道安全原则。执行失败时在 stderr 输出错误详情并以退出码 1 退出。
-- **机器 JSON 格式 (`--json`)**：当需要以程序化方式消费、获取完整结构化数据或被外部系统集成时，传入 `--json`。此时输出标准 JSON 结果（包含 `ok`、`runId`、`data` 或 `error`）。
+- **默认原始纯文本输出**：`ad run` 默认采用面向终端人类阅读与 LLM Agent 上下文消费的原始输出模式。直接将执行结果正文内容（如文件 `content`、`text`、`message` 或标量字符串）输出至 stdout（保留真实换行且无 JSON 转义），相关元数据（如文件路径、行号范围、截断标记）独立输出至 stderr，符合 Unix 管道安全原则。业务执行失败时在 stderr 输出错误详情并以退出码 1 退出。
+- **机器 JSON 格式**（`--json`）：当需要以程序化方式消费、获取完整结构化数据或被外部系统集成时，传入 `--json`。面向智能体调用推荐使用该模式；此时输出标准 JSON 结果（包含 `ok`、`runId`、`data` 或 `error`）；若参数解析出错输出标准错误信封并以退出码 2 退出。
 
 ---
 
@@ -152,8 +166,8 @@ $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 的详情、参数与模式规范（别名 `ad show`） |
-| `ad run <id>` | 本地或远程执行指定 Action（默认输出原始纯文本，支持 `--json` 输出标准信封） |
+| `ad describe <id>` | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引与建议赋值（别名 `ad show`） |
+| `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--json` 输出标准信封） |
 | `ad validate [id]` | 校验 Action 规范与模式规范 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
 | `ad action create <id>` | 创建新 Action 源码（别名 `ad action new`） |

package/bin/ad.js

@@ -8,8 +8,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const distEntry = resolve(import.meta.dirname, "../dist/index.js");
 
 if (existsSync(distEntry)) {
-  const { main } = await import(pathToFileURL(distEntry).href);
-  await main(process.argv);
+  const { runCliProcess } = await import(pathToFileURL(distEntry).href);
+  await runCliProcess(process.argv);
 } else {
   const isBun = typeof process.versions.bun !== "undefined";
   const hasTsx =
@@ -37,6 +37,6 @@ if (existsSync(distEntry)) {
     }
   }
 
-  const { main } = await import("../src/index.ts");
-  await main(process.argv);
+  const { runCliProcess } = await import("../src/index.ts");
+  await runCliProcess(process.argv);
 }

package/dist/commands/action/create.js

@@ -202,27 +202,12 @@ ${returnBody}
         saveManifest(root, manifest);
         // 始终自动生成或更新类型声明文件，确保单一事实源即时生效
         writeActionTypes(root, manifest);
-        let sampleInputStr = "{}";
-        const inputEntries = Object.entries(inputSchema.properties || {});
-        if (inputEntries.length > 0) {
-            const sampleObj = {};
-            for (const [k, prop] of inputEntries) {
-                if (prop.type === "number" || prop.type === "integer")
-                    sampleObj[k] = 42;
-                else if (prop.type === "boolean")
-                    sampleObj[k] = true;
-                else if (prop.type === "array")
-                    sampleObj[k] = ["item"];
-                else if (prop.type === "object")
-                    sampleObj[k] = {};
-                else
-                    sampleObj[k] = "hello";
-            }
-            sampleInputStr = JSON.stringify(sampleObj);
-        }
         writeStdout(`[OK] Created Action '${id}' at ${targetFullFile}`, context);
-        writeStdout(`\nTo run this action:`, context);
-        writeStdout(`  ad run ${id} --input '${sampleInputStr}'`, context);
+        writeStdout(`\n查阅参数契约:`, 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);
     }
     catch (err) {
         if (err instanceof ExecutionError)

package/dist/commands/describe.js

@@ -1,5 +1,6 @@
+import { buildActionDescribePayload, formatActionDetail } from "@actiondock/core";
 import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
-import { renderActionDetail, renderResult } from "../renderer.js";
+import { renderResult } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
 /**
  * 挂载 describe 子命令至指定 Commander 节点。
@@ -26,10 +27,7 @@ export function attachDescribeCommand(parent, context) {
         if (options.package && !targetPackageRoot) {
             throw packageNotFoundError(options.package);
         }
-        let targetRef = id;
-        if (options.package && !id.includes("/") && !id.includes(":")) {
-            targetRef = `${options.package}/${id}`;
-        }
+        const targetRef = id;
         // 通过 Target 门面统一查询 Action 规范
         await withTarget(options, context, async (target) => {
             let spec;
@@ -43,20 +41,10 @@ export function attachDescribeCommand(parent, context) {
                 }
                 throw new ExecutionError(msg);
             }
-            const detail = {
-                id: spec.id,
-                description: spec.description,
-                inputSchema: spec.inputSchema,
-                outputSchema: spec.outputSchema,
-                tags: spec.tags,
-                annotations: spec.annotations,
-                uses: spec.uses,
-                entry: spec.entry,
-                filePath: spec.filePath,
-            };
-            renderResult(detail, {
+            const payload = buildActionDescribePayload(spec);
+            renderResult(payload, {
                 json: options.json,
-                humanFormatter: () => renderActionDetail(detail),
+                humanFormatter: () => formatActionDetail(payload),
                 context,
             });
         }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });

package/dist/commands/run.d.ts

@@ -1,3 +1,4 @@
+import { type InvocationControl } from "@actiondock/core";
 import type { ExecutionResult } from "@actiondock/sdk";
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
@@ -11,7 +12,7 @@ export declare function renderRawExecutionResult(targetRef: string, result: Exec
 /**
  * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
  */
-export declare function executeAction(id: string, options: any, context?: CliContext): Promise<void>;
+export declare function executeAction(id: string, options: any, context?: CliContext, flatArgs?: string[], control?: InvocationControl): Promise<void>;
 /**
  * 挂载 run 子命令至指定 Commander 节点。
  *

package/dist/commands/run.js

@@ -1,4 +1,4 @@
-import { parseDuration, resolveTarget } from "@actiondock/core";
+import { parseDuration, resolveTarget, validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core";
 import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
 import { writeStderr, writeStdout } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
@@ -86,21 +86,34 @@ export function renderRawExecutionResult(targetRef, result, context) {
                 ? result.error.details
                 : JSON.stringify(result.error.details, null, 2), context);
         }
-        process.exitCode = 1;
+        if (context) {
+            context.exitCode = 1;
+        }
+        if (!context?.control) {
+            process.exitCode = 1;
+        }
     }
 }
 /**
  * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
  */
-export async function executeAction(id, options, context) {
+export async function executeAction(id, options, context, flatArgs, control) {
     if (!id) {
         throw new ArgumentError("Action ID is required for run");
     }
+    const effectiveControl = control ?? context?.control;
+    const effectiveSignal = effectiveControl?.signal;
+    const effectiveFlatArgs = flatArgs ?? options.flatArgs;
     const input = await resolveActionInput({
         input: options.input,
         inputFile: options.inputFile,
+        flatArgs: effectiveFlatArgs && effectiveFlatArgs.length > 0 ? effectiveFlatArgs : undefined,
         stdin: context?.stdin,
     });
+    const check = validateActionInputValue(input);
+    if (!check.valid) {
+        throw mapInputValidationFailure("cli-pre-target", check);
+    }
     let timeoutMs;
     if (options.timeout) {
         try {
@@ -119,13 +132,6 @@ export async function executeAction(id, options, context) {
                 configOverrides[k] = v.join("=");
         }
     }
-    const controller = new AbortController();
-    let receivedSigint = false;
-    const sigintHandler = () => {
-        receivedSigint = true;
-        controller.abort(new Error("Interrupted by SIGINT"));
-    };
-    process.once("SIGINT", sigintHandler);
     try {
         // 异步执行仅支持远端目标，本地模式直接拒绝
         const resolvedTopology = resolveTarget({
@@ -151,7 +157,7 @@ export async function executeAction(id, options, context) {
             const isMachine = Boolean(options.json);
             if (options.async) {
                 const ticket = await target.startAction(targetRef, input, {
-                    signal: controller.signal,
+                    signal: effectiveSignal,
                     timeoutMs,
                     config: configOverrides,
                     requestId: options.requestId,
@@ -169,17 +175,23 @@ export async function executeAction(id, options, context) {
                     writeStdout(ticket.runId, context);
                 }
                 if (ticket.status === "failed") {
-                    process.exitCode = 1;
+                    if (context) {
+                        context.exitCode = 1;
+                    }
                     return;
                 }
             }
             else {
                 const result = await target.runAction(targetRef, input, {
-                    signal: controller.signal,
+                    signal: effectiveSignal,
                     timeoutMs,
                     config: configOverrides,
                     requestId: options.requestId,
                 });
+                if (effectiveControl?.cancellationSource === "sigint" &&
+                    (effectiveSignal?.aborted || (!result.ok && result.error?.code === "ACTION_CANCELLED"))) {
+                    throw new SigintError();
+                }
                 if (isMachine) {
                     writeStdout(JSON.stringify(result, null, 2), context);
                 }
@@ -187,21 +199,23 @@ export async function executeAction(id, options, context) {
                     renderRawExecutionResult(targetRef, result, context);
                 }
                 if (!result.ok) {
-                    process.exitCode = 1;
+                    if (context) {
+                        context.exitCode = 1;
+                    }
                     return;
                 }
             }
         }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true, ownDataDir: true });
     }
     catch (err) {
-        if (receivedSigint || err?.name === "AbortError" || err?.message?.includes("SIGINT")) {
+        const isSigint = effectiveControl?.cancellationSource === "sigint" ||
+            err?.message?.includes("Interrupted by SIGINT");
+        if (isSigint &&
+            (err?.name === "AbortError" || effectiveSignal?.aborted || err?.message?.includes("SIGINT") || err instanceof SigintError)) {
             throw new SigintError();
         }
         throw err;
     }
-    finally {
-        process.removeListener("SIGINT", sigintHandler);
-    }
 }
 /**
  * 挂载 run 子命令至指定 Commander 节点。
@@ -211,7 +225,7 @@ export async function executeAction(id, options, context) {
  */
 export function attachRunCommand(parent, context) {
     const cmd = parent
-        .command("run <id>")
+        .command("run <id> [params...]")
         .description("Execute an action (from current project, linked packages, or remote profile)")
         .option("-P, --package <id>", "Target package ID or path")
         .option("-i, --input <json>", "Action input as inline JSON")
@@ -223,9 +237,19 @@ export function attachRunCommand(parent, context) {
         .option("--async", "Execute asynchronously in background (requires remote server or profile)")
         .option("--data-dir <path>", "Custom database directory")
         .option("--json", "Output as JSON")
-        .action(async (id, rawOptions, cmd) => {
-        const options = getEffectiveOptions(rawOptions, cmd);
-        await executeAction(id, options, context);
+        .action(async (id, params, rawOptions, cmd) => {
+        let flatArgs;
+        let effectiveRawOptions = rawOptions;
+        let effectiveCmd = cmd;
+        if (Array.isArray(params)) {
+            flatArgs = params.length > 0 ? params : undefined;
+        }
+        else {
+            effectiveCmd = rawOptions;
+            effectiveRawOptions = params;
+        }
+        const options = getEffectiveOptions(effectiveRawOptions, effectiveCmd);
+        await executeAction(id, { ...options, flatArgs }, context, undefined, context?.control);
     });
 }
 /**

package/dist/errors.js

@@ -1,4 +1,20 @@
+import { InputError, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, } from "@actiondock/core";
 import { ExitCode } from "./types.js";
+/**
+ * 扁平与解析输入错误码集合。
+ */
+const FLAT_ERROR_CODES = new Set([
+    INVALID_FLAT_ARGUMENT,
+    INVALID_JSON,
+    INVALID_JSON_LITERAL,
+    INPUT_PATH_CONFLICT,
+    FLAT_INPUT_LIMIT_EXCEEDED,
+    INPUT_LIMIT_EXCEEDED,
+    INPUT_POLICY_VIOLATION,
+    INPUT_CONFLICT,
+    INPUT_FILE_NOT_FOUND,
+    INPUT_FILE_READ_FAILED,
+]);
 /**
  * CLI 信封错误码常量（仅 CLI 输出协议使用，属包内部码，就地常量化管理）。
  */
@@ -80,10 +96,26 @@ export function formatError(err) {
             details: err.details,
         };
     }
+    if (err instanceof InputError) {
+        return {
+            code: err.code,
+            message: err.message,
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            details: err.details,
+        };
+    }
     // Commander.js 原生错误处理
     if (typeof err === "object" && err !== null && "code" in err && typeof err.code === "string") {
+        const code = err.code;
+        if (FLAT_ERROR_CODES.has(code)) {
+            return {
+                code,
+                message: err.message || String(err),
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                details: err.details,
+            };
+        }
         const commanderErr = err;
-        const code = commanderErr.code;
         // 参数类异常
         if (code.startsWith("commander.unknownOption") ||
             code.startsWith("commander.missingArgument") ||

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type InvocationControl } from "./types.js";
 export * from "./types.js";
 export * from "./errors.js";
 export * from "./renderer.js";
@@ -10,6 +11,12 @@ export * from "./commands/index.js";
  * ActionDock CLI 主执行入口函数。
  *
  * @param argv 命令行参数数组（默认使用 process.argv）
+ * @param control 可选的中断与取消控制契约
  * @returns 进程退出码
  */
-export declare function main(argv?: string[]): Promise<number>;
+export declare function main(argv?: string[], control?: InvocationControl): Promise<number>;
+/**
+ * 命令行独立进程适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export declare function runCliProcess(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -1,7 +1,8 @@
 import { CommanderError } from "commander";
 import { createCliProgram } from "./commands/index.js";
-import { formatError } from "./errors.js";
+import { formatError, SigintError } from "./errors.js";
 import { renderError } from "./renderer.js";
+import { ExitCode } from "./types.js";
 export * from "./types.js";
 export * from "./errors.js";
 export * from "./renderer.js";
@@ -14,16 +15,37 @@ export * from "./commands/index.js";
  * ActionDock CLI 主执行入口函数。
  *
  * @param argv 命令行参数数组（默认使用 process.argv）
+ * @param control 可选的中断与取消控制契约
  * @returns 进程退出码
  */
-export async function main(argv = process.argv) {
-    const program = createCliProgram();
+export async function main(argv = process.argv, control) {
+    const context = { control, exitCode: 0 };
+    const program = createCliProgram(context);
     const isMachine = argv.includes("--json");
+    const normalizedArgv = argv.length >= 2 &&
+        (argv[0].endsWith("node") ||
+            argv[0].endsWith("bun") ||
+            argv[0].endsWith("tsx") ||
+            argv[1].includes("/") ||
+            argv[1].includes("\\") ||
+            argv[1].endsWith(".js") ||
+            argv[1].endsWith(".ts"))
+        ? argv
+        : ["node", "ad", ...argv];
     try {
-        await program.parseAsync(argv);
-        return typeof process.exitCode === "number" ? process.exitCode : 0;
+        await program.parseAsync(normalizedArgv);
+        if (control?.cancellationSource === "sigint" && control?.signal?.aborted) {
+            return ExitCode.SIGINT;
+        }
+        return (context.exitCode && context.exitCode !== 0)
+            ? context.exitCode
+            : (typeof process.exitCode === "number" ? process.exitCode : 0);
     }
     catch (err) {
+        if (control?.cancellationSource === "sigint" &&
+            (control?.signal?.aborted || err?.name === "AbortError" || err?.message?.includes("SIGINT") || err instanceof SigintError)) {
+            return ExitCode.SIGINT;
+        }
         if (err instanceof CommanderError) {
             if (err.exitCode === 0) {
                 return 0;
@@ -32,9 +54,39 @@ export async function main(argv = process.argv) {
         // 复用 renderer 的 renderError 统一错误信封，消除手工拼装的双实现
         renderError(err, {
             json: isMachine,
+            context,
         });
-        process.exitCode = formatError(err).exitCode;
-        return process.exitCode;
+        return formatError(err).exitCode;
+    }
+}
+/**
+ * 命令行独立进程适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export async function runCliProcess(argv = process.argv) {
+    const controller = new AbortController();
+    const control = {
+        signal: controller.signal,
+    };
+    let sigintCount = 0;
+    const sigintHandler = () => {
+        sigintCount++;
+        if (sigintCount === 1) {
+            control.cancellationSource = "sigint";
+            controller.abort(new Error("Interrupted by SIGINT"));
+        }
+        else {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+    };
+    process.on("SIGINT", sigintHandler);
+    try {
+        const exitCode = await main(argv, control);
+        process.exitCode = exitCode;
+    }
+    finally {
+        process.removeListener("SIGINT", sigintHandler);
     }
 }
 import { fileURLToPath } from "node:url";
@@ -42,7 +94,7 @@ import { resolve } from "node:path";
 const isDirectRun = Boolean(process.argv[1]) &&
     resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isDirectRun) {
-    main().catch((err) => {
+    runCliProcess().catch((err) => {
         console.error("Fatal error:", err);
         process.exitCode = 1;
     });

package/dist/renderer.d.ts

@@ -1,5 +1,5 @@
 import type { RunRecord } from "@actiondock/sdk";
-import type { RegistryStatusReport } from "@actiondock/core";
+import { type RegistryStatusReport } from "@actiondock/core";
 import type { Envelope, ProjectDetailInfo, AggregatedPackage, EnvCheckItem, CliContext } from "./types.js";
 /**
  * 构造标准成功结果信封。
@@ -112,7 +112,8 @@ export declare function renderActionList(items: Array<{
     packageId?: string;
 }>, title?: string, isFallback?: boolean, intent?: string): string;
 /**
- * 格式化渲染 Action 详情。
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
  */
 export declare function renderActionDetail(action: {
     id: string;

package/dist/renderer.js

@@ -1,3 +1,4 @@
+import { formatActionDetail } from "@actiondock/core";
 import { formatError } from "./errors.js";
 /**
  * 构造标准成功结果信封。
@@ -254,27 +255,11 @@ export function renderActionList(items, title = "Actions", isFallback = false, i
     return lines.join("\n");
 }
 /**
- * 格式化渲染 Action 详情。
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
  */
 export function renderActionDetail(action) {
-    const lines = [];
-    lines.push(`Action:      ${action.id}`);
-    if (action.packageId) {
-        const rootDesc = action.projectRoot ? ` (${action.projectRoot})` : "";
-        lines.push(`Package:     ${action.packageId}${rootDesc}`);
-    }
-    if (action.description) {
-        lines.push(`Description: ${action.description}`);
-    }
-    if (action.inputSchema) {
-        lines.push("\nInput Schema:");
-        lines.push(JSON.stringify(action.inputSchema, null, 2));
-    }
-    if (action.outputSchema) {
-        lines.push("\nOutput Schema:");
-        lines.push(JSON.stringify(action.outputSchema, null, 2));
-    }
-    return lines.join("\n");
+    return formatActionDetail(action);
 }
 /**
  * 格式化渲染 Action 校验结果。

package/dist/standalone/index.d.ts

@@ -1,5 +1,6 @@
-import { StandaloneDispatcher as CoreStandaloneDispatcher } from "@actiondock/core";
+import { StandaloneDispatcher as CoreStandaloneDispatcher, type InvocationControl } from "@actiondock/core";
 import type { StandaloneOptions } from "../types.js";
+export { type InvocationControl };
 /**
  * 独立二进制轻量参数解析分发器（委托 Core 统一实现，消除重复逻辑）。
  */
@@ -9,8 +10,13 @@ export declare class StandaloneDispatcher extends CoreStandaloneDispatcher {
 /**
  * 运行独立二进制参数解析分发器并返回退出状态码。
  */
-export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions): Promise<number>;
+export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions, control?: InvocationControl): Promise<number>;
 /**
  * 创建独立二进制运行时分发器实例。
  */
 export declare function createStandaloneDispatcher(options: StandaloneOptions): StandaloneDispatcher;
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export declare function runStandaloneProcess(argv: string[] | undefined, options: StandaloneOptions): Promise<void>;

package/dist/standalone/index.js

@@ -10,9 +10,9 @@ export class StandaloneDispatcher extends CoreStandaloneDispatcher {
 /**
  * 运行独立二进制参数解析分发器并返回退出状态码。
  */
-export async function runStandaloneCli(argv = process.argv.slice(2), options) {
+export async function runStandaloneCli(argv = process.argv.slice(2), options, control) {
     const dispatcher = new StandaloneDispatcher(options);
-    return dispatcher.dispatch(argv);
+    return dispatcher.dispatch(argv, control);
 }
 /**
  * 创建独立二进制运行时分发器实例。
@@ -20,3 +20,33 @@ export async function runStandaloneCli(argv = process.argv.slice(2), options) {
 export function createStandaloneDispatcher(options) {
     return new StandaloneDispatcher(options);
 }
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export async function runStandaloneProcess(argv = process.argv.slice(2), options) {
+    const controller = new AbortController();
+    const control = {
+        signal: controller.signal,
+    };
+    let sigintCount = 0;
+    const sigintHandler = () => {
+        sigintCount++;
+        if (sigintCount === 1) {
+            control.cancellationSource = "sigint";
+            controller.abort(new Error("Interrupted by SIGINT"));
+        }
+        else {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+    };
+    process.on("SIGINT", sigintHandler);
+    try {
+        const exitCode = await runStandaloneCli(argv, options, control);
+        process.exitCode = exitCode;
+    }
+    finally {
+        process.removeListener("SIGINT", sigintHandler);
+    }
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import type { ConfigItemDefinition } from "@actiondock/core";
+import type { ConfigItemDefinition, InvocationControl } from "@actiondock/core";
+export type { InvocationControl };
 /**
  * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
  * - SUCCESS: 执行成功（0）
@@ -78,6 +79,10 @@ export interface CliContext {
         secret?: boolean;
         mask?: string;
     }) => Promise<string>;
+    /** 可选的中断与取消控制契约 */
+    control?: InvocationControl;
+    /** 退出码收集器（避免污染全局 process.exitCode） */
+    exitCode?: number;
 }
 /**
  * 工程自省详情信息结构。

package/dist/utils/input.d.ts

@@ -1,46 +1 @@
-import type { JsonValue } from "@actiondock/sdk";
-/**
- * 获取异常的标准描述信息。
- *
- * @param err 待提取消息的异常对象
- */
-export declare function getErrorMessage(err: unknown): string;
-/**
- * 剔除 UTF-8 文本起始处的 BOM 字节标记（\uFEFF）。
- *
- * @param text 原始输入文本
- */
-export declare function stripBom(text: string): string;
-/**
- * 统一解析 JSON 字符串为标准 JSON 值对象，并在失败时抛出结构化参数异常。
- *
- * @param text 待解析文本内容
- * @param source 输入源描述（如 "--input"、"stdin" 或文件物理路径）
- */
-export declare function parseJson(text: string, source: string): JsonValue;
-/**
- * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
- *
- * @param stream 标准输入可读流，默认为 process.stdin
- */
-export declare function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;
-/**
- * Action 执行输入解析选项。
- */
-export interface ResolveActionInputOptions {
-    input?: string;
-    inputFile?: string;
-    stdin?: NodeJS.ReadableStream;
-}
-/**
- * 统一解析 Action 执行入参。
- *
- * 遵循确定性入参契约：
- * - 当未指定任何输入参数时，默认返回空对象 `{}`。
- * - 简单输入通过 `--input` 传递内联 JSON 字符串。
- * - 复杂输入或标准输入通过 `--input-file` 传递（`-` 表示标准输入 stdin）。
- * - 严禁同时指定 `--input` 与 `--input-file`，检测到冲突时明确抛出参数错误。
- *
- * @param options 输入解析选项
- */
-export declare function resolveActionInput(options: ResolveActionInputOptions): Promise<JsonValue>;
+export { resolveActionInput, type ResolveActionInputOptions, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";

package/dist/utils/input.js

@@ -1,89 +1 @@
-import { readFile } from "node:fs/promises";
-import { ArgumentError } from "../errors.js";
-/**
- * 获取异常的标准描述信息。
- *
- * @param err 待提取消息的异常对象
- */
-export function getErrorMessage(err) {
-    if (err instanceof Error) {
-        return err.message;
-    }
-    return String(err);
-}
-/**
- * 剔除 UTF-8 文本起始处的 BOM 字节标记（\uFEFF）。
- *
- * @param text 原始输入文本
- */
-export function stripBom(text) {
-    return text.replace(/^\uFEFF/, "");
-}
-/**
- * 统一解析 JSON 字符串为标准 JSON 值对象，并在失败时抛出结构化参数异常。
- *
- * @param text 待解析文本内容
- * @param source 输入源描述（如 "--input"、"stdin" 或文件物理路径）
- */
-export function parseJson(text, source) {
-    try {
-        return JSON.parse(stripBom(text));
-    }
-    catch (err) {
-        throw new ArgumentError(`Invalid JSON input from ${source}: ${getErrorMessage(err)}`, undefined, "INVALID_JSON");
-    }
-}
-/**
- * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
- *
- * @param stream 标准输入可读流，默认为 process.stdin
- */
-export async function readStdin(stream = process.stdin) {
-    const chunks = [];
-    for await (const chunk of stream) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    }
-    return Buffer.concat(chunks).toString("utf8");
-}
-/**
- * 统一解析 Action 执行入参。
- *
- * 遵循确定性入参契约：
- * - 当未指定任何输入参数时，默认返回空对象 `{}`。
- * - 简单输入通过 `--input` 传递内联 JSON 字符串。
- * - 复杂输入或标准输入通过 `--input-file` 传递（`-` 表示标准输入 stdin）。
- * - 严禁同时指定 `--input` 与 `--input-file`，检测到冲突时明确抛出参数错误。
- *
- * @param options 输入解析选项
- */
-export async function resolveActionInput(options) {
-    if (options.input !== undefined && options.inputFile !== undefined) {
-        throw new ArgumentError("--input and --input-file cannot be used together", undefined, "INPUT_CONFLICT");
-    }
-    if (options.input !== undefined) {
-        return parseJson(options.input, "--input");
-    }
-    if (options.inputFile !== undefined) {
-        let text;
-        if (options.inputFile === "-") {
-            try {
-                text = await readStdin(options.stdin || process.stdin);
-            }
-            catch (err) {
-                throw new ArgumentError(`Failed to read stdin: ${getErrorMessage(err)}`, undefined, "INPUT_FILE_READ_FAILED");
-            }
-            return parseJson(text, "stdin");
-        }
-        try {
-            text = await readFile(options.inputFile, "utf8");
-        }
-        catch (err) {
-            if (err && err.code === "ENOENT") {
-                throw new ArgumentError(`Input file not found: ${options.inputFile}`, undefined, "INPUT_FILE_NOT_FOUND");
-            }
-            throw new ArgumentError(`Failed to read input file '${options.inputFile}': ${getErrorMessage(err)}`, undefined, "INPUT_FILE_READ_FAILED");
-        }
-        return parseJson(text, options.inputFile);
-    }
-    return {};
-}
+export { resolveActionInput, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,11 +34,11 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.6.0",
-    "@actiondock/core": "^2.6.0",
-    "@actiondock/mcp": "^2.6.0",
-    "@actiondock/runtime-node": "^2.6.0",
-    "@actiondock/sdk": "^2.6.0",
+    "@actiondock/builder": "^2.7.0",
+    "@actiondock/core": "^2.7.0",
+    "@actiondock/mcp": "^2.7.0",
+    "@actiondock/runtime-node": "^2.7.0",
+    "@actiondock/sdk": "^2.7.0",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },