@yanhaidao/wecom 2.3.180 → 2.3.190

package/changelog/v2.3.19.md

@@ -0,0 +1,73 @@
+# OpenClaw WeCom 插件 v2.3.19 变更简报
+
+> [!TIP]
+> `v2.3.19` 主要修了四件和真实使用强相关的问题：第一，本机图片/文件终于能更自然地发出去，不再默认只认 OpenClaw 自己目录里的文件；第二，走 Bot WebSocket 时，`dynamicAgents` 也会真正生效，不会再出现“同样开了动态路由，但 WS 会话还是串到主 Agent”这种割裂行为；第三，媒体大小上限开始统一跟随 OpenClaw 标准配置 `mediaMaxMb`，不再是 WeCom 插件自己一套、OpenClaw 主配置又是一套；第四，Bot WS 对话里的图片/文件现在会尽量留在当前 Bot WS 对话里发送，不再静默切到 Agent 私聊链路。
+
+## 2026-03-19（v2.3.19）
+- 【修复 WS 不走 dynamicAgents】**[重要修复]** 之前 `dynamicAgents` 只在旧消息链路上生效，新的 Bot WebSocket 统一运行时没有把这层路由覆盖带进去。结果就是，同样一份配置，在 Webhook 或 Agent 路径上能按“每个用户 / 每个群”隔离会话，但走 WS 时却可能重新落回主 Agent。现在 WS 运行时也会执行同样的动态路由逻辑，单聊、群聊的隔离行为终于统一了。
+- 【修正 Bot WS 对话里的媒体回落策略】**[重要修复]** 如果当前消息本来就在 Bot WS 对话流里，图片/文件发送现在会优先并固定留在同一个 Bot WS 会话内处理。一旦已经尝试过 WS 发送，就不再静默回落到 Agent 私聊链路，避免用户明明在一个 Bot 对话里操作，结果媒体却从另一个 Agent 会话发出来。这个调整只针对 Bot WS，对 Bot Webhook 模式没有影响。
+- 【统一媒体大小配置到 OpenClaw 标准】之前 WeCom 插件内部主要认自己的 `channels.wecom.media.maxBytes`，而不是 OpenClaw 通用的 `mediaMaxMb`。这会带来一个很直接的问题：你明明已经在 OpenClaw 里把媒体大小放宽了，WeCom 这边却还像没看见一样。现在插件会优先读取 `channels.wecom.mediaMaxMb`，并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖；旧的 `channels.wecom.media.maxBytes` 仍然保留兼容，但只作为历史配置兜底。
+- 【补齐 Bot WS 媒体发送链路的大小透传】Bot WS 在读取本地文件、下载远程媒体并上传到企业微信前，现在会真正带上解析后的 `mediaMaxMb` 上限，而不是继续走内部固定值。换句话说，媒体大小限制终于从“写在配置里”和“运行时真的执行”两边对齐了。
+- 【放宽本地文件默认可发送目录】之前本地媒体白名单更偏向 OpenClaw 自己的状态目录，所以像 `~/Downloads/01.png` 这种很自然的用户文件路径，虽然文件确实存在，也会被当成“不允许发送”。现在插件默认额外放行常见用户目录：`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。对普通用户来说，这意味着“桌面、下载、图片目录里的文件”现在默认就更符合直觉地可发送了。
+- 【支持继续追加自定义本地媒体目录】除了默认目录外，现在仍然可以通过 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘、业务导出目录等自定义路径。这里的设计原则很简单：默认给出大多数人会用到的目录，但不假设所有企业的数据都在同一个地方。
+- 【文案与排障提示同步更新】当媒体太大或解密失败时，提示语现在会直接指向 `channels.wecom.mediaMaxMb` 这套推荐配置，避免用户继续被旧的 `media.maxBytes` 误导。
+
+## 这次改动背后的最小理解模型
+
+把这次版本理解成四句话就够了：
+
+1. **会话该隔离的，要真的隔离。**  
+   你开了 `dynamicAgents`，系统就应该不管走 Webhook、Agent Callback 还是 Bot WS，都稳定地把“不同用户 / 不同群”落到不同会话上，而不是不同链路表现不一致。
+
+2. **从哪个对话开始，就该尽量在哪个对话里发回去。**  
+   如果用户是在 Bot WS 对话里让系统发图，那么结果也应该优先回到这个 Bot WS 对话，而不是悄悄切到 Agent 私聊。否则用户看到的“会话边界”和系统内部实际走的链路会分裂。
+
+3. **配置写在哪里，运行时就该认哪里。**  
+   OpenClaw 既然已经把媒体大小的标准字段定成 `mediaMaxMb`，WeCom 插件就不该再偷偷主要走自己那套 `media.maxBytes`。统一之后，用户只需要记住一套规则。
+
+4. **用户的文件，默认应该在用户常用目录里。**  
+   大多数人发文件，不会先把图拷进 `.openclaw/media`，而是直接从下载目录、桌面、图片目录发。默认路径如果违背这个常识，系统虽然“安全”，但体验是不成立的。
+
+## 推荐配置
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "mediaMaxMb": 50,
+      "media": {
+        "tempDir": "/tmp/openclaw-wecom-media",
+        "localRoots": [
+          "/srv/company-share",
+          "/data/reports"
+        ]
+      },
+      "dynamicAgents": {
+        "enabled": true,
+        "dmCreateAgent": true,
+        "groupEnabled": true,
+        "adminUsers": ["your-admin-userid"]
+      }
+    }
+  }
+}
+```
+
+## 升级后你应该感受到的变化
+
+- 从 `Downloads`、`Desktop` 这类常见目录直接发图、发文件，更容易一次成功。
+- 同样开启 `dynamicAgents` 的前提下，Bot WS 会话也会像其他链路一样稳定隔离，不再更容易串上下文。
+- 如果当前就是 Bot WS 对话流，发图、发文件会优先留在这个对话里处理，不会再更容易“跳”到 Agent 私聊。
+- 调整 `mediaMaxMb` 后，WeCom 插件的上传 / 解密 / 读取链路会真正跟着变化，而不是“配置改了，行为没改”。
+
+## 仍然需要知道的边界
+
+- `mediaMaxMb` 控制的是 OpenClaw 这边愿意读取和处理多大的媒体，不代表企业微信协议本身没有限制。
+- 企业微信自身的媒体限制仍然存在，例如图片 / 视频超过 10MB、语音超过 2MB、文件超过 20MB 时，最终行为仍受企业微信接口约束。
+- 旧配置 `channels.wecom.media.maxBytes` 目前还兼容，但新配置建议统一迁移到 `channels.wecom.mediaMaxMb`。
+
+## 升级提示
+
+- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.19`。
+- 如果你之前遇到“WS 开了 dynamicAgents 但还是串到主 Agent”“明明在 Bot WS 对话里发图，结果却从 Agent 私聊发出来”，或“明明改了媒体大小配置却没有生效”，这一版就是针对这些问题的直接修复。
+- 如果你的文件仍然不在默认目录内，例如 NAS、共享盘或业务导出盘，请继续在 `channels.wecom.media.localRoots` 中追加对应路径。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.180",
+  "version": "2.3.190",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {

package/src/agent/handler.ts

@@ -481,7 +481,7 @@ async function processAgentMessage(params: {
   const resolvedContent = resolveEventText();
   let finalContent = resolvedContent;
 
-  const mediaMaxBytes = resolveWecomMediaMaxBytes(config);
+  const mediaMaxBytes = resolveWecomMediaMaxBytes(config, agent.accountId);
 
   // 处理媒体文件
   const attachments: NonNullable<UnifiedInboundEvent["attachments"]> = [];
@@ -598,8 +598,8 @@ async function processAgentMessage(params: {
           content,
           "",
           `媒体处理失败：${String(err)}`,
-          `提示：可在 OpenClaw 配置中提高 channels.wecom.media.maxBytes（当前=${mediaMaxBytes}）`,
-          `例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
+          `提示：可在 OpenClaw 配置中提高 channels.wecom.mediaMaxMb（当前=${Math.round(mediaMaxBytes / (1024 * 1024))}MB）`,
+          "例如：openclaw config set channels.wecom.mediaMaxMb 50",
         ].join("\n");
       }
     } else {

package/src/app/index.ts

@@ -19,6 +19,7 @@ export type BotWsPushHandle = {
     mediaUrl: string;
     text?: string;
     mediaLocalRoots?: readonly string[];
+    maxBytes?: number;
   }) => Promise<{
     ok: boolean;
     messageId?: string;

package/src/capability/bot/stream-orchestrator.ts

@@ -154,7 +154,7 @@ export function createBotStreamOrchestrator(params: {
     let mediaType: string | undefined;
     if (media) {
       try {
-        const maxBytes = resolveWecomMediaMaxBytes(target.config);
+        const maxBytes = resolveWecomMediaMaxBytes(target.config, target.account.accountId);
         const saved = await core.channel.media.saveMediaBuffer(media.buffer, media.contentType, "inbound", maxBytes, media.filename);
         mediaPath = saved.path;
         mediaType = saved.contentType;

package/src/capability/doc/client.ts

@@ -196,25 +196,112 @@ export class WecomDocClient {
         const normalizedFatherId = readString(fatherId);
         if (normalizedSpaceId) payload.spaceid = normalizedSpaceId;
         if (normalizedFatherId) payload.fatherid = normalizedFatherId;
+        
+        // admin_users is required for smart_table to ensure proper permissions
         const normalizedAdminUsers = Array.isArray(adminUsers)
             ? adminUsers.map((item) => readString(item)).filter(Boolean)
             : [];
         if (normalizedAdminUsers.length > 0) {
             payload.admin_users = normalizedAdminUsers;
         }
+        
         const json = await this.postWecomDocApi({
             path: "/cgi-bin/wedoc/create_doc",
             actionLabel: "create_doc",
             agent,
             body: payload,
         });
-        return {
+        
+        const result = {
             raw: json,
             docId: readString(json.docid),
             url: readString(json.url),
             docType: normalizedDocType,
             docTypeLabel: mapDocTypeLabel(normalizedDocType),
         };
+        
+        // Auto-initialize smart_table: clean up default fields and records
+        if (normalizedDocType === 10) {
+            await this.initializeSmartTable({ agent, docId: result.docId });
+        }
+        
+        return result;
+    }
+
+    /**
+     * Initialize smart_table after creation:
+     * 1. Get default sheet (smartsheet type)
+     * 2. Get default fields (usually 5 fields)
+     * 3. Delete 4 default fields, keep 1 as primary key
+     * 4. Get default records (usually 5 empty records)
+     * 5. Delete all default records
+     */
+    private async initializeSmartTable(params: { agent: ResolvedAgentAccount; docId: string }) {
+        const { agent, docId } = params;
+        
+        try {
+            // Step 1: Get sheet list to find the default smartsheet
+            const sheetsResult = await this.smartTableGetSheets({ agent, docId });
+            const defaultSheet = sheetsResult.sheets.find((s: any) => s.type === "smartsheet");
+            if (!defaultSheet) return; // No smartsheet found, skip initialization
+            
+            const sheetId = (defaultSheet as any).sheet_id;
+            
+            // Step 2: Get default fields
+            const fieldsResult = await this.smartTableGetFields({ agent, docId, sheetId });
+            const fields = fieldsResult.fields || [];
+            
+            if (fields.length > 1) {
+                // Keep the last field as primary key, delete the rest
+                // Primary key capable types: TEXT, NUMBER, DATE_TIME, URL, PROGRESS, EMAIL, PHONE_NUMBER, FORMULA, LOCATION, CURRENCY, AUTONUMBER, TITLE, WWGROUP
+                const primaryKeyCapableTypes = [
+                    'FIELD_TYPE_TEXT', 'FIELD_TYPE_NUMBER', 'FIELD_TYPE_DATE_TIME',
+                    'FIELD_TYPE_URL', 'FIELD_TYPE_PROGRESS', 'FIELD_TYPE_EMAIL',
+                    'FIELD_TYPE_PHONE_NUMBER', 'FIELD_TYPE_LOCATION', 'FIELD_TYPE_CURRENCY',
+                    'FIELD_TYPE_AUTONUMBER', 'FIELD_TYPE_WWGROUP'
+                ];
+                
+                // Find a field that can be primary key (prefer the last one)
+                let fieldToDelete: string[] = [];
+                let fieldToKeep: string | null = null;
+                
+                for (let i = fields.length - 1; i >= 0; i--) {
+                    const field = fields[i] as any;
+                    if (!fieldToKeep && primaryKeyCapableTypes.includes(field.field_type)) {
+                        fieldToKeep = field.field_id;
+                    } else if (field.field_id) {
+                        fieldToDelete.push(field.field_id);
+                    }
+                }
+                
+                // If no primary key capable field found, keep the last one anyway
+                if (!fieldToKeep && fields.length > 0) {
+                    const lastField = fields[fields.length - 1] as any;
+                    fieldToKeep = lastField.field_id;
+                    fieldToDelete = fields.slice(0, -1).map((f: any) => f.field_id);
+                }
+                
+                // Delete the fields
+                if (fieldToDelete.length > 0) {
+                    await this.smartTableDelFields({ agent, docId, sheetId, field_ids: fieldToDelete });
+                }
+            }
+            
+            // Step 3: Get default records
+            const recordsResult = await this.smartTableGetRecords({ agent, docId, sheetId, limit: 100 });
+            const records = recordsResult.records || [];
+            
+            if (records.length > 0) {
+                // Delete all default empty records
+                const recordIds = records.map((r: any) => r.record_id).filter(Boolean);
+                if (recordIds.length > 0) {
+                    await this.smartTableDelRecords({ agent, docId, sheetId, record_ids: recordIds });
+                }
+            }
+        } catch (err) {
+            // Non-fatal: smart_table created, just default cleanup failed
+            console.error(`[WecomDocClient] initializeSmartTable failed:`, err);
+        }
     }
 
     async renameDoc(params: { agent: ResolvedAgentAccount; docId: string; newName: string }) {
@@ -1325,8 +1412,9 @@ export class WecomDocClient {
         docId: string; 
         sheetId: string; 
         fields: any[];
+        autoCleanupDefaultField?: boolean; // Auto-delete leftover default field after adding new fields
     }) {
-        const { agent, docId, sheetId, fields } = params;
+        const { agent, docId, sheetId, fields, autoCleanupDefaultField = true } = params;
         
         // Validate fields per official API spec
         if (!Array.isArray(fields) || fields.length === 0) {
@@ -1367,10 +1455,60 @@ export class WecomDocClient {
                 fields: fields,
             },
         });
-        return {
+        
+        const result = {
             raw: json,
             fields: readArray(json.fields),
         };
+        
+        // Auto-cleanup: delete leftover default field after successfully adding new fields
+        // This handles the case where initializeSmartTable kept 1 default field
+        if (autoCleanupDefaultField) {
+            await this.cleanupLeftoverDefaultField({ agent, docId, sheetId, newlyAddedFieldCount: result.fields.length });
+        }
+        
+        return result;
+    }
+
+    /**
+     * Cleanup leftover default field after adding new fields
+     * When user adds new fields, we can safely delete the leftover default field from initialization
+     */
+    private async cleanupLeftoverDefaultField(params: { 
+        agent: ResolvedAgentAccount; 
+        docId: string; 
+        sheetId: string;
+        newlyAddedFieldCount: number;
+    }) {
+        const { agent, docId, sheetId, newlyAddedFieldCount } = params;
+        
+        try {
+            // Get all fields to find the leftover default field
+            const fieldsResult = await this.smartTableGetFields({ agent, docId, sheetId, limit: 100 });
+            const allFields = fieldsResult.fields || [];
+            
+            // After adding N new fields to a table with 1 default field, we should have N+1 fields
+            // If total = newlyAdded + 1, then there's 1 leftover default field to delete
+            if (allFields.length === newlyAddedFieldCount + 1 && newlyAddedFieldCount > 0) {
+                // Find the field that looks like a leftover default
+                // Default fields typically have generic titles like "文本", "数字", "日期", "单选", "人员"
+                const defaultFieldTitles = ['文本', '数字', '日期', '单选', '人员', '文本 1', '数字 1', '日期 1', '单选 1', '人员 1'];
+                const defaultFieldTypes = ['FIELD_TYPE_TEXT', 'FIELD_TYPE_NUMBER', 'FIELD_TYPE_DATE_TIME', 'FIELD_TYPE_SINGLE_SELECT', 'FIELD_TYPE_USER'];
+                
+                const leftoverField = allFields.find((field: any) => {
+                    const isDefaultTitle = defaultFieldTitles.includes(field.field_title);
+                    const isDefaultType = defaultFieldTypes.includes(field.field_type);
+                    return isDefaultTitle && isDefaultType;
+                }) as any;
+                
+                if (leftoverField && leftoverField.field_id) {
+                    await this.smartTableDelFields({ agent, docId, sheetId, field_ids: [leftoverField.field_id] });
+                }
+            }
+        } catch (err) {
+            // Non-fatal: new fields added, just cleanup failed
+            console.error(`[WecomDocClient] cleanupLeftoverDefaultField failed:`, err);
+        }
     }
 
     async smartTableUpdateFields(params: { 
@@ -1515,16 +1653,55 @@ export class WecomDocClient {
             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 对象`);
+        // Strict validation: require correct format based on field type
+        // Do NOT auto-convert ambiguous values to avoid corrupting user intent
+        const validatedRecords = records.map((record: any, recordIndex: number) => {
+            if (!record.values || typeof record.values !== 'object' || Array.isArray(record.values)) {
+                throw new Error(`第${recordIndex + 1}条记录：values 必须是非空对象`);
+            }
+            
+            const validatedValues: Record<string, any> = {};
+            for (const [key, value] of Object.entries(record.values)) {
+                // Accept both array and non-array formats based on field type
+                // Array types: TEXT, USER, SELECT, SINGLE_SELECT, CHECKBOX, PHONE_NUMBER, EMAIL, URL, LOCATION, BARCODE, ATTACHMENT, IMAGE
+                // Non-array types: NUMBER, DATE_TIME, PROGRESS, CURRENCY, PERCENTAGE
+                
+                if (Array.isArray(value)) {
+                    // Array format - validate structure
+                    if (value.length === 0) {
+                        throw new Error(`第${recordIndex + 1}条记录字段 "${key}": 数组不能为空`);
+                    }
+                    validatedValues[key] = value;
+                } else if (typeof value === 'number') {
+                    // Non-array number - valid for NUMBER, PROGRESS, CURRENCY, PERCENTAGE
+                    validatedValues[key] = value;
+                } else if (typeof value === 'string' && /^\d{13}$/.test(value)) {
+                    // Non-array 13-digit string - valid for DATE_TIME (millisecond timestamp)
+                    validatedValues[key] = value;
+                } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // Object format - wrap in array for types like USER, TEXT object
+                    // This allows {user_id: "..."} to become [{user_id: "..."}]
+                    validatedValues[key] = [value];
+                } else {
+                    // Reject ambiguous primitives (plain strings, booleans)
+                    // Users should explicitly use array format: [{type: "text", text: "..."}]
+                    throw new Error(
+                        `第${recordIndex + 1}条记录字段 "${key}": 值格式不明确。` +
+                        `数字/日期类型直接写值 (25, "1704067200000")，` +
+                        `文本/成员/选项类型用数组 ([{"type": "text", "text": "..."}], [{"user_id": "..."}])`
+                    );
+                }
             }
+            
+            return {
+                ...record,
+                values: validatedValues,
+            };
         });
         
         const bodyData: Record<string, unknown> = {
             sheet_id: readString(sheetId),
-            records: records,
+            records: validatedRecords,
         };
         
         if (key_type) {
@@ -1536,7 +1713,49 @@ export class WecomDocClient {
 
     async smartTableUpdateRecords(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; records: any[] }) {
         const { agent, docId, sheetId, records } = params;
-        return this.smartTableOperate({ agent, docId, operation: "update_records", bodyData: { sheet_id: sheetId, records } });
+        
+        // Strict validation: same as addRecords
+        if (!Array.isArray(records) || records.length === 0) {
+            throw new Error("records 必须是非空数组");
+        }
+        
+        const validatedRecords = records.map((record: any, recordIndex: number) => {
+            if (!record.record_id) {
+                throw new Error(`第${recordIndex + 1}条记录缺少 record_id`);
+            }
+            if (!record.values || typeof record.values !== 'object' || Array.isArray(record.values)) {
+                throw new Error(`第${recordIndex + 1}条记录：values 必须是非空对象`);
+            }
+            
+            const validatedValues: Record<string, any> = {};
+            for (const [key, value] of Object.entries(record.values)) {
+                if (Array.isArray(value)) {
+                    if (value.length === 0) {
+                        throw new Error(`第${recordIndex + 1}条记录字段 "${key}": 数组不能为空`);
+                    }
+                    validatedValues[key] = value;
+                } else if (typeof value === 'number') {
+                    validatedValues[key] = value;
+                } else if (typeof value === 'string' && /^\d{13}$/.test(value)) {
+                    validatedValues[key] = value;
+                } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    validatedValues[key] = [value];
+                } else {
+                    throw new Error(
+                        `第${recordIndex + 1}条记录字段 "${key}": 值格式不明确。` +
+                        `数字/日期类型直接写值 (25, "1704067200000")，` +
+                        `文本/成员/选项类型用数组 ([{"type": "text", "text": "..."}], [{"user_id": "..."}])`
+                    );
+                }
+            }
+            
+            return {
+                ...record,
+                values: validatedValues,
+            };
+        });
+        
+        return this.smartTableOperate({ agent, docId, operation: "update_records", bodyData: { sheet_id: sheetId, records: validatedRecords } });
     }
 
     async smartTableDelRecords(params: { agent: ResolvedAgentAccount; docId: string; sheetId: string; record_ids: string[] }) {

package/src/capability/doc/tool.ts

@@ -1189,11 +1189,12 @@ export function registerWecomDocTools(api: OpenClawPluginApi) {
               });
             }
             case "smartsheet_add_records": {
-              const result = await docClient.smartTableOperate({
+              const result = await docClient.smartTableAddRecords({
                 agent: account,
                 docId: params.docId,
-                operation: "add_records",
-                bodyData: params,
+                sheetId: params.sheetId,
+                records: params.records,
+                key_type: params.key_type,
               });
               return buildToolResult({
                 ok: true,
@@ -1205,11 +1206,11 @@ export function registerWecomDocTools(api: OpenClawPluginApi) {
               });
             }
             case "smartsheet_update_records": {
-              const result = await docClient.smartTableOperate({
+              const result = await docClient.smartTableUpdateRecords({
                 agent: account,
                 docId: params.docId,
-                operation: "update_records",
-                bodyData: params,
+                sheetId: params.sheetId,
+                records: params.records,
               });
               return buildToolResult({
                 ok: true,
@@ -1350,7 +1351,13 @@ export function registerWecomDocTools(api: OpenClawPluginApi) {
               });
             }
             case "smartsheet_add_fields": {
-              const result = await docClient.smartTableAddFields({ agent: account, ...params });
+              const result = await docClient.smartTableAddFields({ 
+                agent: account, 
+                docId: params.docId, 
+                sheetId: params.sheetId, 
+                fields: params.fields,
+                autoCleanupDefaultField: params.autoCleanupDefaultField !== false, // Default true
+              });
               return buildToolResult({
                 ok: true,
                 action,

package/src/config/index.ts

@@ -12,5 +12,11 @@ export {
 export { resolveWecomRuntimeAccount, resolveWecomRuntimeConfig, type ResolvedRuntimeAccount, type ResolvedRuntimeConfig } from "./runtime-config.js";
 export { resolveDerivedPath, resolveDerivedPathSummary } from "./derived-paths.js";
 export { resolveWecomEgressProxyUrl, resolveWecomEgressProxyUrlFromNetwork } from "./network.js";
-export { DEFAULT_WECOM_MEDIA_MAX_BYTES, resolveWecomMediaMaxBytes } from "./media.js";
+export {
+  DEFAULT_WECOM_MEDIA_MAX_BYTES,
+  getWecomDefaultMediaLocalRoots,
+  resolveWecomConfiguredMediaLocalRoots,
+  resolveWecomMediaMaxBytes,
+  resolveWecomMergedMediaLocalRoots,
+} from "./media.js";
 export { resolveWecomFailClosedOnDefaultRoute, shouldRejectWecomDefaultRoute } from "./routing.js";

package/src/config/media.test.ts

@@ -0,0 +1,113 @@
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";
+import { resolveWecomMediaMaxBytes, resolveWecomMergedMediaLocalRoots } from "./media.js";
+
+describe("resolveWecomMergedMediaLocalRoots", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("merges defaults with configured local roots", () => {
+    vi.stubEnv("OPENCLAW_STATE_DIR", "/tmp/wecom-state");
+
+    const roots = resolveWecomMergedMediaLocalRoots({
+      cfg: {
+        channels: {
+          wecom: {
+            media: {
+              localRoots: ["~/Downloads", "/tmp/custom-root"],
+            },
+          },
+        },
+      } as never,
+    });
+
+    expect(roots).toEqual(
+      expect.arrayContaining([
+        path.resolve(resolvePreferredOpenClawTmpDir()),
+        "/tmp/wecom-state",
+        "/tmp/wecom-state/media",
+        "/tmp/wecom-state/agents",
+        "/tmp/wecom-state/workspace",
+        "/tmp/wecom-state/sandboxes",
+        path.resolve(os.homedir(), "Desktop"),
+        path.resolve(os.homedir(), "Documents"),
+        path.resolve(os.homedir(), "Downloads"),
+        path.resolve(os.homedir(), "Movies"),
+        path.resolve(os.homedir(), "Pictures"),
+        "/tmp/custom-root",
+      ]),
+    );
+  });
+
+  it("keeps defaults, base roots, and configured roots without duplicates", () => {
+    vi.stubEnv("OPENCLAW_STATE_DIR", "/tmp/wecom-state");
+
+    const roots = resolveWecomMergedMediaLocalRoots({
+      cfg: {
+        channels: {
+          wecom: {
+            media: {
+              localRoots: ["/tmp/agent-root", "/tmp/downloads"],
+            },
+          },
+        },
+      } as never,
+      baseRoots: ["/tmp/agent-root", "/tmp/workspace-agent"],
+    });
+
+    expect(roots).toEqual(
+      expect.arrayContaining([
+        path.resolve(resolvePreferredOpenClawTmpDir()),
+        "/tmp/wecom-state",
+        "/tmp/workspace-agent",
+        "/tmp/agent-root",
+        "/tmp/downloads",
+      ]),
+    );
+    expect(roots.filter((root) => root === "/tmp/agent-root")).toHaveLength(1);
+  });
+});
+
+describe("resolveWecomMediaMaxBytes", () => {
+  it("prefers account mediaMaxMb over channel and agent defaults", () => {
+    expect(
+      resolveWecomMediaMaxBytes(
+        {
+          agents: {
+            defaults: {
+              mediaMaxMb: 12,
+            },
+          },
+          channels: {
+            wecom: {
+              mediaMaxMb: 24,
+              accounts: {
+                ops: {
+                  mediaMaxMb: 32,
+                },
+              },
+            },
+          },
+        } as never,
+        "ops",
+      ),
+    ).toBe(32 * 1024 * 1024);
+  });
+
+  it("falls back to legacy channels.wecom.media.maxBytes when mediaMaxMb is unset", () => {
+    expect(
+      resolveWecomMediaMaxBytes({
+        channels: {
+          wecom: {
+            media: {
+              maxBytes: 15 * 1024 * 1024,
+            },
+          },
+        },
+      } as never),
+    ).toBe(15 * 1024 * 1024);
+  });
+});