zentao-api 0.2.0-beta.1 → 0.2.0

package/dist/misc/errors.js

@@ -1,3 +1,9 @@
+/**
+ * SDK 已知错误码到默认消息的映射表。
+ *
+ * 每条消息允许带 `{key}` 占位符，由 {@link ZentaoError} 构造时使用 `replacements`
+ * 进行字面量替换。此对象使用 `as const`，可直接作为类型来源约束错误码。
+ */
 export const ERRORS = {
     E_INVALID_BASE_URL: 'Invalid ZenTao baseUrl.',
     E_NO_GLOBAL_CLIENT: 'No global client configured. Call ZentaoClient.init() or pass options.client.',
@@ -6,20 +12,39 @@ export const ERRORS = {
     E_TIMEOUT: 'Request timed out.',
     E_INSECURE_BROWSER: 'The insecure option is only supported in Node.js runtimes.',
     E_LOGIN_FAILED: 'ZenTao login failed.',
+    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_UNAVAILABLE: 'ZenTao profile storage is unavailable in this runtime.',
     E_INVALID_MODULE: 'Unknown module: {module}',
     E_INVALID_ACTION: 'Unknown action: {module}-{action}',
     E_INVALID_MODULE_DEFINITION: 'Invalid module definition.',
     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_API_FAILED: 'ZenTao API returned failure: {message}',
 };
-/** SDK 统一错误类型，所有可预期错误都会携带稳定错误码。 */
+/**
+ * SDK 统一错误类型。
+ *
+ * 所有可预期错误（参数缺失、HTTP/网络/超时、登录失败、profile 异常等）都通过
+ * `ZentaoError` 抛出并携带稳定 {@link ErrorCode}，方便调用方按 `code` 区分处理。
+ * 错误消息默认来自 {@link ERRORS} 中的模板，并支持占位符替换。
+ */
 export class ZentaoError extends Error {
-    /** 错误码，对应 {@link ERRORS} 的 key。 */
+    /** 错误码，对应 {@link ERRORS} 的 key；用于稳定地区分错误类型。 */
     code;
-    /** 附加上下文，例如 HTTP 响应详情或原始异常。 */
+    /** 附加上下文，例如 HTTP 响应详情、原始异常或失败的禅道响应原文。 */
     details;
-    /** 根据错误码和占位符替换值创建错误。 */
+    /**
+     * 构造 SDK 错误实例。
+     *
+     * @param code - 错误码，必须是 {@link ERRORS} 中已声明的 key。
+     * @param replacements - 可选的占位符替换值；遍历后会把 `{key}` 替换为字符串化的值。
+     * @param details - 可选的附加上下文（HTTP 响应详情、原始异常等），保存到 {@link details}。
+     */
     constructor(code, replacements, details) {
         let message = ERRORS[code];
         if (replacements) {

package/dist/misc/global-options.d.ts

@@ -1,5 +1,18 @@
 import type { GlobalOptions } from '../types/index.js';
-/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+/**
+ * 获取当前全局选项的快照。
+ *
+ * 返回的是浅拷贝副本，对返回值的修改不会影响内部状态；如需更新请使用 {@link setGlobalOptions}。
+ *
+ * @returns 当前生效的全局选项快照，参见 {@link GlobalOptions}。
+ */
 export declare function getGlobalOptions(): GlobalOptions;
-/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+/**
+ * 以浅合并的方式更新全局选项。
+ *
+ * 仅覆盖传入 `options` 中显式声明的字段；其余字段保留原值。若希望清空某个字段，
+ * 显式传入 `undefined` 即可（会写入 `undefined` 并在后续读取时返回 `undefined`）。
+ *
+ * @param options - 要合并到全局选项中的字段子集。
+ */
 export declare function setGlobalOptions(options: Partial<GlobalOptions>): void;

package/dist/misc/global-options.js

@@ -1,9 +1,22 @@
 let globalOptions = {};
-/** 获取当前全局选项快照；返回副本，避免调用方直接改写内部状态。 */
+/**
+ * 获取当前全局选项的快照。
+ *
+ * 返回的是浅拷贝副本，对返回值的修改不会影响内部状态；如需更新请使用 {@link setGlobalOptions}。
+ *
+ * @returns 当前生效的全局选项快照，参见 {@link GlobalOptions}。
+ */
 export function getGlobalOptions() {
     return { ...globalOptions };
 }
-/** 合并设置全局选项；传入 `undefined` 可清空对应字段。 */
+/**
+ * 以浅合并的方式更新全局选项。
+ *
+ * 仅覆盖传入 `options` 中显式声明的字段；其余字段保留原值。若希望清空某个字段，
+ * 显式传入 `undefined` 即可（会写入 `undefined` 并在后续读取时返回 `undefined`）。
+ *
+ * @param options - 要合并到全局选项中的字段子集。
+ */
 export function setGlobalOptions(options) {
     globalOptions = { ...globalOptions, ...options };
 }

package/dist/modules/registry.d.ts

@@ -2,21 +2,84 @@ import type { ModuleAction, ModuleDefinition } from '../types/index.js';
 import { BUILTIN_MODULES } from './generated.js';
 export { BUILTIN_MODULES };
 export declare const MODULES: ModuleDefinition[];
+/** {@link defineModules} 的选项。 */
 export interface DefineModulesOptions {
-    /** 同名模块是否整体替换；默认合并模块定义和动作。 */
-    relace?: boolean;
+    /**
+     * 同名模块的写入策略。
+     *
+     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
+     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
+     */
+    replace?: boolean;
 }
-/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `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 ZentaoError}。 */
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
 export declare function getModule(moduleName: string): ModuleDefinition;
-/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
+ * 2. 在该模块的动作中按名称大小写不敏感匹配。
+ * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
+ *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
+ *
+ * 返回值同样是已深冻结的引用，请勿尝试修改。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @returns 匹配到的动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ */
 export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
-/** 返回当前运行时注册表中的所有模块名。 */
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
 export declare function getModuleNames(): string[];
-/** 判断模块名是否已注册，大小写不敏感。 */
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
 export declare function isModuleName(moduleName: string): boolean;
 /** @internal */
 export declare function resetModuleDefinitions(): void;

package/dist/modules/registry.js

@@ -3,42 +3,70 @@ import { asArray } from '../utils/index.js';
 import { BUILTIN_MODULES } from './generated.js';
 export { BUILTIN_MODULES };
 export const MODULES = BUILTIN_MODULES;
-// 运行时注册表使用内置定义的浅克隆，避免用户扩展污染生成文件导出的常量。
-let modules = cloneModules(BUILTIN_MODULES);
+// 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
+// - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
+// - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
+//   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
+let modules = freezeModules(deepClone(BUILTIN_MODULES));
 let moduleMap = buildModuleMap(modules);
-function cloneActions(source) {
-    return source.map((action) => ({ ...action }));
+function deepClone(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => deepClone(item));
+    }
+    if (value && typeof value === 'object' && !(value instanceof Function)) {
+        const result = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            result[key] = deepClone(nestedValue);
+        }
+        return result;
+    }
+    return value;
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    for (const key of Object.keys(value)) {
+        deepFreeze(value[key]);
+    }
+    return Object.freeze(value);
 }
-function cloneModules(source) {
-    return source.map((module) => ({
-        ...module,
-        actions: cloneActions(module.actions),
-    }));
+function freezeAction(action) {
+    return deepFreeze(action);
+}
+function freezeModule(module) {
+    module.actions.forEach(freezeAction);
+    return deepFreeze(module);
+}
+function freezeModules(source) {
+    source.forEach(freezeModule);
+    return source;
 }
 function findActionIndex(source, actionName) {
     const key = actionName.toLowerCase();
     return source.findIndex((action) => String(action.name).toLowerCase() === key);
 }
 function mergeActions(base, extension) {
-    const next = cloneActions(base);
+    const next = base.slice();
     for (const action of extension) {
         const index = findActionIndex(next, String(action.name));
-        const clone = { ...action };
+        const frozen = freezeAction(deepClone(action));
         if (index >= 0) {
-            next[index] = clone;
+            next[index] = frozen;
         }
         else {
-            next.push(clone);
+            next.push(frozen);
         }
     }
     return next;
 }
 function mergeModule(base, extension) {
-    return {
+    return freezeModule({
         ...base,
-        ...extension,
+        ...deepClone(extension),
         actions: mergeActions(base.actions, extension.actions),
-    };
+    });
 }
 function buildModuleMap(source) {
     return new Map(source.map((module) => [module.name.toLowerCase(), module]));
@@ -56,42 +84,80 @@ function validateAction(action) {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
 }
-/** 定义或扩展模块；同名模块默认合并动作，`relace` 为真时整体替换，未知模块追加。 */
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
 export function defineModules(input, options = {}) {
     for (const module of asArray(input)) {
         validateModule(module);
         const key = module.name.toLowerCase();
         const index = modules.findIndex((item) => item.name.toLowerCase() === key);
-        const next = { ...module, actions: cloneActions(module.actions) };
         if (index >= 0) {
-            modules[index] = options.relace ? next : mergeModule(modules[index], module);
+            modules[index] = options.replace
+                ? freezeModule(deepClone(module))
+                : mergeModule(modules[index], module);
         }
         else {
-            modules.push(next);
+            modules.push(freezeModule(deepClone(module)));
         }
     }
     rebuildMap();
 }
-/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
 export function defineModuleActions(moduleName, input) {
-    const module = moduleMap.get(moduleName.toLowerCase());
+    const key = moduleName.toLowerCase();
+    const module = moduleMap.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(module.actions, String(action.name));
-        const next = { ...action };
+        const index = findActionIndex(actions, String(action.name));
+        const frozen = freezeAction(deepClone(action));
         // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
         if (index >= 0) {
-            module.actions[index] = next;
+            actions[index] = frozen;
         }
         else {
-            module.actions.push(next);
+            actions.push(frozen);
         }
     }
+    const nextModule = freezeModule({ ...module, actions });
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildMap();
 }
-/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
 export function getModule(moduleName) {
     const module = moduleMap.get(moduleName.toLowerCase());
     if (!module) {
@@ -99,7 +165,22 @@ export function getModule(moduleName) {
     }
     return module;
 }
-/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
+ * 2. 在该模块的动作中按名称大小写不敏感匹配。
+ * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
+ *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
+ *
+ * 返回值同样是已深冻结的引用，请勿尝试修改。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @returns 匹配到的动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ */
 export function getModuleAction(moduleName, actionName) {
     const module = getModule(moduleName);
     const normalized = actionName === 'ls' ? 'list' : actionName;
@@ -114,16 +195,27 @@ export function getModuleAction(moduleName, actionName) {
     }
     throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
 }
-/** 返回当前运行时注册表中的所有模块名。 */
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
 export function getModuleNames() {
     return modules.map((module) => module.name);
 }
-/** 判断模块名是否已注册，大小写不敏感。 */
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
 export function isModuleName(moduleName) {
     return moduleMap.has(moduleName.toLowerCase());
 }
 /** @internal */
 export function resetModuleDefinitions() {
-    modules = cloneModules(BUILTIN_MODULES);
+    modules = freezeModules(deepClone(BUILTIN_MODULES));
     rebuildMap();
 }

package/dist/modules/resolve.js

@@ -1,5 +1,5 @@
 import { ZentaoError } from '../misc/errors.js';
-import { getNestedValue } from '../utils/index.js';
+import { getNestedValue, isRecord } from '../utils/index.js';
 import { getModuleAction } from './registry.js';
 const SCOPE_MAP = {
     product: 'products',
@@ -45,23 +45,35 @@ function parseData(value) {
     }
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
+const TRUTHY_STRINGS = new Set(['true', '1', 'yes', 'on']);
+const FALSY_STRINGS = new Set(['false', '0', 'no', 'off']);
 /** 按 OpenAPI schema 的基础类型对参数做轻量转换。 */
-function coerceValue(value, type) {
-    if (value === undefined)
-        return undefined;
+function coerceValue(value, type, paramName) {
+    if (value === undefined || value === null)
+        return value;
     if (type === 'number' || type === 'integer') {
         const numberValue = Number(value);
         return Number.isNaN(numberValue) ? value : numberValue;
     }
     if (type === 'boolean') {
-        if (value === 'true')
-            return true;
-        if (value === 'false')
-            return false;
-        return Boolean(value);
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number') {
+            if (value === 1)
+                return true;
+            if (value === 0)
+                return false;
+            throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value: String(value) });
+        }
+        if (typeof value === 'string') {
+            const normalized = value.trim().toLowerCase();
+            if (TRUTHY_STRINGS.has(normalized))
+                return true;
+            if (FALSY_STRINGS.has(normalized))
+                return false;
+            throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value });
+        }
+        throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value: String(value) });
     }
     return value;
 }
@@ -131,16 +143,17 @@ export function resolveModuleCommand(module, actionName, params = {}) {
         for (const [key, property] of Object.entries(schema.properties ?? {})) {
             // body 字段优先级：params.data 中的字段 > 平铺 params 字段 > schema 默认值。
             const hasDataValue = Object.prototype.hasOwnProperty.call(data, key);
-            let value = data[key] ?? params[key] ?? property.defaultValue;
+            const hasParamValue = Object.prototype.hasOwnProperty.call(params, key);
+            let value = hasDataValue ? data[key] : hasParamValue ? params[key] : property.defaultValue;
             if (value === undefined && (property.required || required.has(key))) {
                 throw new ZentaoError('E_MISSING_PARAM', { param: key });
             }
-            value = coerceValue(value, property.type);
-            if (property.type === 'array' && value !== undefined && !Array.isArray(value)) {
+            value = coerceValue(value, property.type, key);
+            if (property.type === 'array' && value !== undefined && value !== null && !Array.isArray(value)) {
                 if (typeof value === 'string') {
                     value = value.split(',');
                 }
-                else if (!hasDataValue || !isPlainObject(value)) {
+                else if (!hasDataValue || !isRecord(value)) {
                     value = [value];
                 }
             }

package/dist/profiles/index.d.ts

@@ -0,0 +1,76 @@
+import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+/**
+ * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
+ *
+ * Node.js 环境会改用文件 `~/.config/zentao/zentao.json`，与此常量无关。
+ */
+export declare const ZENTAO_PROFILES_STORAGE_KEY = "ZENTAO_PROFILES";
+/**
+ * 根据 profile 的账号和禅道站点地址生成稳定 key。
+ *
+ * Key 格式为 `account@server`，其中 `server` 会经过 {@link normalizeSiteUrl} 规范化，
+ * 因此即使传入末尾带 `/` 或 `/api.php/v2` 的地址，也会得到一致的结果。
+ *
+ * @param profile - 只需要包含 `account` 和 `server` 两个字段。
+ * @returns 形如 `admin@https://zentao.example.com` 的 profile key。
+ * @throws {ZentaoError} `E_INVALID_PROFILE`（账号为空白）或 `E_INVALID_BASE_URL`（`server` 不合法）。
+ */
+export declare function getProfileKey(profile: Pick<ZentaoProfile, 'account' | 'server'>): string;
+/**
+ * 列出本地保存的所有 profile。
+ *
+ * Node.js 下从 `~/.config/zentao/zentao.json` 读取；浏览器下从 `localStorage` 读取。
+ * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
+ *
+ * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
+ */
+export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
+/**
+ * 获取指定 profile。
+ *
+ * @param profileKey - 可选的 profile key（`account@server`）；不传时返回当前（最近一次切换的）profile。
+ * @returns 命中的 profile（带 `key` 字段）；当 key 不存在或尚未配置当前 profile 时返回 `undefined`。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRecord | undefined>;
+/**
+ * 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。
+ *
+ * 行为细节：
+ * - 同 key（`account@server`）已存在时会**整体覆盖**而非合并字段。
+ * - 写入时会自动补齐 `loginTime` 与 `lastUsedTime`（若调用方未提供则使用当前 ISO 时间）。
+ * - 操作通过进程内串行锁保护 read-modify-write，避免并发调用导致的 lost update；跨进程并发不在保证范围。
+ * - 实际写入使用临时文件 + `rename` 的原子方式，并将文件与目录权限收紧到 `0600`/`0700`（Node.js 下）。
+ *
+ * @param profile - 要写入的 profile，必须至少包含 `server`、`account`、`token`。
+ * @returns 实际写入并附带 `key` 字段的 profile 记录。
+ * @throws {ZentaoError} `E_INVALID_PROFILE`（必填字段缺失或 token 为空白）、
+ *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/**
+ * 删除指定 profile。
+ *
+ * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
+ *
+ * @param profileKey - 要删除的 profile key。
+ * @returns 当且仅当确实删除了某条记录时返回 `true`；key 不存在时返回 `false` 且不会写盘。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export declare function deleteProfile(profileKey: string): Promise<boolean>;
+/**
+ * 切换当前使用的 profile，并刷新其 `lastUsedTime`。
+ *
+ * 不传 `profileKey` 时使用当前 profile（相当于把当前 profile 的 `lastUsedTime` 刷新一遍）。
+ * 切换成功后会立即写回存储，由进程内串行锁保护。
+ *
+ * @param profileKey - 可选的目标 profile key；不传则使用当前 profile。
+ * @returns 切换后生效的 profile 记录（带 `key` 字段）。
+ * @throws {ZentaoError} `E_NO_PROFILE`（未配置任何当前 profile 且未传 key）、
+ *   `E_PROFILE_NOT_FOUND`（目标 key 不存在）、`E_PROFILE_STORAGE_INVALID` /
+ *   `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export declare function switchProfile(profileKey?: string): Promise<ZentaoProfileRecord>;