zentao-api 0.2.0-beta.2 → 0.2.1

package/dist/modules/registry.js

@@ -3,55 +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 cloneValue(value) {
+function deepClone(value) {
     if (Array.isArray(value)) {
-        return value.map(cloneValue);
+        return value.map((item) => deepClone(item));
     }
-    if (value && typeof value === 'object') {
+    if (value && typeof value === 'object' && !(value instanceof Function)) {
         const result = {};
         for (const [key, nestedValue] of Object.entries(value)) {
-            result[key] = cloneValue(nestedValue);
+            result[key] = deepClone(nestedValue);
         }
         return result;
     }
     return value;
 }
-function cloneActions(source) {
-    return source.map((action) => cloneValue(action));
+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 freezeAction(action) {
+    return deepFreeze(action);
+}
+function freezeModule(module) {
+    module.actions.forEach(freezeAction);
+    return deepFreeze(module);
 }
-function cloneModules(source) {
-    return source.map((module) => ({
-        ...cloneValue(module),
-        actions: cloneActions(module.actions),
-    }));
+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 = cloneValue(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]));
@@ -69,74 +84,138 @@ function validateAction(action) {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
 }
-/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `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 = { ...cloneValue(module), actions: cloneActions(module.actions) };
         if (index >= 0) {
-            modules[index] = options.replace ? 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 = cloneValue(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) {
         throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
     }
-    return cloneModules([module])[0];
-}
-/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+    return module;
+}
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 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;
     const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
     if (direct)
-        return cloneValue(direct);
+        return direct;
     const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
     if (!crud.has(normalized)) {
         const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
         if (custom)
-            return cloneValue(custom);
+            return custom;
     }
     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

@@ -45,10 +45,12 @@ function parseData(value) {
     }
     return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
+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;
@@ -61,17 +63,17 @@ function coerceValue(value, type) {
                 return true;
             if (value === 0)
                 return false;
-            return value;
+            throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value: String(value) });
         }
         if (typeof value === 'string') {
             const normalized = value.trim().toLowerCase();
-            if (['true', '1', 'yes', 'on'].includes(normalized))
+            if (TRUTHY_STRINGS.has(normalized))
                 return true;
-            if (['false', '0', 'no', 'off'].includes(normalized))
+            if (FALSY_STRINGS.has(normalized))
                 return false;
-            return value;
+            throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value });
         }
-        return value;
+        throw new ZentaoError('E_INVALID_PARAM', { param: paramName, value: String(value) });
     }
     return value;
 }
@@ -141,12 +143,13 @@ 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(',');
                 }

package/dist/profiles/index.d.ts

@@ -1,14 +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。 */
+/**
+ * 根据 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。 */
+/**
+ * 列出本地保存的所有 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；不传 key 时返回上次使用的 profile。 */
+/**
+ * 获取指定 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。 */
+/**
+ * 添加或覆盖一个本地 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，
+ * 当前 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，并刷新最后使用时间；不传 key 时使用当前 profile。 */
+/**
+ * 切换当前使用的 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>;

package/dist/profiles/index.js

@@ -1,6 +1,11 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isNodeRuntime } from '../misc/environment.js';
 import { normalizeSiteUrl } from '../utils/index.js';
+/**
+ * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
+ *
+ * Node.js 环境会改用文件 `~/.config/zentao/zentao.json`，与此常量无关。
+ */
 export const ZENTAO_PROFILES_STORAGE_KEY = 'ZENTAO_PROFILES';
 const PROFILE_FILE_PARTS = ['.config', 'zentao', 'zentao.json'];
 function isRecord(value) {
@@ -14,9 +19,19 @@ function cloneJson(value) {
 function nowString() {
     return new Date().toISOString();
 }
-async function importNodeModule(specifier) {
-    const dynamicImport = new Function('specifier', 'return import(specifier)');
-    return dynamicImport(specifier);
+// 通过函数参数间接化 `import(specifier)`，避免打包器把 Node 内置模块拉进
+// 浏览器 bundle；同时不依赖 `new Function`/`eval`，对严格 CSP 友好。
+function importNodeModule(specifier) {
+    return import(specifier);
+}
+// 进程内串行锁：所有 read-modify-write 类的 profile 操作都通过这个队列，
+// 避免并发 `addProfile`/`switchProfile` 出现 lost update（写文件本身是原子
+// rename，但 read→modify→write 之间没有跨步保护）。跨进程并发不在保证范围内。
+let storeMutex = Promise.resolve();
+function withStoreMutex(operation) {
+    const next = storeMutex.then(operation, operation);
+    storeMutex = next.catch(() => undefined);
+    return next;
 }
 function getBrowserStorage() {
     try {
@@ -111,8 +126,19 @@ async function writeStore(store) {
         const fs = await importNodeModule('node:fs/promises');
         const path = await importNodeModule('node:path');
         const file = await getProfileFilePath();
-        await fs.mkdir(path.dirname(file), { recursive: true });
-        await fs.writeFile(file, text, 'utf8');
+        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;
     }
     const storage = getBrowserStorage();
@@ -137,16 +163,40 @@ function setFallbackCurrentProfile(store) {
         store.currentProfile = fallback ? getProfileKey(fallback) : undefined;
     }
 }
-/** 根据 profile 的账号和禅道地址生成稳定 key。 */
+/**
+ * 根据 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 function getProfileKey(profile) {
     return profileKeyFromParts(profile.account, profile.server);
 }
-/** 列出所有保存的本地 profile。 */
+/**
+ * 列出本地保存的所有 profile。
+ *
+ * Node.js 下从 `~/.config/zentao/zentao.json` 读取；浏览器下从 `localStorage` 读取。
+ * 读取过程不会写回存储；存储中无法解析的条目会被静默忽略，不会影响其余 profile。
+ *
+ * @returns 当前存储中的所有 profile（带 `key` 字段），文件不存在时返回空数组。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID`（存储内容不是合法 JSON）或
+ *   `E_PROFILE_STORAGE_UNAVAILABLE`（运行时无法访问存储）。
+ */
 export async function getAllProfiles() {
     const store = await readStore();
     return store.profiles.map(toRecord);
 }
-/** 获取指定 profile；不传 key 时返回上次使用的 profile。 */
+/**
+ * 获取指定 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 async function getProfile(profileKey) {
     const store = await readStore();
     const key = profileKey ?? store.currentProfile;
@@ -155,51 +205,90 @@ export async function getProfile(profileKey) {
     const profile = findProfile(store, key);
     return profile ? toRecord(profile) : undefined;
 }
-/** 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。 */
-export async function addProfile(profile) {
-    const store = await readStore();
-    const timestamp = nowString();
-    const normalized = normalizeProfile({
-        ...profile,
-        loginTime: profile.loginTime ?? timestamp,
-        lastUsedTime: profile.lastUsedTime ?? timestamp,
+/**
+ * 添加或覆盖一个本地 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 function addProfile(profile) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const timestamp = nowString();
+        const normalized = normalizeProfile({
+            ...profile,
+            loginTime: profile.loginTime ?? timestamp,
+            lastUsedTime: profile.lastUsedTime ?? timestamp,
+        });
+        const profileKey = getProfileKey(normalized);
+        const index = store.profiles.findIndex((item) => getProfileKey(item) === profileKey);
+        if (index >= 0) {
+            store.profiles[index] = normalized;
+        }
+        else {
+            store.profiles.push(normalized);
+        }
+        store.currentProfile = profileKey;
+        await writeStore(store);
+        return toRecord(normalized);
     });
-    const profileKey = getProfileKey(normalized);
-    const index = store.profiles.findIndex((item) => getProfileKey(item) === profileKey);
-    if (index >= 0) {
-        store.profiles[index] = normalized;
-    }
-    else {
-        store.profiles.push(normalized);
-    }
-    store.currentProfile = profileKey;
-    await writeStore(store);
-    return toRecord(normalized);
 }
-/** 删除指定 profile；返回是否实际删除了记录。 */
-export async function deleteProfile(profileKey) {
-    const store = await readStore();
-    const nextProfiles = store.profiles.filter((profile) => getProfileKey(profile) !== profileKey);
-    if (nextProfiles.length === store.profiles.length)
-        return false;
-    store.profiles = nextProfiles;
-    setFallbackCurrentProfile(store);
-    await writeStore(store);
-    return true;
-}
-/** 切换当前使用的 profile，并刷新最后使用时间；不传 key 时使用当前 profile。 */
-export async function switchProfile(profileKey) {
-    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 });
-    }
-    profile.lastUsedTime = nowString();
-    store.currentProfile = key;
-    await writeStore(store);
-    return toRecord(profile);
+/**
+ * 删除指定 profile。
+ *
+ * 若被删除的是当前 profile，会回退为列表中最近一次写入的 profile；若已无任何 profile，
+ * 当前 profile 会被清空。操作同样通过进程内串行锁保护。
+ *
+ * @param profileKey - 要删除的 profile key。
+ * @returns 当且仅当确实删除了某条记录时返回 `true`；key 不存在时返回 `false` 且不会写盘。
+ * @throws {ZentaoError} `E_PROFILE_STORAGE_INVALID` / `E_PROFILE_STORAGE_UNAVAILABLE`。
+ */
+export function deleteProfile(profileKey) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const nextProfiles = store.profiles.filter((profile) => getProfileKey(profile) !== profileKey);
+        if (nextProfiles.length === store.profiles.length)
+            return false;
+        store.profiles = nextProfiles;
+        setFallbackCurrentProfile(store);
+        await writeStore(store);
+        return true;
+    });
+}
+/**
+ * 切换当前使用的 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 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 });
+        }
+        profile.lastUsedTime = nowString();
+        store.currentProfile = key;
+        await writeStore(store);
+        return toRecord(profile);
+    });
 }

package/dist/request/index.d.ts

@@ -3,5 +3,14 @@ import type { RequestOptions, ResponseData } from '../types/index.js';
  * 按模块动作名请求禅道 API。
  *
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
+ * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ *
+ * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
+ * @param name - 模块动作名，例如 `product/list`。
+ * @param params - 请求参数。
+ * @param options - 请求选项。
+ * @returns 归一化后的禅道 API 响应。
+ * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
-export declare function request(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData>;
+export declare function request<T = unknown>(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;