@actiondock/core 2.12.0 → 2.14.0

package/dist/catalog/graph.d.ts

@@ -6,10 +6,6 @@ import { parseSemVer, type SemVer } from "../utils/index.js";
 import { type DiscoveredPackage, type PackageDiscoveryOptions } from "./discovery.js";
 export type { SemVer };
 export { parseSemVer };
-/**
- * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
- * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
- */
 export declare function areVersionsCompatible(v1: string, v2: string): boolean;
 /**
  * 版本冲突错误。
@@ -145,6 +141,8 @@ export declare class DefaultPackageGraph implements PackageGraph {
 export interface PackageGraphBuilderOptions {
     /** 预先发现的包集合，若未提供则通过 PackageDiscovery 自动发现 */
     packages?: DiscoveredPackage[];
+    /** 完整显式集合的依赖存在性与选定版本校验（Host 增量注册时不启用）。 */
+    validateDependencies?: boolean;
     /** 根工程根目录或根包标识（与 projectRoot 互为别名） */
     root?: string;
     /** 当前工程根目录绝对或相对物理路径 */

package/dist/catalog/graph.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { ActionDockError, ACTION_PACKAGE_VERSION_CONFLICT, MANIFEST_DIGEST_MISMATCH, MANIFEST_NOT_FOUND, MANIFEST_READ_FAILED, PACKAGE_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
+import { ActionDockError, ACTION_PACKAGE_VERSION_CONFLICT, MANIFEST_DIGEST_MISMATCH, MANIFEST_NOT_FOUND, MANIFEST_READ_FAILED, PACKAGE_NOT_FOUND, PACKAGE_ID_CONFLICT, INVALID_ARGUMENT, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
 import { computeManifestDigest, parseJsonWithoutDuplicates } from "../project/digest.js";
 import { loadLockfile } from "../project/lockfile.js";
 import { loadPlaybooks, loadProjectConfig } from "../project/loader.js";
@@ -10,30 +10,124 @@ import { createPackageIdentity } from "../runtime/identity.js";
 import { parseSemVer } from "../utils/index.js";
 import { PackageDiscovery } from "./discovery.js";
 export { parseSemVer };
-/**
- * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
- * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
- */
-export function areVersionsCompatible(v1, v2) {
-    if (v1 === v2 || v1 === "*" || v2 === "*" || !v1 || !v2) {
-        return true;
+/** 有限版本契约：严格三段版本（允许 v/= 前缀）、^、~、*；不猜测其他范围。 */
+function parseVersionRange(value) {
+    const text = value.trim();
+    if (!text || text === "*")
+        return {};
+    const prefix = text[0];
+    const minimum = parseSemVer(prefix === "^" || prefix === "~" ? text.slice(1) : text);
+    if (!minimum)
+        return undefined;
+    if (prefix !== "^" && prefix !== "~")
+        return { minimum, exact: true };
+    const maximum = prefix === "~"
+        ? { major: minimum.major, minor: minimum.minor + 1, patch: 0 }
+        : minimum.major > 0 ? { major: minimum.major + 1, minor: 0, patch: 0 }
+            : minimum.minor > 0 ? { major: 0, minor: minimum.minor + 1, patch: 0 }
+                : { major: 0, minor: 0, patch: minimum.patch + 1 };
+    return { minimum, maximum };
+}
+function compareVersions(a, b) {
+    const core = a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+    if (core)
+        return core;
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (a.prerelease === undefined)
+        return 1;
+    if (b.prerelease === undefined)
+        return -1;
+    const left = a.prerelease.split(".");
+    const right = b.prerelease.split(".");
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        if (left[i] === undefined)
+            return -1;
+        if (right[i] === undefined)
+            return 1;
+        if (left[i] === right[i])
+            continue;
+        const numericLeft = /^\d+$/.test(left[i]);
+        const numericRight = /^\d+$/.test(right[i]);
+        if (numericLeft && numericRight)
+            return BigInt(left[i]) < BigInt(right[i]) ? -1 : 1;
+        if (numericLeft !== numericRight)
+            return numericLeft ? -1 : 1;
+        return left[i] < right[i] ? -1 : 1;
     }
-    const clean1 = v1.trim().replace(/^[\^~=]/, "");
-    const clean2 = v2.trim().replace(/^[\^~=]/, "");
-    const sem1 = parseSemVer(clean1);
-    const sem2 = parseSemVer(clean2);
-    if (!sem1 || !sem2) {
-        return v1 === v2;
+    return 0;
+}
+function satisfiesRange(version, range) {
+    if (range.exact)
+        return compareVersions(version, range.minimum) === 0;
+    if (range.minimum && compareVersions(version, range.minimum) < 0)
+        return false;
+    if (range.maximum && compareVersions(version, range.maximum) >= 0)
+        return false;
+    // 预发布版本仅在范围下界显式点名同一核心版本的预发布时纳入。
+    if (version.prerelease !== undefined) {
+        const min = range.minimum;
+        return Boolean(min?.prerelease && version.major === min.major && version.minor === min.minor && version.patch === min.patch);
     }
-    if (sem1.major !== sem2.major) {
+    return true;
+}
+export function areVersionsCompatible(v1, v2) {
+    const left = parseVersionRange(v1);
+    const right = parseVersionRange(v2);
+    if (!left || !right)
+        return false;
+    const candidate = !left.minimum ? right.minimum : !right.minimum ? left.minimum
+        : compareVersions(left.minimum, right.minimum) >= 0 ? left.minimum : right.minimum;
+    if (!candidate)
+        return true;
+    if (satisfiesRange(candidate, left) && satisfiesRange(candidate, right))
+        return true;
+    // 两个范围可以在预发布下界之后的稳定版本交汇，但不能改变精确版本。
+    const stable = { major: candidate.major, minor: candidate.minor, patch: candidate.patch };
+    return satisfiesRange(stable, left) && satisfiesRange(stable, right);
+}
+/**
+ * 判定给定的依赖规格是否为不支持的语义化版本范围形态（而非获取描述）。
+ *
+ * 规则：
+ * - 范围操作符开头：^, ~, <, >, =, *；
+ * - 复合范围操作符：|| 或 - 范围；
+ * - X 范围与通配：如 1.x, 1.2.x, 1.*, 1.2.*, v1.x 等；
+ * - 不完整两段或一段版本：如 1, 1.2, v1, v1.2 等；
+ * - 版本三段式开头但未被严格解析器支持的非法形态。
+ */
+function isUnsupportedVersionRange(spec) {
+    const text = spec.trim();
+    if (!text)
         return false;
+    if (/^[~^<>=*]/.test(text))
+        return true;
+    if (/\|\||\s+-\s+/.test(text))
+        return true;
+    if (/^v?\d+\.(?:[xX*]|\d+\.[xX*])(?:$|[-+])/.test(text))
+        return true;
+    if (/^v?\d+(?:\.\d+)?$/.test(text))
+        return true;
+    if (/^v?\d+\.\d+\.\d+/.test(text))
+        return true;
+    return false;
+}
+/** 获取描述不是版本约束；仅真实范围及锁定版本参与版本兼容校验。 */
+function dependencyVersionRequirements(spec, locked) {
+    const requirements = [];
+    const range = spec === undefined ? undefined : parseVersionRange(spec);
+    if (spec !== undefined && range)
+        requirements.push(spec);
+    else if (spec !== undefined && isUnsupportedVersionRange(spec)) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Unsupported Action package version range '${spec}'; supported forms are exact versions, ^, ~ and *`);
     }
-    if (v1.startsWith("~") || v2.startsWith("~")) {
-        if (sem1.minor !== sem2.minor) {
-            return false;
-        }
+    const lockedVersion = locked?.resolved || locked?.version;
+    if (lockedVersion && parseSemVer(lockedVersion))
+        requirements.push(lockedVersion);
+    else if (lockedVersion) {
+        throw new ActionDockError(INVALID_ARGUMENT, `Invalid locked Action package version '${lockedVersion}'`);
     }
-    return true;
+    return requirements;
 }
 /**
  * 版本冲突错误。
@@ -280,6 +374,9 @@ export class PackageGraphBuilder {
      */
     buildFromPackages(nodes, generation) {
         for (const pkg of this.options.packages) {
+            if (nodes.has(pkg.id)) {
+                throw new ActionDockError(PACKAGE_ID_CONFLICT, `Package ID '${pkg.id}' occurs more than once in explicit package graph`);
+            }
             const fields = createPackageNodeFields({
                 id: pkg.id,
                 root: pkg.root,
@@ -322,6 +419,39 @@ export class PackageGraphBuilder {
                 rootNode.isDirect = true;
             }
         }
+        if (this.options.validateDependencies) {
+            for (const node of nodes.values()) {
+                const lockfile = node.root ? loadLockfile(node.root) : null;
+                for (const [depId, spec] of Object.entries(node.manifest.dependencies || {})) {
+                    const dep = nodes.get(depId);
+                    if (!dep) {
+                        throw new ActionDockError(PACKAGE_NOT_FOUND, `Package '${depId}' required by '${node.packageId}' is missing from explicit graph`);
+                    }
+                    for (const requirement of dependencyVersionRequirements(spec)) {
+                        if (!areVersionsCompatible(requirement, dep.version)) {
+                            throw new ActionPackageVersionConflictError(depId, [
+                                { requester: node.packageId, rangeOrVersion: requirement },
+                                { requester: depId, rangeOrVersion: dep.version },
+                            ]);
+                        }
+                    }
+                }
+                // 根锁文件也可能锁定传递依赖，不能只检查直接 dependencies。
+                for (const [depId, locked] of Object.entries(lockfile?.packages || {})) {
+                    const dep = nodes.get(depId);
+                    if (!dep)
+                        continue;
+                    for (const requirement of dependencyVersionRequirements(undefined, locked)) {
+                        if (!areVersionsCompatible(requirement, dep.version)) {
+                            throw new ActionPackageVersionConflictError(depId, [
+                                { requester: node.packageId, rangeOrVersion: requirement },
+                                { requester: depId, rangeOrVersion: dep.version },
+                            ]);
+                        }
+                    }
+                }
+            }
+        }
         linkDirectDependencies(nodes);
         computeTransitiveDependencies(nodes);
         const effectiveRootNode = rootIdentity ? nodes.get(rootIdentity.id) : undefined;
@@ -415,6 +545,13 @@ export class PackageGraphBuilder {
                     // 忽略扫描外部链接包异常
                 }
             }
+            const requesterLocks = new Map([[rootPackageId, lockfile]]);
+            const getRequesterLock = (requester) => {
+                if (!requesterLocks.has(requester)) {
+                    requesterLocks.set(requester, loadLockfile(nodes.get(requester).root));
+                }
+                return requesterLocks.get(requester);
+            };
             const versionRequirements = new Map();
             function recordRequirement(pkgId, requester, rangeOrVersion) {
                 const existing = versionRequirements.get(pkgId) || [];
@@ -429,10 +566,22 @@ export class PackageGraphBuilder {
                 existing.push({ requester, rangeOrVersion });
                 versionRequirements.set(pkgId, existing);
             }
+            const recordDependency = (pkgId, requester, spec) => {
+                const requesterLocked = getRequesterLock(requester)?.packages[pkgId];
+                for (const requirement of dependencyVersionRequirements(spec, requesterLocked)) {
+                    recordRequirement(pkgId, requester, requirement);
+                }
+                const rootLocked = lockfile?.packages[pkgId];
+                if (rootLocked && rootLocked !== requesterLocked) {
+                    for (const requirement of dependencyVersionRequirements(undefined, rootLocked)) {
+                        recordRequirement(pkgId, rootPackageId, requirement);
+                    }
+                }
+            };
             const queue = [];
             for (const [depId, spec] of Object.entries(rootManifest.dependencies || {})) {
                 rootNode.directDependencies.add(depId);
-                recordRequirement(depId, rootPackageId, spec);
+                recordDependency(depId, rootPackageId, spec);
                 queue.push({
                     pkgId: depId,
                     requester: rootPackageId,
@@ -460,7 +609,7 @@ export class PackageGraphBuilder {
                     continue;
                 }
                 let pkgDir = null;
-                const locked = lockfile?.packages?.[item.pkgId];
+                const locked = getRequesterLock(item.requester)?.packages[item.pkgId] || lockfile?.packages[item.pkgId];
                 if (packageRootsRecord?.[item.pkgId]) {
                     pkgDir = packageRootsRecord[item.pkgId];
                 }
@@ -474,7 +623,7 @@ export class PackageGraphBuilder {
                     }
                     candidateNames.push(item.rangeOrSpec);
                     candidateNames.push(item.pkgId);
-                    let cur = absProjectRoot;
+                    let cur = nodes.get(item.requester)?.root || absProjectRoot;
                     while (true) {
                         for (const candName of candidateNames) {
                             const candPath = join(cur, "node_modules", candName);
@@ -506,6 +655,9 @@ export class PackageGraphBuilder {
                     throw new ActionDockError(MANIFEST_READ_FAILED, `Failed to read manifest for '${item.pkgId}': ${err.message}`);
                 }
                 const depManifest = parseJsonWithoutDuplicates(manifestRaw);
+                if (depManifest.id !== item.pkgId) {
+                    throw new ActionDockError(PACKAGE_ID_CONFLICT, `Expected package '${item.pkgId}' at '${pkgDir}', found '${depManifest.id}'`);
+                }
                 const actualDigest = computeManifestDigest(depManifest);
                 if (locked?.manifestDigest && locked.manifestDigest !== actualDigest) {
                     throw new ActionDockError(MANIFEST_DIGEST_MISMATCH, `Manifest digest mismatch for package '${item.pkgId}': expected '${locked.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
@@ -538,15 +690,13 @@ export class PackageGraphBuilder {
                 };
                 nodes.set(item.pkgId, newNode);
                 for (const [subDepId, subSpec] of Object.entries(depManifest.dependencies || {})) {
-                    recordRequirement(subDepId, item.pkgId, subSpec);
-                    if (!nodes.has(subDepId)) {
-                        queue.push({
-                            pkgId: subDepId,
-                            requester: item.pkgId,
-                            rangeOrSpec: subSpec,
-                            isDirect: false,
-                        });
-                    }
+                    recordDependency(subDepId, item.pkgId, subSpec);
+                    queue.push({
+                        pkgId: subDepId,
+                        requester: item.pkgId,
+                        rangeOrSpec: subSpec,
+                        isDirect: false,
+                    });
                 }
             }
             if (scanLinked) {

package/dist/index.d.ts

@@ -5,7 +5,6 @@
  * 平台大对象驱动与解析器工具移至特定子路径导出（./server, ./project, ./registry,
  * ./profile, ./graph, ./package），严格杜绝在根导出泄露内部执行与平台上下文机制。
  */
-export { suppressExperimentalWarnings } from "./utils/warning.js";
 export { ACTIONDOCK_VERSION } from "./version.js";
 export { createActionDock, connectActionDock, } from "./service/factory.js";
 export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, RunReadOptions, StateScopeOptions, } from "./service/types.js";
@@ -23,6 +22,8 @@ export { startActionDockServer, } from "./server/server.js";
 export type { ServerOptions, ServerOptions as ActionDockServerOptions, ActionDockServerInstance, } from "./server/types.js";
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { inspectLocalPackageDirectory, validateLocalSkillPackages, isExplicitPath, } from "./project/skill-dir.js";
 export type { ProjectConfig, } from "./project/types.js";
+export type { LocalSkillDirectory, LocalPackageEntry, } from "./project/skill-dir.js";
 export type { PackageGraph, } from "./catalog/graph.js";
 export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";

package/dist/index.js

@@ -5,7 +5,6 @@
  * 平台大对象驱动与解析器工具移至特定子路径导出（./server, ./project, ./registry,
  * ./profile, ./graph, ./package），严格杜绝在根导出泄露内部执行与平台上下文机制。
  */
-export { suppressExperimentalWarnings } from "./utils/warning.js";
 // 1. 核心版本号单一事实源
 export { ACTIONDOCK_VERSION } from "./version.js";
 // 2. 统一服务门面与聚合契约接口
@@ -20,5 +19,6 @@ export { startActionDockServer, } from "./server/server.js";
 // 6. 核心工程辅助
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export { inspectLocalPackageDirectory, validateLocalSkillPackages, isExplicitPath, } from "./project/skill-dir.js";
 // 8. 统一错误模型与核心标准错误码常量
 export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, PROCESS_FAILED, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, PROJECT_ROOT_NOT_FOUND, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";

package/dist/input/describe.d.ts

@@ -88,11 +88,22 @@ export declare function buildActionDescribePayload(spec: {
  * 扁平输入通用语法速查行列表。
  */
 export declare const ACTION_DESCRIBE_SYNTAX_REFERENCE: readonly string[];
+/**
+ * 格式化 Action 详情的可选配置项。
+ */
+export interface FormatActionDetailOptions {
+    /**
+     * 是否支持显式与声明式正文选择运行选项（普通 CLI 为 true，目录型 Standalone 默认为 false）。
+     * @default true
+     */
+    supportsTextField?: boolean;
+}
 /**
  * 格式化渲染 Action 详情人类可读文本。
  * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。
  *
  * @param input Action 描述载荷或 Action 规范
+ * @param options 可选格式化配置项
  * @returns 格式化后的说明文本
  */
 export declare function formatActionDetail(input: ActionDescribePayload | (Partial<ActionSpec> & {
@@ -109,4 +120,4 @@ export declare function formatActionDetail(input: ActionDescribePayload | (Parti
     uses?: string[];
     entry?: string;
     [key: string]: any;
-}): string;
+}, options?: FormatActionDetailOptions): string;

package/dist/input/describe.js

@@ -1,5 +1,6 @@
 import { buildCliInputAdviceV1 } from "./advice.js";
 import { isForbiddenActionInputPropertyName } from "./flat-predicates.js";
+import { analyzeActionOutputContract } from "./output-contract.js";
 /**
  * 计算 Action 输入建议。
  *
@@ -134,9 +135,10 @@ export const ACTION_DESCRIBE_SYNTAX_REFERENCE = [
  * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。
  *
  * @param input Action 描述载荷或 Action 规范
+ * @param options 可选格式化配置项
  * @returns 格式化后的说明文本
  */
-export function formatActionDetail(input) {
+export function formatActionDetail(input, options) {
     const payload = "inputAdvice" in input && input.inputAdvice
         ? input
         : buildActionDescribePayload(input);
@@ -197,5 +199,57 @@ export function formatActionDetail(input) {
             lines.push(`  - ${issue.path}: ${issue.code}`);
         }
     }
+    const supportsTextField = options?.supportsTextField ?? true;
+    const outputContract = analyzeActionOutputContract({
+        annotations: payload.annotations,
+        outputSchema: payload.outputSchema,
+    });
+    const isAnnotationInvalid = outputContract.diagnostics.some((d) => d.code === "INVALID_ANNOTATION");
+    lines.push("");
+    lines.push("Output Selection:");
+    if (supportsTextField) {
+        if (isAnnotationInvalid) {
+            lines.push(`  Invalid annotation: ${outputContract.errors.join("; ")}`);
+            lines.push("  Default run: Synchronous execution will be rejected before invocation due to invalid annotation");
+            lines.push("  Full result: Pass '--json' to bypass default annotation and receive the complete structured envelope");
+            lines.push("  Explicit text field: Pass '--text-field <field>' to bypass default annotation and select a specific field");
+        }
+        else if (outputContract.declared && outputContract.textField) {
+            lines.push(`  Default text field: ${outputContract.textField}`);
+            if (outputContract.errors.length > 0) {
+                lines.push(`  Contract conflict: ${outputContract.errors.join("; ")}`);
+            }
+            lines.push(`  stdout: Raw text content of '${outputContract.textField}' (synchronous execution only)`);
+            lines.push("  stderr: Remaining fields as JSON metadata, diagnostics, and logs");
+            lines.push("  Full result: Pass '--json' to receive the complete structured envelope");
+            lines.push("  Override: Pass '--text-field <field>' to select another top-level string field");
+        }
+        else {
+            lines.push("  Default: Raw string for string results; formatted JSON for objects and arrays");
+            lines.push("  Full result: Pass '--json' to receive the complete structured envelope");
+            lines.push("  Custom field: Pass '--text-field <field>' to extract a specific top-level string field");
+        }
+    }
+    else {
+        if (isAnnotationInvalid) {
+            lines.push(`  Invalid annotation: ${outputContract.errors.join("; ")} (note: ignored in standalone runtime; standalone extracts 'content', 'text', or 'message', falling back to formatted JSON)`);
+            lines.push("  stdout: Raw string for scalars; extracts 'content', 'text', or 'message' from objects");
+            lines.push("  stderr: Remaining fields as metadata (for extracted fields), diagnostics, and logs");
+            lines.push("  Full result: Pass '--json' to receive the complete structured envelope");
+        }
+        else if (outputContract.declared && outputContract.textField) {
+            lines.push(`  Default text field: ${outputContract.textField} (note: ignored in standalone runtime; standalone extracts 'content', 'text', or 'message', falling back to formatted JSON)`);
+            if (outputContract.errors.length > 0) {
+                lines.push(`  Contract conflict: ${outputContract.errors.join("; ")}`);
+            }
+            lines.push("  stdout: Raw string for scalars; extracts 'content', 'text', or 'message' from objects");
+            lines.push("  stderr: Remaining fields as metadata (for extracted fields), diagnostics, and logs");
+            lines.push("  Full result: Pass '--json' to receive the complete structured envelope");
+        }
+        else {
+            lines.push("  Default: Raw string for scalars; extracts 'content', 'text', or 'message' from objects (with metadata on stderr), falling back to formatted JSON");
+            lines.push("  Full result: Pass '--json' to receive the complete structured envelope");
+        }
+    }
     return lines.join("\n");
 }

package/dist/input/flat-materializer.d.ts

@@ -16,6 +16,30 @@ export type NodeState = (typeof NodeState)[keyof typeof NodeState];
 export interface FlatMaterializerOptions {
     maxMaterializedSizeBytes?: number;
 }
+/**
+ * 断言顶层字符串属性写入不与既有字段结构冲突。
+ *
+ * 作为扁平赋值与 stdin 字段绑定共享的路径冲突判定单一事实源：
+ * - 重复赋值同名属性：DUPLICATE_ASSIGNMENT；
+ * - 既有同名对象容器：LEAF_CONTAINER_CONFLICT；
+ * - 既有同名数组容器：OBJECT_ARRAY_CONFLICT。
+ *
+ * @param target 目标对象（仅检测自有属性，不触及原型链）
+ * @param field 待写入的顶层属性名
+ */
+export declare function assertTopLevelLeafAvailable(target: object, field: string): void;
+/**
+ * 校验物化后的最终入参值：结构合法性与实体化总大小上限。
+ *
+ * 作为扁平赋值与 stdin 字段绑定共享的最终校验单一事实源：
+ * - 结构非法或超深：FLAT_INPUT_LIMIT_EXCEEDED（MAX_MATERIALIZED_JSON_DEPTH / INVALID_JSON_VALUE）；
+ * - 序列化后字节超出 maxMaterializedSizeBytes（默认 10MiB）：
+ *   FLAT_INPUT_LIMIT_EXCEEDED（MAX_MATERIALIZED_BYTES）。
+ *
+ * @param result 待校验的最终入参对象
+ * @param options 物化配置选项（可选 maxMaterializedSizeBytes）
+ */
+export declare function assertMaterializedInputWithinLimits(result: JsonValue, options?: FlatMaterializerOptions): void;
 /**
  * 将扁平赋值表达式列表物化为标准 JSON 值对象。
  *

package/dist/input/flat-materializer.js

@@ -11,6 +11,56 @@ export const NodeState = {
     ARRAY: "ARRAY",
     VALUE: "VALUE",
 };
+/**
+ * 断言顶层字符串属性写入不与既有字段结构冲突。
+ *
+ * 作为扁平赋值与 stdin 字段绑定共享的路径冲突判定单一事实源：
+ * - 重复赋值同名属性：DUPLICATE_ASSIGNMENT；
+ * - 既有同名对象容器：LEAF_CONTAINER_CONFLICT；
+ * - 既有同名数组容器：OBJECT_ARRAY_CONFLICT。
+ *
+ * @param target 目标对象（仅检测自有属性，不触及原型链）
+ * @param field 待写入的顶层属性名
+ */
+export function assertTopLevelLeafAvailable(target, field) {
+    if (!Object.hasOwn(target, field))
+        return;
+    const existing = target[field];
+    if (Array.isArray(existing)) {
+        throw inputPathConflict(`Path conflict at "${field}": expected object but found array`, { path: field, reason: "OBJECT_ARRAY_CONFLICT" });
+    }
+    if (existing !== null && typeof existing === "object") {
+        throw inputPathConflict(`Path conflict at "${field}": cannot assign value to existing container (object)`, { path: field, reason: "LEAF_CONTAINER_CONFLICT" });
+    }
+    throw inputPathConflict(`Duplicate assignment to leaf path "${field}"`, { path: field, reason: "DUPLICATE_ASSIGNMENT" });
+}
+/**
+ * 校验物化后的最终入参值：结构合法性与实体化总大小上限。
+ *
+ * 作为扁平赋值与 stdin 字段绑定共享的最终校验单一事实源：
+ * - 结构非法或超深：FLAT_INPUT_LIMIT_EXCEEDED（MAX_MATERIALIZED_JSON_DEPTH / INVALID_JSON_VALUE）；
+ * - 序列化后字节超出 maxMaterializedSizeBytes（默认 10MiB）：
+ *   FLAT_INPUT_LIMIT_EXCEEDED（MAX_MATERIALIZED_BYTES）。
+ *
+ * @param result 待校验的最终入参对象
+ * @param options 物化配置选项（可选 maxMaterializedSizeBytes）
+ */
+export function assertMaterializedInputWithinLimits(result, options) {
+    const check = validateJsonValue(result);
+    if (!check.valid) {
+        throw flatInputLimitExceeded(`Materialized input validation failed: ${check.reason}`, {
+            reason: check.code === "MAX_JSON_DEPTH"
+                ? "MAX_MATERIALIZED_JSON_DEPTH"
+                : "INVALID_JSON_VALUE",
+        });
+    }
+    const maxMaterializedSizeBytes = options?.maxMaterializedSizeBytes ?? DEFAULT_MAX_MATERIALIZED_SIZE_BYTES;
+    const serialized = JSON.stringify(result);
+    const byteLength = Buffer.byteLength(serialized, "utf8");
+    if (byteLength > maxMaterializedSizeBytes) {
+        throw flatInputLimitExceeded(`Materialized input size (${byteLength} bytes) exceeds limit (${maxMaterializedSizeBytes} bytes)`, { byteLength, maxMaterializedSizeBytes, reason: "MAX_MATERIALIZED_BYTES" });
+    }
+}
 function createNode(pathStr, state = NodeState.UNSET) {
     return {
         state,
@@ -159,19 +209,6 @@ export function materializeFlatInput(assignments, options) {
         }
     }
     const result = materializeNode(root);
-    const check = validateJsonValue(result);
-    if (!check.valid) {
-        throw flatInputLimitExceeded(`Materialized input validation failed: ${check.reason}`, {
-            reason: check.code === "MAX_JSON_DEPTH"
-                ? "MAX_MATERIALIZED_JSON_DEPTH"
-                : "INVALID_JSON_VALUE",
-        });
-    }
-    const maxMaterializedSizeBytes = options?.maxMaterializedSizeBytes ?? DEFAULT_MAX_MATERIALIZED_SIZE_BYTES;
-    const serialized = JSON.stringify(result);
-    const byteLength = Buffer.byteLength(serialized, "utf8");
-    if (byteLength > maxMaterializedSizeBytes) {
-        throw flatInputLimitExceeded(`Materialized input size (${byteLength} bytes) exceeds limit (${maxMaterializedSizeBytes} bytes)`, { byteLength, maxMaterializedSizeBytes, reason: "MAX_MATERIALIZED_BYTES" });
-    }
+    assertMaterializedInputWithinLimits(result, options);
     return result;
 }

package/dist/input/index.d.ts

@@ -10,4 +10,5 @@ export * from "./file-input.js";
 export * from "./stdin-input.js";
 export * from "./input-resolver.js";
 export * from "./advice.js";
+export * from "./output-contract.js";
 export * from "./describe.js";

package/dist/input/index.js

@@ -10,4 +10,5 @@ export * from "./file-input.js";
 export * from "./stdin-input.js";
 export * from "./input-resolver.js";
 export * from "./advice.js";
+export * from "./output-contract.js";
 export * from "./describe.js";

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

@@ -16,6 +16,8 @@ export interface InputResolutionPolicy {
     sanitizeInputErrors?: boolean;
     /** 是否仅允许字节流输入（默认 false） */
     byteStreamOnly?: boolean;
+    /** 原始 stdin 文本模式：保留开头 BOM，UTF-8 编码失败视为读取失败（默认 false，仅作用于 stdinField） */
+    stdinRawText?: boolean;
 }
 /**
  * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串（保持历史接口兼容）。
@@ -30,6 +32,8 @@ export interface ResolveActionInputOptions {
     input?: string;
     inputFile?: string;
     flatArgs?: string[];
+    /** 将 stdin 完整原始文本绑定为指定顶层入参字段的字符串值（与 input / inputFile 互斥，可与 flatArgs 组合） */
+    stdinField?: string;
     stdin?: NodeJS.ReadableStream;
     flatOptions?: FlatParserOptions & FlatMaterializerOptions;
     policy?: InputResolutionPolicy;
@@ -51,11 +55,15 @@ export declare function parseJson(text: string, source: string, policy?: InputRe
  * - 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 对象