@actiondock/core 2.12.0 → 2.14.0

package/dist/input/input-resolver.js

@@ -1,5 +1,7 @@
-import { inputConflict, inputLimitExceeded, invalidJson, InputError, FlatInputError, } from "./flat-errors.js";
+import { inputConflict, inputLimitExceeded, inputPathConflict, invalidFlatArgument, invalidJson, InputError, FlatInputError, } from "./flat-errors.js";
+import { isFlatPathPropertyName, isForbiddenActionInputPropertyName, } from "./flat-predicates.js";
 import { decodeFlatInput } from "./flat-decode.js";
+import { assertTopLevelLeafAvailable, assertMaterializedInputWithinLimits, } from "./flat-materializer.js";
 import { validateJsonValue, DEFAULT_MAX_JSON_DEPTH, } from "../value-validator.js";
 import { scanJsonDepth } from "./json-depth-scanner.js";
 import { decodeUtf8Strict, stripBom } from "./utf8.js";
@@ -103,6 +105,62 @@ function sanitizeError(err, source) {
     }
     return err;
 }
+/**
+ * 检测单个扁平 token 是否占用 stdin 绑定目标字段。
+ *
+ * 判定范围（在读 stdin 与执行业务之前）：
+ * - 目标字段本身：重复赋值（DUPLICATE_ASSIGNMENT）；
+ * - 目标字段的任意嵌套路径：叶/容器冲突（LEAF_CONTAINER_CONFLICT）。
+ *
+ * @param token 扁平赋值 token
+ * @param field stdin 绑定的目标字段名
+ */
+function detectFlatTokenFieldConflict(token, field) {
+    const colonEqIndex = token.indexOf(":=");
+    const eqIndex = token.indexOf("=");
+    let opIndex = -1;
+    if (colonEqIndex !== -1 && (eqIndex === -1 || colonEqIndex < eqIndex)) {
+        opIndex = colonEqIndex;
+    }
+    else if (eqIndex !== -1) {
+        opIndex = eqIndex;
+    }
+    const rawPath = opIndex === -1 ? token : token.slice(0, opIndex);
+    if (rawPath !== field && !rawPath.startsWith(`${field}.`))
+        return null;
+    return inputPathConflict(`Input path conflict at "${rawPath}": field "${field}" is already bound to stdin text via --stdin-field`, { path: rawPath, reason: rawPath === field ? "DUPLICATE_ASSIGNMENT" : "LEAF_CONTAINER_CONFLICT" });
+}
+/**
+ * 校验 stdin 字段绑定名是否为合法安全顶层属性名。
+ *
+ * 拒绝空、纯空白、危险属性（`__proto__`、`constructor`、`prototype`）与
+ * 不符合扁平命名段规范（含点分嵌套路径）的表达，错误为 INVALID_FLAT_ARGUMENT。
+ *
+ * @param field 用户提供的字段名
+ */
+function assertStdinFieldName(field) {
+    const problem = (() => {
+        if (field.length === 0)
+            return "empty";
+        if (field.trim() !== field || field.trim().length === 0)
+            return "whitespace";
+        if (isForbiddenActionInputPropertyName(field))
+            return "forbidden";
+        if (field.includes("."))
+            return "dotted";
+        if (!isFlatPathPropertyName(field))
+            return "invalid";
+        return null;
+    })();
+    if (problem === null)
+        return;
+    const reason = problem === "forbidden"
+        ? "FORBIDDEN_PROPERTY"
+        : problem === "dotted"
+            ? "INVALID_DOT_NOTATION"
+            : "INVALID_SEGMENT";
+    throw invalidFlatArgument(`Invalid --stdin-field name (length: ${field.length}): must be a non-empty top-level property name without dot notation`, { length: field.length, reason });
+}
 /**
  * 解析完整 JSON 文档字符串。
  * 若解析失败抛出 INVALID_JSON 异常。
@@ -152,11 +210,15 @@ export function parseJson(text, source, policy) {
  * - effectiveFlat: flatArgs 存在且 length > 0
  * - hasInlineJson: options.input !== undefined（即使为 ""）
  * - hasFileJson: options.inputFile !== undefined（包含 "-"）
- * - 最多一个为 true；若超过一个，抛出 INPUT_CONFLICT（reason: "MULTIPLE_INPUT_MODES"）。
- * - 若三个均为 false，返回默认 {}。
+ * - hasStdinField: options.stdinField !== undefined
+ * - flat / inline JSON / file JSON 三者仍保持原有严格互斥；
+ * - stdinField 可与 flatArgs 组合（正文绑定到字段 + 扁平补充其他字段），
+ *   但与 inline JSON、file JSON（含 inputFile="-"）任何来源严格互斥；
+ * - 若四者均为 false，返回默认 {}。
  * - flatArgs = [] 视为未指定。
  * - options.input === "" 为显式 Full JSON 模式，进入解析并得到 INVALID_JSON / SYNTAX_ERROR，不可退化为 {}。
  * - 显式空 JSON 输入（--input ""、0 字节文件、空 stdin、纯空白、纯 BOM）统一返回 INVALID_JSON / SYNTAX_ERROR。
+ * - stdinField 的 stdin 读取为原始文本绑定：不做 JSON 解析、不剥 BOM、保留首尾空白，空 stdin 得到空字符串。
  *
  * @param options 输入解析选项
  * @returns 解析后的 JSON 对象
@@ -165,6 +227,22 @@ export async function resolveActionInput(options) {
     const effectiveFlat = (options.flatArgs?.length ?? 0) > 0;
     const hasInlineJson = options.input !== undefined;
     const hasFileJson = options.inputFile !== undefined;
+    const hasStdinField = options.stdinField !== undefined;
+    // stdin 字段绑定与完整 JSON 来源（内联 / 文件 / stdin JSON）严格互斥
+    if (hasStdinField && (hasInlineJson || hasFileJson)) {
+        const err = inputConflict("Input options conflict: --stdin-field binds raw stdin text to an action input field and cannot be combined with inline JSON (-i/--input) or file input (-f/--input-file).", {
+            reason: "MULTIPLE_INPUT_MODES",
+            hasFlatArgs: effectiveFlat,
+            hasInput: hasInlineJson,
+            hasInputFile: hasFileJson,
+            hasStdinField,
+        });
+        if (options.policy?.sanitizeInputErrors) {
+            throw sanitizeError(err, "stdin");
+        }
+        throw err;
+    }
+    // 原有三种完整输入模式之间的严格互斥保持不变
     let modeCount = 0;
     if (effectiveFlat)
         modeCount++;
@@ -184,11 +262,52 @@ export async function resolveActionInput(options) {
         }
         throw err;
     }
-    if (modeCount === 0) {
+    if (modeCount === 0 && !hasStdinField) {
         return {};
     }
     const policy = options.policy;
     const maxBytes = policy?.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES;
+    // 0. stdin 原始文本字段绑定模式（可与 flatArgs 组合）
+    if (hasStdinField) {
+        const field = options.stdinField;
+        try {
+            assertStdinFieldName(field);
+            // 冲突检测与扁平完整解码均先于 stdin 读取：
+            // 目标字段占用冲突与任何已知的 flat 语法/路径/字面量错误在读 stdin 前拒绝，
+            // 不因等待上游 EOF 而挂起；解码结果复用，读取后不再重复解码。
+            let result = {};
+            if (effectiveFlat) {
+                for (const token of options.flatArgs) {
+                    const conflict = detectFlatTokenFieldConflict(token, field);
+                    if (conflict) {
+                        throw conflict;
+                    }
+                }
+                result = decodeFlatInput(options.flatArgs, options.flatOptions);
+                assertTopLevelLeafAvailable(result, field);
+            }
+            const text = await readStdinBounded(options.stdin || process.stdin, {
+                maxInputBytes: maxBytes,
+                signal: options.signal,
+                byteStreamOnly: policy?.byteStreamOnly,
+                strictUtf8: policy?.strictUtf8 ?? true,
+                rawText: policy?.stdinRawText ?? true,
+            });
+            // 绑定后对最终入参执行既有实体化结构/总大小校验：
+            // stdin 源字节上限（maxInputBytes）与最终对象序列化上限
+            // （flatOptions.maxMaterializedSizeBytes，默认 10MiB）各自独立生效，
+            // 正文中的引号/反斜杠转义放大亦被最终上限拦截。
+            result[field] = text;
+            assertMaterializedInputWithinLimits(result, options.flatOptions);
+            return result;
+        }
+        catch (err) {
+            if (policy?.sanitizeInputErrors) {
+                throw sanitizeError(err, "stdin");
+            }
+            throw err;
+        }
+    }
     // 1. 扁平入参模式
     if (effectiveFlat) {
         try {

package/dist/input/output-contract.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Action 输出正文字段与 Schema 契约静态分析工具。
+ *
+ * 核心设计原则：
+ * - 纯数据分析：仅基于 Action 清单与 Schema 纯元数据推导，无数据库、无模块加载、无业务执行副作用。
+ * - 静态契约门禁：区分确定矛盾（错误）与无法证明安全（风险警告），不将不确定误判为合法，亦不为证明安全而试跑动作。
+ * - 单一事实源：声明解析、展示描述与门禁校验共用同一套底层纯规则。
+ */
+/**
+ * 契约诊断项。
+ */
+export interface OutputContractDiagnostic {
+    type: "error" | "warning";
+    code: string;
+    message: string;
+}
+/**
+ * 注解解析与检验结果。
+ */
+export interface AnnotationInspectionResult {
+    declared: boolean;
+    valid: boolean;
+    textField?: string;
+    error?: string;
+}
+/**
+ * 输出契约分析输入项。
+ */
+export interface ActionOutputContractInput {
+    annotations?: unknown;
+    outputSchema?: unknown;
+}
+/**
+ * 输出契约全量分析结果。
+ */
+export interface ActionOutputContractAnalysis {
+    declared: boolean;
+    valid: boolean;
+    textField?: string;
+    errors: string[];
+    warnings: string[];
+    diagnostics: OutputContractDiagnostic[];
+}
+/**
+ * 纯静态解析并校验 Action annotations 中的 actiondock.cli 声明。
+ *
+ * 契约规范：
+ * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
+ * - 正文字段键名为 textField，值必须为非空字符串。
+ * - 无相关注解或未声明 textField 时返回 declared: false, valid: true。
+ * - 注解存在但类型非法时返回 valid: false 与对应错误描述。
+ */
+export declare function inspectActionTextFieldAnnotation(annotations?: unknown): AnnotationInspectionResult;
+/**
+ * 静态分析 Action 输出契约（textField 注解与 outputSchema 的兼容性）。
+ *
+ * 错误判断（确定矛盾）：
+ * - 注解结构非法或 textField 不是非空字符串；
+ * - Schema 明确拒绝所有结果（boolean false）；
+ * - Schema 明确只允许非对象根类型；
+ * - Schema 明确禁止目标属性（property schema 为 false）；
+ * - Schema 明确要求目标属性为非字符串类型；
+ * - 目标属性不存在且 Schema 明确禁止额外属性（additionalProperties 为 false）。
+ *
+ * 风险提示（无法完全静态证明安全）：
+ * - 目标字段未声明为 required；
+ * - 目标字段允许 null 等非字符串类型；
+ * - outputSchema 缺失或为布尔 true；
+ * - 未声明 properties 但允许额外属性，或未声明目标属性但允许额外属性；
+ * - Schema 包含 oneOf/anyOf/allOf/$ref 复杂组合无法简单静态推导。
+ */
+export declare function analyzeActionOutputContract(input: ActionOutputContractInput): ActionOutputContractAnalysis;

package/dist/input/output-contract.js

@@ -0,0 +1,274 @@
+/**
+ * Action 输出正文字段与 Schema 契约静态分析工具。
+ *
+ * 核心设计原则：
+ * - 纯数据分析：仅基于 Action 清单与 Schema 纯元数据推导，无数据库、无模块加载、无业务执行副作用。
+ * - 静态契约门禁：区分确定矛盾（错误）与无法证明安全（风险警告），不将不确定误判为合法，亦不为证明安全而试跑动作。
+ * - 单一事实源：声明解析、展示描述与门禁校验共用同一套底层纯规则。
+ */
+/**
+ * 纯静态解析并校验 Action annotations 中的 actiondock.cli 声明。
+ *
+ * 契约规范：
+ * - 注解键名固定为 actiondock.cli，值必须为非空非数组对象。
+ * - 正文字段键名为 textField，值必须为非空字符串。
+ * - 无相关注解或未声明 textField 时返回 declared: false, valid: true。
+ * - 注解存在但类型非法时返回 valid: false 与对应错误描述。
+ */
+export function inspectActionTextFieldAnnotation(annotations) {
+    if (!annotations || typeof annotations !== "object" || Array.isArray(annotations)) {
+        return { declared: false, valid: true };
+    }
+    const record = annotations;
+    if (!Object.hasOwn(record, "actiondock.cli")) {
+        return { declared: false, valid: true };
+    }
+    const cli = record["actiondock.cli"];
+    if (cli === undefined) {
+        return { declared: false, valid: true };
+    }
+    if (typeof cli !== "object" || cli === null || Array.isArray(cli)) {
+        return {
+            declared: true,
+            valid: false,
+            error: `Invalid 'actiondock.cli' annotation: expected an object, but received ${cli === null ? "null" : Array.isArray(cli) ? "an array" : typeof cli}.`,
+        };
+    }
+    const cliRecord = cli;
+    if (!Object.hasOwn(cliRecord, "textField") || cliRecord.textField === undefined) {
+        return { declared: false, valid: true };
+    }
+    const textField = cliRecord.textField;
+    if (typeof textField !== "string") {
+        return {
+            declared: true,
+            valid: false,
+            error: `Invalid 'actiondock.cli.textField' annotation: expected a string, but received ${textField === null ? "null" : Array.isArray(textField) ? "an array" : typeof textField}.`,
+        };
+    }
+    if (textField.trim() === "") {
+        return {
+            declared: true,
+            valid: false,
+            error: "Invalid 'actiondock.cli.textField' annotation: cannot be an empty string.",
+        };
+    }
+    return {
+        declared: true,
+        valid: true,
+        textField,
+    };
+}
+/**
+ * 静态分析 Action 输出契约（textField 注解与 outputSchema 的兼容性）。
+ *
+ * 错误判断（确定矛盾）：
+ * - 注解结构非法或 textField 不是非空字符串；
+ * - Schema 明确拒绝所有结果（boolean false）；
+ * - Schema 明确只允许非对象根类型；
+ * - Schema 明确禁止目标属性（property schema 为 false）；
+ * - Schema 明确要求目标属性为非字符串类型；
+ * - 目标属性不存在且 Schema 明确禁止额外属性（additionalProperties 为 false）。
+ *
+ * 风险提示（无法完全静态证明安全）：
+ * - 目标字段未声明为 required；
+ * - 目标字段允许 null 等非字符串类型；
+ * - outputSchema 缺失或为布尔 true；
+ * - 未声明 properties 但允许额外属性，或未声明目标属性但允许额外属性；
+ * - Schema 包含 oneOf/anyOf/allOf/$ref 复杂组合无法简单静态推导。
+ */
+export function analyzeActionOutputContract(input) {
+    const inspection = inspectActionTextFieldAnnotation(input.annotations);
+    if (!inspection.valid) {
+        const errorMsg = inspection.error;
+        return {
+            declared: true,
+            valid: false,
+            errors: [errorMsg],
+            warnings: [],
+            diagnostics: [
+                {
+                    type: "error",
+                    code: "INVALID_ANNOTATION",
+                    message: errorMsg,
+                },
+            ],
+        };
+    }
+    if (!inspection.declared || !inspection.textField) {
+        return {
+            declared: false,
+            valid: true,
+            errors: [],
+            warnings: [],
+            diagnostics: [],
+        };
+    }
+    const textField = inspection.textField;
+    const errors = [];
+    const warnings = [];
+    const diagnostics = [];
+    function addError(code, message) {
+        errors.push(message);
+        diagnostics.push({ type: "error", code, message });
+    }
+    function addWarning(code, message) {
+        warnings.push(message);
+        diagnostics.push({ type: "warning", code, message });
+    }
+    const schema = input.outputSchema;
+    if (schema === undefined) {
+        addWarning("OUTPUT_SCHEMA_ABSENT", `Output schema is absent; cannot statically verify text field '${textField}'. Runtime validation will apply.`);
+        return {
+            declared: true,
+            valid: true,
+            textField,
+            errors,
+            warnings,
+            diagnostics,
+        };
+    }
+    if (schema === false) {
+        addError("OUTPUT_SCHEMA_REJECTS_ALL", `Output schema explicitly rejects all outputs (schema is false); cannot produce object containing text field '${textField}'.`);
+        return {
+            declared: true,
+            valid: false,
+            textField,
+            errors,
+            warnings,
+            diagnostics,
+        };
+    }
+    if (schema === true) {
+        addWarning("OUTPUT_SCHEMA_ARBITRARY", `Output schema allows arbitrary values (schema is true); text field '${textField}' is not guaranteed to exist or be a string.`);
+        return {
+            declared: true,
+            valid: true,
+            textField,
+            errors,
+            warnings,
+            diagnostics,
+        };
+    }
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        addError("INVALID_OUTPUT_SCHEMA", "Invalid outputSchema: expected a schema object or boolean.");
+        return {
+            declared: true,
+            valid: false,
+            textField,
+            errors,
+            warnings,
+            diagnostics,
+        };
+    }
+    const s = schema;
+    // 1. 检查根节点类型约束
+    if (s.type === undefined) {
+        addWarning("ROOT_TYPE_UNSPECIFIED", `Output schema does not explicitly specify root type as 'object'; non-object outputs cannot satisfy text field '${textField}'.`);
+    }
+    else {
+        const rootTypes = Array.isArray(s.type) ? s.type : [s.type];
+        if (!rootTypes.includes("object")) {
+            addError("ROOT_TYPE_NOT_OBJECT", `Output schema root type is '${String(s.type)}', which does not allow an object required for text field '${textField}'.`);
+            return {
+                declared: true,
+                valid: false,
+                textField,
+                errors,
+                warnings,
+                diagnostics,
+            };
+        }
+        const nonObjectTypes = rootTypes.filter((t) => t !== "object");
+        if (nonObjectTypes.length > 0) {
+            addWarning("ROOT_TYPE_ALLOWS_NON_OBJECT", `Output schema root type allows non-object types (${nonObjectTypes.join(", ")}); text output requires an object at runtime.`);
+        }
+    }
+    // 2. 检查复杂组合关键字（oneOf, anyOf, allOf, $ref）
+    if (s.oneOf || s.anyOf || s.allOf || s.$ref) {
+        addWarning("COMPLEX_SCHEMA_COMPOSITION", `Output schema contains complex composition keywords (oneOf/anyOf/allOf/$ref); text field '${textField}' cannot be fully verified statically.`);
+    }
+    const hasPatternProps = Boolean(s.patternProperties &&
+        typeof s.patternProperties === "object" &&
+        !Array.isArray(s.patternProperties) &&
+        Object.keys(s.patternProperties).length > 0);
+    // 3. 检查属性定义与目标字段
+    if (s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)) {
+        const props = s.properties;
+        if (Object.hasOwn(props, textField)) {
+            const fieldSchema = props[textField];
+            if (fieldSchema === false) {
+                addError("TEXT_FIELD_FORBIDDEN", `Output schema property '${textField}' is explicitly forbidden (property schema is false).`);
+            }
+            else if (fieldSchema === true) {
+                addWarning("TEXT_FIELD_UNTYPED", `Property '${textField}' does not specify a type; cannot guarantee it will be a string.`);
+            }
+            else if (typeof fieldSchema === "object" &&
+                fieldSchema !== null &&
+                !Array.isArray(fieldSchema)) {
+                const propObj = fieldSchema;
+                if (propObj.oneOf || propObj.anyOf || propObj.allOf || propObj.$ref) {
+                    addWarning("TEXT_FIELD_COMPLEX_COMPOSITION", `Property '${textField}' contains complex composition keywords (oneOf/anyOf/allOf/$ref); text output cannot be fully verified statically.`);
+                }
+                if (propObj.type === undefined) {
+                    addWarning("TEXT_FIELD_UNTYPED", `Property '${textField}' does not specify a type; cannot guarantee it will be a string.`);
+                }
+                else {
+                    const fieldTypes = Array.isArray(propObj.type) ? propObj.type : [propObj.type];
+                    if (!fieldTypes.includes("string")) {
+                        addError("TEXT_FIELD_NOT_STRING", `Output schema property '${textField}' has type '${String(propObj.type)}', which does not allow string.`);
+                    }
+                    else {
+                        const nonStringTypes = fieldTypes.filter((t) => t !== "string");
+                        if (nonStringTypes.length > 0) {
+                            addWarning("TEXT_FIELD_ALLOWS_NON_STRING", `Property '${textField}' allows non-string types (${nonStringTypes.join(", ")}); text output requires a string at runtime.`);
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            // 字段未在 properties 中明确定义
+            if (s.additionalProperties === false) {
+                if (hasPatternProps) {
+                    addWarning("TEXT_FIELD_PATTERN_PROPERTIES", `Text field '${textField}' is not declared in properties; presence may be governed by patternProperties and cannot be fully verified statically.`);
+                }
+                else {
+                    addError("TEXT_FIELD_DISALLOWED_ADDITIONAL", `Text field '${textField}' is not declared in outputSchema properties and additionalProperties is false.`);
+                }
+            }
+            else {
+                addWarning("TEXT_FIELD_UNDECLARED_ADDITIONAL", `Text field '${textField}' is not declared in outputSchema properties (allowed via additionalProperties); existence and type cannot be statically verified.`);
+            }
+        }
+    }
+    else {
+        // 未定义 properties
+        if (s.additionalProperties === false) {
+            if (hasPatternProps) {
+                addWarning("TEXT_FIELD_PATTERN_PROPERTIES", `Text field '${textField}' is not declared in properties; presence may be governed by patternProperties and cannot be fully verified statically.`);
+            }
+            else {
+                addError("TEXT_FIELD_DISALLOWED_NO_PROPERTIES", `Output schema has no properties declared and additionalProperties is false; text field '${textField}' cannot exist.`);
+            }
+        }
+        else {
+            addWarning("TEXT_FIELD_NO_PROPERTIES", `Output schema does not define properties; text field '${textField}' existence cannot be statically verified.`);
+        }
+    }
+    // 4. 检查 required 约束（若无确定阻止字段存在的错误）
+    if (errors.length === 0) {
+        const isRequired = Array.isArray(s.required) && s.required.includes(textField);
+        if (!isRequired) {
+            addWarning("TEXT_FIELD_NOT_REQUIRED", `Text field '${textField}' is not marked as required in outputSchema; if absent at runtime, text extraction will fail with OUTPUT_FORMAT_ERROR (business execution remains successful in run records).`);
+        }
+    }
+    return {
+        declared: true,
+        valid: errors.length === 0,
+        textField,
+        errors,
+        warnings,
+        diagnostics,
+    };
+}

package/dist/input/stdin-input.d.ts

@@ -10,6 +10,15 @@ export interface ReadStdinBoundedOptions {
     byteStreamOnly?: boolean;
     /** 是否执行严格 UTF-8 校验与解码（默认 true） */
     strictUtf8?: boolean;
+    /**
+     * 原始文本模式（默认 false）。
+     *
+     * 语义差异（仅在 strictUtf8 下生效）：
+     * - 保留开头 BOM（U+FEFF）作为正文一部分，不执行剥离；
+     * - 编码失败映射为 INPUT_FILE_READ_FAILED（reason: "INVALID_UTF8"）读取失败，
+     *   而不是完整 JSON 场景的 INVALID_JSON 解析失败。
+     */
+    rawText?: boolean;
 }
 /**
  * 以有界大小限制从标准输入流中安全读取全部内容。
@@ -17,7 +26,8 @@ export interface ReadStdinBoundedOptions {
  * 核心契约：
  * - 纯字节流策略拦截：若启用 byteStreamOnly 且流发射 string chunk，抛出 INPUT_FILE_READ_FAILED（reason: "INVALID_STREAM_CHUNK_TYPE"）。
  * - 终态竞态裁决（First Observed Terminal Event Wins）：EOF、limit、abort 谁先观测谁生效，后续事件仅执行清理，不篡改已确定的错误与结果。
- * - 严格 UTF-8 校验：在 strictUtf8 下通过 decodeUtf8Strict 校验并抛出结构化 INVALID_JSON 异常。
+ * - 严格 UTF-8 校验：在 strictUtf8 下通过 decodeUtf8Strict 校验并抛出结构化 INVALID_JSON 异常；
+ *   rawText 模式改为保留 BOM 的 fatal 解码，编码失败抛出 INPUT_FILE_READ_FAILED（reason: "INVALID_UTF8"）。
  *
  * @param stream 标准输入可读流，默认为 process.stdin
  * @param options 读取配置选项

package/dist/input/stdin-input.js

@@ -7,7 +7,8 @@ import { DEFAULT_MAX_INPUT_BYTES } from "./file-input.js";
  * 核心契约：
  * - 纯字节流策略拦截：若启用 byteStreamOnly 且流发射 string chunk，抛出 INPUT_FILE_READ_FAILED（reason: "INVALID_STREAM_CHUNK_TYPE"）。
  * - 终态竞态裁决（First Observed Terminal Event Wins）：EOF、limit、abort 谁先观测谁生效，后续事件仅执行清理，不篡改已确定的错误与结果。
- * - 严格 UTF-8 校验：在 strictUtf8 下通过 decodeUtf8Strict 校验并抛出结构化 INVALID_JSON 异常。
+ * - 严格 UTF-8 校验：在 strictUtf8 下通过 decodeUtf8Strict 校验并抛出结构化 INVALID_JSON 异常；
+ *   rawText 模式改为保留 BOM 的 fatal 解码，编码失败抛出 INPUT_FILE_READ_FAILED（reason: "INVALID_UTF8"）。
  *
  * @param stream 标准输入可读流，默认为 process.stdin
  * @param options 读取配置选项
@@ -18,6 +19,7 @@ export async function readStdinBounded(stream = process.stdin, options) {
     const signal = options?.signal;
     const byteStreamOnly = options?.byteStreamOnly ?? false;
     const strictUtf8 = options?.strictUtf8 ?? true;
+    const rawText = options?.rawText ?? false;
     // 启动前检查 abort
     if (signal?.aborted) {
         throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
@@ -101,8 +103,18 @@ export async function readStdinBounded(stream = process.stdin, options) {
             try {
                 const fullBuffer = Buffer.concat(chunks);
                 if (strictUtf8) {
-                    const text = decodeUtf8Strict(fullBuffer, "full-json-stdin");
-                    resolve(text);
+                    if (rawText) {
+                        // 原始文本模式：保留开头 BOM，编码失败视为读取失败而非 JSON 解析失败
+                        try {
+                            resolve(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fullBuffer));
+                        }
+                        catch (err) {
+                            reject(inputFileReadFailed("stdin", new Error(`Invalid UTF-8 encoding: ${err instanceof Error ? err.message : String(err)}`), { reason: "INVALID_UTF8" }));
+                        }
+                    }
+                    else {
+                        resolve(decodeUtf8Strict(fullBuffer, "full-json-stdin"));
+                    }
                 }
                 else {
                     resolve(fullBuffer.toString("utf8"));

package/dist/project/index.d.ts

@@ -3,13 +3,14 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
+export * from "./skill-dir.js";
 export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, type TraverseDirectoryEntry, type TraverseDirectoryOptions, } from "../utils/index.js";
 export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
-export { resolveActionInput, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
+export { resolveActionInput, buildActionDescribePayload, formatActionDetail, type FormatActionDetailOptions, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, type AnnotationInspectionResult, type ActionOutputContractInput, type ActionOutputContractAnalysis, type OutputContractDiagnostic, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
 export { validateActionInputValue } from "../value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";

package/dist/project/index.js

@@ -3,14 +3,15 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
+export * from "./skill-dir.js";
 export { SNAPSHOT_TRACKED_FILES, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, } from "../utils/index.js";
 export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
-// 动作入参解析、校验与格式化（含 BOM 剥离与标准输入有界读取的单一事实源转引）
-export { resolveActionInput, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
+// 动作入参解析、输出契约分析、校验与格式化（含 BOM 剥离与标准输入有界读取的单一事实源转引）
+export { resolveActionInput, buildActionDescribePayload, formatActionDetail, ACTION_DESCRIBE_SYNTAX_REFERENCE, inspectActionTextFieldAnnotation, analyzeActionOutputContract, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
 export { validateActionInputValue } from "../value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.12.0",
+            "@actiondock/sdk": "^2.14.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.12.0",
+            "@actiondock/testing": "^2.14.0",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",