zentao-api 0.6.6 → 0.6.8

package/dist/profiles/index.js

@@ -1,6 +1,7 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isNodeRuntime } from '../misc/environment.js';
 import { isRecord, normalizeSiteUrl } from '../utils/index.js';
+import { withProfileFileLock } from './file-lock.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -21,23 +22,48 @@ function nowString() {
 function importNodeModule(specifier) {
     return import(specifier);
 }
-// 进程内串行锁：所有 read-modify-write 类的 profile 操作都通过这个队列，
-// 避免并发 `addProfile`/`switchProfile` 出现 lost update（写文件本身是原子
-// rename，但 read→modify→write 之间没有跨步保护）。跨进程并发不在保证范围内。
+// 所有 read-modify-write 都先进入实例队列，再取得文件锁或浏览器 Web Lock。
 let storeMutex = Promise.resolve();
 function withStoreMutex(operation) {
-    const next = storeMutex.then(operation, operation);
+    const run = () => withStorageErrors(async () => {
+        if (isNodeRuntime())
+            return withProfileFileLock(await getProfileFilePath(), operation);
+        const locks = globalThis.navigator?.locks;
+        // ponytail: 没有 Web Locks 时仅保证实例内串行；需要跨标签保证的应用应使用支持 Web Locks 的环境。
+        if (!locks)
+            return operation();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        try {
+            return await locks.request(`${ZENTAO_PROFILES_STORAGE_KEY}:write`, { signal: controller.signal }, () => {
+                clearTimeout(timeout);
+                return operation();
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    });
+    const next = storeMutex.then(run, run);
     storeMutex = next.catch(() => undefined);
     return next;
 }
-function getBrowserStorage() {
+async function withStorageErrors(operation) {
     try {
-        return globalThis.localStorage;
+        return await operation();
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error instanceof ZentaoError)
+            throw error;
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE', undefined, error);
     }
 }
+function getBrowserStorage() {
+    const storage = globalThis.localStorage;
+    if (!storage)
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    return storage;
+}
 async function getProfileFilePath() {
     const path = await importNodeModule('node:path');
     const home = process.env.HOME
@@ -60,30 +86,31 @@ function normalizeProfile(profile) {
         throw new ZentaoError('E_INVALID_PROFILE');
     }
     const token = profile.token.trim();
-    if (!token)
+    const account = profile.account.trim();
+    if (!token || !account)
         throw new ZentaoError('E_INVALID_PROFILE');
     const copy = cloneJson(profile);
     delete copy.key;
     return {
         ...copy,
         server: normalizeSiteUrl(profile.server),
-        account: profile.account.trim(),
+        account,
         token,
     };
 }
 function normalizeStore(raw) {
-    if (!isRecord(raw))
-        return { profiles: [] };
-    const profiles = Array.isArray(raw.profiles)
-        ? raw.profiles.flatMap((profile) => {
-            try {
-                return [normalizeProfile(profile)];
-            }
-            catch {
-                return [];
-            }
-        })
-        : [];
+    if (!isRecord(raw) || !Array.isArray(raw.profiles)
+        || (raw.currentProfile !== undefined && typeof raw.currentProfile !== 'string')) {
+        throw new ZentaoError('E_PROFILE_STORAGE_INVALID');
+    }
+    const profiles = raw.profiles.flatMap((profile) => {
+        try {
+            return [normalizeProfile(profile)];
+        }
+        catch {
+            return [];
+        }
+    });
     const currentProfile = typeof raw.currentProfile === 'string' ? raw.currentProfile : undefined;
     return currentProfile ? { currentProfile, profiles } : { profiles };
 }
@@ -95,54 +122,50 @@ function parseStore(text) {
         throw new ZentaoError('E_PROFILE_STORAGE_INVALID', undefined, error);
     }
 }
-async function readStore() {
-    if (isNodeRuntime()) {
-        const fs = await importNodeModule('node:fs/promises');
-        const file = await getProfileFilePath();
-        try {
-            return parseStore(await fs.readFile(file, 'utf8'));
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return { profiles: [] };
+function readStore() {
+    return withStorageErrors(async () => {
+        if (isNodeRuntime()) {
+            const fs = await importNodeModule('node:fs/promises');
+            const file = await getProfileFilePath();
+            try {
+                return parseStore(await fs.readFile(file, 'utf8'));
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return { profiles: [] };
+                }
+                throw error;
             }
-            throw error;
         }
-    }
-    const storage = getBrowserStorage();
-    if (!storage) {
-        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
-    }
-    const text = storage.getItem(ZENTAO_PROFILES_STORAGE_KEY);
-    return text ? parseStore(text) : { profiles: [] };
+        const text = getBrowserStorage().getItem(ZENTAO_PROFILES_STORAGE_KEY);
+        return text === null ? { profiles: [] } : parseStore(text);
+    });
 }
-async function writeStore(store) {
-    const normalizedStore = normalizeStore(store);
-    const text = `${JSON.stringify(normalizedStore, null, 2)}\n`;
-    if (isNodeRuntime()) {
-        const fs = await importNodeModule('node:fs/promises');
-        const path = await importNodeModule('node:path');
-        const file = await getProfileFilePath();
-        const dir = path.dirname(file);
-        const tempFile = path.join(dir, `.zentao.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
-        await fs.chmod(dir, 0o700).catch(() => undefined);
-        try {
-            await fs.writeFile(tempFile, text, { encoding: 'utf8', mode: 0o600 });
-            await fs.rename(tempFile, file);
-            await fs.chmod(file, 0o600).catch(() => undefined);
-        }
-        catch (error) {
-            await fs.rm(tempFile, { force: true }).catch(() => undefined);
-            throw error;
+function writeStore(store) {
+    return withStorageErrors(async () => {
+        const normalizedStore = normalizeStore(store);
+        const text = `${JSON.stringify(normalizedStore, null, 2)}\n`;
+        if (isNodeRuntime()) {
+            const fs = await importNodeModule('node:fs/promises');
+            const path = await importNodeModule('node:path');
+            const file = await getProfileFilePath();
+            const dir = path.dirname(file);
+            const tempFile = path.join(dir, `.zentao.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+            await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+            await fs.chmod(dir, 0o700).catch(() => undefined);
+            try {
+                await fs.writeFile(tempFile, text, { encoding: 'utf8', mode: 0o600 });
+                await fs.rename(tempFile, file);
+                await fs.chmod(file, 0o600).catch(() => undefined);
+            }
+            catch (error) {
+                await fs.rm(tempFile, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            return;
         }
-        return;
-    }
-    const storage = getBrowserStorage();
-    if (!storage) {
-        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
-    }
-    storage.setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+        getBrowserStorage().setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+    });
 }
 function toRecord(profile) {
     const normalized = normalizeProfile(profile);
@@ -154,6 +177,15 @@ function toRecord(profile) {
 function findProfile(store, profileKey) {
     return store.profiles.find((profile) => getProfileKey(profile) === profileKey);
 }
+function requireProfile(store, profileKey) {
+    const key = profileKey ?? store.currentProfile;
+    if (!key)
+        throw new ZentaoError('E_NO_PROFILE');
+    const profile = findProfile(store, key);
+    if (!profile)
+        throw new ZentaoError('E_PROFILE_NOT_FOUND', { profileKey: key });
+    return profile;
+}
 function setFallbackCurrentProfile(store) {
     if (!store.currentProfile || !findProfile(store, store.currentProfile)) {
         const fallback = store.profiles.at(-1);
@@ -180,7 +212,7 @@ export function getProfileKey(profile) {
  * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
  *
  * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
- * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON 或根结构不合法）或
  *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
  */
 export async function getAllProfiles() {
@@ -202,13 +234,18 @@ export async function getProfile(profileKey) {
     const profile = findProfile(store, key);
     return profile ? toRecord(profile) : undefined;
 }
+/** 只读恢复与账号切换共用相同的 key 解析和错误语义。 @internal */
+export async function getProfileOrThrow(profileKey) {
+    return toRecord(requireProfile(await readStore(), profileKey));
+}
 /**
  * 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。
  *
  * 行为细节：
  * - 同 key（`account@server`）已存在时会**整体覆盖**而非合并字段。
  * - 写入时会自动补齐 `loginTime` 与 `lastUsedTime`（若调用方未提供则使用当前 ISO 时间）。
- * - 操作通过进程内串行锁保护 read-modify-write，避免并发调用导致的 lost update；跨进程并发不在保证范围。
+ * - Node.js 通过文件锁保护同主机本地文件系统的 read-modify-write；浏览器在支持 Web Locks 时保护同源上下文，其他环境仅保证实例内串行。
+ * - 跨进程或上下文等待锁超过约 5 秒时抛出存储不可用错误，不修改 profile 数据。
  * - 实际写入使用临时文件 + `rename` 的原子方式，并将文件与目录权限收紧到 `0600`/`0700`（Node.js 下）。
  *
  * @param profile - 要写入的 profile，必须至少包含 `server`、`account`、`token`。
@@ -217,10 +254,17 @@ export async function getProfile(profileKey) {
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export function addProfile(profile) {
+    return saveProfile(profile);
+}
+/** 登录只更新会话字段和显式偏好，保留同账号的应用数据。 @internal */
+export function saveLoginProfile(profile) {
+    return saveProfile(profile, true);
+}
+function saveProfile(profile, preservePreferences = false) {
     return withStoreMutex(async () => {
         const store = await readStore();
         const timestamp = nowString();
-        const normalized = normalizeProfile({
+        let normalized = normalizeProfile({
             ...profile,
             loginTime: profile.loginTime ?? timestamp,
             lastUsedTime: profile.lastUsedTime ?? timestamp,
@@ -228,6 +272,12 @@ export function addProfile(profile) {
         const profileKey = getProfileKey(normalized);
         const index = store.profiles.findIndex((item) => getProfileKey(item) === profileKey);
         if (index >= 0) {
+            if (preservePreferences) {
+                const previous = store.profiles[index];
+                const config = { ...(isRecord(previous.config) ? previous.config : {}), ...normalized.config };
+                normalized = normalizeProfile({ ...previous, ...profile, ...normalized,
+                    config: Object.keys(config).length ? config : undefined });
+            }
             store.profiles[index] = normalized;
         }
         else {
@@ -238,10 +288,22 @@ export function addProfile(profile) {
         return toRecord(normalized);
     });
 }
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export function updateProfileServerConfig(profileKey, serverConfig, fetchedAt) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const profile = findProfile(store, profileKey);
+        if (!profile)
+            return;
+        profile.serverConfig = cloneJson(serverConfig);
+        profile.serverConfigFetchedAt = fetchedAt;
+        await writeStore(store);
+    });
+}
 /**
  * 删除指定 profile。
  *
- * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 若被删除的是当前 profile，会回退为最近添加且仍保留的 profile；覆盖或切换已有记录不改变添加顺序。若已无任何 profile，
  * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
  *
  * @param profileKey - 要删除的 profile key。
@@ -275,16 +337,9 @@ export function deleteProfile(profileKey) {
 export function switchProfile(profileKey) {
     return withStoreMutex(async () => {
         const store = await readStore();
-        const key = profileKey ?? store.currentProfile;
-        if (!key) {
-            throw new ZentaoError('E_NO_PROFILE');
-        }
-        const profile = findProfile(store, key);
-        if (!profile) {
-            throw new ZentaoError('E_PROFILE_NOT_FOUND', { profileKey: key });
-        }
+        const profile = requireProfile(store, profileKey);
         profile.lastUsedTime = nowString();
-        store.currentProfile = key;
+        store.currentProfile = getProfileKey(profile);
         await writeStore(store);
         return toRecord(profile);
     });

package/dist/request/index.d.ts

@@ -27,6 +27,9 @@ export type RequestResultFor<Name extends BuiltinRequestName> = ActionMetaOf<Nam
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ * 请求前按 Action 的 `minVersion` 检查服务器版本；全局 `version` 可避免配置探测，
+ * `forceRefreshConfig` 则强制使用实际版本。无法获取配置时默认抛错，
+ * `skipVersionCheckOnConfigError` 可允许本次跳过检查，但不能忽略明确的版本不匹配。
  *
  * 对 `update` 动作，当 `options.autoFill` 或全局 `autoFill` 为真时，会先 GET 当前对象，
  * 用现值补齐用户未显式传入的 body 字段后再 PUT，避免禅道覆盖未提交字段。详见 {@link RequestOptions.autoFill}。

package/dist/request/index.js

@@ -1,4 +1,5 @@
-import { ZentaoError } from '../misc/errors.js';
+import { isZentaoConfigFetchError, ZentaoError } from '../misc/errors.js';
+import { parseZentaoVersion, supportsZentaoVersion } from '../misc/zentao-version.js';
 import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveActionRequest } from '../modules/resolve.js';
@@ -57,17 +58,17 @@ function getExplicitDataKeys(data) {
  * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
  * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
  */
-async function autoFillUpdateParams(module, action, params, options) {
+async function autoFillUpdateParams(module, action, params, options, version) {
     const properties = action.requestBody?.schema?.properties;
     const getAction = module.actions.find((candidate) => candidate.type === 'get' && candidate.path === action.path);
     if (!properties || !getAction)
         return params;
-    const current = (await request(`${module.name}/${getAction.name}`, params, {
+    const current = (await requestInternal(`${module.name}/${getAction.name}`, params, {
         client: options.client,
         timeout: options.timeout,
         insecure: options.insecure,
         throwOnFail: true,
-    })).data;
+    }, version)).data;
     if (!isRecord(current))
         return params;
     const explicitDataKeys = getExplicitDataKeys(params.data);
@@ -172,6 +173,10 @@ function normalizeResponse(command, raw, options) {
     return response;
 }
 export async function request(name, params = {}, options = {}) {
+    return requestInternal(name, params, options);
+}
+/** version 为 undefined 时解析一次，null 表示本次调用已选择跳过版本检查。 */
+async function requestInternal(name, params, options, version) {
     const globals = getGlobalOptions();
     const client = options.client ?? globals.client;
     if (!client) {
@@ -195,21 +200,52 @@ export async function request(name, params = {}, options = {}) {
     if (!action) {
         throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
     }
+    if (version === undefined) {
+        if (!options.forceRefreshConfig && globals.version !== undefined) {
+            version = globals.version;
+        }
+        else {
+            try {
+                version = (await client.getZentaoConfig({
+                    forceRefresh: options.forceRefreshConfig,
+                    timeout: options.timeout ?? globals.timeout,
+                    insecure: options.insecure ?? globals.insecure,
+                })).version;
+            }
+            catch (error) {
+                if (!(options.skipVersionCheckOnConfigError ?? globals.skipVersionCheckOnConfigError)
+                    || !isZentaoConfigFetchError(error))
+                    throw error;
+                version = null;
+            }
+        }
+    }
+    if (version !== null && !supportsZentaoVersion(parseZentaoVersion(version), action.minVersion)) {
+        throw new ZentaoError('E_UNSUPPORTED_ZENTAO_VERSION', {
+            action: `${module.name}/${action.name}`,
+            version,
+            minVersion: action.minVersion.join(', '),
+        }, { action: `${module.name}/${action.name}`, version, minVersion: action.minVersion });
+    }
     const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
-        ? await autoFillUpdateParams(module, action, mergedParams, options)
+        ? await autoFillUpdateParams(module, action, mergedParams, { ...options, client }, version)
         : mergedParams;
     const command = resolveActionRequest(module, actionName, finalParams);
     const preparedBody = await prepareActionBody(command, {
         maxUploadBytes: options.maxUploadBytes,
     });
-    const raw = await client.request(command.path, {
-        method: String(command.action.method).toUpperCase(),
-        query: command.query,
-        body: preparedBody.body,
-        bodyType: preparedBody.bodyType,
+    const requestOptions = {
+        ...preparedBody,
         timeout: options.timeout ?? globals.timeout,
         insecure: options.insecure ?? globals.insecure,
-    });
+    };
+    const raw = command.action.request
+        ? await command.action.request({ request: command, ...requestOptions, client, options })
+        : await client.request(command.path, {
+            method: String(command.action.method).toUpperCase(),
+            query: command.query,
+            ...requestOptions,
+        });
     if (options.raw) {
         return raw;
     }

package/dist/types/client.d.ts

@@ -1,3 +1,8 @@
+/** 从本地 profile 恢复客户端时的选项。 */
+export interface FromProfileOptions {
+    /** 是否切换为当前 profile 并更新使用时间，默认 true；false 时恢复过程只读存储。 */
+    activate?: boolean;
+}
 /** 创建 {@link ZentaoClient} 时使用的配置。 */
 export interface ZentaoClientOptions {
     /** 禅道站点根地址，例如 `https://zentao.example.com`；SDK 会自动拼接 `/api.php/v2`。 */
@@ -36,3 +41,8 @@ export interface ClientRequestOptions {
     /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
 }
+/** {@link ZentaoClient.getZentaoConfig} 的选项。 */
+export interface GetZentaoConfigOptions extends Pick<ClientRequestOptions, 'timeout' | 'insecure' | 'signal'> {
+    /** 忽略已有缓存并重新获取配置，默认 false；同一客户端的并发获取会合并。 */
+    forceRefresh?: boolean;
+}

package/dist/types/module.d.ts

@@ -1,5 +1,6 @@
-import type { HttpMethod } from './client.js';
-import type { RequestProcessOptions } from './options.js';
+import type { ZentaoClient } from '../client/index.js';
+import type { ClientRequestBodyType, HttpMethod } from './client.js';
+import type { RequestOptions, RequestProcessOptions } from './options.js';
 import type { Pager } from './response.js';
 /** 模块动作类型：基础 CRUD 或自定义动作。 */
 export type ModuleActionType = 'list' | 'get' | 'create' | 'update' | 'delete' | 'action';
@@ -86,10 +87,32 @@ export type ModuleActionResultFieldMap = Readonly<Record<string, string>>;
  * @param options 本次请求的数据处理选项；直接调用 getter 时可以省略。
  */
 export type ModuleActionGetterFn<T, O = RequestProcessOptions> = (data: unknown, params: Record<string, unknown>, options?: O) => T;
+/**
+ * 自定义动作的请求发送逻辑，在版本检查、参数解析和请求体准备完成后调用。
+ * 返回原始响应数据，后续仍按动作定义提取结果、分页并应用请求选项；抛出的错误原样传递。
+ */
+export type ModuleActionRequestCallback = (info: {
+    /** 解析后的路径、查询参数、请求体数据及动作定义。 */
+    request: ModuleActionRequest;
+    /** 准备好的请求体，例如 JSON 对象或上传用的 FormData。 */
+    body: unknown;
+    /** 请求体序列化方式，可直接传给客户端。 */
+    bodyType?: ClientRequestBodyType;
+    /** 本次请求的超时选项，未指定时回落到全局选项。 */
+    timeout?: number;
+    /** 本次请求的 TLS 选项，未指定时回落到全局选项。 */
+    insecure?: boolean;
+    /** 本次调用选定的客户端。 */
+    client: ZentaoClient;
+    /** 调用方传入的原始请求选项。 */
+    options: RequestOptions;
+}) => Promise<unknown>;
 /** 禅道模块中的单个 API 动作定义。 */
 export interface ModuleAction {
     /** 动作名称，例如 `list`、`get`、`close`。 */
     name: ModuleActionName;
+    /** 各系列支持的最低禅道正式版本，例如 `['22.0', 'biz13.0', 'max8.0', 'ipd5.0']`；不能为空或重复系列，未列出的系列不支持。 */
+    minVersion: readonly string[];
     /** 动作类型，决定高阶 request 的路径/参数解析策略，并在 `method`、`resultType` 省略时作为推导依据。 */
     type: ModuleActionType;
     /** 面向用户展示的动作名称。 */
@@ -126,6 +149,8 @@ export interface ModuleAction {
      * 字符串为字段路径（支持 `a.b` 嵌套）、对象为字段映射、函数则接收原始响应与调用参数。
      */
     resultGetter?: string | ModuleActionResultFieldMap | ModuleActionGetterFn<unknown>;
+    /** 自定义请求回调；省略时通过 ZentaoClient.request 发送请求，返回值沿用相同的响应处理流程。 */
+    request?: ModuleActionRequestCallback;
 }
 /** 内置模块名称，同时允许用户扩展自定义模块名。 */
 export type ModuleName = 'user' | 'program' | 'product' | 'project' | 'execution' | 'productplan' | 'story' | 'epic' | 'requirement' | 'bug' | 'testcase' | 'task' | 'feedback' | 'ticket' | 'system' | 'build' | 'testtask' | 'release' | 'file' | (string & {});
@@ -140,6 +165,11 @@ export interface ModuleDefinition {
     /** 模块支持的动作集合。 */
     actions: readonly ModuleAction[];
 }
+/** 注册库查询选项；不传版本时返回完整的当前定义，不使用全局版本。 */
+export interface ModuleQueryOptions {
+    /** 仅返回该禅道版本支持的动作，以及至少含有一个支持动作的模块。 */
+    version?: string;
+}
 /** 将模块动作和参数解析后的可执行请求描述。 */
 export interface ModuleActionRequest {
     /** 模块名称。 */

package/dist/types/options.d.ts

@@ -2,6 +2,10 @@ import type { ZentaoClient } from '../client/index.js';
 import type { ProcessListOptions, ProcessSingleOptions } from './data.js';
 /** SDK 进程级全局默认选项，供高阶 {@link request} 调用复用。 */
 export interface GlobalOptions {
+    /** 当前禅道正式版本，例如 `biz13.5`；普通高阶请求直接使用，单次强制刷新时使用实际版本。不会自动写入 profile。 */
+    version?: string;
+    /** 配置网络或响应获取失败时，允许登录继续或高阶请求跳过版本检查，默认 false；不忽略版本不匹配、格式错误或存储错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 默认客户端；通常由 `ZentaoClient.init()` 设置。 */
     client?: ZentaoClient;
     /** 默认每页记录数，会映射到模块动作的 `recPerPage` 参数。 */
@@ -25,6 +29,10 @@ export interface GlobalOptions {
 }
 /** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
 export interface RequestOptions extends ProcessListOptions {
+    /** 强制刷新服务器配置并用实际版本校验本次请求，优先于全局 version；不会改写全局版本。 */
+    forceRefreshConfig?: boolean;
+    /** 配置网络或响应获取失败时跳过本次版本检查；优先于全局设置，默认 false，不忽略版本不匹配或格式错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 本次调用使用的客户端；优先级高于全局客户端。 */
     client?: ZentaoClient;
     /** 本次调用使用的每页记录数，优先级高于全局 `recPerPage`。 */

package/dist/types/profile.d.ts

@@ -1,23 +1,27 @@
 import type { ServerConfig } from './response.js';
-/** 保存到本地 profile 中的客户端偏好配置。 */
+/**
+ * 保存到本地 profile 中的客户端偏好配置。
+ * SDK 自动恢复 `timeout` / `insecure`；其余字段仅供上层应用读取和解释。
+ * 自定义值应使用 JSON 数据，不保留 Date、Map 等类型信息，不支持 BigInt 或循环对象。
+ */
 export interface ZentaoProfileConfig {
     /** 默认输出格式，供 CLI 等上层应用复用。 */
     defaultOutputFormat?: 'markdown' | 'json' | 'raw';
-    /** 界面语言。 */
+    /** 上层应用的界面语言，SDK 不自动应用。 */
     lang?: string;
-    /** 默认分页大小。 */
+    /** 上层应用的默认分页大小；SDK 请求分页使用 `recPerPage` 选项。 */
     defaultRecPerPage?: number;
     /** 是否跳过 TLS 证书验证；仅 Node.js 运行时支持。 */
     insecure?: boolean;
     /** 请求超时时间，单位毫秒。 */
     timeout?: number;
-    /** 是否在批量操作出错时停止执行后续操作。 */
+    /** 上层应用是否在批量操作出错时停止执行后续操作。 */
     batchFailFast?: boolean;
-    /** JSON 格式化时是否添加缩进。 */
+    /** 上层应用格式化 JSON 时是否添加缩进。 */
     jsonPretty?: boolean;
-    /** 模块级分页偏好。 */
+    /** 上层应用的模块级分页偏好，SDK 不自动应用。 */
     pagers?: Record<string, number>;
-    /** 允许上层应用保存自定义配置。 */
+    /** 允许上层应用保存 JSON 格式的自定义配置。 */
     [key: string]: unknown;
 }
 /** 本地持久化的禅道账号 profile。 */
@@ -36,9 +40,11 @@ export interface ZentaoProfile {
     lastUsedTime?: string;
     /** 禅道服务端配置。 */
     serverConfig?: ServerConfig;
+    /** 成功从 `?mode=getconfig` 获取配置的本地 ISO 时间；缺失时缓存需要刷新。 */
+    serverConfigFetchedAt?: string;
     /** 客户端自定义配置。 */
     config?: ZentaoProfileConfig;
-    /** 允许上层应用保存额外字段。 */
+    /** 允许上层应用保存 JSON 格式的额外字段，不保留 Date、Map 等类型信息，不支持 BigInt 或循环对象。 */
     [key: string]: unknown;
 }
 /** 运行时返回的 profile，会额外带上 `account@server` 形式的 key。 */

package/dist/types/response.d.ts

@@ -58,6 +58,13 @@ export interface LoginResponse extends ApiResponse {
 }
 /** 禅道 `?mode=getconfig` 返回的服务端配置。 */
 export interface ServerConfig {
+    /**
+     * 禅道版本，不同系列以不同的前缀表示，下面为例子：
+     * - `22.5`：开源版 22.5
+     * - `biz13.5`：企业版 13.5
+     * - `max8.5`：旗舰版 8.5
+     * - `ipd5.5`：IPD 5.5
+     */
     version: string;
     systemMode: string;
     sprintConcept: string;
@@ -67,4 +74,6 @@ export interface ServerConfig {
     methodVar: string;
     viewVar: string;
     sessionVar: string;
+    /** 保留服务端返回的其他配置字段。 */
+    [key: string]: unknown;
 }

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-29T09:25:28.910Z";
-const fallbackVersion = "0.6.6";
+const fallbackBuild = "2026-09-06T14:52:03.785Z";
+const fallbackVersion = "0.6.8";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",