@actiondock/cli 2.12.0 → 2.14.0

package/README.md

@@ -59,6 +59,10 @@ ad run sample.greet -- name=Alice count:=1
 # 复杂参数或对象从文件读取（与扁平参数互斥）
 ad run sample.greet --input-file input.json
 
+# 原始文本管道绑定（假定已注册 summarize 动作且 text 是字符串入参）
+# 可与扁平赋值组合，与 --input / --input-file 互斥
+printf '这是一段正文' | ad run summarize --stdin-field text -- style=brief
+
 # 自动化与脚本通过标准输入传递
 cat input.json | ad run sample.greet --input-file -
 ```
@@ -126,11 +130,12 @@ ad pack
   - 路径冲突（叶节点与容器冲突、对象与数组冲突、重复赋值）严格拒绝（`INPUT_PATH_CONFLICT`）。
   - 拦截原型污染敏感属性（`__proto__`、`constructor`、`prototype`）。
 - 三种输入模式互斥：扁平参数、`--input` 与 `--input-file` 严格互斥，不可混用（`INPUT_CONFLICT`）；未指定输入时默认为 `{}`。
+- 原始文本管道绑定：`printf '正文' | ad run <action> --stdin-field <field> [-- <assignments...>]` 将 stdin 完整正文原样绑定为指定顶层字段的字符串值（不解析类型、不剥 BOM、不修剪空白、空输入为空字符串）；可与扁平赋值组合，与 `--input` / `--input-file` 互斥；stdin 源字节与绑定后的最终入参序列化大小各自受默认 10MiB 上限约束，分别超限报 `INPUT_LIMIT_EXCEEDED` 与 `FLAT_INPUT_LIMIT_EXCEEDED`，JSON 转义放大也计入最终大小；严格 UTF-8 校验失败报读取错误。管道非事务，高风险写入先完整生成并校验再执行。
 - 传统输入选项：
   - 简单内联参数：使用 `--input <json>` 直接解析 JSON 字符串。
   - 复杂对象文件：使用 `--input-file <path>` 读取文件并解析 JSON，避免各类终端的引号转义损坏。
   - 标准输入管道：使用 `--input-file -` 从标准输入读取全部数据并解析 JSON。
-  - 统一解析：解析前均自动剔除 UTF-8 BOM 标记，且不设人为大小上限。
+  - 统一解析：JSON 输入在解析前剔除 UTF-8 BOM，默认大小上限为 10MiB；改用文件不会解除限制。原始文本绑定保留正文 BOM。
 
 ### Windows 与多终端传参建议
 
@@ -156,7 +161,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 - **显式正文输出与默认注解**：
   - 显式指定正文字段：通过 `ad run <id> --text-field <field> -- ...` 提取结果中特定顶层自有字符串字段输出至 stdout（保留真实换行且无 JSON 转义），其余字段以 JSON 对象形式输出至 stderr（元数据为空时不输出）。
   - 声明式默认正文：Action 清单中声明 `annotations["actiondock.cli"] = { "textField": "<field>" }` 时，未指定 `--text-field` 时自动按声明提取正文与元数据；显式 `--text-field` 优先于默认注解。
-  - 严格校验：正文字段缺失、非字符串或返回数据非对象时，明确输出错误并以退出码 1 退出，不静默回退，不改写运行记录。
+  - 严格校验与契约闭环：正文字段缺失、非字符串或返回数据非对象时，明确输出错误并以退出码 1 退出，不静默回退，不改写运行记录。契约通过 `ad describe` 呈现通道语义与覆盖指引，并通过 `ad validate` 进行纯静态元数据合规校验。
   - 参数互斥：`--text-field` 与 `--json`、`--async` 严格互斥，在执行前校验并以退出码 2 退出。
 - **机器模式**（`--json`）：当需要以程序化方式消费、获取完整结构化数据或被外部系统集成时，传入 `--json`。此时始终输出完整执行信封（包含 `ok`、`runId`、`data` 或 `error`），忽略默认正文注解；若参数解析出错输出标准错误信封并以退出码 2 退出。
 
@@ -171,9 +176,9 @@ $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 的详情、模式字段明细、Flat 编码指引与建议赋值 |
-| `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--text-field` 提取正文与 `--json` 输出标准信封） |
-| `ad validate [id]` | 校验 Action 规范与模式规范 |
+| `ad describe <id>` | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引、建议赋值与输出选择契约 |
+| `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--stdin-field` 绑定原始文本、`--text-field` 提取正文与 `--json` 输出标准信封） |
+| `ad validate [id]` | 校验 Action 规范、模式规范与输出选择契约 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
 | `ad action create <id>` | 创建新 Action 源码 |
 | `ad playbook list` / `show` | 查看智能体操作规程 Playbook |

package/bin/ad.js

@@ -3,19 +3,6 @@ import { enableCompileCache } from "node:module";
 try {
   enableCompileCache?.();
 } catch {}
-try {
-  await import("@actiondock/core/warning");
-} catch {
-  try {
-    const { resolve } = await import("node:path");
-    const { existsSync } = await import("node:fs");
-    const { pathToFileURL } = await import("node:url");
-    const coreWarningSrc = resolve(import.meta.dirname, "../../core/src/utils/warning.ts");
-    if (existsSync(coreWarningSrc)) {
-      await import(pathToFileURL(coreWarningSrc).href);
-    }
-  } catch {}
-}
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
@@ -238,9 +225,6 @@ if (needsTsx) {
 
   if (tsxSpecifier) {
     const extraFlags = [];
-    if (process.env.ACTIONDOCK_SILENCE_WARNINGS !== "0") {
-      extraFlags.push("--no-warnings=ExperimentalWarning");
-    }
     if (nodeMajor >= 24) {
       extraFlags.push("--no-strip-types");
     }

package/dist/commands/config/delete.js

@@ -1,8 +1,6 @@
-import { loadProjectConfig, } from "@actiondock/core";
-import { resolvePackageRoot, } from "@actiondock/core/registry";
-import { ArgumentError, packageNotFoundError } from "../../errors.js";
+import { ArgumentError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, withService } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetPackageScope, withService, } from "../../utils/index.js";
 /**
  * 注册 config delete 子命令：删除配置项。
  *
@@ -22,31 +20,22 @@ export function registerConfigDeleteCommand(configCmd, context) {
         if (!key) {
             throw new ArgumentError("Configuration key is required");
         }
-        const root = resolvePackageRoot(options.package);
+        const scope = resolveTargetPackageScope(options, context);
         await withService(options, context, async (service, resolved) => {
             if (resolved.type === "remote") {
-                await service.management?.config.delete(options.package || "", key);
+                await service.management?.config.delete(scope.packageId, key);
                 writeStdout(`[OK] Configuration '${key}' deleted from remote server`, context);
                 return;
             }
-            if (options.global) {
+            if (options.global || (!scope.root && !options.package)) {
                 await service.management?.config.delete("global", key);
                 writeStdout(`[OK] Global configuration '${key}' deleted`, context);
                 return;
             }
-            if (!root) {
-                if (options.package) {
-                    throw packageNotFoundError(options.package);
-                }
-                await service.management?.config.delete("global", key);
-                writeStdout(`[OK] Global configuration '${key}' deleted`, context);
-                return;
-            }
-            const projConfig = loadProjectConfig(root);
-            await service.management?.config.delete(projConfig.id, key);
-            writeStdout(`[OK] Configuration '${key}' deleted for package '${projConfig.id}'`, context);
+            await service.management?.config.delete(scope.packageId, key);
+            writeStdout(`[OK] Configuration '${key}' deleted for package '${scope.packageId}'`, context);
         }, 
         // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
-        { localRoot: root || undefined });
+        { localRoot: scope.root });
     });
 }

package/dist/commands/config/env.js

@@ -2,7 +2,7 @@ import { resolveEnvValue } from "@actiondock/core";
 import { fetchRemoteConfigEnv } from "@actiondock/core/profile";
 import { isSecretConfigKey, } from "@actiondock/core/project";
 import { renderConfigEnv, renderResult } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, resolveTargetFromOptions } from "../../utils/index.js";
+import { applyTargetOptions, assertNotCompositeSkill, getEffectiveOptions, requirePackageRoot, resolveTargetFromOptions, } from "../../utils/index.js";
 /**
  * 注册 config env 子命令：诊断环境变量对声明配置的满足率。
  *
@@ -18,7 +18,7 @@ export function registerConfigEnvCommand(configCmd, context) {
         .action(async (identifier, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const targetPkg = identifier || options.package;
-        // 远端服务分支直接查询远端配置环境诊断接口
+        // 1. 目标拓扑解析（远端服务分支完全隔离本地文件系统）
         const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
             const res = await fetchRemoteConfigEnv(target.serverUrl, target.token, targetPkg, {
@@ -37,6 +37,7 @@ export function registerConfigEnvCommand(configCmd, context) {
             return;
         }
         // 本地项目分支
+        assertNotCompositeSkill(targetPkg);
         const { root, projConfig } = requirePackageRoot(targetPkg, {
             loadConfig: true,
             hint: "Usage: ad config env [package-id] or cd into a project directory.",

package/dist/commands/config/get.js

@@ -1,11 +1,10 @@
 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 { ArgumentError } from "../../errors.js";
 import { renderResult } from "../../renderer.js";
 import { resolveMergedConfigEntry } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, resolveTargetFromOptions, withService, } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetPackageScope, withService, } from "../../utils/index.js";
 /**
  * 注册 config get 子命令：查询指定配置键的生效值。
  *
@@ -27,12 +26,11 @@ export function registerConfigGetCommand(configCmd, context) {
             throw new ArgumentError("Configuration key is required");
         }
         const reveal = Boolean(options.reveal || options.showSecrets);
-        // 远端服务分支不经过 Target 门面，直接查询远端配置接口
-        const target = resolveTargetFromOptions(options, context);
-        if (target.type === "remote") {
-            const res = await fetchRemoteConfig(target.serverUrl, target.token, options.package, {
+        const scope = resolveTargetPackageScope(options, context);
+        if (scope.isRemote) {
+            const res = await fetchRemoteConfig(scope.resolved.serverUrl, scope.resolved.token, scope.packageId, {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
-                insecure: target.insecure,
+                insecure: scope.resolved.insecure,
             });
             const val = res.values?.[key];
             const isSecret = isSecretConfigKey(key, res.declared?.[key]);
@@ -50,13 +48,8 @@ export function registerConfigGetCommand(configCmd, context) {
             });
             return;
         }
-        // 本地分支
-        const root = resolvePackageRoot(options.package);
         await withService(options, context, async (service) => {
-            if (options.global || !root) {
-                if (!options.global && options.package && !root) {
-                    throw packageNotFoundError(options.package);
-                }
+            if (options.global || !scope.root) {
                 const confView = await service.management?.config.get("global", key);
                 const val = confView?.value;
                 const isSecret = confView?.secret ?? isSecretConfigKey(key);
@@ -74,10 +67,10 @@ export function registerConfigGetCommand(configCmd, context) {
                 });
                 return;
             }
-            const projConfig = loadProjectConfig(root);
+            const projConfig = scope.projConfig || loadProjectConfig(scope.root);
             const declaredItem = projConfig.config?.[key];
             // 合并优先级链单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
-            const { value: displayValue, source, secret: isSecret } = await resolveMergedConfigEntry(key, projConfig.id, declaredItem, service, reveal);
+            const { value: displayValue, source, secret: isSecret } = await resolveMergedConfigEntry(key, scope.packageId, declaredItem, service, reveal);
             const payload = {
                 key,
                 value: displayValue,
@@ -91,6 +84,6 @@ export function registerConfigGetCommand(configCmd, context) {
             });
         }, 
         // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
-        { localRoot: root || undefined });
+        { localRoot: scope.root });
     });
 }

package/dist/commands/config/list.js

@@ -1,10 +1,9 @@
 import { fetchRemoteConfig, } from "@actiondock/core/profile";
 import { loadProjectConfig, } from "@actiondock/core";
 import { filterWithFallbackInfo, isSecretConfigKey, maskSecretValue, } from "@actiondock/core/project";
-import { packageNotFoundError } from "../../errors.js";
 import { renderConfigList, renderResult } from "../../renderer.js";
 import { buildMergedConfigEntries } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, resolveTargetFromOptions, withService, } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveTargetPackageScope, withService, } from "../../utils/index.js";
 /**
  * 构造单条配置项的展示视图（含掩码决策，reveal 为假且为敏感键时打码）。
  * 掩码决策收敛于命令层，renderer 仅负责值的字符串格式化。
@@ -42,29 +41,24 @@ export function registerConfigListCommand(configCmd, context) {
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const { shouldFallback } = resolveFallbackStrategy(options);
         const reveal = Boolean(options.reveal || options.showSecrets);
-        // 远端服务分支不经过 Target 门面，直接查询远端配置接口
-        const remoteTargetInfo = resolveTargetFromOptions(options, context);
-        if (remoteTargetInfo.type === "remote") {
-            const res = await fetchRemoteConfig(remoteTargetInfo.serverUrl, remoteTargetInfo.token, options.package, {
+        const scope = resolveTargetPackageScope(options, context);
+        if (scope.isRemote) {
+            const res = await fetchRemoteConfig(scope.resolved.serverUrl, scope.resolved.token, scope.packageId, {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
-                insecure: remoteTargetInfo.insecure,
+                insecure: scope.resolved.insecure,
             });
             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, remoteTargetLabel(remoteTargetInfo), false, effectiveIntent),
+                humanFormatter: () => renderConfigList(entries, remoteTargetLabel(scope.resolved), false, effectiveIntent),
                 context,
             });
             return;
         }
         // 本地分支（通过 Service 门面统一访问）：显式包寻址结果作为本地根目录传递（仅 local 分支求值）
         await withService(options, context, async (service) => {
-            const root = resolveLocalPackageRoot(options.package) || undefined;
             // 全局作用域分支：显式 --global 或无工程回退时仅列举全局配置
-            if (options.global || !root) {
-                if (!options.global && options.package) {
-                    throw packageNotFoundError(options.package);
-                }
+            if (options.global || !scope.root) {
                 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);
@@ -75,9 +69,9 @@ export function registerConfigListCommand(configCmd, context) {
                 });
                 return;
             }
-            const projConfig = loadProjectConfig(root);
+            const projConfig = scope.projConfig || loadProjectConfig(scope.root);
             // 跨作用域合并视图单一事实源：项目包级 > 全局持久化 > 环境变量 > 声明默认值
-            const merged = await buildMergedConfigEntries(root, service, reveal);
+            const merged = await buildMergedConfigEntries(scope.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,
@@ -85,7 +79,7 @@ export function registerConfigListCommand(configCmd, context) {
                 context,
             });
         }, {
-            localRoot: () => resolveLocalPackageRoot(options.package) || undefined,
+            localRoot: scope.root,
         });
     });
 }

package/dist/commands/config/schema.js

@@ -2,7 +2,7 @@ import { isSecretConfigKey, } from "@actiondock/core/project";
 import { notInProjectError } from "../../errors.js";
 import { renderConfigSchema, renderResult } from "../../renderer.js";
 import { buildMergedConfigEntries } from "../../services/config-merge.js";
-import { applyTargetOptions, getEffectiveOptions, requirePackageRoot, withService } from "../../utils/index.js";
+import { applyTargetOptions, assertNotCompositeSkill, getEffectiveOptions, requirePackageRoot, withService, } from "../../utils/index.js";
 /**
  * 注册 config schema 子命令：检查声明配置的解析状态。
  *
@@ -25,17 +25,18 @@ export function registerConfigSchemaCommand(configCmd, context) {
         .option("--json", "Output as JSON")
         .action(async (identifier, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
+        // 远端目标显式拒绝：schema 状态推导依赖本地工程声明与环境变量解析，
+        // 远端作用域无法获得等价视图，静默落到本地会误导调用方
+        if (options.profile || options.server) {
+            throw notInProjectError("'ad config schema' only supports local projects. Remote targets are not supported for schema inspection.");
+        }
         const targetPkg = identifier || options.package;
+        assertNotCompositeSkill(targetPkg);
         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);

package/dist/commands/config/set.js

@@ -1,9 +1,7 @@
 import { isSecretConfigKey, } from "@actiondock/core/project";
-import { loadProjectConfig, } from "@actiondock/core";
-import { resolvePackageRoot, } from "@actiondock/core/registry";
-import { ArgumentError, packageNotFoundError } from "../../errors.js";
+import { ArgumentError } from "../../errors.js";
 import { writeStdout } from "../../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, withService } from "../../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveTargetPackageScope, withService, } from "../../utils/index.js";
 import { resolveConfigValueInput } from "../../prompt.js";
 /**
  * 注册 config set 子命令：写入配置值（支持标准输入与安全提示）。
@@ -24,22 +22,8 @@ export function registerConfigSetCommand(configCmd, context) {
         if (!key) {
             throw new ArgumentError("Configuration key is required");
         }
-        let root = null;
-        let projConfig = null;
-        let declaredDef;
-        if (!options.global && !options.profile && !options.server) {
-            root = resolvePackageRoot(options.package);
-            if (root) {
-                try {
-                    projConfig = loadProjectConfig(root);
-                    declaredDef = projConfig.config?.[key];
-                }
-                catch (err) {
-                    // 清单损坏时必须让错误可见：静默忽略会导致写入错误的作用域
-                    throw err;
-                }
-            }
-        }
+        const scope = resolveTargetPackageScope(options, context);
+        const declaredDef = scope.projConfig?.config?.[key];
         const isSecret = isSecretConfigKey(key, declaredDef);
         let effectiveValueStr = rawVal;
         if (effectiveValueStr === undefined || options.stdin) {
@@ -60,27 +44,21 @@ export function registerConfigSetCommand(configCmd, context) {
         // 目标解析与写入（远端分支直接写远端作用域，本地分支按全局/项目作用域写入）
         await withService(options, context, async (service, resolved) => {
             if (resolved.type === "remote") {
-                await service.management?.config.set(options.package || "", key, parsedVal);
+                await service.management?.config.set(scope.packageId, key, parsedVal);
                 writeStdout(`[OK] Configuration '${key}' updated on remote server`, context);
                 return;
             }
-            if (options.global) {
-                await service.management?.config.set("global", key, parsedVal);
-                writeStdout(`[OK] Global configuration '${key}' updated`, context);
-                return;
-            }
-            if (!root) {
-                if (options.package) {
-                    throw packageNotFoundError(options.package);
-                }
+            if (options.global || (!scope.root && !options.package)) {
                 await service.management?.config.set("global", key, parsedVal);
-                writeStdout(`[OK] Global configuration '${key}' updated (no project in current directory)`, context);
+                writeStdout(!scope.root && !options.package
+                    ? `[OK] Global configuration '${key}' updated (no project in current directory)`
+                    : `[OK] Global configuration '${key}' updated`, context);
                 return;
             }
-            await service.management?.config.set(projConfig.id, key, parsedVal);
-            writeStdout(`[OK] Configuration '${key}' updated for package '${projConfig.id}'`, context);
+            await service.management?.config.set(scope.packageId, key, parsedVal);
+            writeStdout(`[OK] Configuration '${key}' updated for package '${scope.packageId}'`, context);
         }, 
         // 按实际查询范围打开存储：显式包寻址结果作为本地根目录传递
-        { localRoot: root || undefined });
+        { localRoot: scope.root });
     });
 }

package/dist/commands/describe.js

@@ -1,8 +1,8 @@
 import { ACTION_NOT_FOUND, PACKAGE_NOT_FOUND, NOT_FOUND, } from "@actiondock/core";
 import { buildActionDescribePayload, } from "@actiondock/core/project";
-import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
+import { ArgumentError, ExecutionError } from "../errors.js";
 import { formatActionDetail, renderResult } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withService, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveCommandTarget, withService, } from "../utils/index.js";
 /**
  * 挂载 describe 子命令至指定 Commander 节点。
  *
@@ -22,12 +22,9 @@ export function attachDescribeCommand(parent, context) {
         if (!id) {
             throw new ArgumentError("Action ID is required for describe");
         }
-        // 目标拓扑解析（仅 local 分支需要包寻址）
-        const targetPackageRoot = resolveLocalPackageRoot(options.package);
-        if (options.package && !targetPackageRoot) {
-            throw packageNotFoundError(options.package);
-        }
-        const targetRef = id;
+        // 目标拓扑与动作引用解析（远端目标完全隔离本地文件系统）
+        const target = resolveCommandTarget(options, context);
+        const targetRef = target.resolveActionRef(id);
         // 通过 Service 门面统一查询 Action 规范
         await withService(options, context, async (service) => {
             let spec;
@@ -50,7 +47,7 @@ export function attachDescribeCommand(parent, context) {
                 humanFormatter: () => formatActionDetail(payload),
                 context,
             });
-        }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });
+        }, { localRoot: target.targetPackageRoot, scanLinkedPackages: !target.localSkill });
     });
 }
 /**

package/dist/commands/list.js

@@ -1,7 +1,6 @@
 import { filterWithFallbackInfo, } from "@actiondock/core/project";
-import { packageNotFoundError } from "../errors.js";
 import { renderActionList, renderResult } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, withService, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, resolveCommandTarget, resolveFallbackStrategy, resolveIntent, withService, } from "../utils/index.js";
 /**
  * 挂载 list 子命令至指定 Commander 节点。
  *
@@ -23,22 +22,20 @@ export function attachListCommand(parent, context) {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const { isMachine, shouldFallback } = resolveFallbackStrategy(options);
-        // 目标拓扑解析（仅 local 分支需要包寻址）
-        const targetPackageRoot = resolveLocalPackageRoot(options.package);
-        if (options.package && !targetPackageRoot) {
-            throw packageNotFoundError(options.package);
-        }
+        // 目标拓扑与动作引用解析（远端目标完全隔离本地文件系统）
+        const target = resolveCommandTarget(options, context);
         // 通过 Service 门面统一获取 Action 列表
         await withService(options, context, async (service, resolved) => {
             let rawSummaries = await service.discovery.listActions();
-            // 若指定了目标包但本地未过滤，则按包归属精确过滤：
+            // 若指定了包 ID（非本地技能目录），则按包归属精确过滤（本地与远端统一生效）：
             // 仅保留全限定名命中目标包前缀、或 packageId 归属目标包的条目；
             // 无法归属到目标包的无前缀短 id 条目不放行，避免他包短 id 混入
-            if (options.package && !options.profile && !options.server) {
+            if (options.package && !target.localSkill) {
                 const targetPkg = options.package;
                 rawSummaries = rawSummaries.filter((s) => {
-                    if (s.packageId) {
-                        return (s.packageId === targetPkg ||
+                    const pkgId = s.packageId;
+                    if (pkgId) {
+                        return (pkgId === targetPkg ||
                             s.id === targetPkg ||
                             s.id.startsWith(`${targetPkg}/`));
                     }
@@ -46,14 +43,17 @@ export function attachListCommand(parent, context) {
                     return s.id === targetPkg || s.id.startsWith(`${targetPkg}/`);
                 });
             }
+            const isCompositeSkill = target.localSkill?.type === "composite";
             const rawList = rawSummaries.map((s) => {
                 let id = s.id;
-                if (targetPackageRoot || options.package) {
-                    const pkgId = s.packageId || options.package;
+                // 复合技能保持完全限定 ID，不剥离包名前缀
+                if (!isCompositeSkill && (target.targetPackageRoot || options.package)) {
+                    const targetPkg = target.localSkill ? target.localSkill.packages[0].packageId : options.package;
+                    const pkgId = targetPkg || s.packageId;
                     if (pkgId && id.startsWith(`${pkgId}/`)) {
                         id = id.slice(pkgId.length + 1);
                     }
-                    else if (targetPackageRoot && id.includes("/")) {
+                    else if (target.targetPackageRoot && id.includes("/")) {
                         id = id.slice(id.indexOf("/") + 1);
                     }
                 }
@@ -80,7 +80,7 @@ export function attachListCommand(parent, context) {
             }
             const title = resolved.type === "remote"
                 ? `Actions ${remoteTargetSuffix(resolved)}`
-                : targetPackageRoot
+                : target.targetPackageRoot
                     ? `Actions in ${options.package || "current project"}`
                     : "Available Actions";
             renderResult(filterRes.items, {
@@ -88,7 +88,7 @@ export function attachListCommand(parent, context) {
                 humanFormatter: () => renderActionList(filterRes.items, title, filterRes.isFallback, effectiveIntent),
                 context,
             });
-        }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });
+        }, { localRoot: target.targetPackageRoot, scanLinkedPackages: !target.localSkill });
     });
 }
 /**

package/dist/commands/run.js

@@ -1,9 +1,8 @@
 import { validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core/project";
-import { resolveTarget, } from "@actiondock/core/profile";
 import { ACTION_NOT_FOUND, NOT_FOUND, resolveExecutionHint, } from "@actiondock/core";
-import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
+import { ArgumentError, ExecutionError, SigintError } from "../errors.js";
 import { extractTextFieldPayload, resolveActionDefaultTextField, writeStderr, writeStdout, } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, resolveTimeoutMs, withService, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveCommandTarget, resolveTimeoutMs, withService, } from "../utils/index.js";
 /**
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
@@ -78,6 +77,13 @@ export async function executeAction(id, options, context, flatArgs, control) {
             throw new ArgumentError("Cannot specify both --text-field and --async.");
         }
     }
+    // --stdin-field 与 --text-field 分属输入绑定与输出选择，可同时使用；
+    // 与完整 JSON 输入来源的互斥由共享 resolver 统一裁决（INPUT_CONFLICT）
+    if (options.stdinField !== undefined) {
+        if (typeof options.stdinField !== "string") {
+            throw new ArgumentError("The --stdin-field option requires a field name.");
+        }
+    }
     const effectiveControl = control ?? context?.control;
     const effectiveSignal = effectiveControl?.signal;
     const effectiveFlatArgs = flatArgs ?? options.flatArgs;
@@ -85,7 +91,9 @@ export async function executeAction(id, options, context, flatArgs, control) {
         input: options.input,
         inputFile: options.inputFile,
         flatArgs: effectiveFlatArgs && effectiveFlatArgs.length > 0 ? effectiveFlatArgs : undefined,
+        stdinField: options.stdinField,
         stdin: context?.stdin,
+        signal: effectiveSignal,
     });
     const check = validateActionInputValue(input);
     if (!check.valid) {
@@ -102,25 +110,13 @@ export async function executeAction(id, options, context, flatArgs, control) {
         }
     }
     try {
+        // 目标拓扑与动作引用解析（远端目标完全隔离本地文件系统）
+        const target = resolveCommandTarget(options, context);
         // 异步执行仅支持远端目标，本地模式直接拒绝
-        const resolvedTopology = resolveTarget({
-            profile: options.profile,
-            server: options.server,
-            token: options.token,
-            insecure: options.insecure,
-        }, context?.customHome);
-        if (resolvedTopology.type === "local" && options.async) {
+        if (!target.isRemote && options.async) {
             throw new ExecutionError("Async execution requires a long-running ActionDock server.\nUse --profile, --server, or start 'ad serve'.");
         }
-        // 目标拓扑解析（仅 local 分支需要包寻址）
-        const targetPackageRoot = resolveLocalPackageRoot(options.package);
-        if (options.package && !targetPackageRoot) {
-            throw packageNotFoundError(options.package);
-        }
-        let targetRef = id;
-        if (options.package && !id.includes("/")) {
-            targetRef = `${options.package}/${id}`;
-        }
+        const targetRef = target.resolveActionRef(id);
         // 通过 Service 统一执行
         await withService(options, context, async (service) => {
             const isMachine = Boolean(options.json);
@@ -196,7 +192,7 @@ export async function executeAction(id, options, context, flatArgs, control) {
                     return;
                 }
             }
-        }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true, ownDataDir: true });
+        }, { localRoot: target.targetPackageRoot || undefined, scanLinkedPackages: !target.localSkill, ownDataDir: true });
     }
     catch (err) {
         // sigint 取消源、中断链路特征错误码或 SigintError 本身，均统一归并为 SigintError
@@ -242,6 +238,11 @@ Flat Input Syntax & Examples:
     # Extract specific text field to stdout (remaining fields as JSON to stderr)
     ad run <id> --text-field content -- path="README.md"
 
+  Raw Text Input from stdin:
+    # Bind entire stdin content as a string to the given input field
+    printf 'body text' | ad run <id> --stdin-field text -- style=brief
+    cat report.md | ad run <id> --stdin-field content
+
   Complex or multiline inputs:
     # Pass via JSON file with --input-file to avoid shell escaping issues
     ad run <id> --input-file input.json`;
@@ -258,7 +259,8 @@ export function attachRunCommand(parent, context) {
         .option("-P, --package <id>", "Target package ID or path")
         .option("-i, --input <json>", "Action input as inline JSON")
         .option("-f, --input-file <path>", "Action input from JSON file, or '-' for stdin")
-        .option("-c, --config <key=value...>", "Temporary config override (repeatable)");
+        .option("-c, --config <key=value...>", "Temporary config override (repeatable)")
+        .option("--stdin-field <field>", "Bind raw stdin text to a top-level action input field");
     cmd.unknownOption = function (flag) {
         this.error(`unknown option '${flag}'\nHint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>.`, { code: "commander.unknownOption" });
     };