openclaw-channel-dmwork 0.5.9 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-channel-dmwork",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "DMWork channel plugin for OpenClaw via WuKongIM WebSocket",
   "main": "index.ts",
   "type": "module",

package/src/actions.ts

@@ -16,7 +16,8 @@ import {
   updateGroupMd,
 } from "./api-fetch.js";
 import { uploadAndSendMedia } from "./inbound.js";
-import { parseMentions } from "./mention-utils.js";
+import { buildEntitiesFromFallback } from "./mention-utils.js";
+import type { MentionEntity } from "./types.js";
 import { getKnownGroupIds } from "./group-md.js";
 
 export interface MessageActionResult {
@@ -164,15 +165,12 @@ async function handleSend(params: {
   // Send text message
   if (message) {
     let mentionUids: string[] = [];
+    let mentionEntities: MentionEntity[] = [];
 
     if (channelType === ChannelType.Group && memberMap) {
-      const mentionNames = parseMentions(message);
-      for (const name of mentionNames) {
-        const uid = memberMap.get(name);
-        if (uid && !mentionUids.includes(uid)) {
-          mentionUids.push(uid);
-        }
-      }
+      const { entities, uids } = buildEntitiesFromFallback(message, memberMap);
+      mentionUids = uids;
+      mentionEntities = entities;
     }
 
     await sendMessage({
@@ -182,6 +180,7 @@ async function handleSend(params: {
       channelType,
       content: message,
       ...(mentionUids.length > 0 ? { mentionUids } : {}),
+      ...(mentionEntities.length > 0 ? { mentionEntities } : {}),
     });
   }
 

package/src/api-fetch.test.ts

@@ -716,3 +716,81 @@ describe("sendMediaMessage", () => {
     expect(payload.height).toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// ensureTextCharset
+// ---------------------------------------------------------------------------
+describe("ensureTextCharset", () => {
+  it("appends charset=utf-8 to text/plain", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("text/plain")).toBe("text/plain; charset=utf-8");
+  });
+
+  it("appends charset=utf-8 to text/markdown", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("text/markdown")).toBe("text/markdown; charset=utf-8");
+  });
+
+  it("appends charset=utf-8 to text/html", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("text/html")).toBe("text/html; charset=utf-8");
+  });
+
+  it("does not modify image/jpeg", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("image/jpeg")).toBe("image/jpeg");
+  });
+
+  it("does not double-add charset if already present", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("text/plain; charset=utf-8")).toBe("text/plain; charset=utf-8");
+  });
+
+  it("does not override existing charset=gbk", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("text/plain; charset=gbk")).toBe("text/plain; charset=gbk");
+  });
+
+  it("does not modify application/json", async () => {
+    const { ensureTextCharset } = await import("./api-fetch.js");
+    expect(ensureTextCharset("application/json")).toBe("application/json");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// uploadFileToCOS — putParams includes ContentType
+// ---------------------------------------------------------------------------
+describe("uploadFileToCOS putParams ContentType", () => {
+  it("passes ContentType to cos.putObject", async () => {
+    let capturedParams: any = null;
+
+    vi.resetModules();
+
+    // Mock cos-nodejs-sdk-v5 before importing api-fetch
+    vi.doMock("cos-nodejs-sdk-v5", () => {
+      return {
+        default: class FakeCOS {
+          putObject(params: any, cb: any) {
+            capturedParams = params;
+            cb(null, { Location: "bucket.cos.region.myqcloud.com/key" });
+          }
+        },
+      };
+    });
+
+    const { uploadFileToCOS } = await import("./api-fetch.js");
+    await uploadFileToCOS({
+      credentials: { tmpSecretId: "id", tmpSecretKey: "key", sessionToken: "tok" },
+      startTime: 0,
+      expiredTime: 9999999999,
+      bucket: "test-bucket",
+      region: "ap-test",
+      key: "test/file.txt",
+      fileBody: Buffer.from("hello"),
+      contentType: "text/plain; charset=utf-8",
+    });
+
+    expect(capturedParams).not.toBeNull();
+    expect(capturedParams.ContentType).toBe("text/plain; charset=utf-8");
+  });
+});

package/src/api-fetch.ts

@@ -3,7 +3,7 @@
  * These are used by inbound/outbound where the full DMWorkAPI class is not available.
  */
 
-import { ChannelType, MessageType } from "./types.js";
+import { ChannelType, MessageType, type MentionEntity } from "./types.js";
 import path from "path";
 import { open } from "node:fs/promises";
 // @ts-ignore — cos-nodejs-sdk-v5 has incomplete TypeScript definitions
@@ -63,6 +63,7 @@ export async function sendMediaMessage(params: {
   width?: number;
   height?: number;
   mentionUids?: string[];
+  mentionEntities?: MentionEntity[];
   signal?: AbortSignal;
 }): Promise<void> {
   const payload: Record<string, unknown> = {
@@ -79,8 +80,18 @@ export async function sendMediaMessage(params: {
     if (params.size != null) payload.size = params.size;
   }
 
-  if (params.mentionUids && params.mentionUids.length > 0) {
-    payload.mention = { uids: params.mentionUids };
+  if (
+    (params.mentionUids && params.mentionUids.length > 0) ||
+    (params.mentionEntities && params.mentionEntities.length > 0)
+  ) {
+    const mention: Record<string, unknown> = {};
+    if (params.mentionUids && params.mentionUids.length > 0) {
+      mention.uids = params.mentionUids;
+    }
+    if (params.mentionEntities && params.mentionEntities.length > 0) {
+      mention.entities = params.mentionEntities;
+    }
+    payload.mention = mention;
   }
   await postJson(params.apiUrl, params.botToken, "/v1/bot/sendMessage", {
     channel_id: params.channelId,
@@ -103,11 +114,25 @@ export function inferContentType(filename: string): string {
     ".pdf": "application/pdf", ".zip": "application/zip",
     ".doc": "application/msword", ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
     ".xls": "application/vnd.ms-excel", ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    ".txt": "text/plain", ".json": "application/json",
+    ".txt": "text/plain", ".md": "text/markdown", ".markdown": "text/markdown",
+    ".csv": "text/csv", ".html": "text/html", ".htm": "text/html",
+    ".css": "text/css", ".xml": "text/xml", ".yaml": "text/yaml", ".yml": "text/yaml",
+    ".json": "application/json",
   };
   return map[ext] ?? "application/octet-stream";
 }
 
+/**
+ * Ensure text/* content types include a charset parameter.
+ * If the content type starts with "text/" and has no charset, appends "; charset=utf-8".
+ */
+export function ensureTextCharset(contentType: string): string {
+  if (contentType.startsWith("text/") && !contentType.includes("charset")) {
+    return contentType + "; charset=utf-8";
+  }
+  return contentType;
+}
+
 /**
  * Parse image dimensions from buffer (PNG/JPEG/GIF/WebP).
  * Lightweight — reads only the header bytes, no external dependencies.
@@ -169,6 +194,7 @@ export async function sendMessage(params: {
   channelType: ChannelType;
   content: string;
   mentionUids?: string[];
+  mentionEntities?: MentionEntity[];
   mentionAll?: boolean;
   streamNo?: string;
   replyMsgId?: string;
@@ -178,12 +204,19 @@ export async function sendMessage(params: {
     type: MessageType.Text,
     content: params.content,
   };
-  // Add mention field if any UIDs specified or mentionAll
-  if ((params.mentionUids && params.mentionUids.length > 0) || params.mentionAll) {
+  // Add mention field if any UIDs specified, entities present, or mentionAll
+  if (
+    (params.mentionUids && params.mentionUids.length > 0) ||
+    (params.mentionEntities && params.mentionEntities.length > 0) ||
+    params.mentionAll
+  ) {
     const mention: Record<string, unknown> = {};
     if (params.mentionUids && params.mentionUids.length > 0) {
       mention.uids = params.mentionUids;
     }
+    if (params.mentionEntities && params.mentionEntities.length > 0) {
+      mention.entities = params.mentionEntities;
+    }
     if (params.mentionAll) {
       mention.all = true;
     }
@@ -558,6 +591,7 @@ export async function uploadFileToCOS(params: {
     Region: params.region,
     Key: params.key,
     Body: params.fileBody,
+    ContentType: params.contentType,
   };
   if (params.fileSize != null) {
     putParams.ContentLength = params.fileSize;

package/src/channel.test.ts

@@ -1,5 +1,58 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
+// ─── Token refresh cooldown tests ───────────────────────────────────────────
+// These test the time-based cooldown pattern used in channel.ts onError handler
+// to prevent token refresh storms.
+
+describe("token refresh cooldown logic", () => {
+  it("should allow refresh when cooldown has elapsed", () => {
+    let lastTokenRefreshAt = 0;
+    const TOKEN_REFRESH_COOLDOWN_MS = 60_000;
+
+    const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+    expect(cooldownElapsed).toBe(true);
+  });
+
+  it("should block refresh within cooldown window", () => {
+    const TOKEN_REFRESH_COOLDOWN_MS = 60_000;
+    let lastTokenRefreshAt = Date.now(); // just refreshed
+
+    const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+    expect(cooldownElapsed).toBe(false);
+  });
+
+  it("should allow refresh after cooldown expires", () => {
+    const TOKEN_REFRESH_COOLDOWN_MS = 60_000;
+    // Simulate a refresh that happened 61 seconds ago
+    let lastTokenRefreshAt = Date.now() - 61_000;
+
+    const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+    expect(cooldownElapsed).toBe(true);
+  });
+
+  it("should keep cooldown active even after failed refresh (no reset)", () => {
+    const TOKEN_REFRESH_COOLDOWN_MS = 60_000;
+    let lastTokenRefreshAt = 0;
+
+    // Simulate a refresh attempt (set timestamp before trying)
+    lastTokenRefreshAt = Date.now();
+
+    // Simulate failure — in the old code, hasRefreshedToken was reset to false
+    // In the new code, lastTokenRefreshAt stays set (no reset in catch block)
+    // So subsequent attempts within cooldown should be blocked
+    const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+    expect(cooldownElapsed).toBe(false);
+  });
+
+  it("should apply stagger delay before reconnect", async () => {
+    // Verify the stagger delay pattern works
+    const start = Date.now();
+    const staggerMs = Math.floor(Math.random() * 5000);
+    expect(staggerMs).toBeGreaterThanOrEqual(0);
+    expect(staggerMs).toBeLessThan(5000);
+  });
+});
+
 /**
  * Tests for channel.ts singleton timer behavior.
  * Verifies that cleanup timer doesn't accumulate during hot reloads.

package/src/channel.ts

@@ -11,11 +11,12 @@ import {
   resolveDmworkAccount,
   type ResolvedDmworkAccount,
 } from "./accounts.js";
-import { registerBot, sendMessage, sendHeartbeat, sendMediaMessage, inferContentType, fetchBotGroups, getGroupMd, parseImageDimensions, parseImageDimensionsFromFile, getUploadCredentials, uploadFileToCOS } from "./api-fetch.js";
+import { registerBot, sendMessage, sendHeartbeat, sendMediaMessage, inferContentType, ensureTextCharset, fetchBotGroups, getGroupMd, parseImageDimensions, parseImageDimensionsFromFile, getUploadCredentials, uploadFileToCOS } from "./api-fetch.js";
 import { WKSocket } from "./socket.js";
 import { handleInboundMessage, type DmworkStatusSink } from "./inbound.js";
 import { ChannelType, MessageType, type BotMessage, type MessagePayload } from "./types.js";
-import { parseMentions } from "./mention-utils.js";
+import { buildEntitiesFromFallback } from "./mention-utils.js";
+import type { MentionEntity } from "./types.js";
 import { handleDmworkMessageAction, parseTarget } from "./actions.js";
 import { createDmworkManagementTools } from "./agent-tools.js";
 import { getOrCreateGroupMdCache, registerBotGroupIds, getKnownGroupIds } from "./group-md.js";
@@ -349,18 +350,20 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
 
       const { channelId, channelType } = parseTarget(targetForParse, undefined, getKnownGroupIds());
 
+      let mentionEntities: MentionEntity[] = [];
+
       if (channelType === ChannelType.Group) {
-        // Parse @mentions from message content (e.g., "@chenpipi_bot", "@陈皮皮")
-        const contentMentionNames = parseMentions(content);
-        for (const name of contentMentionNames) {
-          if (name && !mentionUids.includes(name)) {
-            mentionUids.push(name);
-            console.log(`[dmwork] parsed @mention from content: ${name}`);
+        // Resolve @name to uid via memberMap (fixes name-as-uid bug)
+        const accountMemberMap = getOrCreateMemberMap(
+          ctx.accountId ?? DEFAULT_ACCOUNT_ID,
+        );
+        const { entities, uids } = buildEntitiesFromFallback(content, accountMemberMap);
+        for (const uid of uids) {
+          if (!mentionUids.includes(uid)) {
+            mentionUids.push(uid);
           }
         }
-        if (mentionUids.length > 0) {
-          console.log(`[dmwork] sending message with mentionUids: ${mentionUids.join(", ")}`);
-        }
+        mentionEntities = entities;
       }
 
       await sendMessage({
@@ -370,6 +373,7 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
         channelType,
         content,
         ...(mentionUids.length > 0 ? { mentionUids } : {}),
+        ...(mentionEntities.length > 0 ? { mentionEntities } : {}),
       });
 
       return { channel: "dmwork", to: ctx.to, messageId: "" };
@@ -441,7 +445,7 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
         tempPath = dl.tempPath;
         localFilePath = dl.tempPath;
         contentType = dl.contentType;
-        if (!contentType) contentType = inferContentType(filename);
+        if (!contentType || contentType === "application/octet-stream") contentType = inferContentType(filename);
         const st = statSync(tempPath);
         fileBody = createReadStream(tempPath);
         fileSize = st.size;
@@ -465,7 +469,7 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
           key: creds.key,
           fileBody,
           fileSize,
-          contentType,
+          contentType: ensureTextCharset(contentType),
           cdnBaseUrl: creds.cdnBaseUrl,
         });
 
@@ -661,8 +665,9 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
       // 4d. Group cache timestamps — track when each group's members were last fetched
       const groupCacheTimestamps = getOrCreateGroupCacheTimestamps(account.accountId);
 
-      // 5. Token refresh state — detect stale cached token
-      let hasRefreshedToken = false;
+      // 5. Token refresh state — time-based cooldown to prevent refresh storms
+      let lastTokenRefreshAt = 0;
+      const TOKEN_REFRESH_COOLDOWN_MS = 60_000; // 60 seconds
       let isRefreshingToken = false; // Guard against concurrent refreshes (#43)
 
       // 5b. Heartbeat failure tracking — reconnect after consecutive failures (#42)
@@ -738,9 +743,6 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
           log?.info?.(`dmwork: WebSocket connected to ${wsUrl}`);
           statusSink({ lastError: null });
           startHeartbeat();
-          // WS connected successfully = WuKongIM accepted the token
-          // Reset refresh flag so we can refresh again if kicked later (#92)
-          hasRefreshedToken = false;
         },
 
         onDisconnected: () => {
@@ -752,12 +754,14 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
           log?.error?.(`dmwork: WebSocket error: ${err.message}`);
           statusSink({ lastError: err.message });
 
-          // If kicked or connect failed, try refreshing the IM token once
+          // If kicked or connect failed, try refreshing the IM token with a cooldown
+          // to prevent refresh storms (e.g. 9000+ refreshes across 11 bots).
           // Use isRefreshingToken to prevent concurrent refresh attempts (#43)
-          if (!hasRefreshedToken && !isRefreshingToken && !stopped &&
+          const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+          if (cooldownElapsed && !isRefreshingToken && !stopped &&
               (err.message.includes("Kicked") || err.message.includes("Connect failed"))) {
             isRefreshingToken = true;
-            hasRefreshedToken = true;
+            lastTokenRefreshAt = Date.now();
             log?.warn?.("dmwork: connection rejected — refreshing IM token...");
             try {
               const fresh = await registerBot({
@@ -769,10 +773,16 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
               log?.info?.("dmwork: got fresh IM token, reconnecting WS...");
               socket.disconnect();
               socket.updateCredentials(fresh.robot_id, fresh.im_token);
+              // Stagger reconnect to avoid thundering herd when multiple bots
+              // refresh tokens simultaneously after server-wide token expiry
+              const staggerMs = Math.floor(Math.random() * 5000);
+              log?.info?.(`dmwork: staggering reconnect by ${staggerMs}ms`);
+              await new Promise(r => setTimeout(r, staggerMs));
+              if (stopped) return; // account was stopped during stagger delay
               socket.connect();
             } catch (refreshErr) {
               log?.error?.(`dmwork: token refresh failed: ${String(refreshErr)}`);
-              hasRefreshedToken = false; // Allow retry on next error (#43)
+              // Keep cooldown active even on failure to prevent rapid retry hammering
             } finally {
               isRefreshingToken = false;
             }

package/src/inbound.test.ts

@@ -11,8 +11,10 @@ import {
   downloadToTemp,
   uploadAndSendMedia,
   downloadMediaToLocal,
+  buildMemberListPrefix,
   type ResolveFileResult,
 } from "./inbound.js";
+import { extractMentionUids } from "./mention-utils.js";
 import { existsSync, unlinkSync, readFileSync } from "node:fs";
 
 /**
@@ -786,3 +788,80 @@ describe("downloadMediaToLocal", () => {
     tempFiles.push(result!);
   });
 });
+
+/**
+ * Tests for Bot @ detection with entities support.
+ */
+describe("Bot @ 检测（entities 支持）", () => {
+  it("应从 entities 检测 bot 被 @", () => {
+    const mention: MentionPayload = {
+      entities: [{ uid: "bot_uid", offset: 0, length: 4 }],
+    };
+    const mentionUids = extractMentionUids(mention);
+    expect(mentionUids.includes("bot_uid")).toBe(true);
+  });
+
+  it("entities 无效时应从 uids 检测", () => {
+    const mention: MentionPayload = {
+      entities: [{} as any],
+      uids: ["bot_uid"],
+    };
+    const mentionUids = extractMentionUids(mention);
+    expect(mentionUids.includes("bot_uid")).toBe(true);
+  });
+});
+
+describe("buildMemberListPrefix", () => {
+  it("should return empty string for empty map", () => {
+    const map = new Map<string, string>();
+    expect(buildMemberListPrefix(map)).toBe("");
+  });
+
+  it("should inject full member list when ≤ 10 members", () => {
+    const map = new Map<string, string>([
+      ["uid_alice", "Alice"],
+      ["uid_bob", "Bob"],
+      ["uid_chen", "陈皮皮"],
+    ]);
+    const result = buildMemberListPrefix(map);
+    expect(result).toContain("[Group Members]");
+    expect(result).toContain("Alice (uid_alice)");
+    expect(result).toContain("Bob (uid_bob)");
+    expect(result).toContain("陈皮皮 (uid_chen)");
+    expect(result).toContain("@[uid:displayName]");
+  });
+
+  it("should inject full member list when exactly 10 members", () => {
+    const map = new Map<string, string>();
+    for (let i = 1; i <= 10; i++) {
+      map.set(`uid_${i}`, `User${i}`);
+    }
+    const result = buildMemberListPrefix(map);
+    expect(result).toContain("[Group Members]");
+    expect(result).toContain("User1 (uid_1)");
+    expect(result).toContain("User10 (uid_10)");
+  });
+
+  it("should inject hint message when > 10 members", () => {
+    const map = new Map<string, string>();
+    for (let i = 1; i <= 11; i++) {
+      map.set(`uid_${i}`, `User${i}`);
+    }
+    const result = buildMemberListPrefix(map);
+    expect(result).toContain("[Group Info]");
+    expect(result).toContain("11 members");
+    expect(result).toContain("group management tool");
+    expect(result).not.toContain("[Group Members]");
+    expect(result).not.toContain("User1 (uid_1)");
+  });
+
+  it("should inject hint message for large groups", () => {
+    const map = new Map<string, string>();
+    for (let i = 1; i <= 50; i++) {
+      map.set(`uid_${i}`, `User${i}`);
+    }
+    const result = buildMemberListPrefix(map);
+    expect(result).toContain("[Group Info]");
+    expect(result).toContain("50 members");
+  });
+});