@mocrane/wecom 2026.3.8-4 → 2026.3.12

package/src/mcp-config.ts

@@ -0,0 +1,182 @@
+/**
+ * MCP 配置拉取与持久化模块
+ *
+ * 负责:
+ * - 通过 WSClient 发送 aibot_get_mcp_config 请求
+ * - 解析服务端响应，提取 MCP 配置 (url、type、is_authed)
+ * - 将配置写入 ~/.openclaw/wecomConfig/config.json 的 mcpConfig 字段
+ */
+
+import os from "os";
+import path from "path";
+import type { WSClient } from "@wecom/aibot-node-sdk";
+import { generateReqId } from "@wecom/aibot-node-sdk";
+import { resolveFileIoHelpers } from "./compat/plugin-sdk-shim.js";
+import type { WecomRuntimeEnv } from "./monitor/types.js";
+import { withTimeout } from "./timeout.js";
+
+// ============================================================================
+// 常量
+// ============================================================================
+
+/** 获取 MCP 配置的 WebSocket 命令 */
+const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
+
+/** MCP 配置拉取超时时间（毫秒） */
+const MCP_CONFIG_FETCH_TIMEOUT_MS = 15_000;
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+/**
+ * MCP 配置响应体
+ */
+export interface McpConfigBody {
+    /** MCP Server 的 StreamableHttp URL */
+    url: string;
+    /** 连接类型，如 "doc" */
+    type?: string;
+    /** 是否已授权 */
+    is_authed?: boolean;
+}
+
+// ============================================================================
+// MCP 配置拉取
+// ============================================================================
+
+/**
+ * 通过 WSClient 发送 aibot_get_mcp_config 命令，获取 MCP 配置
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @returns MCP 配置 (url、type、is_authed)
+ * @throws 响应错误码非 0 或缺少 url 字段时抛出错误
+ */
+export async function fetchMcpConfig(
+    wsClient: WSClient,
+): Promise<McpConfigBody> {
+    const reqId = generateReqId("mcp_config");
+
+    // 通过 reply 方法发送自定义命令
+    const response = await withTimeout(
+        wsClient.reply(
+            { headers: { req_id: reqId } },
+            { biz_type: "doc" },
+            MCP_GET_CONFIG_CMD,
+        ),
+        MCP_CONFIG_FETCH_TIMEOUT_MS,
+        `MCP config fetch timed out after ${MCP_CONFIG_FETCH_TIMEOUT_MS}ms`,
+    );
+
+    // 校验响应错误码
+    if (response.errcode && response.errcode !== 0) {
+        throw new Error(
+            `MCP config request failed: errcode=${response.errcode}, errmsg=${response.errmsg ?? "unknown"}`,
+        );
+    }
+
+    // 提取并校验 body
+    const body = response.body as McpConfigBody | undefined;
+    if (!body?.url) {
+        throw new Error(
+            "MCP config response missing required 'url' field",
+        );
+    }
+
+    return {
+        url: body.url,
+        type: "doc",
+        is_authed: body.is_authed,
+    };
+}
+
+// ============================================================================
+// 配置持久化
+// ============================================================================
+
+/**
+ * 将 MCP 配置写入 ~/.openclaw/wecomConfig/config.json 的 mcpConfig 字段
+ *
+ * 使用 OpenClaw SDK 提供的文件锁和原子写入，保证并发安全。
+ * 配置格式: { mcpConfig: { [type]: { type, url } } }
+ */
+async function saveMcpConfigToPluginJson(
+    config: McpConfigBody,
+    runtime: WecomRuntimeEnv,
+): Promise<void> {
+    const wecomConfigDir = path.join(os.homedir(), ".openclaw", "wecomConfig");
+    const wecomConfigPath = path.join(wecomConfigDir, "config.json");
+
+    const lockOptions = {
+        stale: 60_000,
+        retries: {
+            retries: 6,
+            factor: 1.35,
+            minTimeout: 8,
+            maxTimeout: 1200,
+            randomize: true,
+        },
+    };
+
+    const { withFileLock, readJsonFileWithFallback, writeJsonFileAtomically } =
+        await resolveFileIoHelpers();
+
+    await withFileLock(wecomConfigPath, lockOptions, async () => {
+        // 读取现有配置（不存在时使用空对象）
+        const { value: pluginJson } = await readJsonFileWithFallback<Record<string, unknown>>(
+            wecomConfigPath,
+            {},
+        );
+
+        // 确保 mcpConfig 字段存在且为对象
+        if (!pluginJson.mcpConfig || typeof pluginJson.mcpConfig !== "object") {
+            pluginJson.mcpConfig = {};
+        }
+
+        // 使用 type 作为键存储配置
+        const typeKey = config.type || "default";
+        (pluginJson.mcpConfig as Record<string, unknown>)[typeKey] = {
+            type: config.type,
+            url: config.url,
+        };
+
+        // 原子写入
+        await writeJsonFileAtomically(wecomConfigPath, pluginJson);
+
+        runtime.log?.(`[WeCom] MCP config saved to ${wecomConfigPath}`);
+    });
+}
+
+// ============================================================================
+// 组合入口
+// ============================================================================
+
+/**
+ * 拉取 MCP 配置并持久化到 ~/.openclaw/wecomConfig/config.json
+ *
+ * 认证成功后调用。失败仅记录日志，不影响 WebSocket 消息正常收发。
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @param accountId - 账户 ID（用于日志）
+ * @param runtime - 运行时环境（用于日志）
+ */
+export async function fetchAndSaveMcpConfig(
+    wsClient: WSClient,
+    accountId: string,
+    runtime: WecomRuntimeEnv,
+): Promise<void> {
+    try {
+        runtime.log?.(`[${accountId}] Fetching MCP config...`);
+
+        const config = await fetchMcpConfig(wsClient);
+        runtime.log?.(
+            `[${accountId}] MCP config fetched: url=${config.url}, type=${config.type ?? "N/A"}, is_authed=${config.is_authed ?? "N/A"}`,
+        );
+
+        await saveMcpConfigToPluginJson(config, runtime);
+    } catch (err) {
+        runtime.error?.(
+            `[${accountId}] Failed to fetch/save MCP config: ${String(err)}`,
+        );
+    }
+}

package/src/media/const.ts

@@ -0,0 +1,24 @@
+/**
+ * WeCom 媒体文件大小限制常量
+ *
+ * 对标企业微信智能机器人临时素材上传限制。
+ * 超出限制时，uploader 会按规则降级（如图片→文件）或拒绝。
+ */
+
+/** 图片最大字节数 (10 MB)，超出则降级为 file 类型 */
+export const IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+
+/** 视频最大字节数 (10 MB)，超出则降级为 file 类型 */
+export const VIDEO_MAX_BYTES = 10 * 1024 * 1024;
+
+/** 语音最大字节数 (2 MB)，超出则降级为 file 类型 */
+export const VOICE_MAX_BYTES = 2 * 1024 * 1024;
+
+/** 文件最大字节数 (20 MB)，超出则拒绝发送 */
+export const FILE_MAX_BYTES = 20 * 1024 * 1024;
+
+/** 绝对大小上限，等于 FILE_MAX_BYTES */
+export const ABSOLUTE_MAX_BYTES = FILE_MAX_BYTES;
+
+/** 语音类型支持的 MIME 集合（企微仅支持 AMR 格式语音消息） */
+export const VOICE_SUPPORTED_MIMES = new Set(["audio/amr"]);

package/src/media/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 媒体上传模块公共导出
+ */
+export { uploadAndSendMediaBuffer } from "./uploader.js";
+export type { UploadAndSendMediaBufferOptions, UploadAndSendMediaResult } from "./uploader.js";
+export { detectWeComMediaType, applyFileSizeLimits } from "./uploader.js";
+export type { FileSizeCheckResult } from "./uploader.js";
+export {
+  IMAGE_MAX_BYTES,
+  VIDEO_MAX_BYTES,
+  VOICE_MAX_BYTES,
+  FILE_MAX_BYTES,
+  ABSOLUTE_MAX_BYTES,
+  VOICE_SUPPORTED_MIMES,
+} from "./const.js";

package/src/media/uploader.ts

@@ -0,0 +1,240 @@
+/**
+ * WeCom WS 模式媒体上传工具模块
+ *
+ * 接收 deliver callback 已加载的 Buffer，执行：
+ *   detectWeComMediaType → applyFileSizeLimits → wsClient.uploadMedia → wsClient.sendMediaMessage
+ *
+ * 不含 resolveMediaFile（由 deliver callback 提供 Buffer）。
+ */
+
+import type { WeComMediaType, WSClient } from "@wecom/aibot-node-sdk";
+import {
+  IMAGE_MAX_BYTES,
+  VIDEO_MAX_BYTES,
+  VOICE_MAX_BYTES,
+  ABSOLUTE_MAX_BYTES,
+  VOICE_SUPPORTED_MIMES,
+} from "./const.js";
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** 文件大小检查结果 */
+export interface FileSizeCheckResult {
+  /** 最终确定的企微媒体类型（可能被降级） */
+  finalType: WeComMediaType;
+  /** 是否需要拒绝（超过绝对限制） */
+  shouldReject: boolean;
+  /** 拒绝原因（仅 shouldReject=true 时有值） */
+  rejectReason?: string;
+  /** 是否发生了降级 */
+  downgraded: boolean;
+  /** 降级说明（仅 downgraded=true 时有值） */
+  downgradeNote?: string;
+}
+
+/** uploadAndSendMediaBuffer 的参数 */
+export interface UploadAndSendMediaBufferOptions {
+  /** WSClient 实例 */
+  wsClient: WSClient;
+  /** 文件数据（deliver callback 已读取） */
+  buffer: Buffer;
+  /** MIME 类型（deliver callback 已检测） */
+  contentType: string;
+  /** 文件名（deliver callback 已提取） */
+  fileName: string;
+  /** 目标会话 ID（单聊为 userid，群聊为 chatid） */
+  chatId: string;
+  /** 日志函数 */
+  log?: (msg: string) => void;
+  /** 错误日志函数 */
+  errorLog?: (msg: string) => void;
+}
+
+/** uploadAndSendMediaBuffer 的返回结果 */
+export interface UploadAndSendMediaResult {
+  /** 是否发送成功 */
+  ok: boolean;
+  /** 最终的企微媒体类型 */
+  finalType?: WeComMediaType;
+  /** 是否被拒绝（文件过大） */
+  rejected?: boolean;
+  /** 拒绝原因 */
+  rejectReason?: string;
+  /** 是否发生了降级 */
+  downgraded?: boolean;
+  /** 降级说明 */
+  downgradeNote?: string;
+  /** 错误信息 */
+  error?: string;
+}
+
+// ============================================================================
+// MIME → 企微媒体类型映射
+// ============================================================================
+
+/**
+ * 根据 MIME 类型检测企微媒体类型
+ */
+export function detectWeComMediaType(mimeType: string): WeComMediaType {
+  const mime = mimeType.toLowerCase();
+
+  if (mime.startsWith("image/")) return "image";
+  if (mime.startsWith("video/")) return "video";
+  if (mime.startsWith("audio/") || mime === "application/ogg") return "voice";
+
+  return "file";
+}
+
+// ============================================================================
+// 文件大小检查与降级
+// ============================================================================
+
+/**
+ * 检查文件大小并执行降级策略
+ *
+ * 降级规则：
+ * - voice 非 AMR 格式 → 降级为 file
+ * - image 超过 10MB → 降级为 file
+ * - video 超过 10MB → 降级为 file
+ * - voice 超过 2MB → 降级为 file
+ * - file 超过 20MB → 拒绝发送
+ */
+export function applyFileSizeLimits(
+  fileSize: number,
+  detectedType: WeComMediaType,
+  contentType?: string,
+): FileSizeCheckResult {
+  const fileSizeMB = (fileSize / (1024 * 1024)).toFixed(2);
+
+  // 绝对上限 20MB
+  if (fileSize > ABSOLUTE_MAX_BYTES) {
+    return {
+      finalType: detectedType,
+      shouldReject: true,
+      rejectReason: `文件大小 ${fileSizeMB}MB 超过企业微信最大限制 20MB，无法发送`,
+      downgraded: false,
+    };
+  }
+
+  switch (detectedType) {
+    case "image":
+      if (fileSize > IMAGE_MAX_BYTES) {
+        return {
+          finalType: "file",
+          shouldReject: false,
+          downgraded: true,
+          downgradeNote: `图片大小 ${fileSizeMB}MB 超过 10MB 限制，已转为文件格式发送`,
+        };
+      }
+      break;
+
+    case "video":
+      if (fileSize > VIDEO_MAX_BYTES) {
+        return {
+          finalType: "file",
+          shouldReject: false,
+          downgraded: true,
+          downgradeNote: `视频大小 ${fileSizeMB}MB 超过 10MB 限制，已转为文件格式发送`,
+        };
+      }
+      break;
+
+    case "voice":
+      // 企微语音仅支持 AMR 格式
+      if (contentType && !VOICE_SUPPORTED_MIMES.has(contentType.toLowerCase())) {
+        return {
+          finalType: "file",
+          shouldReject: false,
+          downgraded: true,
+          downgradeNote: `语音格式 ${contentType} 不支持，企微仅支持 AMR 格式，已转为文件格式发送`,
+        };
+      }
+      if (fileSize > VOICE_MAX_BYTES) {
+        return {
+          finalType: "file",
+          shouldReject: false,
+          downgraded: true,
+          downgradeNote: `语音大小 ${fileSizeMB}MB 超过 2MB 限制，已转为文件格式发送`,
+        };
+      }
+      break;
+
+    case "file":
+      break;
+  }
+
+  return {
+    finalType: detectedType,
+    shouldReject: false,
+    downgraded: false,
+  };
+}
+
+// ============================================================================
+// 核心：接收 Buffer → 上传 → 发送
+// ============================================================================
+
+/**
+ * 接收已有 Buffer，通过 WSClient 上传临时素材并发送媒体消息
+ *
+ * 流程：detectWeComMediaType → applyFileSizeLimits → uploadMedia → sendMediaMessage
+ */
+export async function uploadAndSendMediaBuffer(
+  options: UploadAndSendMediaBufferOptions,
+): Promise<UploadAndSendMediaResult> {
+  const { wsClient, buffer, contentType, fileName, chatId, log, errorLog } = options;
+
+  try {
+    // 1. 检测企微媒体类型
+    const detectedType = detectWeComMediaType(contentType);
+    log?.(`media-upload: type=${detectedType} contentType=${contentType} size=${buffer.length} fileName=${fileName}`);
+
+    // 2. 文件大小检查与降级
+    const sizeCheck = applyFileSizeLimits(buffer.length, detectedType, contentType);
+
+    if (sizeCheck.shouldReject) {
+      errorLog?.(`media-upload: rejected — ${sizeCheck.rejectReason}`);
+      return {
+        ok: false,
+        rejected: true,
+        rejectReason: sizeCheck.rejectReason,
+        finalType: sizeCheck.finalType,
+      };
+    }
+
+    const finalType = sizeCheck.finalType;
+
+    if (sizeCheck.downgraded) {
+      log?.(`media-upload: downgraded ${detectedType}→${finalType} — ${sizeCheck.downgradeNote}`);
+    }
+
+    // 3. 分片上传获取 media_id
+    log?.(`media-upload: uploading ${finalType} (${buffer.length} bytes)...`);
+    const uploadResult = await wsClient.uploadMedia(buffer, {
+      type: finalType,
+      filename: fileName,
+    });
+    log?.(`media-upload: uploaded media_id=${uploadResult.media_id}`);
+
+    // 4. 通过 sendMediaMessage 主动发送
+    const videoOptions = finalType === "video" ? { title: fileName } : undefined;
+    await wsClient.sendMediaMessage(chatId, finalType, uploadResult.media_id, videoOptions);
+    log?.(`media-upload: sent to chatId=${chatId} type=${finalType}`);
+
+    return {
+      ok: true,
+      finalType,
+      downgraded: sizeCheck.downgraded,
+      downgradeNote: sizeCheck.downgradeNote,
+    };
+  } catch (err) {
+    const errMsg = String(err);
+    errorLog?.(`media-upload: failed — ${errMsg}`);
+    return {
+      ok: false,
+      error: errMsg,
+    };
+  }
+}