@xgjktech/xg_cwork_im 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgjktech/xg_cwork_im",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "XG CWork IM channel plugin for OpenClaw",
   "keywords": [
     "bot",

package/src/channel.ts

@@ -13,16 +13,20 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
 import { z } from "zod";
 import { clearTokenCache, getToken } from "./auth.js";
-import { startWebSocket } from "./connection.js";
-import { sendTextMessage } from "./send-service.js";
-import type {
-    GatewayStartContext,
-    PluginRuntime,
-    ResolvedAccount,
-    WsMessage,
-    WsMessageParams,
-    XgImChannelPlugin,
-    XgImConfig,
+import { startWebSocket, type ImStreamClient } from "./connection.js";
+import { sendReplyDeliverBlock, sendTextMessage, type ReplyDeliverPayload } from "./send-service.js";
+import {
+    imFormatToMimeType,
+    type BotIdentity,
+    type GatewayStartContext,
+    type MsgFileVO,
+    type PluginRuntime,
+    type ResolvedAccount,
+    type WsMessage,
+    type WsMessageContent,
+    type WsMessageParams,
+    type XgImChannelPlugin,
+    type XgImConfig,
 } from "./types.js";
 
 // ─── 全局 Runtime（在 index.ts 的 register 中注入）────────────────────────────
@@ -47,6 +51,8 @@ const XgImAccountConfigSchema = z.object({
     agentId: z.string().optional().default("main"),
     name: z.string().optional(),
     groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
+    fileUploadFormField: z.string().min(1).optional(),
+    maxAttachmentBytes: z.number().int().positive().optional(),
 });
 
 const XgImConfigSchema = z.object({
@@ -63,6 +69,8 @@ const XgImConfigSchema = z.object({
     initialReconnectDelay: z.number().int().positive().optional().default(1_000),
     maxReconnectDelay: z.number().int().positive().optional().default(60_000),
     reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
+    fileUploadFormField: z.string().min(1).optional(),
+    maxAttachmentBytes: z.number().int().positive().optional(),
     // 多账户：对象 map（key 为 accountId）
     accounts: z.record(z.string(), XgImAccountConfigSchema).optional(),
 }).superRefine((val, ctx) => {
@@ -140,6 +148,210 @@ function toLogger(sink: { info?: (msg: string) => void; warn?: (msg: string) =>
     };
 }
 
+// ─── WebSocket 入站：纯函数与 @ 后派发 ───────────────────────────────────────
+
+function collectFileItems(msgContent: WsMessageContent | undefined): MsgFileVO[] {
+    return (msgContent?.files ?? []).filter((f) => f.url?.trim());
+}
+
+function buildInboundDisplayText(msgContent: WsMessageContent | undefined, fileItems: MsgFileVO[]): string {
+    let rawText = msgContent?.text ?? "";
+    if (fileItems.length > 0) {
+        const names = fileItems
+            .map((f) => f.name?.trim() || f.fileId || "未命名文件")
+            .join("、");
+        const fileNote = `[附件 ${fileItems.length} 个: ${names}]`;
+        rawText = rawText.trim() ? `${rawText.trim()}\n\n${fileNote}` : fileNote;
+    }
+    return rawText;
+}
+
+function isActuallyMentioned(
+    msg: WsMessage,
+    params: WsMessageParams,
+    bot: { userId: string; name: string },
+    rawTextForLegacy: string,
+): boolean {
+    const mentions = params.mentions;
+    const isMentioned =
+        Array.isArray(mentions) && (mentions.includes(bot.userId) || mentions.includes("all"));
+    const isLegacyMentioned =
+        msg.cmd === "robotMention" &&
+        (!params.mentions || params.mentions.length === 0) &&
+        new RegExp(`@${bot.name}\\b`).test(rawTextForLegacy);
+    return isMentioned || isLegacyMentioned;
+}
+
+function mediaFieldsFromFileItems(fileItems: MsgFileVO[]): Record<string, unknown> {
+    if (fileItems.length === 0) return {};
+    const mimes = fileItems.map(
+        (f) => imFormatToMimeType(f.format) ?? "application/octet-stream",
+    );
+    return {
+        MediaPath: fileItems[0]!.url,
+        MediaUrl: fileItems[0]!.url,
+        MediaPaths: fileItems.map((f) => f.url),
+        MediaUrls: fileItems.map((f) => f.url),
+        MediaType: mimes[0],
+        MediaTypes: mimes,
+    };
+}
+
+function untrustedContextFromExtAndBackground(
+    msgExt: WsMessageContent["ext"],
+    senderBackground: string | undefined,
+): string[] | undefined {
+    const parts: string[] = [];
+    if (msgExt) parts.push(JSON.stringify(msgExt));
+    if (senderBackground) parts.push(String(senderBackground));
+    return parts.length > 0 ? parts : undefined;
+}
+
+function buildTargetReplyMeta(params: WsMessageParams): {
+    targetMsgId: string;
+    targetUserId: string;
+    targetUserName: string;
+    previewText: string;
+} {
+    return {
+        targetMsgId: params.msgId,
+        targetUserId: params.userInfo?.id ?? "",
+        targetUserName: params.userInfo?.name ?? "未知用户",
+        previewText: params.msgContent?.text ?? "",
+    };
+}
+
+/** 流式 START → dispatch → 必发 END；首包超时走 HTTP 覆盖占位 */
+async function dispatchMentionedReply(args: {
+    rt: any;
+    cfg: OpenClawConfig;
+    config: XgImConfig;
+    log: Logger;
+    logPrefix: string;
+    route: { sessionKey: string };
+    inboundCtx: unknown;
+    params: WsMessageParams;
+    currentIdentity: BotIdentity;
+    streamClient: ImStreamClient;
+}): Promise<void> {
+    const { rt, cfg, config, log, logPrefix, route, inboundCtx, params, currentIdentity, streamClient } = args;
+
+    log.info(`${logPrefix} [dispatch] Dispatching to OpenClaw AI, sessionKey=${route.sessionKey}`);
+    let isFirstReply = true;
+    const dispatchStart = Date.now();
+
+    const { msgId: streamMsgId } = await streamClient.start({
+        groupId: params.groupId,
+    });
+    log.info(`${logPrefix} [stream] START acknowledged: msgId=${streamMsgId}`);
+
+    let hasFirstReply = false;
+    const firstReplyTimeoutMs = config.firstReplyTimeoutMs ?? 30 * 60_000;
+    const timeoutLabel = `${logPrefix} [stream] First reply timeout after ${firstReplyTimeoutMs}ms, updating thinking message as error`;
+    const firstReplyTimeout = setTimeout(async () => {
+        if (hasFirstReply) return;
+        log.warn(timeoutLabel);
+        try {
+            const reply = buildTargetReplyMeta(params);
+            const timeoutText = "当前请求处理超时，请稍后重试。";
+            await sendTextMessage(
+                config,
+                currentIdentity.token,
+                params.groupId,
+                timeoutText,
+                [reply.targetUserId] as string[],
+                log,
+                streamMsgId,
+                reply,
+            );
+            log.info(
+                `${logPrefix} [send] Timeout reply sent via HTTP: groupId=${params.groupId} msgId=${streamMsgId} text="${timeoutText}"`,
+            );
+        } catch (err: unknown) {
+            log.error(`${logPrefix} [timeout] Failed to send timeout reply: ${String(err)}`);
+        }
+    }, firstReplyTimeoutMs);
+
+    try {
+        await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: inboundCtx,
+            cfg,
+            dispatcherOptions: {
+                responsePrefix: "",
+                deliver: async (payload: ReplyDeliverPayload) => {
+                    try {
+                        const textPart = (payload.markdown || payload.text || "").trim();
+                        const hasMedia =
+                            Boolean(payload.mediaUrl?.trim()) ||
+                            Boolean(payload.mediaUrls?.some((u) => typeof u === "string" && u.trim()));
+                        if (!textPart && !(hasMedia && !payload.isThinking)) return;
+
+                        if (isFirstReply) {
+                            const ttfr = Date.now() - dispatchStart;
+                            log.info(
+                                `${logPrefix} [deliver] First response block received from AI (TTFB: ${ttfr}ms)`,
+                            );
+                            isFirstReply = false;
+                        }
+
+                        const reply = buildTargetReplyMeta(params);
+                        const atIds = [reply.targetUserId] as string[];
+
+                        if (!hasFirstReply) {
+                            hasFirstReply = true;
+                            clearTimeout(firstReplyTimeout);
+                            await sendReplyDeliverBlock(
+                                config,
+                                currentIdentity.token,
+                                params.groupId,
+                                payload,
+                                atIds,
+                                log,
+                                streamMsgId,
+                                reply,
+                            );
+                            const preview =
+                                textPart.length > 80 ? `${textPart.slice(0, 80)}...` : textPart || "[media]";
+                            log.info(
+                                `${logPrefix} [send] First reply sent via HTTP: groupId=${params.groupId} msgId=${streamMsgId} preview="${preview}"`,
+                            );
+                            return;
+                        }
+
+                        await sendReplyDeliverBlock(
+                            config,
+                            currentIdentity.token,
+                            params.groupId,
+                            payload,
+                            atIds,
+                            log,
+                            undefined,
+                            reply,
+                        );
+                        const preview =
+                            textPart.length > 80 ? `${textPart.slice(0, 80)}...` : textPart || "[media]";
+                        log.info(
+                            `${logPrefix} [send] Additional reply sent via HTTP: groupId=${params.groupId} preview="${preview}"`,
+                        );
+                    } catch (err: unknown) {
+                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
+                        throw err;
+                    }
+                },
+            },
+        });
+        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
+    } finally {
+        clearTimeout(firstReplyTimeout);
+        try {
+            await streamClient.end(streamMsgId, "stop");
+            log.info(`${logPrefix} [stream] END sent: msgId=${streamMsgId}`);
+        } catch (endErr: unknown) {
+            log.error(`${logPrefix} [stream] END failed (msgId=${streamMsgId}): ${String(endErr)}`);
+        }
+    }
+}
+
 // ─── Channel Plugin 定义 ─────────────────────────────────────────────────────
 
 export const xgCworkImChannelPlugin: XgImChannelPlugin = {
@@ -159,7 +371,7 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
         chatTypes: ["group"] as Array<"direct" | "group">,
         reactions: false,
         threads: false,
-        media: false,
+        media: true,
         nativeCommands: false,
         blockStreaming: false,
     },
@@ -260,6 +472,35 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
                 messageId: randomUUID(),
             };
         },
+
+        /** 出站带媒体：上传资源后发 FILE，与网关 deliver 逻辑一致（OpenClaw 要求与 sendText 同时实现） */
+        sendMedia: async (ctx) => {
+            const { cfg, to, text, mediaUrl, accountId, log: ctxLog } = ctx as typeof ctx & { log?: Logger };
+            const log = toLogger(ctxLog);
+            const config = getXgImConfig(cfg, accountId);
+            const identity = await getToken(config, log);
+
+            if (!mediaUrl?.trim()) {
+                await sendTextMessage(config, identity.token, to, text || "", [], log);
+                return { channel: "xg_cwork_im", messageId: randomUUID() };
+            }
+
+            await sendReplyDeliverBlock(
+                config,
+                identity.token,
+                to,
+                { text: text || "", mediaUrl: mediaUrl.trim() },
+                [],
+                log,
+                undefined,
+                undefined,
+            );
+
+            return {
+                channel: "xg_cwork_im",
+                messageId: randomUUID(),
+            };
+        },
     },
 
     // ── 网关（WebSocket 长连接）─────────────────────────────────────────────────
@@ -315,22 +556,16 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
                     }
 
                     const msgContent = params.msgContent;
-                    const msgType = msgContent?.type ?? "text";
-                    const msgUrl = msgContent?.url;
+                    const fileItems = collectFileItems(msgContent);
                     const msgExt = msgContent?.ext;
                     const senderId = params.userInfo?.id;
                     const senderName = params.userInfo?.name || senderId || "";
                     const senderBackground = params.userInfo?.background;
 
-                    let rawText = msgContent?.text ?? "";
-                    // 如果是语音消息且没有文本内容，设为占位符
-                    if (msgType === "voice" && !rawText) {
-                        rawText = "[语音消息]";
-                    }
-                    const text = rawText;
+                    const text = buildInboundDisplayText(msgContent, fileItems);
 
-                    if (!text && !msgUrl) {
-                        log.debug?.(`${logPrefix} Empty message (no text and no url), skipping`);
+                    if (!text.trim() && fileItems.length === 0) {
+                        log.debug?.(`${logPrefix} Empty message (no text and no files), skipping`);
                         return;
                     }
 
@@ -338,21 +573,8 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
                         `${logPrefix} Message from ${senderName}(${senderId ?? "unknown"}) in group=${params.groupId}: ${text}`,
                     );
 
-                    // 1. 获取当前机器人身份
                     const currentIdentity = await getToken(config, log);
-                    // 2. 判定是否真正 @ 了当前机器人
-                    const mentions = params.mentions;
-                    const isMentioned = Array.isArray(mentions) &&
-                        (mentions.includes(currentIdentity.userId) || mentions.includes("all"));
-
-                    // (补充逻辑) 如果是 robotMention 指令，但没有 mentions 列表，则降级为老逻辑：文本正则匹配
-                    const isLegacyMentioned = msg.cmd === "robotMention" &&
-                        (!params.mentions || params.mentions.length === 0) &&
-                        new RegExp(`@${currentIdentity.name}\\b`).test(rawText);
-
-                    const actuallyMentioned = isMentioned || isLegacyMentioned;
-
-                    // 3. 构建 OpenClaw 视角的“单条纯净消息”
+                    const actuallyMentioned = isActuallyMentioned(msg, params, currentIdentity, text);
 
                     // 通过 PluginRuntime 路由消息到 OpenClaw
                     const route = rt.channel.routing.resolveAgentRoute({
@@ -407,16 +629,8 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
                         OriginatingChannel: "xg_cwork_im",
                         OriginatingTo: params.groupId,
                         GroupChannel: route.sessionKey,
-                        // 透传媒体信息
-                        MediaUrl: msgUrl,
-                        MediaType: msgType === "voice" ? "voice" : undefined,
-                        // 透传扩展字段给 AI (作为 UntrustedContext)
-                        UntrustedContext: (() => {
-                            const parts: string[] = [];
-                            if (msgExt) parts.push(JSON.stringify(msgExt));
-                            if (senderBackground) parts.push(String(senderBackground));
-                            return parts.length > 0 ? parts : undefined;
-                        })(),
+                        ...mediaFieldsFromFileItems(fileItems),
+                        UntrustedContext: untrustedContextFromExtAndBackground(msgExt, senderBackground),
                         // 同时保留原始 ext 供可能的后续逻辑使用
                         XgImExt: msgExt,
                     });
@@ -449,140 +663,19 @@ export const xgCworkImChannelPlugin: XgImChannelPlugin = {
                         },
                     });
 
-                    // 【只有真 @ 我的消息才做】呼叫 AI 激活推理
                     if (actuallyMentioned) {
-                        log.info(`${logPrefix} [dispatch] Dispatching to OpenClaw AI, sessionKey=${route.sessionKey}`);
-                        let isFirstReply = true;
-                        const dispatchStart = Date.now();
-
-                        // 1. 先向 IM 声明“开始流式消息”，拿到 msgId
-                        const { msgId } = await wsHandle.streamClient.start({
-                            groupId: params.groupId,
-                        });
-                        log.info(`${logPrefix} [stream] START acknowledged: msgId=${msgId}`);
-
-                        // 1.1 为“思考中”占位增加首回复超时保护（默认 30分钟，可通过 firstReplyTimeoutMs 配置）
-                        let hasFirstReply = false;
-                        let firstReplyTimedOut = false;
-                        const firstReplyTimeoutMs = config.firstReplyTimeoutMs ?? 30 * 60_000;
-                        const timeoutLabel = `${logPrefix} [stream] First reply timeout after ${firstReplyTimeoutMs}ms, updating thinking message as error`;
-                        const firstReplyTimeout = setTimeout(async () => {
-                            if (hasFirstReply) {
-                                return;
-                            }
-                            firstReplyTimedOut = true;
-                            log.warn(timeoutLabel);
-                            try {
-                                const senderId = params.userInfo?.id;
-                                const senderName = params.userInfo?.name ?? "未知用户";
-                                const text = params.msgContent?.text ?? "";
-                                const reply = {
-                                    targetMsgId: params.msgId,
-                                    targetUserId: senderId ?? "",
-                                    targetUserName: senderName,
-                                    previewText: text,
-                                };
-                                const timeoutText = "当前请求处理超时，请稍后重试。";
-                                await sendTextMessage(
-                                    config,
-                                    currentIdentity.token,
-                                    params.groupId,
-                                    timeoutText,
-                                    [senderId ?? ""] as string[],
-                                    log,
-                                    msgId,
-                                    reply,
-                                );
-                                log.info(
-                                    `${logPrefix} [send] Timeout reply sent via HTTP: groupId=${params.groupId} msgId=${msgId} text="${timeoutText}"`,
-                                );
-                            } catch (err: unknown) {
-                                log.error(`${logPrefix} [timeout] Failed to send timeout reply: ${String(err)}`);
-                            }
-                        }, firstReplyTimeoutMs);
-
-                        // 2. 分发消息给 AI，deliver 回调负责发送首条和后续回复
-                        let fullText = "";
-
-                        await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-                            ctx: inboundCtx,
+                        await dispatchMentionedReply({
+                            rt,
                             cfg: ctx.cfg,
-                            dispatcherOptions: {
-                                responsePrefix: "",
-                                deliver: async (payload: { markdown?: string; text?: string; isThinking?: boolean }) => {
-                                    try {
-                                        const textToSend = payload.markdown || payload.text;
-                                        if (!textToSend) return;
-
-                                        if (isFirstReply) {
-                                            const ttfr = Date.now() - dispatchStart;
-                                            log.info(`${logPrefix} [deliver] First response block received from AI (TTFB: ${ttfr}ms)`);
-                                            isFirstReply = false;
-                                        }
-
-                                        fullText += textToSend;
-
-                                        const senderId = params.userInfo?.id;
-                                        const senderName = params.userInfo?.name ?? "未知用户";
-                                        const text = params.msgContent?.text ?? "";
-                                        const reply = {
-                                            targetMsgId: params.msgId,
-                                            targetUserId: senderId ?? "",
-                                            targetUserName: senderName,
-                                            previewText: text,
-                                        };
-
-                                        // 第一次有效回复：覆盖“思考中”占位消息（带 msgId）
-                                        if (!hasFirstReply) {
-                                            hasFirstReply = true;
-                                            clearTimeout(firstReplyTimeout);
-                                            await sendTextMessage(
-                                                config,
-                                                currentIdentity.token,
-                                                params.groupId,
-                                                textToSend,
-                                                [senderId ?? ""] as string[],
-                                                log,
-                                                msgId,
-                                                reply,
-                                            );
-                                            const preview = textToSend.length > 80 ? `${textToSend.slice(0, 80)}...` : textToSend;
-                                            log.info(
-                                                `${logPrefix} [send] First reply sent via HTTP: groupId=${params.groupId} msgId=${msgId} text="${preview}"`,
-                                            );
-                                            return;
-                                        }
-
-                                        // 后续回复：作为独立消息发送（不再复用 msgId）
-                                        await sendTextMessage(
-                                            config,
-                                            currentIdentity.token,
-                                            params.groupId,
-                                            textToSend,
-                                            [senderId ?? ""] as string[],
-                                            log,
-                                            undefined,
-                                            reply,
-                                        );
-                                        const preview = textToSend.length > 80 ? `${textToSend.slice(0, 80)}...` : textToSend;
-                                        log.info(
-                                            `${logPrefix} [send] Additional reply sent via HTTP: groupId=${params.groupId} text="${preview}"`,
-                                        );
-                                    } catch (err: unknown) {
-                                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
-                                        throw err;
-                                    }
-                                },
-                            },
+                            config,
+                            log,
+                            logPrefix,
+                            route,
+                            inboundCtx,
+                            params,
+                            currentIdentity,
+                            streamClient: wsHandle.streamClient,
                         });
-
-                        // 3. AI 推理完成，发送 END，结束本次流式占位语义
-                        // 一旦发送 END，就不再补发「请求超时」消息，因此这里无条件清理定时器。
-                        clearTimeout(firstReplyTimeout);
-                        await wsHandle.streamClient.end(msgId, "stop");
-                        log.info(`${logPrefix} [stream] END sent: msgId=${msgId}`);
-
-                        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
                     } else {
                         // 没 @ 我，仅作为旁观者缓存记忆，不打扰群里聊天
                         log.debug?.(`${logPrefix} Not mentioned in group, quietly memorized the message context.`);

package/src/connection.ts

@@ -44,6 +44,9 @@ export interface ImStreamClient {
 /** 心跳间隔（ms）：每 20 秒发一次 ping，防止连接被后台剔除 */
 const PING_INTERVAL_MS = 20_000;
 
+/** 心跳日志间隔（ms）：每 10 分钟输出一次 info 日志，避免刷屏 */
+const PING_LOG_INTERVAL_MS = 600_000;
+
 /** 计算指数退避延迟（带随机抖动） */
 function calcDelay(
     attempt: number,
@@ -107,9 +110,10 @@ export function startWebSocket(
         }
     }
 
-    /** 启动心跳：每 30s 发一次 ping */
+    /** 启动心跳：每 20s 发一次 ping，info 日志每 10 分钟输出一次 */
     function startHeartbeat(socket: WebSocket): void {
         clearHeartbeat();
+        let lastLogTime = 0;
 
         pingTimer = setInterval(() => {
             if (socket.readyState !== WebSocket.OPEN) {
@@ -117,8 +121,12 @@ export function startWebSocket(
                 return;
             }
 
-            const now = new Date().toISOString();
-            log.info(`${logPrefix} ♥ Ping sent at ${now}`);
+            const now = Date.now();
+            const shouldLog = now - lastLogTime >= PING_LOG_INTERVAL_MS;
+            if (shouldLog) {
+                lastLogTime = now;
+                log.info(`${logPrefix} ♥ Ping sent at ${new Date().toISOString()}`);
+            }
 
             // 发送标准 WebSocket ping 帧
             socket.ping((err: Error | null) => {

package/src/group-history-tool.ts

@@ -8,7 +8,7 @@
 import axios from "axios";
 import { Type, type Static } from "@sinclair/typebox";
 import type { AnyAgentTool } from "openclaw/plugin-sdk";
-import { jsonResult } from "openclaw/plugin-sdk";
+import { toolJsonResult } from "./tool-json-result.js";
 import { getToken } from "./auth.js";
 import type { BotIdentity, WsMessageParams, XgImConfig } from "./types.js";
 
@@ -143,7 +143,7 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                 identity = await getToken(accountConfig);
                 console.log(`[cwork_im][tool] token acquired for userId=${identity.userId}`);
             } catch (err: unknown) {
-                return jsonResult({
+                return toolJsonResult({
                     ok: false,
                     error: `Failed to obtain access token: ${String(err)}`,
                     messages: [],
@@ -158,7 +158,7 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                     `[cwork_im][tool] fetched ${messages.length} messages from group ${groupId} using accountId=${accountId ?? "0"} userId=${userId ?? "N/A"}`,
                 );
             } catch (err: unknown) {
-                return jsonResult({
+                return toolJsonResult({
                     ok: false,
                     error: `Failed to fetch group history: ${String(err)}`,
                     messages: [],
@@ -167,7 +167,10 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
 
             // 格式化成对话摘要，方便 AI 理解
             const formatted = messages
-                .filter((m) => m.msgContent?.type === "text")
+                .filter((m) => {
+                    const t = m.msgContent?.type;
+                    return t === "text" || t === "file";
+                })
                 .map((m) => {
                     const senderId = m.userInfo?.id ?? "";
                     const senderName = m.userInfo?.name || senderId || "未知用户";
@@ -175,10 +178,22 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                     const sender = isBot ? "[AI]" : senderName;
                     const ts = m.timestamp ?? m.msgSendTime ?? 0;
                     const time = new Date(ts).toLocaleTimeString("zh-CN", { hour12: false });
-                    return `[${time}] ${sender}: ${m.msgContent.text}`;
+                    const c = m.msgContent;
+                    const body =
+                        c?.type === "file" && c.files?.length
+                            ? [
+                                c.text?.trim(),
+                                `[附件 ${c.files.length} 个: ${c.files
+                                    .map((f) => f.name?.trim() || f.fileId || "文件")
+                                    .join("、")}]`,
+                            ]
+                                .filter(Boolean)
+                                .join(" ")
+                            : (c?.text ?? "");
+                    return `[${time}] ${sender}: ${body}`;
                 });
 
-            return jsonResult({
+            return toolJsonResult({
                 ok: true,
                 groupId,
                 count: formatted.length,