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

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

package/dist/commands/action/create.js

@@ -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";
@@ -202,31 +203,14 @@ ${returnBody}
         saveManifest(root, manifest);
         // 始终自动生成或更新类型声明文件，确保单一事实源即时生效
         writeActionTypes(root, manifest);
-        let sampleInputStr = "{}";
-        const inputEntries = Object.entries(inputSchema.properties || {});
-        if (inputEntries.length > 0) {
-            const sampleObj = {};
-            for (const [k, prop] of inputEntries) {
-                if (prop.type === "number" || prop.type === "integer")
-                    sampleObj[k] = 42;
-                else if (prop.type === "boolean")
-                    sampleObj[k] = true;
-                else if (prop.type === "array")
-                    sampleObj[k] = ["item"];
-                else if (prop.type === "object")
-                    sampleObj[k] = {};
-                else
-                    sampleObj[k] = "hello";
-            }
-            sampleInputStr = JSON.stringify(sampleObj);
-        }
         writeStdout(`[OK] Created Action '${id}' at ${targetFullFile}`, context);
-        writeStdout(`\nTo run this action:`, context);
-        writeStdout(`  ad run ${id} --input '${sampleInputStr}'`, context);
+        writeStdout(`\n查阅参数契约:`, context);
+        writeStdout(`  ad describe ${id}`, context);
+        writeStdout(`\n调用方式:`, context);
+        writeStdout(`  根据 describe 输出的赋值模板传递参数：ad run ${id} --json -- ASSIGNMENT...`, context);
+        writeStdout(`  复杂输入或大段文本：ad run ${id} --json --input-file input.json`, context);
     }
     catch (err) {
-        if (err instanceof ExecutionError)
-            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 });
     });
 }