@dingxiang-me/openclaw-wechat 1.7.2 → 2.0.1

package/src/wecom/outbound-active-stream.js

@@ -25,6 +25,7 @@ export function createWecomActiveStreamDeliverer({
     streamId,
     sessionId,
     content = "",
+    thinkingContent = "",
     normalizedMediaUrls = [],
     mediaType,
     normalizedText = "",
@@ -78,13 +79,17 @@ export function createWecomActiveStreamDeliverer({
     }
 
     let streamContent = String(content ?? "").trim();
+    const normalizedThinkingContent = String(thinkingContent ?? "").trim();
     if (!streamContent) {
-      streamContent =
-        fallbackMediaUrls.length > 0
-          ? fallbackText
-          : streamMsgItem.length > 0
-            ? "已收到模型返回的媒体结果。"
-            : "";
+      if (fallbackMediaUrls.length > 0) {
+        streamContent = fallbackText;
+      } else if (streamMsgItem.length > 0) {
+        streamContent = "已收到模型返回的媒体结果。";
+      } else if (normalizedThinkingContent) {
+        streamContent = "";
+      } else {
+        streamContent = "";
+      }
     }
     if (!normalizedText && streamMsgItem.length > 0 && fallbackMediaUrls.length === 0 && streamContent === fallbackText) {
       streamContent = "已收到模型返回的媒体结果。";
@@ -93,13 +98,15 @@ export function createWecomActiveStreamDeliverer({
       const suffix = `\n\n媒体链接：\n${fallbackMediaUrls.join("\n")}`;
       streamContent = `${streamContent}${suffix}`.trim();
     }
-    if (!streamContent) {
+    if (!streamContent && !normalizedThinkingContent) {
       streamContent = "已收到模型返回的结果。";
     }
 
-    finishBotStream(targetStreamId, streamContent, {
-      msgItem: streamMsgItem,
-    });
+    const finishOptions = { msgItem: streamMsgItem };
+    if (normalizedThinkingContent) {
+      finishOptions.thinkingContent = normalizedThinkingContent;
+    }
+    finishBotStream(targetStreamId, streamContent, finishOptions);
     return {
       ok: true,
       meta: {

package/src/wecom/outbound-delivery.js

@@ -32,6 +32,8 @@ export function createWecomBotReplyDeliverer({
   resolveWecomObservabilityPolicy,
   resolveWecomBotProxyConfig,
   resolveWecomBotConfig,
+  resolveWecomBotLongConnectionReplyContext,
+  pushWecomBotLongConnectionStreamUpdate,
   buildWecomBotSessionId,
   upsertBotResponseUrlCache,
   getBotResponseUrlCache,
@@ -60,6 +62,8 @@ export function createWecomBotReplyDeliverer({
   assertFunction("resolveWecomObservabilityPolicy", resolveWecomObservabilityPolicy);
   assertFunction("resolveWecomBotProxyConfig", resolveWecomBotProxyConfig);
   assertFunction("resolveWecomBotConfig", resolveWecomBotConfig);
+  assertFunction("resolveWecomBotLongConnectionReplyContext", resolveWecomBotLongConnectionReplyContext);
+  assertFunction("pushWecomBotLongConnectionStreamUpdate", pushWecomBotLongConnectionStreamUpdate);
   assertFunction("buildWecomBotSessionId", buildWecomBotSessionId);
   assertFunction("upsertBotResponseUrlCache", upsertBotResponseUrlCache);
   assertFunction("getBotResponseUrlCache", getBotResponseUrlCache);
@@ -163,6 +167,7 @@ export function createWecomBotReplyDeliverer({
     streamId,
     responseUrl,
     text,
+    thinkingContent = "",
     routeAgentId = "",
     mediaUrl,
     mediaUrls,
@@ -209,17 +214,57 @@ export function createWecomBotReplyDeliverer({
       });
     }
     const cachedResponseUrl = getBotResponseUrlCache(normalizedSessionId);
+    const longConnectionContext = resolveWecomBotLongConnectionReplyContext({
+      accountId: normalizedAccountId,
+      sessionId: normalizedSessionId,
+      streamId,
+    });
     const traceId = createDeliveryTraceId("wecom-bot");
     const router = createWecomDeliveryRouter({
       logger: api.logger,
       fallbackConfig: fallbackPolicy,
       observability: observabilityPolicy,
       handlers: {
+        long_connection: async ({ text: content }) => {
+          let streamMsgItem = [];
+          let fallbackMediaUrls = normalizedMediaUrls;
+          if (normalizedMediaUrls.length > 0) {
+            const processed = await buildActiveStreamMsgItems({
+              mediaUrls: normalizedMediaUrls,
+              mediaType,
+              fetchMediaFromUrl,
+              proxyUrl: botProxyUrl,
+              logger: api.logger,
+            });
+            streamMsgItem = processed.msgItem;
+            fallbackMediaUrls = processed.fallbackUrls;
+          }
+          let streamContent = String(content ?? "").trim();
+          if (!streamContent && fallbackMediaUrls.length > 0) {
+            streamContent = fallbackText;
+          }
+          if (fallbackMediaUrls.length > 0) {
+            streamContent = `${streamContent}\n\n媒体链接：\n${fallbackMediaUrls.join("\n")}`.trim();
+          }
+          if (!streamContent && !streamMsgItem.length && !String(thinkingContent ?? "").trim()) {
+            streamContent = fallbackText;
+          }
+          return pushWecomBotLongConnectionStreamUpdate({
+            accountId: normalizedAccountId,
+            sessionId: normalizedSessionId,
+            streamId,
+            content: streamContent,
+            finish: true,
+            msgItem: streamMsgItem,
+            thinkingContent,
+          });
+        },
         active_stream: async ({ text: content }) => {
           return deliverActiveStreamReply({
             streamId,
             sessionId: normalizedSessionId,
             content,
+            thinkingContent,
             normalizedMediaUrls,
             mediaType,
             normalizedText,
@@ -283,6 +328,7 @@ export function createWecomBotReplyDeliverer({
         streamId: streamId || "",
         hasResponseUrl: Boolean(inlineResponseUrl || cachedResponseUrl?.url),
         mediaCount: normalizedMediaUrls.length,
+        hasThinkingContent: Boolean(String(thinkingContent ?? "").trim()),
         botCardMode: botModeConfig?.card?.enabled ? botModeConfig.card.mode : "off",
       },
     });

package/src/wecom/outbound-webhook-sender.js

@@ -32,6 +32,26 @@ export function createWecomWebhookOutboundSender({
   assertFunction("createHash", createHash);
   assertFunction("sleep", sleep);
 
+  const webhookSendChains = new Map();
+
+  function buildWebhookTargetKey({ target, sendUrl }) {
+    return [String(target?.url ?? "").trim(), String(target?.key ?? "").trim(), String(sendUrl ?? "").trim()]
+      .filter(Boolean)
+      .join("|");
+  }
+
+  async function enqueueWebhookSend(targetKey, task) {
+    const previous = webhookSendChains.get(targetKey) || Promise.resolve();
+    const run = previous.catch(() => {}).then(task);
+    const tracked = run.finally(() => {
+      if (webhookSendChains.get(targetKey) === tracked) {
+        webhookSendChains.delete(targetKey);
+      }
+    });
+    webhookSendChains.set(targetKey, tracked);
+    return run;
+  }
+
   function resolveWebhookSendContext({ webhook, webhookTargets, proxyUrl, logger }) {
     const target = resolveWecomWebhookTargetConfig(webhook, webhookTargets);
     if (!target) {
@@ -45,31 +65,34 @@ export function createWecomWebhookOutboundSender({
       throw new Error("invalid webhook target url/key");
     }
     const dispatcher = attachWecomProxyDispatcher(sendUrl, {}, { proxyUrl, logger })?.dispatcher;
-    return { target, dispatcher };
+    return { target, dispatcher, sendUrl };
   }
 
   async function sendWecomWebhookText({ webhook, webhookTargets, text, logger, proxyUrl }) {
-    const { target, dispatcher } = resolveWebhookSendContext({
+    const { target, dispatcher, sendUrl } = resolveWebhookSendContext({
       webhook,
       webhookTargets,
       proxyUrl,
       logger,
     });
-    const chunks = splitWecomText(String(text ?? ""));
-    for (let i = 0; i < chunks.length; i += 1) {
-      await webhookSendText({
-        url: target.url,
-        key: target.key,
-        content: chunks[i],
-        timeoutMs: 15000,
-        dispatcher,
-        fetchImpl,
-      });
-      if (i < chunks.length - 1) {
-        await sleep(200);
+    const targetKey = buildWebhookTargetKey({ target, sendUrl });
+    return enqueueWebhookSend(targetKey, async () => {
+      const chunks = splitWecomText(String(text ?? ""));
+      for (let i = 0; i < chunks.length; i += 1) {
+        await webhookSendText({
+          url: target.url,
+          key: target.key,
+          content: chunks[i],
+          timeoutMs: 15000,
+          dispatcher,
+          fetchImpl,
+        });
+        if (i < chunks.length - 1) {
+          await sleep(200);
+        }
       }
-    }
-    logger?.info?.(`wecom: webhook text sent chunks=${chunks.length}`);
+      logger?.info?.(`wecom: webhook text sent chunks=${chunks.length}`);
+    });
   }
 
   async function sendWecomWebhookMediaBatch({

package/src/wecom/plugin-account-policy-services.js

@@ -107,7 +107,8 @@ export function createWecomPluginAccountPolicyServices({
     processEnv,
   });
 
-  const { resolveWecomVoiceTranscriptionConfig, transcribeInboundVoice } = createWecomVoiceTranscriber({
+  const { resolveWecomVoiceTranscriptionConfig, transcribeInboundVoice, inspectWecomVoiceTranscriptionRuntime } =
+    createWecomVoiceTranscriber({
     tempDirName: WECOM_TEMP_DIR_NAME,
     resolveVoiceTranscriptionConfig,
     normalizeAudioContentType,
@@ -124,6 +125,7 @@ export function createWecomPluginAccountPolicyServices({
     listWebhookTargetAliases,
     listAllWebhookTargetAliases,
     resolveWecomVoiceTranscriptionConfig,
+    inspectWecomVoiceTranscriptionRuntime,
     resolveWecomCommandPolicy,
     resolveWecomAllowFromPolicy,
     resolveWecomDmPolicy,
@@ -165,6 +167,7 @@ export function createWecomPluginAccountPolicyServices({
     resolveWecomObservabilityPolicy,
     resolveWecomDynamicAgentPolicy,
     resolveWecomVoiceTranscriptionConfig,
+    inspectWecomVoiceTranscriptionRuntime,
     transcribeInboundVoice,
     COMMANDS,
     buildWecomBotHelpText,

package/src/wecom/plugin-composition.js

@@ -12,6 +12,8 @@ const processingDeps = createPluginProcessingDeps({
 const { processBotInboundMessage, processInboundMessage, scheduleTextInboundProcessing } =
   createWecomPluginProcessingPipeline(processingDeps);
 
+services.setWecomBotLongConnectionInboundProcessor(processBotInboundMessage);
+
 const routeRuntimeDeps = createPluginRouteRuntimeDeps({
   ...services,
   processBotInboundMessage,

package/src/wecom/plugin-constants.js

@@ -1,5 +1,5 @@
 export const MAX_REQUEST_BODY_SIZE = 1024 * 1024;
-export const PLUGIN_VERSION = "1.7.1";
+export const PLUGIN_VERSION = "2.0.1";
 export const WECOM_TEMP_DIR_NAME = "openclaw-wechat";
 export const WECOM_TEMP_FILE_RETENTION_MS = 30 * 60 * 1000;
 export const WECOM_MIN_FILE_SIZE = 5;

package/src/wecom/plugin-delivery-inbound-services.js

@@ -17,6 +17,8 @@ export function createWecomPluginDeliveryInboundServices({
   resolveWecomObservabilityPolicy,
   resolveWecomBotProxyConfig,
   resolveWecomBotConfig,
+  resolveWecomBotLongConnectionReplyContext,
+  pushWecomBotLongConnectionStreamUpdate,
   upsertBotResponseUrlCache,
   getBotResponseUrlCache,
   markBotResponseUrlUsed,
@@ -53,6 +55,8 @@ export function createWecomPluginDeliveryInboundServices({
     resolveWecomObservabilityPolicy,
     resolveWecomBotProxyConfig,
     resolveWecomBotConfig,
+    resolveWecomBotLongConnectionReplyContext,
+    pushWecomBotLongConnectionStreamUpdate,
     buildWecomBotSessionId,
     upsertBotResponseUrlCache,
     getBotResponseUrlCache,

package/src/wecom/plugin-processing-deps.js

@@ -42,9 +42,12 @@ export function createPluginProcessingDeps(context = {}) {
       isDispatchTimeoutError: context.isDispatchTimeoutError,
       queueBotStreamMedia: context.queueBotStreamMedia,
       updateBotStream: context.updateBotStream,
+      pushWecomBotLongConnectionStreamUpdate: context.pushWecomBotLongConnectionStreamUpdate,
       isAgentFailureText: context.isAgentFailureText,
       scheduleTempFileCleanup: context.scheduleTempFileCleanup,
       ACTIVE_LATE_REPLY_WATCHERS: context.ACTIVE_LATE_REPLY_WATCHERS,
+      resetWecomConversationSession: context.resetWecomConversationSession,
+      clearSessionStoreEntry: context.clearSessionStoreEntry,
     },
     agentInboundDeps: {
       getWecomConfig: context.getWecomConfig,
@@ -83,6 +86,8 @@ export function createPluginProcessingDeps(context = {}) {
       isAgentFailureText: context.isAgentFailureText,
       scheduleTempFileCleanup: context.scheduleTempFileCleanup,
       ACTIVE_LATE_REPLY_WATCHERS: context.ACTIVE_LATE_REPLY_WATCHERS,
+      resetWecomConversationSession: context.resetWecomConversationSession,
+      clearSessionStoreEntry: context.clearSessionStoreEntry,
     },
     textSchedulerDeps: {
       resolveWecomGroupChatPolicy: context.resolveWecomGroupChatPolicy,

package/src/wecom/plugin-route-runtime-deps.js

@@ -51,9 +51,11 @@ export function createPluginRouteRuntimeDeps(context = {}) {
       resolveWecomDynamicAgentPolicy: context.resolveWecomDynamicAgentPolicy,
       resolveWecomBotConfig: context.resolveWecomBotConfig,
       resolveWecomBotConfigs: context.resolveWecomBotConfigs,
+      syncWecomBotLongConnections: context.syncWecomBotLongConnections,
       listEnabledWecomAccounts: context.listEnabledWecomAccounts,
       getWecomConfig: context.getWecomConfig,
       wecomChannelPlugin: context.wecomChannelPlugin,
+      registerWecomDocTools: context.registerWecomDocTools,
     },
   };
 }

package/src/wecom/plugin-services.js

@@ -42,6 +42,9 @@ import { createWecomPluginBaseServices } from "./plugin-base-services.js";
 import { createWecomPluginAccountPolicyServices } from "./plugin-account-policy-services.js";
 import { createWecomPluginDeliveryInboundServices } from "./plugin-delivery-inbound-services.js";
 import { createWecomBotInboundContentBuilder } from "./bot-inbound-content.js";
+import { createWecomBotLongConnectionManager } from "./bot-long-connection-manager.js";
+import { createWecomDocToolRegistrar } from "./doc-tool.js";
+import { createWecomSessionResetter } from "./session-reset.js";
 import { markdownToWecomText } from "./text-format.js";
 import {
   buildWecomSessionId,
@@ -91,6 +94,8 @@ export function createWecomPluginServices({
     resolveWecomObservabilityPolicy: accountPolicy.resolveWecomObservabilityPolicy,
     resolveWecomBotProxyConfig: accountPolicy.resolveWecomBotProxyConfig,
     resolveWecomBotConfig: accountPolicy.resolveWecomBotConfig,
+    resolveWecomBotLongConnectionReplyContext: (...args) => wecomBotLongConnectionManager.resolveReplyContext(...args),
+    pushWecomBotLongConnectionStreamUpdate: (...args) => wecomBotLongConnectionManager.pushStreamUpdate(...args),
     upsertBotResponseUrlCache: base.upsertBotResponseUrlCache,
     getBotResponseUrlCache: base.getBotResponseUrlCache,
     markBotResponseUrlUsed: base.markBotResponseUrlUsed,
@@ -124,12 +129,44 @@ export function createWecomPluginServices({
     writeFile,
     WECOM_TEMP_DIR_NAME,
   });
+  const registerWecomDocTools = createWecomDocToolRegistrar({
+    listEnabledWecomAccounts: accountPolicy.listEnabledWecomAccounts,
+    normalizeAccountId: accountPolicy.normalizeAccountId,
+    fetchWithRetry: base.fetchWithRetry,
+    getWecomAccessToken: base.getWecomAccessToken,
+  });
+  const { resetWecomConversationSession, clearSessionStoreEntry } = createWecomSessionResetter();
+  const wecomBotLongConnectionManager = createWecomBotLongConnectionManager({
+    attachWecomProxyDispatcher: base.attachWecomProxyDispatcher,
+    resolveWecomBotConfigs: accountPolicy.resolveWecomBotConfigs,
+    resolveWecomBotProxyConfig: accountPolicy.resolveWecomBotProxyConfig,
+    parseWecomBotInboundMessage,
+    describeWecomBotParsedMessage,
+    buildWecomBotSessionId,
+    createBotStream: base.createBotStream,
+    upsertBotResponseUrlCache: base.upsertBotResponseUrlCache,
+    markInboundMessageSeen,
+    messageProcessLimiter: base.messageProcessLimiter,
+    executeInboundTaskWithSessionQueue: deliveryInbound.executeInboundTaskWithSessionQueue,
+    deliverBotReplyText: deliveryInbound.deliverBotReplyText,
+    recordInboundMetric: base.recordInboundMetric,
+    recordRuntimeErrorMetric: base.recordRuntimeErrorMetric,
+  });
 
   return {
     ...base,
     ...accountPolicy,
     ...deliveryInbound,
     buildBotInboundContent,
+    registerWecomDocTools,
+    resetWecomConversationSession,
+    clearSessionStoreEntry,
+    setWecomBotLongConnectionInboundProcessor: wecomBotLongConnectionManager.setProcessBotInboundHandler,
+    resolveWecomBotLongConnectionReplyContext: wecomBotLongConnectionManager.resolveReplyContext,
+    pushWecomBotLongConnectionStreamUpdate: wecomBotLongConnectionManager.pushStreamUpdate,
+    syncWecomBotLongConnections: wecomBotLongConnectionManager.sync,
+    stopAllWecomBotLongConnections: wecomBotLongConnectionManager.stopAll,
+    getWecomBotLongConnectionState: wecomBotLongConnectionManager.getConnectionState,
     ACTIVE_LATE_REPLY_WATCHERS,
     WECOM_TEMP_DIR_NAME,
     normalizePluginHttpPath,

package/src/wecom/register-runtime.js

@@ -9,10 +9,12 @@ export function createWecomRegisterRuntime({
   resolveWecomDynamicAgentPolicy,
   resolveWecomBotConfig,
   resolveWecomBotConfigs,
+  syncWecomBotLongConnections,
   listEnabledWecomAccounts,
   getWecomConfig,
   wecomChannelPlugin,
   wecomRouteRegistrar,
+  registerWecomDocTools,
 } = {}) {
   if (typeof setGatewayRuntime !== "function") {
     throw new Error("createWecomRegisterRuntime: setGatewayRuntime is required");
@@ -38,6 +40,9 @@ export function createWecomRegisterRuntime({
   if (resolveWecomBotConfigs != null && typeof resolveWecomBotConfigs !== "function") {
     throw new Error("createWecomRegisterRuntime: resolveWecomBotConfigs must be a function");
   }
+  if (syncWecomBotLongConnections != null && typeof syncWecomBotLongConnections !== "function") {
+    throw new Error("createWecomRegisterRuntime: syncWecomBotLongConnections must be a function");
+  }
   if (listEnabledWecomAccounts != null && typeof listEnabledWecomAccounts !== "function") {
     throw new Error("createWecomRegisterRuntime: listEnabledWecomAccounts must be a function");
   }
@@ -50,6 +55,9 @@ export function createWecomRegisterRuntime({
   if (!wecomRouteRegistrar || typeof wecomRouteRegistrar !== "object") {
     throw new Error("createWecomRegisterRuntime: wecomRouteRegistrar is required");
   }
+  if (registerWecomDocTools != null && typeof registerWecomDocTools !== "function") {
+    throw new Error("createWecomRegisterRuntime: registerWecomDocTools must be a function");
+  }
 
   function register(api) {
     setGatewayRuntime(api.runtime);
@@ -91,6 +99,14 @@ export function createWecomRegisterRuntime({
         `wecom: webhookBot fallback enabled (${webhookBotPolicy.url || webhookBotPolicy.key ? "configured" : "missing-url"})`,
       );
     }
+    let longConnectionStarted = 0;
+    if (typeof syncWecomBotLongConnections === "function") {
+      const longConnectionResult = syncWecomBotLongConnections(api);
+      longConnectionStarted = Number(longConnectionResult?.started) || 0;
+      if (longConnectionStarted > 0) {
+        api.logger.info?.(`wecom(bot-longconn): enabled accounts=${longConnectionStarted}`);
+      }
+    }
     if (observabilityPolicy.enabled) {
       api.logger.info?.(
         `wecom: observability enabled (payloadMeta=${observabilityPolicy.logPayloadMeta ? "on" : "off"})`,
@@ -114,9 +130,12 @@ export function createWecomRegisterRuntime({
     }
 
     api.registerChannel({ plugin: wecomChannelPlugin });
+    if (typeof registerWecomDocTools === "function") {
+      registerWecomDocTools(api);
+    }
     const botRouteRegistered = wecomRouteRegistrar.registerWecomBotWebhookRoute(api);
     const webhookGroups = wecomRouteRegistrar.registerWecomAgentWebhookRoutes(api);
-    if (webhookGroups.size === 0 && !botRouteRegistered) {
+    if (webhookGroups.size === 0 && !botRouteRegistered && longConnectionStarted === 0) {
       api.logger.warn?.("wecom: no enabled account with valid config found; webhook route not registered");
       return;
     }

package/src/wecom/request-parsers.js

@@ -4,6 +4,7 @@ const DEFAULT_XML_PARSER_OPTIONS = {
   ignoreAttributes: false,
   trimValues: true,
   processEntities: false, // 防止 XXE
+  parseTagValue: false, // 保留前导零，避免 FromUserName/MsgId 等字段被自动转数值
 };
 
 export const DEFAULT_MAX_REQUEST_BODY_SIZE = 1024 * 1024;

package/src/wecom/route-registration.js

@@ -70,7 +70,10 @@ export function createWecomRouteRegistrar({
 
     const signedBotConfigs = enabledBotConfigs.filter((item) => item?.token && item?.encodingAesKey);
     if (signedBotConfigs.length === 0) {
-      api.logger.warn?.("wecom(bot): enabled but missing token/encodingAesKey; route not registered");
+      const longConnectionOnly = enabledBotConfigs.some((item) => item?.longConnection?.enabled === true);
+      if (!longConnectionOnly) {
+        api.logger.warn?.("wecom(bot): enabled but missing token/encodingAesKey; route not registered");
+      }
       return false;
     }
 

package/src/wecom/session-reset.js

@@ -0,0 +1,168 @@
+import { access, readFile, rename, writeFile } from "node:fs/promises";
+
+function normalizeText(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizeToken(value) {
+  return normalizeText(value).toLowerCase();
+}
+
+function resolveAgentIdFromSessionKey(sessionKey, fallback = "main") {
+  const match = /^agent:([^:]+):/i.exec(normalizeText(sessionKey));
+  const agentId = normalizeText(match?.[1]);
+  return agentId || normalizeText(fallback) || "main";
+}
+
+function resolveStoreEntryKey(store, sessionKey) {
+  if (!store || typeof store !== "object") return "";
+  const directKey = normalizeText(sessionKey);
+  if (directKey && Object.prototype.hasOwnProperty.call(store, directKey)) return directKey;
+  const normalizedKey = normalizeToken(sessionKey);
+  if (!normalizedKey) return "";
+  return Object.keys(store).find((key) => normalizeToken(key) === normalizedKey) || "";
+}
+
+async function readJsonObject(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (err?.code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+async function persistJsonObject(filePath, payload) {
+  const serialized = `${JSON.stringify(payload, null, 2)}\n`;
+  await writeFile(filePath, serialized, "utf8");
+}
+
+async function archiveTranscriptFile(sessionFile, dateNow = Date.now) {
+  const normalizedPath = normalizeText(sessionFile);
+  if (!normalizedPath) return { archived: false, archivedPath: "" };
+  try {
+    await access(normalizedPath);
+  } catch (err) {
+    if (err?.code === "ENOENT") return { archived: false, archivedPath: "" };
+    throw err;
+  }
+  const archivedPath = `${normalizedPath}.reset-${dateNow()}`;
+  await rename(normalizedPath, archivedPath);
+  return { archived: true, archivedPath };
+}
+
+export function createWecomSessionResetter({ dateNow = Date.now } = {}) {
+  async function clearSessionStoreEntry({ storePath, sessionKey, logger } = {}) {
+    const normalizedStorePath = normalizeText(storePath);
+    const normalizedSessionKey = normalizeText(sessionKey);
+    if (!normalizedStorePath || !normalizedSessionKey) {
+      return { cleared: false, transcriptArchived: false, archivedTranscriptPath: "" };
+    }
+
+    const store = await readJsonObject(normalizedStorePath);
+    const entryKey = resolveStoreEntryKey(store, normalizedSessionKey);
+    if (!entryKey) {
+      return { cleared: false, transcriptArchived: false, archivedTranscriptPath: "" };
+    }
+
+    const entry = store?.[entryKey] && typeof store[entryKey] === "object" ? store[entryKey] : {};
+    delete store[entryKey];
+    await persistJsonObject(normalizedStorePath, store);
+
+    let archivedTranscriptPath = "";
+    let transcriptArchived = false;
+    try {
+      const archived = await archiveTranscriptFile(entry?.sessionFile, dateNow);
+      transcriptArchived = archived.archived === true;
+      archivedTranscriptPath = archived.archivedPath || "";
+    } catch (err) {
+      logger?.warn?.(
+        `wecom: failed to archive transcript during local reset session=${normalizedSessionKey}: ${String(err?.message || err)}`,
+      );
+    }
+
+    return {
+      cleared: true,
+      transcriptArchived,
+      archivedTranscriptPath,
+    };
+  }
+
+  async function resetWecomConversationSession({
+    api,
+    runtime,
+    cfg,
+    baseSessionId,
+    fromUser,
+    chatId = "",
+    isGroupChat = false,
+    commandBody = "/reset",
+    accountId = "default",
+    groupChatPolicy = {},
+    dynamicAgentPolicy = {},
+    isAdminUser = false,
+    resolveWecomAgentRoute,
+    activeLateReplyWatchers,
+  } = {}) {
+    if (typeof resolveWecomAgentRoute !== "function") {
+      throw new Error("resetWecomConversationSession: resolveWecomAgentRoute is required");
+    }
+    if (!runtime?.channel?.session?.resolveStorePath) {
+      throw new Error("resetWecomConversationSession: runtime.channel.session.resolveStorePath is required");
+    }
+
+    const normalizedAccountId = normalizeToken(accountId) || "default";
+    const route = resolveWecomAgentRoute({
+      runtime,
+      cfg,
+      channel: "wecom",
+      accountId: normalizedAccountId,
+      sessionKey: baseSessionId,
+      fromUser,
+      chatId,
+      isGroupChat,
+      content: commandBody,
+      mentionPatterns: groupChatPolicy?.mentionPatterns,
+      dynamicConfig: dynamicAgentPolicy,
+      isAdminUser,
+      logger: api?.logger,
+    });
+
+    const sessionKey = normalizeText(route?.sessionKey) || normalizeText(baseSessionId);
+    const routedAgentId =
+      normalizeText(route?.agentId) || resolveAgentIdFromSessionKey(sessionKey, normalizeText(cfg?.agents?.default));
+    const storePath = runtime.channel.session.resolveStorePath(cfg?.session?.store, {
+      agentId: routedAgentId,
+    });
+
+    const result = await clearSessionStoreEntry({
+      storePath,
+      sessionKey,
+      logger: api?.logger,
+    });
+
+    if (activeLateReplyWatchers?.delete) {
+      activeLateReplyWatchers.delete(sessionKey);
+    }
+
+    api?.logger?.info?.(
+      `wecom: local session reset account=${normalizedAccountId} agent=${routedAgentId || "main"} session=${sessionKey} cleared=${result.cleared ? "yes" : "no"}`,
+    );
+
+    return {
+      ...result,
+      accountId: normalizedAccountId,
+      routedAgentId,
+      route,
+      sessionKey,
+      storePath,
+    };
+  }
+
+  return {
+    clearSessionStoreEntry,
+    resetWecomConversationSession,
+  };
+}