@wecom/wecom-openclaw-plugin 1.0.9-beta.1 → 1.0.10-beta.0

package/dist/src/const.d.ts

@@ -52,3 +52,15 @@ export declare const PLUGIN_JSON_PATH: string;
 export declare const DEFAULT_MEDIA_MAX_MB = 5;
 /** 文本分块大小上限 */
 export declare const TEXT_CHUNK_LIMIT = 4000;
+/** 图片大小上限（字节）：10MB */
+export declare const IMAGE_MAX_BYTES: number;
+/** 视频大小上限（字节）：10MB */
+export declare const VIDEO_MAX_BYTES: number;
+/** 语音大小上限（字节）：2MB */
+export declare const VOICE_MAX_BYTES: number;
+/** 文件大小上限（字节）：20MB */
+export declare const FILE_MAX_BYTES: number;
+/** 文件绝对上限（字节）：超过此值无法发送，等于 FILE_MAX_BYTES */
+export declare const ABSOLUTE_MAX_BYTES: number;
+/** 上传分片大小（字节，Base64 编码前）：512KB */
+export declare const UPLOAD_CHUNK_SIZE: number;

package/dist/src/interface.d.ts

@@ -20,6 +20,16 @@ export interface MessageState {
     accumulatedText: string;
     /** 流式回复的 streamId，用于保持同一个流式回复使用相同的 streamId */
     streamId?: string;
+    /** 是否有用户可见的文本内容（不包括 <think>...</think> 标签） */
+    hasText?: boolean;
+    /** 是否已成功发送过媒体文件 */
+    hasMedia?: boolean;
+    /** 是否有媒体发送失败（权限不足、文件过大等） */
+    hasMediaFailed?: boolean;
+    /** 媒体发送失败时的纯文本错误摘要（用于替换 thinking 流展示给用户） */
+    mediaErrorSummary?: string;
+    /** deliver 回调是否被调用过（用于区分"核心无回复"和"核心回复了空内容"） */
+    deliverCalled?: boolean;
 }
 /**
  * MCP 配置响应体

package/dist/src/media-uploader.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 企业微信出站媒体上传工具模块
+ *
+ * 负责：
+ * - 从 mediaUrl 加载文件 buffer（远程 URL 或本地路径均支持）
+ * - 检测 MIME 类型并映射为企微媒体类型
+ * - 文件大小检查与降级策略
+ */
+import type { WeComMediaType, WSClient, WsFrameHeaders } from "@wecom/aibot-node-sdk";
+/** 媒体文件解析结果 */
+export interface ResolvedMedia {
+    /** 文件数据 */
+    buffer: Buffer;
+    /** 检测到的 MIME 类型 */
+    contentType: string;
+    /** 文件名（从 URL 提取或默认生成） */
+    fileName: string;
+}
+/** 文件大小检查结果 */
+export interface FileSizeCheckResult {
+    /** 最终确定的企微媒体类型（可能被降级） */
+    finalType: WeComMediaType;
+    /** 是否需要拒绝（超过绝对限制） */
+    shouldReject: boolean;
+    /** 拒绝原因（仅 shouldReject=true 时有值） */
+    rejectReason?: string;
+    /** 是否发生了降级 */
+    downgraded: boolean;
+    /** 降级说明（仅 downgraded=true 时有值） */
+    downgradeNote?: string;
+}
+/**
+ * 根据 MIME 类型检测企微媒体类型
+ *
+ * @param mimeType - MIME 类型字符串
+ * @returns 企微媒体类型
+ */
+export declare function detectWeComMediaType(mimeType: string): WeComMediaType;
+/**
+ * 从 mediaUrl 加载媒体文件
+ *
+ * 支持远程 URL（http/https）和本地路径（file:// 或绝对路径），
+ * 利用 openclaw plugin-sdk 的 loadOutboundMediaFromUrl 统一处理。
+ *
+ * @param mediaUrl - 媒体文件的 URL 或本地路径
+ * @param mediaLocalRoots - 允许读取本地文件的安全白名单目录
+ * @returns 解析后的媒体文件信息
+ */
+export declare function resolveMediaFile(mediaUrl: string, mediaLocalRoots?: readonly string[]): Promise<ResolvedMedia>;
+/**
+ * 检查文件大小并执行降级策略
+ *
+ * 降级规则：
+ * - voice 非 AMR 格式 → 降级为 file（企微后台仅支持 AMR）
+ * - image 超过 10MB → 降级为 file
+ * - video 超过 10MB → 降级为 file
+ * - voice 超过 2MB → 降级为 file
+ * - file 超过 20MB → 拒绝发送
+ *
+ * @param fileSize - 文件大小（字节）
+ * @param detectedType - 检测到的企微媒体类型
+ * @param contentType - 文件的 MIME 类型（用于语音格式校验）
+ * @returns 大小检查结果
+ */
+export declare function applyFileSizeLimits(fileSize: number, detectedType: WeComMediaType, contentType?: string): FileSizeCheckResult;
+/** uploadAndSendMedia 的参数 */
+export interface UploadAndSendMediaOptions {
+    /** WSClient 实例 */
+    wsClient: WSClient;
+    /** 媒体文件的 URL 或本地路径 */
+    mediaUrl: string;
+    /** 目标会话 ID（用于 aibot_send_msg 主动发送） */
+    chatId: string;
+    /** 允许读取本地文件的安全白名单目录 */
+    mediaLocalRoots?: readonly string[];
+    /** 日志函数 */
+    log?: (...args: any[]) => void;
+    /** 错误日志函数 */
+    errorLog?: (...args: any[]) => void;
+}
+/** uploadAndSendMedia 的返回结果 */
+export interface UploadAndSendMediaResult {
+    /** 是否发送成功 */
+    ok: boolean;
+    /** 发送后返回的 messageId */
+    messageId?: string;
+    /** 最终的企微媒体类型 */
+    finalType?: WeComMediaType;
+    /** 是否被拒绝（文件过大） */
+    rejected?: boolean;
+    /** 拒绝原因 */
+    rejectReason?: string;
+    /** 是否发生了降级 */
+    downgraded?: boolean;
+    /** 降级说明 */
+    downgradeNote?: string;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 公共媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → sendMediaMessage
+ * 媒体消息统一走 aibot_send_msg 主动发送，避免多文件场景下 reqId 只能用一次的问题。
+ * channel.ts 的 sendMedia 和 monitor.ts 的 deliver 回调都使用此函数。
+ */
+export declare function uploadAndSendMedia(options: UploadAndSendMediaOptions): Promise<UploadAndSendMediaResult>;
+/** uploadAndReplyMedia 的参数 */
+export interface UploadAndReplyMediaOptions {
+    /** WSClient 实例 */
+    wsClient: WSClient;
+    /** 媒体文件的 URL 或本地路径 */
+    mediaUrl: string;
+    /** 原始 WebSocket 帧（用于 aibot_respond_msg 被动回复，携带 req_id） */
+    frame: WsFrameHeaders;
+    /** 允许读取本地文件的安全白名单目录 */
+    mediaLocalRoots?: readonly string[];
+    /** 日志函数 */
+    log?: (...args: any[]) => void;
+    /** 错误日志函数 */
+    errorLog?: (...args: any[]) => void;
+}
+/**
+ * 被动回复媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → replyMedia
+ * 通过 aibot_respond_msg 被动回复通道发送媒体消息，可以覆盖之前的 THINKING_MESSAGE。
+ *
+ * 适用场景：回包只有媒体没有文本时，第一个媒体文件用此方法发送以清理 thinking 状态。
+ */
+export declare function uploadAndReplyMedia(options: UploadAndReplyMediaOptions): Promise<UploadAndSendMediaResult>;

package/dist/src/openclaw-compat.d.ts

@@ -0,0 +1,48 @@
+/**
+ * openclaw plugin-sdk 高版本方法兼容层
+ *
+ * 部分方法（如 loadOutboundMediaFromUrl、detectMime、getDefaultMediaLocalRoots）
+ * 仅在较新版本的 openclaw plugin-sdk 中才导出。
+ *
+ * 本模块在加载时一次性探测 SDK 导出，存在则直接 re-export SDK 版本，
+ * 不存在则导出 fallback 实现。其他模块统一从本文件导入，无需关心底层兼容细节。
+ */
+/** 与 openclaw plugin-sdk 中 WebMediaResult 兼容的类型 */
+export type WebMediaResult = {
+    buffer: Buffer;
+    contentType?: string;
+    kind?: string;
+    fileName?: string;
+};
+export type OutboundMediaLoadOptions = {
+    maxBytes?: number;
+    mediaLocalRoots?: readonly string[];
+};
+export type DetectMimeOptions = {
+    buffer?: Buffer;
+    headerMime?: string | null;
+    filePath?: string;
+};
+/**
+ * 检测 MIME 类型（兼容入口）
+ *
+ * 支持两种调用签名以兼容不同使用场景：
+ * - detectMime(buffer)           → 旧式调用
+ * - detectMime({ buffer, headerMime, filePath }) → 完整参数
+ *
+ * 优先使用 SDK 版本，不可用时使用 fallback。
+ */
+export declare function detectMime(bufferOrOpts: Buffer | DetectMimeOptions): Promise<string | undefined>;
+/**
+ * 从 URL 或本地路径加载媒体文件（兼容入口）
+ *
+ * 优先使用 SDK 版本，不可用时使用 fallback。
+ * SDK 版本抛出的业务异常（如 LocalMediaAccessError）会直接透传。
+ */
+export declare function loadOutboundMediaFromUrl(mediaUrl: string, options?: OutboundMediaLoadOptions): Promise<WebMediaResult>;
+/**
+ * 获取默认媒体本地路径白名单（兼容入口）
+ *
+ * 优先使用 SDK 版本，不可用时手动构建白名单（与 weclaw/src/media/local-roots.ts 逻辑一致）。
+ */
+export declare function getDefaultMediaLocalRoots(): Promise<readonly string[]>;

package/dist/src/utils.d.ts

@@ -28,6 +28,8 @@ export interface WeComConfig {
     groups?: Record<string, WeComGroupConfig>;
     /** 是否发送"思考中"消息，默认为 true */
     sendThinkingMessage?: boolean;
+    /** 额外允许访问的本地媒体路径白名单（支持 ~ 表示 home 目录），如 ["~/Downloads", "~/Documents"] */
+    mediaLocalRoots?: string[];
 }
 export declare const DefaultWsUrl = "wss://openws.work.weixin.qq.com";
 export interface ResolvedWeComAccount {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "1.0.9-beta.1",
+  "version": "1.0.10-beta.0",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@wecom/aibot-node-sdk": "^1.0.1",
+    "@wecom/aibot-node-sdk": "^1.0.2",
     "file-type": "^21.3.0"
   }
 }