@actiondock/core 2.7.0 → 2.9.0

package/dist/runtime/standalone.d.ts

@@ -1,7 +1,7 @@
 import { type ActionDefinition } from "@actiondock/sdk";
-import type { ActionSpec } from "../app/types.js";
+import type { ActionSpec } from "../package/types.js";
 import type { ConfigItemDefinition } from "../project/types.js";
-import type { ActionDockTarget } from "../target/types.js";
+import type { ActionDockService } from "../service/types.js";
 /**
  * 退出状态码常量。
  */
@@ -28,8 +28,8 @@ export interface StandaloneDispatcherOptions {
     version: string;
     /** 描述信息 */
     description?: string;
-    /** 已构造的 ActionDockTarget 门面（若未传入则依据 actions/config 自动创建） */
-    target?: ActionDockTarget;
+    /** 已构造的 ActionDockService 服务（若未传入则依据 actions/config 自动创建） */
+    service?: ActionDockService;
     /** 声明的配置依赖定义（兼容选项） */
     configDefs?: Record<string, ConfigItemDefinition>;
     config?: Record<string, ConfigItemDefinition>;
@@ -56,7 +56,7 @@ export interface StandaloneDispatcherOptions {
  *
  * 职责：
  * 1. 负责轻量参数解析、诊断输出渲染与统一退出码管理。
- * 2. 统一面向 ActionDockTarget 门面调用能力（支持本地 LocalTarget 与 IPC 监督隔离 Target）。
+ * 2. 统一面向 ActionDockService 服务调用能力。
  * 3. 严格遵循 ActionDock 2.0 输出协议约定：结果数据专走 stdout，日志与错误专走 stderr。
  * 4. 独立入口拒绝异步启动语义，显式拦截并返回 STANDALONE_ASYNC_UNSUPPORTED。
  */
@@ -65,7 +65,22 @@ export declare class StandaloneDispatcher {
     constructor(options: StandaloneDispatcherOptions);
     private writeOut;
     private writeErr;
-    private createLocalTarget;
+    /**
+     * 统一错误输出辅助方法。
+     *
+     * JSON 模式向 stdout 输出两空格缩进的标准错误结构；
+     * 纯文本模式向 stderr 输出单行错误消息（默认携带 Error: 前缀）。
+     * 消息文本与退出码由调用方逐字给定，输出字节严格保持不变。
+     *
+     * @param isJson 是否处于 JSON 输出模式
+     * @param code 错误码
+     * @param message JSON 模式错误消息（兼作纯文本默认消息主体）
+     * @param exitCode 调用方应返回的退出状态码
+     * @param options 可选项：textMessage 覆盖纯文本消息全文；details 为 JSON 模式可选结构化详情
+     * @returns 透传 exitCode 供调用方直接返回
+     */
+    private emitError;
+    private createLocalService;
     /**
      * 解析命令行参数并分发执行对应子命令。
      *
@@ -80,9 +95,9 @@ export declare class StandaloneDispatcher {
     private handleConfig;
     private handleState;
     /**
-     * 判定配置读取异常是否为目标层能力缺失（键未配置语义）而非内部故障。
+     * 判定配置读取异常是否为服务能力缺失（键未配置语义）而非内部故障。
      */
-    private isTargetCapabilityError;
+    private isServiceCapabilityError;
     /**
      * 解析携带命名空间前缀的状态键参数：委托 sdk 单一事实源 decodeStateKey。
      *

package/dist/runtime/standalone.js

@@ -1,6 +1,6 @@
 import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../filter/index.js";
-import { createActionDockTarget } from "../target/target.js";
+import { createActionDock } from "../service/factory.js";
 import { STANDALONE_ASYNC_UNSUPPORTED } from "../errors.js";
 import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
 import { validateActionInputValue } from "../json/value-validator.js";
@@ -20,7 +20,7 @@ export const ExitCode = {
  *
  * 职责：
  * 1. 负责轻量参数解析、诊断输出渲染与统一退出码管理。
- * 2. 统一面向 ActionDockTarget 门面调用能力（支持本地 LocalTarget 与 IPC 监督隔离 Target）。
+ * 2. 统一面向 ActionDockService 服务调用能力。
  * 3. 严格遵循 ActionDock 2.0 输出协议约定：结果数据专走 stdout，日志与错误专走 stderr。
  * 4. 独立入口拒绝异步启动语义，显式拦截并返回 STANDALONE_ASYNC_UNSUPPORTED。
  */
@@ -45,18 +45,49 @@ export class StandaloneDispatcher {
             console.error(msg);
         }
     }
-    async createLocalTarget(dataDir, configOverrides = {}) {
-        if (this.options.target) {
-            return { target: this.options.target, ownsTarget: false };
+    /**
+     * 统一错误输出辅助方法。
+     *
+     * JSON 模式向 stdout 输出两空格缩进的标准错误结构；
+     * 纯文本模式向 stderr 输出单行错误消息（默认携带 Error: 前缀）。
+     * 消息文本与退出码由调用方逐字给定，输出字节严格保持不变。
+     *
+     * @param isJson 是否处于 JSON 输出模式
+     * @param code 错误码
+     * @param message JSON 模式错误消息（兼作纯文本默认消息主体）
+     * @param exitCode 调用方应返回的退出状态码
+     * @param options 可选项：textMessage 覆盖纯文本消息全文；details 为 JSON 模式可选结构化详情
+     * @returns 透传 exitCode 供调用方直接返回
+     */
+    emitError(isJson, code, message, exitCode, options) {
+        if (isJson) {
+            const details = options?.details;
+            this.writeOut(JSON.stringify({
+                ok: false,
+                error: {
+                    code,
+                    message,
+                    ...(details !== undefined ? { details } : {}),
+                },
+            }, null, 2));
         }
-        if (this.options.inMemory && this.options._sharedTarget) {
-            return { target: this.options._sharedTarget, ownsTarget: false };
+        else {
+            this.writeErr(options?.textMessage ?? `Error: ${message}`);
+        }
+        return exitCode;
+    }
+    async createLocalService(dataDir, configOverrides = {}) {
+        if (this.options.service) {
+            return { service: this.options.service, ownsService: false };
+        }
+        if (this.options.inMemory && this.options._sharedService) {
+            return { service: this.options._sharedService, ownsService: false };
         }
         // 归一化 Action 集合：单一入口统一三形态输入
         const { actionsMap, actionSpecs } = normalizeActionCollection(this.options.actions);
         // projectConfig.actions 要求 manifest 形态，字段语义兼容，此处显式收敛类型
         const manifestActions = actionSpecs;
-        const appOptions = {
+        const runtimeOptions = {
             projectConfig: {
                 id: this.options.packageId,
                 name: this.options.packageId,
@@ -71,15 +102,14 @@ export class StandaloneDispatcher {
             customHome: this.options.customHome,
             inMemory: this.options.inMemory,
         };
-        const target = await createActionDockTarget({
-            type: "local",
-            appOptions,
+        const service = await createActionDock({
+            runtimeOptions,
         });
         if (this.options.inMemory) {
-            this.options._sharedTarget = target;
-            return { target, ownsTarget: false };
+            this.options._sharedService = service;
+            return { service, ownsService: false };
         }
-        return { target, ownsTarget: true };
+        return { service, ownsService: true };
     }
     /**
      * 解析命令行参数并分发执行对应子命令。
@@ -124,20 +154,9 @@ export class StandaloneDispatcher {
         const subArgs = filteredArgs.slice(1);
         // 2. 独立入口拒绝异步启动语义
         if (controlArgs.includes("--async")) {
-            const isJson = controlArgs.includes("--json");
-            if (isJson) {
-                this.writeOut(JSON.stringify({
-                    ok: false,
-                    error: {
-                        code: STANDALONE_ASYNC_UNSUPPORTED,
-                        message: "Async execution is not supported in standalone single-execution binaries. Use 'ad serve' or remote target.",
-                    },
-                }, null, 2));
-            }
-            else {
-                this.writeErr(`Error [${STANDALONE_ASYNC_UNSUPPORTED}]: Async execution is not supported in standalone single-execution binaries.`);
-            }
-            return ExitCode.FAILURE;
+            return this.emitError(controlArgs.includes("--json"), STANDALONE_ASYNC_UNSUPPORTED, "Async execution is not supported in standalone single-execution binaries. Use 'ad serve' or remote target.", ExitCode.FAILURE, {
+                textMessage: `Error [${STANDALONE_ASYNC_UNSUPPORTED}]: Async execution is not supported in standalone single-execution binaries.`,
+            });
         }
         // 3. 版本与帮助快速处理（无需初始化 Host / Storage）
         if (command === "-v" || command === "-V" || command === "--version" || command === "version") {
@@ -148,35 +167,35 @@ export class StandaloneDispatcher {
             this.printHelp();
             return ExitCode.SUCCESS;
         }
-        let target;
-        let ownsTarget = false;
+        let service;
+        let ownsService = false;
         try {
-            const targetRes = await this.createLocalTarget(dataDir, configOverrides);
-            target = targetRes.target;
-            ownsTarget = targetRes.ownsTarget;
+            const serviceRes = await this.createLocalService(dataDir, configOverrides);
+            service = serviceRes.service;
+            ownsService = serviceRes.ownsService;
         }
         catch (err) {
-            this.writeErr(`Error initializing standalone target: ${err?.message || err}`);
+            this.writeErr(`Error initializing standalone service: ${err?.message || err}`);
             return ExitCode.FAILURE;
         }
         try {
             let code;
             switch (command) {
                 case "list":
-                    code = await this.handleList(target, subArgs);
+                    code = await this.handleList(service, subArgs);
                     break;
                 case "describe":
                 case "show":
-                    code = await this.handleDescribe(target, subArgs);
+                    code = await this.handleDescribe(service, subArgs);
                     break;
                 case "run":
-                    code = await this.handleRun(target, subArgs, actionArgs, control?.signal);
+                    code = await this.handleRun(service, subArgs, actionArgs, control?.signal);
                     break;
                 case "config":
-                    code = await this.handleConfig(target, subArgs);
+                    code = await this.handleConfig(service, subArgs);
                     break;
                 case "state":
-                    code = await this.handleState(target, subArgs);
+                    code = await this.handleState(service, subArgs);
                     break;
                 default:
                     this.writeErr(`Unknown command: '${command}'`);
@@ -190,19 +209,19 @@ export class StandaloneDispatcher {
         }
         catch (err) {
             if (control?.cancellationSource === "sigint" &&
-                (control?.signal?.aborted || err?.name === "AbortError" || err?.message?.includes("SIGINT"))) {
+                (control?.signal?.aborted || err?.name === "AbortError" || err?.code === "SIGINT_INTERRUPTED")) {
                 return ExitCode.SIGINT;
             }
             this.writeErr(`Error: ${err?.message || err}`);
             return ExitCode.FAILURE;
         }
         finally {
-            if (ownsTarget) {
-                await target.close();
+            if (ownsService) {
+                await service.close();
             }
         }
     }
-    async handleList(target, subArgs) {
+    async handleList(service, subArgs) {
         const isJson = subArgs.includes("--json");
         const noFallback = subArgs.includes("--no-fallback");
         let intent;
@@ -224,7 +243,7 @@ export class StandaloneDispatcher {
             }
         }
         const effectiveIntent = intent || (positionalPatterns.length > 0 ? positionalPatterns.join("|") : undefined);
-        const actions = await target.listActions();
+        const actions = await service.discovery.listActions();
         const list = actions.map((a) => ({
             id: a.id,
             description: a.description || "",
@@ -242,42 +261,18 @@ export class StandaloneDispatcher {
         }
         return ExitCode.SUCCESS;
     }
-    async handleDescribe(target, subArgs) {
+    async handleDescribe(service, subArgs) {
         const id = subArgs.find((a) => !a.startsWith("-"));
         const isJson = subArgs.includes("--json");
         if (!id) {
-            if (isJson) {
-                this.writeOut(JSON.stringify({
-                    ok: false,
-                    error: {
-                        code: "INVALID_ARGUMENT",
-                        message: "Action ID is required for describe",
-                    },
-                }, null, 2));
-            }
-            else {
-                this.writeErr("Error: Action ID is required for describe");
-            }
-            return ExitCode.INVALID_ARGUMENT;
+            return this.emitError(isJson, "INVALID_ARGUMENT", "Action ID is required for describe", ExitCode.INVALID_ARGUMENT);
         }
         let action;
         try {
-            action = await target.describeAction(id);
+            action = await service.discovery.describeAction(id);
         }
         catch {
-            if (isJson) {
-                this.writeOut(JSON.stringify({
-                    ok: false,
-                    error: {
-                        code: "INVALID_ARGUMENT",
-                        message: `Action '${id}' not found`,
-                    },
-                }, null, 2));
-            }
-            else {
-                this.writeErr(`Error: Action '${id}' not found`);
-            }
-            return ExitCode.INVALID_ARGUMENT;
+            return this.emitError(isJson, "INVALID_ARGUMENT", `Action '${id}' not found`, ExitCode.INVALID_ARGUMENT);
         }
         const payload = buildActionDescribePayload(action, {
             packageId: this.options.packageId,
@@ -290,23 +285,11 @@ export class StandaloneDispatcher {
         }
         return ExitCode.SUCCESS;
     }
-    async handleRun(target, subArgs, actionArgs, signal) {
+    async handleRun(service, subArgs, actionArgs, signal) {
         const isJson = subArgs.includes("--json");
         const id = subArgs.find((a) => !a.startsWith("-"));
         if (!id) {
-            if (isJson) {
-                this.writeOut(JSON.stringify({
-                    ok: false,
-                    error: {
-                        code: "INVALID_ARGUMENT",
-                        message: "Error: Action ID is required for run",
-                    },
-                }, null, 2));
-            }
-            else {
-                this.writeErr("Error: Action ID is required for run");
-            }
-            return ExitCode.INVALID_ARGUMENT;
+            return this.emitError(isJson, "INVALID_ARGUMENT", "Error: Action ID is required for run", ExitCode.INVALID_ARGUMENT, { textMessage: "Error: Action ID is required for run" });
         }
         let inputStr;
         let inputFile;
@@ -318,19 +301,7 @@ export class StandaloneDispatcher {
                     timeoutMs = parseDuration(subArgs[++i]);
                 }
                 catch (err) {
-                    if (isJson) {
-                        this.writeOut(JSON.stringify({
-                            ok: false,
-                            error: {
-                                code: "INVALID_ARGUMENT",
-                                message: `Invalid timeout format: ${err?.message || err}`,
-                            },
-                        }, null, 2));
-                    }
-                    else {
-                        this.writeErr(`Error: Invalid timeout format: ${err?.message || err}`);
-                    }
-                    return ExitCode.INVALID_ARGUMENT;
+                    return this.emitError(isJson, "INVALID_ARGUMENT", `Invalid timeout format: ${err?.message || err}`, ExitCode.INVALID_ARGUMENT);
                 }
             }
             else if (arg.startsWith("--timeout=")) {
@@ -338,19 +309,7 @@ export class StandaloneDispatcher {
                     timeoutMs = parseDuration(arg.slice(10));
                 }
                 catch (err) {
-                    if (isJson) {
-                        this.writeOut(JSON.stringify({
-                            ok: false,
-                            error: {
-                                code: "INVALID_ARGUMENT",
-                                message: `Invalid timeout format: ${err?.message || err}`,
-                            },
-                        }, null, 2));
-                    }
-                    else {
-                        this.writeErr(`Error: Invalid timeout format: ${err?.message || err}`);
-                    }
-                    return ExitCode.INVALID_ARGUMENT;
+                    return this.emitError(isJson, "INVALID_ARGUMENT", `Invalid timeout format: ${err?.message || err}`, ExitCode.INVALID_ARGUMENT);
                 }
             }
             else if (arg === "--input" && i + 1 < subArgs.length) {
@@ -380,22 +339,11 @@ export class StandaloneDispatcher {
             }
         }
         catch (err) {
-            if (isJson) {
-                this.writeOut(JSON.stringify({
-                    ok: false,
-                    error: {
-                        code: err?.code || "INVALID_ARGUMENT",
-                        message: err?.message || String(err),
-                        ...(err?.details !== undefined ? { details: err.details } : {}),
-                    },
-                }, null, 2));
-            }
-            else {
-                this.writeErr(`Error: ${err?.message || String(err)}`);
-            }
-            return ExitCode.INVALID_ARGUMENT;
+            return this.emitError(isJson, err?.code || "INVALID_ARGUMENT", err?.message || String(err), ExitCode.INVALID_ARGUMENT, {
+                details: err?.details,
+            });
         }
-        const result = await target.runAction(id, input, {
+        const result = await service.execution.run(id, input, {
             signal,
             timeoutMs,
         });
@@ -484,10 +432,14 @@ export class StandaloneDispatcher {
         }
         return result.ok ? ExitCode.SUCCESS : ExitCode.FAILURE;
     }
-    async handleConfig(target, subArgs) {
+    async handleConfig(service, subArgs) {
         const sub = subArgs[0] || "list";
+        if (!service.management) {
+            this.writeErr("Error: management port is not enabled on this service");
+            return ExitCode.FAILURE;
+        }
         if (sub === "list") {
-            const views = await target.listConfig(this.options.packageId);
+            const views = await service.management.config.list(this.options.packageId);
             const dict = {};
             for (const v of views) {
                 if (v.configured && v.value !== undefined) {
@@ -504,13 +456,13 @@ export class StandaloneDispatcher {
                 return ExitCode.INVALID_ARGUMENT;
             }
             try {
-                const item = await target.getConfig(this.options.packageId, key);
+                const item = await service.management.config.get(this.options.packageId, key);
                 this.writeOut(item.configured ? JSON.stringify(item.value) : "undefined");
                 return ExitCode.SUCCESS;
             }
             catch (err) {
-                // 目标层能力缺失（如远端未开启管理接口）视为键未配置，输出 undefined
-                if (this.isTargetCapabilityError(err)) {
+                // 服务能力缺失（如远端未开启管理接口）视为键未配置，输出 undefined
+                if (this.isServiceCapabilityError(err)) {
                     this.writeOut("undefined");
                     return ExitCode.SUCCESS;
                 }
@@ -533,7 +485,7 @@ export class StandaloneDispatcher {
             catch {
                 parsed = rawVal;
             }
-            await target.setConfig(this.options.packageId, key, parsed);
+            await service.management.config.set(this.options.packageId, key, parsed);
             this.writeOut(`Config '${key}' updated`);
             return ExitCode.SUCCESS;
         }
@@ -543,18 +495,22 @@ export class StandaloneDispatcher {
                 this.writeErr("Error: config key required");
                 return ExitCode.INVALID_ARGUMENT;
             }
-            await target.deleteConfig(this.options.packageId, key);
+            await service.management.config.delete(this.options.packageId, key);
             this.writeOut(`Config '${key}' deleted`);
             return ExitCode.SUCCESS;
         }
         this.writeErr(`Unknown config subcommand: '${sub}'`);
         return ExitCode.INVALID_ARGUMENT;
     }
-    async handleState(target, subArgs) {
+    async handleState(service, subArgs) {
         const sub = subArgs[0] || "list";
         let namespace;
         let isAll = false;
         let isJson = false;
+        if (!service.management) {
+            this.writeErr("Error: management port is not enabled on this service");
+            return ExitCode.FAILURE;
+        }
         for (let i = 1; i < subArgs.length; i++) {
             if ((subArgs[i] === "-n" || subArgs[i] === "--namespace") && i + 1 < subArgs.length) {
                 namespace = subArgs[++i];
@@ -571,7 +527,7 @@ export class StandaloneDispatcher {
         }
         if (sub === "list") {
             const prefix = subArgs[1] && !subArgs[1].startsWith("-") ? subArgs[1] : "";
-            const keys = await target.listStateKeys(this.options.packageId, "", {
+            const keys = await service.management.state.list(this.options.packageId, "", {
                 namespace,
                 prefix: prefix || undefined,
                 all: isAll,
@@ -592,7 +548,7 @@ export class StandaloneDispatcher {
                 ns = decoded.namespace || undefined;
                 actualKey = decoded.key;
             }
-            const val = await target.getState(this.options.packageId, "", actualKey, { namespace: ns });
+            const val = await service.management.state.get(this.options.packageId, "", actualKey, { namespace: ns });
             if (isJson) {
                 this.writeOut(JSON.stringify({ key, value: val }, null, 2));
             }
@@ -631,7 +587,7 @@ export class StandaloneDispatcher {
                     ttl = parseInt(subArgs[i].slice(6), 10);
                 }
             }
-            await target.setState(this.options.packageId, "", actualKey, parsed, { namespace: ns, ttl });
+            await service.management.state.set(this.options.packageId, "", actualKey, parsed, { namespace: ns, ttl });
             const displayKey = ns ? `${ns}:${actualKey}` : actualKey;
             this.writeOut(`State '${displayKey}' updated`);
             return ExitCode.SUCCESS;
@@ -642,7 +598,7 @@ export class StandaloneDispatcher {
                 this.writeErr("Error: state key required");
                 return ExitCode.INVALID_ARGUMENT;
             }
-            const deleted = await target.deleteState(this.options.packageId, "", key, { namespace });
+            const deleted = await service.management.state.delete(this.options.packageId, "", key, { namespace });
             if (deleted) {
                 this.writeOut(`State '${key}' deleted`);
                 return ExitCode.SUCCESS;
@@ -652,7 +608,7 @@ export class StandaloneDispatcher {
         }
         if (sub === "clear" || sub === "clean") {
             const prefix = subArgs[1] && !subArgs[1].startsWith("-") ? subArgs[1] : "";
-            const count = await target.clearState(this.options.packageId, "", {
+            const count = await service.management.state.clear(this.options.packageId, "", {
                 namespace,
                 all: isAll,
                 prefix: prefix || undefined,
@@ -664,15 +620,12 @@ export class StandaloneDispatcher {
         return ExitCode.INVALID_ARGUMENT;
     }
     /**
-     * 判定配置读取异常是否为目标层能力缺失（键未配置语义）而非内部故障。
+     * 判定配置读取异常是否为服务能力缺失（键未配置语义）而非内部故障。
      */
-    isTargetCapabilityError(err) {
+    isServiceCapabilityError(err) {
         const code = String(err?.code || "");
-        const msg = String(err?.message || "");
-        return (code === "TARGET_CAPABILITY_UNAVAILABLE" ||
-            code === "CAPABILITY_UNAVAILABLE" ||
-            msg.includes("TARGET_CAPABILITY_UNAVAILABLE") ||
-            msg.includes("Management APIs are not enabled"));
+        return (code === "CAPABILITY_UNAVAILABLE" ||
+            code === "TARGET_CAPABILITY_UNAVAILABLE");
     }
     /**
      * 解析携带命名空间前缀的状态键参数：委托 sdk 单一事实源 decodeStateKey。

package/dist/server/body.d.ts

@@ -1,3 +1,4 @@
+import { ActionDockError } from "../errors.js";
 /**
  * 默认单次 HTTP 请求体最大字节上限（1 MiB）。
  */
@@ -5,15 +6,13 @@ export declare const DEFAULT_MAX_BODY_BYTES: number;
 /**
  * 请求体超出最大允许体积时抛出的异常（对应 HTTP 413 Payload Too Large）。
  */
-export declare class RequestTooLargeError extends Error {
-    code: string;
+export declare class RequestTooLargeError extends ActionDockError {
     constructor(message?: string);
 }
 /**
  * 请求体非合法 JSON 格式时抛出的异常（对应 HTTP 400 Bad Request）。
  */
-export declare class InvalidJsonError extends Error {
-    code: string;
+export declare class InvalidJsonError extends ActionDockError {
     constructor(message?: string);
 }
 /**
@@ -24,12 +23,21 @@ export interface ReadJsonBodyOptions {
     maxBytes?: number;
 }
 /**
- * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ * 流式安全地读取 HTTP 请求体为原始字节数组（有界读取单一事实源）。
  *
  * 防护机制：
- * 1. 快速拒绝（Fast-path）：若请求头中存在 `Content-Length` 且超过 `maxBytes`，立即抛出 RequestTooLargeError，不进行内存分配。
- * 2. 流式计数器（Chunk Streaming）：在读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
- * 3. 安全解码：处理空请求体与 UTF-8 字符集解码。
+ * 1. 快速拒绝（Fast-path）：若请求头中存在 Content-Length 且超过 maxBytes，立即抛出 RequestTooLargeError，不进行内存分配。
+ * 2. 流式计数器（Chunk Streaming）：读取 ReadableStream 过程中实时累计字节数，中途超出上限即刻截断并释放流锁，防止大文件 DoS 与内存耗尽（OOM）。
+ *
+ * @param req 传入的 Request 对象
+ * @param options 读取配置选项
+ * @returns 原始字节数组（空请求体返回空数组）
+ * @throws {RequestTooLargeError} 若请求体体积超限
+ */
+export declare function readBodyWithLimit(req: Request, options?: ReadJsonBodyOptions): Promise<Uint8Array>;
+/**
+ * 流式安全地读取 HTTP 请求体并解析为 JSON 对象。
+ * 防护机制见 readBodyWithLimit；此外处理空请求体与 UTF-8 字符集解码。
  *
  * @param req 传入的 Request 对象
  * @param options 读取配置选项