@actiondock/cli 2.5.0 → 2.6.0

package/README.md

@@ -51,7 +51,14 @@ ad add @actiondock/example-tools
 
 - 本地执行 Action：
 ```bash
+# 简单参数直接内联传递
 ad run sample.greet --input '{"name": "Alice"}'
+
+# 复杂参数或对象从文件读取
+ad run sample.greet --input-file input.json
+
+# 自动化与脚本通过标准输入传递
+cat input.json | ad run sample.greet --input-file -
 ```
 
 - 运行单元测试：
@@ -92,14 +99,48 @@ ad pack
 - `-v, -V, --version`：打印版本号并退出。
 - `-h, --help`：打印命令帮助并退出。
 - `--json`：以标准 JSON 格式输出结果。
-- `--envelope`：将输出包装为标准信封结构对象（包含 `ok: true, data: T` 或 `ok: false, error: { code, message, details }`）。
-- `--data-dir <path>`：指定自定义数据存储目录，实现多测试或多任务数据隔离。
+- `--data-dir <path>`：指定运行时数据库存储目录（包级 `runtime.db`、全局 `global.db` 与目录排他锁），实现多测试或多任务运行数据隔离。注意：本选项仅隔离 SQLite 数据文件，环境配置（profile）与全局注册表（registry）属于用户根目录资产，不受 `--data-dir` 影响。
+- `ACTIONDOCK_HOME=<path>`（环境变量）：指定 ActionDock 用户根目录基准（默认对应操作系统的用户主目录）。如需隔离环境配置 `profiles.json`、全局注册表 `registry.json` 或本地证书，请通过设置此环境变量实现沙箱与自动化测试隔离。
 
 ### 严格目标解析机制
 
 - 严格目标定位：通过 `-P, --package <id|path>` 指定目标包。系统严格区分物理路径与注册表包标识符，若目标不存在则不向当前目录或父级目录隐式回退，直接以参数校验错误退出。
 - 多目标检索契约：在执行多目标检索（如 `ad info` 或 `ad list`）时，若无任何匹配项，在机器模式下始终返回确定性空数组结构并以状态码 0 退出，不因空搜索产生异常中断。
 
+### Action 执行入参契约
+
+执行 Action 支持两种互斥的传参方式：
+
+- 简单内联参数：使用 `--input <json>` 直接解析 JSON 字符串，适合简易标量入参。
+- 复杂对象文件：使用 `--input-file <path>` 读取文件并解析 JSON，避免各类终端的引号转义损坏。
+- 标准输入管道：使用 `--input-file -` 从标准输入读取全部数据并解析 JSON，适合跨进程协同与 CI 自动化脚本。
+- 默认无输入：未指定 `--input` 与 `--input-file` 时，入参默认提供 `{}`。
+- 严格互斥：`--input` 与 `--input-file` 互斥，同时提供时直接报错并退出。
+- 统一解析：无论内联参数、文件还是标准输入，解析前均自动剔除 UTF-8 BOM 标记，且不设人为大小上限。
+
+### Windows 与多终端传参建议
+
+针对 Windows PowerShell、cmd 以及各终端中复杂 JSON 容易遇到的双引号转义问题，推荐按以下规范传参：
+
+- 简单入参：使用 `--input`，如 `ad run greet --input '{"name":"Alice"}'`。
+- 复杂结构：推荐先保存为 JSON 文件并使用 `--input-file`，如 `ad run complex-action --input-file input.json`。
+- 动态生成输入：通过管道输出配合 `--input-file -` 传递，在 PowerShell 中可执行：
+
+```powershell
+$data = @{
+  name = "Alice"
+  options = @{
+    lang = "zh-CN"
+  }
+}
+$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`）。
+
 ---
 
 ## 常用命令速查
@@ -112,7 +153,7 @@ ad pack
 | `ad info [patterns...]` | 检索包元数据与能力清单，支持模式匹配与树形展示 |
 | `ad list [patterns...]` | 列出包内所有已注册的 Action |
 | `ad describe <id>` | 查看 Action 的详情、参数与模式规范（别名 `ad show`） |
-| `ad run <id>` | 本地或远程执行指定 Action 并输出标准信封结果 |
+| `ad run <id>` | 本地或远程执行指定 Action（默认输出原始纯文本，支持 `--json` 输出标准信封） |
 | `ad validate [id]` | 校验 Action 规范与模式规范 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
 | `ad action create <id>` | 创建新 Action 源码（别名 `ad action new`） |

package/dist/commands/action/create.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { assertPathWithinRoot, findProjectRoot, getPackageSlug, loadManifest, loadProjectConfig, saveManifest, writeActionTypes, } from "@actiondock/core";
-import { ExecutionError } from "../../errors.js";
+import { ExecutionError, notInProjectError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
 import { attachDescribeCommand } from "../describe.js";
 import { attachListCommand } from "../list.js";
@@ -89,7 +89,7 @@ export function registerActionCommands(program, context) {
 export async function handleActionCreate(id, options, context) {
     const root = findProjectRoot();
     if (!root) {
-        throw new ExecutionError("Not in an ActionDock project (actiondock.json not found)");
+        throw notInProjectError();
     }
     try {
         const config = loadProjectConfig(root);

package/dist/commands/add.js

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { ActionPackageResolver, beginTransaction, computeManifestDigest, findProjectRoot, getInstallCommand, loadLockfile, loadManifest, MANIFEST_FILE_NAME, parseJsonWithoutDuplicates, saveLockfile, saveManifest, } from "@actiondock/core";
-import { ArgumentError, ExecutionError } from "../errors.js";
+import { ArgumentError, ExecutionError, notInProjectError } from "../errors.js";
 import { renderResult } from "../renderer.js";
-import { getEffectiveOptions, spawnAsync } from "../utils/index.js";
+import { assertSafePackageSpec, getEffectiveOptions, spawnAsync } from "../utils/index.js";
 /**
  * 从安装说明符中提取基础 npm 包名（去除版本号及前缀范围）。
  */
@@ -34,17 +34,18 @@ export function registerAddCommand(program, context) {
         .option("-D, --dev", "Install package as development dependency")
         .option("-P, --package <path>", "Target project directory path")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (packageSpec, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const root = options.package ? resolve(options.package) : findProjectRoot();
         if (!root) {
-            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <path> or cd into a project directory.");
+            throw notInProjectError("Please specify -P, --package <path> or cd into a project directory.");
         }
         const manifest = loadManifest(root);
         if (!manifest) {
             throw new ArgumentError(`actiondock.json not found in ${root}`);
         }
+        // 包说明符白名单前置校验：拒绝 shell 元字符，消除 win32 shell 拼接注入面
+        assertSafePackageSpec(packageSpec);
         const npmPackageName = extractNpmPackageName(packageSpec);
         // 获取排他修改锁并创建事务快照
         const tx = await beginTransaction(root, `ad add ${packageSpec}`);
@@ -131,7 +132,6 @@ export function registerAddCommand(program, context) {
             };
             renderResult(resultPayload, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => `Successfully added and locked '${resultPayload.packageId}' (v${resultPayload.version}) from ${resultPayload.npmPackage}.`,
                 context,
             });

package/dist/commands/build.js

@@ -1,5 +1,5 @@
 import { findProjectRoot, resolvePackageRoot } from "@actiondock/core";
-import { ExecutionError } from "../errors.js";
+import { ExecutionError, notInProjectError, packageNotFoundError } from "../errors.js";
 import { renderResult, writeStdout } from "../renderer.js";
 import { getEffectiveOptions, parseListOption } from "../utils/index.js";
 export function registerBuildCommand(program, context) {
@@ -27,11 +27,11 @@ export function registerBuildCommand(program, context) {
             : findProjectRoot();
         if (!root) {
             if (options.package) {
-                throw new ExecutionError(`Package '${options.package}' not found in linked packages or path`);
+                throw packageNotFoundError(options.package);
             }
-            throw new ExecutionError("Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id> or cd into a project directory.");
+            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
         }
-        const isMachine = Boolean(options.json || options.envelope);
+        const isMachine = Boolean(options.json);
         if (!isMachine) {
             writeStdout("Building Node.js delivery artifact...");
         }
@@ -57,7 +57,6 @@ export function registerBuildCommand(program, context) {
         }
         renderResult(result, {
             json: isMachine,
-            envelope: options.envelope,
             humanFormatter: () => {
                 const lines = [];
                 lines.push(`[OK] Successfully built ${result.packageId} (v${result.version})`);

package/dist/commands/config/delete.js

@@ -1,5 +1,5 @@
 import { loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError } from "../../errors.js";
+import { ArgumentError, packageNotFoundError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, withTarget } from "../../utils/index.js";
 /**
@@ -35,7 +35,7 @@ export function registerConfigDeleteCommand(configCmd, context) {
             }
             if (!root) {
                 if (options.package) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
                 await target.deleteConfig("global", key);
                 writeStdout(`[OK] Global configuration '${key}' deleted`, context);

package/dist/commands/config/env.js

@@ -1,7 +1,7 @@
-import { fetchRemoteConfigEnv, isSecretConfigKey, loadProjectConfig, resolveEnvValue, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
-import { ArgumentError } from "../../errors.js";
+import { fetchRemoteConfigEnv, isSecretConfigKey, loadProjectConfig, resolveEnvValue, resolvePackageRoot, } from "@actiondock/core";
+import { notInProjectError, packageNotFoundError } from "../../errors.js";
 import { renderConfigEnv, renderResult } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions } from "../../utils/index.js";
 /**
  * 注册 config env 子命令：诊断环境变量对声明配置的满足率。
  *
@@ -14,18 +14,11 @@ export function registerConfigEnvCommand(configCmd, context) {
         .description("Diagnose environment variable satisfaction for declared configuration")
         .option("-P, --package <id>", "Target package ID or path"))
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (identifier, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const targetPkg = identifier || options.package;
         // 远端服务分支直接查询远端配置环境诊断接口
-        const target = resolveTarget({
-            profile: options.profile,
-            server: options.server,
-            token: options.token,
-            insecure: options.insecure,
-            allowInsecureHttp: options.allowInsecureHttp,
-        }, context?.customHome);
+        const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
             const res = await fetchRemoteConfigEnv(target.serverUrl, target.token, targetPkg, {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
@@ -33,7 +26,6 @@ export function registerConfigEnvCommand(configCmd, context) {
             });
             renderResult(res, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => renderConfigEnv(res.envChecks || [], res.packageId),
                 context,
             });
@@ -47,9 +39,9 @@ export function registerConfigEnvCommand(configCmd, context) {
         const root = resolvePackageRoot(targetPkg);
         if (!root) {
             if (targetPkg) {
-                throw new ArgumentError(`Package '${targetPkg}' not found in linked packages or path`);
+                throw packageNotFoundError(targetPkg);
             }
-            throw new ArgumentError("Not in an ActionDock project.\nUsage: ad config env [package-id] or cd into a project directory.");
+            throw notInProjectError("Usage: ad config env [package-id] or cd into a project directory.");
         }
         const projConfig = loadProjectConfig(root);
         const declared = projConfig.config || {};
@@ -76,7 +68,6 @@ export function registerConfigEnvCommand(configCmd, context) {
         };
         renderResult(payload, {
             json: options.json,
-            envelope: options.envelope,
             humanFormatter: () => renderConfigEnv(envChecks, projConfig.id),
             context,
         });

package/dist/commands/config/get.js

@@ -1,19 +1,8 @@
-import { fetchRemoteConfig, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
-import { ArgumentError } from "../../errors.js";
+import { fetchRemoteConfig, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolvePackageRoot, } from "@actiondock/core";
+import { ArgumentError, packageNotFoundError } from "../../errors.js";
 import { renderResult } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, withTarget } from "../../utils/index.js";
-/**
- * 解析远端目标拓扑信息（仅信息解析，不创建 Target 实例）。
- */
-function resolveRemoteTargetInfo(options, context) {
-    return resolveTarget({
-        profile: options.profile,
-        server: options.server,
-        token: options.token,
-        insecure: options.insecure,
-        allowInsecureHttp: options.allowInsecureHttp,
-    }, context?.customHome);
-}
+import { resolveMergedConfigEntry } from "../../services/config-merge.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions, withTarget, } from "../../utils/index.js";
 /**
  * 注册 config get 子命令：查询指定配置键的生效值。
  *
@@ -29,7 +18,6 @@ export function registerConfigGetCommand(configCmd, context) {
         .option("--reveal, --show-secrets", "Reveal plain text values for secrets")
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (key, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         if (!key) {
@@ -37,7 +25,7 @@ export function registerConfigGetCommand(configCmd, context) {
         }
         const reveal = Boolean(options.reveal || options.showSecrets);
         // 远端服务分支不经过 Target 门面，直接查询远端配置接口
-        const target = resolveRemoteTargetInfo(options, context);
+        const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
             const res = await fetchRemoteConfig(target.serverUrl, target.token, options.package, {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
@@ -54,7 +42,6 @@ export function registerConfigGetCommand(configCmd, context) {
             };
             renderResult(payload, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => (displayValue !== undefined ? String(displayValue) : ""),
                 context,
             });
@@ -65,7 +52,7 @@ export function registerConfigGetCommand(configCmd, context) {
         await withTarget(options, context, async (localTarget) => {
             if (options.global || !root) {
                 if (!options.global && options.package && !root) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
                 const confView = await localTarget.getConfig("global", key);
                 const val = confView?.value;
@@ -79,7 +66,6 @@ export function registerConfigGetCommand(configCmd, context) {
                 };
                 renderResult(payload, {
                     json: options.json,
-                    envelope: options.envelope,
                     humanFormatter: () => (displayValue !== undefined ? String(displayValue) : ""),
                     context,
                 });
@@ -87,24 +73,8 @@ export function registerConfigGetCommand(configCmd, context) {
             }
             const projConfig = loadProjectConfig(root);
             const declaredItem = projConfig.config?.[key];
-            const confView = await localTarget.getConfig(projConfig.id, key);
-            let resolvedVal = confView?.value;
-            let source = confView?.source === "package" ? "project" : (confView?.source || "default");
-            const envResolved = resolveEnvValue(key, declaredItem, projConfig.id);
-            if (confView && confView.configured) {
-                resolvedVal = confView.value;
-                source = confView.source === "package" ? "project" : confView.source;
-            }
-            else if (envResolved !== undefined) {
-                resolvedVal = envResolved.value;
-                source = "env";
-            }
-            else {
-                resolvedVal = declaredItem?.default;
-                source = "default";
-            }
-            const isSecret = confView?.secret ?? isSecretConfigKey(key, declaredItem);
-            const displayValue = !reveal && isSecret && resolvedVal !== undefined ? maskSecretValue(resolvedVal) : resolvedVal;
+            // 合并优先级链单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
+            const { value: displayValue, source, secret: isSecret } = await resolveMergedConfigEntry(key, projConfig.id, declaredItem, localTarget, reveal);
             const payload = {
                 key,
                 value: displayValue,
@@ -113,7 +83,6 @@ export function registerConfigGetCommand(configCmd, context) {
             };
             renderResult(payload, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => (displayValue !== undefined ? String(displayValue) : ""),
                 context,
             });

package/dist/commands/config/list.js

@@ -1,7 +1,8 @@
-import { fetchRemoteConfig, filterWithFallbackInfo, findProjectRoot, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
-import { ArgumentError } from "../../errors.js";
+import { fetchRemoteConfig, filterWithFallbackInfo, findProjectRoot, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolvePackageRoot, } from "@actiondock/core";
+import { packageNotFoundError } from "../../errors.js";
 import { renderConfigList, renderResult } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveIntent, withTarget } from "../../utils/index.js";
+import { buildMergedConfigEntries } from "../../services/config-merge.js";
+import { applyTargetOptions, getEffectiveOptions, resolveIntent, resolveTargetFromOptions, withTarget, } from "../../utils/index.js";
 /**
  * 构造单条配置项的展示视图（含掩码决策，reveal 为假且为敏感键时打码）。
  * 掩码决策收敛于命令层，renderer 仅负责值的字符串格式化。
@@ -33,20 +34,13 @@ export function registerConfigListCommand(configCmd, context) {
         .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")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (patterns = [], rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const shouldFallback = options.fallback !== false;
         const reveal = Boolean(options.reveal || options.showSecrets);
         // 远端服务分支不经过 Target 门面，直接查询远端配置接口
-        const remoteTargetInfo = resolveTarget({
-            profile: options.profile,
-            server: options.server,
-            token: options.token,
-            insecure: options.insecure,
-            allowInsecureHttp: options.allowInsecureHttp,
-        }, context?.customHome);
+        const remoteTargetInfo = resolveTargetFromOptions(options, context);
         if (remoteTargetInfo.type === "remote") {
             const res = await fetchRemoteConfig(remoteTargetInfo.serverUrl, remoteTargetInfo.token, options.package, {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
@@ -55,7 +49,6 @@ export function registerConfigListCommand(configCmd, context) {
             const entries = Object.entries(res.values || {}).map(([k, v]) => toDisplayEntry(k, v, "remote", isSecretConfigKey(k, res.declared?.[k]), reveal, res.declared?.[k]?.description || ""));
             renderResult(entries, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => renderConfigList(entries, `Remote Server ${remoteTargetInfo.serverUrl}${remoteTargetInfo.profileName ? ` (Profile: ${remoteTargetInfo.profileName})` : ""}`, false, effectiveIntent),
                 context,
             });
@@ -70,7 +63,6 @@ export function registerConfigListCommand(configCmd, context) {
                 const filterRes = filterWithFallbackInfo(entries, effectiveIntent, [(c) => c.key, (c) => c.value], shouldFallback);
                 renderResult(filterRes.items, {
                     json: options.json,
-                    envelope: options.envelope,
                     humanFormatter: () => renderConfigList(filterRes.items, "Global Scope", filterRes.isFallback, effectiveIntent),
                     context,
                 });
@@ -78,63 +70,24 @@ export function registerConfigListCommand(configCmd, context) {
             }
             if (!root) {
                 if (options.package) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
                 const all = await localTarget.listConfig("global");
                 const entries = all.map((item) => toDisplayEntry(item.key, item.value, "global", item.secret || isSecretConfigKey(item.key), reveal));
                 const filterRes = filterWithFallbackInfo(entries, effectiveIntent, [(c) => c.key, (c) => c.value], shouldFallback);
                 renderResult(filterRes.items, {
                     json: options.json,
-                    envelope: options.envelope,
                     humanFormatter: () => renderConfigList(filterRes.items, "Global Scope (No project found)", filterRes.isFallback, effectiveIntent),
                     context,
                 });
                 return;
             }
             const projConfig = loadProjectConfig(root);
-            const declared = projConfig.config || {};
-            const globalConfigList = await localTarget.listConfig("global");
-            const projectConfigList = await localTarget.listConfig(projConfig.id);
-            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),
-            ]);
-            // 配置合并优先级：项目包级 > 全局持久化 > 环境变量 > 声明默认值。
-            // core 的 RuntimeConfig.describe 已是五层链事实源，但 Target 门面仅按作用域暴露
-            // listConfig(scope)，不提供跨作用域合并视图；此处保持命令层合并逻辑，
-            // 与 app.getConfig 的 describe 委托链行为语义一致（overrides 层仅存在于 run 链路）。
-            const merged = Array.from(allKeys).map((k) => {
-                let rawValue;
-                let source = "default";
-                const envResolved = resolveEnvValue(k, declared[k], projConfig.id);
-                const projItem = projectConfigMap.get(k);
-                const globItem = globalConfigMap.get(k);
-                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 = declared[k]?.default;
-                    source = "default";
-                }
-                const isSecret = isSecretConfigKey(k, declared[k]);
-                return toDisplayEntry(k, rawValue, source, isSecret, reveal, declared[k]?.description || "");
-            });
+            // 跨作用域合并视图单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
+            const merged = await buildMergedConfigEntries(root, localTarget, reveal);
             const filterRes = filterWithFallbackInfo(merged, effectiveIntent, [(c) => c.key, (c) => c.value, (c) => c.description, (c) => c.source], shouldFallback);
             renderResult(filterRes.items, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => renderConfigList(filterRes.items, `${projConfig.name} (${projConfig.id})`, filterRes.isFallback, effectiveIntent),
                 context,
             });

package/dist/commands/config/schema.js

@@ -1,5 +1,5 @@
 import { createActionDockTarget, isSecretConfigKey, loadProjectConfig, resolveEnvValue, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError, ExecutionError } from "../../errors.js";
+import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError } from "../../errors.js";
 import { renderConfigSchema, renderResult, writeStdout } from "../../renderer.js";
 import { getEffectiveOptions } from "../../utils/index.js";
 /**
@@ -16,7 +16,6 @@ export function registerConfigSchemaCommand(configCmd, context) {
         .option("-P, --package <id>", "Target package ID or path")
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (identifier, rawOptions, cmd) => {
         try {
             const options = getEffectiveOptions(rawOptions, cmd);
@@ -24,9 +23,9 @@ export function registerConfigSchemaCommand(configCmd, context) {
             const root = resolvePackageRoot(targetPkg);
             if (!root) {
                 if (targetPkg) {
-                    throw new ArgumentError(`Package '${targetPkg}' not found in linked packages or path`);
+                    throw packageNotFoundError(targetPkg);
                 }
-                throw new ArgumentError("Not in an ActionDock project.\nUsage: ad config schema [package-id] or cd into a project directory.");
+                throw notInProjectError("Usage: ad config schema [package-id] or cd into a project directory.");
             }
             const projConfig = loadProjectConfig(root);
             const declared = projConfig.config || {};
@@ -97,10 +96,9 @@ export function registerConfigSchemaCommand(configCmd, context) {
                 missingCount: missingRequired.length,
                 configs: items,
             };
-            if (options.json || options.envelope) {
+            if (options.json) {
                 renderResult(result, {
                     json: options.json,
-                    envelope: options.envelope,
                     context,
                 });
             }

package/dist/commands/config/set.js

@@ -1,5 +1,5 @@
 import { isSecretConfigKey, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError } from "../../errors.js";
+import { ArgumentError, packageNotFoundError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, withTarget } from "../../utils/index.js";
 import { resolveConfigValueInput } from "../../prompt.js";
@@ -69,7 +69,7 @@ export function registerConfigSetCommand(configCmd, context) {
             }
             if (!root) {
                 if (options.package) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
                 await target.setConfig("global", key, parsedVal);
                 writeStdout(`[OK] Global configuration '${key}' updated (no project in current directory)`, context);

package/dist/commands/describe.js

@@ -1,4 +1,4 @@
-import { ArgumentError, ExecutionError } from "../errors.js";
+import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
 import { renderActionDetail, renderResult } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
 /**
@@ -15,7 +15,6 @@ export function attachDescribeCommand(parent, context) {
         .option("-P, --package <id>", "Target package ID or path");
     return applyTargetOptions(cmd)
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .option("--data-dir <path>", "Custom database storage directory")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
@@ -25,7 +24,7 @@ export function attachDescribeCommand(parent, context) {
         // 目标拓扑解析（仅 local 分支需要包寻址）
         const targetPackageRoot = resolveLocalPackageRoot(options.package);
         if (options.package && !targetPackageRoot) {
-            throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            throw packageNotFoundError(options.package);
         }
         let targetRef = id;
         if (options.package && !id.includes("/") && !id.includes(":")) {
@@ -57,7 +56,6 @@ export function attachDescribeCommand(parent, context) {
             };
             renderResult(detail, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => renderActionDetail(detail),
                 context,
             });

package/dist/commands/doctor.js

@@ -1,7 +1,7 @@
-import { fetchRemoteDoctor, resolveTarget, runDoctorChecks } from "@actiondock/core";
+import { fetchRemoteDoctor, runDoctorChecks } from "@actiondock/core";
 import { ExecutionError } from "../errors.js";
 import { renderResult } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions } from "../utils/index.js";
 export function registerDoctorCommand(program, context) {
     const cmd = program
         .command("doctor")
@@ -9,16 +9,10 @@ export function registerDoctorCommand(program, context) {
         .option("-P, --package <id|path>", "Target package ID or directory path for project diagnostics");
     applyTargetOptions(cmd)
         .option("--json", "Output diagnostics report in JSON format")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (rawOptions, cmd) => {
         try {
             const options = getEffectiveOptions(rawOptions, cmd);
-            const target = resolveTarget({
-                profile: options.profile,
-                server: options.server,
-                token: options.token,
-                insecure: options.insecure,
-            }, context?.customHome);
+            const target = resolveTargetFromOptions(options, context);
             let report;
             if (target.type === "remote") {
                 const remoteRes = await fetchRemoteDoctor(target.serverUrl, target.token, options.package, {
@@ -35,7 +29,6 @@ export function registerDoctorCommand(program, context) {
             }
             renderResult(report, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => {
                     const lines = [];
                     const title = target.type === "remote"

package/dist/commands/export.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { basename } from "node:path";
 import { discoverProjects, findProjectRoot, listLinkedPackages, resolvePackageRoot } from "@actiondock/core";
-import { ExecutionError } from "../errors.js";
+import { ExecutionError, notInProjectError, packageNotFoundError } from "../errors.js";
 import { renderResult, writeStdout } from "../renderer.js";
 import { getEffectiveOptions, parseListOption } from "../utils/index.js";
 export function registerExportCommand(program, context) {
@@ -68,7 +68,7 @@ export function registerExportCommand(program, context) {
             for (const pkgIdOrPath of options.package) {
                 const root = resolvePackageRoot(pkgIdOrPath);
                 if (!root) {
-                    throw new ExecutionError(`Package '${pkgIdOrPath}' not found in linked packages or path`);
+                    throw packageNotFoundError(pkgIdOrPath);
                 }
                 if (!roots.includes(root)) {
                     roots.push(root);
@@ -81,13 +81,13 @@ export function registerExportCommand(program, context) {
                 roots.push(root);
             }
             else {
-                throw new ExecutionError("Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id>, --workspace, --all, or cd into a project directory.");
+                throw notInProjectError("Please specify -P, --package <id>, --workspace, --all, or cd into a project directory.");
             }
         }
         if (roots.length > 1 && (options.actions || options.playbook)) {
             throw new ExecutionError("Filtering options (--actions, --playbook) can only be used when exporting a single package.");
         }
-        const isMachine = Boolean(options.json || options.envelope);
+        const isMachine = Boolean(options.json);
         try {
             const { exportCompositeSkill, exportSkill, exportSkillBatch } = await import("@actiondock/builder");
             if (options.bundle !== undefined) {
@@ -109,7 +109,6 @@ export function registerExportCommand(program, context) {
                 });
                 renderResult(result, {
                     json: isMachine,
-                    envelope: options.envelope,
                     humanFormatter: () => {
                         const lines = [];
                         lines.push(`[OK] Successfully exported Composite Skill: ${result.bundleName}`);
@@ -150,7 +149,6 @@ export function registerExportCommand(program, context) {
                 });
                 renderResult(batchRes, {
                     json: isMachine,
-                    envelope: options.envelope,
                     humanFormatter: () => {
                         const lines = [];
                         lines.push(`[OK] Successfully batch exported ${batchRes.results.length} Skill packages to: ${batchRes.outDir}`);
@@ -183,7 +181,6 @@ export function registerExportCommand(program, context) {
             });
             renderResult(result, {
                 json: isMachine,
-                envelope: options.envelope,
                 humanFormatter: () => {
                     const lines = [];
                     lines.push(`[OK] Successfully exported ${result.mode === "node" ? "Node Directory" : "Source"} Skill: ${result.packageId} (v${result.version})`);