@yanhaidao/wecom 2.3.12 → 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,26 @@
 
 > 项目保持高频迭代，核心改进一览：
 
+#### 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 上下文，不再只保留用户当前这句提问。
+- 🌊 **[重要修复]** `Bot WS` 流式回复改为按“累计全文刷新”发送，修复企业微信客户端里长回答断断续续、像被拆成多段的问题。
+- 🧩 `Bot WS` 这次显式对齐企业微信 `stream.id` 的刷新语义：后续更新会覆盖为当前完整内容，而不是只发送最新增量片段。
+- ✅ 新增 `bot-ws` 引用上下文与累计流式发送回归测试，避免后续重构回退。
+
 #### v2.3.12（2026-03-12）
 
 - 🛠 **[重要修复]** Bot WS 流式回复超 6 分钟后的 `846608 stream message update expired` 现在被识别为终态错误，不再导致进程退出。
@@ -109,6 +141,8 @@
 - 🚀 Bot WS 模式下主动文本消息优先走 WS 长连接；Agent 仅兜底文件/媒体或未启用 WS 的场景。
 - 🧯 `sdk-adapter` 为 WebSocket frame 异步处理补上显式兜底捕获，漏网异常记录为 runtime issue 而非崩溃。
 - ⏱ 回复窗口过期时占位符保活立即停止。
+- 🛠 **[重要修复]** Bot WS 模式下接收图片/文件现在使用消息体独立 `aeskey` 解密，修复之前保存密文导致 `Failed to optimize image` 的问题。
+- 🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的 81013 错误。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
 
 #### v2.3.11（2026-03-11）
 
@@ -413,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>
@@ -473,12 +520,125 @@ openclaw channels status --deep
 **Q5: 为什么发视频给 Bot 没反应？**
 > **A:** 官方 Bot 接口**不支持接收视频**。如果您需要处理视频内容，必须配置 Agent 小微应用，由于 Agent 下行具备富媒体流承接功能，本插件会自动从底层拦截将其解码并传输给底层大模型看。
 
+**Q6: 支持个人微信吗？**
+> **A:** 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），这不等同于“个人微信网页版协议”。您可以在个人微信中直接与企业号/应用对话，无需打开企业微信 App。
+
 ---
 
 <a id="sec-9"></a>
 
 ## 七、📮 联系我 与 版本协议
 
+### 最近更新
+
+近期保持高频迭代，最近版本如下：
+
+#### 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.12.md

@@ -7,10 +7,12 @@
 - 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。
 - 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。
 - 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。
+- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。
 - 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。
 - 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。
 - 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。
 - 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。
+- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。
 
 ## 验证结果
 - `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`

package/changelog/v2.3.13.md

@@ -0,0 +1,19 @@
+# OpenClaw WeCom 插件 v2.3.13 变更简报
+
+> [!TIP]
+> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。
+
+## 2026-03-13（v2.3.13）
+- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。
+- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。
+- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。
+- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。
+
+## 验证结果
+- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`
+- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`
+
+## 升级提示
+- 无需新增配置，升级到 `v2.3.13` 后自动生效。
+- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。
+- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。

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,8 +1,8 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.12",
+  "version": "2.3.14",
   "type": "module",
-  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持 Agent 主动发消息与多账号接入",
+  "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/YanHaidao/wecom.git"
@@ -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", () => {