@actiondock/cli 2.11.0 → 2.12.0

package/README.md

@@ -152,8 +152,13 @@ $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`）；若参数解析出错输出标准错误信封并以退出码 2 退出。
+- **默认纯文本输出**：`ad run` 默认采用纯文本模式。标量直接输出；结构化对象完整输出为标准 JSON 格式到 stdout；不进行私有业务字段自动嗅探。
+- **显式正文输出与默认注解**：
+  - 显式指定正文字段：通过 `ad run <id> --text-field <field> -- ...` 提取结果中特定顶层自有字符串字段输出至 stdout（保留真实换行且无 JSON 转义），其余字段以 JSON 对象形式输出至 stderr（元数据为空时不输出）。
+  - 声明式默认正文：Action 清单中声明 `annotations["actiondock.cli"] = { "textField": "<field>" }` 时，未指定 `--text-field` 时自动按声明提取正文与元数据；显式 `--text-field` 优先于默认注解。
+  - 严格校验：正文字段缺失、非字符串或返回数据非对象时，明确输出错误并以退出码 1 退出，不静默回退，不改写运行记录。
+  - 参数互斥：`--text-field` 与 `--json`、`--async` 严格互斥，在执行前校验并以退出码 2 退出。
+- **机器模式**（`--json`）：当需要以程序化方式消费、获取完整结构化数据或被外部系统集成时，传入 `--json`。此时始终输出完整执行信封（包含 `ok`、`runId`、`data` 或 `error`），忽略默认正文注解；若参数解析出错输出标准错误信封并以退出码 2 退出。
 
 ---
 
@@ -167,7 +172,7 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad info [patterns...]` | 检索包元数据与能力清单，支持模式匹配与树形展示 |
 | `ad list [patterns...]` | 列出包内所有已注册的 Action |
 | `ad describe <id>` | 编码顾问：查看 Action 的详情、模式字段明细、Flat 编码指引与建议赋值 |
-| `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--json` 输出标准信封） |
+| `ad run <id>` | 本地或远程执行指定 Action（规范语法 `ad run <id> [options] -- <assignments...>`，支持 `--text-field` 提取正文与 `--json` 输出标准信封） |
 | `ad validate [id]` | 校验 Action 规范与模式规范 |
 | `ad doctor` | 执行运行环境与项目结构健康诊断 |
 | `ad action create <id>` | 创建新 Action 源码 |

package/dist/commands/action/create.js

@@ -199,8 +199,9 @@ ${returnBody}
         writeStdout(`\nParameter contract:`, context);
         writeStdout(`  ad describe ${id}`, context);
         writeStdout(`\nUsage:`, context);
-        writeStdout(`  Pass parameters according to describe assignment template: ad run ${id} --json -- ASSIGNMENT...`, context);
-        writeStdout(`  Complex input or large text: ad run ${id} --json --input-file input.json`, context);
+        writeStdout(`  Pass parameters according to describe assignment template: ad run ${id} -- ASSIGNMENT...`, context);
+        writeStdout(`  Complex input or large text: ad run ${id} --input-file input.json`, context);
+        writeStdout(`  Append --json only when structured extraction is needed`, context);
     }
     catch (err) {
         throw wrapAsExecutionError(err);

package/dist/commands/run.d.ts

@@ -2,14 +2,18 @@ import { type InvocationControl } from "@actiondock/core/server";
 import type { ExecutionResult } from "@actiondock/sdk";
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+export interface RawExecutionRenderOptions {
+    textField?: string;
+}
 /**
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
  * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 显式或声明式正文输出：指定 textField 时仅输出该自有字符串字段至 stdout，剩余字段以 JSON 对象形式输出至 stderr。
  * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
-export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext): void;
+export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext, options?: RawExecutionRenderOptions): void;
 /**
  * 统一执行 Action 核心逻辑（使用 ActionDockService 服务端口）。
  *

package/dist/commands/run.js

@@ -1,18 +1,27 @@
 import { validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core/project";
 import { resolveTarget, } from "@actiondock/core/profile";
-import { resolveExecutionHint } from "@actiondock/core";
+import { ACTION_NOT_FOUND, NOT_FOUND, resolveExecutionHint, } from "@actiondock/core";
 import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
-import { writeStderr, writeStdout } from "../renderer.js";
+import { extractTextFieldPayload, resolveActionDefaultTextField, writeStderr, writeStdout, } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, resolveTimeoutMs, withService, } from "../utils/index.js";
 /**
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
  * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 显式或声明式正文输出：指定 textField 时仅输出该自有字符串字段至 stdout，剩余字段以 JSON 对象形式输出至 stderr。
  * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
-export function renderRawExecutionResult(targetRef, result, context) {
+export function renderRawExecutionResult(targetRef, result, context, options) {
     if (result.ok) {
+        if (options?.textField !== undefined) {
+            const { text, metadata } = extractTextFieldPayload(result.data, options.textField);
+            writeStdout(text, context);
+            if (metadata) {
+                writeStderr(JSON.stringify(metadata, null, 2), context);
+            }
+            return;
+        }
         const data = result.data;
         let rawText;
         if (typeof data === "string") {
@@ -58,6 +67,17 @@ export async function executeAction(id, options, context, flatArgs, control) {
     if (!id) {
         throw new ArgumentError("Action ID is required for run");
     }
+    if (options.textField !== undefined) {
+        if (typeof options.textField !== "string" || options.textField.trim() === "") {
+            throw new ArgumentError("The --text-field option requires a non-empty field name.");
+        }
+        if (options.json) {
+            throw new ArgumentError("Cannot specify both --text-field and --json.");
+        }
+        if (options.async) {
+            throw new ArgumentError("Cannot specify both --text-field and --async.");
+        }
+    }
     const effectiveControl = control ?? context?.control;
     const effectiveSignal = effectiveControl?.signal;
     const effectiveFlatArgs = flatArgs ?? options.flatArgs;
@@ -131,6 +151,21 @@ export async function executeAction(id, options, context, flatArgs, control) {
                 }
             }
             else {
+                let effectiveTextField = options.textField;
+                if (!isMachine && effectiveTextField === undefined) {
+                    try {
+                        const spec = await service.discovery.describeAction(targetRef);
+                        effectiveTextField = resolveActionDefaultTextField(spec.annotations);
+                    }
+                    catch (err) {
+                        if (err?.code === ACTION_NOT_FOUND || err?.code === NOT_FOUND) {
+                            // 若动作未找到，继续交由 execution.run 生成统一的执行与提示结果
+                        }
+                        else {
+                            throw err;
+                        }
+                    }
+                }
                 const result = await service.execution.run(targetRef, input, {
                     signal: effectiveSignal,
                     timeoutMs,
@@ -152,7 +187,7 @@ export async function executeAction(id, options, context, flatArgs, control) {
                     }
                 }
                 else {
-                    renderRawExecutionResult(targetRef, result, context);
+                    renderRawExecutionResult(targetRef, result, context, { textField: effectiveTextField });
                 }
                 if (!result.ok) {
                     if (context) {
@@ -203,6 +238,10 @@ Flat Input Syntax & Examples:
     # Nested object properties
     ad run <id> -- user.name="alice" user.age:=30
 
+  Text Field Output:
+    # Extract specific text field to stdout (remaining fields as JSON to stderr)
+    ad run <id> --text-field content -- path="README.md"
+
   Complex or multiline inputs:
     # Pass via JSON file with --input-file to avoid shell escaping issues
     ad run <id> --input-file input.json`;
@@ -229,6 +268,7 @@ export function attachRunCommand(parent, context) {
         .option("--async", "Execute asynchronously in background (requires remote server or profile)")
         .option("--data-dir <path>", "Custom database directory")
         .option("--json", "Output as JSON")
+        .option("--text-field <field>", "Extract and output a specific top-level string field as raw text")
         .addHelpText("after", RUN_HELP_AFTER_TEXT)
         .action(async (id, params, rawOptions, cmd) => {
         let flatArgs;

package/dist/renderers/action.d.ts

@@ -1,5 +1,32 @@
 import type { ActionSpec } from "@actiondock/core";
 import { buildActionDescribePayload } from "@actiondock/core/project";
+/**
+ * 解析 Action 注解中的默认正文输出字段声明。
+ *
+ * 契约规范：
+ * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
+ * - 正文字段键名为 textField，值必须为非空字符串。
+ * - 无相关注解或未声明 textField 时返回 undefined。
+ * - 注解存在但类型非法时抛出 ExecutionError。
+ */
+export declare function resolveActionDefaultTextField(annotations?: Record<string, unknown>): string | undefined;
+/**
+ * 结构化正文与元数据抽取结果。
+ */
+export interface TextFieldExtractionResult {
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 从 Action 执行数据中抽取指定自有顶层正文字段及剩余元数据。
+ *
+ * 契约规范：
+ * - 仅支持结果数据的顶层自有字符串字段，拒绝通过原型链提取。
+ * - 结果数据本身必须为对象且不能为数组。
+ * - 目标字段必须存在且值为字符串（空字符串为合法有效正文）。
+ * - 剩余元数据安全构造，杜绝原型污染；元数据为空时返回 undefined。
+ */
+export declare function extractTextFieldPayload(data: unknown, textField: string): TextFieldExtractionResult;
 /**
  * 格式化渲染 Action 列表。
  */

package/dist/renderers/action.js

@@ -1,4 +1,79 @@
 import { buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, } from "@actiondock/core/project";
+import { ExecutionError } from "../errors.js";
+/**
+ * 解析 Action 注解中的默认正文输出字段声明。
+ *
+ * 契约规范：
+ * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
+ * - 正文字段键名为 textField，值必须为非空字符串。
+ * - 无相关注解或未声明 textField 时返回 undefined。
+ * - 注解存在但类型非法时抛出 ExecutionError。
+ */
+export function resolveActionDefaultTextField(annotations) {
+    if (!annotations || typeof annotations !== "object") {
+        return undefined;
+    }
+    if (!Object.hasOwn(annotations, "actiondock.cli")) {
+        return undefined;
+    }
+    const cli = annotations["actiondock.cli"];
+    if (cli === undefined) {
+        return undefined;
+    }
+    if (typeof cli !== "object" || cli === null || Array.isArray(cli)) {
+        throw new ExecutionError(`Invalid 'actiondock.cli' annotation: expected an object, but received ${cli === null ? "null" : Array.isArray(cli) ? "an array" : typeof cli}.`, undefined, "INVALID_ANNOTATION");
+    }
+    if (!Object.hasOwn(cli, "textField") || cli.textField === undefined) {
+        return undefined;
+    }
+    const textField = cli.textField;
+    if (typeof textField !== "string") {
+        throw new ExecutionError(`Invalid 'actiondock.cli.textField' annotation: expected a string, but received ${textField === null ? "null" : Array.isArray(textField) ? "an array" : typeof textField}.`, undefined, "INVALID_ANNOTATION");
+    }
+    if (textField.trim() === "") {
+        throw new ExecutionError("Invalid 'actiondock.cli.textField' annotation: cannot be an empty string.", undefined, "INVALID_ANNOTATION");
+    }
+    return textField;
+}
+/**
+ * 从 Action 执行数据中抽取指定自有顶层正文字段及剩余元数据。
+ *
+ * 契约规范：
+ * - 仅支持结果数据的顶层自有字符串字段，拒绝通过原型链提取。
+ * - 结果数据本身必须为对象且不能为数组。
+ * - 目标字段必须存在且值为字符串（空字符串为合法有效正文）。
+ * - 剩余元数据安全构造，杜绝原型污染；元数据为空时返回 undefined。
+ */
+export function extractTextFieldPayload(data, textField) {
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new ExecutionError(`CLI output format error: expected result data to be an object, but received ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}.`, undefined, "OUTPUT_FORMAT_ERROR");
+    }
+    if (!Object.hasOwn(data, textField)) {
+        throw new ExecutionError(`CLI output format error: text field '${textField}' was not found in result data.`, undefined, "OUTPUT_FORMAT_ERROR");
+    }
+    const textValue = data[textField];
+    if (typeof textValue !== "string") {
+        throw new ExecutionError(`CLI output format error: text field '${textField}' must be a string, but received ${textValue === null ? "null" : Array.isArray(textValue) ? "an array" : typeof textValue}.`, undefined, "OUTPUT_FORMAT_ERROR");
+    }
+    const metadata = {};
+    let hasMetadata = false;
+    for (const key of Object.keys(data)) {
+        if (key === textField) {
+            continue;
+        }
+        Object.defineProperty(metadata, key, {
+            value: data[key],
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+        hasMetadata = true;
+    }
+    return {
+        text: textValue,
+        metadata: hasMetadata ? metadata : undefined,
+    };
+}
 /**
  * 格式化渲染 Action 列表。
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,10 +34,10 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.11.0",
-    "@actiondock/core": "^2.11.0",
-    "@actiondock/mcp": "^2.11.0",
-    "@actiondock/sdk": "^2.11.0",
+    "@actiondock/builder": "^2.12.0",
+    "@actiondock/core": "^2.12.0",
+    "@actiondock/mcp": "^2.12.0",
+    "@actiondock/sdk": "^2.12.0",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },