@dingxiang-me/openclaw-wechat 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-03-14
+
+### Added
+- 新增 `dm.mode=pairing`，首次私聊可接入 OpenClaw 原生配对审批流，不再只能依赖静态 `allowFrom`
+- 新增 WeCom 渠道 pairing metadata，支持 `quickstartAllowFrom`、`wecomUserId` 归一化以及审批通过后的默认通知回执
+- `wecom:selfcheck`、`wecom:agent:selfcheck`、`wecom:bot:selfcheck` 新增接入摘要，直接输出 `readiness` 与 `routing`
+
+### Changed
+- WeCom 渠道 metadata 补齐 `detailLabel`、`systemImage` 与 quickstart 提示，接入路径更贴近 OpenClaw 原生渠道
+- `/status` 输出优先展示“收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档”准备情况，并显式展示 `bindings` / `dynamicAgent` 路由来源
+- WeCom Bot 长连接正常连接日志默认降到 `debug`，减少 `connect/opened/subscribed` 噪音
+- README（中英文）改成 `2.1.0` 接入口径，补充 `pairing`、selfcheck 摘要和推荐接入顺序
+
+## [2.0.1] - 2026-03-14
+
+### Fixed
+- 修复 WeCom Agent 回复 `/workspace/...` 文件路径时因动态会话工作区缺少目标文件，最终只回显路径文本而不实际发送图片/文件的问题
+- 修复 WeCom Bot 长连接对附件回调 payload 形态兼容不足，导致 PDF/文件消息被当成普通文本继续处理的问题；补充 `msg_type`、嵌套 `message`、`attachments/items`、`file_url/download_url/file_name/aes_key` 等兼容解析
+- 修复 WeCom Bot 入站文件/图片处理未完整透传媒体级 AES Key 的问题，降低 PDF/图片解密失败和内容损坏风险
+- 修复本地 `whisper-cli` 转写时临时音频文件在子进程真正读取前被提前清理，导致语音识别报错 `input file not found`
+- 补充 WeCom Bot 长连接未解析 callback 的运行日志，便于继续定位企业微信新回调形态
+
 ## [2.0.0] - 2026-03-13
 
 ### Changed

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 
 ## Table of Contents
 
-- [Major Update (v2.0.0)](#major-update-v200)
+- [Onboarding Update (v2.1.0)](#onboarding-update-v210)
 - [Highlights](#highlights)
 - [Mode Comparison](#mode-comparison)
 - [5-Minute Quick Start](#5-minute-quick-start)
@@ -28,41 +28,27 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 - [Development](#development)
 - [FAQ](#faq)
 
-## Major Update (v2.0.0)
+## Onboarding Update (v2.1.0)
 
-This is a real capability update, not a minor patch.  
-`OpenClaw-Wechat` now has **working WeCom Bot long-connection support** in real gateway runtime.
+This release focuses on setup quality, not feature sprawl. The goal is to make `OpenClaw-Wechat` behave more like a native OpenClaw channel during install and first-run.
 
-### WeCom Bot long connection
+### What changed
 
 | Item | Result |
 |---|---|
-| Official endpoint | `wss://openws.work.weixin.qq.com` |
-| Inbound commands | `aibot_msg_callback` / `aibot_event_callback` |
-| Outbound command | `aibot_respond_msg` |
-| Runtime | switched to `ws`, no longer blocked by built-in Node WebSocket `1006` failures |
-| Public Bot callback required | no, not in long-connection mode |
-| Verification command | `npm run wecom:bot:longconn:probe -- --json` |
-
-### Control UI and operations
-
-This release also keeps the earlier operations improvements: **WeCom supports visual configuration in Control UI**, so you no longer need to rely on manual JSON edits only.
-
-### Visual config in Control UI
-
-| Item | Status | Notes |
-|---|---|---|
-| WeCom config form | ✅ | `channels.wecom` can be edited/saved directly from UI |
-| Localized labels | ✅ | Common fields are now clearly labeled in Chinese for ops teams |
-| Sensitive-field hints | ✅ | secret/token/aesKey fields are marked as sensitive |
-| Runtime status clarity | ✅ | `Connected` is no longer stuck at `n/a`; default account display name is localized |
-| Inbound activity tracking | ✅ | `Last inbound` is updated after webhook callbacks (`n/a` before first inbound after restart is expected) |
+| DM pairing approval | Added `dm.mode=pairing`, backed by OpenClaw native pairing flow |
+| Quickstart metadata | Added `detailLabel`, `systemImage`, and `quickstartAllowFrom` |
+| `/status` readability | Status now leads with `receive / reply / send / media / voice / doc` readiness |
+| Selfcheck summaries | `wecom:selfcheck`, `wecom:agent:selfcheck`, and `wecom:bot:selfcheck` now print `readiness` and `routing` summaries |
+| Route visibility | Status and selfcheck now show whether routing comes from `bindings` or `dynamicAgent` |
+| Long-connection log noise | Normal connect / opened / subscribed logs moved to `debug` |
 
 ### Practical impact
 
-- Configure WeCom directly in `Channels -> WeCom` without hand-editing large config files.
-- Better readability for day-to-day ops and handover.
-- More accurate runtime status display reduces false alarm on “plugin not working”.
+- New users can start from the smallest working config, then add multi-account or dynamic routing later.
+- Teams that want controlled DM access can now use `pairing` instead of maintaining `allowFrom` only.
+- `/status` and selfcheck answer “can it receive, reply, and send?” before lower-level transport details.
+- Bot long-connection is quieter by default while still keeping useful warnings and errors.
 
 ## Highlights
 
@@ -75,7 +61,7 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 | Bot card replies | ✅ | `markdown/template_card` with automatic text fallback |
 | Multi-account support | ✅ | `channels.wecom.accounts.<id>` |
 | Sender allowlist and admin bypass | ✅ | `allowFrom` + `adminUsers` |
-| Direct-message policy | ✅ | `dm.mode=open/allowlist/deny` + account overrides |
+| Direct-message policy | ✅ | `dm.mode=open/allowlist/pairing/deny` + account overrides |
 | Event welcome reply (`enter_agent`) | ✅ | configurable via `events.enterAgentWelcome*` |
 | Command allowlist | ✅ | `/help`, `/status`, `/clear`, `/new`, etc. |
 | Group trigger policy | ✅ | mention-required or direct-trigger |
@@ -103,7 +89,7 @@ This release also keeps the earlier operations improvements: **WeCom supports vi
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-Recommended minimum package version: `2.0.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
+Recommended minimum package version: `2.1.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
 
 For local development or direct source-path loading, use:
 
@@ -159,6 +145,20 @@ If you are loading from source path instead, use the version below with `load.pa
 
 > Agent-mode note (important): configure **Trusted IP** in the WeCom self-built app settings and include the real egress IP of your OpenClaw gateway. Otherwise you may see "messages received but no reply".
 
+If you want first-contact DM approval, add:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dm": {
+        "mode": "pairing"
+      }
+    }
+  }
+}
+```
+
 ### 4) Restart and verify
 
 ```bash
@@ -169,6 +169,11 @@ npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
+Selfcheck now starts with two summary lines:
+
+- `readiness`: whether receive / reply / send are currently usable
+- `routing`: whether `bindings` and `dynamicAgent` are active
+
 ## Requirements
 
 | Item | Description |
@@ -310,7 +315,7 @@ When multi-account is enabled, each account can override Bot callback credential
 | Sender ACL | `allowFrom`, `allowFromRejectMessage` |
 | Command ACL | `commands.enabled`, `commands.allowlist`, `commands.rejectMessage` |
 | Admin bypass | `adminUsers` |
-| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` |
+| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` (`open / allowlist / pairing / deny`) |
 | Event policy | `events.enabled`, `events.enterAgentWelcomeEnabled`, `events.enterAgentWelcomeText` |
 | Group trigger | `groupChat.enabled`, `groupChat.triggerMode`, `groupChat.mentionPatterns`, `groupChat.triggerKeywords` |
 | Dynamic route | `dynamicAgent.*` (compatible with `dynamicAgents.*`, `dm.createAgentOnFirstMessage`) |
@@ -433,7 +438,7 @@ Outbound target formats:
 |---|---|
 | `WECOM_ALLOW_FROM*` | sender authorization |
 | `WECOM_COMMANDS_*` | command ACL |
-| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist |
+| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist / pairing controls |
 | `WECOM_EVENTS_*`, `WECOM_<ACCOUNT>_EVENTS_*` | event handling + enter_agent welcome text |
 | `WECOM_GROUP_CHAT_*` | group trigger policy |
 | `WECOM_DEBOUNCE_*` | text debounce |

package/README.md

@@ -12,7 +12,7 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 
 ## 目录
 
-- [重大更新（v2.0.0）](#重大更新v200)
+- [接入更新（v2.1.0）](#接入更新v210)
 - [功能概览](#功能概览)
 - [模式对比](#模式对比)
 - [5 分钟极速上手](#5-分钟极速上手)
@@ -33,75 +33,42 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 - [FAQ](#faq)
 - [版本与贡献](#版本与贡献)
 
-## 重大更新（v2.0.0）
+## 接入更新（v2.1.0）
 
-这次是一次真正的能力级更新，不是小修补。  
-`OpenClaw-Wechat` 现在已经把 **企业微信智能机器人长连接** 正式做成可用能力，并且已经在真实网关环境下完成：
+这版不是继续堆新平台能力，而是把接入体验收口到“更像 OpenClaw 原生渠道”的状态。
 
-- WebSocket 握手成功
-- `aibot_subscribe` 鉴权成功
-- 心跳 `ping` / 回执成功
-- 网关日志出现 `socket opened` 和 `subscribed`
-
-### 企业微信 Bot 长连接已正式可用
+### 这版新增了什么
 
 | 项目 | 结果 |
 |---|---|
-| 官方地址 | `wss://openws.work.weixin.qq.com` |
-| 入站命令 | `aibot_msg_callback` / `aibot_event_callback` |
-| 出站命令 | `aibot_respond_msg` |
-| 运行时实现 | 已切换为 `ws`，不再使用会导致 `1006` 的 Node 内置 WebSocket |
-| Bot 回调公网依赖 | 长连接模式下不需要 |
-| 自检命令 | `npm run wecom:bot:longconn:probe -- --json` |
-
-这次版本同时还保留并增强了原有的 **WeCom Doc 工具链**。  
-现在 `OpenClaw-Wechat` 已经同时具备：
-
-- 后台可视化配置
-- WeCom Doc 文档/表格/收集表工具
-- 文档权限与协作者管理
-- 分享链接可用性诊断
-- 文档权限打不开问题的直接诊断
-- 链接文本输出完整性修复（URL 下划线不再丢失）
-
-### 这次版本解决了什么
-
-| 场景 | 旧问题 | 现在的处理方式 |
-|---|---|---|
-| 企业微信 Bot 长连接 | 旧版地址、命令字和运行时实现不对，连接阶段直接 `1006` | 已对齐官方地址、协议命令和 `ws` 实现，真实网关已订阅成功 |
-| 想验证“到底连上没有” | 只能看零散日志，难以区分握手、鉴权还是心跳失败 | `wecom:bot:longconn:probe` 会直接验证握手、鉴权与心跳 |
-| 创建文档后自己打不开 | 文档创建成功，但发起人没被自动授权 | `create` 默认自动把当前企微请求人加入协作者 |
-| 分享链接能发出来，但别人打开像“文档不存在” | 无法快速判断是权限、分享码还是 guest 访问问题 | `validate_share_link` 直接诊断 `guest / blankpage / scode / 路径资源 ID` |
-| 只知道“更新成员权限成功”，但还是打不开 | 成员权限、查看规则、外部分享是三套概念，容易混淆 | `diagnose_auth` 直接输出企业内/企业外访问、查看成员、协作者与请求人角色 |
-| 把分享链接路径当成 `docId` 使用 | 后续 API 调用报 `invalid docid` | `create/share/get_auth` 结果显式返回真实 `docId`，并给出使用提示 |
-| 链接里有下划线，发出去后被改坏 | Markdown 清洗误伤 URL | 文本格式化已修复，URL 下划线完整保留 |
-
-### 可视化配置能力（Control UI）
-
-| 项目 | 现状 | 说明 |
-|---|---|---|
-| WeCom 配置表单 | ✅ | `channels.wecom` 支持在后台页面直接编辑与保存 |
-| 中文字段标签 | ✅ | 常用字段（如 `corpId`、`callbackToken`、`accounts.*`）均已中文化 |
-| 敏感项标记 | ✅ | `secret/token/aesKey` 字段按敏感项展示 |
-| 状态展示 | ✅ | `Connected` 不再长期 `n/a`，默认账号显示名中文化为“默认账号” |
-| 入站状态追踪 | ✅ | 收到回调后自动更新 `Last inbound`（重启后首次入站前为 `n/a` 属正常） |
-| 文档工具开关 | ✅ | `tools.doc` 等文档相关配置可被 schema 正确识别 |
-
-### 文档工具升级摘要
-
-| 能力层 | 新增内容 |
-|---|---|
-| 文档基础 | `create`、`rename`、`get_info`、`share`、`delete` |
-| 权限管理 | `grant_access`、`add_collaborators`、`set_join_rule`、`set_member_auth`、`set_safety_setting` |
-| 运维诊断 | `get_auth`、`diagnose_auth`、`validate_share_link` |
-| 表格/收集表 | `get_sheet_properties`、`create_collect`、`modify_collect`、`get_form_info`、`get_form_answer`、`get_form_statistic` |
-
-### 你升级后能直接获得的变化
-
-- 在 OpenClaw 后台的 `Channels -> WeCom` 页面可直接配置并保存核心参数。
-- 在同一个插件里直接调用 `wecom_doc`，不需要额外安装第二个 WeCom Doc 插件。
-- 现在排查“为什么这个链接打不开”不需要再手翻日志和原始 JSON，工具会直接给出结论。
-- 文档创建、协作者授权、分享链接诊断已经形成闭环，适合直接上线给真实企微用户使用。
+| 私聊配对审批 | 新增 `dm.mode=pairing`，首次私聊会生成 OpenClaw 原生配对审批 |
+| Quickstart 元信息 | 渠道 metadata 补齐 `detailLabel`、`systemImage`、`quickstartAllowFrom` |
+| `/status` 可读性 | 优先展示 `收消息 / 回消息 / 主动发送 / 媒体 / 语音 / 文档` 准备情况 |
+| Selfcheck 摘要 | `wecom:selfcheck` / `wecom:agent:selfcheck` / `wecom:bot:selfcheck` 新增 `readiness` 与 `routing` 摘要 |
+| 路由可见性 | 明确显示当前是否命中 `bindings` 或 `dynamicAgent` |
+| 长连接日志降噪 | 正常的 connect / opened / subscribed 改为 `debug`，减少默认噪音 |
+
+### 这版对接入有什么实际影响
+
+- 新用户现在可以按最小配置先跑通，再决定是否启用多账号、动态路由和文档工具。
+- 需要私聊审批时，不再只能靠手写 `allowFrom`，可以直接用 `pairing` 模式接到 OpenClaw 审批流。
+- `/status` 和 selfcheck 先回答“能不能收、能不能回、能不能发”，再展开工程细节。
+- Bot 长连接默认日志更安静，排障时再开 `debug` 看正常心跳和订阅细节。
+
+### 当前推荐的接入顺序
+
+1. 先选一个主入口：
+   - Bot 长连接：适合最快跑通对话
+   - Agent：适合需要主动发送、菜单、自建应用能力
+2. 再决定私聊准入：
+   - `open`：直接可聊
+   - `allowlist`：仅显式白名单
+   - `pairing`：首次私聊先审批
+3. 最后再加增强项：
+   - `bindings`
+   - `dynamicAgent`
+   - `wecom_doc`
+   - 本地语音转写
 
 ## 5 分钟极速上手
 
@@ -113,7 +80,7 @@ OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两
 openclaw plugins install @dingxiang-me/openclaw-wechat
 ```
 
-> 最低建议版本：`2.0.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据。
+> 最低建议版本：`2.1.0`。如果 `openclaw.json` 里的 `plugins.installs.openclaw-wechat` 仍显示 `1.7.x`，请先升级或重装；旧包不会正确注册 `wecom` channel 元数据。
 
 如果你是在本地开发或要直接跑仓库源码，再用下面这套：
 
@@ -170,6 +137,20 @@ npm install
 
 > Agent 模式补充（重要）：在企业微信自建应用后台请配置**可信 IP**，把 OpenClaw 网关实际出网 IP 加入白名单。否则可能出现“能收到消息但不回复”。
 
+如果你希望私聊先审批，再开放会话，可以直接加：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dm": {
+        "mode": "pairing"
+      }
+    }
+  }
+}
+```
+
 ### Step 4. 重启并自检
 
 ```bash
@@ -180,6 +161,11 @@ npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
+现在自检输出会先给出两行摘要：
+
+- `readiness`: 当前是否能收、能回、能发
+- `routing`: 当前是否启用 `bindings` 和 `dynamicAgent`
+
 ### Step 5. 发一条消息验证
 
 | 验证项 | 预期结果 |
@@ -201,7 +187,7 @@ npm run wecom:bot:selfcheck -- --all-accounts
 | Bot 卡片回包 | ✅ | 支持 `markdown/template_card`，失败自动降级文本 |
 | 多账户 | ✅ | `channels.wecom.accounts.<id>` |
 | 发送者授权控制 | ✅ | `allowFrom` + 账户级覆盖 |
-| 私聊策略（DM） | ✅ | `dm.mode=open/allowlist/deny` + 账户级覆盖 |
+| 私聊策略（DM） | ✅ | `dm.mode=open/allowlist/pairing/deny` + 账户级覆盖 |
 | 事件欢迎语（enter_agent） | ✅ | `events.enterAgentWelcome*` 可配置 |
 | 命令白名单 | ✅ | `/help` `/status` `/clear` `/new` 等 |
 | 群聊触发策略 | ✅ | 支持 `direct/mention/keyword` 三种模式 |
@@ -662,7 +648,7 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 拒绝文案 | `allowFromRejectMessage` | 未授权提示 |
 | 管理员 | `adminUsers` | 绕过命令白名单 |
 | 命令白名单 | `commands.enabled` + `commands.allowlist` | 限制 `/` 指令 |
-| 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/拒绝 |
+| 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/配对审批/拒绝 |
 | 事件策略 | `events.enabled` + `events.enterAgentWelcomeEnabled` + `events.enterAgentWelcomeText` | 控制事件处理与 enter_agent 欢迎语 |
 | 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件（自建应用支持 `direct/mention/keyword`；Bot 模式按平台限制固定 `mention`） |
 | 动态路由 | `dynamicAgent.*`（兼容 `dynamicAgents.*`、`dm.createAgentOnFirstMessage`） | 动态 Agent + workspace bootstrap 播种 |

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-wechat",
   "name": "OpenClaw-Wechat",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "channels": [
     "wecom"
@@ -672,10 +672,11 @@
             "enum": [
               "open",
               "allowlist",
+              "pairing",
               "deny"
             ],
             "default": "open",
-            "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+            "description": "私聊策略：open=开放，allowlist=白名单，pairing=首次私聊需审批，deny=关闭"
           },
           "rejectMessage": {
             "type": "string",
@@ -688,7 +689,7 @@
           },
           "allowFrom": {
             "type": "array",
-            "description": "私聊白名单（mode=allowlist 时生效）",
+            "description": "私聊白名单（mode=allowlist/pairing 时作为显式放行名单）",
             "items": {
               "type": "string",
               "minLength": 1
@@ -1194,14 +1195,15 @@
                   "enum": [
                     "open",
                     "allowlist",
+                    "pairing",
                     "deny"
                   ],
                   "default": "open",
-                  "description": "私聊策略：open=开放，allowlist=白名单，deny=关闭"
+                  "description": "私聊策略：open=开放，allowlist=白名单，pairing=首次私聊需审批，deny=关闭"
                 },
                 "allowFrom": {
                   "type": "array",
-                  "description": "私聊白名单（mode=allowlist 时生效）",
+                  "description": "私聊白名单（mode=allowlist/pairing 时作为显式放行名单）",
                   "items": {
                     "type": "string",
                     "minLength": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingxiang-me/openclaw-wechat",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "license": "MIT",
@@ -24,10 +24,13 @@
       "id": "wecom",
       "label": "企业微信 WeCom",
       "selectionLabel": "企业微信 WeCom（自建应用/Bot）",
+      "detailLabel": "企业微信自建应用 / Bot",
       "docsPath": "/channels/wecom",
       "docsLabel": "wecom",
       "blurb": "企业微信消息通道（自建应用回调 + Bot 回调 + 发送 API）。",
       "order": 80,
+      "systemImage": "building.2.crop.circle",
+      "quickstartAllowFrom": true,
       "aliases": [
         "wework",
         "qiwei",

package/src/core.js

@@ -55,7 +55,7 @@ const BOT_CARD_MODE_SET = new Set(["markdown", "template_card"]);
 const DELIVERY_FALLBACK_LAYER_SET = new Set(DEFAULT_DELIVERY_FALLBACK_ORDER);
 const DYNAMIC_AGENT_MAP_SPLITTER = /[,\n]/;
 const GROUP_CHAT_TRIGGER_MODE_SET = new Set(["direct", "mention", "keyword"]);
-const DM_POLICY_MODE_SET = new Set(["open", "allowlist", "deny"]);
+const DM_POLICY_MODE_SET = new Set(["open", "allowlist", "pairing", "deny"]);
 const DYNAMIC_AGENT_MODE_SET = new Set(["mapping", "deterministic", "hybrid"]);
 const DYNAMIC_AGENT_ID_STRATEGY_SET = new Set(["readable-hash"]);
 const LEGACY_INLINE_ACCOUNT_RESERVED_KEYS = new Set([
@@ -582,6 +582,7 @@ function normalizeWecomDmPolicyMode(value, fallback = "open") {
     .toLowerCase();
   if (!normalized) return fallback;
   if (normalized === "closed" || normalized === "close") return "deny";
+  if (normalized === "disabled") return "deny";
   if (normalized === "whitelist") return "allowlist";
   if (DM_POLICY_MODE_SET.has(normalized)) return normalized;
   return fallback;
@@ -836,9 +837,16 @@ export function resolveWecomDmPolicyConfig({
     channelDmConfig.rejectMessage,
     channelDmConfig.blockMessage,
     readDmRejectMessageEnv(envVars, processEnv, accountId),
-    mode === "deny" ? "当前渠道私聊已关闭，请联系管理员。" : "当前私聊账号未授权，请联系管理员。",
-  );
-  const effectiveMode = mode === "allowlist" && allowFrom.length === 0 ? "deny" : mode;
+    mode === "deny"
+      ? "当前渠道私聊已关闭，请联系管理员。"
+      : mode === "pairing"
+        ? "当前私聊需先完成配对审批。"
+        : "当前私聊账号未授权，请联系管理员。",
+  );
+  const effectiveMode =
+    mode === "allowlist" && allowFrom.length === 0
+      ? "deny"
+      : mode;
   return {
     mode: effectiveMode,
     allowFrom,

package/src/wecom/agent-inbound-guards.js

@@ -1,3 +1,8 @@
+import {
+  issueWecomPairingChallenge,
+  resolveWecomDirectMessageAccess,
+} from "./pairing.js";
+
 function assertFunction(name, value) {
   if (typeof value !== "function") {
     throw new Error(`agent-inbound-guards: ${name} is required`);
@@ -61,28 +66,46 @@ export async function applyWecomAgentInboundGuards({
 
   const commandPolicy = resolveWecomCommandPolicy(api);
   const isAdminUser = commandPolicy.adminUsers.includes(normalizedFromUser);
-  const dmPolicy = resolveWecomDmPolicy(api, config?.accountId || accountId || "default", config);
+  const resolvedAccountId = config?.accountId || accountId || "default";
+  const dmPolicy = resolveWecomDmPolicy(api, resolvedAccountId, config);
+  const allowFromPolicy = resolveWecomAllowFromPolicy(api, resolvedAccountId, config);
+
   if (!isGroupChat) {
-    if (dmPolicy.mode === "deny") {
-      await sendTextToUser(dmPolicy.rejectMessage || "当前渠道私聊已关闭，请联系管理员。");
-      return { ok: false, commandBody: nextCommandBody, isAdminUser };
-    }
-    if (dmPolicy.mode === "allowlist") {
-      const dmSenderAllowed = isAdminUser || isWecomSenderAllowed({
-        senderId: normalizedFromUser,
-        allowFrom: dmPolicy.allowFrom,
+    const dmAccess = await resolveWecomDirectMessageAccess({
+      api,
+      accountId: resolvedAccountId,
+      dmPolicy,
+      allowFromPolicy,
+      normalizedFromUser,
+      isAdminUser,
+      isWecomSenderAllowed,
+    });
+    if (dmAccess.decision === "pairing") {
+      const pairing = await issueWecomPairingChallenge({
+        api,
+        accountId: resolvedAccountId,
+        fromUser,
+        normalizedFromUser,
+        sendPairingReply: sendTextToUser,
       });
-      if (!dmSenderAllowed) {
-        await sendTextToUser(dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。");
-        return { ok: false, commandBody: nextCommandBody, isAdminUser };
+      if (!pairing.created && pairing.unsupported) {
+        await sendTextToUser(dmPolicy.rejectMessage || "当前私聊需先完成配对审批。");
       }
+      return { ok: false, commandBody: nextCommandBody, isAdminUser };
+    }
+    if (dmAccess.decision !== "allow") {
+      await sendTextToUser(dmAccess.rejectText || dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。");
+      return { ok: false, commandBody: nextCommandBody, isAdminUser };
     }
   }
-  const allowFromPolicy = resolveWecomAllowFromPolicy(api, config?.accountId || accountId || "default", config);
-  const senderAllowed = isAdminUser || isWecomSenderAllowed({
-    senderId: normalizedFromUser,
-    allowFrom: allowFromPolicy.allowFrom,
-  });
+
+  const senderAllowed =
+    isAdminUser ||
+    allowFromPolicy.allowFrom.includes("*") ||
+    isWecomSenderAllowed({
+      senderId: normalizedFromUser,
+      allowFrom: allowFromPolicy.allowFrom,
+    });
   if (!senderAllowed) {
     api?.logger?.warn?.(
       `wecom: sender blocked by allowFrom account=${config?.accountId || "default"} user=${normalizedFromUser}`,

package/src/wecom/api-client-send-text.js

@@ -11,6 +11,26 @@ export function createWecomTextSender({
     throw new Error("createWecomTextSender: sendWecomTypedMessage is required");
   }
 
+  const targetSendChains = new Map();
+
+  function buildTargetKey({ corpId, agentId, toUser, toParty, toTag, chatId } = {}) {
+    const accountKey = `${corpId || "corp:unknown"}:${agentId || "agent:unknown"}`;
+    if (chatId) return `${accountKey}:chat:${chatId}`;
+    return `${accountKey}:direct:${[toUser, toParty, toTag].filter(Boolean).join("|") || "unknown"}`;
+  }
+
+  async function enqueueTargetSend(targetKey, task) {
+    const previous = targetSendChains.get(targetKey) || Promise.resolve();
+    const run = previous.catch(() => {}).then(task);
+    const tracked = run.finally(() => {
+      if (targetSendChains.get(targetKey) === tracked) {
+        targetSendChains.delete(targetKey);
+      }
+    });
+    targetSendChains.set(targetKey, tracked);
+    return run;
+  }
+
   async function sendWecomTextSingle({
     corpId,
     corpSecret,
@@ -57,29 +77,32 @@ export function createWecomTextSender({
     logger,
     proxyUrl,
   }) {
-    const chunks = splitWecomText(text);
-    logger?.info?.(`wecom: splitting message into ${chunks.length} chunks, total bytes=${getByteLength(text)}`);
+    const targetKey = buildTargetKey({ corpId, agentId, toUser, toParty, toTag, chatId });
+    return enqueueTargetSend(targetKey, async () => {
+      const chunks = splitWecomText(text);
+      logger?.info?.(`wecom: splitting message into ${chunks.length} chunks, total bytes=${getByteLength(text)}`);
 
-    for (let i = 0; i < chunks.length; i += 1) {
-      logger?.info?.(`wecom: sending chunk ${i + 1}/${chunks.length}, bytes=${getByteLength(chunks[i])}`);
-      // eslint-disable-next-line no-await-in-loop
-      await sendWecomTextSingle({
-        corpId,
-        corpSecret,
-        agentId,
-        toUser,
-        toParty,
-        toTag,
-        chatId,
-        text: chunks[i],
-        logger,
-        proxyUrl,
-      });
-      if (i < chunks.length - 1) {
+      for (let i = 0; i < chunks.length; i += 1) {
+        logger?.info?.(`wecom: sending chunk ${i + 1}/${chunks.length}, bytes=${getByteLength(chunks[i])}`);
         // eslint-disable-next-line no-await-in-loop
-        await sleep(300);
+        await sendWecomTextSingle({
+          corpId,
+          corpSecret,
+          agentId,
+          toUser,
+          toParty,
+          toTag,
+          chatId,
+          text: chunks[i],
+          logger,
+          proxyUrl,
+        });
+        if (i < chunks.length - 1) {
+          // eslint-disable-next-line no-await-in-loop
+          await sleep(300);
+        }
       }
-    }
+    });
   }
 
   return {

package/src/wecom/bot-inbound-content.js

@@ -40,9 +40,11 @@ export function createWecomBotInboundContentBuilder({
     botProxyUrl,
     msgType = "text",
     commandBody = "",
+    normalizedImageEntries = [],
     normalizedImageUrls = [],
     normalizedFileUrl = "",
     normalizedFileName = "",
+    normalizedFileAesKey = "",
     normalizedVoiceUrl = "",
     normalizedVoiceMediaId = "",
     normalizedVoiceContentType = "",
@@ -52,12 +54,17 @@ export function createWecomBotInboundContentBuilder({
     const tempPathsToCleanup = [];
     let messageText = String(commandBody ?? "").trim();
 
-    if (normalizedImageUrls.length > 0) {
+    if (normalizedImageUrls.length > 0 || normalizedImageEntries.length > 0) {
       const fetchedImagePaths = [];
-      const imageUrlsToFetch = normalizedImageUrls.slice(0, 3);
+      const imageEntriesToFetch =
+        Array.isArray(normalizedImageEntries) && normalizedImageEntries.length > 0
+          ? normalizedImageEntries.slice(0, 3)
+          : normalizedImageUrls.slice(0, 3).map((url) => ({ url, aesKey: "" }));
       const tempDir = join(tmpdir(), WECOM_TEMP_DIR_NAME);
       await mkdir(tempDir, { recursive: true });
-      for (const imageUrl of imageUrlsToFetch) {
+      for (const imageEntry of imageEntriesToFetch) {
+        const imageUrl = String(imageEntry?.url ?? "").trim();
+        const imageAesKey = String(imageEntry?.aesKey ?? "").trim();
         try {
           const { buffer, contentType } = await fetchMediaFromUrl(imageUrl, {
             proxyUrl: botProxyUrl,
@@ -73,10 +80,11 @@ export function createWecomBotInboundContentBuilder({
           let effectiveBuffer = buffer;
           let effectiveImageType =
             normalizedType.startsWith("image/") ? normalizedType : detectImageContentTypeFromBuffer(buffer);
-          if (!effectiveImageType && botModeConfig?.encodingAesKey) {
+          const decryptAesKey = imageAesKey || String(botModeConfig?.encodingAesKey ?? "").trim();
+          if (!effectiveImageType && decryptAesKey) {
             try {
               const decryptedBuffer = decryptWecomMediaBuffer({
-                aesKey: botModeConfig.encodingAesKey,
+                aesKey: decryptAesKey,
                 encryptedBuffer: buffer,
               });
               const decryptedImageType = detectImageContentTypeFromBuffer(decryptedBuffer);
@@ -158,7 +166,7 @@ export function createWecomBotInboundContentBuilder({
           });
           const decrypted = smartDecryptWecomFileBuffer({
             buffer: downloaded.buffer,
-            aesKey: botModeConfig?.encodingAesKey,
+            aesKey: normalizedFileAesKey || botModeConfig?.encodingAesKey,
             contentType: downloaded.contentType,
             sourceUrl: downloaded.finalUrl || normalizedFileUrl,
             decryptFn: decryptWecomMediaBuffer,