zentao-api 0.6.6 → 0.6.8

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import type { ClientRequestOptions, ZentaoClientOptions } from '../types/index.js';
+import type { ClientRequestOptions, FromProfileOptions, GetZentaoConfigOptions, ServerConfig, ZentaoClientOptions } from '../types/index.js';
 /**
  * 禅道 API 客户端，封装一次次原始 HTTP 调用。
  *
@@ -20,6 +20,10 @@ export declare class ZentaoClient {
     private token?;
     private readonly timeout?;
     private readonly insecure?;
+    private profileKey?;
+    private serverConfig?;
+    private serverConfigFetchedAt?;
+    private configRequest?;
     /**
      * 使用完整配置创建客户端。
      *
@@ -65,6 +69,35 @@ export declare class ZentaoClient {
         responseType: 'blob';
     }): Promise<Blob>;
     request<T = unknown>(path: string, options?: ClientRequestOptions): Promise<T>;
+    /**
+     * 使用完整 URL 发起请求，复用 API 与站点配置的传输层。
+     *
+     * @param url - 完整请求 URL，包含所需的查询参数。
+     * @param options - 单次请求选项；其中 `query` 需由调用方预先拼入 `url`。
+     * @param token - 显式注入的 Token；省略时不自动使用实例保存的 Token。
+     * @param fetchOptions - 原生 fetch 的缓存与凭据选项。
+     * @returns 按 `options.responseType` 解析的响应体，默认优先 JSON，失败后返回文本。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    fetch(url: string, options: ClientRequestOptions, token?: string, fetchOptions?: Pick<RequestInit, 'cache' | 'credentials'>): Promise<unknown>;
+    /**
+     * 匿名获取禅道站点 `/?mode=getconfig` 配置，只需站点地址，无需登录或 profile。
+     *
+     * 不发送 API Token，浏览器请求显式省略 Cookie 等凭据，不受 API Token 过期影响。
+     *
+     * 默认复用不超过 24 小时的缓存；缺失、过期或时间异常时重新获取。
+     * `forceRefresh: true` 忽略缓存。同一客户端的并发刷新共用首次调用的传输选项；
+     * 后加入的调用仍可通过自己的 signal 取消等待。
+     * 成功后更新实例缓存；启用 `persistProfiles` 且绑定了 profile 时仅更新其配置和获取时间。
+     * 返回独立副本，修改返回值不会改变缓存。此方法不会忽略配置获取错误。
+     *
+     * @param options - 缓存、超时、TLS 与取消选项。
+     * @returns 服务器配置。
+     * @throws {ZentaoError} 传输错误、`E_INVALID_ZENTAO_CONFIG`、`E_INVALID_ZENTAO_VERSION` 或 profile 存储错误。
+     */
+    getZentaoConfig(options?: GetZentaoConfigOptions): Promise<ServerConfig>;
+    private loadZentaoConfig;
+    private waitForConfig;
     /**
      * 发起 `GET` 请求。
      *
@@ -106,10 +139,14 @@ export declare class ZentaoClient {
     /**
      * 使用账号密码登录禅道。
      *
-     * 成功后会把返回的 Token 写入当前客户端实例（后续请求自动带上 `Token` 头）；
+     * 验证成功后强制获取一次站点配置，再把返回的 Token 写入当前客户端实例；
+     * 配置获取失败默认阻断登录，只有全局 `skipVersionCheckOnConfigError` 可允许继续。
+     * 全局 `version` 不跳过登录时的配置获取。
      * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
      * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
      * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     * 重新登录同一账号时保留已有自定义字段，以及未被显式覆盖的客户端偏好。
+     * 保存的 `timeout` / `insecure` 与请求一致：全局显式值优先于实例默认值。
      *
      * @param account - 禅道用户账号。
      * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
@@ -140,13 +177,16 @@ export declare class ZentaoClient {
     /**
      * 根据本地持久化 profile 创建客户端。
      *
-     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 默认调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
      * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     * `activate: false` 时只读存储，不切换账号、不更新时间，支持可读但不可写的存储。
+     * 两种模式均不替换全局客户端；后续配置刷新是否写回仍由全局 `persistProfiles` 控制。
      *
      * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @param options - 恢复选项；默认保持切换当前 profile 的行为。
      * @returns 用 profile 还原后的客户端实例。
      * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
-     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     *   `E_PROFILE_STORAGE_INVALID`（存储内容不合法）、`E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
      */
-    static fromProfile(profileKey?: string): Promise<ZentaoClient>;
+    static fromProfile(profileKey?: string, options?: FromProfileOptions): Promise<ZentaoClient>;
 }

package/dist/client/index.js

@@ -1,9 +1,14 @@
-import { ZentaoError } from '../misc/errors.js';
+import { isZentaoConfigFetchError, ZentaoError } from '../misc/errors.js';
+import { parseZentaoVersion } from '../misc/zentao-version.js';
 import { assertInsecureSupported, fetchWithInsecureTls } from '../misc/environment.js';
 import { getGlobalOptions, setGlobalOptions } from '../misc/global-options.js';
-import { addProfile, switchProfile } from '../profiles/index.js';
+import { getProfileOrThrow, saveLoginProfile, switchProfile, updateProfileServerConfig } from '../profiles/index.js';
 import { isRecord, normalizeSiteUrl } from '../utils/index.js';
 const DEFAULT_TIMEOUT = 10000;
+const CONFIG_MAX_AGE = 24 * 60 * 60 * 1000;
+function isServerConfig(value) {
+    return isRecord(value) && typeof value.version === 'string' && value.version.trim().length > 0;
+}
 function appendQueryValue(search, key, value) {
     if (value === undefined)
         return;
@@ -298,6 +303,10 @@ export class ZentaoClient {
     token;
     timeout;
     insecure;
+    profileKey;
+    serverConfig;
+    serverConfigFetchedAt;
+    configRequest;
     constructor(input) {
         const options = typeof input === 'string' ? { baseUrl: input } : input;
         this.siteUrl = normalizeSiteUrl(options.baseUrl);
@@ -307,20 +316,33 @@ export class ZentaoClient {
         this.insecure = options.insecure;
     }
     async request(path, options = {}) {
+        return this.fetch(buildUrl(this.baseUrl, path, options.query), options, this.token);
+    }
+    /**
+     * 使用完整 URL 发起请求，复用 API 与站点配置的传输层。
+     *
+     * @param url - 完整请求 URL，包含所需的查询参数。
+     * @param options - 单次请求选项；其中 `query` 需由调用方预先拼入 `url`。
+     * @param token - 显式注入的 Token；省略时不自动使用实例保存的 Token。
+     * @param fetchOptions - 原生 fetch 的缓存与凭据选项。
+     * @returns 按 `options.responseType` 解析的响应体，默认优先 JSON，失败后返回文本。
+     * @throws {ZentaoError} 传输层失败时抛出，详见 {@link ZentaoClient.request}。
+     */
+    async fetch(url, options, token, fetchOptions = {}) {
         const globals = getGlobalOptions();
         const method = options.method ?? 'GET';
         const timeout = options.timeout ?? globals.timeout ?? this.timeout ?? DEFAULT_TIMEOUT;
         const insecure = options.insecure ?? globals.insecure ?? this.insecure;
         assertInsecureSupported(insecure);
-        const url = buildUrl(this.baseUrl, path, options.query);
         const headers = new Headers(options.headers);
-        if (this.token) {
-            headers.set('Token', this.token);
+        if (token) {
+            headers.set('Token', token);
         }
         const init = {
             method,
             headers,
             redirect: 'manual',
+            ...fetchOptions,
         };
         // GET 请求不携带 body，避免浏览器和部分代理拒绝请求。
         if (options.body !== undefined && method !== 'GET') {
@@ -365,6 +387,75 @@ export class ZentaoClient {
                 cleanup();
         }
     }
+    /**
+     * 匿名获取禅道站点 `/?mode=getconfig` 配置，只需站点地址，无需登录或 profile。
+     *
+     * 不发送 API Token，浏览器请求显式省略 Cookie 等凭据，不受 API Token 过期影响。
+     *
+     * 默认复用不超过 24 小时的缓存；缺失、过期或时间异常时重新获取。
+     * `forceRefresh: true` 忽略缓存。同一客户端的并发刷新共用首次调用的传输选项；
+     * 后加入的调用仍可通过自己的 signal 取消等待。
+     * 成功后更新实例缓存；启用 `persistProfiles` 且绑定了 profile 时仅更新其配置和获取时间。
+     * 返回独立副本，修改返回值不会改变缓存。此方法不会忽略配置获取错误。
+     *
+     * @param options - 缓存、超时、TLS 与取消选项。
+     * @returns 服务器配置。
+     * @throws {ZentaoError} 传输错误、`E_INVALID_ZENTAO_CONFIG`、`E_INVALID_ZENTAO_VERSION` 或 profile 存储错误。
+     */
+    async getZentaoConfig(options = {}) {
+        const config = await this.loadZentaoConfig(options, getGlobalOptions().persistProfiles ? this.profileKey : undefined);
+        return structuredClone(config);
+    }
+    async loadZentaoConfig(options, profileKey) {
+        if (options.signal?.aborted)
+            throw new ZentaoError('E_ABORTED');
+        // 刷新进行中时等待其结果，避免同一批调用混用旧缓存和新配置。
+        if (this.configRequest)
+            return this.waitForConfig(this.configRequest, options.signal);
+        const fetchedAt = typeof this.serverConfigFetchedAt === 'string' ? Date.parse(this.serverConfigFetchedAt) : NaN;
+        const age = Date.now() - fetchedAt;
+        if (!options.forceRefresh && isServerConfig(this.serverConfig) && age >= 0 && age <= CONFIG_MAX_AGE) {
+            parseZentaoVersion(this.serverConfig.version);
+            return this.serverConfig;
+        }
+        const pending = this.fetch(buildUrl(this.siteUrl, '/', { mode: 'getconfig' }), {
+            method: 'GET', timeout: options.timeout, insecure: options.insecure, signal: options.signal,
+        }, undefined, { cache: 'no-store', credentials: 'omit' }).then(async (config) => {
+            if (!isServerConfig(config))
+                throw new ZentaoError('E_INVALID_ZENTAO_CONFIG');
+            parseZentaoVersion(config.version);
+            const timestamp = new Date().toISOString();
+            if (profileKey)
+                await updateProfileServerConfig(profileKey, config, timestamp);
+            this.serverConfig = config;
+            this.serverConfigFetchedAt = timestamp;
+            return config;
+        });
+        this.configRequest = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            this.configRequest = undefined;
+        }
+    }
+    async waitForConfig(pending, signal) {
+        if (!signal)
+            return pending;
+        let onAbort;
+        const aborted = new Promise((_, reject) => {
+            onAbort = () => reject(new ZentaoError('E_ABORTED'));
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        });
+        try {
+            return await Promise.race([pending, aborted]);
+        }
+        finally {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
     /**
      * 发起 `GET` 请求。
      *
@@ -414,10 +505,14 @@ export class ZentaoClient {
     /**
      * 使用账号密码登录禅道。
      *
-     * 成功后会把返回的 Token 写入当前客户端实例（后续请求自动带上 `Token` 头）；
+     * 验证成功后强制获取一次站点配置，再把返回的 Token 写入当前客户端实例；
+     * 配置获取失败默认阻断登录，只有全局 `skipVersionCheckOnConfigError` 可允许继续。
+     * 全局 `version` 不跳过登录时的配置获取。
      * 当全局 `persistProfiles` 为真时，会同时把账号、Token、用户信息、服务端配置和
      * 客户端偏好（仅在显式设置过 `timeout` / `insecure` 时）持久化为本地 profile，
      * 并切换为当前 profile，方便下次通过 {@link ZentaoClient.fromProfile} 直接登录态恢复。
+     * 重新登录同一账号时保留已有自定义字段，以及未被显式覆盖的客户端偏好。
+     * 保存的 `timeout` / `insecure` 与请求一致：全局显式值优先于实例默认值。
      *
      * @param account - 禅道用户账号。
      * @param password - 禅道用户密码（明文，仅在传输层 TLS 内使用）。
@@ -430,25 +525,38 @@ export class ZentaoClient {
         if (response.status !== 'success' || !response.token) {
             throw new ZentaoError('E_LOGIN_FAILED');
         }
-        this.token = response.token;
         const globals = getGlobalOptions();
+        let serverConfig;
+        try {
+            // 共用 getZentaoConfig 的获取流程，但登录确认前不能刷新之前绑定的账号。
+            serverConfig = await this.loadZentaoConfig({ forceRefresh: true });
+        }
+        catch (error) {
+            if (!globals.skipVersionCheckOnConfigError || !isZentaoConfigFetchError(error))
+                throw error;
+        }
+        let profileKey;
         if (globals.persistProfiles) {
             const config = {};
-            const timeout = this.timeout ?? globals.timeout;
-            const insecure = this.insecure ?? globals.insecure;
+            const timeout = globals.timeout ?? this.timeout;
+            const insecure = globals.insecure ?? this.insecure;
             if (timeout !== undefined)
                 config.timeout = timeout;
             if (insecure !== undefined)
                 config.insecure = insecure;
-            await addProfile({
+            const profile = await saveLoginProfile({
                 server: this.siteUrl,
                 account,
                 token: response.token,
                 user: isRecord(response.user) ? response.user : undefined,
-                serverConfig: isRecord(response.serverConfig) ? response.serverConfig : undefined,
+                serverConfig: serverConfig ? structuredClone(serverConfig) : undefined,
+                serverConfigFetchedAt: serverConfig ? this.serverConfigFetchedAt : undefined,
                 config: Object.keys(config).length > 0 ? config : undefined,
             });
+            profileKey = profile.key;
         }
+        this.token = response.token;
+        this.profileKey = profileKey;
         return response.token;
     }
     /**
@@ -479,23 +587,28 @@ export class ZentaoClient {
     /**
      * 根据本地持久化 profile 创建客户端。
      *
-     * 实际会调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
+     * 默认调用 {@link switchProfile}：若 `profileKey` 存在则刷新其 `lastUsedTime` 并设为当前 profile；
      * 不传 `profileKey` 时使用当前 profile。Profile 中保存的 `timeout` / `insecure` 偏好也会被带回到客户端实例。
+     * `activate: false` 时只读存储，不切换账号、不更新时间，支持可读但不可写的存储。
+     * 两种模式均不替换全局客户端；后续配置刷新是否写回仍由全局 `persistProfiles` 控制。
      *
      * @param profileKey - 可选的 profile key，格式为 `account@server`；不传时使用当前 profile。
+     * @param options - 恢复选项；默认保持切换当前 profile 的行为。
      * @returns 用 profile 还原后的客户端实例。
      * @throws {ZentaoError} `E_NO_PROFILE`（无任何 profile 且未传 key）、`E_PROFILE_NOT_FOUND`（指定 key 不存在）、
-     *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
+     *   `E_PROFILE_STORAGE_INVALID`（存储内容不合法）、`E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问持久化存储）。
      */
-    static async fromProfile(profileKey) {
-        // switchProfile 会在内部读取存储、校验 key 并刷新 lastUsedTime 后写回，
-        // 若 key 不存在会抛出 E_PROFILE_NOT_FOUND；不传 key 时由 switchCurrentProfile 处理。
-        const activeProfile = await switchProfile(profileKey);
-        return new ZentaoClient({
+    static async fromProfile(profileKey, options = {}) {
+        const activeProfile = options.activate === false ? await getProfileOrThrow(profileKey) : await switchProfile(profileKey);
+        const client = new ZentaoClient({
             baseUrl: activeProfile.server,
             token: activeProfile.token,
             timeout: typeof activeProfile.config?.timeout === 'number' ? activeProfile.config.timeout : undefined,
             insecure: typeof activeProfile.config?.insecure === 'boolean' ? activeProfile.config.insecure : undefined,
         });
+        client.profileKey = activeProfile.key;
+        client.serverConfig = activeProfile.serverConfig;
+        client.serverConfigFetchedAt = activeProfile.serverConfigFetchedAt;
+        return client;
     }
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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, type ExportRegistryOptions, type ExportedModuleAction, type ExportedModuleDefinition, exportRegistry, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
+export { defineModuleActions, defineModules, type DefineModulesOptions, type ExportRegistryOptions, type ExportedModuleAction, type ExportedModuleDefinition, exportRegistry, extendModuleAction, getModuleNames, isModuleName, getModule, getModuleAction, getModuleActionParams, getObjectProps, } 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';

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, exportRegistry, extendModuleAction, getModuleNames, getModule, getModuleAction, getModuleActionParams, getObjectProps, } from './modules/registry.js';
+export { defineModuleActions, defineModules, exportRegistry, extendModuleAction, getModuleNames, isModuleName, getModule, getModuleAction, getModuleActionParams, getObjectProps, } 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/errors.d.ts

@@ -13,10 +13,13 @@ export declare const ERRORS: {
     readonly E_ABORTED: "Request was aborted.";
     readonly E_INSECURE_BROWSER: "The insecure option is only supported in Node.js runtimes.";
     readonly E_LOGIN_FAILED: "ZenTao login failed.";
+    readonly E_INVALID_ZENTAO_CONFIG: "ZenTao configuration must be an object with a non-empty version.";
+    readonly E_INVALID_ZENTAO_VERSION: "Invalid ZenTao version: {version}";
+    readonly E_UNSUPPORTED_ZENTAO_VERSION: "Action {action} does not support ZenTao {version}; minimum versions: {minVersion}";
     readonly E_INVALID_PROFILE: "Invalid ZenTao profile.";
     readonly E_NO_PROFILE: "No ZenTao profile is configured.";
     readonly E_PROFILE_NOT_FOUND: "ZenTao profile not found: {profileKey}";
-    readonly E_PROFILE_STORAGE_INVALID: "ZenTao profile storage is not valid JSON.";
+    readonly E_PROFILE_STORAGE_INVALID: "ZenTao profile storage must be a JSON object with a profiles array and an optional currentProfile string.";
     readonly E_PROFILE_STORAGE_UNAVAILABLE: "ZenTao profile storage is unavailable in this runtime.";
     readonly E_INVALID_MODULE: "Unknown module: {module}";
     readonly E_INVALID_ACTION: "Unknown action: {module}-{action}";
@@ -36,6 +39,8 @@ export declare const ERRORS: {
 };
 /** SDK 已知错误码，对应 {@link ERRORS} 的 key。 */
 export type ErrorCode = keyof typeof ERRORS;
+/** 仅配置获取失败可选择跳过；取消、版本错误和持久化错误仍须抛出。 @internal */
+export declare function isZentaoConfigFetchError(error: unknown): boolean;
 /**
  * SDK 统一错误类型。
  *

package/dist/misc/errors.js

@@ -13,10 +13,13 @@ export const ERRORS = {
     E_ABORTED: 'Request was aborted.',
     E_INSECURE_BROWSER: 'The insecure option is only supported in Node.js runtimes.',
     E_LOGIN_FAILED: 'ZenTao login failed.',
+    E_INVALID_ZENTAO_CONFIG: 'ZenTao configuration must be an object with a non-empty version.',
+    E_INVALID_ZENTAO_VERSION: 'Invalid ZenTao version: {version}',
+    E_UNSUPPORTED_ZENTAO_VERSION: 'Action {action} does not support ZenTao {version}; minimum versions: {minVersion}',
     E_INVALID_PROFILE: 'Invalid ZenTao profile.',
     E_NO_PROFILE: 'No ZenTao profile is configured.',
     E_PROFILE_NOT_FOUND: 'ZenTao profile not found: {profileKey}',
-    E_PROFILE_STORAGE_INVALID: 'ZenTao profile storage is not valid JSON.',
+    E_PROFILE_STORAGE_INVALID: 'ZenTao profile storage must be a JSON object with a profiles array and an optional currentProfile string.',
     E_PROFILE_STORAGE_UNAVAILABLE: 'ZenTao profile storage is unavailable in this runtime.',
     E_INVALID_MODULE: 'Unknown module: {module}',
     E_INVALID_ACTION: 'Unknown action: {module}-{action}',
@@ -34,6 +37,11 @@ export const ERRORS = {
     E_UPLOAD_FILE_TOO_LARGE: 'Upload file is {size} bytes and exceeds the {limit} byte limit.',
     E_INVALID_UPLOAD_SOURCE: 'Invalid upload source for field: {field}',
 };
+/** 仅配置获取失败可选择跳过；取消、版本错误和持久化错误仍须抛出。 @internal */
+export function isZentaoConfigFetchError(error) {
+    return error instanceof ZentaoError && (error.code === 'E_HTTP_ERROR' || error.code === 'E_NETWORK_ERROR'
+        || error.code === 'E_TIMEOUT' || error.code === 'E_INVALID_ZENTAO_CONFIG');
+}
 /**
  * SDK 统一错误类型。
  *

package/dist/misc/zentao-version.d.ts

@@ -0,0 +1,11 @@
+interface ZentaoVersion {
+    edition: string;
+    parts: number[];
+}
+/** 只接受开源版、biz、max、ipd 系列的点分数字正式版本。 */
+export declare function parseZentaoVersion(version: string): ZentaoVersion;
+/** 注册和生成时共用，缺少版本、格式非法或同系列重复均拒绝。 */
+export declare function validateMinVersion(value: unknown): asserts value is readonly string[];
+/** 同系列逐段比较，缺少的数字段视为零；未列出的系列不支持。 */
+export declare function supportsZentaoVersion(version: ZentaoVersion, minimums: readonly string[]): boolean;
+export {};

package/dist/misc/zentao-version.js

@@ -0,0 +1,35 @@
+import { ZentaoError } from './errors.js';
+/** 只接受开源版、biz、max、ipd 系列的点分数字正式版本。 */
+export function parseZentaoVersion(version) {
+    const match = typeof version === 'string' ? version.trim().match(/^(biz|max|ipd)?(\d+(?:\.\d+)*)$/i) : null;
+    const parts = match?.[2].split('.').map(Number);
+    if (!match || !parts?.every(Number.isSafeInteger)) {
+        throw new ZentaoError('E_INVALID_ZENTAO_VERSION', { version: String(version) });
+    }
+    return { edition: (match[1] ?? '').toLowerCase(), parts };
+}
+/** 注册和生成时共用，缺少版本、格式非法或同系列重复均拒绝。 */
+export function validateMinVersion(value) {
+    try {
+        if (!Array.isArray(value) || value.length === 0)
+            throw new Error('minVersion must be a non-empty array.');
+        const editions = Array.from(value, version => parseZentaoVersion(version).edition);
+        if (new Set(editions).size !== editions.length)
+            throw new Error('Duplicate editions in minVersion.');
+    }
+    catch (error) {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION', undefined, error);
+    }
+}
+/** 同系列逐段比较，缺少的数字段视为零；未列出的系列不支持。 */
+export function supportsZentaoVersion(version, minimums) {
+    const minimum = minimums.map(parseZentaoVersion).find(item => item.edition === version.edition);
+    if (!minimum)
+        return false;
+    for (let index = 0; index < Math.max(version.parts.length, minimum.parts.length); index++) {
+        const difference = (version.parts[index] ?? 0) - (minimum.parts[index] ?? 0);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    return true;
+}

package/dist/modules/define.d.ts

@@ -21,7 +21,8 @@ export interface DefineModulesOptions {
  *
  * @param input - 单个或一组模块定义。
  * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段；
+ *   `E_INVALID_ACTION_DEFINITION` —— 动作字段非法或 `minVersion` 缺失、为空、格式错误、系列重复。
  */
 export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
 /**
@@ -34,7 +35,7 @@ export declare function defineModules(input: ModuleDefinition | ModuleDefinition
  * @param moduleName - 目标模块名（大小写不敏感）。
  * @param input - 单个或一组动作定义。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   （动作缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），或
  *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
@@ -52,7 +53,7 @@ export declare function defineModuleActions(moduleName: string, input: ModuleAct
  * @param actionName - 目标动作名（大小写不敏感）。
  * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
- *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），
  *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export declare function extendModuleAction(moduleName: string, actionName: string, action: Partial<ModuleAction> | ((action: ModuleAction) => ModuleAction)): void;

package/dist/modules/define.js

@@ -13,7 +13,8 @@ import { deepClone, deepMerge, findActionIndex, freezeAction, freezeModule, getM
  *
  * @param input - 单个或一组模块定义。
  * @param options - 写入策略，参见 {@link DefineModulesOptions}。
- * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段；
+ *   `E_INVALID_ACTION_DEFINITION` —— 动作字段非法或 `minVersion` 缺失、为空、格式错误、系列重复。
  */
 export function defineModules(input, options = {}) {
     const modules = getModulesState();
@@ -42,7 +43,7 @@ export function defineModules(input, options = {}) {
  * @param moduleName - 目标模块名（大小写不敏感）。
  * @param input - 单个或一组动作定义。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION_DEFINITION`
- *   （动作缺少 `name` / `path`，或 `method` / `resultType` 类型非法），或
+ *   （动作缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），或
  *   `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export function defineModuleActions(moduleName, input) {
@@ -84,7 +85,7 @@ export function defineModuleActions(moduleName, input) {
  * @param actionName - 目标动作名（大小写不敏感）。
  * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
  * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）、
- *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`，或 `method` / `resultType` 类型非法），
+ *   `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path`、`minVersion` 无效，或 `method` / `resultType` 类型非法），
  *   或 `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`（省略字段且无法按 `type` 推导）。
  */
 export function extendModuleAction(moduleName, actionName, action) {