@actiondock/cli 2.5.1 → 2.6.0

package/dist/index.js

@@ -18,7 +18,7 @@ export * from "./commands/index.js";
  */
 export async function main(argv = process.argv) {
     const program = createCliProgram();
-    const isMachine = argv.includes("--json") || argv.includes("--envelope");
+    const isMachine = argv.includes("--json");
     try {
         await program.parseAsync(argv);
         return typeof process.exitCode === "number" ? process.exitCode : 0;
@@ -32,7 +32,6 @@ export async function main(argv = process.argv) {
         // 复用 renderer 的 renderError 统一错误信封，消除手工拼装的双实现
         renderError(err, {
             json: isMachine,
-            envelope: isMachine,
         });
         process.exitCode = formatError(err).exitCode;
         return process.exitCode;

package/dist/renderer.d.ts

@@ -37,7 +37,6 @@ export declare function writeStderr(message: string, context?: CliContext): void
  */
 export declare function renderResult<T>(data: T, options: {
     json?: boolean;
-    envelope?: boolean;
     humanFormatter?: () => string;
     context?: CliContext;
 }): void;
@@ -46,7 +45,6 @@ export declare function renderResult<T>(data: T, options: {
  */
 export declare function renderError(err: unknown, options: {
     json?: boolean;
-    envelope?: boolean;
     context?: CliContext;
 }): void;
 /**

package/dist/renderer.js

@@ -72,21 +72,9 @@ export function writeStderr(message, context) {
  * 统一根据输出模式进行渲染输出。
  */
 export function renderResult(data, options) {
-    const isJson = Boolean(options.json || options.envelope);
-    const useEnvelope = Boolean(options.envelope || (isJson && options.context?.defaultEnvelope));
+    const isJson = Boolean(options.json);
     if (isJson) {
-        if (useEnvelope) {
-            // 避免重复包装已有信封
-            if (typeof data === "object" && data !== null && "ok" in data) {
-                writeStdout(formatJson(data), options.context);
-            }
-            else {
-                writeStdout(formatJson(createSuccessEnvelope(data)), options.context);
-            }
-        }
-        else {
-            writeStdout(formatJson(data), options.context);
-        }
+        writeStdout(formatJson(data), options.context);
     }
     else {
         if (options.humanFormatter) {
@@ -102,7 +90,7 @@ export function renderResult(data, options) {
  */
 export function renderError(err, options) {
     const formatted = formatError(err);
-    const isMachine = Boolean(options.json || options.envelope || options.context?.defaultEnvelope);
+    const isMachine = Boolean(options.json);
     if (isMachine) {
         const errorEnv = createErrorEnvelope(formatted.code, formatted.message, formatted.details);
         writeStdout(formatJson(errorEnv), options.context);

package/dist/services/config-merge.d.ts

@@ -0,0 +1,41 @@
+import { type ActionDockTarget, type ConfigItemDefinition } from "@actiondock/core";
+/**
+ * 配置合并视图条目：跨作用域合并后的键值展示结构。
+ * source 标签语义：project（包级持久化）> global（全局持久化）> env（环境变量）> default（声明默认值）。
+ */
+export interface MergedConfigEntry {
+    key: string;
+    value: unknown;
+    source: "project" | "global" | "env" | "default";
+    secret: boolean;
+    description?: string;
+}
+/**
+ * 解析单个配置键的合并视图（项目包级 > 全局持久化 > 环境变量 > 声明默认值）。
+ *
+ * 与 config list 的整表合并保持同一优先级链：包级持久化命中即短路，
+ * 全局持久化次之，环境变量再次，最后回退声明默认值。
+ *
+ * @param key 配置键名
+ * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
+ * @param declaredItem 工程声明的配置项定义
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
+ */
+export declare function resolveMergedConfigEntry(key: string, packageId: string, declaredItem: ConfigItemDefinition | undefined, target: ActionDockTarget, reveal: boolean): Promise<{
+    value: unknown;
+    source: MergedConfigEntry["source"];
+    secret: boolean;
+}>;
+/**
+ * 构造工程范围的完整配置合并视图（config list 单一事实源）。
+ *
+ * 键全集 = 工程声明键 ∪ 包级持久化键 ∪ 全局持久化键，
+ * 每个键按 resolveMergedConfigEntry 相同的优先级链取值，
+ * 消除 config get 与 config list 两命令间的合并实现差异。
+ *
+ * @param root 工程根目录
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文
+ */
+export declare function buildMergedConfigEntries(root: string, target: ActionDockTarget, reveal: boolean): Promise<MergedConfigEntry[]>;

package/dist/services/config-merge.js

@@ -0,0 +1,93 @@
+import { isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue, } from "@actiondock/core";
+/**
+ * 解析单个配置键的合并视图（项目包级 > 全局持久化 > 环境变量 > 声明默认值）。
+ *
+ * 与 config list 的整表合并保持同一优先级链：包级持久化命中即短路，
+ * 全局持久化次之，环境变量再次，最后回退声明默认值。
+ *
+ * @param key 配置键名
+ * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
+ * @param declaredItem 工程声明的配置项定义
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
+ */
+export async function resolveMergedConfigEntry(key, packageId, declaredItem, target, reveal) {
+    const confView = await target.getConfig(packageId, key);
+    const envResolved = resolveEnvValue(key, declaredItem, packageId);
+    let rawValue;
+    let source;
+    if (confView && confView.configured) {
+        rawValue = confView.value;
+        source = confView.source === "package" ? "project" : confView.source;
+    }
+    else if (envResolved !== undefined) {
+        rawValue = envResolved.value;
+        source = "env";
+    }
+    else {
+        rawValue = declaredItem?.default;
+        source = "default";
+    }
+    const isSecret = confView?.secret ?? isSecretConfigKey(key, declaredItem);
+    const displayValue = !reveal && isSecret && rawValue !== undefined ? maskSecretValue(rawValue) : rawValue;
+    return { value: displayValue, source, secret: isSecret };
+}
+/**
+ * 构造工程范围的完整配置合并视图（config list 单一事实源）。
+ *
+ * 键全集 = 工程声明键 ∪ 包级持久化键 ∪ 全局持久化键，
+ * 每个键按 resolveMergedConfigEntry 相同的优先级链取值，
+ * 消除 config get 与 config list 两命令间的合并实现差异。
+ *
+ * @param root 工程根目录
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文
+ */
+export async function buildMergedConfigEntries(root, target, reveal) {
+    const projConfig = loadProjectConfig(root);
+    const declared = projConfig.config || {};
+    const projectConfigList = await target.listConfig(projConfig.id);
+    const globalConfigList = await target.listConfig("global");
+    const projectConfigMap = new Map(projectConfigList.map((c) => [c.key, c]));
+    const globalConfigMap = new Map(globalConfigList.map((c) => [c.key, c]));
+    const allKeys = new Set([
+        ...Object.keys(declared),
+        ...projectConfigList.map((c) => c.key),
+        ...globalConfigList.map((c) => c.key),
+    ]);
+    const entries = [];
+    for (const key of allKeys) {
+        const declaredItem = declared[key];
+        const envResolved = resolveEnvValue(key, declaredItem, projConfig.id);
+        const projItem = projectConfigMap.get(key);
+        const globItem = globalConfigMap.get(key);
+        let rawValue;
+        let source;
+        if (projItem && projItem.configured && projItem.source === "package") {
+            rawValue = projItem.value;
+            source = "project";
+        }
+        else if (globItem && globItem.configured) {
+            rawValue = globItem.value;
+            source = "global";
+        }
+        else if (envResolved !== undefined) {
+            rawValue = envResolved.value;
+            source = "env";
+        }
+        else {
+            rawValue = declaredItem?.default;
+            source = "default";
+        }
+        const isSecret = isSecretConfigKey(key, declaredItem);
+        const displayValue = !reveal && isSecret && rawValue !== undefined ? maskSecretValue(rawValue) : rawValue;
+        entries.push({
+            key,
+            value: displayValue,
+            source,
+            secret: isSecret,
+            ...(declaredItem?.description !== undefined ? { description: declaredItem.description } : {}),
+        });
+    }
+    return entries;
+}

package/dist/services/index.d.ts

@@ -1 +1,2 @@
 export * from "./inspect.js";
+export * from "./config-merge.js";

package/dist/services/index.js

@@ -1 +1,2 @@
 export * from "./inspect.js";
+export * from "./config-merge.js";

package/dist/types.d.ts

@@ -67,8 +67,6 @@ export interface CliContext {
     dataDir?: string;
     /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
     customHome?: string;
-    /** 默认信封包装输出模式 */
-    defaultEnvelope?: boolean;
     /** 自定义标准输出写入函数 */
     stdout?: (msg: string) => void;
     /** 自定义标准错误写入函数 */

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@ export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
+export * from "./input.js";

package/dist/utils/index.js

@@ -5,3 +5,4 @@ export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
+export * from "./input.js";

package/dist/utils/input.d.ts

@@ -0,0 +1,46 @@
+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>;

package/dist/utils/input.js

@@ -0,0 +1,89 @@
+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 {};
+}

package/dist/utils/spawn.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 校验包管理器依赖说明符仅包含白名单字符。
+ * 非法字符直接抛出参数错误，不进入子进程拼接链路。
+ *
+ * @param spec 待校验的包说明符（如 `@scope/pkg@^1.2.3`）
+ */
+export declare function assertSafePackageSpec(spec: string): void;
 /**
  * 子进程执行结果视图。
  */
@@ -16,6 +23,12 @@ export interface SpawnAsyncResult {
  *
  * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
  *
+ * win32 shell 取舍说明：npm 在 Windows 上是 `.cmd` 批处理脚本，Node 20.12+
+ * 针对 CVE-2024-27980 的缓解措施使 `shell:false` 直接 spawn `.cmd` 抛出 EINVAL，
+ * 因此 win32 保留 shell 拼接模式；命令注入面由调用方的
+ * assertSafePackageSpec 白名单前置校验关闭（包说明符仅允许
+ * 字母数字与 `@/:/-_/.+`，全部 shell 元字符被拒绝）。
+ *
  * @param command 可执行文件名
  * @param args 参数列表
  * @param options 附加选项（cwd 与 shell 策略）

package/dist/utils/spawn.js

@@ -1,9 +1,40 @@
 import { spawn } from "node:child_process";
+import { ArgumentError } from "../errors.js";
+/**
+ * npm/bun 包说明符白名单字符集。
+ *
+ * 覆盖 npm 依赖说明符语法所需的安全字符：
+ * - 字母数字与 `.`（名称与版本组成）
+ * - `@`（scope 前缀与版本定界符）、`/`（scope 分隔符）
+ * - `:`（git 协议与 tag 前缀）、`-` 与 `_`（名称连字符与版本预发布段）
+ * - `+`（semver build 元数据）
+ *
+ * 显式拒绝全部 shell 元字符（空格、引号、`$`、反引号、`&`、`|`、`<`、`>`、`(`、`)` 等），
+ * 从源头消除 win32 shell 拼接模式下的命令注入面。
+ */
+const PACKAGE_SPEC_PATTERN = /^[a-zA-Z0-9@/:\-_.+]+$/;
+/**
+ * 校验包管理器依赖说明符仅包含白名单字符。
+ * 非法字符直接抛出参数错误，不进入子进程拼接链路。
+ *
+ * @param spec 待校验的包说明符（如 `@scope/pkg@^1.2.3`）
+ */
+export function assertSafePackageSpec(spec) {
+    if (!PACKAGE_SPEC_PATTERN.test(spec)) {
+        throw new ArgumentError(`Invalid package specifier '${spec}': only letters, digits, '@', '/', ':', '-', '_', '.', '+' are allowed`);
+    }
+}
 /**
  * 异步执行子进程（Promise 化 spawn），保留 win32 shell 处理与退出码透传。
  *
  * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
  *
+ * win32 shell 取舍说明：npm 在 Windows 上是 `.cmd` 批处理脚本，Node 20.12+
+ * 针对 CVE-2024-27980 的缓解措施使 `shell:false` 直接 spawn `.cmd` 抛出 EINVAL，
+ * 因此 win32 保留 shell 拼接模式；命令注入面由调用方的
+ * assertSafePackageSpec 白名单前置校验关闭（包说明符仅允许
+ * 字母数字与 `@/:/-_/.+`，全部 shell 元字符被拒绝）。
+ *
  * @param command 可执行文件名
  * @param args 参数列表
  * @param options 附加选项（cwd 与 shell 策略）

package/dist/utils/target.d.ts

@@ -29,12 +29,27 @@ export interface TargetResolutionOptions {
     /** 是否允许向非回环地址发送明文 HTTP 请求（对应 --allow-insecure-http） */
     allowInsecureHttp?: boolean;
 }
+/**
+ * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
+ *
+ * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
+ * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
+ *
+ * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
+ * @param context CLI 上下文
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ */
+export declare function resolveTargetFromOptions(options: TargetResolutionOptions, context?: CliContext): ResolvedTarget;
 /**
  * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
  *
  * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
  * 都保证 target 资源被正确释放，业务异常原样透传。
  *
+ * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
+ * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
+ * 需要持有者语义的执行命令通过 localOptions.ownDataDir 显式声明。
+ *
  * @param options 命令选项视图（profile/server/token/package/dataDir/insecure/allowInsecureHttp）
  * @param context CLI 上下文
  * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
@@ -45,6 +60,12 @@ export declare function withTarget(options: TargetResolutionOptions, context: Cl
     localRoot?: string | (() => string | undefined);
     /** 是否扫描全局链接包（对应 scanLinkedPackages） */
     scanLinkedPackages?: boolean;
+    /**
+     * 是否以数据目录持有者身份打开本地 Host：true 时 App 存储打开阶段收割遗留孤儿运行。
+     * 执行类命令（ad run）应置 true；查询类命令（state/runs/config/list/describe）
+     * 保持缺省 false，避免误收割并发 serve 进程的在途运行记录。
+     */
+    ownDataDir?: boolean;
 }): Promise<void>;
 /**
  * 仅远端模式目标执行辅助：创建远端 Target 并保证资源释放。

package/dist/utils/target.js

@@ -15,31 +15,51 @@ export function applyTargetOptions(command) {
         .option("-k, --insecure", "Allow insecure server connections (skip TLS certificate validation)")
         .option("--allow-insecure-http", "Allow sending auth token over unencrypted HTTP to non-loopback hosts");
 }
+/**
+ * 目标拓扑解析单一入口：从命令选项视图解析远端/本地目标拓扑信息。
+ *
+ * 收拢全部解析字段（profile/server/token/insecure/allowInsecureHttp），
+ * 消除命令间逐字段内联复制导致的漂移（如漏传 allowInsecureHttp）。
+ *
+ * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
+ * @param context CLI 上下文
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ */
+export function resolveTargetFromOptions(options, context) {
+    return resolveTarget({
+        profile: options.profile,
+        server: options.server,
+        token: options.token,
+        insecure: options.insecure,
+        allowInsecureHttp: options.allowInsecureHttp,
+    }, context?.customHome);
+}
 /**
  * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
  *
  * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
  * 都保证 target 资源被正确释放，业务异常原样透传。
  *
+ * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
+ * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
+ * 需要持有者语义的执行命令通过 localOptions.ownDataDir 显式声明。
+ *
  * @param options 命令选项视图（profile/server/token/package/dataDir/insecure/allowInsecureHttp）
  * @param context CLI 上下文
  * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
  * @param localOptions 本地分支附加选项（如 scanLinkedPackages）与 localRoot 回退策略
  */
 export async function withTarget(options, context, fn, localOptions) {
-    const resolved = resolveTarget({
-        profile: options.profile,
-        server: options.server,
-        token: options.token,
-        insecure: options.insecure,
-        allowInsecureHttp: options.allowInsecureHttp,
-    }, context?.customHome);
+    const resolved = resolveTargetFromOptions(options, context);
     // localRoot 仅在 local 分支求值，避免远端模式下触发包寻址副作用
     const localRoot = resolved.type === "local"
         ? (typeof localOptions?.localRoot === "function" ? localOptions.localRoot() : localOptions?.localRoot) ??
             findProjectRoot() ??
             undefined
         : undefined;
+    // 本地执行命令声明持有者身份时，向 App 层透传收割开关；
+    // 查询命令保持缺省不传，存储以旁观模式打开
+    const appRecoverOrphans = localOptions?.ownDataDir === true ? { recoverOrphans: true } : undefined;
     const target = await createActionDockTarget(resolved.type === "remote"
         ? {
             type: "remote",
@@ -61,6 +81,7 @@ export async function withTarget(options, context, fn, localOptions) {
             ...(localOptions?.scanLinkedPackages !== undefined
                 ? { scanLinkedPackages: localOptions.scanLinkedPackages }
                 : undefined),
+            ...(appRecoverOrphans ? { recoverOrphans: true } : undefined),
         });
     try {
         await fn(target, resolved);
@@ -74,13 +95,7 @@ export async function withTarget(options, context, fn, localOptions) {
  * 适用于 runs cancel 等明确要求远端目标的命令。
  */
 export async function withRemoteTarget(options, context, fn) {
-    const resolved = resolveTarget({
-        profile: options.profile,
-        server: options.server,
-        token: options.token,
-        insecure: options.insecure,
-        allowInsecureHttp: options.allowInsecureHttp,
-    }, context?.customHome);
+    const resolved = resolveTargetFromOptions(options, context);
     const target = await createActionDockTarget({
         type: "remote",
         serverUrl: resolved.serverUrl,

package/dist/utils/utils.d.ts

@@ -20,18 +20,17 @@ export declare function getTargetRoot(packageOption?: string, keyHint?: string):
     key: string;
 };
 /**
- * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
 export declare function getEffectiveOptions(rawOptions: any, cmd?: any): any;
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
  */
 export declare function resolveFallbackStrategy(options: {
     fallback?: boolean;
     json?: boolean;
-    envelope?: boolean;
 }): {
     isMachine: boolean;
     shouldFallback: boolean;

package/dist/utils/utils.js

@@ -1,5 +1,5 @@
 import { resolvePackageRoot, findProjectRoot } from "@actiondock/core";
-import { ArgumentError } from "../errors.js";
+import { ArgumentError, notInProjectError, packageNotFoundError } from "../errors.js";
 /**
  * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
  * 多个关键字使用 '|'（正则逻辑或）连接。
@@ -78,16 +78,16 @@ export function getTargetRoot(packageOption, keyHint) {
     const root = resolvePackageRoot(targetPackage) || (targetPackage ? null : findProjectRoot());
     if (!root) {
         if (targetPackage) {
-            throw new ArgumentError(`Package '${targetPackage}' not found in linked packages or path`);
+            throw packageNotFoundError(targetPackage);
         }
         else {
-            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found). Please specify -P, --package <id> or cd into a project directory.");
+            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
         }
     }
     return { root, key: effectiveKey };
 }
 /**
- * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
 export function getEffectiveOptions(rawOptions, cmd) {
     if (cmd && typeof cmd.optsWithGlobals === "function") {
@@ -97,11 +97,11 @@ export function getEffectiveOptions(rawOptions, cmd) {
 }
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
  */
 export function resolveFallbackStrategy(options) {
-    const isMachine = Boolean(options.json || options.envelope);
+    const isMachine = Boolean(options.json);
     const fallbackExplicit = options.fallback === true ||
         (Array.isArray(process.argv) && process.argv.includes("--fallback"));
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.5.1",
+  "version": "2.6.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.5.1",
-    "@actiondock/core": "^2.5.1",
-    "@actiondock/mcp": "^2.5.1",
-    "@actiondock/runtime-node": "^2.5.1",
-    "@actiondock/sdk": "^2.5.1",
+    "@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",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },