openclaw-channel-dmwork 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# openclaw-channel-dmwork
+
+DMWork channel plugin for [OpenClaw](https://openclaw.ai) — connecting AI agents to DMWork (WuKongIM) instant messaging.
+
+## Features
+
+- WebSocket connection via WuKongIM protocol
+- Private chat: AI responds to all messages
+- Group chat: mention gating (`@bot` required, configurable)
+- History context: unmentioned messages are recorded and prepended when bot is mentioned
+- Multi-bot support: each bot token = one OpenClaw instance
+
+## Install
+
+```bash
+openclaw plugins install openclaw-channel-dmwork
+```
+
+## Configuration
+
+In your `openclaw.json`:
+
+```json
+{
+  "dmwork": {
+    "accounts": [{
+      "apiUrl": "http://localhost:8090",
+      "wsUrl": "ws://localhost:5200",
+      "botToken": "bf_your_bot_token_here",
+      "requireMention": true
+    }]
+  }
+}
+```
+
+## Requirements
+
+- DMWork server with BotFather enabled
+- Bot token from BotFather (`/newbot` command)
+- OpenClaw >= 2026.2.0
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,27 @@
+/**
+ * openclaw-channel-dmwork
+ *
+ * OpenClaw channel plugin for DMWork messaging platform.
+ * Connects via WuKongIM WebSocket for real-time messaging.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { dmworkPlugin } from "./src/channel.js";
+import { setDmworkRuntime } from "./src/runtime.js";
+
+const plugin: {
+  id: string;
+  name: string;
+  description: string;
+  register: (api: OpenClawPluginApi) => void;
+} = {
+  id: "dmwork",
+  name: "DMWork",
+  description: "OpenClaw DMWork channel plugin via WuKongIM WebSocket",
+  register(api) {
+    setDmworkRuntime(api.runtime);
+    api.registerChannel({ plugin: dmworkPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "dmwork",
+  "channels": ["dmwork"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "openclaw-channel-dmwork",
+  "version": "0.1.0",
+  "description": "DMWork (WuKongIM) channel plugin for OpenClaw — AI Agent 时代的 IM",
+  "main": "index.ts",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "openclaw-channel",
+    "dmwork",
+    "wukongim",
+    "im",
+    "bot",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yujiawei/dmwork-adapters.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "ws": "^8.16.0",
+    "wukongimjssdk": "^1.3.4",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "openclaw": "2026.2.12",
+    "typescript": "^5.4.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "dmwork",
+      "label": "DMWork",
+      "selectionLabel": "DMWork (WuKongIM)",
+      "docsLabel": "dmwork",
+      "blurb": "WuKongIM gateway for DMWork — AI Agent 时代的 IM",
+      "order": 90
+    }
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,78 @@
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { DmworkConfig } from "./config-schema.js";
+
+export type DmworkAccountConfig = DmworkConfig & {
+  accounts?: Record<string, DmworkConfig | undefined>;
+};
+
+export type ResolvedDmworkAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  config: {
+    botToken?: string;
+    apiUrl: string;
+    wsUrl?: string;
+    pollIntervalMs: number;
+    heartbeatIntervalMs: number;
+    requireMention?: boolean;
+  };
+};
+
+const DEFAULT_API_URL = "http://localhost:8090";
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+
+export function listDmworkAccountIds(cfg: OpenClawConfig): string[] {
+  const channel = (cfg.channels?.dmwork ?? {}) as DmworkAccountConfig;
+  const accountIds = Object.keys(channel.accounts ?? {});
+  if (accountIds.length > 0) {
+    return accountIds;
+  }
+  return [DEFAULT_ACCOUNT_ID];
+}
+
+export function resolveDefaultDmworkAccountId(_cfg: OpenClawConfig): string {
+  return DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveDmworkAccount(params: {
+  cfg: OpenClawConfig;
+  accountId?: string | null;
+}): ResolvedDmworkAccount {
+  const accountId = params.accountId ?? DEFAULT_ACCOUNT_ID;
+  const channel = (params.cfg.channels?.dmwork ?? {}) as DmworkAccountConfig;
+  const accountConfig = channel.accounts?.[accountId] ?? channel;
+
+  const botToken = accountConfig.botToken ?? channel.botToken;
+  const apiUrl = accountConfig.apiUrl ?? channel.apiUrl ?? DEFAULT_API_URL;
+  const wsUrl = accountConfig.wsUrl ?? channel.wsUrl;
+  const pollIntervalMs =
+    accountConfig.pollIntervalMs ??
+    channel.pollIntervalMs ??
+    DEFAULT_POLL_INTERVAL_MS;
+  const heartbeatIntervalMs =
+    accountConfig.heartbeatIntervalMs ??
+    channel.heartbeatIntervalMs ??
+    DEFAULT_HEARTBEAT_INTERVAL_MS;
+
+  const enabled = accountConfig.enabled ?? channel.enabled ?? true;
+  const configured = Boolean(botToken?.trim());
+
+  return {
+    accountId,
+    name: accountConfig.name ?? channel.name,
+    enabled,
+    configured,
+    config: {
+      botToken,
+      apiUrl,
+      wsUrl,
+      pollIntervalMs,
+      heartbeatIntervalMs,
+      requireMention: accountConfig.requireMention ?? channel.requireMention,
+    },
+  };
+}

package/src/api-fetch.ts

@@ -0,0 +1,106 @@
+/**
+ * Lightweight fetch-based API helpers for use inside OpenClaw plugin context.
+ * These are used by inbound/outbound where the full DMWorkAPI class is not available.
+ */
+
+import { ChannelType, MessageType } from "./types.js";
+
+const DEFAULT_HEADERS = {
+  "Content-Type": "application/json",
+};
+
+async function postJson<T>(
+  apiUrl: string,
+  botToken: string,
+  path: string,
+  payload: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<T> {
+  const url = `${apiUrl.replace(/\/+$/, "")}${path}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      ...DEFAULT_HEADERS,
+      Authorization: `Bearer ${botToken}`,
+    },
+    body: JSON.stringify(payload),
+    signal,
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`DMWork API ${path} failed (${response.status}): ${text || response.statusText}`);
+  }
+
+  const text = await response.text();
+  if (!text) return {} as T;
+  return JSON.parse(text) as T;
+}
+
+export async function sendMessage(params: {
+  apiUrl: string;
+  botToken: string;
+  channelId: string;
+  channelType: ChannelType;
+  content: string;
+  streamNo?: string;
+  signal?: AbortSignal;
+}): Promise<void> {
+  await postJson(params.apiUrl, params.botToken, "/v1/bot/sendMessage", {
+    channel_id: params.channelId,
+    channel_type: params.channelType,
+    ...(params.streamNo ? { stream_no: params.streamNo } : {}),
+    payload: { type: MessageType.Text, content: params.content },
+  }, params.signal);
+}
+
+export async function sendTyping(params: {
+  apiUrl: string;
+  botToken: string;
+  channelId: string;
+  channelType: ChannelType;
+  signal?: AbortSignal;
+}): Promise<void> {
+  await postJson(params.apiUrl, params.botToken, "/v1/bot/typing", {
+    channel_id: params.channelId,
+    channel_type: params.channelType,
+  }, params.signal);
+}
+
+export async function sendReadReceipt(params: {
+  apiUrl: string;
+  botToken: string;
+  channelId: string;
+  channelType: ChannelType;
+  messageIds?: string[];
+  signal?: AbortSignal;
+}): Promise<void> {
+  await postJson(params.apiUrl, params.botToken, "/v1/bot/readReceipt", {
+    channel_id: params.channelId,
+    channel_type: params.channelType,
+    ...(params.messageIds && params.messageIds.length > 0 ? { message_ids: params.messageIds } : {}),
+  }, params.signal);
+}
+
+export async function sendHeartbeat(params: {
+  apiUrl: string;
+  botToken: string;
+  signal?: AbortSignal;
+}): Promise<void> {
+  await postJson(params.apiUrl, params.botToken, "/v1/bot/heartbeat", {}, params.signal);
+}
+
+export async function registerBot(params: {
+  apiUrl: string;
+  botToken: string;
+  signal?: AbortSignal;
+}): Promise<{
+  robot_id: string;
+  im_token: string;
+  ws_url: string;
+  api_url: string;
+  owner_uid: string;
+  owner_channel_id: string;
+}> {
+  return postJson(params.apiUrl, params.botToken, "/v1/bot/register", {}, params.signal);
+}

package/src/api.ts

@@ -0,0 +1,96 @@
+import axios, { type AxiosInstance } from "axios";
+import type {
+  BotRegisterReq,
+  BotRegisterResp,
+  BotSendMessageReq,
+  BotTypingReq,
+  BotReadReceiptReq,
+  BotEventsReq,
+  BotEventsResp,
+  BotStreamStartReq,
+  BotStreamStartResp,
+  BotStreamEndReq,
+  SendMessageResult,
+  DMWorkConfig,
+} from "./types.js";
+
+/**
+ * DMWork Bot REST API client.
+ */
+export class DMWorkAPI {
+  private client: AxiosInstance;
+
+  constructor(
+    private config: DMWorkConfig,
+  ) {
+    this.client = axios.create({
+      baseURL: config.apiUrl,
+      headers: {
+        Authorization: `Bearer ${config.botToken}`,
+        "Content-Type": "application/json",
+      },
+      timeout: 30_000,
+    });
+  }
+
+  /** Register bot and obtain credentials */
+  async register(req?: BotRegisterReq): Promise<BotRegisterResp> {
+    const { data } = await this.client.post<BotRegisterResp>(
+      "/v1/bot/register",
+      req ?? {},
+    );
+    return data;
+  }
+
+  /** Send a message */
+  async sendMessage(req: BotSendMessageReq): Promise<SendMessageResult> {
+    const { data } = await this.client.post<SendMessageResult>(
+      "/v1/bot/sendMessage",
+      req,
+    );
+    return data;
+  }
+
+  /** Send typing indicator */
+  async sendTyping(req: BotTypingReq): Promise<void> {
+    await this.client.post("/v1/bot/typing", req);
+  }
+
+  /** Send read receipt */
+  async sendReadReceipt(req: BotReadReceiptReq): Promise<void> {
+    await this.client.post("/v1/bot/readReceipt", req);
+  }
+
+  /** Poll for new events (REST mode) */
+  async getEvents(req: BotEventsReq): Promise<BotEventsResp> {
+    const { data } = await this.client.post<BotEventsResp>(
+      "/v1/bot/events",
+      req,
+    );
+    return data;
+  }
+
+  /** Acknowledge an event */
+  async ackEvent(eventId: number): Promise<void> {
+    await this.client.post(`/v1/bot/events/${eventId}/ack`);
+  }
+
+  /** Start a streaming message */
+  async streamStart(req: BotStreamStartReq): Promise<BotStreamStartResp> {
+    const { data } = await this.client.post<BotStreamStartResp>(
+      "/v1/bot/stream/start",
+      req,
+    );
+    return data;
+  }
+
+  /** End a streaming message */
+  async streamEnd(req: BotStreamEndReq): Promise<void> {
+    await this.client.post("/v1/bot/stream/end", req);
+  }
+
+  /** Send heartbeat (REST mode keep-alive) */
+  async heartbeat(): Promise<void> {
+    await this.client.post("/v1/bot/heartbeat");
+  }
+}

package/src/channel.ts

@@ -0,0 +1,265 @@
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  type ChannelOutboundContext,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { DmworkConfigSchema } from "./config-schema.js";
+import {
+  listDmworkAccountIds,
+  resolveDefaultDmworkAccountId,
+  resolveDmworkAccount,
+  type ResolvedDmworkAccount,
+} from "./accounts.js";
+import { registerBot, sendMessage, sendHeartbeat } 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 { DEFAULT_GROUP_HISTORY_LIMIT, type HistoryEntry } from "openclaw/plugin-sdk";
+
+const meta = {
+  id: "dmwork",
+  label: "DMWork",
+  selectionLabel: "DMWork (WuKongIM)",
+  docsPath: "/channels/dmwork",
+  docsLabel: "dmwork",
+  blurb: "WuKongIM gateway for DMWork",
+  order: 90,
+};
+
+export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
+  id: "dmwork",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: false,
+    reactions: false,
+    threads: false,
+  },
+  reload: { configPrefixes: ["channels.dmwork"] },
+  configSchema: buildChannelConfigSchema(DmworkConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listDmworkAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveDmworkAccount({ cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultDmworkAccountId(cfg),
+    isEnabled: (account) => account.enabled,
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      apiUrl: account.config.apiUrl,
+      botToken: account.config.botToken ? "[set]" : "[missing]",
+      wsUrl: account.config.wsUrl ?? "[auto-detect]",
+    }),
+  },
+  messaging: {
+    normalizeTarget: (target) => target.trim(),
+    targetResolver: {
+      looksLikeId: (input) => Boolean(input.trim()),
+      hint: "<userId or channelId>",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async (ctx) => {
+      const account = resolveDmworkAccount({
+        cfg: ctx.cfg as OpenClawConfig,
+        accountId: ctx.accountId ?? DEFAULT_ACCOUNT_ID,
+      });
+      if (!account.config.botToken) {
+        throw new Error("DMWork botToken is not configured");
+      }
+      const content = ctx.text?.trim();
+      if (!content) {
+        return { channel: "dmwork", to: ctx.to, messageId: "" };
+      }
+
+      await sendMessage({
+        apiUrl: account.config.apiUrl,
+        botToken: account.config.botToken,
+        channelId: ctx.to,
+        channelType: ChannelType.DM,
+        content,
+      });
+
+      return { channel: "dmwork", to: ctx.to, messageId: "" };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      apiUrl: account.config.apiUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.configured || !account.config.botToken) {
+        throw new Error(
+          `DMWork not configured for account "${account.accountId}" (missing botToken)`,
+        );
+      }
+
+      const log = ctx.log;
+      const statusSink: DmworkStatusSink = (patch) =>
+        ctx.setStatus({ accountId: account.accountId, ...patch });
+
+      log?.info?.(`[${account.accountId}] registering DMWork bot...`);
+
+      // 1. Register bot
+      let credentials: {
+        robot_id: string;
+        im_token: string;
+        ws_url: string;
+        owner_uid: string;
+      };
+      try {
+        credentials = await registerBot({
+          apiUrl: account.config.apiUrl,
+          botToken: account.config.botToken,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log?.error?.(`dmwork: bot registration failed: ${message}`);
+        statusSink({ lastError: message });
+        throw err;
+      }
+
+      log?.info?.(
+        `[${account.accountId}] bot registered as ${credentials.robot_id}`,
+      );
+
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        lastStartAt: Date.now(),
+        lastError: null,
+      });
+
+      // 2. Resolve WebSocket URL
+      const wsUrl = account.config.wsUrl || credentials.ws_url;
+
+      // 3. Start heartbeat timer
+      let heartbeatTimer: NodeJS.Timeout | null = null;
+      let stopped = false;
+
+      const startHeartbeat = () => {
+        // Clear existing heartbeat to prevent duplicates on reconnect
+        if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+        heartbeatTimer = setInterval(() => {
+          if (stopped) return;
+          sendHeartbeat({
+            apiUrl: account.config.apiUrl,
+            botToken: account.config.botToken!,
+          }).catch((err) => {
+            log?.error?.(`dmwork: heartbeat failed: ${String(err)}`);
+          });
+        }, account.config.heartbeatIntervalMs);
+      };
+
+      // 4. Group history map for mention gating context
+      const groupHistories = new Map<string, HistoryEntry[]>();
+
+      // 5. Connect WebSocket
+      const socket = new WKSocket({
+        wsUrl,
+        uid: credentials.robot_id,
+        token: credentials.im_token,
+
+        onMessage: (msg: BotMessage) => {
+          // Skip self messages
+          if (msg.from_uid === credentials.robot_id) return;
+          // Skip non-text for now
+          if (!msg.payload || msg.payload.type !== MessageType.Text) return;
+
+          log?.info?.(
+            `dmwork: recv message from=${msg.from_uid} channel=${msg.channel_id ?? "DM"} type=${msg.channel_type ?? 1}`,
+          );
+
+          handleInboundMessage({
+            account,
+            message: msg,
+            botUid: credentials.robot_id,
+            groupHistories,
+            log,
+            statusSink,
+          }).catch((err) => {
+            log?.error?.(`dmwork: inbound handler failed: ${String(err)}`);
+          });
+        },
+
+        onConnected: () => {
+          log?.info?.(`dmwork: WebSocket connected to ${wsUrl}`);
+          statusSink({ lastError: null });
+          startHeartbeat();
+
+          // No greeting on connect — bot stays silent until user sends a message
+        },
+
+        onDisconnected: () => {
+          log?.warn?.("dmwork: WebSocket disconnected, will reconnect...");
+          statusSink({ lastError: "disconnected" });
+        },
+
+        onError: (err: Error) => {
+          log?.error?.(`dmwork: WebSocket error: ${err.message}`);
+          statusSink({ lastError: err.message });
+        },
+      });
+
+      socket.connect();
+
+      // Handle abort signal
+      const onAbort = () => {
+        stopped = true;
+        socket.disconnect();
+        if (heartbeatTimer) {
+          clearInterval(heartbeatTimer);
+          heartbeatTimer = null;
+        }
+      };
+
+      if (ctx.abortSignal.aborted) {
+        onAbort();
+      } else {
+        ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
+      }
+
+      return {
+        stop: () => {
+          stopped = true;
+          socket.disconnect();
+          if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+          }
+          ctx.abortSignal.removeEventListener("abort", onAbort);
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+        },
+      };
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+const DmworkAccountSchema = z.strictObject({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  botToken: z.string().optional(),
+  apiUrl: z.string().optional(),
+  wsUrl: z.string().optional(),
+  pollIntervalMs: z.number().int().min(500).optional(),
+  heartbeatIntervalMs: z.number().int().min(5000).optional(),
+  requireMention: z.boolean().optional(),
+  botUid: z.string().optional(),
+});
+
+export const DmworkConfigSchema = z.strictObject({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  botToken: z.string().optional(),
+  apiUrl: z.string().optional(),
+  wsUrl: z.string().optional(),
+  pollIntervalMs: z.number().int().min(500).optional(),
+  heartbeatIntervalMs: z.number().int().min(5000).optional(),
+  requireMention: z.boolean().optional(),
+  botUid: z.string().optional(),
+  accounts: z.record(z.string(), DmworkAccountSchema.optional()).optional(),
+});
+
+export type DmworkConfig = z.infer<typeof DmworkConfigSchema>;

package/src/inbound.ts

@@ -0,0 +1,223 @@
+import type { ChannelLogSink, OpenClawConfig } from "openclaw/plugin-sdk";
+import { sendMessage, sendReadReceipt, sendTyping } from "./api-fetch.js";
+import type { ResolvedDmworkAccount } from "./accounts.js";
+import type { BotMessage } from "./types.js";
+import { ChannelType, MessageType } from "./types.js";
+import { getDmworkRuntime } from "./runtime.js";
+import {
+  recordPendingHistoryEntryIfEnabled,
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntriesIfEnabled,
+  DEFAULT_GROUP_HISTORY_LIMIT,
+  type HistoryEntry,
+} from "openclaw/plugin-sdk";
+
+export type DmworkStatusSink = (patch: {
+  lastInboundAt?: number;
+  lastOutboundAt?: number;
+  lastError?: string | null;
+}) => void;
+
+function resolveContent(payload: BotMessage["payload"]): string {
+  if (!payload) return "";
+  if (typeof payload.content === "string") return payload.content;
+  if (typeof payload.url === "string") return payload.url;
+  return "";
+}
+
+export async function handleInboundMessage(params: {
+  account: ResolvedDmworkAccount;
+  message: BotMessage;
+  botUid: string;
+  groupHistories: Map<string, HistoryEntry[]>;
+  log?: ChannelLogSink;
+  statusSink?: DmworkStatusSink;
+}) {
+  const { account, message, botUid, groupHistories, log, statusSink } = params;
+
+  const isGroup =
+    typeof message.channel_id === "string" &&
+    message.channel_id.length > 0 &&
+    message.channel_type === ChannelType.Group;
+
+  const sessionId = isGroup
+    ? message.channel_id!
+    : message.from_uid;
+
+  const rawBody = resolveContent(message.payload);
+  if (!rawBody) {
+    log?.info?.(
+      `dmwork: inbound dropped session=${sessionId} reason=empty-content`,
+    );
+    return;
+  }
+
+  // --- Mention gating for group messages ---
+  // In groups, only respond when the bot is explicitly @mentioned via
+  // payload.mention.uids (structured mention from WuKongIM).
+  // Unmentioned messages are recorded as history context for when the bot
+  // IS mentioned later.
+  const requireMention = account.config.requireMention !== false; // default true
+  let historyPrefix = "";
+
+  if (isGroup && requireMention) {
+    const mentionUids: string[] = message.payload?.mention?.uids ?? [];
+    const mentionAll: boolean = message.payload?.mention?.all === true;
+    const isMentioned = mentionAll || mentionUids.includes(botUid);
+
+    if (!isMentioned) {
+      // Record as pending history for future context
+      recordPendingHistoryEntryIfEnabled({
+        channelId: "dmwork",
+        groupId: sessionId,
+        entry: {
+          sender: message.from_uid,
+          body: historyPrefix + rawBody,
+          timestamp: message.timestamp ? message.timestamp * 1000 : Date.now(),
+        },
+        limit: DEFAULT_GROUP_HISTORY_LIMIT,
+      });
+      log?.info?.(
+        `dmwork: group message not mentioning bot, recorded as history context`,
+      );
+      return;
+    }
+
+    // Bot IS mentioned — prepend history context
+    const enrichedBody = buildPendingHistoryContextFromMap({
+      historyMap: groupHistories,
+      historyKey: sessionId,
+      currentMessage: rawBody,
+      limit: DEFAULT_GROUP_HISTORY_LIMIT,
+    });
+    if (enrichedBody !== rawBody) {
+      historyPrefix = enrichedBody.slice(0, enrichedBody.length - rawBody.length);
+      log?.info?.(`dmwork: prepending history context (${historyPrefix.length} chars)`);
+    }
+    // Clear history after consuming
+    clearHistoryEntriesIfEnabled({
+      historyMap: groupHistories,
+      historyKey: sessionId,
+      limit: DEFAULT_GROUP_HISTORY_LIMIT,
+    });
+  }
+
+  const core = getDmworkRuntime();
+  const config = core.config.loadConfig() as OpenClawConfig;
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: "dmwork",
+    accountId: account.accountId,
+    peer: {
+      kind: isGroup ? "group" : "direct",
+      id: sessionId,
+    },
+  });
+
+  const fromLabel = isGroup
+    ? `group:${message.channel_id}`
+    : `user:${message.from_uid}`;
+
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "DMWork",
+    from: fromLabel,
+    timestamp: message.timestamp ? message.timestamp * 1000 : undefined,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: `dmwork:${message.from_uid}`,
+    To: `dmwork:${sessionId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderId: message.from_uid,
+    MessageSid: String(message.message_id),
+    Timestamp: message.timestamp ? message.timestamp * 1000 : undefined,
+    GroupSubject: isGroup ? message.channel_id : undefined,
+    Provider: "dmwork",
+    Surface: "dmwork",
+    OriginatingChannel: "dmwork",
+    OriginatingTo: `dmwork:${sessionId}`,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      log?.error?.(`dmwork: failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  statusSink?.({ lastInboundAt: Date.now(), lastError: null });
+
+  const replyChannelId = isGroup ? message.channel_id! : message.from_uid;
+  const replyChannelType = isGroup ? ChannelType.Group : ChannelType.DM;
+
+  // 已读回执 + 正在输入 — fire-and-forget，失败不影响主流程
+  log?.info?.(`dmwork: sending readReceipt+typing to channel=${replyChannelId} type=${replyChannelType} apiUrl=${account.config.apiUrl}`);
+  const messageIds = message.message_id ? [message.message_id] : [];
+  sendReadReceipt({ apiUrl: account.config.apiUrl, botToken: account.config.botToken ?? "", channelId: replyChannelId, channelType: replyChannelType, messageIds })
+    .then(() => log?.info?.("dmwork: readReceipt sent OK"))
+    .catch((err) => log?.error?.(`dmwork: readReceipt failed: ${String(err)}`));
+  sendTyping({ apiUrl: account.config.apiUrl, botToken: account.config.botToken ?? "", channelId: replyChannelId, channelType: replyChannelType })
+    .then(() => log?.info?.("dmwork: typing sent OK"))
+    .catch((err) => log?.error?.(`dmwork: typing failed: ${String(err)}`));
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config,
+    dispatcherOptions: {
+      deliver: async (payload: {
+        text?: string;
+        mediaUrls?: string[];
+        mediaUrl?: string;
+        replyToId?: string | null;
+      }) => {
+        const contentParts: string[] = [];
+        if (payload.text) contentParts.push(payload.text);
+        const mediaUrls = [
+          ...(payload.mediaUrls ?? []),
+          ...(payload.mediaUrl ? [payload.mediaUrl] : []),
+        ].filter(Boolean);
+        if (mediaUrls.length > 0) contentParts.push(...mediaUrls);
+        const content = contentParts.join("\n").trim();
+        if (!content) return;
+
+        const replyChannelId = isGroup ? message.channel_id! : message.from_uid;
+        const replyChannelType = isGroup ? ChannelType.Group : ChannelType.DM;
+
+        await sendMessage({
+          apiUrl: account.config.apiUrl,
+          botToken: account.config.botToken ?? "",
+          channelId: replyChannelId,
+          channelType: replyChannelType,
+          content,
+        });
+
+        statusSink?.({ lastOutboundAt: Date.now(), lastError: null });
+      },
+      onError: (err, info) => {
+        log?.error?.(`dmwork ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+  });
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setDmworkRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getDmworkRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("DMWork runtime not initialized");
+  }
+  return runtime;
+}

package/src/socket.ts

@@ -0,0 +1,120 @@
+import { EventEmitter } from "events";
+import WKSDK, { ConnectStatus, type Message } from "wukongimjssdk";
+import type { BotMessage, MessagePayload } from "./types.js";
+
+interface WKSocketOptions {
+  wsUrl: string;
+  uid: string;
+  token: string;
+  onMessage: (msg: BotMessage) => void;
+  onConnected?: () => void;
+  onDisconnected?: () => void;
+  onError?: (err: Error) => void;
+}
+
+/**
+ * WuKongIM WebSocket client for bot connections.
+ * Thin wrapper around wukongimjssdk — the SDK handles binary encoding,
+ * DH key exchange, encryption, heartbeat, reconnect, and RECVACK.
+ *
+ * NOTE: WKSDK.shared() is a singleton. Each WKSocket must fully
+ * disconnect before connecting to avoid connection leaks and msgKey
+ * mismatch errors from concurrent WebSocket sessions.
+ */
+export class WKSocket extends EventEmitter {
+  private statusListener: ((status: ConnectStatus, reasonCode?: number) => void) | null = null;
+  private messageListener: ((message: Message) => void) | null = null;
+  private connected = false;
+
+  constructor(private opts: WKSocketOptions) {
+    super();
+  }
+
+  /** Connect to WuKongIM WebSocket */
+  connect(): void {
+    const im = WKSDK.shared();
+
+    // Ensure clean state — disconnect any prior session first
+    try { im.disconnect(); } catch { /* ignore */ }
+
+    im.config.addr = this.opts.wsUrl;
+    im.config.uid = this.opts.uid;
+    im.config.token = this.opts.token;
+    im.config.deviceFlag = 0; // APP — matches bot registration device flag
+
+    // Remove any stale listeners before adding new ones
+    if (this.statusListener) {
+      im.connectManager.removeConnectStatusListener(this.statusListener);
+    }
+    if (this.messageListener) {
+      im.chatManager.removeMessageListener(this.messageListener);
+    }
+
+    // Listen for connection status changes
+    this.statusListener = (status: ConnectStatus, reasonCode?: number) => {
+      switch (status) {
+        case ConnectStatus.Connected:
+          this.connected = true;
+          this.opts.onConnected?.();
+          break;
+        case ConnectStatus.Disconnect:
+          if (this.connected) {
+            this.connected = false;
+            this.opts.onDisconnected?.();
+          }
+          break;
+        case ConnectStatus.ConnectFail:
+          this.connected = false;
+          this.opts.onError?.(
+            new Error(`Connect failed: reasonCode=${reasonCode ?? "unknown"}`),
+          );
+          break;
+        case ConnectStatus.ConnectKick:
+          this.connected = false;
+          this.opts.onError?.(new Error("Kicked by server"));
+          this.opts.onDisconnected?.();
+          break;
+      }
+    };
+    im.connectManager.addConnectStatusListener(this.statusListener);
+
+    // Listen for incoming messages — SDK auto-decrypts and sends RECVACK
+    this.messageListener = (message: Message) => {
+      const content = message.content;
+      const payload: MessagePayload = {
+        type: content?.contentType ?? 0,
+        content: content?.conversationDigest ?? content?.contentObj?.content,
+        ...content?.contentObj,
+      };
+
+      const msg: BotMessage = {
+        message_id: String(message.messageID),
+        message_seq: message.messageSeq,
+        from_uid: message.fromUID,
+        channel_id: message.channel?.channelID,
+        channel_type: message.channel?.channelType,
+        timestamp: message.timestamp,
+        payload,
+      };
+      this.opts.onMessage(msg);
+    };
+    im.chatManager.addMessageListener(this.messageListener);
+
+    im.connect();
+  }
+
+  /** Gracefully disconnect */
+  disconnect(): void {
+    const im = WKSDK.shared();
+    this.connected = false;
+    if (this.statusListener) {
+      im.connectManager.removeConnectStatusListener(this.statusListener);
+      this.statusListener = null;
+    }
+    if (this.messageListener) {
+      im.chatManager.removeMessageListener(this.messageListener);
+      this.messageListener = null;
+    }
+    try { im.disconnect(); } catch { /* ignore */ }
+  }
+}

package/src/stream.ts

@@ -0,0 +1,96 @@
+import type { DMWorkAPI } from "./api.js";
+import { ChannelType, MessageType } from "./types.js";
+
+/**
+ * Manages streaming message output for AI agents.
+ * Handles stream/start → progressive sendMessage → stream/end lifecycle.
+ */
+export class StreamManager {
+  private activeStreams = new Map<
+    string,
+    { channelId: string; channelType: ChannelType }
+  >();
+
+  constructor(private api: DMWorkAPI) {}
+
+  /**
+   * Start a new stream and return the stream_no.
+   */
+  async startStream(
+    channelId: string,
+    channelType: ChannelType,
+    initialContent = "",
+  ): Promise<string> {
+    const payload = Buffer.from(
+      JSON.stringify({
+        type: MessageType.Text,
+        content: initialContent,
+      }),
+    ).toString("base64");
+
+    const resp = await this.api.streamStart({
+      channel_id: channelId,
+      channel_type: channelType,
+      payload,
+    });
+
+    this.activeStreams.set(resp.stream_no, { channelId, channelType });
+    return resp.stream_no;
+  }
+
+  /**
+   * Send a chunk of streaming content.
+   */
+  async sendChunk(streamNo: string, content: string): Promise<void> {
+    const stream = this.activeStreams.get(streamNo);
+    if (!stream) throw new Error(`Unknown stream: ${streamNo}`);
+
+    await this.api.sendMessage({
+      channel_id: stream.channelId,
+      channel_type: stream.channelType,
+      stream_no: streamNo,
+      payload: {
+        type: MessageType.Text,
+        content,
+      },
+    });
+  }
+
+  /**
+   * End a stream.
+   */
+  async endStream(streamNo: string): Promise<void> {
+    const stream = this.activeStreams.get(streamNo);
+    if (!stream) return;
+
+    await this.api.streamEnd({
+      stream_no: streamNo,
+      channel_id: stream.channelId,
+      channel_type: stream.channelType,
+    });
+
+    this.activeStreams.delete(streamNo);
+  }
+
+  /**
+   * Convenience: stream a full text response with chunking.
+   * Splits by sentences/paragraphs and sends progressively.
+   */
+  async streamText(
+    channelId: string,
+    channelType: ChannelType,
+    textIterator: AsyncIterable<string>,
+  ): Promise<void> {
+    const streamNo = await this.startStream(channelId, channelType);
+
+    let accumulated = "";
+    try {
+      for await (const chunk of textIterator) {
+        accumulated += chunk;
+        await this.sendChunk(streamNo, accumulated);
+      }
+    } finally {
+      await this.endStream(streamNo);
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+/** DMWork Bot API types */
+
+export interface BotRegisterReq {
+  name?: string;
+}
+
+export interface BotRegisterResp {
+  robot_id: string;
+  im_token: string;
+  ws_url: string;
+  api_url: string;
+  owner_uid: string;
+  owner_channel_id: string;
+}
+
+export interface BotSendMessageReq {
+  channel_id: string;
+  channel_type: ChannelType;
+  stream_no?: string;
+  payload: MessagePayload;
+}
+
+export interface BotTypingReq {
+  channel_id: string;
+  channel_type: ChannelType;
+}
+
+export interface BotReadReceiptReq {
+  channel_id: string;
+  channel_type: ChannelType;
+}
+
+export interface BotEventsReq {
+  event_id: number;
+  limit?: number;
+}
+
+export interface BotEventsResp {
+  status: number;
+  results: BotEvent[];
+}
+
+export interface BotEvent {
+  event_id: number;
+  message?: BotMessage;
+}
+
+export interface BotMessage {
+  message_id: string;
+  message_seq: number;
+  from_uid: string;
+  channel_id?: string;
+  channel_type?: ChannelType;
+  timestamp: number;
+  payload: MessagePayload;
+}
+
+export interface MessagePayload {
+  type: MessageType;
+  content?: string;
+  url?: string;
+  [key: string]: unknown;
+}
+
+export interface BotStreamStartReq {
+  channel_id: string;
+  channel_type: ChannelType;
+  payload: string; // base64 encoded
+}
+
+export interface BotStreamStartResp {
+  stream_no: string;
+}
+
+export interface BotStreamEndReq {
+  stream_no: string;
+  channel_id: string;
+  channel_type: ChannelType;
+}
+
+export interface SendMessageResult {
+  message_id: number;
+  message_seq: number;
+}
+
+/** Channel types */
+export enum ChannelType {
+  DM = 1,
+  Group = 2,
+}
+
+/** Message content types */
+export enum MessageType {
+  Text = 1,
+  Image = 2,
+  GIF = 3,
+  Voice = 4,
+  Video = 5,
+  Location = 6,
+  Card = 7,
+  File = 8,
+}
+
+/** Plugin config */
+export interface DMWorkConfig {
+  botToken: string;
+  apiUrl: string;
+  wsUrl?: string;
+}
+