@elizaos/plugin-wechat 2.0.0-alpha.537

package/src/reply-dispatcher.ts

@@ -0,0 +1,75 @@
+import type { ProxyClient } from "./proxy-client";
+
+const DEFAULT_CHUNK_SIZE = 2000;
+
+export interface ReplyDispatcherOptions {
+  client: ProxyClient;
+  chunkSize?: number;
+}
+
+export class ReplyDispatcher {
+  private readonly client: ProxyClient;
+  private readonly chunkSize: number;
+
+  constructor(options: ReplyDispatcherOptions) {
+    this.client = options.client;
+    this.chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+  }
+
+  async sendText(to: string, text: string): Promise<void> {
+    const chunks = this.chunk(text);
+    for (const chunk of chunks) {
+      try {
+        await this.client.sendText(to, chunk);
+      } catch (err) {
+        console.error(`[wechat] Failed to send text to ${to}:`, err);
+        throw err;
+      }
+    }
+  }
+
+  async sendImage(
+    to: string,
+    imagePath: string,
+    caption?: string,
+  ): Promise<void> {
+    try {
+      await this.client.sendImage(to, imagePath, caption);
+    } catch (err) {
+      console.error(`[wechat] Failed to send image to ${to}:`, err);
+      throw err;
+    }
+  }
+
+  private chunk(text: string): string[] {
+    if (text.length <= this.chunkSize) {
+      return [text];
+    }
+
+    const chunks: string[] = [];
+    let remaining = text;
+
+    while (remaining.length > 0) {
+      if (remaining.length <= this.chunkSize) {
+        chunks.push(remaining);
+        break;
+      }
+
+      // Try to break at a newline
+      let breakAt = remaining.lastIndexOf("\n", this.chunkSize);
+      if (breakAt <= 0) {
+        // Try to break at a space
+        breakAt = remaining.lastIndexOf(" ", this.chunkSize);
+      }
+      if (breakAt <= 0) {
+        // Hard break
+        breakAt = this.chunkSize;
+      }
+
+      chunks.push(remaining.slice(0, breakAt));
+      remaining = remaining.slice(breakAt).trimStart();
+    }
+
+    return chunks;
+  }
+}

package/src/runtime-bridge.test.ts

@@ -0,0 +1,135 @@
+import type { Content } from "@elizaos/core";
+import { describe, expect, it, vi } from "vitest";
+import { deliverIncomingWechatMessage } from "./runtime-bridge";
+import type { WechatMessageContext } from "./types";
+
+function createMessage(
+  overrides: Partial<WechatMessageContext> = {},
+): WechatMessageContext {
+  return {
+    id: "wechat-msg-1",
+    type: "text",
+    sender: "wxid-alice",
+    recipient: "wxid-agent",
+    content: "hello agent",
+    timestamp: 123,
+    raw: { type: 60001 },
+    ...overrides,
+  };
+}
+
+function createRuntime(overrides: Record<string, unknown> = {}) {
+  return {
+    agentId: "00000000-0000-0000-0000-000000000001",
+    ensureConnection: vi.fn().mockResolvedValue(undefined),
+    createMemory: vi.fn().mockResolvedValue(undefined),
+    emitEvent: vi.fn().mockResolvedValue(undefined),
+    logger: {
+      warn: vi.fn(),
+      error: vi.fn(),
+    },
+    ...overrides,
+  };
+}
+
+describe("deliverIncomingWechatMessage", () => {
+  it("routes incoming messages through the runtime message API and reply callback", async () => {
+    const sendText = vi.fn().mockResolvedValue(undefined);
+    const sendMessage = vi.fn(
+      async (
+        _runtime: unknown,
+        _memory: unknown,
+        options?: {
+          onResponse?: (content: Content) => Promise<unknown>;
+        },
+      ) => {
+        await options?.onResponse?.({ text: "reply from agent" } as Content);
+        return { responseContent: { text: "reply from agent" } as Content };
+      },
+    );
+    const runtime = createRuntime({
+      elizaOS: { sendMessage },
+    });
+
+    await deliverIncomingWechatMessage({
+      runtime,
+      accountId: "main",
+      message: createMessage(),
+      sendText,
+    });
+
+    expect(runtime.ensureConnection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        entityId: expect.any(String),
+        roomId: expect.any(String),
+        userName: "wxid-alice",
+        userId: "wxid-alice",
+        source: "wechat",
+        channelId: "wxid-alice",
+        worldName: "WeChat",
+      }),
+    );
+    expect(sendMessage).toHaveBeenCalledTimes(1);
+
+    const [, memory] = sendMessage.mock.calls[0];
+    expect(memory).toEqual(
+      expect.objectContaining({
+        content: expect.objectContaining({
+          text: "hello agent",
+          source: "wechat",
+          channelType: "DM",
+        }),
+        metadata: expect.objectContaining({
+          type: "message",
+          source: "wechat",
+          provider: "wechat",
+          fromId: "wxid-alice",
+          wechat: expect.objectContaining({
+            userId: "wxid-alice",
+            messageId: "wechat-msg-1",
+          }),
+        }),
+      }),
+    );
+
+    expect(sendText).toHaveBeenCalledTimes(1);
+    expect(sendText).toHaveBeenCalledWith(
+      "main",
+      "wxid-alice",
+      "reply from agent",
+    );
+    expect(runtime.createMemory).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: expect.objectContaining({
+          text: "reply from agent",
+          source: "wechat",
+          channelType: "DM",
+        }),
+      }),
+      "messages",
+    );
+  });
+
+  it("falls back to MESSAGE_RECEIVED events when no message pipeline is available", async () => {
+    const runtime = createRuntime();
+
+    await deliverIncomingWechatMessage({
+      runtime,
+      accountId: "main",
+      message: createMessage(),
+      sendText: vi.fn().mockResolvedValue(undefined),
+    });
+
+    expect(runtime.emitEvent).toHaveBeenCalledWith(["MESSAGE_RECEIVED"], {
+      runtime,
+      message: expect.objectContaining({
+        content: expect.objectContaining({
+          text: "hello agent",
+          source: "wechat",
+        }),
+      }),
+      callback: expect.any(Function),
+      source: "wechat",
+    });
+  });
+});

package/src/runtime-bridge.ts

@@ -0,0 +1,259 @@
+import { type Content, type Memory, stringToUuid } from "@elizaos/core";
+import type { WechatMessageContext } from "./types";
+
+type ResponseCallback = (content: Content) => Promise<Memory[]>;
+
+type RuntimeLike = {
+  agentId?: string;
+  ensureConnection?: (details: Record<string, unknown>) => Promise<unknown>;
+  elizaOS?: {
+    sendMessage?: (
+      runtime: unknown,
+      message: Memory,
+      options?: { onResponse?: ResponseCallback },
+    ) => Promise<{ responseContent?: Content } | undefined>;
+  };
+  messageService?: {
+    handleMessage?: (
+      runtime: unknown,
+      message: Memory,
+      onResponse: ResponseCallback,
+    ) => Promise<{ responseContent?: Content } | undefined>;
+  };
+  emitEvent?: (events: string[], payload: unknown) => Promise<unknown>;
+  createMemory?: (memory: Memory, tableName: string) => Promise<unknown>;
+  logger?: {
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+};
+
+export interface IncomingWechatDeliveryOptions {
+  runtime: unknown;
+  accountId: string;
+  message: WechatMessageContext;
+  sendText: (accountId: string, to: string, text: string) => Promise<void>;
+}
+
+export async function deliverIncomingWechatMessage(
+  options: IncomingWechatDeliveryOptions,
+): Promise<void> {
+  const runtime = options.runtime as RuntimeLike;
+  const agentId =
+    typeof runtime.agentId === "string" && runtime.agentId.length > 0
+      ? runtime.agentId
+      : stringToUuid("wechat-agent");
+  const incomingMemory = buildIncomingMemory(
+    agentId,
+    options.accountId,
+    options.message,
+  );
+  const replyTarget = resolveReplyTarget(options.message);
+  let replyIndex = 0;
+  let replyDelivered = false;
+
+  const onResponse: ResponseCallback = async (content) => {
+    const replyText = extractReplyText(content);
+    if (!replyText) {
+      return [];
+    }
+
+    replyDelivered = true;
+    await options.sendText(options.accountId, replyTarget, replyText);
+
+    const replyMemory = buildReplyMemory(
+      agentId,
+      options.accountId,
+      options.message,
+      replyText,
+      replyIndex,
+    );
+    replyIndex += 1;
+
+    await runtime.createMemory?.(replyMemory, "messages");
+    return [replyMemory];
+  };
+
+  await runtime.ensureConnection?.({
+    entityId: incomingMemory.entityId,
+    roomId: incomingMemory.roomId,
+    worldId: stringToUuid(`wechat:world:${options.accountId}`),
+    userName: options.message.sender,
+    userId: options.message.sender,
+    name: options.message.sender,
+    source: "wechat",
+    type: getChannelType(options.message),
+    channelId: resolveChannelId(options.message),
+    worldName: "WeChat",
+  });
+
+  if (typeof runtime.elizaOS?.sendMessage === "function") {
+    const result = await runtime.elizaOS.sendMessage(
+      options.runtime,
+      incomingMemory,
+      { onResponse },
+    );
+    await maybeHandleResponseContent(result, replyDelivered, onResponse);
+    return;
+  }
+
+  if (typeof runtime.messageService?.handleMessage === "function") {
+    const result = await runtime.messageService.handleMessage(
+      options.runtime,
+      incomingMemory,
+      onResponse,
+    );
+    await maybeHandleResponseContent(result, replyDelivered, onResponse);
+    return;
+  }
+
+  if (typeof runtime.emitEvent === "function") {
+    await runtime.emitEvent(["MESSAGE_RECEIVED"], {
+      runtime: options.runtime,
+      message: incomingMemory,
+      callback: onResponse,
+      source: "wechat",
+    });
+    return;
+  }
+
+  runtime.logger?.warn?.(
+    "[wechat] No inbound runtime message pipeline is available",
+  );
+}
+
+function buildIncomingMemory(
+  agentId: string,
+  accountId: string,
+  message: WechatMessageContext,
+): Memory {
+  return {
+    id: stringToUuid(`wechat:incoming:${accountId}:${message.id}`),
+    agentId,
+    entityId: stringToUuid(`wechat:entity:${accountId}:${message.sender}`),
+    roomId: stringToUuid(
+      `wechat:room:${accountId}:${resolveChannelId(message)}`,
+    ),
+    createdAt: message.timestamp,
+    content: {
+      text: message.content,
+      source: "wechat",
+      channelType: getChannelType(message),
+      metadata: {
+        accountId,
+        sender: message.sender,
+        recipient: message.recipient,
+        messageType: message.type,
+        threadId: message.threadId,
+        groupSubject: message.group?.subject,
+        imageUrl: message.imageUrl,
+      },
+    },
+    metadata: {
+      type: "message",
+      source: "wechat",
+      provider: "wechat",
+      timestamp: message.timestamp,
+      entityName: message.sender,
+      entityUserName: message.sender,
+      fromId: message.sender,
+      sourceId: stringToUuid(`wechat:entity:${accountId}:${message.sender}`),
+      chatType: getChannelType(message),
+      messageIdFull: message.id,
+      sender: {
+        id: message.sender,
+        name: message.sender,
+        username: message.sender,
+      },
+      wechat: {
+        id: message.sender,
+        userId: message.sender,
+        username: message.sender,
+        userName: message.sender,
+        name: message.sender,
+        messageId: message.id,
+        accountId,
+        recipient: message.recipient,
+        threadId: message.threadId,
+        groupSubject: message.group?.subject,
+      },
+    },
+  } as Memory;
+}
+
+function buildReplyMemory(
+  agentId: string,
+  accountId: string,
+  message: WechatMessageContext,
+  text: string,
+  replyIndex: number,
+): Memory {
+  return {
+    id: stringToUuid(`wechat:reply:${accountId}:${message.id}:${replyIndex}`),
+    agentId,
+    entityId: agentId,
+    roomId: stringToUuid(
+      `wechat:room:${accountId}:${resolveChannelId(message)}`,
+    ),
+    createdAt: Date.now(),
+    content: {
+      text,
+      source: "wechat",
+      channelType: getChannelType(message),
+      inReplyTo: message.id,
+      metadata: {
+        accountId,
+        recipient: resolveReplyTarget(message),
+      },
+    },
+    metadata: {
+      type: "message",
+      source: "wechat",
+      provider: "wechat",
+      timestamp: Date.now(),
+      fromBot: true,
+      fromId: agentId,
+      sourceId: agentId,
+      chatType: getChannelType(message),
+      messageIdFull: `wechat:reply:${message.id}:${replyIndex}`,
+      wechat: {
+        accountId,
+        recipient: resolveReplyTarget(message),
+        threadId: message.threadId,
+      },
+    },
+  } as Memory;
+}
+
+function getChannelType(message: WechatMessageContext): "DM" | "GROUP" {
+  return message.group ? "GROUP" : "DM";
+}
+
+function resolveChannelId(message: WechatMessageContext): string {
+  return message.threadId ?? message.sender;
+}
+
+function resolveReplyTarget(message: WechatMessageContext): string {
+  return message.threadId ?? message.sender;
+}
+
+function extractReplyText(content: Content): string | null {
+  if (typeof content.text !== "string") {
+    return null;
+  }
+
+  const trimmed = content.text.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+async function maybeHandleResponseContent(
+  result: { responseContent?: Content } | undefined,
+  replyDelivered: boolean,
+  onResponse: ResponseCallback,
+): Promise<void> {
+  if (replyDelivered || !result?.responseContent) {
+    return;
+  }
+
+  await onResponse(result.responseContent);
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+export type DeviceType = "ipad" | "mac";
+export type LoginStatus = "waiting" | "need_verify" | "logged_in";
+
+export interface WechatAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  apiKey: string;
+  proxyUrl: string;
+  deviceType?: DeviceType;
+  webhookPort?: number;
+  webhookUrl?: string;
+  wcId?: string;
+  nickName?: string;
+}
+
+export interface WechatConfig {
+  enabled?: boolean;
+  apiKey?: string;
+  proxyUrl?: string;
+  webhookPort?: number;
+  deviceType?: DeviceType;
+  loginTimeoutMs?: number;
+  accounts?: Record<string, WechatAccountConfig>;
+  features?: {
+    images?: boolean;
+    groups?: boolean;
+  };
+}
+
+export interface ResolvedWechatAccount {
+  id: string;
+  apiKey: string;
+  proxyUrl: string;
+  deviceType: DeviceType;
+  webhookPort: number;
+  wcId?: string;
+  nickName?: string;
+}
+
+export type WechatMessageType =
+  | "text"
+  | "image"
+  | "video"
+  | "file"
+  | "voice"
+  | "unknown";
+
+export interface WechatMessageContext {
+  id: string;
+  type: WechatMessageType;
+  sender: string;
+  recipient: string;
+  content: string;
+  timestamp: number;
+  threadId?: string;
+  group?: {
+    subject: string;
+  };
+  imageUrl?: string;
+  raw: unknown;
+}
+
+export interface AccountStatus {
+  valid: boolean;
+  wcId?: string;
+  loginState: LoginStatus;
+  nickName?: string;
+  tier?: string;
+  quota?: number;
+}
+
+export interface ProxyApiResponse<T> {
+  code: number;
+  message?: string;
+  data?: T;
+}

package/src/utils/qrcode.ts

@@ -0,0 +1,16 @@
+/**
+ * Display a QR code URL to the terminal.
+ * Prints the URL for the user to open in a browser.
+ * A vendored text-based QR renderer could be added here later.
+ */
+export function displayQRUrl(url: string): void {
+  console.log("");
+  console.log("╔══════════════════════════════════════════╗");
+  console.log("║  Scan this QR code with WeChat to login  ║");
+  console.log("╠══════════════════════════════════════════╣");
+  console.log(`║  ${url}`);
+  console.log("╚══════════════════════════════════════════╝");
+  console.log("");
+  console.log("Open the URL above in your browser to see the QR code.");
+  console.log("");
+}