@yanhaidao/wecom 2.3.160 → 2.3.180

package/src/capability/doc/client.ts

@@ -391,19 +391,23 @@ export class WecomDocClient {
             // Need to check current auth status
             try {
                 const currentAuth = await this.getDocAuth({ agent, docId });
-                const viewerUserIds = new Set(
-                    (currentAuth.docMembers || [])
-                        .filter((m: any) => m.type === 1 && m.userid)
-                        .map((m: any) => m.userid)
-                );
-                const newCollaboratorUserIds = normalizeDocMemberEntryList(collaborators)
-                    .map(e => e.userid)
-                    .filter(Boolean) as string[];
+                // Build a map of viewer entries with their full structure (preserving type and other fields)
+                const viewerMap = new Map<string, any>();
+                (currentAuth.docMembers || [])
+                    .filter((m: any) => m.userid)
+                    .forEach((m: any) => viewerMap.set(m.userid, m));
                 
-                // Auto-add viewers who are being promoted to collaborators
-                const autoRemoveViewers = newCollaboratorUserIds
-                    .filter(userid => viewerUserIds.has(userid))
-                    .map(userid => ({ userid, type: 1 }));
+                // Normalize new collaborators to get their userids
+                const newCollaboratorEntries = normalizeDocMemberEntryList(collaborators);
+                
+                // Auto-add viewers who are being promoted to collaborators, preserving their original structure
+                const autoRemoveViewers = newCollaboratorEntries
+                    .filter(entry => entry.userid && viewerMap.has(entry.userid))
+                    .map(entry => {
+                        // Preserve the original viewer's full structure (type, userid, etc.)
+                        const originalViewer = viewerMap.get(entry.userid!);
+                        return { ...originalViewer };
+                    });
                 
                 if (autoRemoveViewers.length > 0) {
                     finalRemoveViewers = autoRemoveViewers;
@@ -488,6 +492,16 @@ export class WecomDocClient {
             throw new Error("问题数量不能超过 200 个");
         }
         
+        // Auto-fill status fields for questions and options
+        questions.forEach((q: any) => {
+            if (q.status === undefined) q.status = 1;
+            if (Array.isArray(q.option_item)) {
+                q.option_item.forEach((opt: any) => {
+                    if (opt.status === undefined) opt.status = 1;
+                });
+            }
+        });
+        
         // Validate each question
         questions.forEach((q: any, index: number) => {
             if (!q.question_id || !Number.isInteger(q.question_id) || q.question_id < 1) {
@@ -505,6 +519,9 @@ export class WecomDocClient {
             if (q.must_reply === undefined || typeof q.must_reply !== 'boolean') {
                 throw new Error(`第${index + 1}个问题：must_reply 必填且必须为布尔值`);
             }
+            if (q.status !== undefined && ![1, 2].includes(q.status)) {
+                throw new Error(`第${index + 1}个问题：status 必须为 1(正常) 或 2(删除)`);
+            }
             
             // Validate option_item for single/multiple/dropdown questions
             const requiresOptions = [2, 3, 15].includes(q.reply_type); // 单选/多选/下拉列表
@@ -520,6 +537,9 @@ export class WecomDocClient {
                     if (!opt.value || readString(opt.value).length === 0) {
                         throw new Error(`第${index + 1}个问题的第${optIndex + 1}个选项：value 必填`);
                     }
+                    if (opt.status !== undefined && ![1, 2].includes(opt.status)) {
+                        throw new Error(`第${index + 1}个问题的第${optIndex + 1}个选项：status 必须为 1(正常) 或 2(删除)`);
+                    }
                 });
             }
             
@@ -546,6 +566,13 @@ export class WecomDocClient {
             console.warn("警告：timed_finish 与 timed_repeat_info 互斥，若都填优先定时重复");
         }
         
+        // Validate timed_repeat_info.enable=true requires fill_in_range
+        if (formSetting.timed_repeat_info?.enable) {
+            if (!formSetting.fill_in_range || (!formSetting.fill_in_range.userids?.length && !formSetting.fill_in_range.departmentids?.length)) {
+                throw new Error("timed_repeat_info 开启时，fill_in_range 必填（需指定 userids 或 departmentids）");
+            }
+        }
+        
         // Build payload
         const payload: Record<string, unknown> = {
             form_info: {
@@ -563,8 +590,8 @@ export class WecomDocClient {
         if (normalizedFatherId) payload.fatherid = normalizedFatherId;
         
         const json = await this.postWecomDocApi({
-            path: "/cgi-bin/wedoc/create_collect",
-            actionLabel: "create_collect",
+            path: "/cgi-bin/wedoc/create_form",
+            actionLabel: "create_form",
             agent,
             body: payload,
         });
@@ -605,6 +632,16 @@ export class WecomDocClient {
                 throw new Error("问题数量不能超过 200 个");
             }
             
+            // Auto-fill status fields for questions and options
+            questions.forEach((q: any) => {
+                if (q.status === undefined) q.status = 1;
+                if (Array.isArray(q.option_item)) {
+                    q.option_item.forEach((opt: any) => {
+                        if (opt.status === undefined) opt.status = 1;
+                    });
+                }
+            });
+            
             // Validate each question (same as createCollect)
             questions.forEach((q: any, index: number) => {
                 if (!q.question_id || !Number.isInteger(q.question_id) || q.question_id < 1) {
@@ -658,8 +695,8 @@ export class WecomDocClient {
         }
         
         const json = await this.postWecomDocApi({
-            path: "/cgi-bin/wedoc/modify_collect",
-            actionLabel: "modify_collect",
+            path: "/cgi-bin/wedoc/modify_form",
+            actionLabel: "modify_form",
             agent,
             body: payload,
         });
@@ -696,6 +733,12 @@ export class WecomDocClient {
                 .map((item) => Number(item))
                 .filter((item) => Number.isFinite(item))
             : [];
+        
+        // Official API limit: ≤100 answer IDs
+        if (normalizedAnswerIds.length > 100) {
+            throw new Error(`answer_ids 不能超过 100 个，当前：${normalizedAnswerIds.length}`);
+        }
+        
         const payload: Record<string, unknown> = {
             repeated_id: normalizedRepeatedId,
         };
@@ -724,6 +767,32 @@ export class WecomDocClient {
         if (payload.length === 0) {
             throw new Error("requests required");
         }
+        
+        // Validate each request per official API
+        payload.forEach((req: any, index: number) => {
+            const reqType = Number(req.req_type);
+            
+            // req_type=2: Get submitted list - requires start_time and end_time (same day timestamps)
+            if (reqType === 2) {
+                if (!req.start_time || !req.end_time) {
+                    throw new Error(`第${index + 1}个请求：req_type=2 时必须提供 start_time 和 end_time（当天时间戳）`);
+                }
+                // Validate timestamps are numbers
+                if (!Number.isFinite(Number(req.start_time)) || !Number.isFinite(Number(req.end_time))) {
+                    throw new Error(`第${index + 1}个请求：start_time 和 end_time 必须是有效时间戳`);
+                }
+                // Validate end_time >= start_time
+                if (Number(req.end_time) < Number(req.start_time)) {
+                    throw new Error(`第${index + 1}个请求：end_time 必须大于等于 start_time`);
+                }
+            }
+            
+            // Validate repeated_id is present
+            if (!req.repeated_id) {
+                throw new Error(`第${index + 1}个请求：repeated_id 必填`);
+            }
+        });
+        
         const json = await this.postWecomDocApi({
             path: "/cgi-bin/wedoc/get_form_statistic",
             actionLabel: "get_form_statistic",
@@ -758,30 +827,90 @@ export class WecomDocClient {
     }
 
     async updateDocContent(params: { agent: ResolvedAgentAccount; docId: string; requests: UpdateRequest[]; version?: number; batchMode?: boolean }) {
-        const { agent, docId, requests, version, batchMode } = params;
+        const { agent, docId, requests, version } = params;
         
         // Validate requests structure basic check
         const requestList = readArray(requests);
         if (requestList.length === 0) {
              throw new Error("requests list cannot be empty");
         }
-
-        const body: Record<string, unknown> = {
-            docid: readString(docId),
-            requests: requestList,
-        };
-        // version is optional but recommended for concurrency control
+        
+        // Validate version difference (≤100 per official API)
         if (version !== undefined && version !== null) {
-            body.version = Number(version);
+            const currentContent = await this.getDocContent({ agent, docId });
+            const versionDiff = Math.abs(currentContent.version - version);
+            if (versionDiff > 100) {
+                throw new Error(`version 与最新版本差值不能超过 100（当前版本：${currentContent.version}，传入版本：${version}，差值：${versionDiff}）`);
+            }
         }
         
-        const json = await this.postWecomDocApi({
-            path: "/cgi-bin/wedoc/document/batch_update",
-            actionLabel: "update_doc_content",
-            agent,
-            body,
-        }) as BatchUpdateDocResponse;
-        return { raw: json };
+        // Validate each request's ranges count (≤10 per official API)
+        requestList.forEach((req: any, index: number) => {
+            if (req.replace_text?.ranges && req.replace_text.ranges.length > 10) {
+                throw new Error(`第${index + 1}个操作：replace_text.ranges 不能超过 10 个`);
+            }
+            if (req.update_text_property?.ranges && req.update_text_property.ranges.length > 10) {
+                throw new Error(`第${index + 1}个操作：update_text_property.ranges 不能超过 10 个`);
+            }
+            // Validate insert_table limits
+            if (req.insert_table) {
+                const { rows, cols } = req.insert_table;
+                if (rows > 100) throw new Error(`第${index + 1}个操作：insert_table 行数不能超过 100`);
+                if (cols > 60) throw new Error(`第${index + 1}个操作：insert_table 列数不能超过 60`);
+                if (rows * cols > 1000) throw new Error(`第${index + 1}个操作：insert_table 单元格总数不能超过 1000`);
+            }
+        });
+
+        // Official API limit: ≤30 operations per batch
+        const MAX_OPERATIONS = 30;
+        if (requestList.length <= MAX_OPERATIONS) {
+            // Single batch
+            const body: Record<string, unknown> = {
+                docid: readString(docId),
+                requests: requestList,
+            };
+            if (version !== undefined && version !== null) {
+                body.version = Number(version);
+            }
+            
+            const json = await this.postWecomDocApi({
+                path: "/cgi-bin/wedoc/document/batch_update",
+                actionLabel: "update_doc_content",
+                agent,
+                body,
+            }) as BatchUpdateDocResponse;
+            return { raw: json, batches: 1 };
+        }
+        
+        // Auto-batch: split into multiple requests
+        // Note: Each batch updates the version, so we need to get latest version for each batch
+        const batches: BatchUpdateDocResponse[] = [];
+        for (let i = 0; i < requestList.length; i += MAX_OPERATIONS) {
+            const batchRequests = requestList.slice(i, i + MAX_OPERATIONS);
+            
+            // Get latest version before each batch (except first if version provided)
+            let currentVersion = version;
+            if (i > 0 || currentVersion === undefined || currentVersion === null) {
+                const content = await this.getDocContent({ agent, docId });
+                currentVersion = content.version;
+            }
+            
+            const body: Record<string, unknown> = {
+                docid: readString(docId),
+                requests: batchRequests,
+                version: currentVersion,
+            };
+            
+            const json = await this.postWecomDocApi({
+                path: "/cgi-bin/wedoc/document/batch_update",
+                actionLabel: `update_doc_content_batch_${Math.floor(i / MAX_OPERATIONS) + 1}`,
+                agent,
+                body,
+            }) as BatchUpdateDocResponse;
+            batches.push(json);
+        }
+        
+        return { raw: batches[batches.length - 1], batches: batches.length, allBatches: batches };
     }
 
     // --- Spreadsheet Operations ---
@@ -824,8 +953,9 @@ export class WecomDocClient {
         startRow?: number;
         startColumn?: number;
         gridData?: any;
+        requests?: any[];  // For direct batch_update with multiple operations
     }) {
-        const { agent, docId, sheetId, startRow = 0, startColumn = 0, gridData } = params;
+        const { agent, docId, sheetId, startRow = 0, startColumn = 0, gridData, requests } = params;
         
         // Validate required docId
         const normalizedDocId = readString(docId);
@@ -839,15 +969,72 @@ export class WecomDocClient {
             throw new Error('sheetId is required');
         }
         
+        // Handle direct requests (for multiple operations)
+        if (requests && requests.length > 0) {
+            // Official API limit: ≤5 operations per batch
+            const MAX_OPERATIONS = 5;
+            
+            // Validate each request
+            requests.forEach((req: any, index: number) => {
+                if (req.update_range_request?.grid_data?.rows) {
+                    const rows = req.update_range_request.grid_data.rows;
+                    const rowCount = rows.length;
+                    const rowWidths = rows.map((row: any) => row.values?.length || 0);
+                    const columnCount = rowWidths.length > 0 ? Math.max(...rowWidths) : 0;
+                    const totalCells = rowWidths.reduce((sum: number, width: number) => sum + width, 0);
+                    
+                    if (rowCount > 1000) throw new Error(`第${index + 1}个操作：行数不能超过 1000`);
+                    if (columnCount > 200) throw new Error(`第${index + 1}个操作：列数不能超过 200`);
+                    if (totalCells > 10000) throw new Error(`第${index + 1}个操作：单元格总数不能超过 10000`);
+                }
+            });
+            
+            if (requests.length > MAX_OPERATIONS) {
+                throw new Error(`单次批量更新最多${MAX_OPERATIONS}个操作，当前：${requests.length}`);
+            }
+            
+            const body = {
+                docid: normalizedDocId,
+                requests: requests
+            };
+            
+            const json = await this.postWecomDocApi({
+                path: "/cgi-bin/wedoc/spreadsheet/batch_update",
+                actionLabel: "spreadsheet_batch_update",
+                agent, body,
+            });
+            return { 
+                raw: json, 
+                docId: normalizedDocId,
+                operations: requests.length
+            };
+        }
+        
+        // Handle single gridData update
+        if (!gridData) {
+            throw new Error('gridData or requests is required');
+        }
+        
         // Build GridData per official API
         // gridData.rows[i].values[j] must be: {cell_value: {text} | {link: {text, url}}, cell_format?: {...}}
-        const rows = (gridData?.rows || []).map((row: any) => ({
+        const rows = (gridData.rows || []).map((row: any) => ({
             values: (row.values || []).map((cell: any) => {
                 // If already CellData format, use as-is
                 if (cell && typeof cell === 'object' && cell.cell_value) {
                     return cell;
                 }
-                // Otherwise wrap primitive as CellValue
+                // Support link simplified format: { url: '...', text: '...' }
+                if (cell && typeof cell === 'object' && cell.url) {
+                    return { 
+                        cell_value: { 
+                            link: { 
+                                url: String(cell.url), 
+                                text: String(cell.text ?? cell.url) 
+                            } 
+                        } 
+                    };
+                }
+                // Otherwise wrap primitive as CellValue with text
                 return { cell_value: { text: String(cell ?? '') } };
             })
         }));
@@ -874,8 +1061,7 @@ export class WecomDocClient {
             rows: rows
         };
         
-        // Build batch_update request per official API
-        // Note: requests array length ≤ 5 per API spec
+        // Build batch_update request per official API (single operation)
         const body = {
             docid: normalizedDocId,
             requests: [{
@@ -893,7 +1079,7 @@ export class WecomDocClient {
         });
         return { 
             raw: json, 
-            docId: body.docid as string,
+            docId: normalizedDocId,
             updatedCells: json.data?.responses?.[0]?.update_range_response?.updated_cells || 0
         };
     }
@@ -978,13 +1164,18 @@ export class WecomDocClient {
         return { raw: json, docId };
     }
 
-    async smartTableGetSheets(params: { agent: ResolvedAgentAccount; docId: string }) {
-        const { agent, docId } = params;
+    async smartTableGetSheets(params: { agent: ResolvedAgentAccount; docId: string; sheet_id?: string; need_all_type_sheet?: boolean }) {
+        const { agent, docId, sheet_id, need_all_type_sheet } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+        };
+        if (sheet_id) payload.sheet_id = sheet_id;
+        if (need_all_type_sheet !== undefined) payload.need_all_type_sheet = need_all_type_sheet;
         const json = await this.postWecomDocApi({
             path: "/cgi-bin/wedoc/smartsheet/get_sheet",
             actionLabel: "smartsheet_get_sheet",
             agent,
-            body: { docid: readString(docId) },
+            body: payload,
         });
         return {
             raw: json,
@@ -1006,34 +1197,278 @@ export class WecomDocClient {
         const { agent, docId, sheetId, title } = params;
         return this.smartTableOperate({ agent, docId, operation: "update_sheet", bodyData: { properties: { sheet_id: sheetId, title } } });
     }
-    async smartTableAddView(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; view_title: string; view_type: string; property_gantt?: any; property_calendar?: any }) {
-        const { agent, docId, sheetId, view_title, view_type, property_gantt, property_calendar } = params;
-        return this.smartTableOperate({ agent, docId, operation: "add_view", bodyData: { sheet_id: sheetId, view_title, view_type, property_gantt, property_calendar } });
+    async smartTableAddView(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        view_title: string; 
+        view_type: string;
+        property?: any;  // ViewProperty: sort_spec, filter_spec, group_spec, etc.
+        property_gantt?: any;  // Deprecated, use property instead
+        property_calendar?: any;  // Deprecated, use property instead
+    }) {
+        const { agent, docId, sheetId, view_title, view_type, property, property_gantt, property_calendar } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+            sheet_id: readString(sheetId),
+            view_title: readString(view_title),
+            view_type: readString(view_type),
+        };
+        if (property && typeof property === 'object') {
+            payload.property = property;
+        }
+        // Support deprecated property_gantt/property_calendar for backward compatibility
+        if (property_gantt) payload.property_gantt = property_gantt;
+        if (property_calendar) payload.property_calendar = property_calendar;
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/add_view",
+            actionLabel: "smartsheet_add_view",
+            agent,
+            body: payload,
+        });
+        return {
+            raw: json,
+            view: json.view,
+        };
     }
 
-    async smartTableUpdateView(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; view_id: string; view_title?: string; property_gantt?: any; property_calendar?: any }) {
-        const { agent, docId, sheetId, view_id, view_title, property_gantt, property_calendar } = params;
-        return this.smartTableOperate({ agent, docId, operation: "update_view", bodyData: { sheet_id: sheetId, view_id, view_title, property_gantt, property_calendar } });
+    async smartTableUpdateView(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        view_id: string; 
+        view_title?: string;
+        property?: any;  // ViewProperty: sort_spec, filter_spec, group_spec, etc.
+        property_gantt?: any;  // Deprecated, use property instead
+        property_calendar?: any;  // Deprecated, use property instead
+    }) {
+        const { agent, docId, sheetId, view_id, view_title, property, property_gantt, property_calendar } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+            sheet_id: readString(sheetId),
+            view_id: readString(view_id),
+        };
+        if (view_title) payload.view_title = readString(view_title);
+        if (property && typeof property === 'object') {
+            payload.property = property;
+        }
+        // Support deprecated property_gantt/property_calendar for backward compatibility
+        if (property_gantt) payload.property_gantt = property_gantt;
+        if (property_calendar) payload.property_calendar = property_calendar;
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/update_view",
+            actionLabel: "smartsheet_update_view",
+            agent,
+            body: payload,
+        });
+        return {
+            raw: json,
+            view: json.view,
+        };
     }
 
     async smartTableDelView(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; view_ids: string[] }) {
         const { agent, docId, sheetId, view_ids } = params;
-        return this.smartTableOperate({ agent, docId, operation: "delete_views", bodyData: { sheet_id: sheetId, view_ids } });
+        
+        if (!Array.isArray(view_ids) || view_ids.length === 0) {
+            throw new Error("view_ids 必须是非空数组");
+        }
+        
+        return this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/delete_views",
+            actionLabel: "smartsheet_del_view",
+            agent,
+            body: {
+                docid: readString(docId),
+                sheet_id: readString(sheetId),
+                view_ids: view_ids,
+            },
+        });
+    }
+
+    async smartTableGetViews(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        view_ids?: string[];
+        offset?: number;
+        limit?: number;
+    }) {
+        const { agent, docId, sheetId, view_ids, offset, limit } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+            sheet_id: readString(sheetId),
+        };
+        if (view_ids && Array.isArray(view_ids)) payload.view_ids = view_ids;
+        if (offset !== undefined) payload.offset = offset;
+        if (limit !== undefined) payload.limit = limit;
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/get_views",
+            actionLabel: "smartsheet_get_views",
+            agent,
+            body: payload,
+        });
+        return {
+            raw: json,
+            views: readArray(json.views),
+            total: json.total,
+            has_more: json.has_more,
+            next: json.next,
+        };
     }
 
-    async smartTableAddFields(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; fields: any[] }) {
+    async smartTableAddFields(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        fields: any[];
+    }) {
         const { agent, docId, sheetId, fields } = params;
-        return this.smartTableOperate({ agent, docId, operation: "add_fields", bodyData: { sheet_id: sheetId, fields } });
+        
+        // Validate fields per official API spec
+        if (!Array.isArray(fields) || fields.length === 0) {
+            throw new Error("fields 必须是非空数组");
+        }
+        
+        // Validate each field has required field_title and field_type
+        fields.forEach((field: any, index: number) => {
+            if (!field.field_title) {
+                throw new Error(`第${index + 1}个字段：field_title 必填`);
+            }
+            if (!field.field_type) {
+                throw new Error(`第${index + 1}个字段：field_type 必填`);
+            }
+            // Validate field_type is valid enum value
+            const validFieldTypes = [
+                'FIELD_TYPE_TEXT', 'FIELD_TYPE_NUMBER', 'FIELD_TYPE_CHECKBOX',
+                'FIELD_TYPE_DATE_TIME', 'FIELD_TYPE_IMAGE', 'FIELD_TYPE_ATTACHMENT',
+                'FIELD_TYPE_USER', 'FIELD_TYPE_URL', 'FIELD_TYPE_SELECT',
+                'FIELD_TYPE_CREATED_USER', 'FIELD_TYPE_MODIFIED_USER', 'FIELD_TYPE_CREATED_TIME',
+                'FIELD_TYPE_MODIFIED_TIME', 'FIELD_TYPE_PROGRESS', 'FIELD_TYPE_PHONE_NUMBER',
+                'FIELD_TYPE_EMAIL', 'FIELD_TYPE_SINGLE_SELECT', 'FIELD_TYPE_REFERENCE',
+                'FIELD_TYPE_LOCATION', 'FIELD_TYPE_CURRENCY', 'FIELD_TYPE_WWGROUP',
+                'FIELD_TYPE_AUTONUMBER', 'FIELD_TYPE_PERCENTAGE', 'FIELD_TYPE_BARCODE'
+            ];
+            if (!validFieldTypes.includes(field.field_type)) {
+                throw new Error(`第${index + 1}个字段：field_type 必须是有效的字段类型（见 FieldType 枚举）`);
+            }
+        });
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/add_fields",
+            actionLabel: "smartsheet_add_fields",
+            agent,
+            body: {
+                docid: readString(docId),
+                sheet_id: readString(sheetId),
+                fields: fields,
+            },
+        });
+        return {
+            raw: json,
+            fields: readArray(json.fields),
+        };
+    }
+
+    async smartTableUpdateFields(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        fields: any[];
+    }) {
+        const { agent, docId, sheetId, fields } = params;
+        
+        // Validate fields per official API spec
+        if (!Array.isArray(fields) || fields.length === 0) {
+            throw new Error("fields 必须是非空数组");
+        }
+        
+        // Validate each field has required field_id and field_type
+        fields.forEach((field: any, index: number) => {
+            if (!field.field_id) {
+                throw new Error(`第${index + 1}个字段：field_id 必填`);
+            }
+            if (!field.field_type) {
+                throw new Error(`第${index + 1}个字段：field_type 必填`);
+            }
+            // field_title is optional for update, but at least one of field_title or property_* must be provided
+            if (!field.field_title && !Object.keys(field).some(key => key.startsWith('property_'))) {
+                throw new Error(`第${index + 1}个字段：field_title 或 property_* 属性至少提供一个`);
+            }
+        });
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/update_fields",
+            actionLabel: "smartsheet_update_fields",
+            agent,
+            body: {
+                docid: readString(docId),
+                sheet_id: readString(sheetId),
+                fields: fields,
+            },
+        });
+        return {
+            raw: json,
+            fields: readArray(json.fields),
+        };
     }
 
     async smartTableDelFields(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; field_ids: string[] }) {
         const { agent, docId, sheetId, field_ids } = params;
-        return this.smartTableOperate({ agent, docId, operation: "delete_fields", bodyData: { sheet_id: sheetId, field_ids } });
+        
+        if (!Array.isArray(field_ids) || field_ids.length === 0) {
+            throw new Error("field_ids 必须是非空数组");
+        }
+        
+        return this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/delete_fields",
+            actionLabel: "smartsheet_del_fields",
+            agent,
+            body: {
+                docid: readString(docId),
+                sheet_id: readString(sheetId),
+                field_ids: field_ids,
+            },
+        });
     }
 
-    async smartTableUpdateFields(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; fields: any[] }) {
-        const { agent, docId, sheetId, fields } = params;
-        return this.smartTableOperate({ agent, docId, operation: "update_fields", bodyData: { sheet_id: sheetId, fields } });
+    async smartTableGetFields(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        view_id?: string;
+        field_ids?: string[];
+        field_titles?: string[];
+        offset?: number;
+        limit?: number;
+    }) {
+        const { agent, docId, sheetId, view_id, field_ids, field_titles, offset, limit } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+            sheet_id: readString(sheetId),
+        };
+        if (view_id) payload.view_id = view_id;
+        if (field_ids && Array.isArray(field_ids)) payload.field_ids = field_ids;
+        if (field_titles && Array.isArray(field_titles)) payload.field_titles = field_titles;
+        if (offset !== undefined) payload.offset = offset;
+        if (limit !== undefined) payload.limit = limit;
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/get_fields",
+            actionLabel: "smartsheet_get_fields",
+            agent,
+            body: payload,
+        });
+        return {
+            raw: json,
+            fields: readArray(json.fields),
+            total: json.total,
+            has_more: json.has_more,
+            next: json.next,
+        };
     }
 
     async smartTableAddGroup(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; name: string; children?: string[] }) {
@@ -1066,9 +1501,37 @@ export class WecomDocClient {
         return this.smartTableOperate({ agent, docId, operation: "update_external_records", bodyData: { sheet_id: sheetId, records } });
     }
 
-    async smartTableAddRecords(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; records: any[] }) {
-        const { agent, docId, sheetId, records } = params;
-        return this.smartTableOperate({ agent, docId, operation: "add_records", bodyData: { sheet_id: sheetId, records } });
+    async smartTableAddRecords(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        records: any[];
+        key_type?: string;
+    }) {
+        const { agent, docId, sheetId, records, key_type } = params;
+        
+        // Validate records format per official API spec (doc2.txt line 1594-1601)
+        if (!Array.isArray(records) || records.length === 0) {
+            throw new Error("records 必须是非空数组");
+        }
+        
+        // Validate each record has values object
+        records.forEach((record: any, index: number) => {
+            if (!record.values || typeof record.values !== 'object') {
+                throw new Error(`第${index + 1}条记录缺少 values 对象`);
+            }
+        });
+        
+        const bodyData: Record<string, unknown> = {
+            sheet_id: readString(sheetId),
+            records: records,
+        };
+        
+        if (key_type) {
+            bodyData.key_type = key_type;
+        }
+        
+        return this.smartTableOperate({ agent, docId, operation: "add_records", bodyData });
     }
 
     async smartTableUpdateRecords(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; records: any[] }) {
@@ -1081,9 +1544,51 @@ export class WecomDocClient {
         return this.smartTableOperate({ agent, docId, operation: "delete_records", bodyData: { sheet_id: sheetId, record_ids } });
     }
 
-    async smartTableGetRecords(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; record_ids?: string[]; offset?: number; limit?: number }) {
-        const { agent, docId, sheetId, record_ids, offset, limit } = params;
-        return this.smartTableOperate({ agent, docId, operation: "get_records", bodyData: { sheet_id: sheetId, record_ids, offset, limit } });
+    async smartTableGetRecords(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string; 
+        view_id?: string;
+        record_ids?: string[];
+        key_type?: string;
+        field_titles?: string[];
+        field_ids?: string[];
+        sort?: any[];
+        offset?: number;
+        limit?: number;
+        ver?: number;
+        filter_spec?: any;
+    }) {
+        const { agent, docId, sheetId, view_id, record_ids, key_type, field_titles, field_ids, sort, offset, limit, ver, filter_spec } = params;
+        const payload: Record<string, unknown> = {
+            docid: readString(docId),
+            sheet_id: readString(sheetId),
+        };
+        if (view_id) payload.view_id = view_id;
+        if (record_ids && Array.isArray(record_ids)) payload.record_ids = record_ids;
+        if (key_type) payload.key_type = key_type;
+        if (field_titles && Array.isArray(field_titles)) payload.field_titles = field_titles;
+        if (field_ids && Array.isArray(field_ids)) payload.field_ids = field_ids;
+        if (sort && Array.isArray(sort)) payload.sort = sort;
+        if (offset !== undefined) payload.offset = offset;
+        if (limit !== undefined) payload.limit = limit;
+        if (ver !== undefined) payload.ver = ver;
+        if (filter_spec && typeof filter_spec === 'object') payload.filter_spec = filter_spec;
+        
+        const json = await this.postWecomDocApi({
+            path: "/cgi-bin/wedoc/smartsheet/get_records",
+            actionLabel: "smartsheet_get_records",
+            agent,
+            body: payload,
+        });
+        return {
+            raw: json,
+            records: readArray(json.records),
+            total: json.total,
+            has_more: json.has_more,
+            next: json.next,
+            ver: json.ver,
+        };
     }
 
     // --- Smartsheet Content Permissions ---
@@ -1173,13 +1678,13 @@ export class WecomDocClient {
         });
     }
 
-    async getDocAdvancedAccountList(params: { agent: ResolvedAgentAccount; offset?: number; limit?: number }) {
-        const { agent, offset, limit } = params;
+    async getDocAdvancedAccountList(params: { agent: ResolvedAgentAccount; cursor?: number; limit?: number }) {
+        const { agent, cursor, limit } = params;
         return this.postWecomDocApi({
             path: "/cgi-bin/meeting/vip/get_vip_user_list",
             actionLabel: "get_advanced_account_list",
             agent,
-            body: { cursor: offset ? String(offset) : undefined, limit: limit ?? 100 },
+            body: { cursor: cursor !== undefined ? String(cursor) : undefined, limit: limit ?? 100 },
         });
     }