@actiondock/cli 2.12.0 → 2.13.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/dist/commands/run.js

@@ -78,6 +78,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 +92,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) {
@@ -242,6 +251,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 +272,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" });
     };

package/dist/commands/validate.js

@@ -1,4 +1,4 @@
-import { checkGeneratedTypes, GENERATED_TYPES_OUTDATED_CODE, loadActions, } from "@actiondock/core/project";
+import { checkGeneratedTypes, GENERATED_TYPES_OUTDATED_CODE, loadActions, analyzeActionOutputContract, } from "@actiondock/core/project";
 import { ArgumentError, ExecutionError } from "../errors.js";
 import { renderActionValidation, renderResult } from "../renderer.js";
 import { getEffectiveOptions, requirePackageRoot } from "../utils/index.js";
@@ -49,10 +49,22 @@ export function attachValidateCommand(parent, context) {
             if (outSchema && typeof outSchema !== "object") {
                 errors.push("Invalid outputSchema object");
             }
+            const annotations = item.spec?.annotations ?? item.act?.annotations;
+            const contractAnalysis = analyzeActionOutputContract({
+                annotations,
+                outputSchema: outSchema,
+            });
+            if (contractAnalysis.errors.length > 0) {
+                for (const err of contractAnalysis.errors) {
+                    errors.push(err);
+                }
+            }
+            const warnings = contractAnalysis.warnings.slice();
             results.push({
                 id: item.id,
                 valid: errors.length === 0,
                 errors,
+                ...(warnings.length > 0 ? { warnings } : {}),
             });
         }
         const allValid = results.every((r) => r.valid);

package/dist/renderers/action.d.ts

@@ -1,5 +1,5 @@
-import type { ActionSpec } from "@actiondock/core";
-import { buildActionDescribePayload } from "@actiondock/core/project";
+import { formatActionDetail, type FormatActionDetailOptions } from "@actiondock/core/project";
+export { formatActionDetail, type FormatActionDetailOptions, };
 /**
  * 解析 Action 注解中的默认正文输出字段声明。
  *
@@ -7,7 +7,7 @@ import { buildActionDescribePayload } from "@actiondock/core/project";
  * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
  * - 正文字段键名为 textField，值必须为非空字符串。
  * - 无相关注解或未声明 textField 时返回 undefined。
- * - 注解存在但类型非法时抛出 ExecutionError。
+ * - 注解存在但类型非法时抛出 ExecutionError (INVALID_ANNOTATION)。
  */
 export declare function resolveActionDefaultTextField(annotations?: Record<string, unknown>): string | undefined;
 /**
@@ -35,30 +35,9 @@ export declare function renderActionList(items: Array<{
     description: string;
     packageId?: string;
 }>, title?: string, isFallback?: boolean, intent?: string): string;
-/**
- * 格式化渲染 Action 详情人类可读文本。
- *
- * @param input Action 描述载荷或 Action 规范
- * @returns 格式化后的说明文本
- */
-export declare function formatActionDetail(input: ReturnType<typeof buildActionDescribePayload> | (Partial<ActionSpec> & {
-    id: string;
-}) | {
-    id: string;
-    packageId?: string;
-    projectRoot?: string;
-    description?: string;
-    inputSchema?: unknown;
-    outputSchema?: unknown;
-    tags?: string[];
-    annotations?: Record<string, unknown>;
-    uses?: string[];
-    entry?: string;
-    [key: string]: any;
-}): string;
 /**
  * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
- * 统一复用 formatActionDetail 实现。
+ * 统一复用核心 formatActionDetail 实现。
  */
 export declare function renderActionDetail(action: {
     id: string;
@@ -75,4 +54,5 @@ export declare function renderActionValidation(results: Array<{
     id: string;
     valid: boolean;
     errors: string[];
+    warnings?: string[];
 }>): string;

package/dist/renderers/action.js

@@ -1,4 +1,5 @@
-import { buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, } from "@actiondock/core/project";
+import { inspectActionTextFieldAnnotation, formatActionDetail, } from "@actiondock/core/project";
+export { formatActionDetail, };
 import { ExecutionError } from "../errors.js";
 /**
  * 解析 Action 注解中的默认正文输出字段声明。
@@ -7,33 +8,14 @@ import { ExecutionError } from "../errors.js";
  * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
  * - 正文字段键名为 textField，值必须为非空字符串。
  * - 无相关注解或未声明 textField 时返回 undefined。
- * - 注解存在但类型非法时抛出 ExecutionError。
+ * - 注解存在但类型非法时抛出 ExecutionError (INVALID_ANNOTATION)。
  */
 export function resolveActionDefaultTextField(annotations) {
-    if (!annotations || typeof annotations !== "object") {
-        return undefined;
+    const inspection = inspectActionTextFieldAnnotation(annotations);
+    if (!inspection.valid) {
+        throw new ExecutionError(inspection.error, undefined, "INVALID_ANNOTATION");
     }
-    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;
+    return inspection.textField;
 }
 /**
  * 从 Action 执行数据中抽取指定自有顶层正文字段及剩余元数据。
@@ -94,78 +76,9 @@ export function renderActionList(items, title = "Actions", isFallback = false, i
     lines.push("\nTip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.");
     return lines.join("\n");
 }
-/**
- * 格式化渲染 Action 详情人类可读文本。
- *
- * @param input Action 描述载荷或 Action 规范
- * @returns 格式化后的说明文本
- */
-export function formatActionDetail(input) {
-    const payload = "inputAdvice" in input && input.inputAdvice
-        ? input
-        : buildActionDescribePayload(input);
-    const lines = [];
-    lines.push(`Action: ${payload.id}`);
-    if (payload.packageId) {
-        lines.push(`Package: ${payload.packageId}`);
-    }
-    if (payload.description) {
-        lines.push(`Description: ${payload.description}`);
-    }
-    if (payload.tags && payload.tags.length > 0) {
-        lines.push(`Tags: ${payload.tags.join(", ")}`);
-    }
-    if (payload.uses && payload.uses.length > 0) {
-        lines.push(`Uses: ${payload.uses.join(", ")}`);
-    }
-    if (payload.entry) {
-        lines.push(`Entry: ${payload.entry}`);
-    }
-    if (payload.inputSchema !== undefined) {
-        lines.push("");
-        lines.push("Input Schema:");
-        lines.push(typeof payload.inputSchema === "string"
-            ? payload.inputSchema
-            : JSON.stringify(payload.inputSchema, null, 2));
-    }
-    if (payload.outputSchema !== undefined) {
-        lines.push("");
-        lines.push("Output Schema:");
-        lines.push(typeof payload.outputSchema === "string"
-            ? payload.outputSchema
-            : JSON.stringify(payload.outputSchema, null, 2));
-    }
-    lines.push("");
-    lines.push(`Recommended Input: ${payload.inputAdvice.recommendedMode}`);
-    if (payload.inputAdvice.reason) {
-        lines.push(`Reason: ${payload.inputAdvice.reason}`);
-    }
-    const hasAssignments = Boolean(payload.inputAdvice.assignments &&
-        Object.keys(payload.inputAdvice.assignments).length > 0);
-    if (hasAssignments) {
-        lines.push("");
-        lines.push("Assignments:");
-        for (const [key, op] of Object.entries(payload.inputAdvice.assignments)) {
-            lines.push(`  ${key}${op}`);
-        }
-    }
-    if (payload.inputAdvice.recommendedMode === "flat" || hasAssignments) {
-        lines.push("");
-        lines.push("Syntax Reference:");
-        lines.push(...(payload.syntaxReference || ACTION_DESCRIBE_SYNTAX_REFERENCE));
-    }
-    if (payload.inputAdvice.issues && payload.inputAdvice.issues.length > 0) {
-        lines.push("");
-        lines.push("Issues:");
-        for (const issue of payload.inputAdvice.issues) {
-            lines.push(`  - ${issue.path}: ${issue.code}`);
-        }
-    }
-    return lines.join("\n");
-}
 /**
  * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
- * 统一复用 formatActionDetail 实现。
+ * 统一复用核心 formatActionDetail 实现。
  */
 export function renderActionDetail(action) {
     return formatActionDetail(action);
@@ -177,10 +90,19 @@ export function renderActionValidation(results) {
     const lines = [];
     for (const r of results) {
         if (r.valid) {
-            lines.push(`[OK] ${r.id}: Valid`);
+            if (r.warnings && r.warnings.length > 0) {
+                lines.push(`[OK] ${r.id}: Valid (warnings: ${r.warnings.join("; ")})`);
+            }
+            else {
+                lines.push(`[OK] ${r.id}: Valid`);
+            }
         }
         else {
-            lines.push(`[FAIL] ${r.id}: ${r.errors.join(", ")}`);
+            let msg = `[FAIL] ${r.id}: ${r.errors.join(", ")}`;
+            if (r.warnings && r.warnings.length > 0) {
+                msg += ` (warnings: ${r.warnings.join("; ")})`;
+            }
+            lines.push(msg);
         }
     }
     return lines.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.12.0",
+  "version": "2.13.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.12.0",
-    "@actiondock/core": "^2.12.0",
-    "@actiondock/mcp": "^2.12.0",
-    "@actiondock/sdk": "^2.12.0",
+    "@actiondock/builder": "^2.13.0",
+    "@actiondock/core": "^2.13.0",
+    "@actiondock/mcp": "^2.13.0",
+    "@actiondock/sdk": "^2.13.0",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },