zentao-api 0.1.0 → 0.2.0-beta.2

package/dist/modules/registry.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+import { BUILTIN_MODULES } from './generated.js';
+export { BUILTIN_MODULES };
+export declare const MODULES: ModuleDefinition[];
+export interface DefineModulesOptions {
+    /** 同名模块是否整体替换；默认合并模块定义和动作。 */
+    replace?: boolean;
+}
+/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
+export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
+/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
+/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+export declare function getModule(moduleName: string): ModuleDefinition;
+/** 获取指定模块动作；`ls` 会作为 `list` 的别名处理。 */
+export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+/** 返回当前运行时注册表中的所有模块名。 */
+export declare function getModuleNames(): string[];
+/** 判断模块名是否已注册，大小写不敏感。 */
+export declare function isModuleName(moduleName: string): boolean;
+/** @internal */
+export declare function resetModuleDefinitions(): void;

package/dist/modules/registry.js

@@ -0,0 +1,142 @@
+import { ZentaoError } from '../misc/errors.js';
+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);
+let moduleMap = buildModuleMap(modules);
+function cloneValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(cloneValue);
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            result[key] = cloneValue(nestedValue);
+        }
+        return result;
+    }
+    return value;
+}
+function cloneActions(source) {
+    return source.map((action) => cloneValue(action));
+}
+function cloneModules(source) {
+    return source.map((module) => ({
+        ...cloneValue(module),
+        actions: cloneActions(module.actions),
+    }));
+}
+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);
+    for (const action of extension) {
+        const index = findActionIndex(next, String(action.name));
+        const clone = cloneValue(action);
+        if (index >= 0) {
+            next[index] = clone;
+        }
+        else {
+            next.push(clone);
+        }
+    }
+    return next;
+}
+function mergeModule(base, extension) {
+    return {
+        ...base,
+        ...extension,
+        actions: mergeActions(base.actions, extension.actions),
+    };
+}
+function buildModuleMap(source) {
+    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
+}
+function rebuildMap() {
+    moduleMap = buildModuleMap(modules);
+}
+function validateModule(module) {
+    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
+        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
+    }
+}
+function validateAction(action) {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+}
+/** 定义或扩展模块；同名模块默认合并动作，`replace` 为真时整体替换，未知模块追加。 */
+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);
+        }
+        else {
+            modules.push(next);
+        }
+    }
+    rebuildMap();
+}
+/** 为已存在模块定义或覆盖动作；同名动作替换，未知动作追加。 */
+export function defineModuleActions(moduleName, input) {
+    const module = moduleMap.get(moduleName.toLowerCase());
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    for (const action of asArray(input)) {
+        validateAction(action);
+        const index = findActionIndex(module.actions, String(action.name));
+        const next = cloneValue(action);
+        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
+        if (index >= 0) {
+            module.actions[index] = next;
+        }
+        else {
+            module.actions.push(next);
+        }
+    }
+}
+/** 获取模块定义；模块不存在时抛出 {@link ZentaoError}。 */
+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` 的别名处理。 */
+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);
+    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);
+    }
+    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+}
+/** 返回当前运行时注册表中的所有模块名。 */
+export function getModuleNames() {
+    return modules.map((module) => module.name);
+}
+/** 判断模块名是否已注册，大小写不敏感。 */
+export function isModuleName(moduleName) {
+    return moduleMap.has(moduleName.toLowerCase());
+}
+/** @internal */
+export function resetModuleDefinitions() {
+    modules = cloneModules(BUILTIN_MODULES);
+    rebuildMap();
+}

package/dist/modules/resolve.d.ts

@@ -0,0 +1,7 @@
+import type { ListPagerInfo, ModuleAction, ModuleDefinition, ResolvedModuleCommand } from '../types/index.js';
+/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
+export declare function resolveModuleCommand(module: ModuleDefinition, actionName: string, params?: Record<string, unknown>): ResolvedModuleCommand;
+/** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
+export declare function extractResult(action: ModuleAction, response: Record<string, unknown>): unknown;
+/** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
+export declare function extractPager(action: ModuleAction, response: Record<string, unknown>): ListPagerInfo | undefined;

package/dist/modules/resolve.js

@@ -0,0 +1,206 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getNestedValue, isRecord } from '../utils/index.js';
+import { getModuleAction } from './registry.js';
+const SCOPE_MAP = {
+    product: 'products',
+    project: 'projects',
+    execution: 'executions',
+};
+const SCOPE_KEY_ORDER = ['execution', 'project', 'product'];
+/** 从调用参数中推断作用域列表路径，优先级为执行 > 项目 > 产品。 */
+function pickScope(params) {
+    for (const key of SCOPE_KEY_ORDER) {
+        const value = params[key] ?? params[`${key}ID`];
+        if (value === undefined || value === null || value === '')
+            continue;
+        const numberValue = Number(value);
+        if (!Number.isNaN(numberValue)) {
+            return { scope: SCOPE_MAP[key], scopeID: numberValue };
+        }
+    }
+    return undefined;
+}
+/** 替换动作路径模板中的 `{param}` 占位符。 */
+function resolvePath(action, values) {
+    return action.path.replace(/\{(\w+)\}/g, (_, key) => {
+        const value = values[key];
+        if (value === undefined || value === '') {
+            throw new ZentaoError('E_MISSING_PARAM', { param: key });
+        }
+        return String(value);
+    });
+}
+/** 支持用户通过 `params.data` 传入 JSON 字符串或对象作为请求体基础值。 */
+function parseData(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string') {
+        try {
+            const parsed = JSON.parse(value);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/** 按 OpenAPI schema 的基础类型对参数做轻量转换。 */
+function coerceValue(value, type) {
+    if (value === undefined)
+        return undefined;
+    if (type === 'number' || type === 'integer') {
+        const numberValue = Number(value);
+        return Number.isNaN(numberValue) ? value : numberValue;
+    }
+    if (type === 'boolean') {
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number') {
+            if (value === 1)
+                return true;
+            if (value === 0)
+                return false;
+            return value;
+        }
+        if (typeof value === 'string') {
+            const normalized = value.trim().toLowerCase();
+            if (['true', '1', 'yes', 'on'].includes(normalized))
+                return true;
+            if (['false', '0', 'no', 'off'].includes(normalized))
+                return false;
+            return value;
+        }
+        return value;
+    }
+    return value;
+}
+/** 将模块名、动作名和调用参数解析为实际 API 请求路径、查询参数和请求体。 */
+export function resolveModuleCommand(module, actionName, params = {}) {
+    const action = getModuleAction(module.name, actionName);
+    const pathValues = {};
+    const pathParamNames = Object.keys(action.pathParams ?? {});
+    // 生成定义中的 scope 列表接口会统一成 /{scope}/{scopeID}/xxx。
+    if (pathParamNames.includes('scope')) {
+        const scope = pickScope(params);
+        if (!scope)
+            throw new ZentaoError('E_MISSING_PARAM', { param: 'product/project/execution' });
+        pathValues.scope = scope.scope;
+        pathValues.scopeID = scope.scopeID;
+    }
+    const idParamName = pathParamNames.find((key) => key.endsWith('ID') && key !== 'scopeID');
+    const idValue = params.id ?? params[`${module.name}ID`] ?? (idParamName ? params[idParamName] : undefined);
+    const id = idValue === undefined ? undefined : Number(idValue);
+    if (idParamName && id !== undefined && !Number.isNaN(id)) {
+        pathValues[idParamName] = id;
+    }
+    // pathParams 中未显式传值的参数，可从定义里的默认值或第一个可选项补齐。
+    for (const key of pathParamNames) {
+        if (key === 'scope' || key === 'scopeID' || pathValues[key] !== undefined)
+            continue;
+        const definition = action.pathParams?.[key];
+        const value = params[key];
+        if (value !== undefined) {
+            pathValues[key] = value;
+            continue;
+        }
+        if (typeof definition === 'object') {
+            if (definition.defaultValue !== undefined) {
+                pathValues[key] = definition.defaultValue;
+            }
+            else if (definition.options?.[0]?.value !== undefined) {
+                pathValues[key] = definition.options[0].value;
+            }
+        }
+        if (pathValues[key] === undefined) {
+            throw new ZentaoError('E_MISSING_PARAM', { param: key });
+        }
+    }
+    // 查询参数只从 action.params 中声明过的字段生成，避免把 body 字段误放到 URL 上。
+    const query = {};
+    for (const param of action.params ?? []) {
+        let value = params[param.name];
+        if (value === undefined && param.name === 'pageID') {
+            value = params.page;
+        }
+        if (value === undefined) {
+            value = param.defaultValue ?? param.options?.[0]?.value;
+        }
+        if (value === undefined && param.required) {
+            throw new ZentaoError('E_MISSING_PARAM', { param: param.name });
+        }
+        if (value !== undefined) {
+            query[param.name] = value;
+        }
+    }
+    let data = parseData(params.data);
+    if (action.requestBody?.schema?.type === 'object') {
+        data = data ? { ...data } : {};
+        const schema = action.requestBody.schema;
+        const required = new Set(schema.required ?? []);
+        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;
+            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)) {
+                if (typeof value === 'string') {
+                    value = value.split(',');
+                }
+                else if (!hasDataValue || !isRecord(value)) {
+                    value = [value];
+                }
+            }
+            if (value !== undefined) {
+                data[key] = value;
+            }
+        }
+    }
+    return {
+        module: module.name,
+        action,
+        params,
+        path: resolvePath(action, pathValues),
+        query,
+        data,
+        id: id === undefined || Number.isNaN(id) ? undefined : id,
+    };
+}
+/** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
+export function extractResult(action, response) {
+    const getter = action.resultGetter;
+    if (!getter)
+        return response.data ?? response;
+    if (typeof getter === 'function')
+        return getter(response, {});
+    if (typeof getter === 'string')
+        return getNestedValue(response, getter);
+    const result = {};
+    for (const [targetKey, sourceKey] of Object.entries(getter)) {
+        result[targetKey] = response[sourceKey];
+    }
+    return result;
+}
+/** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
+export function extractPager(action, response) {
+    const getter = action.pagerGetter;
+    if (!getter)
+        return response.pager;
+    if (typeof getter === 'function')
+        return getter(response, {});
+    if (typeof getter === 'string')
+        return getNestedValue(response, getter);
+    const page = response[getter.pageID];
+    const recPerPage = response[getter.recPerPage];
+    const recTotal = response[getter.recTotal];
+    if (page === undefined || recPerPage === undefined || recTotal === undefined)
+        return undefined;
+    return {
+        pageID: Number(page),
+        recPerPage: Number(recPerPage),
+        recTotal: Number(recTotal),
+    };
+}

package/dist/profiles/index.d.ts

@@ -0,0 +1,14 @@
+import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+export declare const ZENTAO_PROFILES_STORAGE_KEY = "ZENTAO_PROFILES";
+/** 根据 profile 的账号和禅道地址生成稳定 key。 */
+export declare function getProfileKey(profile: Pick<ZentaoProfile, 'account' | 'server'>): string;
+/** 列出所有保存的本地 profile。 */
+export declare function getAllProfiles(): Promise<ZentaoProfileRecord[]>;
+/** 获取指定 profile；不传 key 时返回上次使用的 profile。 */
+export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRecord | undefined>;
+/** 添加或覆盖一个本地 profile，并把它设置为当前使用的 profile。 */
+export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 删除指定 profile；返回是否实际删除了记录。 */
+export declare function deleteProfile(profileKey: string): Promise<boolean>;
+/** 切换当前使用的 profile，并刷新最后使用时间；不传 key 时使用当前 profile。 */
+export declare function switchProfile(profileKey?: string): Promise<ZentaoProfileRecord>;

package/dist/profiles/index.js

@@ -0,0 +1,205 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isNodeRuntime } from '../misc/environment.js';
+import { normalizeSiteUrl } from '../utils/index.js';
+export const ZENTAO_PROFILES_STORAGE_KEY = 'ZENTAO_PROFILES';
+const PROFILE_FILE_PARTS = ['.config', 'zentao', 'zentao.json'];
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneJson(value) {
+    if (value === undefined)
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+function nowString() {
+    return new Date().toISOString();
+}
+async function importNodeModule(specifier) {
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    return dynamicImport(specifier);
+}
+function getBrowserStorage() {
+    try {
+        return globalThis.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function getProfileFilePath() {
+    const path = await importNodeModule('node:path');
+    const home = process.env.HOME
+        ?? process.env.USERPROFILE
+        ?? (await importNodeModule('node:os')).homedir();
+    if (!home) {
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    }
+    return path.join(home, ...PROFILE_FILE_PARTS);
+}
+function profileKeyFromParts(account, server) {
+    const normalizedAccount = account.trim();
+    const normalizedServer = normalizeSiteUrl(server);
+    if (!normalizedAccount)
+        throw new ZentaoError('E_INVALID_PROFILE');
+    return `${normalizedAccount}@${normalizedServer}`;
+}
+function normalizeProfile(profile) {
+    if (!isRecord(profile) || typeof profile.server !== 'string' || typeof profile.account !== 'string' || typeof profile.token !== 'string') {
+        throw new ZentaoError('E_INVALID_PROFILE');
+    }
+    const token = profile.token.trim();
+    if (!token)
+        throw new ZentaoError('E_INVALID_PROFILE');
+    const copy = cloneJson(profile);
+    delete copy.key;
+    return {
+        ...copy,
+        server: normalizeSiteUrl(profile.server),
+        account: profile.account.trim(),
+        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 [];
+            }
+        })
+        : [];
+    const currentProfile = typeof raw.currentProfile === 'string' ? raw.currentProfile : undefined;
+    return currentProfile ? { currentProfile, profiles } : { profiles };
+}
+function parseStore(text) {
+    try {
+        return normalizeStore(JSON.parse(text));
+    }
+    catch (error) {
+        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: [] };
+            }
+            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: [] };
+}
+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();
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, text, 'utf8');
+        return;
+    }
+    const storage = getBrowserStorage();
+    if (!storage) {
+        throw new ZentaoError('E_PROFILE_STORAGE_UNAVAILABLE');
+    }
+    storage.setItem(ZENTAO_PROFILES_STORAGE_KEY, text);
+}
+function toRecord(profile) {
+    const normalized = normalizeProfile(profile);
+    return {
+        ...cloneJson(normalized),
+        key: getProfileKey(normalized),
+    };
+}
+function findProfile(store, profileKey) {
+    return store.profiles.find((profile) => getProfileKey(profile) === profileKey);
+}
+function setFallbackCurrentProfile(store) {
+    if (!store.currentProfile || !findProfile(store, store.currentProfile)) {
+        const fallback = store.profiles.at(-1);
+        store.currentProfile = fallback ? getProfileKey(fallback) : undefined;
+    }
+}
+/** 根据 profile 的账号和禅道地址生成稳定 key。 */
+export function getProfileKey(profile) {
+    return profileKeyFromParts(profile.account, profile.server);
+}
+/** 列出所有保存的本地 profile。 */
+export async function getAllProfiles() {
+    const store = await readStore();
+    return store.profiles.map(toRecord);
+}
+/** 获取指定 profile；不传 key 时返回上次使用的 profile。 */
+export async function getProfile(profileKey) {
+    const store = await readStore();
+    const key = profileKey ?? store.currentProfile;
+    if (!key)
+        return undefined;
+    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,
+    });
+    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);
+}

package/dist/request/index.d.ts

@@ -0,0 +1,7 @@
+import type { RequestOptions, ResponseData } from '../types/index.js';
+/**
+ * 按模块动作名请求禅道 API。
+ *
+ * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ */
+export declare function request(name: `${string}/${string}`, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData>;

package/dist/request/index.js

@@ -0,0 +1,65 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getGlobalOptions } from '../misc/global-options.js';
+import { getModule } from '../modules/registry.js';
+import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
+/** 将 `moduleName/methodName` 形式的请求名拆成模块名和动作名。 */
+function splitRequestName(name) {
+    const index = name.indexOf('/');
+    if (index <= 0 || index === name.length - 1) {
+        throw new ZentaoError('E_INVALID_REQUEST_NAME');
+    }
+    return {
+        moduleName: name.slice(0, index),
+        actionName: name.slice(index + 1),
+    };
+}
+/** 将禅道原始响应归一化为稳定的 ResponseData 结构。 */
+function normalizeResponse(command, raw, limit) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { status: 'success', data: raw };
+    }
+    const record = raw;
+    const status = record.status === 'fail' ? 'fail' : 'success';
+    let data = extractResult(command.action, record);
+    const numericLimit = limit === undefined ? undefined : Number(limit);
+    if (Array.isArray(data) && numericLimit !== undefined && !Number.isNaN(numericLimit)) {
+        data = data.slice(0, numericLimit);
+    }
+    const pager = extractPager(command.action, record);
+    return {
+        status,
+        message: typeof record.message === 'string' ? record.message : undefined,
+        data,
+        pager: pager ? {
+            total: Number(pager.recTotal),
+            page: Number(pager.pageID),
+            recPerPage: Number(pager.recPerPage),
+        } : undefined,
+    };
+}
+/**
+ * 按模块动作名请求禅道 API。
+ *
+ * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
+ */
+export async function request(name, params = {}, options = {}) {
+    const globals = getGlobalOptions();
+    const client = options.client ?? globals.client;
+    if (!client) {
+        throw new ZentaoError('E_NO_GLOBAL_CLIENT');
+    }
+    const { moduleName, actionName } = splitRequestName(name);
+    const module = getModule(moduleName);
+    // recPerPage 是最常用的列表参数，允许在全局或本次调用中统一覆盖。
+    const recPerPage = params.recPerPage ?? options.recPerPage ?? globals.recPerPage;
+    const mergedParams = recPerPage === undefined ? params : { ...params, recPerPage };
+    const command = resolveModuleCommand(module, actionName, mergedParams);
+    const raw = await client.request(command.path, {
+        method: String(command.action.method).toUpperCase(),
+        query: command.query,
+        body: command.data,
+        timeout: options.timeout ?? globals.timeout,
+        insecure: options.insecure ?? globals.insecure,
+    });
+    return normalizeResponse(command, raw, options.limit ?? globals.limit);
+}