@xgjktech/xg_cwork_im 1.0.7 → 1.0.9

package/src/send-service.ts

@@ -1,68 +1,215 @@
-/**
- * XG-IM 消息发送模块
- *
- * 调用 IM 接口将 AI 回复发送到指定群聊，并 @ 原始发送者。
- */
-
-import axios from "axios";
-import type { Log } from "./auth.js";
-import type { GetLatestMsgListResponse, SendMessageBody, WsMessageParams, XgImConfig } from "./types.js";
-
-/**
- * 发送文本消息到指定 IM 群聊。
- *
- * @param config     插件配置
- * @param token      鉴权 token
- * @param groupId    目标群聊 ID（gid / groupId）
- * @param content    消息内容文本
- * @param atUserIds  需要 @ 的用户 ID 列表（可为空）
- * @param log        日志接口
- * @param msgId      可选的业务消息 ID（用于覆盖/更新已有消息）
- * @param reply      可选的被回复消息信息（用于在 IM 中建立“回复某条消息”的关联）
- */
-export async function sendTextMessage(
-    config: XgImConfig,
-    token: string,
-    groupId: string,
-    content: string,
-    atUserIds: string[] = [],
-    log?: Log,
-    msgId?: string,
-    reply?: SendMessageBody["reply"],
-): Promise<void> {
-    const url = `${config.baseUrl}/im/message/send`;
-
-    const body: SendMessageBody = {
-        type: "RICH_TEXT",
-        groupId,
-        text: content,
-        ...(atUserIds.length > 0 ? { atUserIds } : {}),
-        ...(msgId ? { msgId } : {}),
-        ...(reply ? { reply } : {}),
-    };
-
-    log?.info(`[cwork_im:send] POST ${url} groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);
-    if (config.debug) {
-        log?.debug?.(`[cwork_im:send] Request body: ${JSON.stringify(body)}`);
-    }
-
-    try {
-        const res = await axios.post(url, body, {
-            headers: {
-                "Content-Type": "application/json",
-                "access-token": token,
-            },
-            timeout: 10_000,
-        });
-
-        log?.info(`[cwork_im:send] Response status=${res.status}`);
-        if (config.debug) {
-            log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
-        }
-    } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
-        log?.error(`[cwork_im:send] Failed to send message to groupId=${groupId}: ${msg}`);
-        throw err;
-    }
-}
-
+/**
+ * XG-IM 消息发送模块
+ *
+ * 调用 IM 接口将 AI 回复发送到指定群聊，并 @ 原始发送者。
+ * 支持 RICH_TEXT 与带资源 fileId 的 FILE 类型（attachments）。
+ */
+
+import axios from "axios";
+import type { Log } from "./auth.js";
+import {
+    downloadMediaBuffer,
+    formatFromFilename,
+    resolveMaxAttachmentBytes,
+    resolveResourceUploadUrl,
+    uploadWholeResourceFile,
+} from "./resource-file.js";
+import type { SendMessageBody, SendMessageFileAttachment, SendMessageReply, XgImConfig } from "./types.js";
+
+function formatDeliverError(err: unknown): string {
+    if (axios.isAxiosError(err)) {
+        const parts = [err.message];
+        if (err.code) parts.push(`axiosCode=${err.code}`);
+        if (err.response?.status != null) parts.push(`httpStatus=${err.response.status}`);
+        return parts.join(" ");
+    }
+    if (err instanceof Error) return err.message;
+    return String(err);
+}
+
+async function postImMessage(
+    config: XgImConfig,
+    token: string,
+    groupId: string,
+    body: SendMessageBody,
+    atUserIds: string[] = [],
+    log?: Log,
+): Promise<void> {
+    const url = `${config.baseUrl}/im/message/send`;
+    const full: SendMessageBody = {
+        ...body,
+        groupId,
+        ...(atUserIds.length > 0 ? { atUserIds } : {}),
+    } as SendMessageBody;
+
+    log?.info(`[cwork_im:send] POST ${url} groupId=${groupId} type=${full.type} atUsers=${JSON.stringify(atUserIds)}`);
+    if (config.debug) {
+        log?.debug?.(`[cwork_im:send] Request body: ${JSON.stringify(full)}`);
+    }
+
+    try {
+        const res = await axios.post(url, full, {
+            headers: {
+                "Content-Type": "application/json",
+                "access-token": token,
+            },
+            timeout: 10_000,
+        });
+
+        log?.info(`[cwork_im:send] Response status=${res.status}`);
+        if (config.debug) {
+            log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
+        }
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log?.error(`[cwork_im:send] Failed to send message to groupId=${groupId}: ${msg}`);
+        throw err;
+    }
+}
+
+/** OpenClaw dispatch deliver 单块载荷：文本 + 可选媒体 URL（与 plugin-sdk 约定对齐）。 */
+export type ReplyDeliverPayload = {
+    markdown?: string;
+    text?: string;
+    isThinking?: boolean;
+    mediaUrl?: string;
+    mediaUrls?: string[];
+};
+
+/**
+ * 将 deliver 块发到 IM：若有媒体则先 POST baseUrl/file/upDownload/uploadWholeFile 再发 FILE；否则发 RICH_TEXT。
+ */
+export async function sendReplyDeliverBlock(
+    config: XgImConfig,
+    token: string,
+    groupId: string,
+    payload: ReplyDeliverPayload,
+    atUserIds: string[] = [],
+    log?: Log,
+    msgId?: string,
+    reply?: SendMessageReply,
+): Promise<void> {
+    const textToSend = (payload.markdown || payload.text || "").trim();
+    const mediaList = [
+        ...(payload.mediaUrl ? [payload.mediaUrl] : []),
+        ...((payload.mediaUrls ?? []).filter((u) => typeof u === "string" && u.trim())),
+    ];
+    const uniqueUrls = [...new Set(mediaList)];
+    const maxBytes = resolveMaxAttachmentBytes(config);
+    const formField = config.fileUploadFormField?.trim() || "file";
+
+    const wantFile = uniqueUrls.length > 0 && !payload.isThinking;
+
+    if (wantFile) {
+        const fileUploadUrl = resolveResourceUploadUrl(config.baseUrl);
+        try {
+            const attachments: SendMessageFileAttachment[] = [];
+            for (const u of uniqueUrls) {
+                const { buffer, filename } = await downloadMediaBuffer(u, maxBytes, log);
+                const { fileId } = await uploadWholeResourceFile({
+                    fileUploadUrl,
+                    token,
+                    buffer,
+                    filename,
+                    formField,
+                    log,
+                });
+                attachments.push({
+                    fileId,
+                    fileType: "FILE",
+                    format: formatFromFilename(filename),
+                    name: filename,
+                    size: buffer.length,
+                    source: "resource",
+                });
+            }
+            const caption = textToSend.length > 0 ? textToSend : " ";
+            await postImMessage(
+                config,
+                token,
+                groupId,
+                {
+                    type: "FILE",
+                    text: caption,
+                    attachments,
+                    ...(msgId ? { msgId } : {}),
+                    ...(reply ? { reply } : {}),
+                },
+                atUserIds,
+                log,
+            );
+            return;
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:send] FILE deliver failed, fallback to text if any: ${formatDeliverError(err)}`);
+            if (textToSend.length > 0) {
+                await postImMessage(
+                    config,
+                    token,
+                    groupId,
+                    {
+                        type: "RICH_TEXT",
+                        text: `${textToSend}\n\n（媒体未发出：${formatDeliverError(err)}）`,
+                        ...(msgId ? { msgId } : {}),
+                        ...(reply ? { reply } : {}),
+                    },
+                    atUserIds,
+                    log,
+                );
+            }
+            return;
+        }
+    }
+
+    if (textToSend.length > 0) {
+        await postImMessage(
+            config,
+            token,
+            groupId,
+            {
+                type: "RICH_TEXT",
+                text: textToSend,
+                ...(msgId ? { msgId } : {}),
+                ...(reply ? { reply } : {}),
+            },
+            atUserIds,
+            log,
+        );
+    }
+}
+
+/**
+ * 发送文本消息到指定 IM 群聊。
+ *
+ * @param config     插件配置
+ * @param token      鉴权 token
+ * @param groupId    目标群聊 ID（gid / groupId）
+ * @param content    消息内容文本
+ * @param atUserIds  需要 @ 的用户 ID 列表（可为空）
+ * @param log        日志接口
+ * @param msgId      可选的业务消息 ID（用于覆盖/更新已有消息）
+ * @param reply      可选的被回复消息信息（用于在 IM 中建立“回复某条消息”的关联）
+ */
+export async function sendTextMessage(
+    config: XgImConfig,
+    token: string,
+    groupId: string,
+    content: string,
+    atUserIds: string[] = [],
+    log?: Log,
+    msgId?: string,
+    reply?: SendMessageReply,
+): Promise<void> {
+    await postImMessage(
+        config,
+        token,
+        groupId,
+        {
+            type: "RICH_TEXT",
+            text: content,
+            ...(msgId ? { msgId } : {}),
+            ...(reply ? { reply } : {}),
+        },
+        atUserIds,
+        log,
+    );
+}

package/src/tool-json-result.ts

@@ -0,0 +1,24 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+
+type ToolExecuteReturn = Awaited<ReturnType<NonNullable<AnyAgentTool["execute"]>>>;
+
+/**
+ * 与 `openclaw/plugin-sdk` 的 `jsonResult` 返回结构一致（AgentToolResult），
+ * 供工具 `execute` 使用。
+ *
+ * 部分环境下网关打包插件后，`import { jsonResult } from "openclaw/plugin-sdk"` 会变成
+ * `_pluginSdk.jsonResult` 且值为 `undefined`，调用时报
+ * `(0 , _pluginSdk.jsonResult) is not a function`。
+ * 使用本函数可避免依赖该命名导出在打包产物中是否保留。
+ */
+export function toolJsonResult(payload: unknown): ToolExecuteReturn {
+    if (payload === undefined) {
+        return { content: [{ type: "text", text: "" }] } as ToolExecuteReturn;
+    }
+    const text =
+        typeof payload === "string" ? JSON.stringify(payload) : JSON.stringify(payload, null, 2);
+    return {
+        content: [{ type: "text", text }],
+        details: payload,
+    } as ToolExecuteReturn;
+}

package/src/types.ts

@@ -37,6 +37,11 @@ export interface XgImAccountConfig {
     name?: string;
     /** 群聊策略：open = 不需要 @，mention = 必须 @ 机器人才触发 */
     groupPolicy?: "open" | "mention";
+    /** multipart 整文件上传字段名，默认 file（与 `/file/upDownload/uploadWholeFile` 约定一致时可不改） */
+    fileUploadFormField?: string;
+    maxAttachmentBytes?: number;
+    /** 覆盖顶层的入站附件 workspace 子目录（相对 Agent workspace） */
+    inboundMediaWorkspaceSubdir?: string;
 }
 
 export interface XgImConfig extends OpenClawConfig {
@@ -76,6 +81,21 @@ export interface XgImConfig extends OpenClawConfig {
      * - 仅用于保护「思考中」占位消息，避免长时间不被更新。
      */
     firstReplyTimeoutMs?: number;
+
+    /**
+     * 附件上传地址固定为 `{baseUrl}/file/upDownload/uploadWholeFile`，请求头 `access-token` 与发 IM 相同。
+     * multipart 字段名默认 `file`，可通过 fileUploadFormField 覆盖。
+     */
+    fileUploadFormField?: string;
+    /** 单个附件下载/上传允许的最大字节数，默认 50MB */
+    maxAttachmentBytes?: number;
+
+    /**
+     * 若配置为非空相对路径（相对于当前 Agent workspace 根目录）：入站附件会先下载到
+     * `{workspace}/{本字段}/{userId}/{YYYY-MM-DD}/{name}_{HHmmssmmm}.ext`，再向 OpenClaw 传入本地 `file://` 路径。
+     * 未配置或为空则仍使用 IM 返回的远程 URL。
+     */
+    inboundMediaWorkspaceSubdir?: string;
 }
 
 // ─── IM 接口 Request / Response ─────────────────────────────────────────────
@@ -113,6 +133,75 @@ export interface WsMessage {
     ts: number;
 }
 
+/**
+ * 与 IM 服务 `MsgFileVO` 对齐的附件项（WebSocket `msgContent.files[]`）。
+ */
+export interface MsgFileVO {
+    /** 文件下载链接，短期有效 */
+    url: string;
+    /** 文件格式，小写：pdf、png、docx、doc、ppt、txt、md 等 */
+    format?: string;
+    /** 文件 ID；若来自七牛等无业务 id 的场景可为空 */
+    fileId?: string;
+    /** 文件大小（字节） */
+    size?: number;
+    /** 文件名称，如 xxx.pdf */
+    name?: string;
+    /**
+     * IM 侧已解析的正文（如图片 OCR/说明、文档抽取的文本等）。
+     * 非空时插件会拼入入站 `Body`/`RawBody`，一并交给 OpenClaw。
+     */
+    content?: string;
+}
+
+/** @deprecated 使用 {@link MsgFileVO} */
+export type WsInboundFileItem = MsgFileVO;
+
+/** 常见 IM format → MIME，供 OpenClaw 媒体理解；未知格式返回 undefined */
+export function imFormatToMimeType(format: string | undefined): string | undefined {
+    const f = format?.trim().toLowerCase();
+    if (!f) return undefined;
+    const map: Record<string, string> = {
+        pdf: "application/pdf",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        doc: "application/msword",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ppt: "application/vnd.ms-powerpoint",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        xls: "application/vnd.ms-excel",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        zip: "application/zip",
+        mp3: "audio/mpeg",
+        wav: "audio/wav",
+        mp4: "video/mp4",
+    };
+    return map[f];
+}
+
+/**
+ * 入站消息内容体（与 IM WebSocket `params.msgContent` 对齐）。
+ *
+ * - **type=`text`**：纯文本；**text** 建议非空。
+ * - **type=`file`**：带 1..N 个文件，**files** 建议至少 1 项；**text** 可为配文（同时上传多文件 + 一句话）。**files[].content** 可由 IM 填已解析文本（如图/文档），插件会拼入入站正文。
+ * - 语音在 IM 侧已转写为文字时，应以 **type=`text`** 推送转写结果，不再使用 voice。
+ */
+export interface WsMessageContent {
+    /** 文本正文；纯文本消息为主内容；file 消息上为可选配文 */
+    text?: string;
+    /** `text` | `file`（可扩展其它枚举，插件对未知类型按文本兜底） */
+    type: string;
+    /** 多附件；type 为 file 时由 IM 填至少一项 */
+    files?: MsgFileVO[];
+    ext?: Record<string, any>;
+}
+
 /** robotMention 消息的 params */
 export interface WsMessageParams {
     msgId: string;
@@ -129,12 +218,7 @@ export interface WsMessageParams {
          */
         background?: string;
     };
-    msgContent: {
-        text: string;
-        type: string;
-        url?: string;
-        ext?: Record<string, any>;
-    };
+    msgContent: WsMessageContent;
     /** 服务端可能返回 msgSendTime 或 timestamp */
     msgSendTime?: number;
     timestamp?: number;
@@ -156,29 +240,40 @@ export interface SendMessageReply {
     previewText: string;
 }
 
-export interface SendMessageBody {
-    type: "TEXT" | "RICH_TEXT" | "VOICE";
-    groupId?: string;
-    toUserId?: string;
-    text: string;
-    atUserIds?: string[];
-    /**
-     * 业务侧生成的消息 ID。
-     *
-     * - 若不传：服务端按普通“新消息”处理。
-     * - 若传入：服务端可根据 msgId 更新已有的流式占位消息内容。
-     */
-    msgId?: string;
-
-    /**
-     * 被回复消息信息。
-     *
-     * - 若不传：视为普通消息。
-     * - 若传入：服务端可按 targetMsgId 建立“回复某条消息”的关联。
-     */
-    reply?: SendMessageReply;
+/** IM 发送 FILE 类型消息时的附件项（与发消息接口约定一致） */
+export interface SendMessageFileAttachment {
+    fileId: string;
+    /** 固定为 FILE */
+    fileType: "FILE";
+    /** 小写扩展名，如 md、pdf */
+    format: string;
+    name: string;
+    size: number;
+    /** 固定为 resource */
+    source: "resource";
 }
 
+export type SendMessageBody =
+    | {
+          type: "TEXT" | "RICH_TEXT" | "VOICE";
+          groupId?: string;
+          toUserId?: string;
+          text: string;
+          atUserIds?: string[];
+          msgId?: string;
+          reply?: SendMessageReply;
+      }
+    | {
+          type: "FILE";
+          groupId?: string;
+          toUserId?: string;
+          text: string;
+          attachments: SendMessageFileAttachment[];
+          atUserIds?: string[];
+          msgId?: string;
+          reply?: SendMessageReply;
+      };
+
 /** GET /im/message/getLatestMsgListForAI 响应 */
 export interface GetLatestMsgListResponse {
     data?: WsMessageParams[];