@actiondock/cli 2.6.0 → 2.8.0

package/dist/commands/state.js

@@ -1,32 +1,78 @@
-import { decodeStateKey, findProjectRoot, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
+import { decodeStateKey, } from "@actiondock/sdk";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
 import { renderResult, renderStateList, writeStderr, writeStdout } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, getTargetRoot, resolveIntent, withTarget, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, getTargetRoot, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveTargetFromOptions, withService, } from "../utils/index.js";
 import { renderLinkedPackagesStateList, renderProjectScopedStateList, } from "./state-list.js";
 /**
- * 解析复合状态键为命名空间与裸键视图。
+ * 统一预解码状态键寻址（get、set、delete 共享的单一事实源）。
  *
- * 多冒号歧义键（如 `review:owner/repo:42`）不再直接崩溃：
+ * 三命令在 CLI 层即完成 `ns:key` 复合键解耦：
+ * - 显式 `-n/--namespace` 指定时命名空间以其为准，键保持原串不拆解；
+ * - 未显式指定时按复合键语法预解码出命名空间与裸键；
+ * - 多冒号歧义键降级为整串裸键并提示。
+ *
+ * 歧义键（如 `review:owner/repo:42`）不再直接崩溃：
  * 降级为「整串作为裸 key」并在 stderr 提示可用 -n/--namespace 显式指定，
  * 保持与本地存储层歧义兜底（deleteStateSmart 的纯键回退）一致的容错语义。
+ *
+ * 本地与远端分支都消费解耦后的 namespace + key，
+ * 消除「set 预解码而 get/delete 依赖存储层回退」的语义不对称。
  */
-function decodeStateKeyWithFallback(rawKey, hasExplicitNamespace, context) {
+function resolveStateAddress(rawKey, options, context) {
+    if (options.namespace !== undefined) {
+        return { namespace: options.namespace, key: rawKey };
+    }
     try {
         const decoded = decodeStateKey(rawKey);
         return { namespace: decoded.namespace || undefined, key: decoded.key };
     }
     catch {
-        if (!hasExplicitNamespace) {
-            writeStderr(`[WARN] State key '${rawKey}' contains multiple colon delimiters; treating it as a bare key. Use -n/--namespace to specify the namespace explicitly.`, context);
-        }
+        writeStderr(`[WARN] State key '${rawKey}' contains multiple colon delimiters; treating it as a bare key. Use -n/--namespace to specify the namespace explicitly.`, context);
         return { namespace: undefined, key: rawKey };
     }
 }
+/**
+ * 解析状态命令目标作用域（remote 与 local 双分支模板的单一事实源）。
+ *
+ * 远端分支直接以 -P 参数寻址，消息后缀固定为 "on remote server"；
+ * 本地分支基于 getTargetRoot 完成包寻址（含从键中剥离 pkg/ 前缀），
+ * 以工程配置 id 寻址，消息后缀为 "in/from package '...'"。
+ *
+ * @param resolved 目标拓扑解析结果
+ * @param options 命令选项视图
+ * @param rawKey 原始键（本地分支用于剥离 pkg/ 前缀）
+ * @returns 作用域解析结果（含包标识、消息后缀、本地根目录与工程配置）
+ */
+function resolveStateScope(resolved, options, rawKey) {
+    if (resolved.type === "remote") {
+        return {
+            packageId: options.package || "",
+            scopeSuffix: "on remote server",
+            deleteSuffix: "on remote server",
+            effectiveKey: rawKey || "",
+            projConfig: undefined,
+            localRoot: undefined,
+        };
+    }
+    // 本地项目模式：getTargetRoot 会从键中剥离 pkg/ 前缀，寻址基于解耦后的裸键
+    const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
+    const projConfig = loadProjectConfig(root);
+    return {
+        packageId: projConfig.id,
+        scopeSuffix: `in package '${projConfig.id}'`,
+        deleteSuffix: `from package '${projConfig.id}'`,
+        effectiveKey,
+        projConfig,
+        localRoot: root,
+    };
+}
 /**
  * 注册 state 状态管理命令（get、set、delete、clear、keys、list）。
  *
- * @param program Commander 实例
- * @param context 命令行上下文
+ * @param program Commander 根程序对象
+ * @param context CLI 上下文
  */
 export function registerStateCommands(program, context) {
     const stateCmd = program
@@ -36,18 +82,18 @@ export function registerStateCommands(program, context) {
     const handleListKeys = async (prefix = "", rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, prefix ? [prefix] : []);
-        const shouldFallback = options.fallback !== false;
-        await withTarget(options, context, async (target, resolved) => {
+        const { shouldFallback } = resolveFallbackStrategy(options);
+        await withService(options, context, async (service, resolved) => {
             const actionId = options.action || "";
             // 远端服务模式：直接列举远端包作用域键
             if (resolved.type === "remote") {
-                const keys = await target.listStateKeys(options.package || "", actionId, {
+                const keys = (await service.management?.state.list(options.package || "", actionId, {
                     namespace: options.namespace,
                     prefix,
-                });
+                })) ?? [];
                 renderResult(keys, {
                     json: options.json,
-                    humanFormatter: () => renderStateList(keys, `Remote Server ${resolved.serverUrl}${resolved.profileName ? ` (Profile: ${resolved.profileName})` : ""}`, false, effectiveIntent),
+                    humanFormatter: () => renderStateList(keys, remoteTargetLabel(resolved), false, effectiveIntent),
                     context,
                 });
                 return;
@@ -65,7 +111,7 @@ export function registerStateCommands(program, context) {
             }
             if (targetRoot) {
                 await renderProjectScopedStateList({
-                    target,
+                    service,
                     targetRoot,
                     actionId,
                     prefix,
@@ -77,7 +123,7 @@ export function registerStateCommands(program, context) {
                 return;
             }
             await renderLinkedPackagesStateList({
-                target,
+                service,
                 actionId,
                 prefix,
                 options,
@@ -96,6 +142,7 @@ export function registerStateCommands(program, context) {
         .option("-n, --namespace <ns>", "Filter keys under specific namespace (omit to list all namespaces)"))
         .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
         .option("--detail", "Include metadata (ttl, expiresAt, size, updatedAt) in JSON output")
+        .option("--fallback", "Enable fallback to full list when no items match intent")
         .option("--no-fallback", "Disable fallback to full list when no items match intent")
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
@@ -109,6 +156,7 @@ export function registerStateCommands(program, context) {
         .option("-n, --namespace <ns>", "Filter keys under specific namespace"))
         .option("-i, --intent <pattern>", "Regex or fuzzy intent filter")
         .option("--detail", "Include metadata in JSON output")
+        .option("--fallback", "Enable fallback to full list when no items match intent")
         .option("--no-fallback", "Disable fallback")
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
@@ -127,45 +175,28 @@ export function registerStateCommands(program, context) {
         if (!rawKey) {
             throw new ArgumentError("State key is required");
         }
-        await withTarget(options, context, async (target, resolved) => {
+        // 惰性作用域缓存：仅本地分支求值一次，避免远端模式触发包寻址副作用
+        let scope;
+        const resolveScope = (resolved) => (scope ??= resolveStateScope(resolved, options, rawKey));
+        await withService(options, context, async (service, resolved) => {
             const actionId = options.action || "";
-            if (resolved.type === "remote") {
-                const decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
-                const effectiveNamespace = options.namespace || decoded.namespace;
-                const actualKey = options.namespace ? rawKey : decoded.key;
-                const entry = await target.getState(options.package || "", actionId, actualKey, {
-                    namespace: effectiveNamespace,
-                    detail: true,
-                });
-                if (entry === undefined || entry.value === undefined) {
-                    throw new ExecutionError(`State key '${rawKey}' not found on remote server`);
-                }
-                const val = entry.value;
-                renderResult({ key: rawKey, value: val, namespace: entry.namespace || effectiveNamespace }, {
-                    json: options.json,
-                    humanFormatter: () => (typeof val === "object" ? JSON.stringify(val, null, 2) : String(val)),
-                    context,
-                });
-                return;
-            }
-            // 本地项目模式
-            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
-            const projConfig = loadProjectConfig(root);
-            const entry = await target.getState(projConfig.id, actionId, effectiveKey, {
-                namespace: options.namespace,
+            const targetScope = resolveScope(resolved);
+            const address = resolveStateAddress(targetScope.effectiveKey, options, context);
+            const entry = await service.management?.state.get(targetScope.packageId, actionId, address.key, {
+                namespace: address.namespace,
                 detail: true,
             });
             if (entry === undefined || entry.value === undefined) {
-                throw new ExecutionError(`State key '${rawKey}' not found in package '${projConfig.id}'`);
+                throw new ExecutionError(`State key '${rawKey}' not found ${targetScope.scopeSuffix}`);
             }
             const val = entry.value;
-            const matchedNamespace = entry.namespace;
+            const matchedNamespace = resolved.type === "remote" ? (entry.namespace || address.namespace) : entry.namespace;
             renderResult({ key: rawKey, value: val, namespace: matchedNamespace }, {
                 json: options.json,
                 humanFormatter: () => (typeof val === "object" ? JSON.stringify(val, null, 2) : String(val)),
                 context,
             });
-        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+        }, { localRoot: () => resolveScope(resolveTargetFromOptions(options, context)).localRoot });
     });
     // state set <key> <value>
     applyTargetOptions(stateCmd
@@ -192,36 +223,21 @@ export function registerStateCommands(program, context) {
         if (options.ttl && (isNaN(ttlSec) || ttlSec <= 0)) {
             throw new ArgumentError(`Invalid --ttl value: '${options.ttl}'. Must be a positive integer.`);
         }
-        await withTarget(options, context, async (target, resolved) => {
+        // 惰性作用域缓存：仅本地分支求值一次，避免远端模式触发包寻址副作用
+        let scope;
+        const resolveScope = (resolved) => (scope ??= resolveStateScope(resolved, options, rawKey));
+        await withService(options, context, async (service, resolved) => {
             const actionId = options.action || "";
-            if (resolved.type === "remote") {
-                const decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
-                const effectiveNamespace = options.namespace || decoded.namespace;
-                const actualKey = options.namespace ? rawKey : decoded.key;
-                await target.setState(options.package || "", actionId, actualKey, parsedVal, {
-                    namespace: effectiveNamespace,
-                    ttl: ttlSec,
-                });
-                writeStdout(`[OK] State '${rawKey}' updated on remote server`, context);
-                return;
-            }
-            // 本地项目模式
-            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
-            const projConfig = loadProjectConfig(root);
-            let actualNamespace = options.namespace;
-            let finalKey = effectiveKey;
-            if (options.namespace === undefined && effectiveKey.includes(":")) {
-                const decoded = decodeStateKeyWithFallback(effectiveKey, false, context);
-                actualNamespace = decoded.namespace;
-                finalKey = decoded.key;
-            }
-            await target.setState(projConfig.id, actionId, finalKey, parsedVal, {
-                namespace: actualNamespace,
+            const targetScope = resolveScope(resolved);
+            const address = resolveStateAddress(targetScope.effectiveKey, options, context);
+            await service.management?.state.set(targetScope.packageId, actionId, address.key, parsedVal, {
+                namespace: address.namespace,
                 ttl: ttlSec,
             });
-            const displayKey = actualNamespace ? `${actualNamespace}:${finalKey}` : finalKey;
-            writeStdout(`[OK] State '${displayKey}' updated in package '${projConfig.id}'`, context);
-        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+            // 远端回显原始键；本地回显解耦后的 ns:key 复合视图
+            const displayKey = resolved.type === "remote" ? rawKey : (address.namespace ? `${address.namespace}:${address.key}` : address.key);
+            writeStdout(`[OK] State '${displayKey}' updated ${targetScope.scopeSuffix}`, context);
+        }, { localRoot: () => resolveScope(resolveTargetFromOptions(options, context)).localRoot });
     });
     // state delete <key>
     applyTargetOptions(stateCmd
@@ -237,32 +253,21 @@ export function registerStateCommands(program, context) {
         if (!rawKey) {
             throw new ArgumentError("State key is required");
         }
-        await withTarget(options, context, async (target, resolved) => {
+        // 惰性作用域缓存：仅本地分支求值一次，避免远端模式触发包寻址副作用
+        let scope;
+        const resolveScope = (resolved) => (scope ??= resolveStateScope(resolved, options, rawKey));
+        await withService(options, context, async (service, resolved) => {
             const actionId = options.action || "";
-            if (resolved.type === "remote") {
-                const decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
-                const effectiveNamespace = options.namespace || decoded.namespace;
-                const actualKey = options.namespace ? rawKey : decoded.key;
-                const deleted = await target.deleteState(options.package || "", actionId, actualKey, {
-                    namespace: effectiveNamespace,
-                });
-                if (!deleted) {
-                    throw new ExecutionError(`State key '${rawKey}' not found on remote server`);
-                }
-                writeStdout(`[OK] State '${rawKey}' deleted on remote server`, context);
-                return;
-            }
-            // 本地项目模式
-            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
-            const projConfig = loadProjectConfig(root);
-            const deleted = await target.deleteState(projConfig.id, actionId, effectiveKey, {
-                namespace: options.namespace,
+            const targetScope = resolveScope(resolved);
+            const address = resolveStateAddress(targetScope.effectiveKey, options, context);
+            const deleted = await service.management?.state.delete(targetScope.packageId, actionId, address.key, {
+                namespace: address.namespace,
             });
             if (!deleted) {
-                throw new ExecutionError(`State key '${rawKey}' not found in package '${projConfig.id}'`);
+                throw new ExecutionError(`State key '${rawKey}' not found ${targetScope.scopeSuffix}`);
             }
-            writeStdout(`[OK] State '${rawKey}' deleted from package '${projConfig.id}'`, context);
-        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+            writeStdout(`[OK] State '${rawKey}' deleted ${targetScope.deleteSuffix}`, context);
+        }, { localRoot: () => resolveScope(resolveTargetFromOptions(options, context)).localRoot });
     });
     // state clear
     applyTargetOptions(stateCmd
@@ -279,27 +284,29 @@ export function registerStateCommands(program, context) {
         if (!options.all && options.namespace === undefined) {
             throw new ArgumentError("Must specify either -n/--namespace <name> to clear specific namespace, or --all to clear entire package state store.");
         }
-        await withTarget(options, context, async (target, resolved) => {
+        // 惰性作用域缓存：仅本地分支求值一次，避免远端模式触发包寻址副作用
+        let scope;
+        const resolveScope = (resolved) => (scope ??= resolveStateScope(resolved, options));
+        await withService(options, context, async (service, resolved) => {
             const actionId = options.action || "";
             if (resolved.type === "remote") {
-                const count = await target.clearState(options.package || "", actionId, {
+                const count = (await service.management?.state.clear(options.package || "", actionId, {
                     namespace: options.namespace,
                     all: Boolean(options.all),
-                });
+                })) ?? 0;
                 writeStdout(`[OK] Cleared ${count} state entry(s) on remote server`, context);
                 return;
             }
             // 本地项目模式
-            const { root } = getTargetRoot(options.package);
-            const projConfig = loadProjectConfig(root);
-            const count = await target.clearState(projConfig.id, actionId, {
+            const targetScope = resolveScope(resolved);
+            const count = (await service.management?.state.clear(targetScope.packageId, actionId, {
                 namespace: options.namespace,
                 all: Boolean(options.all),
-            });
+            })) ?? 0;
             const scopeDesc = options.all
                 ? "all namespaces"
                 : `namespace '${options.namespace}'`;
-            writeStdout(`[OK] Cleared ${count} state entry(s) in ${scopeDesc} for package '${projConfig.id}'`, context);
-        }, { localRoot: () => getTargetRoot(options.package).root });
+            writeStdout(`[OK] Cleared ${count} state entry(s) in ${scopeDesc} for package '${targetScope.projConfig.id}'`, context);
+        }, { localRoot: () => resolveScope(resolveTargetFromOptions(options, context)).localRoot });
     });
 }

package/dist/commands/test.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { findProjectRoot } from "@actiondock/core";
+import { findProjectRoot, } from "@actiondock/core";
 import { writeStderr } from "../renderer.js";
 import { spawnAsync } from "../utils/index.js";
 export function registerTestCommand(program) {

package/dist/commands/validate.js

@@ -1,7 +1,7 @@
-import { checkGeneratedTypes, findProjectRoot, GENERATED_TYPES_OUTDATED_CODE, loadActions, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError } from "../errors.js";
+import { checkGeneratedTypes, GENERATED_TYPES_OUTDATED_CODE, loadActions, } from "@actiondock/core/project";
+import { ArgumentError, ExecutionError } from "../errors.js";
 import { renderActionValidation, renderResult } from "../renderer.js";
-import { getEffectiveOptions } from "../utils/index.js";
+import { getEffectiveOptions, requirePackageRoot } from "../utils/index.js";
 /**
  * 挂载 validate 子命令至指定 Commander 节点。
  *
@@ -17,20 +17,7 @@ export function attachValidateCommand(parent, context) {
         .option("--data-dir <path>", "Custom database storage directory")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
-        let root = null;
-        if (options.package) {
-            root = resolvePackageRoot(options.package);
-            if (!root) {
-                throw packageNotFoundError(options.package);
-            }
-        }
-        else {
-            root = findProjectRoot();
-        }
-        if (!root) {
-            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
-        }
-        const config = loadProjectConfig(root);
+        const { root, projConfig: config } = requirePackageRoot(options.package, { loadConfig: true });
         const actions = await loadActions(root, config.actionsDir);
         let toValidate = [];
         if (id) {

package/dist/errors.d.ts

@@ -20,6 +20,20 @@ export declare class ArgumentError extends CliError {
 export declare class ExecutionError extends CliError {
     constructor(message: string, details?: unknown, code?: string);
 }
+/**
+ * 将任意异常统一包裹为 CLI 执行错误（错误码保留辅助）。
+ *
+ * 包裹规则：
+ * - CliError 与 ActionDockError 原样透传（保留原始 code、details 与退出码映射）；
+ * - 其余异常包裹为 ExecutionError，并保留 cause 链接与数字型 code 字段，
+ *   避免 core 抛出的结构化错误码被一律降级为 EXECUTION_FAILURE。
+ * - messagePrefix 仅对需要包裹的分支生效（附加命令语境说明）；
+ *   透传分支保持原始实例不变，不重建消息。
+ *
+ * @param err 待包裹的原始异常
+ * @param messagePrefix 可选的消息前缀（仅包裹分支生效）
+ */
+export declare function wrapAsExecutionError(err: unknown, messagePrefix?: string): Error;
 /**
  * 用户中断信号错误（退出码为 130）。
  */

package/dist/errors.js

@@ -1,4 +1,21 @@
+import { ActionDockError, INVALID_ARGUMENT, INVALID_PACKAGE_ID, PACKAGE_NOT_FOUND, ACTION_NOT_FOUND, NOT_FOUND, PATH_TRAVERSAL, 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 { InputError } from "@actiondock/core/project";
 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 输出协议使用，属包内部码，就地常量化管理）。
  */
@@ -39,6 +56,33 @@ export class ExecutionError extends CliError {
         this.name = "ExecutionError";
     }
 }
+/**
+ * 将任意异常统一包裹为 CLI 执行错误（错误码保留辅助）。
+ *
+ * 包裹规则：
+ * - CliError 与 ActionDockError 原样透传（保留原始 code、details 与退出码映射）；
+ * - 其余异常包裹为 ExecutionError，并保留 cause 链接与数字型 code 字段，
+ *   避免 core 抛出的结构化错误码被一律降级为 EXECUTION_FAILURE。
+ * - messagePrefix 仅对需要包裹的分支生效（附加命令语境说明）；
+ *   透传分支保持原始实例不变，不重建消息。
+ *
+ * @param err 待包裹的原始异常
+ * @param messagePrefix 可选的消息前缀（仅包裹分支生效）
+ */
+export function wrapAsExecutionError(err, messagePrefix) {
+    if (err instanceof CliError || err instanceof ActionDockError) {
+        return err;
+    }
+    const originalMessage = err instanceof Error ? err.message : String(err);
+    const message = messagePrefix ? `${messagePrefix}${originalMessage}` : originalMessage;
+    const rawCode = err?.code;
+    const code = typeof rawCode === "string" && rawCode ? rawCode : "EXECUTION_FAILURE";
+    const wrapped = new ExecutionError(message, undefined, code);
+    if (err instanceof Error) {
+        wrapped.cause = err;
+    }
+    return wrapped;
+}
 /**
  * 用户中断信号错误（退出码为 130）。
  */
@@ -80,10 +124,41 @@ 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,
+        };
+    }
+    if (err instanceof ActionDockError) {
+        const isArgument = err.code === INVALID_ARGUMENT ||
+            err.code === INVALID_PACKAGE_ID ||
+            err.code === PACKAGE_NOT_FOUND ||
+            err.code === ACTION_NOT_FOUND ||
+            err.code === NOT_FOUND ||
+            err.code === PATH_TRAVERSAL ||
+            FLAT_ERROR_CODES.has(err.code);
+        return {
+            code: err.code,
+            message: err.message,
+            exitCode: isArgument ? ExitCode.INVALID_ARGUMENT : ExitCode.FAILURE,
+            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") ||
@@ -108,9 +183,10 @@ export function formatError(err) {
     }
     if (err instanceof Error) {
         return {
-            code: CLI_CODE_ERROR,
+            code: err.code || CLI_CODE_ERROR,
             message: err.message,
             exitCode: ExitCode.FAILURE,
+            details: err.details,
         };
     }
     return {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type InvocationControl, type CliContext } 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, contextOptions?: Partial<CliContext>): 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, contextOptions) {
+    const context = { control, exitCode: 0, ...contextOptions };
+    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?.code === "SIGINT_INTERRUPTED" || 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/registry";
 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;