@yanhaidao/wecom 2.3.9 → 2.3.10

package/README.md

@@ -30,8 +30,10 @@
 ## 💡 核心价值：为什么选择本插件？
 
 ### 🎉 重大特性一览
-1. **无需域名，极低门槛**：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，**彻底打通无公网 IP、无备案域名的内网服务器**与企微的实时对话桥梁！
-2. **主动发消息，能力全覆盖**：基于 Agent 模式，全面支持**主动触达**，轻松实现早报定时任务、服务器异常报警、自动每日总结。
+1. **防断连黑科技** (v2.3.10 新增)：针对 DeepSeek R1 等长时间 <think> 的推理模型，首创 **4秒前置保活 ACK** 机制。彻底断绝模型限速或慢思考导致的 WebSocket 5秒超时重试风暴与消息卡死现象。
+2. **无需域名，极低门槛**：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，**彻底打通无公网 IP、无备案域名的内网服务器**与企微的实时对话桥梁！
+3. **主动发消息，能力全覆盖**：基于 Agent 模式，全面支持**主动触达**，轻松实现早报定时任务、服务器异常报警、自动每日总结。
+4. **向导自动路由自动适配** (v2.3.10 新增)：在终端执行 `openclaw channels add` 时，若是单企微账号接入，将**静默触发自动 Agent 路由绑定**，丝滑跳过全局冗杂的路由分配步骤。
 
 ### 🔧 全新统一运行时架构 (Unified Runtime)
 插件现已采用全新解耦架构：
@@ -154,7 +156,7 @@ openclaw channels add
           },
           "agent": {
             "corpId": "CORP_ID",
-            "corpSecret": "CORP_SECRET",
+            "agentSecret": "AGENT_SECRET",
             "agentId": 1000001,
             "token": "AGENT_TOKEN",
             "encodingAESKey": "AGENT_AES_KEY",
@@ -189,6 +191,10 @@ openclaw channels add
 }
 ```
 
+说明：
+- 新配置推荐使用 `agent.agentSecret`
+- 历史配置里的 `agent.corpSecret` 仍兼容读取，但后续文档统一使用 `agentSecret`
+
 ### 1.3 高级网络配置（公网出口代理）
 如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，首先使用Bot模式的ws接入方式。
 
@@ -422,18 +428,25 @@ openclaw channels status --deep
 
 ## 七、📮 联系我 与 版本协议
 
-### v2.3.9 更新日志（2026-03-09）
+### 最近更新
+
+近期保持高频迭代，最近版本如下：
+
+#### v2.3.10（2026-03-10）
+
+- onboarding 默认收敛为 `Bot + WS + 开放私聊`。
+- 修复 `Bot WS` 长文本双重回复问题。
+- 修复首个自定义接入标识时报 `default not found`。
+- Agent 新配置统一使用 `agentSecret`。
 
-本次版本重点收敛为“默认更易用、排障更直接、回调更稳定”：
+#### v2.3.9（2026-03-09）
 
-- **默认 Bot WebSocket 引导**：onboarding 默认写入 `bot.ws`，新用户无需域名即可完成机器人接入。
-- **中文化配置体验**：企业微信插件自管账号创建与私聊策略提示，尽量避免流程中重复出现英文术语。
-- **Bot WS 流式输出修复**：长连接模式支持块级流式交付，不再只保留最终结果。
-- **Webhook / Agent 回调稳定性增强**：统一 HTTP 分发链路，并补齐默认账号显式路径，便于 Bot 与 Agent 回调稳定命中。
-- **Agent 排障日志增强**：补充原始 callback、解密摘要、发送请求与响应日志，更容易定位“能接收但不能回复”的问题。
-- **配置收敛**：移除 `bot.enabled` / `agent.enabled` 冗余字段，减少误导。
+- Bot 默认接入改为 `WebSocket`，无需域名更易上手。
+- 完善中文 onboarding，减少重复提示。
+- 恢复 `Bot WS` 流式输出能力。
+- 增强 Agent 回调与发送日志，排障更直接。
 
-详细版本记录见 `changelog/v2.3.9.md`。
+详细版本记录见 `changelog/v2.3.10.md` 与 `changelog/v2.3.9.md`。
 
 微信交流群（扫码入群）：
 

package/changelog/v2.3.10.md

@@ -0,0 +1,17 @@
+# OpenClaw WeCom 插件 v2.3.10 变更简报
+
+> [!TIP]
+> **默认更易用、修复更直接的版本。**
+
+## 2026-03-10（v2.3.10）
+- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发"⏳ 正在思考中..."），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。
+- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。
+- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。
+- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account "default" not found` 的问题。
+- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。
+- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。
+- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。
+
+## 验证结果
+- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`
+- `pnpm build`

package/compat-single-account.md

@@ -31,7 +31,7 @@ openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'
 
 ```bash
 openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
-openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
+openclaw config set channels.wecom.agent.agentSecret "YOUR_AGENT_SECRET"
 openclaw config set channels.wecom.agent.agentId 1000001
 openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
 openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
@@ -71,7 +71,7 @@ openclaw channels status
 
       "agent": {
         "corpId": "YOUR_CORP_ID",
-        "corpSecret": "YOUR_CORP_SECRET",
+        "agentSecret": "YOUR_AGENT_SECRET",
         "agentId": 1000001,
         "token": "YOUR_CALLBACK_TOKEN",
         "encodingAESKey": "YOUR_CALLBACK_AES_KEY",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.9",
+  "version": "2.3.10",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
   "repository": {

package/src/config/accounts.resolve.test.ts

@@ -13,8 +13,11 @@ describe("resolveWecomAccount", () => {
           "acct-a": {
             enabled: true,
             bot: {
-              token: "token-a",
-              encodingAESKey: "aes-a",
+              primaryTransport: "webhook",
+              webhook: {
+                token: "token-a",
+                encodingAESKey: "aes-a",
+              },
             },
           },
         },
@@ -35,4 +38,38 @@ describe("resolveWecomAccount", () => {
     expect(account.enabled).toBe(true);
     expect(account.configured).toBe(true);
   });
+
+  it("treats literal default as an alias for configured default account", () => {
+    const account = resolveWecomAccount({ cfg, accountId: "default" });
+    expect(account.accountId).toBe("acct-a");
+    expect(account.enabled).toBe(true);
+    expect(account.configured).toBe(true);
+  });
+
+  it("accepts agentSecret for fresh configs and normalizes it for runtime use", () => {
+    const agentCfg: OpenClawConfig = {
+      channels: {
+        wecom: {
+          enabled: true,
+          defaultAccount: "acct-agent",
+          accounts: {
+            "acct-agent": {
+              enabled: true,
+              agent: {
+                corpId: "corp-id",
+                agentSecret: "agent-secret",
+                agentId: 1000001,
+                token: "token",
+                encodingAESKey: "1234567890123456789012345678901234567890123",
+              },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const account = resolveWecomAccount({ cfg: agentCfg });
+    expect(account.agent?.apiConfigured).toBe(true);
+    expect(account.agent?.corpSecret).toBe("agent-secret");
+  });
 });

package/src/config/accounts.ts

@@ -73,14 +73,15 @@ function resolveAgentAccount(
 ): ResolvedAgentAccount {
   const agentId = toNumber(config.agentId);
   const callbackConfigured = Boolean(config.token && config.encodingAESKey);
-  const apiConfigured = Boolean(config.corpId && config.corpSecret && agentId);
+  const normalizedAgentSecret = config.agentSecret?.trim() || config.corpSecret?.trim() || "";
+  const apiConfigured = Boolean(config.corpId && normalizedAgentSecret && agentId);
   return {
     accountId,
     configured: callbackConfigured || apiConfigured,
     callbackConfigured,
     apiConfigured,
     corpId: config.corpId,
-    corpSecret: config.corpSecret,
+    corpSecret: normalizedAgentSecret,
     agentId,
     token: config.token,
     encodingAESKey: config.encodingAESKey,
@@ -113,6 +114,15 @@ function toResolvedAccount(params: {
   };
 }
 
+function createMissingResolvedAccount(accountId: string): ResolvedWecomAccount {
+  return {
+    accountId,
+    enabled: false,
+    configured: false,
+    config: {},
+  };
+}
+
 export function detectMode(config: WecomConfig | undefined): ResolvedMode {
   if (!config || config.enabled === false) return "disabled";
   if (config.accounts && Object.keys(config.accounts).length > 0) {
@@ -260,12 +270,24 @@ export function resolveWecomAccount(params: {
   accountId?: string | null;
 }): ResolvedWecomAccount {
   const resolved = resolveWecomAccounts(params.cfg);
-  const accountId = params.accountId?.trim() || resolved.defaultAccountId;
-  const account = resolved.accounts[accountId];
-  if (!account) {
-    throw new Error(`WeCom account "${accountId}" not found.`);
+  const explicitAccountId = params.accountId?.trim();
+  const accountId = explicitAccountId || resolved.defaultAccountId;
+  const direct = resolved.accounts[accountId];
+  if (direct) {
+    return direct;
   }
-  return account;
+
+  // Treat the literal "default" as an alias for the configured default account.
+  // This keeps generic onboarding flows working even when the first WeCom account
+  // was created under a custom id like "haidao" instead of a literal "default".
+  if (explicitAccountId === DEFAULT_ACCOUNT_ID) {
+    const fallback = resolved.accounts[resolved.defaultAccountId];
+    if (fallback) {
+      return fallback;
+    }
+  }
+
+  return createMissingResolvedAccount(accountId);
 }
 
 export function isWecomEnabled(cfg: OpenClawConfig): boolean {

package/src/config/schema.ts

@@ -67,13 +67,18 @@ const botSchema = z
 const agentSchema = z
   .object({
     corpId: z.string(),
-    corpSecret: z.string(),
+    agentSecret: z.string().optional(),
+    corpSecret: z.string().optional(),
     agentId: z.union([z.number(), z.string()]).optional(),
     token: z.string(),
     encodingAESKey: z.string(),
     welcomeText: z.string().optional(),
     dm: dmSchema,
   })
+  .refine((value) => Boolean(value.agentSecret?.trim() || value.corpSecret?.trim()), {
+    path: ["agentSecret"],
+    message: "agentSecret 不能为空",
+  })
   .optional();
 
 const dynamicAgentsSchema = z

package/src/onboarding.test.ts

@@ -168,7 +168,7 @@ describe("wecom onboarding", () => {
   it("uses plugin-owned chinese account selection and no generic dm adapter", async () => {
     const prompter = createPrompter({
       select: vi.fn(async ({ message }: { message: string }) => {
-        if (message === "请选择企业微信账号:") {
+        if (message === "请选择企业微信接入标识（英文）:") {
           return "__new__";
         }
         if (message === "请选择您要配置的接入模式:") {
@@ -180,7 +180,7 @@ describe("wecom onboarding", () => {
         throw new Error(`Unexpected select prompt: ${message}`);
       }) as WizardPrompter["select"],
       text: vi.fn(async ({ message }: { message: string }) => {
-        if (message === "请输入新的企业微信账号 ID:") {
+        if (message === "请输入新的企业微信接入标识（英文）:") {
           return "HaiDao";
         }
         if (message === "请输入 BotId（机器人 ID）:") {
@@ -213,7 +213,56 @@ describe("wecom onboarding", () => {
     const noteText = (prompter.note as ReturnType<typeof vi.fn>).mock.calls
       .map(([message]) => String(message))
       .join("\n");
-    expect(noteText).toContain("账号 ID 已规范化为：haidao");
+    expect(noteText).toContain("接入标识已规范化为：haidao");
     expect(wecomOnboardingAdapter.dmPolicy).toBeUndefined();
   });
+
+  it("writes agentSecret for fresh agent onboarding", async () => {
+    const prompter = createPrompter({
+      select: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "请选择您要配置的接入模式:") {
+          return "agent";
+        }
+        if (message === "请选择私聊 (DM) 访问策略:") {
+          return "open";
+        }
+        throw new Error(`Unexpected select prompt: ${message}`);
+      }) as WizardPrompter["select"],
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "请输入 CorpID (企业ID):") {
+          return "corp-id";
+        }
+        if (message === "请输入 AgentID (应用ID):") {
+          return "1000001";
+        }
+        if (message === "请输入应用 Secret:") {
+          return "agent-secret";
+        }
+        if (message === "请输入 Token (回调令牌):") {
+          return "callback-token";
+        }
+        if (message === "请输入 EncodingAESKey (回调加密密钥):") {
+          return "1234567890123456789012345678901234567890123";
+        }
+        if (message === "欢迎语 (可选):") {
+          return "欢迎使用智能助手";
+        }
+        throw new Error(`Unexpected text prompt: ${message}`);
+      }) as WizardPrompter["text"],
+    });
+
+    const result = await wecomOnboardingAdapter.configure({
+      cfg: {} as OpenClawConfig,
+      runtime: createRuntime(),
+      prompter,
+      options: {},
+      accountOverrides: {},
+      shouldPromptAccountIds: false,
+      forceAllowFrom: false,
+    });
+
+    const agent = result.cfg.channels?.wecom?.accounts?.default?.agent;
+    expect(agent?.agentSecret).toBe("agent-secret");
+    expect(agent?.corpSecret).toBeUndefined();
+  });
 });

package/src/onboarding.ts

@@ -250,26 +250,26 @@ async function resolveOnboardingAccountId(params: {
     if (!override && params.shouldPromptAccountIds) {
         const existingIds = listWecomAccountIds(params.cfg);
         const choice = await params.prompter.select({
-            message: "请选择企业微信账号:",
+            message: "请选择企业微信接入标识（英文）:",
             options: [
                 ...existingIds.map((id) => ({
                     value: id,
-                    label: id === DEFAULT_ACCOUNT_ID ? "default（主账号）" : id,
+                    label: id === DEFAULT_ACCOUNT_ID ? "default（默认标识）" : id,
                 })),
-                { value: "__new__", label: "新增账号" },
+                { value: "__new__", label: "新增接入标识" },
             ],
             initialValue: accountId,
         });
         if (choice === "__new__") {
             const entered = await params.prompter.text({
-                message: "请输入新的企业微信账号 ID:",
-                validate: (value: string | undefined) => (value?.trim() ? undefined : "账号 ID 不能为空"),
+                message: "请输入新的企业微信接入标识（英文）:",
+                validate: (value: string | undefined) => (value?.trim() ? undefined : "接入标识不能为空"),
             });
             const normalized = normalizeAccountId(String(entered));
             if (String(entered).trim() !== normalized) {
                 await params.prompter.note(
-                    `账号 ID 已规范化为：${normalized}`,
-                    "企业微信账号",
+                    `接入标识已规范化为：${normalized}`,
+                    "企业微信接入标识",
                 );
             }
             accountId = normalized;
@@ -325,7 +325,7 @@ async function promptMode(prompter: WizardPrompter): Promise<WecomMode> {
                 hint: "Bot 默认 WS 易上手，Agent 负责应用回调、主动推送和媒体发送",
             },
         ],
-        initialValue: "both",
+        initialValue: "bot",
     });
     return choice as WecomMode;
 }
@@ -433,10 +433,10 @@ async function configureAgentMode(
     ).trim();
     const agentId = Number(agentIdStr);
 
-    const corpSecret = String(
+    const agentSecret = String(
         await prompter.text({
-            message: "请输入 Secret (应用密钥):",
-            validate: (value: string | undefined) => (value?.trim() ? undefined : "Secret 不能为空"),
+            message: "请输入应用 Secret:",
+            validate: (value: string | undefined) => (value?.trim() ? undefined : "应用 Secret 不能为空"),
         }),
     ).trim();
 
@@ -478,7 +478,7 @@ async function configureAgentMode(
 
     const agentConfig: WecomAgentConfig = {
         corpId,
-        corpSecret,
+        agentSecret,
         agentId,
         token,
         encodingAESKey,
@@ -506,7 +506,7 @@ async function promptDmPolicy(
             { value: "open", label: "开放模式", hint: "任何人可发起" },
             { value: "disabled", label: "禁用私聊", hint: "不接受私聊消息" },
         ],
-        initialValue: "pairing",
+        initialValue: "open",
     });
 
     const policy = policyChoice as "pairing" | "allowlist" | "open" | "disabled";
@@ -560,7 +560,7 @@ async function showSummary(cfg: OpenClawConfig, prompter: WizardPrompter, accoun
         lines.push("   出站能力: Agent API（主动发送 / 补送 / 媒体）");
     }
 
-    lines.push(`   账号 ID: ${accountId}`);
+    lines.push(`   接入标识: ${accountId}`);
     lines.push("   运维检查: openclaw channels status --deep");
     lines.push("   关键日志: [wecom-runtime] [wecom-ws] [wecom-http] [wecom-agent-delivery]");
 

package/src/outbound.test.ts

@@ -16,7 +16,7 @@ describe("wecomOutbound", () => {
         text: "caption",
         mediaUrl: "https://example.com/media.png",
       } as any),
-    ).rejects.toThrow(/account "default" not found/i);
+    ).rejects.toThrow(/requires Agent mode for account=default/i);
   });
 
   it("throws explicit error when outbound accountId does not exist", async () => {

package/src/transport/bot-ws/inbound.ts

@@ -91,7 +91,6 @@ export function mapBotWsFrameToInboundEvent(params: {
       transport: "bot-ws",
       accountId: account.accountId,
       reqId: frame.headers.req_id,
-      passiveWindowMs: 5_000,
       raw: {
         transport: "bot-ws",
         command: frame.cmd,

package/src/transport/bot-ws/reply.ts

@@ -15,6 +15,16 @@ export function createBotWsReplyHandle(params: {
     return streamId;
   };
 
+  let ackSent = false;
+  const ackTimer = setTimeout(() => {
+    if (ackSent) return;
+    ackSent = true;
+    params.client.replyStream(params.frame, resolveStreamId(), "⏳ 正在思考中...\n\n", false)
+      .catch(() => { /* ignore */ });
+  }, 4000);
+
+  const cleanupTimer = () => clearTimeout(ackTimer);
+
   return {
     context: {
       transport: "bot-ws",
@@ -29,17 +39,22 @@ export function createBotWsReplyHandle(params: {
       },
     },
     deliver: async (payload: ReplyPayload, info) => {
-      if (payload.isReasoning) {
-        return;
-      }
+      if (payload.isReasoning) return;
+      
       const text = payload.text?.trim();
-      if (!text) {
-        return;
+      if (!text) return;
+
+      if (!ackSent) {
+        cleanupTimer();
+        ackSent = true;
       }
+      
       await params.client.replyStream(params.frame, resolveStreamId(), text, info.kind === "final");
       params.onDeliver?.();
     },
     fail: async (error: unknown) => {
+      cleanupTimer();
+      ackSent = true;
       const message = error instanceof Error ? error.message : String(error);
       await params.client.replyStream(params.frame, resolveStreamId(), `WeCom WS reply failed: ${message}`, true);
       params.onFail?.(error);

package/src/types/config.ts

@@ -49,7 +49,12 @@ export type WecomBotConfig = {
 
 export type WecomAgentConfig = {
   corpId: string;
-  corpSecret: string;
+  agentSecret?: string;
+  /**
+   * Deprecated compatibility alias for old configs.
+   * New configs should use `agentSecret`.
+   */
+  corpSecret?: string;
   agentId?: number | string;
   token: string;
   encodingAESKey: string;