@yanhaidao/wecom 2.3.141 → 2.3.160

package/README.md

@@ -14,7 +14,11 @@
 </p>
 
 <p align="center">
-  <strong>🚀 深度适配企业微信原生文档（WeCom Doc）：将对话沉淀为企业数字资产 [v2.3.14 重磅]</strong>
+  <strong>🚀 深度适配企业微信原生文档（WeCom Doc）：将对话沉淀为企业数字资产，并补齐写入稳定性 [v2.3.15]</strong>
+</p>
+
+<p align="center">
+  <strong>🆕 Bot WS 混合消息附件解析修复：图片和文字一起发时，AI 终于能看到真实媒体内容 [v2.3.16]</strong>
 </p>
 
 <p align="center">
@@ -72,6 +76,7 @@
 
 #### 📎 **全模态支持 (Multi-Modal)**
 *   **发什么都能看**：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
+*   **混合消息也不丢附件**：从 `v2.3.16` 起，`Bot WS` 可正确解析“图片/文件 + 文本”混合消息，AI 不再只看到腾讯 COS 临时签名链接文本。
 *   **要什么都能给**：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。
 
 #### 📝 **深度适配企业微信“协作文档” (WeCom Doc)**
@@ -114,6 +119,29 @@
 
 > 项目保持高频迭代，核心改进一览：
 
+#### v2.3.16（2026-03-16）
+
+- 🛠 **[重要修复]** 补齐 `Bot WS` 对 `mixed` 结构消息的附件提取逻辑。现在用户发送“图片/文件 + 文本”的混合消息时，插件会自动遍历媒体节点并提取 URL 与 `aeskey`，确保核心处理链路能正常下载、解密并交给 AI 分析真实媒体内容。
+- 🖼 修复此前 AI 只能读到腾讯 COS 临时签名链接文本、无法真正查看图片本体的问题，尤其适合“发一张截图再补一句说明”的常见企业微信使用场景。
+
+**升级指引：**
+```bash
+openclaw plugins update wecom
+```
+
+#### 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）
 
 - 📝 **[重磅功能]** 深度适配企业微信原生「协作文档」，支持通过自然语言自动建文档/表格、单元格级精准修改、跨表数据分析与权限管控。Thanks [@proyy](https://github.com/proyy)。
@@ -448,7 +476,9 @@ Agent 输出 `{"template_card": ...}` 时自动渲染为交互卡片：
 系统会自动以异步、排队、防冲突的队列，将被激活的动态专用助理自动追加写入底层核心系统配置文件 `openclaw.json` (或相应 yaml) 的 `agents.list` 数组中，这就意味着：这套扩容体系是对上层管理员完全**透明且免运维**的，机器人活了，号也就落盘注册好了。
 
 ### 4.4 📝 Docs 极客级协作资产管控
-从 v2.3.14 起，OpenClaw WeCom 插件已深度集成了企微原生协作文档的管理策略引擎。只需自然语言指令，即可唤醒这一能力：
+从 v2.3.14 起，OpenClaw WeCom 插件已深度集成企微原生协作文档；在 v2.3.15 中，又重点补上了 `init_content`、图片插入、批量更新索引与群聊目标解析的稳定性问题。现在你既可以让 AI 建档，也更适合直接拿来做真实写入与协作：
+
+另外，从 v2.3.16 起，`Bot WS` 对“图片/文件 + 说明文字”这类混合消息的附件解析也已补齐，更适合把截图、报表和文字说明一起发给 AI 做联合分析。
 
 **【典型赋能场景】**
 1. **自动化建档**：对机器人说：“建一个名为『Q1需求追踪』的表格，并把群里的人都加上可写权限。”它将自动调用 `create_doc` 并生成带权限的企微链接。
@@ -529,115 +559,7 @@ 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`。
 
 微信交流群（扫码入群）：
 

package/changelog/v2.3.15.md

@@ -0,0 +1,15 @@
+# OpenClaw WeCom 插件 v2.3.15 变更简报
+
+> [!TIP]
+> **企业微信文档写入稳定性与消息目标路由修复版本**：`v2.3.15` 重点解决了企微文档 `init_content` 初始化内容写入不稳定、图片插入失败、批量更新索引错误，以及群聊回复时容易触发的 `81013` 目标解析错误。同时，这次也补回并完善了文档、在线表格、智能表格、收集表等能力，避免相关工具调用缺接口或直接失败。
+
+## 2026-03-14（v2.3.15）
+- 【文档初始化内容修复】🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行：图片先上传再插入，文本与图片段落会基于最新索引和版本号写入，减少标题正文错位、图片不显示、内容插到错误位置的问题。
+- 【批量更新稳定性修复】📄 **[重要修复]** 修复 `document.batch_update` 的索引计算与模式切换问题。混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时，不再更容易触发 `ParagraphValidator`、`TextValidator`、`DrawingValidator` 一类报错。
+- 【文档客户端能力恢复】🔧 重新补齐此前精简时误删的企微文档客户端接口，恢复文档权限、在线表格、智能表格、收集表等相关方法，避免工具层调用缺方法、返回异常或直接不可用。
+- 【在线表格与收集表支持补齐】📊 完善企微在线表格和收集表的类型定义、参数校验与错误提示。现在会更早拦截超出 API 限制的请求，例如表格行列/单元格数量超限、收集表题目结构缺失、选项题参数不完整等问题。
+- 【群聊目标解析修复】💬 **[重要修复]** 修复企业微信群聊回复时 `To` 字段被错误硬编码为用户目标的问题。群聊、私聊、部门、标签目标现在会按正确前缀解析，减少发送时报 `81013 user & party & tag all invalid` 的情况。
+
+## 升级提示
+- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.15`。
+- 如果你之前遇到“建文档成功但内容没写进去”“图片插不进去”“批量更新偶发报索引错误”或“群里回复机器人时报 81013”，本次升级后会明显改善。

package/changelog/v2.3.16.md

@@ -0,0 +1,11 @@
+# OpenClaw WeCom 插件 v2.3.16 变更简报
+
+> [!TIP]
+> **企业微信 Bot-WS 混合消息附件解析修复版本**：`v2.3.16` 重点解决了在 WebSocket 模式下，企业微信机器人接收到的混合消息（如同时包含图片和文字）由于解析遗漏导致附件丢失、AI 只能看到带签名的临时链接文本而无法查看真正图片内容的问题。
+
+## 2026-03-16（v2.3.16）
+- 【混合消息媒体解析修复】🛠 **[重要修复]** 补齐了 Bot WebSocket 传输通道（`bot-ws`）下对 `mixed` 结构消息的附件提取逻辑。现在，当用户在企微发出一条包含图片/文件与文字的混合消息时，底层框架会自动遍历并提取各个媒体节点的 URL 和 AES Key，确保核心处理管线能进行正常下载与安全解密。
+
+## 升级提示
+- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.16`。
+- 如果你之前在企微发出“带图的一段话”时，曾遇到 AI 回复说“这是一个腾讯 COS 的临时签名链接”，本次升级后，此问题将被修复，AI 将可以直接分析图片内容本身。

package/docs/update-content-fix.md

@@ -0,0 +1,135 @@
+# 企微文档批量更新修复指南
+
+## 问题背景
+
+企业微信文档 API 的 `batch_update` 接口存在以下限制：
+
+1. **索引基于快照**：所有操作的索引基于请求发送时的文档快照
+2. **原子性**：批量操作中一个失败则全部回滚
+3. **段落验证**：`insert_text` 必须指向已有 Run 元素，不能在空段落执行
+4. **版本控制**：`version` 参数用于并发控制（与最新版本差≤100）
+
+## 常见问题
+
+### ParagraphValidator cannot find p's parent
+
+**原因**：在空段落或无效位置插入内容
+
+**解决方案**：
+```typescript
+// 错误：直接在空位置插入文本
+requests: [
+  { insert_paragraph: { location: { index: 1 } } },
+  { insert_text: { location: { index: 1 }, text: "内容" } }  // ❌ 索引错误
+]
+
+// 正确：使用顺序模式或正确计算索引
+requests: [
+  { insert_paragraph: { location: { index: 1 } } },
+  { insert_text: { location: { index: 2 }, text: "内容" } }  // ✅ index+1
+]
+```
+
+### TextValidator cannot find p parent
+
+**原因**：`insert_text` 操作的目标段落在文档快照中不存在
+
+**解决方案**：每次操作前获取最新文档结构
+
+## 推荐方案
+
+### 方案 A：顺序模式（推荐，默认）
+
+```typescript
+await docClient.updateDocContent({
+  agent, docId,
+  requests: [...],
+  batchMode: false  // 默认：顺序执行，每次获取最新版本
+});
+```
+
+**优点**：
+- 可靠性高
+- 自动处理版本和索引
+- 适合复杂场景
+
+**缺点**：
+- API 调用次数较多
+
+### 方案 B：批量模式（高性能场景）
+
+```typescript
+await docClient.updateDocContent({
+  agent, docId,
+  requests: [
+    { insert_paragraph: { location: { index: 1 } } },
+    { insert_text: { location: { index: 2 }, text: "内容" } }
+  ],
+  batchMode: true,  // 批量执行，基于同一快照
+  version: 123      // 必须提供版本号
+});
+```
+
+**优点**：
+- API 调用次数少
+- 性能更好
+
+**缺点**：
+- 需要精确计算索引
+- 所有操作基于同一快照
+
+### 方案 C：使用 init_content（创建文档）
+
+```typescript
+await docClient.createDoc({
+  agent,
+  docName: "新文档",
+  docType: "doc",
+  init_content: [
+    "# 标题",
+    "第一段内容",
+    { type: "image", url: "https://..." },
+    "第二段内容"
+  ]
+});
+```
+
+**优点**：
+- 最简单可靠
+- 自动处理分段
+
+**缺点**：
+- 仅适用于创建文档
+
+## API 限制速查
+
+| 操作 | 限制 |
+|------|------|
+| 批量操作数 | 1-30 个 requests |
+| 版本差 | ≤100 |
+| 新增行 | ≤1000 |
+| 新增列 | ≤200 |
+| 单元格总数 | ≤10000 |
+| 查询范围 | 行≤1000, 列≤200 |
+
+## 错误码
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| ParagraphValidator | 段落位置无效 | 使用正确索引或顺序模式 |
+| TextValidator | 目标段落不存在 | 先创建段落或获取最新结构 |
+| DrawingValidator | 图片位置无效 | 在有效段落插入 |
+| version mismatch | 版本过旧 | 重新获取最新文档 |
+
+## 最佳实践
+
+1. **创建文档**：使用 `init_content`（最可靠）
+2. **更新文档**：使用顺序模式（`batchMode: false`，默认）
+3. **批量追加**：简单场景可用批量模式（需精确计算索引）
+4. **并发控制**：始终传递 `version` 参数
+5. **错误处理**：捕获异常并重试（最多 3 次）
+
+## 相关文档
+
+- [API 使用指南](./api-usage-guide.md)
+- [示例代码](./examples.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.3.141",
+  "version": "2.3.160",
   "type": "module",
   "description": "OpenClaw 企业微信（WeCom）插件，默认 Bot WebSocket，支持加密媒体解密、Agent 主动发消息与多账号接入",
   "repository": {

package/src/agent/handler.ts

@@ -652,7 +652,7 @@ const ctxPayload = core.channel.reply.finalizeInboundContext({
     CommandBody: finalContent,
     Attachments: attachments.length > 0 ? attachments : undefined,
     From: isGroup ? `wecom:group:${peerId}` : `wecom:user:${fromUser}`,
-    To: `wecom:user:${peerId}`,
+    To: isGroup ? `wecom:group:${peerId}` : `wecom:user:${fromUser}`,
     SessionKey: route.sessionKey,
     AccountId: route.accountId,
     ChatType: isGroup ? "group" : "direct",