@yanhaidao/wecom 2.0.2 → 2.2.4

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.ts

@@ -1,5 +1,11 @@
 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");
@@ -22,6 +28,12 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
   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]!;
@@ -44,6 +56,11 @@ 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;
@@ -56,6 +73,11 @@ export function computeWecomMsgSignature(params: {
   return sha1Hex(parts.join(""));
 }
 
+/**
+ * **verifyWecomSignature (验证消息签名)**
+ * 
+ * 比较计算出的签名与企业微信传入的签名是否一致。
+ */
 export function verifyWecomSignature(params: {
   token: string;
   timestamp: string;
@@ -72,6 +94,17 @@ export function verifyWecomSignature(params: {
   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;
@@ -111,6 +144,16 @@ export function decryptWecomEncrypted(params: {
   return msg;
 }
 
+/**
+ * **encryptWecomPlaintext (加密回复消息)**
+ * 
+ * 将明文消息打包为企业微信的加密格式。
+ * 流程：
+ * 1. 构造协议包: [16字节随机串][4字节长度][消息体][接收者ID]。
+ * 2. PKCS#7 填充。
+ * 3. AES-CBC 加密。
+ * 4. 转 Base64。
+ */
 export function encryptWecomPlaintext(params: {
   encodingAESKey: string;
   receiveId?: string;

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

@@ -1,10 +1,17 @@
 import { describe, it, expect, vi } from "vitest";
 import { decryptWecomMedia } from "./media.js";
 import { WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
-import axios from "axios";
 import crypto from "node:crypto";
 
-vi.mock("axios");
+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;
@@ -28,19 +35,18 @@ describe("decryptWecomMedia", () => {
         cipher.setAutoPadding(false);
         const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
 
-        // 3. Mock Axios
-        (axios.get as any).mockResolvedValue({
-            data: encrypted,
-        });
+        // 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(axios.get).toHaveBeenCalledWith("http://mock.url/image", expect.objectContaining({
-            responseType: "arraybuffer"
-        }));
+        expect(undiciFetch).toHaveBeenCalledWith(
+            "http://mock.url/image",
+            expect.objectContaining({ signal: expect.anything() }),
+        );
     });
 
     it("should fail if key is invalid", async () => {

package/src/media.ts

@@ -1,23 +1,39 @@
 import crypto from "node:crypto";
-import axios from "axios";
 import { decodeEncodingAESKey, pkcs7Unpad, WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
+import { readResponseBodyAsBuffer, wecomFetch, type WecomHttpOptions } from "./http.js";
 
 /**
- * Download and decrypt WeCom media file (e.g. image).
+ * **decryptWecomMedia (解密企业微信媒体文件)**
  * 
- * WeCom media files are AES-256-CBC encrypted with the same EncodingAESKey.
- * The IV is the first 16 bytes of the AES Key.
- * The content is PKCS#7 padded.
+ * 简易封装：直接传入 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 response = await axios.get(url, {
-        responseType: "arraybuffer", // Important: get raw buffer
-        timeout: 15000,
-        maxContentLength: maxBytes || undefined, // Limit download size
-        maxBodyLength: maxBytes || undefined,
-    });
-    const encryptedData = Buffer.from(response.data);
+    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);

package/src/monitor/state.ts

@@ -0,0 +1,354 @@
+import crypto from "node:crypto";
+import type { StreamState, PendingInbound, ActiveReplyState, WecomWebhookTarget } from "./types.js";
+import type { WecomInboundMessage } from "../types.js";
+
+// Constants
+export const LIMITS = {
+    STREAM_TTL_MS: 10 * 60 * 1000,
+    ACTIVE_REPLY_TTL_MS: 60 * 60 * 1000,
+    DEFAULT_DEBOUNCE_MS: 500,
+    STREAM_MAX_BYTES: 20_480,
+    REQUEST_TIMEOUT_MS: 15_000
+};
+
+/**
+ * **StreamStore (流状态会话存储)**
+ * 
+ * 管理企业微信回调的流式会话状态、消息去重和防抖聚合逻辑。
+ * 负责维护 msgid 到 streamId 的映射，以及临时缓存待处理的 Pending 消息。
+ */
+export class StreamStore {
+    private streams = new Map<string, StreamState>();
+    private msgidToStreamId = new Map<string, string>();
+    private pendingInbounds = new Map<string, PendingInbound>();
+    private onFlush?: (pending: PendingInbound) => void;
+
+    /**
+     * **setFlushHandler (设置防抖刷新回调)**
+     * 
+     * 当防抖计时器结束时调用的处理函数。通常用于触发 Agent 进行消息处理。
+     * @param handler 回调函数，接收聚合后的 PendingInbound 对象
+     */
+    public setFlushHandler(handler: (pending: PendingInbound) => void) {
+        this.onFlush = handler;
+    }
+
+    /**
+     * **createStream (创建流会话)**
+     * 
+     * 初始化一个新的流式会话状态。
+     * @param params.msgid (可选) 企业微信消息 ID，用于后续去重映射
+     * @returns 生成的 streamId (Hex 字符串)
+     */
+    createStream(params: { msgid?: string }): string {
+        const streamId = crypto.randomBytes(16).toString("hex");
+
+        if (params.msgid) {
+            this.msgidToStreamId.set(String(params.msgid), streamId);
+        }
+
+        this.streams.set(streamId, {
+            streamId,
+            msgid: params.msgid,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+            started: false,
+            finished: false,
+            content: ""
+        });
+
+        return streamId;
+    }
+
+    /**
+     * **getStream (获取流状态)**
+     * 
+     * 根据 streamId 获取当前的会话状态。
+     * @param streamId 流会话 ID
+     */
+    getStream(streamId: string): StreamState | undefined {
+        return this.streams.get(streamId);
+    }
+
+    /**
+     * **getStreamByMsgId (通过 msgid 查找流 ID)**
+     * 
+     * 用于消息去重：检查该 msgid 是否已经关联由正在进行或已完成的流会话。
+     * @param msgid 企业微信消息 ID
+     */
+    getStreamByMsgId(msgid: string): string | undefined {
+        return this.msgidToStreamId.get(String(msgid));
+    }
+
+    /**
+     * **updateStream (更新流状态)**
+     * 
+     * 原子更新流状态，并自动刷新 updatedAt 时间戳。
+     * @param streamId 流会话 ID
+     * @param mutator 状态修改函数
+     */
+    updateStream(streamId: string, mutator: (state: StreamState) => void): void {
+        const state = this.streams.get(streamId);
+        if (state) {
+            mutator(state);
+            state.updatedAt = Date.now();
+        }
+    }
+
+    /**
+     * **markStarted (标记流开始)**
+     * 
+     * 标记该流会话已经开始处理（通常在 Agent 启动后调用）。
+     */
+    markStarted(streamId: string): void {
+        this.updateStream(streamId, (s) => { s.started = true; });
+    }
+
+    /**
+     * **markFinished (标记流结束)**
+     * 
+     * 标记该流会话已完成，不再接收内容更新。
+     */
+    markFinished(streamId: string): void {
+        this.updateStream(streamId, (s) => { s.finished = true; });
+    }
+
+    /**
+     * **addPendingMessage (添加待处理消息 / 防抖聚合)**
+     * 
+     * 将收到的消息加入待处理队列。如果相同 pendingKey 已存在，则是防抖聚合；否则创建新条目。
+     * 会自动设置或重置防抖定时器。
+     * 
+     * @param params 消息参数
+     * @returns { streamId, isNew } isNew=true 表示这是新的一组消息，需初始化 ActiveReply
+     */
+    addPendingMessage(params: {
+        pendingKey: string;
+        target: WecomWebhookTarget;
+        msg: WecomInboundMessage;
+        msgContent: string;
+        nonce: string;
+        timestamp: string;
+        debounceMs?: number;
+    }): { streamId: string; isNew: boolean } {
+        const { pendingKey, target, msg, msgContent, nonce, timestamp, debounceMs } = params;
+        const effectiveDebounceMs = debounceMs ?? LIMITS.DEFAULT_DEBOUNCE_MS;
+        const existing = this.pendingInbounds.get(pendingKey);
+
+        if (existing) {
+            existing.contents.push(msgContent);
+            if (msg.msgid) existing.msgids.push(msg.msgid);
+            if (existing.timeout) clearTimeout(existing.timeout);
+
+            // 重置定时器 (Debounce)
+            existing.timeout = setTimeout(() => {
+                this.flushPending(pendingKey);
+            }, effectiveDebounceMs);
+
+            return { streamId: existing.streamId, isNew: false };
+        }
+
+        // 创建新的聚合分组
+        const streamId = this.createStream({ msgid: msg.msgid });
+        const pending: PendingInbound = {
+            streamId,
+            target,
+            msg,
+            contents: [msgContent],
+            msgids: msg.msgid ? [msg.msgid] : [],
+            nonce,
+            timestamp,
+            createdAt: Date.now(),
+            timeout: setTimeout(() => {
+                this.flushPending(pendingKey);
+            }, effectiveDebounceMs)
+        };
+        this.pendingInbounds.set(pendingKey, pending);
+        return { streamId, isNew: true };
+    }
+
+    /**
+     * **flushPending (触发消息处理)**
+     * 
+     * 内部方法：防抖时间结束后，将聚合的消息一次性推送给 flushHandler。
+     */
+    private flushPending(pendingKey: string): void {
+        const pending = this.pendingInbounds.get(pendingKey);
+        if (!pending) return;
+
+        this.pendingInbounds.delete(pendingKey);
+        if (pending.timeout) {
+            clearTimeout(pending.timeout);
+            pending.timeout = null;
+        }
+
+        if (this.onFlush) {
+            this.onFlush(pending);
+        }
+    }
+
+    /**
+     * **prune (清理过期状态)**
+     * 
+     * 清理过期的流会话、msgid 映射以及残留的 Pending 消息。
+     * @param now 当前时间戳 (毫秒)
+     */
+    prune(now: number = Date.now()): void {
+        const streamCutoff = now - LIMITS.STREAM_TTL_MS;
+
+        // 清理过期的流会话
+        for (const [id, state] of this.streams.entries()) {
+            if (state.updatedAt < streamCutoff) {
+                this.streams.delete(id);
+                if (state.msgid) {
+                    // 如果 msgid 映射仍指向该 stream，则一并移除
+                    if (this.msgidToStreamId.get(state.msgid) === id) {
+                        this.msgidToStreamId.delete(state.msgid);
+                    }
+                }
+            }
+        }
+
+        // 清理悬空的 msgid 映射 (Double check)
+        for (const [msgid, id] of this.msgidToStreamId.entries()) {
+            if (!this.streams.has(id)) {
+                this.msgidToStreamId.delete(msgid);
+            }
+        }
+
+        // 清理超时的 Pending 消息 (通常由 timeout 清理，此处作为兜底)
+        for (const [key, pending] of this.pendingInbounds.entries()) {
+            if (now - pending.createdAt > LIMITS.STREAM_TTL_MS) {
+                if (pending.timeout) clearTimeout(pending.timeout);
+                this.pendingInbounds.delete(key);
+            }
+        }
+    }
+}
+
+/**
+ * **ActiveReplyStore (主动回复地址存储)**
+ * 
+ * 管理企业微信回调中的 `response_url` (用于被动回复转主动推送) 和 `proxyUrl`。
+ * 支持 'once' (一次性) 或 'multi' (多次) 使用策略。
+ */
+export class ActiveReplyStore {
+    private activeReplies = new Map<string, ActiveReplyState>();
+
+    /**
+     * @param policy 使用策略: "once" (默认，销毁式) 或 "multi"
+     */
+    constructor(private policy: "once" | "multi" = "once") { }
+
+    /**
+     * **store (存储回复地址)**
+     * 
+     * 关联 streamId 与 response_url。
+     */
+    store(streamId: string, responseUrl?: string, proxyUrl?: string): void {
+        const url = responseUrl?.trim();
+        if (!url) return;
+        this.activeReplies.set(streamId, { response_url: url, proxyUrl, createdAt: Date.now() });
+    }
+
+    /**
+     * **getUrl (获取回复地址)**
+     * 
+     * 获取指定 streamId 关联的 response_url。
+     */
+    getUrl(streamId: string): string | undefined {
+        return this.activeReplies.get(streamId)?.response_url;
+    }
+
+    /**
+     * **use (消耗回复地址)**
+     * 
+     * 使用存储的 response_url 执行操作。
+     * - 如果策略是 "once"，第二次调用会抛错。
+     * - 自动更新使用时间 (usedAt)。
+     * 
+     * @param streamId 流会话 ID
+     * @param fn 执行函数，接收 { responseUrl, proxyUrl }
+     */
+    async use(streamId: string, fn: (params: { responseUrl: string; proxyUrl?: string }) => Promise<void>): Promise<void> {
+        const state = this.activeReplies.get(streamId);
+        if (!state?.response_url) {
+            return; // 无 URL 可用，安全跳过
+        }
+
+        if (this.policy === "once" && state.usedAt) {
+            throw new Error(`response_url already used for stream ${streamId} (Policy: once)`);
+        }
+
+        try {
+            await fn({ responseUrl: state.response_url, proxyUrl: state.proxyUrl });
+            state.usedAt = Date.now();
+        } catch (err: unknown) {
+            state.lastError = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+    }
+
+    /**
+     * **prune (清理过期地址)**
+     * 
+     * 清理超过 TTL 的 active reply 记录。
+     */
+    prune(now: number = Date.now()): void {
+        const cutoff = now - LIMITS.ACTIVE_REPLY_TTL_MS;
+        for (const [id, state] of this.activeReplies.entries()) {
+            if (state.createdAt < cutoff) {
+                this.activeReplies.delete(id);
+            }
+        }
+    }
+}
+
+/**
+ * **MonitorState (全局监控状态容器)**
+ * 
+ * 模块单例，统一管理 StreamStore 和 ActiveReplyStore 实例。
+ * 提供生命周期方法 (startPruning / stopPruning) 以自动清理过期数据。
+ */
+class MonitorState {
+    /** 主要的流状态存储 */
+    public readonly streamStore = new StreamStore();
+    /** 主动回复地址存储 */
+    public readonly activeReplyStore = new ActiveReplyStore("multi");
+
+    private pruneInterval?: NodeJS.Timeout;
+
+    /**
+     * **startPruning (启动自动清理)**
+     * 
+     * 启动定时器，定期清理过期的流和回复地址。应在插件有活跃 Target 时调用。
+     * @param intervalMs 清理间隔 (默认 60s)
+     */
+    public startPruning(intervalMs: number = 60_000): void {
+        if (this.pruneInterval) return;
+        this.pruneInterval = setInterval(() => {
+            const now = Date.now();
+            this.streamStore.prune(now);
+            this.activeReplyStore.prune(now);
+        }, intervalMs);
+    }
+
+    /**
+     * **stopPruning (停止自动清理)**
+     * 
+     * 停止定时器。应在插件无活跃 Target 时调用以释放资源。
+     */
+    public stopPruning(): void {
+        if (this.pruneInterval) {
+            clearInterval(this.pruneInterval);
+            this.pruneInterval = undefined;
+        }
+    }
+}
+
+/**
+ * **monitorState (全局单例)**
+ * 
+ * 导出全局唯一的 MonitorState 实例，供整个应用共享状态。
+ */
+export const monitorState = new MonitorState();