zentao-api 0.3.2 → 0.3.3

package/dist/modules/registry-store.js

@@ -1,6 +1,23 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isRecord } from '../utils/object.js';
 import { BUILTIN_MODULES } from './generated.js';
+// 动作类型到 HTTP 方法 / 结果形态的默认推导表：当动作未显式声明 method / resultType 时按 type 补齐。
+const METHOD_BY_TYPE = {
+    list: 'get',
+    get: 'get',
+    create: 'post',
+    update: 'put',
+    delete: 'delete',
+    action: 'post',
+};
+const RESULT_TYPE_BY_TYPE = {
+    list: 'list',
+    get: 'object',
+    create: 'object',
+    update: 'object',
+    delete: 'text',
+    action: 'text',
+};
 // 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
 // - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
 // - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
@@ -57,8 +74,32 @@ export function deepFreeze(value) {
     }
     return Object.freeze(value);
 }
+/**
+ * 按 {@link ModuleAction.type} 就地补齐省略的 `method` / `resultType`。
+ *
+ * 已显式声明的字段保持不变；当 `type` 无法推导出对应默认值时抛错，提示显式指定。
+ *
+ * @throws {ZentaoError} `E_INDETERMINATE_ACTION_METHOD` / `E_INDETERMINATE_ACTION_RESULT_TYPE`
+ */
+export function normalizeAction(action) {
+    if (action.method === undefined) {
+        const method = METHOD_BY_TYPE[action.type];
+        if (method === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_METHOD', { action: String(action.name), type: String(action.type) });
+        }
+        action.method = method;
+    }
+    if (action.resultType === undefined) {
+        const resultType = RESULT_TYPE_BY_TYPE[action.type];
+        if (resultType === undefined) {
+            throw new ZentaoError('E_INDETERMINATE_ACTION_RESULT_TYPE', { action: String(action.name), type: String(action.type) });
+        }
+        action.resultType = resultType;
+    }
+    return action;
+}
 export function freezeAction(action) {
-    return deepFreeze(action);
+    return deepFreeze(normalizeAction(action));
 }
 export function freezeModule(module) {
     module.actions.forEach(freezeAction);
@@ -102,7 +143,14 @@ export function validateModule(module) {
     }
 }
 export function validateAction(action) {
-    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    // method / resultType 可省略（由 normalizeAction 按 type 推导），但显式给出时必须是字符串。
+    if (action.method !== undefined && typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+    if (action.resultType !== undefined && typeof action.resultType !== 'string') {
         throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
     }
 }

package/dist/modules/registry.d.ts

@@ -173,7 +173,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly userID: "用户ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "program";
@@ -354,7 +353,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly programID: "项目集ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "product";
@@ -579,7 +577,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly productID: "产品ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "project";
@@ -775,7 +772,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly projectID: "项目ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "execution";
@@ -1028,7 +1024,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly executionID: "执行ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "productplan";
@@ -1231,7 +1226,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly productplanID: "产品计划ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "story";
@@ -1479,7 +1473,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly storyID: "需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活需求";
@@ -1507,7 +1500,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更需求";
@@ -1547,7 +1539,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭需求";
@@ -1576,7 +1567,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "epic";
@@ -1809,7 +1799,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly epicID: "业务需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活业务需求";
@@ -1837,7 +1826,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更业务需求";
@@ -1877,7 +1865,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["reviewer"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭业务需求";
@@ -1906,7 +1893,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "requirement";
@@ -2138,7 +2124,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly requirementID: "用户需求ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活用户需求";
@@ -2166,7 +2151,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "change";
         readonly display: "变更用户需求";
@@ -2198,7 +2182,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭用户需求";
@@ -2227,7 +2210,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "bug";
@@ -2465,7 +2447,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly bugID: "Bug ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活Bug";
@@ -2500,7 +2481,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭Bug";
@@ -2524,7 +2504,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "resolve";
         readonly display: "解决Bug";
@@ -2565,7 +2544,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["resolution"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testcase";
@@ -2816,7 +2794,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly testcasID: "测试用例ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "task";
@@ -3050,7 +3027,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly taskID: "任务ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活任务";
@@ -3083,7 +3059,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭任务";
@@ -3107,7 +3082,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "finish";
         readonly display: "完成任务";
@@ -3154,7 +3128,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["currentConsumed", "realStarted", "finishedDate"];
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "start";
         readonly display: "启动任务";
@@ -3197,7 +3170,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["realStarted"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "feedback";
@@ -3403,7 +3375,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly feedbackID: "反馈ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活反馈";
@@ -3431,7 +3402,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭反馈";
@@ -3460,7 +3430,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "ticket";
@@ -3682,7 +3651,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly ticketID: "工单ID";
         };
-        readonly render: "action";
     }, {
         readonly name: "activate";
         readonly display: "激活工单";
@@ -3710,7 +3678,6 @@ export declare const MODULES: readonly [{
                 };
             };
         };
-        readonly render: "action";
     }, {
         readonly name: "close";
         readonly display: "关闭工单";
@@ -3739,7 +3706,6 @@ export declare const MODULES: readonly [{
                 readonly required: readonly ["closedReason", "comment"];
             };
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "system";
@@ -3992,7 +3958,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly buildID: "版本ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "testtask";
@@ -4157,7 +4122,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly testtaskID: "测试单ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "release";
@@ -4290,7 +4254,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly releasID: "发布ID";
         };
-        readonly render: "action";
     }];
 }, {
     readonly name: "file";
@@ -4327,7 +4290,6 @@ export declare const MODULES: readonly [{
         readonly pathParams: {
             readonly fileID: "附件ID";
         };
-        readonly render: "action";
     }];
 }];
 export { type DefineModulesOptions, defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';

package/dist/modules/resolve.d.ts

@@ -2,6 +2,6 @@ import type { ListPagerInfo, ModuleAction, ModuleDefinition, ResolvedModuleComma
 /** 将模块名、动作名和调用参数解析为实际 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;
+export declare function extractResult(action: ModuleAction, response: Record<string, unknown>, params?: Record<string, unknown>): unknown;
 /** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
-export declare function extractPager(action: ModuleAction, response: Record<string, unknown>): ListPagerInfo | undefined;
+export declare function extractPager(action: ModuleAction, response: Record<string, unknown>, params?: Record<string, unknown>): ListPagerInfo | undefined;

package/dist/modules/resolve.js

@@ -173,32 +173,32 @@ export function resolveModuleCommand(module, actionName, params = {}) {
     };
 }
 /** 根据动作定义中的 resultGetter，从原始响应里提取业务数据。 */
-export function extractResult(action, response) {
+export function extractResult(action, response, params = {}) {
     const getter = action.resultGetter;
     if (!getter)
         return response.data ?? response;
     if (typeof getter === 'function')
-        return getter(response, {});
+        return getter(response, params);
     if (typeof getter === 'string')
         return getNestedValue(response, getter);
     const result = {};
     for (const [targetKey, sourceKey] of Object.entries(getter)) {
-        result[targetKey] = response[sourceKey];
+        result[targetKey] = getNestedValue(response, sourceKey);
     }
     return result;
 }
 /** 根据动作定义中的 pagerGetter，从原始响应里提取分页信息。 */
-export function extractPager(action, response) {
+export function extractPager(action, response, params = {}) {
     const getter = action.pagerGetter;
     if (!getter)
         return response.pager;
     if (typeof getter === 'function')
-        return getter(response, {});
+        return getter(response, params);
     if (typeof getter === 'string')
         return getNestedValue(response, getter);
-    const page = response[getter.pageID];
-    const recPerPage = response[getter.recPerPage];
-    const recTotal = response[getter.recTotal];
+    const page = getNestedValue(response, getter.pageID);
+    const recPerPage = getNestedValue(response, getter.recPerPage);
+    const recTotal = getNestedValue(response, getter.recTotal);
     if (page === undefined || recPerPage === undefined || recTotal === undefined)
         return undefined;
     return {

package/dist/request/index.d.ts

@@ -104,6 +104,9 @@ export type RequestResultFor<Name extends BuiltinRequestName> = ActionOfRequest<
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
  *
+ * 对 `update` 动作，当 `options.autoFill` 或全局 `autoFill` 为真时，会先 GET 当前对象，
+ * 用现值补齐用户未显式传入的 body 字段后再 PUT，避免禅道覆盖未提交字段。详见 {@link RequestOptions.autoFill}。
+ *
  * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
  * @param name - 请求名，例如 `product`、`product/list` 或 `product/1`。
  * @param params - 请求参数。

package/dist/request/index.js

@@ -1,6 +1,6 @@
 import { ZentaoError } from '../misc/errors.js';
 import { getGlobalOptions } from '../misc/global-options.js';
-import { getModule } from '../modules/registry.js';
+import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveModuleCommand } from '../modules/resolve.js';
 import { isRecord, processData } from '../utils/index.js';
 /** 将 `moduleName`、`moduleName/methodName` 或 `moduleName/<objectID>` 请求名拆成模块名、动作名和对象 ID。 */
@@ -30,6 +30,54 @@ function splitRequestName(name) {
         actionName,
     };
 }
+/** 解析 `params.data` 中用户显式传入的 body 字段名，用于 autoFill 判断字段归属。 */
+function getExplicitDataKeys(data) {
+    let value = data;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return new Set();
+        }
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return new Set(Object.keys(value));
+    }
+    return new Set();
+}
+/**
+ * 在执行 `update` 动作前，用当前对象的现值填充用户未显式传入的 body 字段。
+ *
+ * 仅当模块存在 `type: 'get'` 动作且 update 动作声明了对象类型 body schema 时生效；
+ * 否则原样返回参数。GET 失败或返回非对象时同样跳过填充，交由后续 PUT 正常处理。
+ *
+ * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
+ * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
+ */
+async function autoFillUpdateParams(module, action, params, options) {
+    const properties = action.requestBody?.schema?.properties;
+    const getAction = module.actions.find((candidate) => candidate.type === 'get');
+    if (!properties || !getAction)
+        return params;
+    const current = (await request(`${module.name}/${getAction.name}`, params, {
+        client: options.client,
+        timeout: options.timeout,
+        insecure: options.insecure,
+        throwOnFail: options.throwOnFail,
+    })).data;
+    if (!isRecord(current))
+        return params;
+    const explicitDataKeys = getExplicitDataKeys(params.data);
+    const filled = { ...params };
+    for (const key of Object.keys(properties)) {
+        const userProvided = Object.prototype.hasOwnProperty.call(params, key) || explicitDataKeys.has(key);
+        if (!userProvided && Object.prototype.hasOwnProperty.call(current, key)) {
+            filled[key] = current[key];
+        }
+    }
+    return filled;
+}
 function stringifyMessage(value) {
     if (typeof value === 'string')
         return value;
@@ -96,9 +144,9 @@ function normalizeResponse(command, raw, options) {
     }
     const record = raw;
     const status = record.status === 'fail' ? 'fail' : 'success';
-    const data = applyProcessing(extractResult(command.action, record), options);
+    const data = applyProcessing(extractResult(command.action, record, command.params), options);
     const rawMessage = record.message;
-    const pager = extractPager(command.action, record);
+    const pager = extractPager(command.action, record, command.params);
     const response = {
         status,
         message: stringifyMessage(rawMessage),
@@ -134,7 +182,13 @@ export async function request(name, params = {}, options = {}) {
         ...(id !== undefined ? { id } : {}),
         ...(recPerPage !== undefined ? { recPerPage } : {}),
     };
-    const command = resolveModuleCommand(module, actionName, mergedParams);
+    // autoFill：update 动作先 GET 当前对象，用现值补齐用户未显式传入的字段，
+    // 避免禅道 PUT 把未提交字段覆盖为空。
+    const action = getModuleAction(moduleName, actionName);
+    const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
+        ? await autoFillUpdateParams(module, action, mergedParams, options)
+        : mergedParams;
+    const command = resolveModuleCommand(module, actionName, finalParams);
     const raw = await client.request(command.path, {
         method: String(command.action.method).toUpperCase(),
         query: command.query,

package/dist/types/module.d.ts

@@ -50,31 +50,42 @@ export interface ModuleActionResponse {
     /** 响应示例。 */
     example?: unknown;
 }
-/** 模块动作渲染目标类型；保留给 CLI 等上层应用使用。 */
-export type ModuleActionResultRenderType = 'markdown' | 'json' | 'raw';
-/** 模块动作自定义渲染函数类型；SDK 本身不直接渲染终端输出。 */
-export type ModuleActionResultRender = (result: unknown, type: ModuleActionResultRenderType, action: ModuleAction) => string;
-/** 从原始响应中提取分页字段时使用的字段映射。 */
+/** 从原始响应中提取分页字段时使用的字段映射，值为原始响应中的字段路径（支持 `a.b` 嵌套）。 */
 export interface ModuleActionPagerGetterMap {
-    /** 当前页码字段名。 */
+    /** 当前页码字段路径。 */
     pageID: string;
-    /** 每页记录数字段名。 */
+    /** 每页记录数字段路径。 */
     recPerPage: string;
-    /** 总记录数字段名。 */
+    /** 总记录数字段路径。 */
     recTotal: string;
 }
+/**
+ * 从原始响应中重映射业务数据字段的映射表。
+ * 键为输出字段名，值为原始响应中的字段路径（支持 `a.b` 嵌套）。
+ */
+export type ModuleActionResultFieldMap = Readonly<Record<string, string>>;
+/**
+ * 从原始响应中提取数据时使用的函数形态。
+ * @param data 原始响应对象。
+ * @param params 触发本次请求的原始调用参数。
+ */
+export type ModuleActionGetterFn<T> = (data: unknown, params: Record<string, unknown>) => T;
 /** 禅道模块中的单个 API 动作定义。 */
 export interface ModuleAction {
     /** 动作名称，例如 `list`、`get`、`close`。 */
     name: ModuleActionName;
-    /** 动作类型，决定高阶 request 的路径/参数解析策略。 */
+    /** 动作类型，决定高阶 request 的路径/参数解析策略，并在 `method`、`resultType` 省略时作为推导依据。 */
     type: ModuleActionType;
     /** 面向用户展示的动作名称。 */
     display?: string;
     /** 动作说明。 */
     description?: string;
-    /** HTTP 方法。 */
-    method: ModuleActionMethod;
+    /**
+     * HTTP 方法；省略时按 {@link type} 自动推导：
+     * `list`/`get` → `GET`、`create`/`action` → `POST`、`update` → `PUT`、`delete` → `DELETE`。
+     * 当 `type` 无法推导出方法时抛出 `E_INDETERMINATE_ACTION_METHOD`。
+     */
+    method?: ModuleActionMethod;
     /** API 路径模板，可包含 `{productID}` 等路径参数。 */
     path: string;
     /** 路径参数定义；字符串为说明，对象可携带默认值和可选项。 */
@@ -83,14 +94,22 @@ export interface ModuleAction {
     params?: readonly ModuleActionParam[];
     /** 请求体定义。 */
     requestBody?: ModuleActionRequestBody;
-    /** 结果形态。 */
-    resultType: ModuleActionResultType;
-    /** 从原始响应中提取分页信息的位置或函数。 */
-    pagerGetter?: string | ModuleActionPagerGetterMap | ((data: unknown, params: Record<string, unknown>) => ListPagerInfo);
-    /** 从原始响应中提取业务数据的位置或函数。 */
-    resultGetter?: string | Record<string, string> | ((data: unknown, params: Record<string, unknown>) => unknown);
-    /** 供上层应用使用的渲染配置。 */
-    render?: string | ModuleActionResultRender | Record<ModuleActionResultRenderType, ModuleActionResultRender>;
+    /**
+     * 结果形态；省略时按 {@link type} 自动推导：
+     * `list` → `list`、`get`/`create`/`update` → `object`、`delete`/`action` → `text`。
+     * 当 `type` 无法推导出结果形态时抛出 `E_INDETERMINATE_ACTION_RESULT_TYPE`。
+     */
+    resultType?: ModuleActionResultType;
+    /**
+     * 从原始响应中提取分页信息的位置或函数：
+     * 字符串为字段路径（支持 `a.b` 嵌套）、对象为字段映射、函数则接收原始响应与调用参数。
+     */
+    pagerGetter?: string | ModuleActionPagerGetterMap | ModuleActionGetterFn<ListPagerInfo>;
+    /**
+     * 从原始响应中提取业务数据的位置或函数：
+     * 字符串为字段路径（支持 `a.b` 嵌套）、对象为字段映射、函数则接收原始响应与调用参数。
+     */
+    resultGetter?: string | ModuleActionResultFieldMap | ModuleActionGetterFn<unknown>;
 }
 /** 内置模块名称，同时允许用户扩展自定义模块名。 */
 export type ModuleName = 'user' | 'program' | 'product' | 'project' | 'execution' | 'productplan' | 'story' | 'epic' | 'requirement' | 'bug' | 'testcase' | 'task' | 'feedback' | 'ticket' | 'system' | 'build' | 'testtask' | 'release' | 'file' | (string & {});

package/dist/types/options.d.ts

@@ -16,6 +16,12 @@ export interface GlobalOptions {
     persistProfiles?: boolean;
     /** 当禅道服务端返回 `{ status: "fail" }` 时是否抛出 `E_API_FAILED`，默认 false。 */
     throwOnFail?: boolean;
+    /**
+     * 是否在执行 `update` 操作时自动填充未传入的字段，默认 false。
+     *
+     * 优先级低于单次请求选项；语义见 {@link RequestOptions.autoFill}。
+     */
+    autoFill?: boolean;
 }
 /** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
 export interface RequestOptions extends ProcessListOptions {
@@ -32,4 +38,14 @@ export interface RequestOptions extends ProcessListOptions {
      * 不传时回落到全局 `throwOnFail`，默认 false（保留原始失败响应）。
      */
     throwOnFail?: boolean;
+    /**
+     * 是否在执行 `update` 操作时自动填充未传入的字段。
+     *
+     * 设为 `true` 后，会先 GET 当前对象，把用户未显式传入（含 `params.data`）且
+     * 动作 body schema 中声明的字段用现值补齐，再发起 PUT，避免禅道用空值覆盖未提交字段。
+     * 因此只需传想修改的字段即可。仅对 `type: 'update'` 且模块存在 `type: 'get'` 动作时生效。
+     *
+     * 不传时回落到全局 `autoFill`，默认 false。
+     */
+    autoFill?: boolean;
 }

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-06-29T10:27:50.494Z";
-const fallbackVersion = "0.3.2";
+const fallbackBuild = "2026-06-30T10:00:59.615Z";
+const fallbackVersion = "0.3.3";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

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