zentao-api 0.3.0 → 0.3.2

package/dist/client/index.d.ts

@@ -52,7 +52,16 @@ export declare class ZentaoClient {
      * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
      *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
      */
-    request(path: string, options?: ClientRequestOptions): Promise<unknown>;
+    request(path: string, options: ClientRequestOptions & {
+        responseType: 'response';
+    }): Promise<Response>;
+    request(path: string, options: ClientRequestOptions & {
+        responseType: 'arrayBuffer';
+    }): Promise<ArrayBuffer>;
+    request(path: string, options: ClientRequestOptions & {
+        responseType: 'blob';
+    }): Promise<Blob>;
+    request<T = unknown>(path: string, options?: ClientRequestOptions): Promise<T>;
     /**
      * 发起 `GET` 请求。
      *
@@ -61,7 +70,7 @@ export declare class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    get<T>(path: string): Promise<T>;
+    get<T>(path: string, options?: Omit<ClientRequestOptions, 'method' | 'body' | 'bodyType'>): Promise<T>;
     /**
      * 发起 `POST` 请求，`body` 会被序列化为 JSON。
      *
@@ -71,7 +80,7 @@ export declare class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    post<T>(path: string, body: unknown): Promise<T>;
+    post<T>(path: string, body: unknown, options?: Omit<ClientRequestOptions, 'method'>): Promise<T>;
     /**
      * 发起 `PUT` 请求，`body` 会被序列化为 JSON。
      *
@@ -81,7 +90,7 @@ export declare class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    put<T>(path: string, body: unknown): Promise<T>;
+    put<T>(path: string, body: unknown, options?: Omit<ClientRequestOptions, 'method'>): Promise<T>;
     /**
      * 发起 `DELETE` 请求。
      *
@@ -90,7 +99,7 @@ export declare class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    delete<T>(path: string): Promise<T>;
+    delete<T>(path: string, options?: Omit<ClientRequestOptions, 'method' | 'body' | 'bodyType'>): Promise<T>;
     /**
      * 使用账号密码登录禅道。
      *

package/dist/client/index.js

@@ -15,8 +15,92 @@ function buildUrl(baseUrl, path, query) {
     }
     return url.toString();
 }
-/** 优先解析 JSON；非 JSON 响应保留为原始文本。 */
-async function parseResponse(response) {
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isInstanceOfGlobal(value, name) {
+    const ctor = globalThis[name];
+    return typeof ctor === 'function' && value instanceof ctor;
+}
+function isArrayBufferBody(value) {
+    return value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function appendFormValue(form, key, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            appendFormValue(form, key, item);
+        return;
+    }
+    form.append(key, value === null ? '' : String(value));
+}
+function serializeBody(body, bodyType, headers) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (bodyType === 'form') {
+        const form = body instanceof URLSearchParams ? body : new URLSearchParams();
+        if (!(body instanceof URLSearchParams) && isPlainObject(body)) {
+            for (const [key, value] of Object.entries(body))
+                appendFormValue(form, key, value);
+        }
+        else if (!(body instanceof URLSearchParams)) {
+            throw new ZentaoError('E_INVALID_PARAM', { param: 'body', value: String(body) });
+        }
+        if (!headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/x-www-form-urlencoded;charset=UTF-8');
+        }
+        return form;
+    }
+    if (bodyType === 'raw' ||
+        typeof body === 'string' ||
+        isArrayBufferBody(body) ||
+        isInstanceOfGlobal(body, 'FormData') ||
+        isInstanceOfGlobal(body, 'URLSearchParams') ||
+        isInstanceOfGlobal(body, 'Blob') ||
+        isInstanceOfGlobal(body, 'ReadableStream')) {
+        return body;
+    }
+    if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json');
+    }
+    return JSON.stringify(body);
+}
+function createRequestSignal(timeout, externalSignal) {
+    const controller = new AbortController();
+    const abortFromExternal = () => controller.abort(externalSignal?.reason);
+    const timer = setTimeout(() => controller.abort(), timeout);
+    if (externalSignal?.aborted) {
+        abortFromExternal();
+    }
+    else {
+        externalSignal?.addEventListener('abort', abortFromExternal, { once: true });
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timer);
+            externalSignal?.removeEventListener('abort', abortFromExternal);
+        },
+    };
+}
+/** 按指定策略解析响应；默认优先 JSON，失败后保留原始文本。 */
+async function parseResponse(response, responseType = 'auto') {
+    if (responseType === 'response')
+        return response;
+    if (responseType === 'arrayBuffer')
+        return response.arrayBuffer();
+    if (responseType === 'blob')
+        return response.blob();
+    if (responseType === 'text')
+        return response.text();
+    if (responseType === 'json') {
+        const text = await response.text();
+        return text === '' ? undefined : JSON.parse(text);
+    }
     const text = await response.text();
     if (text === '')
         return undefined;
@@ -56,23 +140,6 @@ export class ZentaoClient {
         this.timeout = options.timeout;
         this.insecure = options.insecure;
     }
-    /**
-     * 发起一次原始 API 请求。
-     *
-     * 选项优先级：本次调用 `options` > 全局选项（{@link getGlobalOptions}） > 客户端构造时默认值。
-     *
-     * 特殊处理：
-     * - 默认 HTTP 方法为 `GET`，`GET` 请求即使提供了 `options.body` 也不会发送，避免被部分代理/浏览器拒绝。
-     * - 非空响应优先按 JSON 解析；解析失败时回落为字符串原文。
-     * - 业务层失败（即响应体 `{ status: "fail" }`）不会抛出，仍按原样返回；只有 HTTP/网络/超时等传输层错误才会抛错。
-     * - `insecure` 仅在 Node.js 下可用，浏览器中传入会抛 `E_INSECURE_BROWSER`。
-     *
-     * @param path - 相对 {@link baseUrl} 的路径，可省略前导 `/`。
-     * @param options - 单次请求选项，参见 {@link ClientRequestOptions}。
-     * @returns 解析后的响应体；当响应为空字符串时返回 `undefined`。
-     * @throws {ZentaoError} 可能抛出 `E_HTTP_ERROR`（非 2xx 状态）、`E_NETWORK_ERROR`（底层 fetch 失败）、
-     *   `E_TIMEOUT`（超过 `timeout`）或 `E_INSECURE_BROWSER`（浏览器中开启了 `insecure`）。
-     */
     async request(path, options = {}) {
         const globals = getGlobalOptions();
         const method = options.method ?? 'GET';
@@ -80,21 +147,19 @@ export class ZentaoClient {
         const insecure = options.insecure ?? globals.insecure ?? this.insecure;
         assertInsecureSupported(insecure);
         const url = buildUrl(this.baseUrl, path, options.query);
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeout);
-        const headers = {};
+        const headers = new Headers(options.headers);
         if (this.token) {
-            headers.Token = this.token;
+            headers.set('Token', this.token);
         }
+        const { signal, cleanup } = createRequestSignal(timeout, options.signal);
         const init = {
             method,
             headers,
-            signal: controller.signal,
+            signal,
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
         if (options.body !== undefined && method !== 'GET') {
-            headers['Content-Type'] = 'application/json';
-            init.body = JSON.stringify(options.body);
+            init.body = serializeBody(options.body, options.bodyType, headers);
         }
         try {
             const response = await fetchWithInsecureTls(insecure, url, init);
@@ -109,7 +174,7 @@ export class ZentaoClient {
                     body: await response.text().catch(() => undefined),
                 });
             }
-            return parseResponse(response);
+            return parseResponse(response, options.responseType);
         }
         catch (error) {
             if (error instanceof ZentaoError)
@@ -120,7 +185,7 @@ export class ZentaoClient {
             throw new ZentaoError('E_NETWORK_ERROR', { message: error.message ?? String(error) }, error);
         }
         finally {
-            clearTimeout(timer);
+            cleanup();
         }
     }
     /**
@@ -131,8 +196,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async get(path) {
-        return this.request(path, { method: 'GET' });
+    async get(path, options = {}) {
+        return this.request(path, { ...options, method: 'GET' });
     }
     /**
      * 发起 `POST` 请求，`body` 会被序列化为 JSON。
@@ -143,8 +208,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async post(path, body) {
-        return this.request(path, { method: 'POST', body });
+    async post(path, body, options = {}) {
+        return this.request(path, { ...options, method: 'POST', body });
     }
     /**
      * 发起 `PUT` 请求，`body` 会被序列化为 JSON。
@@ -155,8 +220,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async put(path, body) {
-        return this.request(path, { method: 'PUT', body });
+    async put(path, body, options = {}) {
+        return this.request(path, { ...options, method: 'PUT', body });
     }
     /**
      * 发起 `DELETE` 请求。
@@ -166,8 +231,8 @@ export class ZentaoClient {
      * @returns 解析后的响应体（强转为 `T`）。
      * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
      */
-    async delete(path) {
-        return this.request(path, { method: 'DELETE' });
+    async delete(path, options = {}) {
+        return this.request(path, { ...options, method: 'DELETE' });
     }
     /**
      * 使用账号密码登录禅道。

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError, type ErrorCode } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, type DefineModulesOptions, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
-export { request } from './request/index.js';
+export { defineModuleActions, defineModules, type DefineModulesOptions, extendModuleAction, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
+export { request, type BuiltinRequestName, type RequestParamsFor, type RequestResultFor, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';
-export type { ApiListResponse, ApiResponse, ClientRequestOptions, DataRecord, DataRecordFilter, DataRecordFilterGroup, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';
+export type { ApiListResponse, ApiResponse, ClientRequestBodyType, ClientRequestOptions, ClientResponseType, DataRecord, DataRecordFilter, DataRecordFilterGroup, GlobalOptions, HttpMethod, ListPagerInfo, LoginResponse, ModuleAction, ModuleActionMethod, ModuleActionName, ModuleActionPagerGetterMap, ModuleActionParam, ModuleActionParamOption, ModuleActionRequestBody, ModuleActionResponse, ModuleActionResultRender, ModuleActionResultRenderType, ModuleActionResultType, ModuleActionType, ModuleDefinition, ModuleName, Pager, ProcessListOptions, ProcessSingleOptions, RequestOptions, ResolvedModuleCommand, ResponseData, ServerConfig, SortExpr, SortFn, ZentaoProfile, ZentaoProfileConfig, ZentaoProfileRecord, ZentaoProfilesStore, ZentaoClientOptions, } from './types/index.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { ZentaoClient } from './client/index.js';
 export { ERRORS, ZentaoError } from './misc/errors.js';
 export { getGlobalOptions, setGlobalOptions } from './misc/global-options.js';
 export { ZENTAO_PROFILES_STORAGE_KEY, addProfile, deleteProfile, getAllProfiles, getProfile, getProfileKey, switchProfile, } from './profiles/index.js';
-export { defineModuleActions, defineModules, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
-export { request } from './request/index.js';
+export { defineModuleActions, defineModules, extendModuleAction, getModuleNames, getModule, getModuleAction, } from './modules/registry.js';
+export { request, } from './request/index.js';
 export { pickFields, pickFieldsSingle, filterData, searchData, sortData, processData, } from './utils/index.js';
 export { BUILD, VERSION } from './version.js';

package/dist/misc/environment.js

@@ -25,7 +25,11 @@ function toResponseHeaders(headers) {
     }
     return result;
 }
-async function toNodeBody(body) {
+function hasHeader(headers, name) {
+    const normalized = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+}
+async function toNodeBody(body, headers) {
     if (body === undefined || body === null)
         return undefined;
     if (typeof body === 'string')
@@ -38,8 +42,25 @@ async function toNodeBody(body) {
         return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
     }
     if (body instanceof Blob) {
+        if (body.type && !hasHeader(headers, 'content-type')) {
+            headers['content-type'] = body.type;
+        }
         return new Uint8Array(await body.arrayBuffer());
     }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const request = new Request('https://zentao-api.local/', { method: 'POST', body });
+        const contentType = request.headers.get('content-type');
+        if (contentType && !hasHeader(headers, 'content-type')) {
+            headers['content-type'] = contentType;
+        }
+        return new Uint8Array(await request.arrayBuffer());
+    }
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+        if (!hasHeader(headers, 'content-type')) {
+            headers['content-type'] = 'application/x-www-form-urlencoded;charset=UTF-8';
+        }
+        return body.toString();
+    }
     return String(body);
 }
 function abortError() {
@@ -60,7 +81,8 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
     const transport = parsed.protocol === 'https:'
         ? await importNodeModule('node:https')
         : await importNodeModule('node:http');
-    const body = await toNodeBody(init.body);
+    const headers = toNodeRequestHeaders(init.headers);
+    const body = await toNodeBody(init.body, headers);
     return new Promise((resolve, reject) => {
         if (init.signal?.aborted) {
             reject(abortError());
@@ -68,7 +90,7 @@ async function nodeFetchWithTlsOptions(url, init, rejectUnauthorized) {
         }
         const request = transport.request(parsed, {
             method: init.method ?? 'GET',
-            headers: toNodeRequestHeaders(init.headers),
+            headers,
             rejectUnauthorized,
         }, (response) => {
             const chunks = [];

package/dist/misc/errors.d.ts

@@ -23,7 +23,7 @@ export declare const ERRORS: {
     readonly E_INVALID_ACTION_DEFINITION: "Invalid module action definition.";
     readonly E_MISSING_PARAM: "Missing required parameter: {param}";
     readonly E_INVALID_PARAM: "Invalid value for parameter {param}: {value}";
-    readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName/methodName\".";
+    readonly E_INVALID_REQUEST_NAME: "Request name must use the form \"moduleName\", \"moduleName/methodName\", or \"moduleName/<objectID>\".";
     readonly E_API_FAILED: "ZenTao API returned failure: {message}";
 };
 /** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */

package/dist/misc/errors.js

@@ -23,7 +23,7 @@ export const ERRORS = {
     E_INVALID_ACTION_DEFINITION: 'Invalid module action definition.',
     E_MISSING_PARAM: 'Missing required parameter: {param}',
     E_INVALID_PARAM: 'Invalid value for parameter {param}: {value}',
-    E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName/methodName".',
+    E_INVALID_REQUEST_NAME: 'Request name must use the form "moduleName", "moduleName/methodName", or "moduleName/<objectID>".',
     E_API_FAILED: 'ZenTao API returned failure: {message}',
 };
 /**

package/dist/modules/define.d.ts

@@ -0,0 +1,63 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+/** {@link defineModules} 的选项。 */
+export interface DefineModulesOptions {
+    /**
+     * 同名模块的写入策略。
+     *
+     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
+     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
+     */
+    replace?: boolean;
+}
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）
+ *   或 `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export declare function extendModuleAction(moduleName: string, actionName: string, action: Partial<ModuleAction> | ((action: ModuleAction) => ModuleAction)): void;
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export declare function resetModuleDefinitions(): void;

package/dist/modules/define.js

@@ -0,0 +1,119 @@
+import { ZentaoError } from '../misc/errors.js';
+import { asArray } from '../utils/index.js';
+import { deepClone, deepMerge, findActionIndex, freezeAction, freezeModule, getModuleMapState, getModulesState, mergeModule, rebuildModuleMap, resetState, validateAction, validateModule, } from './registry-store.js';
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export function defineModules(input, options = {}) {
+    const modules = getModulesState();
+    for (const module of asArray(input)) {
+        validateModule(module);
+        const key = module.name.toLowerCase();
+        const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+        if (index >= 0) {
+            modules[index] = options.replace
+                ? freezeModule(deepClone(module))
+                : mergeModule(modules[index], module);
+        }
+        else {
+            modules.push(freezeModule(deepClone(module)));
+        }
+    }
+    rebuildModuleMap();
+}
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export function defineModuleActions(moduleName, input) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().get(key);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    const actions = module.actions.slice();
+    for (const action of asArray(input)) {
+        validateAction(action);
+        const index = findActionIndex(actions, String(action.name));
+        const frozen = freezeAction(deepClone(action));
+        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
+        if (index >= 0) {
+            actions[index] = frozen;
+        }
+        else {
+            actions.push(frozen);
+        }
+    }
+    const nextModule = freezeModule({ ...module, actions });
+    const modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）
+ *   或 `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export function extendModuleAction(moduleName, actionName, action) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().get(key);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    const actions = module.actions.slice();
+    const actionIndex = findActionIndex(actions, actionName);
+    if (actionIndex < 0) {
+        throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+    }
+    const current = actions[actionIndex];
+    // 函数：以当前动作的深克隆为入参，返回值作为完整动作定义直接取代原定义，不做合并。
+    // 对象：作为补丁与原动作深度合并。
+    const next = typeof action === 'function' ? action(deepClone(current)) : deepMerge(current, action);
+    validateAction(next);
+    actions[actionIndex] = freezeAction(next);
+    const nextModule = freezeModule({ ...module, actions });
+    const modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export function resetModuleDefinitions() {
+    resetState();
+}