@yanhaidao/wecom 2.3.13 → 2.3.14

package/README.md

@@ -13,6 +13,10 @@
   <strong>🚀 企业级多模式 AI 助手接入方案（统一运行时架构）</strong>
 </p>
 
+<p align="center">
+  <strong>🚀 深度适配企业微信原生文档（WeCom Doc）：将对话沉淀为企业数字资产 [v2.3.14 重磅]</strong>
+</p>
+
 <p align="center">
   <a href="#sec-1">💡 核心价值</a> •
   <a href="#sec-2">📊 模式对比</a> •
@@ -70,6 +74,13 @@
 *   **发什么都能看**：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
 *   **要什么都能给**：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。
 
+#### 📝 **深度适配企业微信“协作文档” (WeCom Doc)**
+> *基于“协作的本质是信息流动”第一性原理打造，打破只能聊天的开源怪圈，让 AI 真正握住公司级文档库大权。*
+> *特别感谢 [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案。*
+*   **文档全生命周期**：支持从项目模板自动化创建全新文档、跨越部门重命名/克隆操作。
+*   **表格数据精细手术**：告别全量粗暴覆写，支持基于 Range 选区的单元格级精准更新（如：对特定表格内的状态进行实时覆盖）。
+*   **安全确权与跨界分析**：不仅能读取、分析现有庞大报表数据，更可用指令动态缩放协作成员的读写安全锁钥。
+
 #### 📢 **企业级触达 (Enterprise Reach)**
 *   **精准广播**：支持向 **部门 (Party)**、**标签 (Tag)** 或 **外部群** 批量推送消息。
 *   **Cronjob 集成**：通过简单的 JSON 配置实现早报推送、日报提醒、服务器报警。
@@ -93,6 +104,7 @@
 | **交互卡片 (A2UI)**| ❌ 不支持 | ✅ **支持** (Button/Select等) | **✅ 支持** |
 | **AI 流式响应** | ✅ **支持** (丝滑打字机) | ❌ 不支持 (全部生成完一次发送) | **✅ 完美支持** |
 | **主动触达 (Cron)**| ❌ 仅被动回复/有限推送 | ✅ **全量推送** (指定人/部门/标签) | **✅ 企业级触达** |
+| **📝 文档/表格管理** | ❌ 不支持 | ⚠️ 需自行开发对接 | **✅ 原生深度适配** (建档/改数据/读表/权限) |
 
 ---
 
@@ -102,6 +114,19 @@
 
 > 项目保持高频迭代，核心改进一览：
 
+#### v2.3.14（2026-03-14）
+
+- 📝 **[重磅功能]** 深度适配企业微信原生「协作文档」，支持通过自然语言自动建文档/表格、单元格级精准修改、跨表数据分析与权限管控。Thanks [@proyy](https://github.com/proyy)。
+- 🛑 **[核心修复]** 彻底修复并发场景下"正在思考..."无限刷屏死循环（`errcode=846608`），引入按会话追踪清理机制。
+- 📡 **[合规修复]** `enter_chat` 等事件不再违规调用流式回复接口，终结 `invalid req_id (846605)` 报错。
+- 🛡 WS 长连接增加 120 秒硬性超时熔断，防止极端情况下占位符永不停止。
+- 🤫 Agent 模式 `enter_agent` / `subscribe` 不再触发大模型生成欢迎语，静默处理，零 Token 消耗。
+
+**升级指引：**
+```bash
+openclaw plugins update wecom
+```
+
 #### v2.3.13（2026-03-13）
 
 - 🛠 **[重要修复]** `Bot WS` 现在会把“引用 + 提问”中的引用内容一起带入 Agent 上下文，不再只保留用户当前这句提问。
@@ -422,6 +447,19 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 在《二、配置说明》中讲解的 `dynamicAgents`，除了在运行时把会话隔离，它还在内存里做了一套高吞吐状态写入：
 系统会自动以异步、排队、防冲突的队列，将被激活的动态专用助理自动追加写入底层核心系统配置文件 `openclaw.json` (或相应 yaml) 的 `agents.list` 数组中，这就意味着：这套扩容体系是对上层管理员完全**透明且免运维**的，机器人活了，号也就落盘注册好了。
 
+### 4.4 📝 Docs 极客级协作资产管控
+从 v2.3.14 起，OpenClaw WeCom 插件已深度集成了企微原生协作文档的管理策略引擎。只需自然语言指令，即可唤醒这一能力：
+
+**【典型赋能场景】**
+1. **自动化建档**：对机器人说：“建一个名为『Q1需求追踪』的表格，并把群里的人都加上可写权限。”它将自动调用 `create_doc` 并生成带权限的企微链接。
+2. **移动端碎片修改**：在地铁上吩咐：“把「第二周面试记录」里的 B2 到 B5 单元格全部更新为‘二面通过’。” AI 会精准直击数据块，不干扰他人协同（`spreadsheet.edit_data`）。
+3. **跨表分析**：发给机器人一张总账表的企微链接：“分析这表里的营收列，告诉我哪个部门贡献最大？” AI 原生抓取数据解算输出。
+
+> **⚠️ 权限解锁指引**：
+> 要让 AI 解锁该能力，仅在配置文件填入 `agentSecret` 不够。企业微信已将文档在权限面上实施了“物理隔离”。请务必：
+> 1. 进入 [企微管理后台 -> 协作 -> 文档 -> 可调用接口应用白名单](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，勾选赋予你的 OpenClaw 自建应用“通行证”。
+> 2. 在 OpenClaw UI 界面工具集（Tool）勾选所有前缀含有 `doc:` 或 `wecom` 下相关操作单元。
+
 ---
 
 <a id="sec-7"></a>
@@ -491,6 +529,116 @@ openclaw channels status --deep
 
 ## 七、📮 联系我 与 版本协议
 
+### 最近更新
+
+近期保持高频迭代，最近版本如下：
+
+#### v2.3.12-zh（2026-03-13）by proyy
+
+> 本版本 WeCom Doc 功能增强来自 [proyy/wecom](https://github.com/proyy/wecom)。
+
+**WeCom Doc 功能模块详细核验报告：**
+
+### 📊 功能实现状态总览
+
+| 功能模块 | 状态 | 说明 |
+| :--- | :--- | :--- |
+| **管理文档** | ✅ 已实现 | 新建/删除/重命名/信息获取/分享均已就绪 |
+| **管理文档内容** | ✅ 已实现 | 文档内容读写、表格行列操作均已支持 |
+| **智能表格** | ✅ 已实现 | 子表/视图/字段/记录/编组的全生命周期管理 |
+| **设置文档权限** | ✅ 已实现 | 成员权限、安全设置、查看规则均已覆盖 |
+| **管理收集表** | ✅ 已实现 | 创建/编辑/统计/答案读取均已实现 |
+| **高级账号管理** | ✅ 已实现 | 分配/取消/列表查询均已实现 |
+| **素材管理** | ✅ 已实现 | 支持上传图片到文档专用素材库 |
+| **回调通知** | ❌ **未实现** | **当前系统会丢弃文档相关回调事件** |
+| **接收外部数据** | ✅ 已实现 | 已支持向智能表格添加/更新外部记录 |
+
+### 📝 逐项详细确认
+
+#### 1. 管理文档
+*   **新建文档**: `createDoc` (支持文档、表格、智能表格)
+*   **重命名文档**: `renameDoc`
+*   **删除文档**: `deleteDoc`
+*   **获取文档基础信息**: `getDocBaseInfo`
+*   **分享文档**: `shareDoc`
+
+#### 2. 管理文档内容
+*   **编辑文档内容**: `updateDocContent`
+*   **获取文档数据**: `getDocContent`
+*   **管理表格内容**: `modifySheetProperties`
+*   **编辑表格内容**: `editSheetData`
+*   **获取表格行列信息**: `getSheetProperties`
+*   **获取表格数据**: `getSheetData`
+
+#### 3. 管理智能表格内容
+*   **添加/删除/更新/查询子表**: `smartTableAddSheet`, `smartTableDeleteSheet` 等
+*   **添加/删除/更新/查询视图**: `smartTableAddView`, `smartTableView` 等
+*   **添加/删除/更新/查询字段**: `smartTableAddField`, `smartTableUpdateField` 等
+*   **添加/删除/更新/查询记录**: `smartTableAddRecords`, `smartTableGetRecords` 等
+*   **添加/删除/更新/获取编组**: 已通过 `smartTableUpdateGrouping` 等接口实现
+
+#### 4. 设置文档权限
+*   **获取文档权限信息**: `getDocAuth`
+*   **修改文档查看规则**: `setDocJoinRule`
+*   **修改文档通知范围及权限**: `modDocMemberNotifiedScope`, `setDocMemberAuth`
+*   **修改文档安全设置**: `setDocSafetySetting`, `modDocSecuritySetting`
+*   **管理智能表格内容权限**: 已包含在上述权限接口中 (支持对子表粒度控制)
+
+#### 5. 管理收集表
+*   **创建/编辑收集表**: `createCollect`, `modifyCollect`
+*   **获取收集表信息**: `getFormInfo`
+*   **收集表的统计信息查询**: `getFormStatistic`
+*   **读取收集表答案**: `getFormAnswer`
+
+#### 6. 回调通知 (⚠️ 缺失)
+*   修改文档成员事件
+*   删除文档事件
+*   收集表完成事件
+*   删除收集表事件
+*   修改收集表设置事件
+*   字段变更事件
+*   记录变更事件
+
+**原因诊断**: 在 `src/agent/handler.ts` 的 `shouldProcessAgentInboundMessage` 函数中，系统目前**显式过滤**了除 `subscribe`, `enter_agent`, `batch_job_result` 之外的所有事件。文档变更事件（如 `update_doc`, `doc_create` 等）会被视为 `unknown event` 而直接丢弃。
+
+#### 7. 接收外部数据到智能表格
+*   **概述/添加记录**: `smartTableAddExternalRecords`
+*   **更新记录**: `smartTableUpdateExternalRecords`
+
+#### 8. 高级功能账号管理 & 素材管理
+*   **账号管理**: `assignDocAdvancedAccount`, `cancelDocAdvancedAccount`, `getDocAdvancedAccountList`
+*   **上传文档图片**: `uploadDocImage`
+
+#### v2.3.11-zh（2026-03-12）by proyy
+
+- 全面增加企业微信 WeCom Doc 工具链：文档/表格/智能表格/收集表，以及全面的 CRUD 支持。
+- 增加文档权限与协作者管理 API。
+- 针对分享链接可用性诊断并修复底层返回带下划线 URL 被 markdown 行内截断导致打不开的问题。
+- 针对长文本分段问题进行的 BUG 修复与升级。
+
+#### v2.3.11（2026-03-11）
+
+- `Bot WS` 升级为即时占位 + 持续保活，降低长思考时的 `invalid req_id`。
+- `streamPlaceholderContent` 统一作用于 `Bot WS` 与 `Bot Webhook`。
+- onboarding 在空配置下也会提供 `default` 账号选项。
+- README 补充多账号共用静态 Agent 时的 session 隔离建议。
+
+#### 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` 流式输出能力。
+- 增强 Agent 回调与发送日志，排障更直接。
+
+详细版本记录见 `changelog/v2.3.11.md`、`changelog/v2.3.10.md` 与 `changelog/v2.3.9.md`。
+
 微信交流群（扫码入群）：
 
 ![企业微信交流群](https://openclaw.cc/wechat-github.jpg)

package/changelog/v2.3.14.md

@@ -0,0 +1,48 @@
+# OpenClaw WeCom 插件 v2.3.14 变更简报
+
+> [!TIP]
+> **企业微信“协作文档”原生整合与长连接稳定性修复版本**：`v2.3.14` 将机器人的能力从“陪聊”正式拓展到了“办公协同”。现在，你可以直接在微信群里让机器人去填报销单、建项目表；同时我们也彻底修复了多人并发聊天时机器人“正在思考”卡死刷屏的问题。
+>
+> 📣 **特别感谢** [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案，使本版本的 Docs 能力得以落地。
+
+## 重磅功能：把聊天直接变成企业文档（用后即得）
+
+我们受够了问 AI 一个问题，答案最后只能被新消息顶没。这次更新，我们让机器人获得了操作“企业微信协作文档”的实体权限。
+
+### 场景 1：开新项目，不用再求人建表格拉权限了
+- **以前**：你在群里说“准备一下下周的活动追踪表”，然后得切出去打开文档中心，新建表格，再一个个抄名字把大家拉进来。
+- **现在**：直接在群里 `@机器人 帮我建一个名为『春季新品发布会追踪』的表格，并把群里的人都加上可写权限`。机器人建好后会直接在群里甩出一个链接，所有人点开就能直接编辑，全程零切换。
+
+### 场景 2：坐在地铁上，照样神操作填报销/跟进数据
+- **以前**：你刚下班，群里有人问“今天 C 组的面试谁通过了？”你只能回答“我等下回家用电脑打开「面试记录表」改一下状态”。全量改动很容易把别人的同行数据覆盖掉。
+- **现在**：你可以直接发语音或者敲字 `@机器人 把「第二周面试记录表」里的 B2 到 B5 单元格全部更新为“二面通过”`。机器人会像操作手术刀一样，只精准替换指定的数据块（`spreadsheet.edit_data`），丝毫不影响文档里的其他公式。
+
+### 场景 3：直接让 AI 读懂全公司的数据报表
+- **以前**：你要先自己把表格下载成 Excel，再一段段复制数据发给大模型：“帮我算算这堆数据谁最高”。
+- **现在**：你直接丢给他一个企微文档链接：`@机器人 分析一下这张表里的第一季度数据，告诉我谁的单产最差？`。由于具备了原生读取能力（`get_sheet_range_data`），它会自己去拉取数据查表，给你输出结论。
+
+## 💡 Docs 权限配置指引（只需一次）
+
+为了让上述场景跑通，光配 `agentSecret` 是不够的。这是因为哪怕是公司自建的机器人，默认也没资格动你们内部的文档资产。你需要：
+1. **去企微后台发“通行证”**：进入 [企业微信后台 -> 协作 -> 文档 -> 可调用接口的应用](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，把你的机器人应用放进白名单。
+2. **在 OpenClaw 里激活能力**：打开 UI 界面 的 `Settings` -> `Agents` -> `Tools`，找到 `wecom`，把带有 `doc` 字眼的所有工具（创建文档、读取表格、改权限等）通通打勾。
+
+
+## 核心修复：终结“正在思考...”刷屏噩梦
+除了新功能，这次我们也彻底对长连接（WS）卡死问题做了一次大手术：
+- 🛑 **告别并发刷屏**：群里人多手杂的时候，以前机器人如果处理不过来，不仅不回话，还会满屏一直弹“正在思考...”。现在只要有一条真回复发出来，它会自动把同群里那些卡死、过期的“正在思考”全部瞬间清理干净。
+- 📡 **进群欢迎语报错 846605 终结**：修复了大家常反馈的“有人一进群，后台就疯狂报 invalid req_id”的陈年老 Bug。现在对进群、推卡片等非聊天事件，我们全面切换成了专属接口，彻底避免违规流式推送。
+- 🛡 **120 秒物理断网**：即使模型源站点挂了，我们现在也会在 120 秒内强制熔断提示，绝不让你面对一个无限转圈的加载框。
+
+---
+## 验证结果
+- `pnpm test -- src/transport/bot-ws`
+- 所有 WS 回复通道单测已全部通过，尤其是关于 `setInterval` 占位符存活期的验证得到了补全与修复。
+
+## 升级指引
+```bash
+openclaw plugins update wecom
+```
+- 无需新增配置，执行上述命令即可一键升级到 `v2.3.14`。
+- 升级后，如果你拉几十个机器人进群并同时发言，曾经那种满屏飘“正在思考...”却无人回答的乱象将不复存在。
+- 如果之前查看后台日志总是看到 `stream message update expired (>6 minutes)` 甚至因为连带引发的 WS 断网重启，本次升级将大幅度平息日志告警红字，稳定长连接状态。

package/index.ts

@@ -7,6 +7,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { handleWecomWebhookRequest } from "./src/monitor.js";
 import { setWecomRuntime } from "./src/runtime.js";
 import { wecomPlugin } from "./src/channel.js";
+import { registerWecomDocTools } from "./src/capability/doc/tool.js";
 
 const plugin = {
   id: "wecom",
@@ -33,6 +34,9 @@ const plugin = {
         match: "prefix",
       });
     }
+
+    // Register WeCom Doc Tools
+    registerWecomDocTools(api);
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.13",
+  "version": "2.3.14",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {
@@ -50,6 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.2.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.8"
   }
 }

package/src/agent/handler.event-filter.test.ts

@@ -3,22 +3,32 @@ import { describe, expect, it } from "vitest";
 import { shouldProcessAgentInboundMessage } from "./handler.js";
 
 describe("shouldProcessAgentInboundMessage", () => {
-    it("skips event callbacks so they do not create sessions", () => {
+    it("allows enter_agent/subscribe through the filter (handled earlier by static welcome)", () => {
         const enterAgent = shouldProcessAgentInboundMessage({
             msgType: "event",
             eventType: "enter_agent",
             fromUser: "zhangsan",
         });
-        expect(enterAgent.shouldProcess).toBe(false);
-        expect(enterAgent.reason).toBe("event:enter_agent");
+        expect(enterAgent.shouldProcess).toBe(true);
+        expect(enterAgent.reason).toBe("allowed_event:enter_agent");
 
         const subscribe = shouldProcessAgentInboundMessage({
             msgType: "event",
             eventType: "subscribe",
             fromUser: "lisi",
         });
-        expect(subscribe.shouldProcess).toBe(false);
-        expect(subscribe.reason).toBe("event:subscribe");
+        expect(subscribe.shouldProcess).toBe(true);
+        expect(subscribe.reason).toBe("allowed_event:subscribe");
+    });
+
+    it("skips unknown event callbacks so they do not create sessions", () => {
+        const unknown = shouldProcessAgentInboundMessage({
+            msgType: "event",
+            eventType: "some_random_event",
+            fromUser: "zhangsan",
+        });
+        expect(unknown.shouldProcess).toBe(false);
+        expect(unknown.reason).toBe("event:some_random_event");
     });
 
     it("skips system sender callbacks", () => {

package/src/agent/handler.ts

@@ -7,7 +7,7 @@ import { pathToFileURL } from "node:url";
 import path from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
-import type { ResolvedAgentAccount } from "../types/index.js";
+import type { ResolvedAgentAccount, UnifiedInboundEvent, WecomInboundKind } from "../types/index.js";
 import {
     extractMsgType,
     extractFromUser,
@@ -22,6 +22,7 @@ import { downloadAgentApiMedia, sendAgentApiText } from "../transport/agent-api/
 import { getWecomRuntime } from "../runtime.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import type { TransportSessionPatch } from "../types/index.js";
+import type { WecomAccountRuntime } from "../app/account-runtime.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
 import { resolveWecomMediaMaxBytes, shouldRejectWecomDefaultRoute } from "../config/index.js";
 import { buildAgentSessionTarget, generateAgentId, shouldUseDynamicAgent, ensureDynamicAgentListed } from "../dynamic-agent.js";
@@ -35,6 +36,23 @@ const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaida
 const RECENT_MSGID_TTL_MS = 10 * 60 * 1000;
 const recentAgentMsgIds = new Map<string, number>();
 
+// Event deduplication (e.g. for ENTER_AGENT/subscribe welcome messages)
+// We only want to send a welcome message once every 5 minutes per user
+const RECENT_EVENT_TTL_MS =3 * 60 * 1000;
+const recentAgentEvents = new Map<string, number>();
+
+function rememberAgentEvent(key: string): boolean {
+    const now = Date.now();
+    const existing = recentAgentEvents.get(key);
+    if (existing && now - existing < RECENT_EVENT_TTL_MS) return false;
+    recentAgentEvents.set(key, now);
+    // Prune expired
+    for (const [k, ts] of recentAgentEvents) {
+        if (now - ts >= RECENT_EVENT_TTL_MS) recentAgentEvents.delete(k);
+    }
+    return true;
+}
+
 function rememberAgentMsgId(msgId: string): boolean {
     const now = Date.now();
     const existing = recentAgentMsgIds.get(msgId);
@@ -150,6 +168,28 @@ export function shouldProcessAgentInboundMessage(params: {
     const eventType = String(params.eventType ?? "").trim().toLowerCase();
 
     if (msgType === "event") {
+        const allowedEvents = [
+            "subscribe",
+            "enter_agent",
+            "batch_job_result",
+            // WeCom Doc events
+            "doc_create",
+            "doc_delete",
+            "doc_content_change",
+            "doc_member_change",
+            // WeCom Form events
+            "wedoc_collect_submit",
+            // SmartSheet events
+            "smartsheet_record_change",
+            "smartsheet_field_change",
+            "smartsheet_view_change"
+        ];
+        if (allowedEvents.includes(eventType) || eventType.startsWith("doc_") || eventType.startsWith("wedoc_") || eventType.startsWith("smartsheet_")) {
+            return {
+                shouldProcess: true,
+                reason: `allowed_event:${eventType}`,
+            };
+        }
         return {
             shouldProcess: false,
             reason: `event:${eventType || "unknown"}`,
@@ -241,6 +281,7 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
         const chatId = extractChatId(msg);
         const msgId = extractMsgId(msg);
         const eventType = String((msg as Record<string, unknown>).Event ?? "").trim().toLowerCase();
+
         if (msgId) {
             const ok = rememberAgentMsgId(msgId);
             if (!ok) {
@@ -262,6 +303,15 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
                 return true;
             }
         }
+
+        // Agent 模式下 enter_agent / subscribe 不做任何处理，静默回 success
+        if (msgType === "event" && (eventType === "enter_agent" || eventType === "subscribe")) {
+            log?.(`[wecom-agent] ignoring ${eventType} from=${fromUser}; agent does not handle welcome events`);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("success");
+            return true;
+        }
         const content = String(extractContent(msg) ?? "");
 
         const preview = content.length > 100 ? `${content.slice(0, 100)}…` : content;
@@ -341,11 +391,41 @@ async function processAgentMessage(params: {
 
     const isGroup = Boolean(chatId);
     const peerId = isGroup ? chatId! : fromUser;
+    const eventType = String(msg.Event ?? "").trim().toLowerCase();
+
+    const resolveInboundKind = (): WecomInboundKind => {
+        if (msgType === "event") {
+            if (eventType === "subscribe" || eventType === "enter_agent") return "welcome";
+            return "event";
+        }
+        if (msgType === "image") return "image";
+        if (msgType === "voice") return "voice";
+        if (msgType === "video") return "video";
+        if (msgType === "file") return "file";
+        if (msgType === "location") return "location";
+        if (msgType === "link") return "link";
+        return "text";
+    };
+
+    const inboundKind = resolveInboundKind();
+    const resolveEventText = (): string => {
+        if (inboundKind === "welcome" && agent.config.welcomeText) {
+            return agent.config.welcomeText;
+        }
+        if (msgType === "event") {
+            return `[event:${eventType || "unknown"}]`;
+        }
+        return content;
+    };
+    
+    // BUG FIX: 真正调用 resolveEventText() 获取欢迎语或事件描述
+    const resolvedContent = resolveEventText();
+    let finalContent = resolvedContent;
+
     const mediaMaxBytes = resolveWecomMediaMaxBytes(config);
 
     // 处理媒体文件
-    const attachments: any[] = []; // TODO: define specific type
-    let finalContent = content;
+    const attachments: NonNullable<UnifiedInboundEvent["attachments"]> = [];
     let mediaPath: string | undefined;
     let mediaType: string | undefined;
 
@@ -369,9 +449,9 @@ async function processAgentMessage(params: {
                 const originalExt = path.extname(originalFileName).toLowerCase();
                 const normalizedContentType =
                     looksText && originalExt === ".md" ? "text/markdown" :
-                    looksText && (!contentType || contentType === "application/octet-stream")
-                        ? "text/plain; charset=utf-8"
-                        : contentType;
+                        looksText && (!contentType || contentType === "application/octet-stream")
+                            ? "text/plain; charset=utf-8"
+                            : contentType;
 
                 const ext = extMap[normalizedContentType] || (looksText ? "txt" : "bin");
                 const filename = `${mediaId}.${ext}`;
@@ -400,8 +480,8 @@ async function processAgentMessage(params: {
                 // 构建附件
                 attachments.push({
                     name: originalFileName,
-                    mimeType: normalizedContentType,
-                    url: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
+                    contentType: normalizedContentType,
+                    remoteUrl: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
                 });
 
                 // 更新文本提示
@@ -510,7 +590,7 @@ async function processAgentMessage(params: {
         route.agentId = targetAgentId;
         route.sessionKey = `agent:${targetAgentId}:wecom:${agent.accountId}:${isGroup ? "group" : "dm"}:${peerId}`;
         // 异步添加到 agents.list（不阻塞）
-        ensureDynamicAgentListed(targetAgentId, core).catch(() => {});
+        ensureDynamicAgentListed(targetAgentId, core).catch(() => { });
         log?.(`[wecom-agent] dynamic agent routing: ${targetAgentId}, sessionKey=${route.sessionKey}`);
     }
     // ===== 动态 Agent 路由注入结束 =====
@@ -602,46 +682,110 @@ const ctxPayload = core.channel.reply.finalizeInboundContext({
         },
     });
 
-    // 调度回复
-    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-        ctx: ctxPayload,
-        cfg: config,
-        replyOptions: {
-            disableBlockStreaming: true,
-        },
-        dispatcherOptions: {
-            deliver: async (payload: { text?: string }, info: { kind: string }) => {
-                if (info.kind !== "final") {
-                    return;
-                }
-                const text = payload.text ?? "";
-                if (!text) return;
-
-                try {
-                    // 统一策略：Agent 模式在群聊场景默认只私信触发者（避免 wr/wc chatId 86008）
-                    await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text });
-                    touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
-                    log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
-                } catch (err: unknown) {
-                    const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
-                    error?.(`[wecom-agent] reply failed: ${message}`);
-                    auditSink?.({
-                        transport: "agent-callback",
-                        category: "fallback-delivery-failed",
-                        summary: `agent callback reply failed user=${fromUser} kind=${info.kind}`,
-                        raw: {
-                            transport: "agent-callback",
-                            envelopeType: "xml",
-                            body: msg,
-                        },
-                        error: message,
-                    });
-                }            },
-            onError: (err: unknown, info: { kind: string }) => {
-                error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
-            },
+    // 5秒无响应自动回复进度提示
+    let hasResponseSent = false;
+    const processingTimer = setTimeout(async () => {
+        if (hasResponseSent) return;
+        try {
+            await sendAgentApiText({ 
+                agent, 
+                toUser: fromUser, 
+                chatId: undefined, 
+                text: "正在处理中，请稍候..." 
+            });
+            log?.(`[wecom-agent] sent processing notification to ${fromUser}`);
+        } catch (err) {
+            error?.(`[wecom-agent] failed to send processing notification: ${String(err)}`);
         }
-    });
+    }, 5000);
+
+    // 发送队列锁：确保所有 deliver 调用（以及内部的分片发送）严格串行执行
+    let messageSendQueue = Promise.resolve();
+
+    try {
+        // 调度回复
+        await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg: config,
+            replyOptions: {
+                disableBlockStreaming: true,
+            },
+            dispatcherOptions: {
+                deliver: async (payload: { text?: string }, info: { kind: string }) => {
+                    const text = payload.text ?? "";
+                    // 忽略空文本消息
+                    if (!text || !text.trim()) {
+                        return;
+                    }
+
+                    // 标记已有回复，清除/失效定时器
+                    hasResponseSent = true;
+                    clearTimeout(processingTimer);
+
+                    // 将本次发送任务加入队列
+                    // 即使 deliver 被并发调用，队列中的任务也会按入队顺序串行执行
+                    const currentTask = async () => {
+                        const MAX_CHUNK_SIZE = 600;
+                        // 确保分片顺序发送
+                        for (let i = 0; i < text.length; i += MAX_CHUNK_SIZE) {
+                            const chunk = text.slice(i, i + MAX_CHUNK_SIZE);
+                            
+                            try {
+                                await sendAgentApiText({ agent, toUser: fromUser, chatId: undefined, text: chunk });
+                                touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+                                log?.(`[wecom-agent] reply chunk delivered (${info.kind}) to ${fromUser}, len=${chunk.length}`);
+                                
+                                // 强制延时：确保企业微信有足够时间处理顺序
+                                if (i + MAX_CHUNK_SIZE < text.length) {
+                                    await new Promise(resolve => setTimeout(resolve, 200));
+                                }
+                            } catch (err: unknown) {
+                                const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
+                                error?.(`[wecom-agent] reply failed: ${message}`);
+                                auditSink?.({
+                                    transport: "agent-callback",
+                                    category: "fallback-delivery-failed",
+                                    summary: `agent callback reply failed user=${fromUser} kind=${info.kind}`,
+                                    raw: {
+                                        transport: "agent-callback",
+                                        envelopeType: "xml",
+                                        body: msg,
+                                    },
+                                    error: message,
+                                });
+                            }
+                        }
+                        
+                        // 不同 Block 之间也增加一点间隔
+                        if (info.kind !== "final") {
+                            await new Promise(resolve => setTimeout(resolve, 200));
+                        }
+                    };
+
+                    // 更新队列链
+                    // 使用 then 链接，并捕获前一个任务可能的错误，确保当前任务总能执行
+                    messageSendQueue = messageSendQueue
+                        .then(() => currentTask())
+                        .catch((err) => {
+                            error?.(`[wecom-agent] previous send task failed: ${String(err)}`);
+                            // 前一个失败不应阻止当前任务，继续尝试执行当前任务
+                            return currentTask();
+                        });
+
+                    // 等待当前任务完成（保持背压，虽然对于 http callback 模式这可能只是延迟了整体结束时间）
+                    await messageSendQueue;
+                },
+                onError: (err: unknown, info: { kind: string }) => {
+                    clearTimeout(processingTimer);
+                    error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
+                },
+            }
+        });
+    } finally {
+        clearTimeout(processingTimer);
+        // 确保所有排队的消息都发完了才退出（虽然对于 HTTP 响应来说，res.end 早就调用了）
+        await messageSendQueue;
+    }
 }
 
 /**

package/src/app/account-runtime.ts

@@ -30,7 +30,7 @@ export class WecomAccountRuntime {
     readonly core: PluginRuntime,
     readonly cfg: OpenClawConfig,
     readonly resolved: ResolvedRuntimeAccount,
-    private readonly log: {
+    readonly log: {
       info?: (message: string) => void;
       warn?: (message: string) => void;
       error?: (message: string) => void;

package/src/app/index.ts

@@ -27,6 +27,10 @@ export function registerAccountRuntime(accountRuntime: WecomAccountRuntime): voi
   console.log(`[wecom-runtime] register account=${accountRuntime.account.accountId}`);
 }
 
+export function getAccountRuntime(accountId: string): WecomAccountRuntime | undefined {
+  return runtimes.get(accountId);
+}
+
 export function getAccountRuntimeSnapshot(accountId: string) {
   return runtimes.get(accountId)?.buildRuntimeStatus();
 }