@yanhaidao/wecom 2.0.2 → 2.2.4

package/GEMINI.md

@@ -0,0 +1,76 @@
+# 企业微信 (WeCom) 插件上下文
+
+## 平台架构：机器人 (Bot) vs 自建应用 (Agent)
+
+本插件采用 **双模 (Dual-Mode)** 架构，结合了企业微信“智能机器人”和“自建应用”的优势。
+
+### 1. 定义与边界
+
+| 特性 | **Bot (智能机器人)** | **Agent (自建应用)** |
+| :--- | :--- | :--- |
+| **身份** | 虚拟用户/助手。 | 工作台中的服务应用。 |
+| **位置** | 存在于 **会话** 中 (单聊或群聊)。 | 存在于 **工作台** 或应用列表。 |
+| **协议** | **JSON** (加密)。 | **XML** (加密)。 |
+| **交互** | 对话式 (回复用户)。 | 事务式 (通知用户/系统)。 |
+| **流式 (Stream)** | ✅ **支持** (打字机效果)。 | ❌ 不支持。 |
+| **文件能力** | ❌ **受限** (被动回复无法发文件)。 | ✅ **完整支持** (API 发送视频、文件、图片)。 |
+| **群聊支持** | ✅ 原生支持 (可被 @)。 | ⚠️ 受限 (仅能在自建群或通过 API 推送)。 |
+
+### 2. 通信协议
+
+#### A. Bot (智能机器人)
+*   **接收 (回调)**:
+    *   **格式**: JSON。
+    *   **单聊**: `chattype: "single"`. 无 `chatid`。`cid` = `from.userid`。
+    *   **群聊**: `chattype: "group"`. 有 `chatid`。`cid` = `chatid`。
+*   **发送 (回复)**:
+    *   **交互回复**: 使用回调中的 `response_url`。支持 `markdown`, `template_card`。**不支持文件/视频**。
+    *   **主动推送**: 使用 Webhook Key。
+
+#### B. Agent (自建应用)
+*   **接收 (回调)**:
+    *   **格式**: XML。
+    *   **结构**: `<ToUserName>`, `<FromUserName>`, `<MsgType>`, `<Content>`。
+*   **发送 (推送)**:
+    *   **API**: `message/send`。
+    *   **能力**: 支持所有媒体类型 (文件, 视频, 语音, 文本, 卡片)。
+    *   **对象**: 用户 (`touser`), 部门 (`toparty`), 标签 (`totag`)。
+
+---
+
+## 核心策略：机器人优先，智能体兜底 (接近 6 分钟切换)
+
+### 目标
+*   **默认**: 用户在 Bot 会话触发，结果在 Bot 会话内完成回复（含流式）。
+*   **兜底**: 当 Bot 因超时（接近 6 分钟限制）、异常或流式窗口结束无法完成交付时，若配置了 Agent，则由 Agent 私信触发用户发送最终结果。
+
+### 关键约束
+*   **6 分钟窗口**: 企业微信智能机器人流式链路最多维持 6 分钟。超过后连接断开。
+
+### 流程详解
+
+#### 1. 启动阶段 (Bot)
+1.  **接收消息**: 解析 JSON 回调。
+2.  **生成 StreamID**: 确定性生成 `streamId = hash(accountId + aibotid + msgid)`，防止并发重试导致重复创建流。
+3.  **快速响应**: 立即返回“已接收，处理中”或流式首包，建立连接。
+
+#### 2. 执行阶段 (Worker)
+4.  **异步处理**: 任务入队执行。
+5.  **流式刷新**: 当收到企微的“流式消息刷新”回调时，根据 `streamId` 返回最新生成的内容。
+
+#### 3. 正常交付 (Bot)
+6.  **完成**: 任务在 6 分钟内完成，发送 `finish=true` 信号结束流式消息。
+
+#### 4. 异常切换 (Agent 兜底)
+7.  **触发条件**:
+    *   **超时临界**: `now >= createdAt + 6min - 安全阈值(30s)`。
+    *   **链路中断**: Bot 刷新回调长时间未到达 (如 > 60s)。
+    *   **发送异常**: Bot 接口报错。
+8.  **切换动作**:
+    *   **状态标记**: 将任务标记为 `agent_fallback`。
+    *   **用户提示**: (可选) Bot 在群内尝试发送“结果将私信送达”。
+    *   **私信推送**: Agent 调用 `message/send` 接口，将最终结果（文本/文件）推送给触发者 `userId`。
+    *   **注意**: 即使原会话是群聊，兜底结果通常通过 Agent **私信** 发送给触发者，因为 Agent 难以直接向普通群推送消息。
+
+### 总结
+该策略确保了用户体验（首选流式）和交付可靠性（超时/发文件走 Agent）的平衡。

package/README.md

@@ -1,120 +1,363 @@
 # OpenClaw 企业微信（WeCom）Channel 插件
 
-维护者：YanHaidao（VX：YanHaidao）
+<p align="center">
+  <strong>🚀 企业级双模式 AI 助手接入方案</strong>
+</p>
 
-状态：支持企业微信智能机器人（API 模式）加密回调 + 被动回复（stream）。
+<p align="center">
+  <a href="#功能亮点">功能亮点</a> •
+  <a href="#模式对比">模式对比</a> •
+  <a href="#快速开始">快速开始</a> •
+  <a href="#配置说明">配置说明</a> •
+  <a href="#联系我">联系我</a>
+</p>
 
-## 联系我
+---
 
-微信交流群（扫码入群）：
+## 💡 核心价值：为什么选择本插件？
 
-![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
+### 🏗 独创架构：Bot + Agent 双模融合
+
+传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。
+本插件采用 **双模并行架构**，同时压榨两种模式的极限能力：
+
+*   **Bot 通道 (智能体)**：负责 **实时对话**。提供毫秒级流式响应（打字机效果），零延迟交互。
+*   **Agent 通道 (自建应用)**：负责 **能力兜底**。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。
+
+### 🧩 功能特性全景
 
-## 文件与图片入模（说明）
+#### 1. 🗣 **沉浸式交互 (Immersive Interaction)**
+*   **原生流式 (Stream)**：基于 HTTP 分块传输，拒绝 "转圈等待"，体验如 ChatGPT 网页版般丝滑。
+*   **交互式卡片 (Card)**：支持 Button/Menu 交互回传，可构建审批、查询等复杂业务流 (Agent模式)。
 
-图片/文件 URL 下载内容为加密数据，需使用 `EncodingAESKey` 解密后再解析并入模。
+#### 2. 📎 **全模态支持 (Multi-Modal)**
+*   **发什么都能看**：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
+*   **要什么都能给**：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。
 
-## 测试页截图（文件上传 / 解析）
+#### 3. 📢 **企业级触达 (Enterprise Reach)**
+*   **精准广播**：支持向 **部门 (Party)**、**标签 (Tag)** 或 **外部群** 批量推送消息。
+*   **Cronjob 集成**：通过简单的 JSON 配置实现早报推送、日报提醒、服务器报警。
 
-![WeCom 测试页截图（文件上传 / 解析）](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/01.image.jpg)
+#### 4. 🛡 **生产级稳定 (Production Ready)**
+*   **容灾切换**：Bot 模式 6 分钟超时自动熔断，切换 Agent 私信送达，防止长任务回答丢失。
+*   **Token 自动运维**：内置 AccessToken 守护进程，自动缓存、提前刷新、过期重试。
 
-## A2UI 交互卡片（template_card）
+---
 
-- Agent 输出 `{"template_card": ...}`（JSON）时：单聊且有 `response_url` 会发送交互卡片；群聊或无 `response_url` 自动降级为文本说明（不透出原始 JSON）。
-- 收到 `template_card_event` 时：会转换为伪文本消息触发 Agent，并基于 `msgid` 去重避免重复处理。
-- 卡片相关的示例/skill：可加群获取（见上方交流群二维码）。
+<div align="center">
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/01.image.jpg" width="45%" />
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/02.image.jpg" width="45%" />
+</div>
+
+
+
+## 📊 模式能力对比
+
+| 能力维度 | 🤖 Bot 模式 | 🧩 Agent 模式 | ✨ **本插件 (双模)** |
+|:---|:---:|:---:|:---:|
+| **流式响应** | ✅ 原生支持 | ❌ 不支持 | **✅ 完美支持** |
+| **发送文件/图** | ❌ 不支持 | ✅ 支持 | **✅ 自动切换** |
+| **主动推送** | ❌ 仅回调 | ✅ 随时推送 | **✅ 完整 API** |
+| **Cronjob 定时** | ❌ 仅回调 | ✅ 支持 | **✅ 完美集成** |
+| **接收语音** | ✅ 转文字 | ✅ 语音+文字 | **✅ 双路处理** |
+| **群聊支持** | ✅ @即回 | ⚠️ 仅自建群 | **✅ 混合支持** |
+
+---
+
+## 快速开始
 
-## 安装
+### 1. 安装插件
 
-### 从 npm 安装
 ```bash
 openclaw plugins install @yanhaidao/wecom
 openclaw plugins enable wecom
+```
+
+也可以通过命令行向导快速配置：
+
+```bash
+openclaw config --section channels
+```
+
+### 2. 配置 Bot 模式（智能体）
+
+```bash
+openclaw config set channels.wecom.enabled true
+openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
+openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
+openclaw config set channels.wecom.bot.receiveId ""
+openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
+openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"
+
+# 不配置表示所有人可用，配置则进入白名单模式
+openclaw config set channels.wecom.bot.dm.allowFrom '[]' 
+```
+
+### 3. 配置 Agent 模式（自建应用，可选）
+
+```bash
+openclaw config set channels.wecom.enabled true
+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.agentId 1000001
+openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
+openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
+openclaw config set channels.wecom.agent.welcomeText "欢迎使用智能助手"
+# 不配置表示所有人可用，配置则进入白名单模式
+openclaw config set channels.wecom.agent.dm.allowFrom '[]'
+```
+
+### 4. 高级网络配置 (公网出口代理)
+如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，企业微信 API 会因 IP 变动报错 `60020 not allow to access from your ip`。
+此时需配置一个**固定 IP 的正向代理** (如 Squid)，让插件通过该代理访问企微 API。
+
+```bash
+openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"
+```
+
+### 5. 验证
+
+```bash
 openclaw gateway restart
+openclaw channels status
 ```
 
-## 配置结构参考
+---
 
-```json
+## 配置说明
+
+### 完整配置结构
+
+```jsonc
 {
   "channels": {
     "wecom": {
       "enabled": true,
-      "webhookPath": "/wecom",
-      "token": "YOUR_TOKEN",
-      "encodingAESKey": "YOUR_ENCODING_AES_KEY",
-      "receiveId": "",
-      "streamPlaceholderContent": "正在思考...",
-      "dm": { "policy": "pairing" }
+      
+      // Bot 模式配置（智能体）
+      "bot": {
+        "token": "YOUR_BOT_TOKEN",
+        "encodingAESKey": "YOUR_BOT_AES_KEY",
+        "receiveId": "",                        // 可选，用于解密校验
+        "streamPlaceholderContent": "正在思考...",
+        "welcomeText": "你好！我是 AI 助手",
+        "dm": { "allowFrom": [] }               // 私聊限制
+      },
+      
+      // Agent 模式配置（自建应用）
+      "agent": {
+        "corpId": "YOUR_CORP_ID",
+        "corpSecret": "YOUR_CORP_SECRET",
+        "agentId": 1000001,
+        "token": "YOUR_CALLBACK_TOKEN",         // 企微后台「设置API接收」
+        "encodingAESKey": "YOUR_CALLBACK_AES_KEY",
+        "welcomeText": "欢迎使用智能助手",
+        "dm": { "allowFrom": [] }
+      },
+
+      // 网络配置（可选）
+      "network": {
+        "egressProxyUrl": "http://proxy.company.local:3128"
+      }
     }
   }
 }
 ```
 
-## 接入企业微信
+### Webhook 路径（固定）
 
-### 搭建企微 Bot（API 模式）
+| 模式 | 路径 | 说明 |
+|:---|:---|:---|
+| Bot | `/wecom/bot` | 智能体回调 |
+| Agent | `/wecom/agent` | 自建应用回调 |
 
-1. 登录企业微信管理后台  
-进入「安全与管理」→「管理工具」→「智能机器人」：`https://work.weixin.qq.com/wework_admin/frame#/manageTools`
+### DM 策略
 
-2. 创建机器人（务必选择 API 模式）  
-创建机器人时需要填写回调 URL（公网可访问的 HTTPS 地址），例如：`https://example.com/wecom`
+- **不配置 `dm.allowFrom`** → 所有人可用（默认）
+- **配置 `dm.allowFrom: ["user1", "user2"]`** → 白名单模式，仅列表内用户可私聊
 
-3. 记录机器人配置  
-在机器人详情里找到并保存以下信息，后续会写入 OpenClaw 配置：
-- Token
-- EncodingAESKey
-- ReceiveId（如果你的机器人/回调配置需要校验的话）
+### 常用指令
 
-## 快速开始
+| 指令 | 说明 | 示例 |
+|:---|:---|:---|
+| `/new` | 🆕 开启新会话 (重置上下文) | `/new` 或 `/new GPT-4` |
+| `/reset` | 🔄 重置会话 (同 /new) | `/reset` |
 
-1. 启用插件
-```bash
-openclaw plugins enable wecom
-```
+---
 
-2. 配置企业微信机器人（必需）
-```bash
-openclaw config set channels.wecom.enabled true
-openclaw config set channels.wecom.webhookPath "/wecom"
-openclaw config set channels.wecom.token "YOUR_TOKEN"
-openclaw config set channels.wecom.encodingAESKey "YOUR_ENCODING_AES_KEY"
-openclaw config set channels.wecom.receiveId ""
-```
+## 企业微信接入指南
 
-3. 配置 Gateway（示例）
-```bash
-openclaw config set gateway.mode "local"
-openclaw config set gateway.bind "0.0.0.0"
-openclaw config set gateway.port 18789
-```
+### Bot 模式（智能机器人）
 
-4. 重启 Gateway
-```bash
-openclaw gateway restart
-```
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/manageTools)
+2. 进入「安全与管理」→「管理工具」→「智能机器人」
+3. 创建机器人，选择 **API 模式**
+4. 填写回调 URL：`https://your-domain.com/wecom/bot`
+5. 记录 Token 和 EncodingAESKey
 
-5. 验证
-```bash
-openclaw channels status
+### Agent 模式（自建应用）
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/apps)
+2. 进入「应用管理」→「自建」→ 创建应用
+3. 获取 AgentId、CorpId、Secret
+4. **重要：** 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
+   - 如果你使用内网穿透/动态 IP，建议配置 `channels.wecom.network.egressProxyUrl` 走固定出口代理，否则可能出现：`60020 not allow to access from your ip`
+5. 在应用详情中设置「接收消息 - 设置API接收」
+6. 填写回调 URL：`https://your-domain.com/wecom/agent`
+7. 记录回调 Token 和 EncodingAESKey
+
+<div align="center">
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/03.bot.page.png" width="45%" alt="Bot Config" />
+  <img src="https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/03.agent.page.png" width="45%" alt="Agent Config" />
+</div>
+
+---
+
+## 高级功能
+
+### A2UI 交互卡片
+
+Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
+
+- ✅ 单聊场景：发送真实交互卡片
+- ✅ 按钮点击：触发 `template_card_event` 回调
+- ✅ 自动去重：基于 `msgid` 避免重复处理
+- ⚠️ 群聊降级：自动转为文本描述
+
+
+
+### ⏰ Cronjob 企业级定时推送
+
+本插件深度集成了 OpenClaw 的 Cronjob 调度能力，配合 Agent 强大的广播 API，轻松实现企业级通知服务。
+
+> **核心场景**：早报推送、服务器报警、日报提醒、节日祝福。
+
+#### 1. 目标配置 (Target)
+无需遍历用户列表，直接利用 Agent 强大的组织架构触达能力：
+
+| 目标类型 | 格式示例 | 推送范围 | 典型场景 |
+|:---|:---|:---|:---|
+| **部门 (Party)** | `party:1` (或 `1`) | 📢 **全员广播** | 全员通知、技术部周报 |
+| **标签 (Tag)** | `tag:Ops` | 🎯 **精准分组** | 运维报警、管理层汇报 |
+| **外部群 (Group)** | `group:wr...` | 💬 **群聊推送** | 项目组群日报 (需由Agent建群) |
+| **用户 (User)** | `user:zhangsan` | 👤 **即时私信** | 个人待办提醒 |
+
+#### 2. 配置示例 (`schedule.json`)
+
+只需在工作区根目录创建 `schedule.json` 即可生效：
+
+```json
+{
+  "tasks": [
+    {
+      "cron": "0 9 * * 1-5", // 每周一至周五 早上9:00
+      "action": "reply.send",
+      "params": {
+        "channel": "wecom",
+        "to": "party:1",      // 一键发送给根部门所有人！
+        "text": "🌞 早安！请查收[今日行业简报](https://example.com/daily)。"
+      }
+    },
+    {
+      "cron": "0 18 * * 5",
+      "action": "reply.send",
+      "params": {
+        "channel": "wecom",
+        "to": "tag:Ops",       // 仅发送给运维组
+        "text": "🔒 周五封网提醒：请检查服务器状态。"
+      }
+    }
+  ]
+}
 ```
 
-## 说明
 
-- webhook 必须是公网 HTTPS。出于安全考虑，建议只对外暴露 `/wecom` 路径。
-- stream 模式：第一次回包可能是占位符；随后 WeCom 会以 `msgtype=stream` 回调刷新拉取完整内容。
-- 限制：仅支持被动回复，不支持脱离回调的主动发送。
 
+---
+
+## 📖 详细行为说明 (Behavior Detail)
+
+### 1. 企业微信群聊交付规则
+
+*   **默认 (Bot 回复)**：群聊里 @Bot，默认由 Bot 在群内直接回复（优先文本/图片/Markdown）。
+*   **例外 (文件兜底)**：如果回复内容包含**非图片文件**（如 PDF/Word/表格/压缩包等），由于企微 Bot 接口不支持，插件会自动：
+    1.  Bot 在群里提示："由于格式限制，文件将通过私信发送给您"。
+    2.  无缝切换到 **自建应用 (Agent)** 通道，将文件私信发送给触发者。
+*   **提示**：若未配置 Agent，Bot 会明确提示“需要管理员配置自建应用通道”。
+
+### 2. 长任务可靠性保障
+
+*   **超时熔断**：企业微信限制 Bot 流式回复窗口约为 6 分钟。
+*   **自动接力**：当对话时长接近此阈值时，Monitor 会自动截断 Bot 流，提示 "剩余内容将私信发送"，并立即启动 Agent 通道私信发送完整结果。这彻底解决了长思考任务（如深度推理、代码生成）因超时导致用户收不到结果的问题。
+
+### 3. 主动发送安全机制
+
+*   **群发保护**：Agent 主动发送接口不再尝试向普通群 `chatid` (wr/wc...) 发消息（该路径常因权限与归属产生的隐蔽错误）。
+*   **引导提示**：系统会明确拦截并通过日志提示中文错误："请使用 Bot 群内交付或改为私信目标（userid/部门/标签）"，帮助管理员快速排查配置。
+
+### 4. 管理员友好
+
+*   所有兜底逻辑（Fallback）触发时，如果因配置缺失导致失败，Bot 都会给出清晰的**中文提示**，而不是沉默或报代码错误，极大降低了排查难度。
+
+---
+
+## 🙋 社区问答 (FAQ)
+
+针对社区反馈的高频问题，我们已在 v2.2.4 版本中全部解决：
+
+**Q1: 同时使用 Bot 和 Agent 会导致消息重复吗？**
+> **A:** 不会。本插件采用“Bot 优先”策略。用户在哪个通道发消息，就从哪个通道回。只有在 Bot 无法处理（如发文件）时才会智能切换到 Agent 通道作为补充。
+
+**Q2: 使用内网穿透时，企业微信报错 60020 (IP 不白名单) 怎么办？**
+> **A:** 新增了 `config.network.egressProxyUrl` 配置。您可以配置一个拥有固定公网 IP 的代理服务器（如 Squid），让插件通过该代理与企微 API 通信，从而绕过动态 IP 限制。
+
+**Q3: 原生 Bot 模式支持图片，为什么 Agent 模式不行？**
+> **A:** Agent 模式之前确实存在此短板。但在 v2.2.4 中，我们完整实现了 Agent 端的 XML 媒体解析与 `media_id` 下载逻辑，现在 Agent 模式也能完美看图、听语音了。
+
+**Q4: 群里 @机器人 发送文件失败？**
+> **A:** 因为企业微信 Bot 接口本身不支持发送非图片文件。我们的解决方案是：自动检测到文件发送需求后，改为通过 Agent 私信该用户发送文件，并在群里给出 "文件已私信发给您" 的提示。
+
+**Q5: Cronjob 定时任务怎么发给群？**
+> **A:** Cronjob 必须走 Agent 通道（Bot 无法主动发消息）。您只需在配置中指定 `to: "party:1"` (部门) 或 `to: "group:wr123..."` (外部群)，即可实现定时推送到群。
+
+---
+
+## 联系我
+
+微信交流群（扫码入群）：
+
+![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
+
+维护者：YanHaidao（VX：YanHaidao）
+
+---
+
+## 更新日志
+
+### 2026.2.4
+
+- 🚀 **架构升级**：实施 "Bot 优先 + Agent 兜底" 策略，兼顾流式体验与长任务稳定性（6分钟切换）。
+- ✨ **全模态支持**：Agent 模式完整支持接收与发送图片、文件、语音、视频。
+- ✨ **Cronjob 增强**：支持向部门 (`party:ID`) 和标签 (`tag:ID`) 广播消息。
+- 🛠 **Monitor 重构**：统一的消息防抖与流状态管理，提升并发稳定性。
+- 🐞 **修复**：Outbound ID 解析逻辑及 API 客户端参数缺失问题。
+
+### 2026.2.3
 
+- 🎉 **重大更新**：新增 Agent 模式（自建应用）支持
+- ✨ 双模式并行：Bot + Agent 可同时运行
+- ✨ **多模态支持**：Agent 模式支持图片/语音/文件/视频的接收与自动下载
+- ✨ AccessToken 自动管理：缓存 + 智能刷新
+- ✨ Agent 主动推送：脱离回调限制
+- ✨ XML 加解密：完整 Agent 回调支持
+- 📁 代码重构：模块化解耦设计
 
-# 更新日志
+### 2026.1.31
 
-## 2026.1.31
+- 文档：补充入模与测试截图说明
+- 新增文件支持
+- 新增卡片支持
 
-- 文档：补充入模与测试截图说明。
-- 新增 文件支持
-- 新增 卡片支持
-## 2026.1.30
+### 2026.1.30
 
-- 项目更名：Clawdbot → OpenClaw（CLI：`clawdbot` → `openclaw`）。
+- 项目更名：Clawdbot → OpenClaw

package/index.ts

@@ -13,6 +13,14 @@ const plugin = {
   name: "WeCom",
   description: "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   configSchema: emptyPluginConfigSchema(),
+  /**
+   * **register (注册插件)**
+   * 
+   * OpenClaw 插件入口点。
+   * 1. 注入 Runtime 环境 (api.runtime)。
+   * 2. 注册 WeCom 渠道插件 (ChannelPlugin)。
+   * 3. 注册 Webhook HTTP 处理器 (handleWecomWebhookRequest)。
+   */
   register(api: OpenClawPluginApi) {
     setWecomRuntime(api.runtime);
     api.registerChannel({ plugin: wecomPlugin });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.0.2",
+  "version": "2.2.4",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "author": "YanHaidao (VX: YanHaidao)",
@@ -32,10 +32,15 @@
     }
   },
   "dependencies": {
-    "axios": "^1.13.4",
+    "fast-xml-parser": "5.3.4",
+    "undici": "^7.20.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "openclaw": ">=2026.1.26"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "typescript": "^5.9.3"
   }
 }