@yanhaidao/wecom 2.3.150 → 2.3.180

package/README.md

@@ -7,214 +7,211 @@
 
 > [!WARNING]
 > **原创声明**：本项目涉及的“多账号隔离与矩阵路由架构”、“Bot+Agent双模融合架构”、“长任务超时接力逻辑”及“全自动媒体流转接”等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。
-> 欢迎技术交流与合规引用，但**严禁任何不经授权的“功能像素级抄袭”或删除原作者署名的代码搬运行为**。
+> 欢迎技术交流与合规引用，但严禁任何不经授权的“功能像素级抄袭”或删除原作者署名的代码搬运行为。
 
 <p align="center">
   <strong>🚀 企业级多模式 AI 助手接入方案（统一运行时架构）</strong>
 </p>
 
-<p align="center">
-  <strong>🚀 深度适配企业微信原生文档（WeCom Doc）：将对话沉淀为企业数字资产，并补齐写入稳定性 [v2.3.15]</strong>
-</p>
+---
 
-<p align="center">
-  <a href="#sec-1">💡 核心价值</a> •
-  <a href="#sec-2">📊 模式对比</a> •
-  <a href="#sec-changelog">📋 最近更新</a> •
-  <a href="#sec-3">一、快速开始</a> •
-  <a href="#sec-4">二、配置说明</a> •
-  <a href="#sec-5">三、企业微信接入</a> •
-  <a href="#sec-6">四、高级功能</a> •
-  <a href="#sec-7">五、详细行为说明</a> •
-  <a href="#sec-9">六、社区与维护</a>
-</p>
+## 💡 核心价值：为什么团队会真正选择这个插件？
 
----
+企业真正需要的，不是“把一个模型接进企业微信”，而是让企业微信变成一个**能长期工作的 AI 协作入口**。
 
-<a id="sec-1"></a>
-## 💡 核心价值：为什么选择本插件？
+大多数团队最终只关心五件事：
 
-### 🎉 重大特性一览
-1. **防断连黑科技** (v2.3.11 升级)：针对 DeepSeek R1 等长时间 <think> 的推理模型，Bot WS 已升级为 **即时占位 + 持续保活 ACK** 机制。收到用户消息后立即展示 `streamPlaceholderContent`，并在首个真实回复块到来前持续保活，显著降低 WebSocket `invalid req_id` 与消息卡死现象。
-2. **无需域名，极低门槛**：全面支持基于 WebSocket 的长连接（Bot WS）模式接入企业微信机器人，**彻底打通无公网 IP、无备案域名的内网服务器**与企微的实时对话桥梁！
-3. **主动发消息，能力全覆盖**：基于 Agent 模式，全面支持**主动触达**，轻松实现早报定时任务、服务器异常报警、自动每日总结。
-4. **向导自动路由自动适配** (v2.3.10 新增)：在终端执行 `openclaw channels add` 时，若是单企微账号接入，将**静默触发自动 Agent 路由绑定**，丝滑跳过全局冗杂的路由分配步骤。
+- 能不能先低门槛接起来，而不是先做一轮重部署
+- 多人同时使用时，会不会串上下文、串身份、串会话
+- 长任务会不会因为长连接窗口太短而白跑
+- 能不能既有实时对话体验，又能做正式推送和稳定投递
+- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层，而不只是停留在聊天框
 
-### 🔧 全新统一运行时架构 (Unified Runtime)
-插件现已采用全新解耦架构：
-- **`Bot` / `Agent`** 是能力层 (Capability)。
-- **`WS` / `Webhook` / `Callback` / `API`** 是传输层 (Transport)。
-- 同一账号下，Bot 可以在长连接（WS）和主动回调（Webhook）之间通过 `primaryTransport` 自由无缝切换。
-- HTTP Callback 路径一律由系统基于 `accountId` 全自动派生，告别繁乱的手工 URL 配置。
+常见方案通常会很快碰到边界：
 
-### 🎭 独创架构：Bot + Agent 双模融合 (Original Design by YanHaidao)
+- **只用 Bot WS**：接得快、聊得顺，但会受到单连接、心跳保活、会话边界和组织级广播能力的限制
+- **只用 Agent**：能力强、治理清晰，但部署门槛更高，对话体验不如 Bot WS 丝滑
+- **只选单一路径**：团队最后往往被迫在“体验”和“能力”之间二选一
 
-传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。
-本插件采用 **双模并行架构**，同时压榨两种模式的极限能力：
+本插件的价值，就在于把这些原本互相冲突的目标，尽量同时成立。
 
-*   **Bot 通道 (智能体)**：负责 **实时对话**。提供毫秒级流式响应（打字机效果），零延迟交互。
-*   **Agent 通道 (自建应用)**：负责 **能力兜底**。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。
+### 您真正会得到什么？
 
-### 🚀 企业级：多账号（Multi-account）矩阵隔离 (Original Design)
+1. **多人共用一个入口，但上下文不会串**
+   - **问题本质**：企业里真正难的不是“接入一个机器人”，而是让几十上百个人同时使用时，仍然保持每个人的上下文隔离。
+   - **插件做法**：按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。
+   - **用户收益**：同一个企业微信入口可以承接多人并发使用，而不会出现“张三的问题让李四接上回答”的串流灾难。
 
-本插件支持 **无限扩展的账号矩阵**，这是本插件区别于普通插件的核心壁垒：
+2. **长任务不白跑，回复不轻易丢**
+   - **问题本质**：企业微信长连接的响应窗口很短，而推理模型的思考时间往往很长。
+   - **插件做法**：先保活，再流式推进；必要时走备用投递路径，把最终结果交付出去。
+   - **用户收益**：更敢把复杂任务、长文本分析、报告生成交给 AI，而不是每次都担心“算完了却发不回来”。
 
-*   **千人千面 (Dynamic Agents)**：内置自动会话隔离机制，百人同时私聊或群聊自动分摊至专属独立助理，告别上下文串扰。
-*   **账号级隔离 (Isolation)**：不同 `accountId` 之间的收发链路、运行时实例与动态 Agent 默认隔离；若多个账号共用同一个静态 Agent，建议额外配合 `session.dmScope = "per-account-channel-peer"`，避免私聊上下文共用。
-*   **矩阵绑定 (Binding)**：支持一个 OpenClaw 实例同时挂载多个企业/多个应用，通过 `bindings` 灵活分发流量。
-*   **智能路由 (Routing)**：基于入站 `accountId` 自动分拣回复路径，Bot 无法回复时仅回退到**同账号组内**的 Agent，实现闭环的高可用。
+3. **实时对话体验和正式投递能力，不用二选一**
+   - **问题本质**：实时聊天和组织级推送，往往不是同一条技术路径最擅长的事。
+   - **插件做法**：会话内实时交互、流式回复、异步追发优先走 `Bot WS`；组织级广播、冷启动触达、正式通知由 `Agent` 兜底。
+   - **用户收益**：日常使用时体验像聊天助手，正式落地时又有企业应用该有的稳定性和控制力。
 
-### 功能特性全景
+4. **AI 不只会聊天，还能进入企业微信协作层**
+   - **问题本质**：如果 AI 只能回消息，信息最终还是散落在聊天流里，业务并没有真正被推进。
+   - **插件做法**：把企业微信原生协作能力按两条能力平面接入 OpenClaw。
+   - **用户收益**：AI 不仅能回答问题，还能真正参与文档、日程、会议、待办和通讯录相关工作。
 
-#### 🗣 **沉浸式交互 (Immersive Interaction)**
-*   **原生流式 (Stream)**：基于 HTTP 分块传输，拒绝 "转圈等待"，体验如 ChatGPT 网页版般丝滑。
-*   **交互式卡片 (Card)**：支持 Button/Menu 交互回传，可构建审批、查询等复杂业务流 (Agent模式)。
+5. **小团队能低门槛上手，大团队也能正式上线**
+   - **问题本质**：小团队怕折腾，大团队怕失控。
+   - **插件做法**：`Bot WS` 适合快速启用，`Agent` 适合正式治理，两者可以并存。
+   - **用户收益**：您不用在“今天先跑起来”和“将来能不能正规化”之间做破坏性迁移。
 
-#### 📎 **全模态支持 (Multi-Modal)**
-*   **发什么都能看**：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
-*   **要什么都能给**：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。
+---
 
-#### 📝 **深度适配企业微信“协作文档” (WeCom Doc)**
-> *基于“协作的本质是信息流动”第一性原理打造，打破只能聊天的开源怪圈，让 AI 真正握住公司级文档库大权。*
-> *特别感谢 [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案。*
-*   **文档全生命周期**：支持从项目模板自动化创建全新文档、跨越部门重命名/克隆操作。
-*   **表格数据精细手术**：告别全量粗暴覆写，支持基于 Range 选区的单元格级精准更新（如：对特定表格内的状态进行实时覆盖）。
-*   **安全确权与跨界分析**：不仅能读取、分析现有庞大报表数据，更可用指令动态缩放协作成员的读写安全锁钥。
+## 📊 为什么不是只选 Bot，或者只选 Agent？
 
-#### 📢 **企业级触达 (Enterprise Reach)**
-*   **精准广播**：支持向 **部门 (Party)**、**标签 (Tag)** 或 **外部群** 批量推送消息。
-*   **Cronjob 集成**：通过简单的 JSON 配置实现早报推送、日报提醒、服务器报警。
+从用户视角看，差别不在于协议名词，而在于**你要解决的是什么问题**。
 
-#### 🛡 **生产级稳定 (Production Ready)**
-*   **容灾切换**：Bot 模式 6 分钟超时自动熔断，切换 Agent 私信送达，防止长任务回答丢失。
-*   **Token 自动运维**：内置 AccessToken 守护进程，自动缓存、提前刷新、过期重试。
+| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |
+|:---|:---|:---|:---|
+| **先跑起来的速度** | ✅ 快，无需固定公网 IP | ❌ 较重，需要正式应用配置 | ✅ 先用 Bot 起步，后续平滑补 Agent |
+| **实时聊天体验** | ✅ 最强，天然适合低延迟和流式回复 | ⚠️ 能收能发，但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |
+| **异步结果回推** | ✅ 可以，适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot，必要时 Agent 兜底 |
+| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |
+| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |
+| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要“体验”和“能力”的团队 |
+
+> **建议理解方式：**
+> - 如果您最在意的是“先接起来、先用起来、先聊顺”，优先上 `Bot WS`
+> - 如果您最在意的是“正式部署、组织级能力、自动化治理”，补齐 `Agent`
+> - 如果您真正想把 AI 在企业微信里长期用下去，最终往往需要两者并存
 
 ---
 
+## 🧩 企业微信协作能力：为什么这件事比“能聊天”更重要？
 
-<a id="sec-2"></a>
-## 📊 模式能力对比
+很多企业微信 AI 机器人，本质上只是把答案发回聊天框。  
+真正有价值的，是让 AI 进入您**已经在工作的地方**。
 
-| 能力维度 | 🤖 Bot 模式 | 🧩 Agent 模式 | ✨ **本插件 (双模)** |
-|:---|:---|:---|:---|
-| **部署网络要求** | ✅ **无需公网IP/域名 (WS)** | ❌ 必须公网IP/域名回调 | **✅ 全环境适用** |
-| **接收消息 (单聊)** | ✅ 文本/图片/语音/文件 | ✅ 文本/图片/语音/视频/位置/链接 | **✅ 全能互补** (覆盖所有类型) |
-| **接收消息 (群聊)** | ✅ 文本/引用 | ❌ 不支持 (群聊无回调) | **✅ 文本/引用** |
-| **回复消息类型** | ❌ 仅文本/图片/Markdown | ✅ **全模态** (文本/图片/视频/文件等) | **✅ 智能路由** (自动判定切换) |
-| **交互卡片 (A2UI)**| ❌ 不支持 | ✅ **支持** (Button/Select等) | **✅ 支持** |
-| **AI 流式响应** | ✅ **支持** (丝滑打字机) | ❌ 不支持 (全部生成完一次发送) | **✅ 完美支持** |
-| **主动触达 (Cron)**| ❌ 仅被动回复/有限推送 | ✅ **全量推送** (指定人/部门/标签) | **✅ 企业级触达** |
-| **📝 文档/表格管理** | ❌ 不支持 | ⚠️ 需自行开发对接 | **✅ 原生深度适配** (建档/改数据/读表/权限) |
+在本插件里，企业微信的**文档、日程、会议、待办、通讯录**等能力，不再只是外围说明，而是被接成了可以实际调用的协作平面。
 
----
+### 1. Bot WS 协作模式：适合小团队的个人身份入口
 
-<a id="sec-changelog"></a>
+根据企业微信最新开放说明，面向 **5 人及以下的小微企业**，`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。
 
-## 📋 最近更新
+在本插件里，这条链路以 `wecom_mcp` 的方式挂载，只在 **WeCom Bot WS 会话** 中可用：
 
-> 项目保持高频迭代，核心改进一览：
+- 能力入口：`wecom_mcp`
+- 典型能力品类：`doc`、`meeting`、`todo`、`contact`
+- 触发条件：当前会话必须来自 `Bot WS`
+- 更适合的场景：个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景
 
-#### v2.3.150（2026-03-15）
+它的价值在于：
 
-- 🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行，图片会先上传再插入，减少标题正文错位、图片不显示、内容插入到错误位置的问题。
-- 📄 **[重要修复]** 修复 `document.batch_update` 相关的索引与写入稳定性问题，混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时更不容易触发校验报错。
-- 🔧 恢复并补齐企微文档客户端缺失接口，重新覆盖文档、在线表格、智能表格、收集表与权限管理等能力，避免工具调用时缺方法或直接失败。
-- 📊 完善在线表格与收集表的类型定义、参数校验和错误提示，超限或结构不完整的请求会更早被拦截。
-- 💬 **[重要修复]** 修复企业微信群聊回复时 `To` 目标解析错误，群聊、私聊、部门、标签目标现在会按正确前缀解析，减少 `81013 user & party & tag all invalid` 报错。
+- **门槛低**：无需先走完整的自建应用接入流程
+- **身份自然**：更贴近当前聊天用户自己的协作上下文
+- **启动快**：对小团队尤其友好
 
-**升级指引：**
-```bash
-openclaw plugins update wecom
-```
+它的边界也要明确：
 
-#### v2.3.14（2026-03-14）
+- 依赖 `Bot WS` 会话存在
+- 主动推送仍然以**已建立会话**为前提
+- 实际开放范围以企业微信后台可见权限为准
 
-- 📝 **[重磅功能]** 深度适配企业微信原生「协作文档」，支持通过自然语言自动建文档/表格、单元格级精准修改、跨表数据分析与权限管控。Thanks [@proyy](https://github.com/proyy)。
-- 🛑 **[核心修复]** 彻底修复并发场景下"正在思考..."无限刷屏死循环（`errcode=846608`），引入按会话追踪清理机制。
-- 📡 **[合规修复]** `enter_chat` 等事件不再违规调用流式回复接口，终结 `invalid req_id (846605)` 报错。
-- 🛡 WS 长连接增加 120 秒硬性超时熔断，防止极端情况下占位符永不停止。
-- 🤫 Agent 模式 `enter_agent` / `subscribe` 不再触发大模型生成欢迎语，静默处理，零 Token 消耗。
+### 2. Agent 协作模式：适合正式落地的应用身份入口
 
-**升级指引：**
-```bash
-openclaw plugins update wecom
-```
+`Agent` 模式走的是**自建应用 API** 平面，更适合企业级稳定自动化与组织级治理。
+
+在本插件里，当前内置的协作工具主要包括：
+
+- `wecom_doc`：文档、表格、权限、分享可用性诊断等
+- `wecom_calendar`：日历、日程、参与人、回执、默认日历等
+
+它更适合：
+
+- 把协作能力放进正式企业应用权限体系
+- 与定时任务、异步流程、正式投递联动
+- 面向组织对象做更稳定的自动化操作
+
+### 3. 这两条能力链在插件里已经实际接通
 
-#### v2.3.13（2026-03-13）
+当前插件已经把这两条协作链路都注册进来：
 
-- 🛠 **[重要修复]** `Bot WS` 现在会把“引用 + 提问”中的引用内容一起带入 Agent 上下文，不再只保留用户当前这句提问。
-- 🌊 **[重要修复]** `Bot WS` 流式回复改为按“累计全文刷新”发送，修复企业微信客户端里长回答断断续续、像被拆成多段的问题。
-- 🧩 `Bot WS` 这次显式对齐企业微信 `stream.id` 的刷新语义：后续更新会覆盖为当前完整内容，而不是只发送最新增量片段。
-- ✅ 新增 `bot-ws` 引用上下文与累计流式发送回归测试，避免后续重构回退。
+- `wecom_mcp`：仅在 `Bot WS` 会话中暴露
+- `wecom_doc`：仅在 `Agent` 会话中暴露
+- `wecom_calendar`：仅在 `Agent` 会话中暴露
 
-#### v2.3.12（2026-03-12）
+也就是说，您拿到的不是“一个只能聊天的企微插件”，而是：
 
-- 🛠 **[重要修复]** Bot WS 流式回复超 6 分钟后的 `846608 stream message update expired` 现在被识别为终态错误，不再导致进程退出。
-- 🛠 **[重要修复]** SDK 5 秒回执超时 (`Reply ack timeout`) 也被识别为终态错误，超时后立即停止占位保活，不再产生 `unhandledRejection`。
-- 🚀 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）
+### 4. 授权方式
 
-- `Bot WS` 升级为即时占位 + 持续保活，降低长思考时的 `invalid req_id`。
-- `streamPlaceholderContent` 统一作用于 `Bot WS` 与 `Bot Webhook`。
-- onboarding 在空配置下也会提供 `default` 账号选项。
+请按所选平面分别授权：
 
-#### v2.3.10（2026-03-10）
+- **Bot WS 模式授权**：前往企业微信管理后台 👉「工作台 - 智能机器人」，找到对应机器人，点击编辑，在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。
+- **Agent 模式授权**：前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」，将您的自建应用加入“可调用接口的应用”。
 
-- onboarding 默认收敛为 `Bot + WS + 开放私聊`。
-- 修复 `Bot WS` 长文本双重回复问题。
-- Agent 新配置统一使用 `agentSecret`。
+一句话理解：
 
-<details>
-<summary>更早版本</summary>
+- **Bot WS** 更像“当前聊天用户的实时协作入口”
+- **Agent** 更像“企业正式应用身份下的自动化执行入口”
 
-#### v2.3.9（2026-03-09）
+两者同时配置后，您既能拿到顺滑的实时交互，也能拿到企业级可治理的协作能力。
 
-- Bot 默认接入改为 `WebSocket`，无需域名更易上手。
-- 完善中文 onboarding，减少重复提示。
-- 恢复 `Bot WS` 流式输出能力。
-- 增强 Agent 回调与发送日志，排障更直接。
+---
+
+## 📋 最近更新 (Changelog摘要)
+
+> 项目保持高频迭代，全面对齐甚至超越企业真实业务诉求。
+> **为保持精简，以下仅展示近期 3 次重大架构演进，完整历史版本（含全部 `v2.2.x`）请前往 [changelog/ 目录](./changelog/) 查阅。**
 
-</details>
+#### 📌 v2.3.18（2026-03-18）
+- **[重大升级] 双平面能力融合（Bot WS ＋ MCP 强化）** 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时，将官方新开放的企业微信能力暴露给大模型。现在，大模型可凭用户身份读写待办、日程、查通讯录。
+- **[多账号硬隔离]** 彻底重构 MCP 缓存池实现 `accountId + category` 的二次硬维隔离，无论您的矩阵挂载了多少家企业的助手，上下文及鉴权缓存绝不会交叉重叠。
+- **[媒体通道重构]** 补齐 Bot WS 本地的媒体上传链，同时设立了严格的 `5秒熔断机制`，若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。
 
-详细版本记录见 `changelog/` 目录。
+#### 📌 v2.3.16（2026-03-16）
+- **[解析增强] 混合消息媒体正确接管** 🛠 重点修复在 `Bot WS` 通道下，用户如果发了“一张截图 + 一段文字指示”，以前容易丢掉截图或者 AI 只能看到无法查看的腾讯云临时链接。新版底层引擎将自动扫过所有的媒体节点摘取 URL 与解密 AES Key，还大模型一双慧眼。
+
+#### 📌 v2.3.15（2026-03-14）
+- **[原生资产稳定写入]** 📄 深度强化大模型创建企微相关原生存根文档/表格时的写入稳定性。执行 `init_content` 有了更强的前置图片上传清洗能力；极大程度杜绝了混发段落/文本/图片触发的企微官方 `Validator` 异常。
+- **[复杂分发目标解包]** 💬 补齐所有关于企业微信“群聊、部门、标签组”作为 `To` 目标的精确指令解析算法，保障向全公司的组织架构层级呼气 AI 报告不再报出 `81013 target invalid`。
+
+*(查看更早期关于“超时熔断代投、动态扩容矩阵”等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*
 
 ---
 
-<a id="sec-3"></a>
 ## 一、🚀 快速开始
 
 > 推荐统一使用**多账号矩阵模型**。 
-> 即使只有一个账号，也建议写在 `channels.wecom.accounts.default` 节点下。
+> 即使您的企业只接入了一个账号，也强烈建议将其配入 `channels.wecom.accounts.default` 节点下。
 
-### 1.1 安装插件
+### 1.1 插件安装
 
 ```bash
 openclaw plugins install @yanhaidao/wecom
 openclaw plugins enable wecom
 ```
 
-### 1.2 互动向导式配置 (推荐)
+### 1.2 互动向导式初配 (适合个人开发者与极客)
 
-如果你不想手写 JSON 配置文件，可以通过互动式向导完成通道挂载：
+如果您不想手写繁杂的 JSON 配置文件，可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署：
 
-1. 确保已通过 npm 安装该插件：`openclaw plugins install @yanhaidao/wecom`并且启用了 `openclaw plugins enable wecom`
-2. 在终端中，输入以下命令，添加渠道：
-```bash
-openclaw channels add
-```
-3. 在「Select channel」步骤的下拉列表中，找到并选择：**企业微信 (WeCom)**
-4. 按照屏幕终端提示，依次填入企业微信机器人 `Bot ID` 及 `Secret` 等必填项即可。
+1. 确保已启用本插件。
+2. 在终端运行添加渠道指令：
+   ```bash
+   openclaw channels add
+   ```
+3. 选择下拉列表中第一顺位的：**企业微信 (WeCom)**
+4. 根据终端亮色指引，填入企微机器人对应的 `Bot ID` 及 `Secret`，机器人即可完成握手并进入可用状态。
+
+### 1.3 生产环境顶配架构示范（Bot WS 流式交互 + Agent 私有通道兜底发送）
 
-向导完成后，后台服务将自动装载你的配置并尝试建立长连接通信。
+如果您的目标不是“接进来能聊两句”，而是让团队在企业微信里长期稳定使用 AI，这套组合更接近生产环境的推荐形态：
 
-### 1.3 推荐配置结构（Bot + Agent 组合版）
+- `Bot WS` 负责实时对话、低延迟流式回复和更轻的接入门槛
+- `Agent` 负责主动推送、媒体发送和长任务后的兜底交付
+- `dynamicAgents` 负责把不同用户、不同群聊的会话真正隔离开，避免多人共用一个入口时互相串上下文
 
-这是生产环境最推荐的形态（进阶纯手工配置），兼顾了快速流式体验与 Agent 强大的兜底分发能力。如果您是给企业配置多名矩阵助理，或需要启动 Agent 兜底能力和定时推送能力，请进入 OpenClaw 的配置文件直接写入 JSON。以下是生产环境最推荐的综合形态：
+请进入 OpenClaw 配置文件（`openclaw.json`）的 `channels.wecom` 内使用：
 
 ```jsonc
 {
@@ -225,32 +222,27 @@ openclaw channels add
       "accounts": {
         "default": {
           "enabled": true,
-          "name": "默认企微账号",
+          "name": "企微销售二部支持中枢",
           "bot": {
             "primaryTransport": "ws",             // 指定 Bot 主通讯协议：ws 或 webhook
-            "streamPlaceholderContent": "正在思考...",
-            "welcomeText": "你好，我已接入 OpenClaw。",
+            "streamPlaceholderContent": "正在深思熟虑，请稍候...", // 避免流式回复开始前长时间无反馈
+            "welcomeText": "你好，我是已连网的专属大脑。",
             "dm": {
               "policy": "pairing",
               "allowFrom": []
             },
-            "ws": {                               // Bot WS 配置
-              "botId": "BOT_ID",
-              "secret": "BOT_SECRET"
-            },
-            "webhook": {                          // Bot Webhook 配置 (按需)
-              "token": "BOT_TOKEN",
-              "encodingAESKey": "BOT_AES_KEY",
-              "receiveId": "BOT_RECEIVE_ID"
+            "ws": {                               // Bot WS 建连所需凭证
+              "botId": "YOUR_BOT_ID",
+              "secret": "YOUR_BOT_SECRET"
             }
           },
-          "agent": {
-            "corpId": "CORP_ID",
-            "agentSecret": "AGENT_SECRET",
+          "agent": {                              // 主动推送、媒体发送与兜底交付链路
+            "corpId": "YOUR_CORP_ID",
+            "agentSecret": "YOUR_AGENT_SECRET",
             "agentId": 1000001,
             "token": "AGENT_TOKEN",
             "encodingAESKey": "AGENT_AES_KEY",
-            "welcomeText": "你好，这里是 Agent 通道。",
+            "welcomeText": "若长连接断开，我将使用此通道传递残存报告。",
             "dm": {
               "policy": "open",
               "allowFrom": []
@@ -259,297 +251,158 @@ openclaw channels add
         }
       },
       "media": {
-        "tempDir": "/tmp/openclaw-wecom-media",
-        "retentionHours": 24,
-        "cleanupOnStart": true,
-        "maxBytes": 26214400
+        "tempDir": "/tmp/openclaw-wecom-media"
       },
-      "network": {
+      "network": {                                // 内网或受限网络环境可通过代理出网
         "egressProxyUrl": "http://127.0.0.1:3128"
       },
-      "routing": {
-        "failClosedOnDefaultRoute": true
-      },
-      "dynamicAgents": {
+      "dynamicAgents": {                          // 为单聊/群聊创建独立路由，减少多人串上下文
         "enabled": true,
         "dmCreateAgent": true,
         "groupEnabled": true,
-        "adminUsers": ["zhangsan"]
+        "adminUsers": ["zhangsan001"]             // 管理员绕过动态路由，直连主 Agent
       }
     }
   }
 }
 ```
 
-说明：
-- 新配置推荐使用 `agent.agentSecret`
-- 历史配置里的 `agent.corpSecret` 仍兼容读取，但后续文档统一使用 `agentSecret`
-- `bot.streamPlaceholderContent` 会同时作用于 `Bot WS` 与 `Bot Webhook`；在 `Bot WS` 下，收到用户消息后会立即显示该占位符，并在长思考期间持续保活。
-- 如果你在一个 OpenClaw 实例里挂载多个 `accounts`，并让它们共同路由到同一个静态 Agent，建议在全局配置里加上 `session.dmScope = "per-account-channel-peer"`，让私聊 session key 显式带上 `accountId`。
-
-### 1.3 高级网络配置（公网出口代理）
-如果您的服务器使用 **动态 IP** (如家庭宽带、内网穿透) 或 **无公网 IP**，首先使用Bot模式的ws接入方式。
-
-企业微信 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"
-```
-
-### 1.4 验证启动与观测
-
-使用最新的自检命令以检查通道装载、端口绑定与运行情况：
-```bash
-openclaw channels status --deep
-```
-
-建议重点看这几个核心状态指标是否健康：
-- `primaryTransport` / `transport` / `health`
-
----
+> **注意：** 历史配置里的 `agent.corpSecret` 引擎依然能够向后兼容拾起，但后续的新项目推荐采用标准的 `agentSecret` 作为对齐键。
 
-<a id="sec-4"></a>
+### 1.4 dynamicAgents 详细说明：为什么生产环境建议开启
 
-## 二、⚙️ 三模配置模式详解
+`dynamicAgents` 的核心价值，不是“自动创建很多 Agent”，而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。  
+如果不开它，所有消息更容易汇入同一个主 Agent；一旦开始多人共用，最先出问题的通常不是模型能力，而是上下文、长期记忆和处理边界混在一起。
 
-新版已分离 `Transport` 传输层，以下是独立运转模式的基本构成（你可以随意组合它们入同一个 account）：
+更简单地看，可以直接按下面这张表决定要不要开：
 
-### 2.1 仅 Bot WS 模式
-最简的流式交互版（无兜底分发功能）。
-关键约束：`bot.primaryTransport = "ws"` 必须包含 `bot.ws` 参数。
+| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |
+|---|---|---|---|
+| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络，长期上下文可能互相污染 | `enabled=true` + `dmCreateAgent=true` | 每个人都有自己的稳定上下文 |
+| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent，群与群之间边界不清晰 | `enabled=true` + `groupEnabled=true` | 每个群都有独立会话空间 |
+| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent，排障更分散 | `adminUsers=["管理员userid"]` | 管理账号继续直连主 Agent |
+| 只是做 PoC 或单人试用 | 一上来就启用隔离，理解成本偏高 | `enabled=false` | 先把连通性和基础回复跑通 |
 
-行为说明：
-- 收到用户消息后立即发送一次 `streamPlaceholderContent` 占位流。
-- 若模型首个真实文本块尚未产出，系统会持续发送保活占位，避免长思考期间 `req_id` 失效。
+系统当前的真实行为如下：
 
-```jsonc
-{
-  "accounts": {
-    "default": {
-      "bot": {
-        "primaryTransport": "ws",
-        "ws": { "botId": "BOT_ID", "secret": "BOT_SECRET" }
-      }
-    }
-  }
-}
-```
+- 开启后，会按 `账号 + 会话类型 + 对端 ID` 生成确定性的 Agent ID，例如 `wecom-default-dm-zhangsan` 或 `wecom-default-group-wr123456`
+- 同一个用户或同一个群，下次再发消息时会继续命中同一个动态 Agent，而不是临时随机分配
+- 首次命中时，插件会自动把这个动态 Agent 追加到 `agents.list`，不需要您手工维护一长串列表
+- 这套逻辑同时作用于 `Bot WS` 和 `Agent Callback` 两条主消息链路，不是只有某一种模式才生效
+- `adminUsers` 中的账号会始终绕过动态路由，直接走主 Agent，适合放管理员、运营或排障账号
+- 默认值是 `enabled=false`、`dmCreateAgent=true`、`groupEnabled=true`、`adminUsers=[]`，也就是不开总开关时不会生效，但一旦开启，单聊和群聊会默认一起进入隔离模式
 
-### 2.2 仅 Bot Webhook 模式
-针对某些无法建立高可靠 WS 网关的环境，退化使用 URL 回调。
-关键约束：`bot.primaryTransport = "webhook"` 必须包含 `bot.webhook` 参数。
-
-```jsonc
-{
-  "accounts": {
-    "default": {
-      "bot": {
-        "primaryTransport": "webhook",
-        "webhook": { "token": "BOT_TOKEN", "encodingAESKey": "BOT_AES_KEY" }
-      }
-    }
-  }
-}
-```
-
-### 2.3 自动分流与会话隔离 (dynamicAgents)
-
-这属于插件的**全局网络与行为组**。
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `enabled` | `boolean` | 是否启用动态 Agent |
-| `dmCreateAgent` | `boolean` | 私聊是否自动建 Agent |
-| `groupEnabled` | `boolean` | 群聊是否允许动态 Agent |
-| `adminUsers` | `string[]` | 管理员白名单 |
-
-#### 场景说明（解决真实企业痛点）
-企业场景下，当多名同事或多个群组同时与系统交互时，系统默认只会连接同一个全局 AI Agent。这会导致**会话上下文串扰（张三发的问题，李四接着问，上下文混乱）**。
-
-开启 `dynamicAgents` 后，可以解决此痛点，实现**“千人千面、万群万脑”**的并发隔离机制：
-- **`enabled` (总开关)**：一旦打开，系统会自动为每个会话的来源进行分流，并动态生成专属的底层 Agent 实例（如 `wecom-default-dm-张三`），无需人工配置。
-- **`dmCreateAgent` (私聊自动建号)**：实现员工私人助理模式。每个人私聊发消息，系统都会临时绑定独立记忆的专属助理，避免为全公司几百人挨个去后台扫码建号配置。
-- **`groupEnabled` (群聊自动分群)**：实现各个群聊主题封闭。A 群的讨论话题绝不会串扰到 B 群。
-- **`adminUsers` (管理员特权后门)**：填入管理员的微信 ID。遇到这几个人发消息时，系统**不会**去进动态 Agent 隔离区，而是直通后端的主控制台 Agent，以便执行全网管理指令。
-
-> **🌟 多账号矩阵下的全局生效与物理隔离**
-> `dynamicAgents` 属于通道级的全局开关，开启后会对配置的所有账号（`accounts`）生效。为了维持账号的绝对隔离，生成的隔离 Agent ID 内置了 Account 维度（例如：`wecom-ops-dm-张三` vs `wecom-sales-dm-张三`），保证跨企业应用依旧安全隔绝。
->
-> 如果你没有开启 `dynamicAgents`，但多个 `accountId` 共享同一个静态 Agent，请在 OpenClaw 全局配置里显式设置 `session.dmScope = "per-account-channel-peer"`，确保不同账号的私聊上下文不会被收敛到同一个 session key。
+需要注意的是，`dynamicAgents` 解决的是“路由隔离”和“会话隔离”，不是权限系统本身。  
+也就是说，它能显著减少上下文串线，但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent，仍然要结合 `dm.policy`、`bindings` 和企业微信授权配置一起看。
 
 ---
 
-<a id="sec-5"></a>
-
-## 三、🏢 企业微信接入指南
-
-新版系统已将 Callback 回调处理实现了**全自动的账号分流路径派生**，开发者不要在配置里手工定义 `ReceiveID` 的硬编码路由覆盖，请在企业微信管理后台直接指向对应路径。
+## 二、🏢 企业微信后台回调挂载指南 (针对使用了 Webhook 或 Agent Callback 的重度用户)
 
-### 3.1 明确各类模式的目标路径
+如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件，需要将系统的路径下发到企业微信管理后台。
+由于系统默认采纳**多账号分流路径派生**，请切记不要随意丢弃末尾的 `{accountId}`，如下所示：
 
-| 类型 | 默认账号 | 非默认账号 (如 ops) |
-|---|---|---|
-| **Bot Webhook** | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |
-| **Agent Callback** | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |
+| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |
+|---|---|---|---|
+| **Bot Webhook** | `https://x.com` | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |
+| **Agent Callback** | `https://x.com` | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |
 
-*(注：系统通过智能中间件，若只配了 default 且你访问 `/plugins/wecom/bot` 无后缀，也会尝试自动漂移至 default，但**极不建议**，必须写标准账号名后缀以规避未来扩展冲突。)*
-
-### 3.2 下发路由至企业微信后台
-1. 登录企业微信管理后台
-2. 机器人填入回调 URL：`https://your-domain.com/plugins/wecom/bot/{accountId}`
-3. 自建应用填入回调 URL：`https://your-domain.com/plugins/wecom/agent/{accountId}` (不要忘记加可信IP)。
-
-<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>
+*警告：极度不推荐将老旧单一根路径（如 `/plugins/wecom/bot`）在未指定账户空间下裸奔使用，一旦您的业务扩张到第二个账号，将会引发难以追溯的回调抢占雪崩。*
 
 ---
 
-<a id="sec-6"></a>
-
-## 四、✨ 高级功能
+## 三、📡 排障与抓包：洞悉黑盒下的脉搏
 
-### 4.1 A2UI 交互卡片
+当前版本请使用以下三条命令组合排障。注意：`openclaw channels status` **不支持** `--deep`，插件级探测参数是 `--probe`；`--deep` 属于顶层 `openclaw status`。
 
-Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
+### 3.1 先看插件级状态快照
 
-- ✅ 单聊场景：发送真实交互卡片
-- ✅ 按钮点击：触发 `template_card_event` 回调
-- ✅ 自动去重：基于 `msgid` 避免重复处理
-- ⚠️ 群聊降级：自动转为文本描述
-
-### 4.2 ⏰ Cronjob 企业级定时推送
-
-本插件深度集成了 OpenClaw 的 Cronjob 调度能力，配合 Agent 强大的广播 API，轻松实现企业级通知服务。
-
-> **核心场景**：早报推送、服务器报警、日报提醒、节日祝福。
+```bash
+openclaw channels status --probe
+```
 
-#### 4.2.1 目标配置 (Target)
-无需遍历用户列表，直接利用 Agent 强大的组织架构触达能力：
+适合回答这些问题：
 
-| 目标类型 | 格式示例 | 推送范围 | 典型场景 |
-|:---|:---|:---|:---|
-| **部门 (Party)** | `party:1` (或 `1`) | 📢 **全员广播** | 全员通知、技术部周报 |
-| **标签 (Tag)** | `tag:Ops` | 🎯 **精准分组** | 运维报警、管理层汇报 |
-| **外部群 (Group)** | `group:wr...` | 💬 **群聊推送** | 项目组群日报 (需由Agent建群) |
-| **用户 (User)** | `user:zhangsan` | 👤 **即时私信** | 个人待办提醒 |
+- 企业微信账号是否已被网关识别并加载
+- 账号当前是否 `enabled` / `configured`
+- 运行时是否 `running` / `connected` / `authenticated`
+- 最近一次错误、最近进出站时间是否异常
 
-#### 4.2.2 配置示例 (`schedule.json`)
+如果网关可达，这条命令会返回企业微信账号的运行时快照。  
+如果网关不可达，它会自动退化为“只看配置”的摘要输出。
 
-只需在工作区根目录创建 `schedule.json` 即可生效：
+### 3.2 再看全局深度诊断
 
-```json
-{
-  "tasks": [
-    {
-      "cron": "0 9 * * 1-5", // 每周一至周五 早上9:00
-      "action": "reply.send",
-      "params": {
-        "channel": "wecom",
-        "to": "party:1",      // 一键发送给根部门所有人！
-        "text": "🌞 早安！请查收[今日行业简报](https://example.com/daily)。"
-      }
-    }
-  ]
-}
+```bash
+openclaw status --deep
 ```
 
-### 4.3 🤖 动态 Agent 扩容引擎
-在《二、配置说明》中讲解的 `dynamicAgents`，除了在运行时把会话隔离，它还在内存里做了一套高吞吐状态写入：
-系统会自动以异步、排队、防冲突的队列，将被激活的动态专用助理自动追加写入底层核心系统配置文件 `openclaw.json` (或相应 yaml) 的 `agents.list` 数组中，这就意味着：这套扩容体系是对上层管理员完全**透明且免运维**的，机器人活了，号也就落盘注册好了。
-
-### 4.4 📝 Docs 极客级协作资产管控
-从 v2.3.14 起，OpenClaw WeCom 插件已深度集成企微原生协作文档；在 v2.3.15 中，又重点补上了 `init_content`、图片插入、批量更新索引与群聊目标解析的稳定性问题。现在你既可以让 AI 建档，也更适合直接拿来做真实写入与协作：
+这条命令是 **OpenClaw 全局诊断入口**，适合确认：
 
-**【典型赋能场景】**
-1. **自动化建档**：对机器人说：“建一个名为『Q1需求追踪』的表格，并把群里的人都加上可写权限。”它将自动调用 `create_doc` 并生成带权限的企微链接。
-2. **移动端碎片修改**：在地铁上吩咐：“把「第二周面试记录」里的 B2 到 B5 单元格全部更新为‘二面通过’。” AI 会精准直击数据块，不干扰他人协同（`spreadsheet.edit_data`）。
-3. **跨表分析**：发给机器人一张总账表的企微链接：“分析这表里的营收列，告诉我哪个部门贡献最大？” AI 原生抓取数据解算输出。
+- Gateway 本身是否健康
+- 当前机器上的整体通道探测是否正常
+- 最近心跳、会话、服务状态是否异常
 
-> **⚠️ 权限解锁指引**：
-> 要让 AI 解锁该能力，仅在配置文件填入 `agentSecret` 不够。企业微信已将文档在权限面上实施了“物理隔离”。请务必：
-> 1. 进入 [企微管理后台 -> 协作 -> 文档 -> 可调用接口应用白名单](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，勾选赋予你的 OpenClaw 自建应用“通行证”。
-> 2. 在 OpenClaw UI 界面工具集（Tool）勾选所有前缀含有 `doc:` 或 `wecom` 下相关操作单元。
+当您怀疑问题不只在企业微信插件，而是 Gateway、网络、配置路径或其他通道共同影响时，优先跑这条。
 
----
-
-<a id="sec-7"></a>
-
-## 五、📖 详细行为说明 & 运行约束
+### 3.3 最后直接看 WeCom 日志
 
-### 5.1 运行约束原则
-- **协议单工限制**：同一账号下，Bot 只能选择一个主传输协议 `primaryTransport` (`ws` 或 `webhook`) 运作。
-- **帧边界不可打破**：Bot WS 是基于官方微信内部通信协议的扩展，它必须携带并原路奉还对应的 `req_id`。插件会在长思考期间自动发送占位/保活帧来维持该回复窗口，但标准化事件不会替代原始数据帧，业务流始终可访问该原始微信底层框架。
-- **媒体沙盒边界**：不论是 `Webhook`，还是 `WS`，涉及企微媒体加解密的处理绝不再跨界干预业务执行层。由内部服务自动在 Transport / Media Service 网关边界卸载 `aeskey` 解密并转换为统一 OpenClaw 媒体类抛出。
-
-### 5.2 企业微信群聊交付规则
+```bash
+openclaw channels logs --channel wecom --lines 200
+```
 
-*   **默认 (Bot 回复)**：群聊里 @Bot，默认由 Bot 在群内直接回复（优先文本/图片/Markdown）。
-*   **例外 (文件兜底)**：如果回复内容包含**非图片文件**（如 PDF/Word/表格/压缩包等），由于企微 Bot 接口不支持，插件会自动：
-    1.  Bot 在群里提示："由于格式限制，文件将通过私信发送给您"。
-    2.  无缝切换到 **自建应用 (Agent)** 通道，将文件私信发送给触发者。
-*   **提示**：若未配置 Agent，Bot 会明确提示“需要管理员配置自建应用通道”。
+当发生疑难连接断开、消息不回、媒体文件下发神秘消失时，直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下，助你顺藤摸瓜：
 
-### 5.3 长任务可靠性保障
+- `[wecom-runtime]`：统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。
+- `[wecom-ws]`：Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。
+- `[wecom-agent-delivery]`：Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。
 
-*   **超时熔断**：企业微信限制 Bot 流式回复窗口约为 6 分钟。
-*   **自动接力**：当对话时长接近此阈值时，Monitor 会自动截断 Bot 流，提示 "剩余内容将私信发送"，并立即启动 Agent 通道私信发送完整结果。
+### 3.4 推荐排障顺序
 
-### 5.4 命令行排障抓包指南
+建议按下面顺序执行：
 
-利用自带命令直接追溯到新版本的微架构心跳：
 ```bash
-openclaw channels status --deep
+openclaw channels status --probe
+openclaw status --deep
+openclaw channels logs --channel wecom --lines 200
 ```
 
-如果出故障，除了系统根日志外，新版强化了命名空间隔离的抓包日志锚点，你可以直接在日志中过滤检索：
-- `[wecom-runtime]`：插件整体初始化装配线、出入站分检
-- `[wecom-ws]`：专门看 Bot WS 链路是否频繁掉线被踢、握手授权是否有效。
-- `[wecom-http]`：监控与企微云端所有 HTTP 通信（如 Token 刷新、向企微主动抛消息等网络损耗/限流情况）。
-- `[wecom-agent-delivery]`：看自建应用的被动反向代投情况以及群发选型问题。
+您可以按输出这样判断：
 
----
-
-<a id="sec-8"></a>
-
-## 六、🙋 社区问答 (FAQ)
+- `configured=false`：先检查 `bot.ws.botId`、`bot.ws.secret`、`agent.corpId`、`agent.agentSecret`、`agent.agentId` 等配置是否完整。
+- `running=false`：说明账号没有真正启动，优先看 `[wecom-runtime]`。
+- `connected=false` 或 `authenticated=false`：优先看 `[wecom-ws]`，一般是 WebSocket 握手、密钥或连接稳定性问题。
+- 能收不能发，或群里发文件/卡片失败：优先看 `[wecom-agent-delivery]`。
+- `lastError` 持续刷新：通常不是一次性误报，建议结合最近 200 行日志一起看。
 
-针对社区反馈的高频问题，解答如下：
-
-**Q1: 能不能同时配置 `bot.ws` 和 `bot.webhook`？**
-> **A:** 完全可以，且强烈推荐一起预置填写。但真正被框架加载用于**接管实时会话流量**的，永远遵循 `bot.primaryTransport` 这个单选项切换开关。
-
-**Q2: 为什么不要手写 callback path？**
-> **A:** 因为由于重构后的引擎能承载大量的企业企微号同时并发挂载，所以必须抛弃写死的映射表。运行时已强制执行 `{accountId}` 前置命名空间策略路由分配。强行手写旧路由会被中间件劫并产生警告抛出。
+---
 
-**Q3: 为什么 `plugins list` 出现重复 `wecom` 报错？**
-> **A:** 一定是因为你既使用了 `npm i @yanhaidao/wecom`，又尝试 clone 代码本地挂载了 `openclaw plugins install -l ./extensions/wecom` 产生了 npm/file 包竞态冲突导致。请进入配置目录显露出的隐藏子目录彻底清除只留其一即可。
+## 四、🤝 项目协作者
 
-**Q4: 使用内网穿透时，企业微信报错 60020 (IP 不白名单) 怎么办？**
-> **A:** 请启用配置中的 `config.network.egressProxyUrl` 项。利用具有独立静态外网IP的二级跳板代理（比如 Squid），来穿透这层官方强制保护盾。
+感谢所有为本项目提交代码、测试、文档与反馈的协作者。
 
-**Q5: 为什么发视频给 Bot 没反应？**
-> **A:** 官方 Bot 接口**不支持接收视频**。如果您需要处理视频内容，必须配置 Agent 小微应用，由于 Agent 下行具备富媒体流承接功能，本插件会自动从底层拦截将其解码并传输给底层大模型看。
+<p align="center">
+  <a href="https://github.com/YanHaidao/wecom/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=YanHaidao/wecom" alt="WeCom contributors" />
+  </a>
+</p>
 
-**Q6: 支持个人微信吗？**
-> **A:** 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），这不等同于“个人微信网页版协议”。您可以在个人微信中直接与企业号/应用对话，无需打开企业微信 App。
+如果头像墙没有立刻刷新，通常是 GitHub 统计或第三方缓存延迟，稍后再看即可。
 
 ---
 
-<a id="sec-9"></a>
-
-## 七、📮 联系我 与 版本协议
-
+## 五、📮 联系作者 与 许可证协议指引
 
+<p>
+  如果您在搭建这套极度庞大的多端复合体系时遇到迷思，或者对底层代理流量重定向有着深度企业定制化需求，请毫无顾虑地与我连接：
+</p>
 
-微信交流群（扫码入群）：
+- 微信直接交流群（扫描底部二维码进群探讨技术）：
+- **维护者**：YanHaidao 
 
 ![企业微信交流群](https://openclaw.cc/wechat-github.jpg)
 
-维护者：YanHaidao（VX：YanHaidao）
-
-本项目采用 **ISC License** 开源协议，并在此强调以下要求：
-1. **保留署名**：在任何分发、修改或使用本项目时，**必须**完整保留本项目的版权声明。
-2. **尊重原创**：本项目包含的“架构”“长对话超时接力”等均为作者 **YanHaidao** 核心成果，拒绝任何去署名的“纯搬运”剽窃。
+### 最后的话：关于开源及署名
+本项目遵循 **ISC License**，您可以将其用于极其广阔的项目天地中。但开源不是拿来主义：
+在此明确强调，包括所谓的“Bot+Agent 保活接力超时融合机制”、“千人千面多账户切面”、“自动寻的路由下沉” 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。**拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。**
+愿我们能在彼此尊重的前提下，共同拓展 OpenClaw 生态的无垠边界。