@xgjktech/xg_cwork_im 1.11.0 → 1.11.1

package/index.ts

@@ -11,6 +11,8 @@ import { buildGroupHistoryTool, extractXgCworkImConfig } from "./src/group-histo
 import { buildSendGroupMessageTool } from "./src/send-group-message-tool.js";
 import type { XgCworkImPluginModule } from "./src/types.js";
 
+export { XG_IM_RECOMMENDED_CHANNEL_SYSTEM_PROMPT } from "./src/recommended-system-prompt.js";
+
 const plugin: XgCworkImPluginModule = {
     id: "xg_cwork_im",
     name: "XG CWork IM Channel",
@@ -24,6 +26,7 @@ const plugin: XgCworkImPluginModule = {
         if (cworkConfig) {
             // 工具涉及网络请求 / 副作用，按文档要求标记为 optional，由用户在 Agent 的 tools.allow 中显式启用
             api.registerTool(buildGroupHistoryTool(cworkConfig), { optional: true });
+            // 主动推送（Cron/定时等）向 IM 发纯文本；用户经 IM 对话时不用此工具
             api.registerTool(buildSendGroupMessageTool(cworkConfig), { optional: true });
         } else {
             console.warn("[xg_cwork_im] channel config not found, skipping tool registration");

package/package.json

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

package/src/channel.ts

@@ -428,20 +428,43 @@ async function dispatchMentionedReply(args: {
         }
     }, firstReplyTimeoutMs);
 
+    let deliverCallCount = 0;
+    let deliverSkippedCount = 0;
+
     try {
         await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
             ctx: inboundCtx,
             cfg,
             dispatcherOptions: {
                 responsePrefix: "",
+                // Logged when normalizeReplyPayload decides to skip a payload (e.g. heartbeat, silent token, empty).
+                onSkip: (payload: unknown, meta: { kind: string; reason: string }) => {
+                    deliverSkippedCount++;
+                    log.info(
+                        `${logPrefix} [deliver] Payload skipped by normalizer kind=${meta.kind} reason=${meta.reason}`,
+                    );
+                },
+                // Logged when deliver throws and the dispatcher catches it (error would otherwise be silently dropped).
+                onError: (err: unknown, meta: { kind: string }) => {
+                    log.error(
+                        `${logPrefix} [deliver] Dispatcher caught unhandled error kind=${meta.kind}: ${String(err)}`,
+                    );
+                },
                 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 (!textPart && !(hasMedia && !payload.isThinking)) {
+                            log.info(
+                                `${logPrefix} [deliver] Payload has no sendable content, skipping` +
+                                    ` (isThinking=${payload.isThinking ?? false} hasMedia=${hasMedia})`,
+                            );
+                            return;
+                        }
 
+                        deliverCallCount++;
                         if (isFirstReply) {
                             const ttfr = Date.now() - dispatchStart;
                             log.info(
@@ -490,13 +513,22 @@ async function dispatchMentionedReply(args: {
                             `${logPrefix} [send] Additional reply sent via HTTP: groupId=${params.groupId} preview="${preview}"`,
                         );
                     } catch (err: unknown) {
-                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
+                        log.error(`${logPrefix} [deliver] Reply deliver failed: ${String(err)}`);
                         throw err;
                     }
                 },
             },
         });
-        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
+        log.info(
+            `${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}` +
+                ` (delivered=${deliverCallCount} skipped=${deliverSkippedCount})`,
+        );
+        if (!hasFirstReply) {
+            log.warn(
+                `${logPrefix} [dispatch] No reply was sent to user after dispatch completed` +
+                    ` (delivered=${deliverCallCount} skipped=${deliverSkippedCount})`,
+            );
+        }
     } finally {
         clearTimeout(firstReplyTimeout);
         try {

package/src/recommended-system-prompt.ts

@@ -0,0 +1,3 @@
+/** 建议复制到 `channels.xg_cwork_im.systemPrompt`。 */
+export const XG_IM_RECOMMENDED_CHANNEL_SYSTEM_PROMPT =
+    "发文件给用户时，在回复正文里单独写一行 `MEDIA:<路径>`，例如：MEDIA:/workspace/report.pdf。路径支持 /workspace/…、file://…、http(s)://…。OpenClaw 会自动读取该路径并让通道上传，用户可直接在 IM 中下载。不要把路径当作已发送；也不要上传到外部网站。";

package/src/resource-file.ts

@@ -5,6 +5,7 @@
  */
 
 import axios from "axios";
+import { File } from "node:buffer";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -44,14 +45,63 @@ export function formatFromFilename(filename: string): string {
     return "bin";
 }
 
+/** 仅当含 %XX 序列时 decodeURIComponent，避免对已解码的 Unicode 再 decode 抛错 */
+export function safeDecodeUriFilenameSegment(segment: string): string {
+    const s = segment.trim();
+    if (!s) return s;
+    if (!/%[0-9A-Fa-f]{2}/.test(s)) return s;
+    try {
+        return decodeURIComponent(s.replace(/\+/g, " "));
+    } catch {
+        return s;
+    }
+}
+
+/**
+ * 从 HTTP Content-Disposition 解析文件名（优先 RFC 5987 `filename*=` UTF-8，再普通 filename=）。
+ */
+export function parseFilenameFromContentDisposition(header: string | undefined): string | undefined {
+    if (header == null || typeof header !== "string") return undefined;
+    const h = header.trim();
+    if (!h) return undefined;
+
+    const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;\r\n]+)/i.exec(h);
+    if (star?.[1]) {
+        const v = star[1].trim();
+        const decoded = safeDecodeUriFilenameSegment(v);
+        if (decoded) return decoded;
+    }
+
+    const quoted = /filename\s*=\s*"((?:[^"\\]|\\.)*)"/i.exec(h);
+    if (quoted?.[1]) {
+        const inner = quoted[1].replace(/\\(.)/g, "$1").trim();
+        if (inner) return safeDecodeUriFilenameSegment(inner);
+    }
+
+    const unquoted = /filename\s*=\s*([^;\r\n]+)/i.exec(h);
+    if (unquoted?.[1]) {
+        let v = unquoted[1].trim().replace(/^["']|["']$/g, "");
+        if (v.toLowerCase().startsWith("utf-8''")) v = v.slice(7);
+        if (v) return safeDecodeUriFilenameSegment(v);
+    }
+
+    return undefined;
+}
+
 export function displayNameFromUrl(url: string): string {
     try {
         if (url.startsWith("file://")) {
             return path.basename(fileURLToPath(url)) || "file";
         }
         const u = new URL(url);
-        const seg = path.basename(u.pathname) || "attachment";
-        return seg.split("?")[0] || "attachment";
+        const qName = u.searchParams.get("filename") ?? u.searchParams.get("name");
+        if (qName?.trim()) {
+            return safeDecodeUriFilenameSegment(qName.trim()) || "attachment";
+        }
+        const pathname = u.pathname || "/";
+        const last = pathname.split("/").filter(Boolean).pop() ?? "";
+        const base = safeDecodeUriFilenameSegment(last.split("?")[0] || "");
+        return base || "attachment";
     } catch {
         return "attachment";
     }
@@ -124,6 +174,24 @@ async function readLocalFsIntoBuffer(fsPath: string, maxBytes: number, log?: Log
     return { buffer, filename };
 }
 
+/**
+ * 将 OpenClaw 约定的 `/workspace/<rel>` 路径解析为本机绝对路径（跨平台）。
+ *
+ * OpenClaw 在所有平台启动时均会 chdir 到 workspace 目录，因此
+ * `process.cwd()` 即为 workspace 根，/workspace/<rel> 等价于 cwd/<rel>：
+ *   - Windows : C:\Users\..\.openclaw\workspace\<rel>
+ *   - macOS   : ~/.openclaw/workspace/<rel>
+ *   - Linux容器: /workspace/<rel>（cwd=/workspace，path.join 结果不变）
+ *
+ * 返回 null 表示路径不符合 /workspace/ 格式。
+ */
+export function resolveWorkspacePrefixPath(raw: string): string | null {
+    if (!raw.startsWith("/workspace/") && raw !== "/workspace") return null;
+    const rel = raw.startsWith("/workspace/") ? raw.slice("/workspace/".length) : "";
+    const cwd = process.cwd();
+    return rel ? path.join(cwd, rel) : cwd;
+}
+
 export async function downloadMediaBuffer(
     url: string,
     maxBytes: number,
@@ -132,6 +200,18 @@ export async function downloadMediaBuffer(
     const raw = url.trim();
     log?.info(`[cwork_im:media] resolve ref=${summarizeMediaRef(raw)}`);
 
+    // Handle OpenClaw /workspace/ convention: map to actual workspace directory.
+    const workspaceResolved = resolveWorkspacePrefixPath(raw);
+    if (workspaceResolved && workspaceResolved !== raw) {
+        log?.info(`[cwork_im:media] /workspace/ -> ${summarizeMediaRef(workspaceResolved)}`);
+        try {
+            return await readLocalFsIntoBuffer(workspaceResolved, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed /workspace/ ${summarizeMediaRef(workspaceResolved)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
     if (raw.startsWith("file://")) {
         let fsPath: string;
         try {
@@ -161,16 +241,11 @@ export async function downloadMediaBuffer(
             });
             const buffer = Buffer.from(res.data as ArrayBuffer);
             let filename = displayNameFromUrl(raw);
-            const cd = res.headers["content-disposition"];
+            const cdRaw = res.headers["content-disposition"];
+            const cd = Array.isArray(cdRaw) ? cdRaw[0] : cdRaw;
             if (typeof cd === "string") {
-                const m = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(cd);
-                if (m?.[1]) {
-                    try {
-                        filename = decodeURIComponent(m[1].trim());
-                    } catch {
-                        filename = m[1].trim();
-                    }
-                }
+                const fromCd = parseFilenameFromContentDisposition(cd);
+                if (fromCd) filename = fromCd;
             }
             log?.info(`[cwork_im:media] http ok bytes=${buffer.length} name=${filename}`);
             return { buffer, filename };
@@ -212,9 +287,10 @@ export async function uploadWholeResourceFile(args: {
     log?: Log;
 }): Promise<{ fileId: string; size: number }> {
     const { fileUploadUrl, token, buffer, filename, formField, log } = args;
-    const blob = new Blob([new Uint8Array(buffer)]);
     const form = new FormData();
-    form.append(formField, blob, filename);
+    // 使用 File 携带 UTF-8 文件名，避免部分环境下 Blob+第三参在 multipart 里被错误编码导致服务端乱码
+    const file = new File([buffer], filename, { type: "application/octet-stream" });
+    form.append(formField, file);
 
     log?.info(`[cwork_im:upload] POST ${fileUploadUrl} field=${formField} name=${filename} bytes=${buffer.length}`);
 
@@ -239,6 +315,16 @@ export async function uploadWholeResourceFile(args: {
         throw new Error(`upload HTTP ${res.status}: ${rawText.slice(0, 500)}`);
     }
 
+    // Unified IM API response: { data, resultCode: 1, resultMsg: "" } — resultCode=1 means success.
+    if (json && typeof json === "object") {
+        const j = json as Record<string, unknown>;
+        if (j.resultCode !== undefined && j.resultCode !== 1) {
+            const msg = `upload IM API error resultCode=${j.resultCode}${j.resultMsg ? ` resultMsg=${j.resultMsg}` : ""}`;
+            log?.error(`[cwork_im:upload] ${msg} body=${rawText.slice(0, 500)}`);
+            throw new Error(msg);
+        }
+    }
+
     const fileId = extractFileIdFromUploadResponse(json ?? rawText);
     if (!fileId) {
         log?.error(`[cwork_im:upload] missing fileId in body=${rawText.slice(0, 500)}`);

package/src/send-group-message-tool.ts

@@ -1,11 +1,10 @@
 /**
- * XG-IM 发送群消息工具（供 AI 按需调用）
+ * XG-IM「主动推消息」工具（供 OpenClaw 在非对话场景下调用）
  *
- * 适用场景：
- * - Cron 定时任务主动推送通知
- * - AI 分析后需要主动发起提醒（无需用户先 @ 机器人）
+ * 用途：定时任务、Cron、后台任务等需要 **经本 channel 主动把结果推送到 IM 群** 时，发一条纯文本。
+ * **不用于**用户正通过 IM 与助手聊天时的回合内回复——那种情况走正常助手回复流，用不上本工具。
  *
- * 通过 api.registerTool() 注入，工具内部自动获取机器人 token，AI 无需感知鉴权细节。
+ * 通过 api.registerTool() 注入，工具内部自动获取机器人 token。
  */
 
 import { Type, type Static } from "@sinclair/typebox";
@@ -29,7 +28,7 @@ const SendGroupMessageParams = Type.Object({
         }),
     ),
     text: Type.String({
-        description: "要发送的消息内容（纯文本）",
+        description: "要发送的消息内容（仅纯文本，不支持附件/文件）",
     }),
     atUserIds: Type.Optional(
         Type.Array(Type.String(), {
@@ -41,19 +40,18 @@ const SendGroupMessageParams = Type.Object({
 // ─── 工具构建函数 ─────────────────────────────────────────────────────────────
 
 /**
- * 构建发送群消息工具对象。
- * 由 index.ts 在 register() 里调用，config 在注册时捕获进闭包，
- * 工具执行时自动调用 getToken(config) 获取机器人 token。
+ * 构建「主动推送群消息」工具（纯文本）。
+ * 由 index.ts 在 register() 里调用。
  */
 export function buildSendGroupMessageTool(config: XgImConfig): AnyAgentTool {
     return {
         name: "xg_cwork_im_send_group_message",
-        label: "【xg_cwork_im】发送群聊消息",
+        label: "【xg_cwork_im】主动推送群消息（纯文本）",
         description: [
-            "【仅限 xg_cwork_im 通道】向指定 IM 群聊发送一条消息。",
-            "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
-            "消息将以机器人身份发出，可选择 @ 特定用户。",
-            "groupId 为 IM 群组的唯一 ID（不是群名称），通常从当前对话的 group_channel 字段中解析（格式：agent:main:xg_cwork_im:group:<groupId>）。",
+            "【用途】仅用于 OpenClaw **主动推消息**：例如定时任务 / Cron / 后台任务完成后，经 xg_cwork_im 向群里发一条**纯文字**结果或通知。",
+            "【不要用错】用户正在 IM 里和助手**对话**时，**不要**用本工具回话——对话回复由 OpenClaw 正常走 channel，**用不上**本工具。",
+            "【发文件】本工具不能发附件。用户要「发报告/发文件」时，在**对用户的助手回复**里用 **mediaUrl(s)** 指向 workspace 或 file://；**禁止**为发文件上传到 tmpfiles 等外站。",
+            "【参数】groupId 为 IM 群唯一 ID；主动推送时若需告知某人，可填 atUserIds。",
         ].join("\n"),
         parameters: SendGroupMessageParams,
         async execute(_toolCallId: string, params: Static<typeof SendGroupMessageParams>) {

package/src/send-service.ts

@@ -60,6 +60,19 @@ async function postImMessage(
         if (config.debug) {
             log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
         }
+
+        // Detect business-level errors that arrive with HTTP 200.
+        // IM API unified response: { data, resultCode: 1, resultMsg: "" } — resultCode=1 means success.
+        const d = res.data;
+        if (d && typeof d === "object") {
+            const resultCode = (d as Record<string, unknown>).resultCode;
+            const resultMsg = (d as Record<string, unknown>).resultMsg;
+            if (resultCode !== undefined && resultCode !== 1) {
+                throw new Error(
+                    `IM API error resultCode=${resultCode}${resultMsg ? ` resultMsg=${resultMsg}` : ""}`,
+                );
+            }
+        }
     } 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}`);
@@ -141,21 +154,21 @@ export async function sendReplyDeliverBlock(
             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,
-                );
-            }
+            const errNote = `（文件发送失败：${formatDeliverError(err)}）`;
+            const fallbackText = textToSend.length > 0 ? `${textToSend}\n\n${errNote}` : errNote;
+            await postImMessage(
+                config,
+                token,
+                groupId,
+                {
+                    type: "RICH_TEXT",
+                    text: fallbackText,
+                    ...(msgId ? { msgId } : {}),
+                    ...(reply ? { reply } : {}),
+                },
+                atUserIds,
+                log,
+            );
             return;
         }
     }

package/src/types.ts

@@ -289,6 +289,7 @@ export type SendMessageBody =
           toUserId?: string;
           text: string;
           atUserIds?: string[];
+          /** 流式占位消息 ID，用于将回复更新到对应的占位消息上 */
           msgId?: string;
           reply?: SendMessageReply;
       }
@@ -299,6 +300,7 @@ export type SendMessageBody =
           text: string;
           attachments: SendMessageFileAttachment[];
           atUserIds?: string[];
+          /** 流式占位消息 ID，用于将回复更新到对应的占位消息上 */
           msgId?: string;
           reply?: SendMessageReply;
       };