@mocrane/wecom 2026.2.5

package/src/crypto/signature.ts

@@ -0,0 +1,43 @@
+/**
+ * WeCom 签名计算与验证
+ */
+
+import crypto from "node:crypto";
+
+function sha1Hex(input: string): string {
+    return crypto.createHash("sha1").update(input).digest("hex");
+}
+
+/**
+ * 计算 WeCom 消息签名
+ */
+export function computeWecomMsgSignature(params: {
+    token: string;
+    timestamp: string;
+    nonce: string;
+    encrypt: string;
+}): string {
+    const parts = [params.token, params.timestamp, params.nonce, params.encrypt]
+        .map((v) => String(v ?? ""))
+        .sort();
+    return sha1Hex(parts.join(""));
+}
+
+/**
+ * 验证 WeCom 消息签名
+ */
+export function verifyWecomSignature(params: {
+    token: string;
+    timestamp: string;
+    nonce: string;
+    encrypt: string;
+    signature: string;
+}): boolean {
+    const expected = computeWecomMsgSignature({
+        token: params.token,
+        timestamp: params.timestamp,
+        nonce: params.nonce,
+        encrypt: params.encrypt,
+    });
+    return expected === params.signature;
+}

package/src/crypto/xml.ts

@@ -0,0 +1,49 @@
+/**
+ * WeCom XML 加解密辅助函数
+ * 用于 Agent 模式处理 XML 格式回调
+ */
+
+/**
+ * 从 XML 密文中提取 Encrypt 字段
+ */
+export function extractEncryptFromXml(xml: string): string {
+    const match = /<Encrypt><!\[CDATA\[(.*?)\]\]><\/Encrypt>/s.exec(xml);
+    if (!match?.[1]) {
+        // 尝试不带 CDATA 的格式
+        const altMatch = /<Encrypt>(.*?)<\/Encrypt>/s.exec(xml);
+        if (!altMatch?.[1]) {
+            throw new Error("Invalid XML: missing Encrypt field");
+        }
+        return altMatch[1];
+    }
+    return match[1];
+}
+
+/**
+ * 从 XML 中提取 ToUserName (CorpID)
+ */
+export function extractToUserNameFromXml(xml: string): string {
+    const match = /<ToUserName><!\[CDATA\[(.*?)\]\]><\/ToUserName>/s.exec(xml);
+    if (!match?.[1]) {
+        const altMatch = /<ToUserName>(.*?)<\/ToUserName>/s.exec(xml);
+        return altMatch?.[1] ?? "";
+    }
+    return match[1];
+}
+
+/**
+ * 构建加密 XML 响应
+ */
+export function buildEncryptedXmlResponse(params: {
+    encrypt: string;
+    signature: string;
+    timestamp: string;
+    nonce: string;
+}): string {
+    return `<xml>
+<Encrypt><![CDATA[${params.encrypt}]]></Encrypt>
+<MsgSignature><![CDATA[${params.signature}]]></MsgSignature>
+<TimeStamp>${params.timestamp}</TimeStamp>
+<Nonce><![CDATA[${params.nonce}]]></Nonce>
+</xml>`;
+}

package/src/crypto.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext } from "./crypto.js";
+
+describe("wecom crypto", () => {
+  it("round-trips plaintext", () => {
+    const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"; // 43 chars base64 (plus '=' padding)
+    const plaintext = JSON.stringify({ hello: "world" });
+    const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext });
+    const decrypted = decryptWecomEncrypted({ encodingAESKey, receiveId: "", encrypt });
+    expect(decrypted).toBe(plaintext);
+  });
+
+  it("pads correctly when raw length is a multiple of 32", () => {
+    const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG";
+    // raw length = 20 + plaintext.length + receiveId.length; choose plaintext length % 32 === 12
+    const plaintext = "x".repeat(12);
+    const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext });
+    const decrypted = decryptWecomEncrypted({ encodingAESKey, receiveId: "", encrypt });
+    expect(decrypted).toBe(plaintext);
+  });
+
+  it("computes sha1 msg signature", () => {
+    const sig = computeWecomMsgSignature({
+      token: "token",
+      timestamp: "123",
+      nonce: "456",
+      encrypt: "ENCRYPT",
+    });
+    expect(sig).toMatch(/^[a-f0-9]{40}$/);
+  });
+});

package/src/crypto.ts

@@ -0,0 +1,176 @@
+import crypto from "node:crypto";
+
+/**
+ * **decodeEncodingAESKey (解码 AES Key)**
+ * 
+ * 将企业微信配置的 Base64 编码的 AES Key 解码为 Buffer。
+ * 包含补全 Padding 和长度校验 (必须32字节)。
+ */
+export function decodeEncodingAESKey(encodingAESKey: string): Buffer {
+  const trimmed = encodingAESKey.trim();
+  if (!trimmed) throw new Error("encodingAESKey missing");
+  const withPadding = trimmed.endsWith("=") ? trimmed : `${trimmed}=`;
+  const key = Buffer.from(withPadding, "base64");
+  if (key.length !== 32) {
+    throw new Error(`invalid encodingAESKey (expected 32 bytes after base64 decode, got ${key.length})`);
+  }
+  return key;
+}
+
+// WeCom uses PKCS#7 padding with a block size of 32 bytes (not AES's 16-byte block).
+// This is compatible with AES-CBC as 32 is a multiple of 16, but it requires manual padding/unpadding.
+export const WECOM_PKCS7_BLOCK_SIZE = 32;
+
+function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
+  const mod = buf.length % blockSize;
+  const pad = mod === 0 ? blockSize : blockSize - mod;
+  const padByte = Buffer.from([pad]);
+  return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
+}
+
+/**
+ * **pkcs7Unpad (去除 PKCS#7 填充)**
+ * 
+ * 移除 AES 解密后的 PKCS#7 填充字节。
+ * 包含填充合法性校验。
+ */
+export function pkcs7Unpad(buf: Buffer, blockSize: number): Buffer {
+  if (buf.length === 0) throw new Error("invalid pkcs7 payload");
+  const pad = buf[buf.length - 1]!;
+  if (pad < 1 || pad > blockSize) {
+    throw new Error("invalid pkcs7 padding");
+  }
+  if (pad > buf.length) {
+    throw new Error("invalid pkcs7 payload");
+  }
+  // Best-effort validation (all padding bytes equal).
+  for (let i = 0; i < pad; i += 1) {
+    if (buf[buf.length - 1 - i] !== pad) {
+      throw new Error("invalid pkcs7 padding");
+    }
+  }
+  return buf.subarray(0, buf.length - pad);
+}
+
+function sha1Hex(input: string): string {
+  return crypto.createHash("sha1").update(input).digest("hex");
+}
+
+/**
+ * **computeWecomMsgSignature (计算消息签名)**
+ * 
+ * 算法：sha1(sort(token, timestamp, nonce, encrypt_msg))
+ */
+export function computeWecomMsgSignature(params: {
+  token: string;
+  timestamp: string;
+  nonce: string;
+  encrypt: string;
+}): string {
+  const parts = [params.token, params.timestamp, params.nonce, params.encrypt]
+    .map((v) => String(v ?? ""))
+    .sort();
+  return sha1Hex(parts.join(""));
+}
+
+/**
+ * **verifyWecomSignature (验证消息签名)**
+ * 
+ * 比较计算出的签名与企业微信传入的签名是否一致。
+ */
+export function verifyWecomSignature(params: {
+  token: string;
+  timestamp: string;
+  nonce: string;
+  encrypt: string;
+  signature: string;
+}): boolean {
+  const expected = computeWecomMsgSignature({
+    token: params.token,
+    timestamp: params.timestamp,
+    nonce: params.nonce,
+    encrypt: params.encrypt,
+  });
+  return expected === params.signature;
+}
+
+/**
+ * **decryptWecomEncrypted (解密企业微信消息)**
+ * 
+ * 将企业微信的 AES 加密包解密为明文。
+ * 流程：
+ * 1. Base64 解码 AESKey 并获取 IV (前16字节)。
+ * 2. AES-CBC 解密。
+ * 3. 去除 PKCS#7 填充。
+ * 4. 拆解协议包结构: [16字节随机串][4字节长度][消息体][接收者ID]。
+ * 5. 校验接收者ID (ReceiveId)。
+ */
+export function decryptWecomEncrypted(params: {
+  encodingAESKey: string;
+  receiveId?: string;
+  encrypt: string;
+}): string {
+  const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+  const iv = aesKey.subarray(0, 16);
+  const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, iv);
+  decipher.setAutoPadding(false);
+  const decryptedPadded = Buffer.concat([
+    decipher.update(Buffer.from(params.encrypt, "base64")),
+    decipher.final(),
+  ]);
+  const decrypted = pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE);
+
+  if (decrypted.length < 20) {
+    throw new Error(`invalid decrypted payload (expected at least 20 bytes, got ${decrypted.length})`);
+  }
+
+  // 16 bytes random + 4 bytes network-order length + msg + receiveId (optional)
+  const msgLen = decrypted.readUInt32BE(16);
+  const msgStart = 20;
+  const msgEnd = msgStart + msgLen;
+  if (msgEnd > decrypted.length) {
+    throw new Error(`invalid decrypted msg length (msgEnd=${msgEnd}, payloadLength=${decrypted.length})`);
+  }
+  const msg = decrypted.subarray(msgStart, msgEnd).toString("utf8");
+
+  const receiveId = params.receiveId ?? "";
+  if (receiveId) {
+    const trailing = decrypted.subarray(msgEnd).toString("utf8");
+    if (trailing !== receiveId) {
+      throw new Error(`receiveId mismatch (expected "${receiveId}", got "${trailing}")`);
+    }
+  }
+
+  return msg;
+}
+
+/**
+ * **encryptWecomPlaintext (加密回复消息)**
+ * 
+ * 将明文消息打包为企业微信的加密格式。
+ * 流程：
+ * 1. 构造协议包: [16字节随机串][4字节长度][消息体][接收者ID]。
+ * 2. PKCS#7 填充。
+ * 3. AES-CBC 加密。
+ * 4. 转 Base64。
+ */
+export function encryptWecomPlaintext(params: {
+  encodingAESKey: string;
+  receiveId?: string;
+  plaintext: string;
+}): string {
+  const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+  const iv = aesKey.subarray(0, 16);
+  const random16 = crypto.randomBytes(16);
+  const msg = Buffer.from(params.plaintext ?? "", "utf8");
+  const msgLen = Buffer.alloc(4);
+  msgLen.writeUInt32BE(msg.length, 0);
+  const receiveId = Buffer.from(params.receiveId ?? "", "utf8");
+
+  const raw = Buffer.concat([random16, msgLen, msg, receiveId]);
+  const padded = pkcs7Pad(raw, WECOM_PKCS7_BLOCK_SIZE);
+  const cipher = crypto.createCipheriv("aes-256-cbc", aesKey, iv);
+  cipher.setAutoPadding(false);
+  const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+  return encrypted.toString("base64");
+}

package/src/http.ts

@@ -0,0 +1,102 @@
+import type { Dispatcher } from "undici";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+
+type ProxyDispatcher = Dispatcher;
+
+const proxyDispatchers = new Map<string, ProxyDispatcher>();
+
+/**
+ * **getProxyDispatcher (获取代理 Dispatcher)**
+ * 
+ * 缓存并复用 ProxyAgent，避免重复创建连接池。
+ */
+function getProxyDispatcher(proxyUrl: string): ProxyDispatcher {
+  const existing = proxyDispatchers.get(proxyUrl);
+  if (existing) return existing;
+  const created = new ProxyAgent(proxyUrl);
+  proxyDispatchers.set(proxyUrl, created);
+  return created;
+}
+
+function mergeAbortSignal(params: {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): AbortSignal | undefined {
+  const signals: AbortSignal[] = [];
+  if (params.signal) signals.push(params.signal);
+  if (params.timeoutMs && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0) {
+    signals.push(AbortSignal.timeout(params.timeoutMs));
+  }
+  if (!signals.length) return undefined;
+  if (signals.length === 1) return signals[0];
+  return AbortSignal.any(signals);
+}
+
+/**
+ * **WecomHttpOptions (HTTP 选项)**
+ * 
+ * @property proxyUrl 代理服务器地址
+ * @property timeoutMs 请求超时时间 (毫秒)
+ * @property signal AbortSignal 信号
+ */
+export type WecomHttpOptions = {
+  proxyUrl?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+/**
+ * **wecomFetch (统一 HTTP 请求)**
+ * 
+ * 基于 `undici` 的 fetch 封装，自动处理 ProxyAgent 和 Timeout。
+ * 所有对企业微信 API 的调用都应经过此函数。
+ */
+export async function wecomFetch(input: string | URL, init?: RequestInit, opts?: WecomHttpOptions): Promise<Response> {
+  const proxyUrl = opts?.proxyUrl?.trim() ?? "";
+  const dispatcher = proxyUrl ? getProxyDispatcher(proxyUrl) : undefined;
+
+  const initSignal = init?.signal ?? undefined;
+  const signal = mergeAbortSignal({ signal: opts?.signal ?? initSignal, timeoutMs: opts?.timeoutMs });
+  const nextInit: RequestInit & { dispatcher?: Dispatcher } = {
+    ...(init ?? {}),
+    ...(signal ? { signal } : {}),
+    ...(dispatcher ? { dispatcher } : {}),
+  };
+
+  return undiciFetch(input, nextInit as Parameters<typeof undiciFetch>[1]) as unknown as Promise<Response>;
+}
+
+/**
+ * **readResponseBodyAsBuffer (读取响应 Body)**
+ * 
+ * 将 Response Body 读取为 Buffer，支持最大字节限制以防止内存溢出。
+ * 适用于下载媒体文件等场景。
+ */
+export async function readResponseBodyAsBuffer(res: Response, maxBytes?: number): Promise<Buffer> {
+  if (!res.body) return Buffer.alloc(0);
+
+  const limit = maxBytes && Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : undefined;
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  const reader = res.body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+
+    total += value.byteLength;
+    if (limit && total > limit) {
+      try {
+        await reader.cancel("body too large");
+      } catch {
+        // ignore
+      }
+      throw new Error(`response body too large (>${limit} bytes)`);
+    }
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}
+

package/src/media.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+import { decryptWecomMedia } from "./media.js";
+import { WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
+import crypto from "node:crypto";
+
+const { undiciFetch } = vi.hoisted(() => {
+    const undiciFetch = vi.fn();
+    return { undiciFetch };
+});
+
+vi.mock("undici", () => ({
+    fetch: undiciFetch,
+    ProxyAgent: class ProxyAgent { },
+}));
+
+function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
+    const mod = buf.length % blockSize;
+    const pad = mod === 0 ? blockSize : blockSize - mod;
+    const padByte = Buffer.from([pad]);
+    return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
+}
+
+describe("decryptWecomMedia", () => {
+    it("should download and decrypt media successfully", async () => {
+        // 1. Setup Key and Data
+        const aesKeyBase64 = "jWmYm7qr5nMoCAstdRmNjt3p7vsH8HkK+qiJqQ0aaaa="; // 32 bytes when decoded + padding
+        const aesKey = Buffer.from(aesKeyBase64 + "=", "base64");
+        const iv = aesKey.subarray(0, 16);
+
+        const originalData = Buffer.from("Hello WeCom Image Data", "utf8");
+
+        // 2. Encrypt manually (AES-256-CBC + PKCS7)
+        const padded = pkcs7Pad(originalData, WECOM_PKCS7_BLOCK_SIZE);
+        const cipher = crypto.createCipheriv("aes-256-cbc", aesKey, iv);
+        cipher.setAutoPadding(false);
+        const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+
+        // 3. Mock HTTP fetch
+        undiciFetch.mockResolvedValue(new Response(encrypted));
+
+        // 4. Test
+        const decrypted = await decryptWecomMedia("http://mock.url/image", aesKeyBase64);
+
+        // 5. Assert
+        expect(decrypted.toString("utf8")).toBe("Hello WeCom Image Data");
+        expect(undiciFetch).toHaveBeenCalledWith(
+            "http://mock.url/image",
+            expect.objectContaining({ signal: expect.anything() }),
+        );
+    });
+
+    it("should fail if key is invalid", async () => {
+        await expect(decryptWecomMedia("http://url", "invalid-key")).rejects.toThrow();
+    });
+});

package/src/media.ts

@@ -0,0 +1,55 @@
+import crypto from "node:crypto";
+import { decodeEncodingAESKey, pkcs7Unpad, WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
+import { readResponseBodyAsBuffer, wecomFetch, type WecomHttpOptions } from "./http.js";
+
+/**
+ * **decryptWecomMedia (解密企业微信媒体文件)**
+ * 
+ * 简易封装：直接传入 URL 和 AES Key 下载并解密。
+ * 企业微信媒体文件使用与消息体相同的 AES-256-CBC 加密，IV 为 AES Key 前16字节。
+ * 解密后需移除 PKCS#7 填充。
+ */
+export async function decryptWecomMedia(url: string, encodingAESKey: string, maxBytes?: number): Promise<Buffer> {
+    return decryptWecomMediaWithHttp(url, encodingAESKey, { maxBytes });
+}
+
+/**
+ * **decryptWecomMediaWithHttp (解密企业微信媒体 - 高级)**
+ * 
+ * 支持传递 HTTP 选项（如 Proxy、Timeout）。
+ * 流程：
+ * 1. 下载加密内容。
+ * 2. 准备 AES Key 和 IV。
+ * 3. AES-CBC 解密。
+ * 4. PKCS#7 去除填充。
+ */
+export async function decryptWecomMediaWithHttp(
+    url: string,
+    encodingAESKey: string,
+    params?: { maxBytes?: number; http?: WecomHttpOptions },
+): Promise<Buffer> {
+    // 1. Download encrypted content
+    const res = await wecomFetch(url, undefined, { ...params?.http, timeoutMs: params?.http?.timeoutMs ?? 15_000 });
+    if (!res.ok) {
+        throw new Error(`failed to download media: ${res.status}`);
+    }
+    const encryptedData = await readResponseBodyAsBuffer(res, params?.maxBytes);
+
+    // 2. Prepare Key and IV
+    const aesKey = decodeEncodingAESKey(encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+
+    // 3. Decrypt
+    const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, iv);
+    decipher.setAutoPadding(false); // We handle padding manually
+    const decryptedPadded = Buffer.concat([
+        decipher.update(encryptedData),
+        decipher.final(),
+    ]);
+
+    // 4. Unpad
+    // Note: Unlike msg bodies, usually removing PKCS#7 padding is enough for media files.
+    // The Python SDK logic: pad_len = decrypted_data[-1]; decrypted_data = decrypted_data[:-pad_len]
+    // Our pkcs7Unpad function does exactly this + validation.
+    return pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE);
+}

package/src/monitor/state.queue.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, test, vi } from "vitest";
+
+import type { WecomInboundMessage } from "../types.js";
+import type { WecomWebhookTarget } from "./types.js";
+import { StreamStore } from "./state.js";
+
+describe("wecom StreamStore queue", () => {
+  test("does not merge into active batch; flushes queued batch after active finishes", async () => {
+    vi.useFakeTimers();
+    try {
+      const store = new StreamStore();
+      const flushed: string[] = [];
+      store.setFlushHandler((pending) => flushed.push(pending.streamId));
+
+      const target = {
+        account: {} as any,
+        config: {} as any,
+        runtime: {},
+        core: {} as any,
+        path: "/wecom",
+      } satisfies WecomWebhookTarget;
+
+      const conversationKey = "wecom:default:U:C";
+
+      const msg1 = { msgid: "M1" } satisfies WecomInboundMessage;
+      const msg2 = { msgid: "M2" } satisfies WecomInboundMessage;
+
+      const r1 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: msg1,
+        msgContent: "1",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 10,
+      });
+      const r2 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: msg2,
+        msgContent: "2",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 10,
+      });
+
+      expect(r1.status).toBe("active_new");
+      // 初始批次不接收合并：第二条进入 queued
+      expect(r2.status).toBe("queued_new");
+      expect(r2.streamId).not.toBe(r1.streamId);
+
+      // Follow-ups within queued should merge into queued (status queued_merged).
+      const r3 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: { msgid: "M3" } as any,
+        msgContent: "3",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 10,
+      });
+      expect(r3.status).toBe("queued_merged");
+      expect(r3.streamId).toBe(r2.streamId);
+
+      // Active batch flushes at debounce time.
+      await vi.advanceTimersByTimeAsync(11);
+      expect(flushed).toEqual([r1.streamId]);
+
+      // Queued batch timer also fires, but cannot flush until active finishes.
+      await vi.advanceTimersByTimeAsync(11);
+      expect(flushed).toEqual([r1.streamId]);
+
+      // Once the active stream finishes, queued batch is promoted and flushes immediately.
+      store.onStreamFinished(r1.streamId);
+      expect(flushed).toEqual([r1.streamId, r2.streamId]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  test("merges into active batch when it has not started yet (even after promotion)", async () => {
+    vi.useFakeTimers();
+    try {
+      const store = new StreamStore();
+      const flushed: string[] = [];
+      store.setFlushHandler((pending) => flushed.push(pending.streamId));
+
+      const target = {
+        account: {} as any,
+        config: {} as any,
+        runtime: {},
+        core: {} as any,
+        path: "/wecom",
+      } satisfies WecomWebhookTarget;
+
+      const conversationKey = "wecom:default:U:C2";
+
+      // 1 becomes active and flushes; mark as started to simulate "processing started".
+      const r1 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: { msgid: "M1" } as any,
+        msgContent: "1",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 10,
+      });
+      store.markStarted(r1.streamId);
+      await vi.advanceTimersByTimeAsync(11);
+      expect(flushed).toEqual([r1.streamId]);
+
+      // 2 enters queued with a longer debounce; it should NOT become readyToFlush yet.
+      const r2 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: { msgid: "M2" } as any,
+        msgContent: "2",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 100,
+      });
+      expect(flushed).toEqual([r1.streamId]);
+
+      // Finish 1, promote 2 to active (but do NOT flush immediately since it's not readyToFlush).
+      store.onStreamFinished(r1.streamId);
+      expect(flushed).toEqual([r1.streamId]);
+
+      // Now 2 is active, but (in real monitor) it may still be in debounce before markStarted.
+      // We simulate that by NOT calling markStarted. Follow-up should merge into active (same streamId).
+      const r3 = store.addPendingMessage({
+        conversationKey,
+        target,
+        msg: { msgid: "M3" } as any,
+        msgContent: "3",
+        nonce: "n",
+        timestamp: "t",
+        debounceMs: 10,
+      });
+      expect(r3.streamId).toBe(r2.streamId);
+      expect(r3.status).toBe("active_merged");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  test("clears conversation state when idle so next message becomes active", async () => {
+    const store = new StreamStore();
+    store.setFlushHandler(() => { });
+
+    const target = {
+      account: {} as any,
+      config: {} as any,
+      runtime: {},
+      core: {} as any,
+      path: "/wecom",
+    } satisfies WecomWebhookTarget;
+
+    const conversationKey = "wecom:default:U:idle";
+
+    const r1 = store.addPendingMessage({
+      conversationKey,
+      target,
+      msg: { msgid: "M1" } as any,
+      msgContent: "1",
+      nonce: "n",
+      timestamp: "t",
+      debounceMs: 10,
+    });
+    store.markStarted(r1.streamId);
+    store.markFinished(r1.streamId);
+    store.onStreamFinished(r1.streamId);
+
+    const r2 = store.addPendingMessage({
+      conversationKey,
+      target,
+      msg: { msgid: "M2" } as any,
+      msgContent: "2",
+      nonce: "n",
+      timestamp: "t",
+      debounceMs: 10,
+    });
+    expect(r2.status).toBe("active_new");
+    expect(r2.streamId).not.toBe(r1.streamId);
+  });
+});