@actiondock/cli 2.7.0 → 2.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @actiondock/cli
 
-ActionDock 2.0 官方命令行门面工具链。
+ActionDock 2.x 官方命令行门面工具链。
 
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
@@ -15,7 +15,6 @@ ActionDock 2.0 官方命令行门面工具链。
 - 原生基于 Node.js >=24.12.0 运行，充分依托原生类型擦除、内置 SQLite 与原生 HTTP 特性。
 - 支持 npm、pnpm 与 yarn 标准包管理器进行全局安装与项目级管理。
 - 日常开发、调试、测试、构建、打包、MCP 服务启动与 HTTP 部署完全基于 Node.js 与 npm 标准工作流，无需安装外部编译器。
-- 单文件独立二进制构建（`--target`、`--bytecode`、`--standalone`）与 `actiondock.manifest.json` 已在 2.0 中彻底移除，由标准的 Node.js 目录交付产物与 npm 打包取代。
 
 ---
 
@@ -109,6 +108,7 @@ ad pack
 
 - 严格目标定位：通过 `-P, --package <id|path>` 指定目标包。系统严格区分物理路径与注册表包标识符，若目标不存在则不向当前目录或父级目录隐式回退，直接以参数校验错误退出。
 - 多目标检索契约：在执行多目标检索（如 `ad info` 或 `ad list`）时，若无任何匹配项，在机器模式下始终返回确定性空数组结构并以状态码 0 退出，不因空搜索产生异常中断。
+- 服务端细粒度白名单：通过 `ad serve` 启动微服务时，支持通过 `-P, --package <package-id>` 与 `-A, --action <action-ref>` 分别指定包白名单与动作白名单（支持短名与全限定名，可多次指定或逗号分隔）。同时配置时取权限交集。未授权动作的详情调阅与执行均被阻断并返回 403 错误（错误码 `ACTION_FORBIDDEN`），历史运行记录与 MCP 协议工具暴露同步过滤。
 
 ### Action 执行入参契约
 
@@ -181,7 +181,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad export skill` | 导出 Agent Skill 技能包（支持 `--mode source` 与 `--mode node`） |
 | `ad link` / `unlink` | 注册或注销工作区全局路由与符号链接 |
 | `ad profile` | 管理远程执行节点凭证与环境配置 |
-| `ad serve` | 启动远程 HTTP/HTTPS 执行调度微服务（原生支持 `--https` 自签名与生产证书） |
+| `ad serve` | 启动远程 HTTP/HTTPS 执行调度微服务（支持 `-P` 包白名单与 `-A` 动作白名单细粒度权限控制，原生支持 `--https` 自签名与生产证书） |
 | `ad mcp` | 以 STDIO 或 HTTP 协议启动 MCP 服务 |
 
 ---
@@ -190,10 +190,9 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 
 作为顶层门面与独立运行分发器，`@actiondock/cli` 串联以下子包：
 
-- 运行时适配：依赖 [@actiondock/runtime-node](../runtime-node/README.md)，在启动时自动注入基于 Node.js 原生能力的驱动实现。
-- 领域内核：依赖 [@actiondock/core](../core/README.md)，调度统一调用门面 ActionDockTarget、数据目录锁 DataDirLock 与依赖事务管理器。
-- 构建与打包：依赖 [@actiondock/builder](../builder/README.md)，完成目录交付构建、npm 打包与技能导出。
-- 协议服务：通过 [@actiondock/mcp](../mcp/README.md) 启动协议监听。
+- 领域内核与运行时：依赖 [@actiondock/core](../core/README.md)，统一对接标准服务端口体系（`DiscoveryPort`、`ExecutionPort`、`RunsPort`、`ConfigPort`、`StatePort`）与统一服务门面（`createActionDock`、`connectActionDock`），承载原生运行时、存储驱动与受管进程治理。
+- 构建与打包：依赖 [@actiondock/builder](../builder/README.md)，完成依赖闭包规划、Node 目录交付产物构建、npm 打包与 Agent Skill 资产导出。
+- 协议服务：通过 [@actiondock/mcp](../mcp/README.md) 启动 Model Context Protocol 协议监听与适配。
 
 ---
 

package/bin/ad.js

@@ -1,42 +1,71 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const distEntry = resolve(import.meta.dirname, "../dist/index.js");
+const isBun = typeof process.versions.bun !== "undefined";
+const hasTsx =
+  process.execArgv.some((arg, i) => arg === "--import" && process.execArgv[i + 1]?.includes("tsx")) ||
+  process.execArgv.some((arg) => arg.includes("tsx"));
 
-if (existsSync(distEntry)) {
-  const { runCliProcess } = await import(pathToFileURL(distEntry).href);
-  await runCliProcess(process.argv);
-} else {
-  const isBun = typeof process.versions.bun !== "undefined";
-  const hasTsx =
-    process.execArgv.some((arg, i) => arg === "--import" && process.execArgv[i + 1]?.includes("tsx")) ||
-    process.execArgv.some((arg) => arg.includes("tsx"));
-
-  if (!isBun && !hasTsx) {
-    const require = createRequire(import.meta.url);
-    let tsxSpecifier = null;
+if (!isBun && !hasTsx) {
+  const require = createRequire(import.meta.url);
+  let tsxSpecifier = null;
+  try {
+    tsxSpecifier = pathToFileURL(require.resolve("tsx", { paths: [import.meta.dirname, process.cwd()] })).href;
+  } catch {
     try {
       tsxSpecifier = pathToFileURL(require.resolve("tsx")).href;
     } catch {
       // 未检测到 tsx 模块
     }
+  }
+
+  if (tsxSpecifier) {
+    const child = spawn(
+      process.execPath,
+      ["--import", tsxSpecifier, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+      {
+        stdio: "inherit",
+      }
+    );
+
+    const forwardSignal = (sig) => {
+      if (child.pid && !child.killed) {
+        try {
+          child.kill(sig);
+        } catch {}
+      }
+    };
+
+    process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+    process.on("SIGINT", () => forwardSignal("SIGINT"));
+    process.on("SIGHUP", () => forwardSignal("SIGHUP"));
 
-    if (tsxSpecifier) {
-      const res = spawnSync(
-        process.execPath,
-        ["--import", tsxSpecifier, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
-        {
-          stdio: "inherit",
+    await new Promise((resolvePromise) => {
+      child.on("exit", (code, signal) => {
+        if (signal) {
+          process.removeListener("SIGTERM", forwardSignal);
+          process.removeListener("SIGINT", forwardSignal);
+          process.removeListener("SIGHUP", forwardSignal);
+          process.kill(process.pid, signal);
+        } else {
+          process.exit(code ?? 0);
         }
-      );
-      process.exit(res.status ?? (res.signal ? 1 : 0));
-    }
+        resolvePromise();
+      });
+    });
   }
+}
+
+const distEntry = resolve(import.meta.dirname, "../dist/index.js");
 
+if (existsSync(distEntry)) {
+  const { runCliProcess } = await import(pathToFileURL(distEntry).href);
+  await runCliProcess(process.argv);
+} else {
   const { runCliProcess } = await import("../src/index.ts");
   await runCliProcess(process.argv);
 }

package/dist/commands/action/create.js

@@ -1,7 +1,8 @@
 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, notInProjectError } from "../../errors.js";
+import { assertPathWithinRoot, getPackageSlug, loadManifest, saveManifest, writeActionTypes, } from "@actiondock/core/project";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { ExecutionError, notInProjectError, wrapAsExecutionError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
 import { attachDescribeCommand } from "../describe.js";
 import { attachListCommand } from "../list.js";
@@ -210,8 +211,6 @@ ${returnBody}
         writeStdout(`  复杂输入或大段文本：ad run ${id} --json --input-file input.json`, context);
     }
     catch (err) {
-        if (err instanceof ExecutionError)
-            throw err;
-        throw new ExecutionError(err.message);
+        throw wrapAsExecutionError(err);
     }
 }

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, notInProjectError } from "../errors.js";
+import { join } from "node:path";
+import { PackageGraphBuilder, } from "@actiondock/core/graph";
+import { beginTransaction, computeManifestDigest, getInstallCommand, loadLockfile, MANIFEST_FILE_NAME, parseJsonWithoutDuplicates, saveLockfile, saveManifest, } from "@actiondock/core/project";
 import { renderResult } from "../renderer.js";
-import { assertSafePackageSpec, getEffectiveOptions, spawnAsync } from "../utils/index.js";
+import { assertSafePackageSpec, getEffectiveOptions, requireProjectManifestRoot, rollbackAndRethrow, spawnAsync, } from "../utils/index.js";
 /**
  * 从安装说明符中提取基础 npm 包名（去除版本号及前缀范围）。
  */
@@ -36,14 +36,7 @@ export function registerAddCommand(program, context) {
         .option("--json", "Output as JSON")
         .action(async (packageSpec, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
-        const root = options.package ? resolve(options.package) : findProjectRoot();
-        if (!root) {
-            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}`);
-        }
+        const { root, manifest } = requireProjectManifestRoot(options.package);
         // 包说明符白名单前置校验：拒绝 shell 元字符，消除 win32 shell 拼接注入面
         assertSafePackageSpec(packageSpec);
         const npmPackageName = extractNpmPackageName(packageSpec);
@@ -97,9 +90,9 @@ export function registerAddCommand(program, context) {
             manifest.dependencies = manifest.dependencies || {};
             manifest.dependencies[targetPackageId] =
                 targetPackageId === npmPackageName ? `^${targetVersion}` : npmPackageName;
-            // 触发依赖图解析及版本冲突检测
-            const resolver = new ActionPackageResolver({ projectRoot: root, manifest });
-            const graph = resolver.resolveSync();
+            // 触发依赖图构建及版本冲突检测
+            const builder = new PackageGraphBuilder({ projectRoot: root, manifest });
+            const graph = builder.buildSync();
             // 更新 actiondock.lock.json
             const lockfile = loadLockfile(root) || {
                 lockfileVersion: 1,
@@ -137,8 +130,7 @@ export function registerAddCommand(program, context) {
             });
         }
         catch (err) {
-            await tx.rollback({ frozenInstall: false });
-            throw new ExecutionError(err.message, err, err.code || "ADD_DEPENDENCY_FAILED");
+            await rollbackAndRethrow(tx, err, "ADD_DEPENDENCY_FAILED");
         }
     });
 }

package/dist/commands/build.js

@@ -1,7 +1,6 @@
-import { findProjectRoot, resolvePackageRoot } from "@actiondock/core";
-import { ExecutionError, notInProjectError, packageNotFoundError } from "../errors.js";
+import { ExecutionError } from "../errors.js";
 import { renderResult, writeStdout } from "../renderer.js";
-import { getEffectiveOptions, parseListOption } from "../utils/index.js";
+import { getEffectiveOptions, parseListOption, requirePackageRoot } from "../utils/index.js";
 export function registerBuildCommand(program, context) {
     program
         .command("build")
@@ -14,23 +13,9 @@ export function registerBuildCommand(program, context) {
         .option("--vendor-deps", "Materialize locked production dependencies into the output")
         .option("--allow-install-scripts", "Allow lifecycle install scripts to run during vendor-deps")
         .option("--require-reproducible", "Require reproducible build and fail if install scripts must run")
-        .option("-t, --target <target>", "Target compilation platform (removed)")
-        .option("--bytecode", "Bytecode compilation (removed)")
         .action(async (rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
-        // 彻底删除原有单文件二进制输出语义
-        if (options.target !== undefined || options.bytecode !== undefined) {
-            throw new ExecutionError("Unsupported build mode: '--target' and '--bytecode' standalone single-file binary compilation have been removed in ActionDock 2.0. Directory-based Node.js builds are now the standard distribution format.", undefined, "UNSUPPORTED_BUILD_MODE");
-        }
-        const root = options.package
-            ? resolvePackageRoot(options.package)
-            : findProjectRoot();
-        if (!root) {
-            if (options.package) {
-                throw packageNotFoundError(options.package);
-            }
-            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
-        }
+        const { root } = requirePackageRoot(options.package);
         const isMachine = Boolean(options.json);
         if (!isMachine) {
             writeStdout("Building Node.js delivery artifact...");

package/dist/commands/config/delete.js

@@ -1,7 +1,8 @@
-import { loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
+import { loadProjectConfig, } from "@actiondock/core";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { ArgumentError, packageNotFoundError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, withTarget } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, withService } from "../../utils/index.js";
 /**
  * 注册 config delete 子命令：删除配置项。
  *
@@ -22,14 +23,14 @@ export function registerConfigDeleteCommand(configCmd, context) {
             throw new ArgumentError("Configuration key is required");
         }
         const root = resolvePackageRoot(options.package);
-        await withTarget(options, context, async (target, resolved) => {
+        await withService(options, context, async (service, resolved) => {
             if (resolved.type === "remote") {
-                await target.deleteConfig(options.package || "", key);
+                await service.management?.config.delete(options.package || "", key);
                 writeStdout(`[OK] Configuration '${key}' deleted from remote server`, context);
                 return;
             }
             if (options.global) {
-                await target.deleteConfig("global", key);
+                await service.management?.config.delete("global", key);
                 writeStdout(`[OK] Global configuration '${key}' deleted`, context);
                 return;
             }
@@ -37,12 +38,12 @@ export function registerConfigDeleteCommand(configCmd, context) {
                 if (options.package) {
                     throw packageNotFoundError(options.package);
                 }
-                await target.deleteConfig("global", key);
+                await service.management?.config.delete("global", key);
                 writeStdout(`[OK] Global configuration '${key}' deleted`, context);
                 return;
             }
             const projConfig = loadProjectConfig(root);
-            await target.deleteConfig(projConfig.id, key);
+            await service.management?.config.delete(projConfig.id, key);
             writeStdout(`[OK] Configuration '${key}' deleted for package '${projConfig.id}'`, context);
         });
     });

package/dist/commands/config/env.js

@@ -1,7 +1,7 @@
-import { fetchRemoteConfigEnv, isSecretConfigKey, loadProjectConfig, resolveEnvValue, resolvePackageRoot, } from "@actiondock/core";
-import { notInProjectError, packageNotFoundError } from "../../errors.js";
+import { fetchRemoteConfigEnv, resolveEnvValue, } from "@actiondock/core/profile";
+import { isSecretConfigKey, } from "@actiondock/core/project";
 import { renderConfigEnv, renderResult } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, resolveTargetFromOptions } from "../../utils/index.js";
 /**
  * 注册 config env 子命令：诊断环境变量对声明配置的满足率。
  *
@@ -36,14 +36,10 @@ export function registerConfigEnvCommand(configCmd, context) {
             return;
         }
         // 本地项目分支
-        const root = resolvePackageRoot(targetPkg);
-        if (!root) {
-            if (targetPkg) {
-                throw packageNotFoundError(targetPkg);
-            }
-            throw notInProjectError("Usage: ad config env [package-id] or cd into a project directory.");
-        }
-        const projConfig = loadProjectConfig(root);
+        const { root, projConfig } = requirePackageRoot(targetPkg, {
+            loadConfig: true,
+            hint: "Usage: ad config env [package-id] or cd into a project directory.",
+        });
         const declared = projConfig.config || {};
         const envChecks = [];
         for (const [key, itemDef] of Object.entries(declared)) {

package/dist/commands/config/get.js

@@ -1,8 +1,11 @@
-import { fetchRemoteConfig, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolvePackageRoot, } from "@actiondock/core";
+import { fetchRemoteConfig, } from "@actiondock/core/profile";
+import { isSecretConfigKey, maskSecretValue, } from "@actiondock/core/project";
+import { loadProjectConfig, } from "@actiondock/core";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { ArgumentError, packageNotFoundError } from "../../errors.js";
 import { renderResult } from "../../renderer.js";
 import { resolveMergedConfigEntry } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions, withTarget, } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions, withService, } from "../../utils/index.js";
 /**
  * 注册 config get 子命令：查询指定配置键的生效值。
  *
@@ -49,12 +52,12 @@ export function registerConfigGetCommand(configCmd, context) {
         }
         // 本地分支
         const root = resolvePackageRoot(options.package);
-        await withTarget(options, context, async (localTarget) => {
+        await withService(options, context, async (service) => {
             if (options.global || !root) {
                 if (!options.global && options.package && !root) {
                     throw packageNotFoundError(options.package);
                 }
-                const confView = await localTarget.getConfig("global", key);
+                const confView = await service.management?.config.get("global", key);
                 const val = confView?.value;
                 const isSecret = confView?.secret ?? isSecretConfigKey(key);
                 const displayValue = !reveal && isSecret && val !== undefined ? maskSecretValue(val) : val;
@@ -74,7 +77,7 @@ export function registerConfigGetCommand(configCmd, context) {
             const projConfig = loadProjectConfig(root);
             const declaredItem = projConfig.config?.[key];
             // 合并优先级链单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
-            const { value: displayValue, source, secret: isSecret } = await resolveMergedConfigEntry(key, projConfig.id, declaredItem, localTarget, reveal);
+            const { value: displayValue, source, secret: isSecret } = await resolveMergedConfigEntry(key, projConfig.id, declaredItem, service, reveal);
             const payload = {
                 key,
                 value: displayValue,

package/dist/commands/config/list.js

@@ -1,8 +1,11 @@
-import { fetchRemoteConfig, filterWithFallbackInfo, findProjectRoot, isSecretConfigKey, loadProjectConfig, maskSecretValue, resolvePackageRoot, } from "@actiondock/core";
+import { fetchRemoteConfig, } from "@actiondock/core/profile";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { filterWithFallbackInfo, isSecretConfigKey, maskSecretValue, } from "@actiondock/core/project";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
 import { packageNotFoundError } from "../../errors.js";
 import { renderConfigList, renderResult } from "../../renderer.js";
 import { buildMergedConfigEntries } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, resolveIntent, resolveTargetFromOptions, withTarget, } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveTargetFromOptions, withService, } from "../../utils/index.js";
 /**
  * 构造单条配置项的展示视图（含掩码决策，reveal 为假且为敏感键时打码）。
  * 掩码决策收敛于命令层，renderer 仅负责值的字符串格式化。
@@ -31,13 +34,14 @@ export function registerConfigListCommand(configCmd, context) {
         .option("-g, --global", "Show only global configurations"))
         .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
         .option("--reveal, --show-secrets", "Reveal plain text values for secrets")
+        .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")
         .action(async (patterns = [], rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
-        const shouldFallback = options.fallback !== false;
+        const { shouldFallback } = resolveFallbackStrategy(options);
         const reveal = Boolean(options.reveal || options.showSecrets);
         // 远端服务分支不经过 Target 门面，直接查询远端配置接口
         const remoteTargetInfo = resolveTargetFromOptions(options, context);
@@ -49,42 +53,32 @@ 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,
-                humanFormatter: () => renderConfigList(entries, `Remote Server ${remoteTargetInfo.serverUrl}${remoteTargetInfo.profileName ? ` (Profile: ${remoteTargetInfo.profileName})` : ""}`, false, effectiveIntent),
+                humanFormatter: () => renderConfigList(entries, remoteTargetLabel(remoteTargetInfo), false, effectiveIntent),
                 context,
             });
             return;
         }
-        // 本地分支（通过 Target 门面统一访问）
-        await withTarget(options, context, async (localTarget) => {
+        // 本地分支（通过 Service 门面统一访问）
+        await withService(options, context, async (service) => {
             const root = options.package ? resolvePackageRoot(options.package) : findProjectRoot();
-            if (options.global) {
-                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,
-                    humanFormatter: () => renderConfigList(filterRes.items, "Global Scope", filterRes.isFallback, effectiveIntent),
-                    context,
-                });
-                return;
-            }
-            if (!root) {
-                if (options.package) {
+            // 全局作用域分支：显式 --global 或无工程回退时仅列举全局配置
+            if (options.global || !root) {
+                if (!options.global && options.package) {
                     throw packageNotFoundError(options.package);
                 }
-                const all = await localTarget.listConfig("global");
+                const all = (await service.management?.config.list("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,
-                    humanFormatter: () => renderConfigList(filterRes.items, "Global Scope (No project found)", filterRes.isFallback, effectiveIntent),
+                    humanFormatter: () => renderConfigList(filterRes.items, options.global ? "Global Scope" : "Global Scope (No project found)", filterRes.isFallback, effectiveIntent),
                     context,
                 });
                 return;
             }
             const projConfig = loadProjectConfig(root);
             // 跨作用域合并视图单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
-            const merged = await buildMergedConfigEntries(root, localTarget, reveal);
+            const merged = await buildMergedConfigEntries(root, service, 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,

package/dist/commands/config/schema.d.ts

@@ -3,7 +3,13 @@ import type { CliContext } from "../../types.js";
 /**
  * 注册 config schema 子命令：检查声明配置的解析状态。
  *
+ * 状态推导复用 config-merge 的跨作用域合并视图单一事实源
+ * （项目包级 > 全局持久化 > 环境变量 > 声明默认值）：
+ * - source 命中 project、global 或 env 时状态为 SET；
+ * - source 为 default（仅声明默认值兜底）时状态为 DEFAULT；
+ * - 键无任何来源（不在合并视图中，即未声明默认值也未持久化）时状态为 MISSING。
+ *
  * @param configCmd config 命令实例
- * @param context 命令行上下文
+ * @param context CLI 上下文
  */
 export declare function registerConfigSchemaCommand(configCmd: Command, context?: CliContext): void;

package/dist/commands/config/schema.js

@@ -1,80 +1,63 @@
-import { createActionDockTarget, isSecretConfigKey, loadProjectConfig, resolveEnvValue, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError } from "../../errors.js";
+import { isSecretConfigKey, } from "@actiondock/core/project";
+import { notInProjectError } from "../../errors.js";
 import { renderConfigSchema, renderResult, writeStdout } from "../../renderer.js";
-import { getEffectiveOptions } from "../../utils/index.js";
+import { buildMergedConfigEntries } from "../../services/config-merge.js";
+import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, withService } from "../../utils/index.js";
 /**
  * 注册 config schema 子命令：检查声明配置的解析状态。
  *
+ * 状态推导复用 config-merge 的跨作用域合并视图单一事实源
+ * （项目包级 > 全局持久化 > 环境变量 > 声明默认值）：
+ * - source 命中 project、global 或 env 时状态为 SET；
+ * - source 为 default（仅声明默认值兜底）时状态为 DEFAULT；
+ * - 键无任何来源（不在合并视图中，即未声明默认值也未持久化）时状态为 MISSING。
+ *
  * @param configCmd config 命令实例
- * @param context 命令行上下文
+ * @param context CLI 上下文
  */
 export function registerConfigSchemaCommand(configCmd, context) {
-    configCmd
+    applyTargetOptions(configCmd
         .command("schema [identifier]")
         .alias("check")
         .description("Inspect declared configuration requirements and check resolution status")
-        .option("-P, --package <id>", "Target package ID or path")
+        .option("-P, --package <id>", "Target package ID or path"))
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
         .action(async (identifier, rawOptions, cmd) => {
-        try {
-            const options = getEffectiveOptions(rawOptions, cmd);
-            const targetPkg = identifier || options.package;
-            const root = resolvePackageRoot(targetPkg);
-            if (!root) {
-                if (targetPkg) {
-                    throw packageNotFoundError(targetPkg);
-                }
-                throw notInProjectError("Usage: ad config schema [package-id] or cd into a project directory.");
-            }
-            const projConfig = loadProjectConfig(root);
-            const declared = projConfig.config || {};
-            const declaredKeys = Object.keys(declared);
-            const target = await createActionDockTarget({
-                type: "local",
-                projectRoot: root,
-                customHome: context?.customHome,
-                dataDir: options.dataDir || context?.dataDir,
-            });
-            let globalConfig = [];
-            let projectConfig = [];
-            try {
-                globalConfig = await target.listConfig("global");
-                projectConfig = await target.listConfig(projConfig.id);
-            }
-            finally {
-                await target.close();
-            }
-            const projectConfigMap = new Map(projectConfig.map((c) => [c.key, c]));
-            const globalConfigMap = new Map(globalConfig.map((c) => [c.key, c]));
-            const items = declaredKeys.map((key) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const targetPkg = identifier || options.package;
+        const { root, projConfig } = requirePackageRoot(targetPkg, {
+            loadConfig: true,
+            hint: "Usage: ad config schema [package-id] or cd into a project directory.",
+        });
+        const declared = projConfig.config || {};
+        // 远端目标显式拒绝：schema 状态推导依赖本地工程声明与环境变量解析，
+        // 远端作用域无法获得等价视图，静默落到本地会误导调用方
+        if (options.profile || options.server) {
+            throw notInProjectError("'ad config schema' only supports local projects. Remote targets are not supported for schema inspection.");
+        }
+        // 跨作用域合并视图单一事实源：与 config list 共享同一条优先级链
+        await withService(options, context, async (service) => {
+            const merged = await buildMergedConfigEntries(root, service, true);
+            const mergedByKey = new Map(merged.map((entry) => [entry.key, entry]));
+            const items = Object.keys(declared).map((key) => {
                 const itemDef = declared[key];
                 const isSecret = isSecretConfigKey(key, itemDef);
-                let resolvedValue;
+                const mergedEntry = mergedByKey.get(key);
                 let source = "missing";
                 let status = "MISSING";
-                const envResolved = resolveEnvValue(key, itemDef, projConfig.id);
-                const projItem = projectConfigMap.get(key);
-                const globItem = globalConfigMap.get(key);
-                if (projItem && projItem.configured && projItem.source === "package") {
-                    resolvedValue = projItem.value;
-                    source = "project";
-                    status = "SET";
-                }
-                else if (globItem && globItem.configured) {
-                    resolvedValue = globItem.value;
-                    source = "global";
-                    status = "SET";
-                }
-                else if (envResolved !== undefined) {
-                    resolvedValue = envResolved.value;
-                    source = "env";
-                    status = "SET";
-                }
-                else if (itemDef.default !== undefined) {
-                    resolvedValue = itemDef.default;
-                    source = "default";
-                    status = "DEFAULT";
+                let resolvedValue;
+                if (mergedEntry) {
+                    source = mergedEntry.source;
+                    resolvedValue = mergedEntry.value;
+                    // 合并视图的 default 来源仅是链尾兑底标签：
+                    // 真正的 DEFAULT 状态要求声明确实携带默认值，否则视为 MISSING
+                    if (mergedEntry.source !== "default") {
+                        status = "SET";
+                    }
+                    else if (itemDef.default !== undefined) {
+                        status = "DEFAULT";
+                    }
                 }
                 return {
                     key,
@@ -108,12 +91,6 @@ export function registerConfigSchemaCommand(configCmd, context) {
             if (!ok) {
                 process.exitCode = 1;
             }
-        }
-        catch (err) {
-            if (err instanceof ArgumentError || err instanceof ExecutionError) {
-                throw err;
-            }
-            throw new ExecutionError(err.message);
-        }
+        }, { localRoot: root });
     });
 }