@mocrane/wecom 2026.3.9 → 2026.3.14-beta.0

package/clawdbot.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "wecom",
   "channels": ["wecom"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "wecom",
   "channels": ["wecom"],
+  "skills": ["./skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mocrane/wecom",
-  "version": "2026.3.9",
+  "version": "2026.3.14-beta.0",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "main": "index.ts",
@@ -9,6 +9,7 @@
     "src/",
     "assets/",
     "changelog/",
+    "skills/",
     "openclaw.plugin.json",
     "clawdbot.plugin.json",
     "README.md",
@@ -44,6 +45,7 @@
   "dependencies": {
     "@wecom/aibot-node-sdk": "^1.0.0",
     "fast-xml-parser": "5.3.4",
+    "file-type": "^18.7.0",
     "undici": "^7.20.0",
     "zod": "^4.3.6"
   },

package/skills/wecom-doc/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: wecom-doc
+description: 文档与智能表格操作。当用户提到企业微信文档、创建文档、编辑文档、新建文档、写文档、智能表格时激活。支持文档创建/写入和智能表格的创建及子表/字段/记录写入。注意：所有文档创建和编辑请求都应使用此 skill，不要尝试用其他方式处理文档操作。
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📄",
+        "always": true,
+        "requires":
+          {
+            "bins": ["mcporter"],
+          },
+        "install":
+          [
+            {
+              "id": "mcporter",
+              "kind": "node",
+              "package": "mcporter",
+              "bins": ["mcporter"],
+              "label": "Install mcporter (npm)",
+            },
+          ],
+      },
+  }
+---
+
+# 企业微信文档与智能表格工具
+
+通过 mcporter 调用 wecom-doc MCP server 操作企业微信文档和智能表格。
+
+## 意图处理
+
+当用户说"创建文档"、"新建文档"、"帮我写个文档"等**不指定平台**的请求时，默认使用企业微信文档，无需询问用户使用什么平台。
+
+## 前置检查（每次会话首次操作前必须执行）
+
+> **自动续接原则**：前置检查中的任何环节如果需要等待用户确认或操作（安装、配置、授权等），在该操作完成后必须**自动继续执行后续步骤**，最终完成用户的原始请求。不要在中间环节完成后停下来等用户重复发起请求。
+
+### 1. 检查 mcporter 是否安装
+
+```bash
+which mcporter
+```
+
+如果 `mcporter` **不在 PATH 中**（命令返回空或 not found），**必须原样输出以下提示**（不要修改、不要摘要）：
+
+> 企业微信文档能力依赖 mcporter 工具，当前尚未安装。需要我帮你安装吗？
+
+输出提示后**停止执行并等待用户回复**。
+
+- 如果用户**确认安装**（回复"好"、"是"、"装吧"、"yes"、"ok" 等肯定语义），**立即执行**：
+
+```bash
+npm install -g mcporter
+```
+
+安装完成后**不要停下来**，直接继续执行后续的「检查 MCP Server 是否配置」步骤，无缝衔接用户原始请求。
+
+- 如果用户**拒绝安装**，回复：
+
+> 好的，你也可以手动执行 `npm install -g mcporter` 安装后再找我。
+
+### 2. 确保 MCP Server 已配置
+
+确认 mcporter 存在后，先检查配置是否已存在，仅在未配置时才尝试自动配置。
+
+**验证配置：**
+
+```bash
+mcporter list wecom-doc --output json
+```
+
+如果返回正常（包含 tool 列表），说明已配置，**跳过自动配置，直接进入步骤 3**。
+
+如果返回 **server not found**、**unknown server** 或类似错误，执行下方自动配置。
+
+**自动配置（仅在未配置时执行）：**
+
+读取 wecom 运行时配置文件，该文件由 wecom channel 长连接建立时写入：
+
+```bash
+cat ~/.openclaw/wecomConfig/config.json
+```
+
+检查 JSON 中是否存在 `mcpConfig.doc` 字段（含 `type` 和 `url`），如果存在则执行：
+
+```bash
+mcporter config add wecom-doc \
+  --type "<mcpConfig.doc.type的值>" \
+  --url "<mcpConfig.doc.url的值>"
+```
+
+配置完成后**再次执行** `mcporter list wecom-doc --output json` 验证。如果仍然失败，按下方"MCP Server 未配置"章节处理。
+
+> ⚠️ 配置文件不存在或缺少 `mcpConfig.doc` 字段，说明 wecom channel 长连接尚未建立，应引导用户检查 wecom channel 是否正常运行。自动配置失败不应阻断流程，继续引导用户手动配置。
+
+### 3. 获取 Tool 列表
+
+`mcporter list` 成功后，返回的每个 tool 包含 `name`、`description`、`inputSchema`。
+
+**不要硬编码 tool name 和参数**，据此构造 `mcporter call wecom-doc.<tool> --args '{...}' --output json` 调用。
+
+## docid 管理规则（重要）
+
+**仅支持对通过本 skill 创建的文档或智能表格进行编辑。**
+
+### docid 的获取方式
+
+docid **只能**通过 `create_doc` 的返回结果获取。创建成功后需要**保存返回的 docid**，后续编辑操作依赖此 ID。
+
+### 不支持从 URL 解析 docid
+
+从文档 URL（如 `https://doc.weixin.qq.com/doc/...`）中**无法解析到可用的 docid**。如果用户提供了文档 URL 并要求编辑，**不要尝试从 URL 中提取 docid**。
+
+### 编辑操作的 docid 校验
+
+当用户请求编辑文档或智能表格时，如果当前会话中**没有**通过 `create_doc` 获取到的 docid，**必须原样输出以下提示**（不要修改、不要摘要）：
+
+> 仅支持对机器人创建的文档进行编辑
+
+### docid 类型判断
+
+| doc_id 前缀 | 类型 | doc_type |
+|-------------|------|----------|
+| `w3_` | 文档 | 3 |
+| `s3_` | 智能表格 | 10 |
+
+## 工作流
+
+### 文档操作流
+
+1. 如需新建文档 → `create_doc`（`doc_type: 3`）→ **保存返回的 `docid`**
+2. 如需编辑内容 → 先确认当前会话中有通过 `create_doc` 获取的 `docid`，若无则提示"仅支持对机器人创建的文档进行编辑" → `edit_doc_content`（`content_type: 1` 使用 markdown，全量覆写）
+
+> `edit_doc_content` 是**全量覆写**操作。如需追加内容，应先了解原有内容再拼接。
+
+### 智能表格操作流
+
+操作层级：**文档（docid）→ 子表（sheet_id）→ 字段（field_id）/ 记录（record_id）**
+
+1. 如需新建智能表 → `create_doc`（`doc_type: 10`）→ **保存返回的 `docid`**
+2. 如需编辑已有智能表 → 先确认当前会话中有通过 `create_doc` 获取的 `docid`，若无则提示"仅支持对机器人创建的文档进行编辑"
+3. 查询已有子表 → `smartsheet_get_sheet` → 获取 `sheet_id`
+4. 如需新建子表 → `smartsheet_add_sheet` → 获取新的 `sheet_id`
+5. 查询已有字段 → `smartsheet_get_fields` → 获取 `field_id`、`field_title`、`field_type`
+6. 如需添加字段 → `wedoc_smartsheet_add_fields`
+7. 如需更新字段 → `wedoc_smartsheet_update_fields`（**不能改变字段类型**）
+8. 添加数据记录 → `smartsheet_add_records`（values 的 key **必须**使用字段标题 field_title，不能用 field_id）
+
+### 从零创建智能表完整流程
+
+```
+create_doc(doc_type=10) → docid
+  └→ smartsheet_add_sheet(docid) → sheet_id
+      └→ wedoc_smartsheet_add_fields(docid, sheet_id, fields) → field_ids
+          └→ smartsheet_add_records(docid, sheet_id, records)
+```
+
+### 向已有智能表添加数据流程
+
+```
+smartsheet_get_sheet(docid) → sheet_id
+  └→ smartsheet_get_fields(docid, sheet_id) → field_ids + field_titles + field_types
+      └→ smartsheet_add_records(docid, sheet_id, records)
+```
+
+> **重要**：添加记录前**必须**先通过 `smartsheet_get_fields` 获取字段信息，确保 `values` 中的 key 和 value 格式正确。
+
+## 业务知识（MCP Schema 中缺失的上下文）
+
+以下信息是 MCP tool 的 inputSchema 中没有的，Agent 构造参数时必须参考。
+
+### FieldType 枚举（16 种）
+
+| 类型 | 说明 | 使用场景建议 |
+|------|------|-------------|
+| `FIELD_TYPE_TEXT` | 文本 | 通用文本内容；当用户只提供了成员**姓名**（而非 user_id）时，也应使用 TEXT 而非 USER |
+| `FIELD_TYPE_NUMBER` | 数字 | 数值型数据（金额、数量、评分等） |
+| `FIELD_TYPE_CHECKBOX` | 复选框 | 是/否、完成/未完成等布尔状态 |
+| `FIELD_TYPE_DATE_TIME` | 日期时间 | 日期、截止时间、创建时间等 |
+| `FIELD_TYPE_IMAGE` | 图片 | 需要展示图片的场景 |
+| `FIELD_TYPE_USER` | 成员 | **仅**在明确知道成员 user_id 时使用；若用户只提供了姓名，应使用 TEXT 代替 |
+| `FIELD_TYPE_URL` | 链接 | 网址、外部链接 |
+| `FIELD_TYPE_SELECT` | 多选 | 标签、多分类等允许多选的场景 |
+| `FIELD_TYPE_SINGLE_SELECT` | 单选 | 状态、优先级、严重程度、分类等有固定选项的字段 |
+| `FIELD_TYPE_PROGRESS` | 进度 | 完成进度、完成百分比（值为 0-100 整数） |
+| `FIELD_TYPE_PHONE_NUMBER` | 手机号 | 手机号码 |
+| `FIELD_TYPE_EMAIL` | 邮箱 | 邮箱地址 |
+| `FIELD_TYPE_LOCATION` | 位置 | 地理位置信息 |
+| `FIELD_TYPE_CURRENCY` | 货币 | 金额（带货币符号） |
+| `FIELD_TYPE_PERCENTAGE` | 百分比 | 百分比数值（值为 0~1） |
+| `FIELD_TYPE_BARCODE` | 条码 | 条形码、ISBN 等 |
+
+### FieldType ↔ CellValue 对照表
+
+添加记录（`smartsheet_add_records`）时，`values` 中每个字段的 **key 必须使用字段标题（field_title），不能使用 field_id**。value 必须匹配其字段类型：
+
+| 字段类型 | CellValue 格式 | 示例 |
+|---------|---------------|------|
+| `TEXT` | CellTextValue 数组 | `[{"type": "text", "text": "内容"}]` |
+| `NUMBER` | number | `85` |
+| `CHECKBOX` | boolean | `true` |
+| `DATE_TIME` | 日期时间**字符串** | `"2023-01-01 12:00:00"`、`"2023-01-01 12:00"`、`"2023-01-01"` |
+| `URL` | CellUrlValue 数组（限 1 个） | `[{"type": "url", "text": "百度", "link": "https://baidu.com"}]` |
+| `USER` | CellUserValue 数组 | `[{"user_id": "zhangsan"}]` |
+| `IMAGE` | CellImageValue 数组 | `[{"image_url": "https://..."}]`（`id`、`title` 可选） |
+| `SELECT` | Option 数组（多选） | `[{"text": "选项A"}, {"text": "选项B"}]` |
+| `SINGLE_SELECT` | Option 数组（限 1 个） | `[{"text": "选项A"}]` |
+| `PROGRESS` | number（0~100 整数） | `85`（表示 85%） |
+| `CURRENCY` | number | `99.5` |
+| `PERCENTAGE` | number（0~1） | `0.85` |
+| `PHONE_NUMBER` | string | `"13800138000"` |
+| `EMAIL` | string | `"user@example.com"` |
+| `BARCODE` | string | `"978-3-16-148410-0"` |
+| `LOCATION` | CellLocationValue 数组（限 1 个） | `[{"source_type": 1, "id": "xxx", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]` |
+
+> **Option 格式说明**：`SINGLE_SELECT`/`SELECT` 的选项支持 `style` 字段（1~27 对应不同颜色），如 `[{"text": "紧急", "style": 1}]`。`style` 为可选字段，不传则使用默认颜色。
+
+### 易错点
+
+- `DATE_TIME` 的值是**日期时间字符串**，支持 `"YYYY-MM-DD HH:MM:SS"`（精确到秒）、`"YYYY-MM-DD HH:MM"`（精确到分）、`"YYYY-MM-DD"`（精确到天），系统自动按东八区转换为时间戳，无需手动计算
+- `CellUrlValue` 的链接字段名是 **`link`**，不是 `url`
+- `TEXT` 类型的值**必须**使用数组格式 `[{"type": "text", "text": "内容"}]`，外层方括号不可省略，不能传单个对象 `{"type":"text","text":"内容"}`
+- `SINGLE_SELECT`/`SELECT` 类型的值**必须**使用数组格式 `[{"text": "选项内容"}]`，不能直接传字符串
+- `PROGRESS` 的值范围是 **0~100 整数**（85 = 85%）；`PERCENTAGE` 的值范围是 **0~1**（0.85 = 85%），两者不同注意区分
+- `wedoc_smartsheet_update_fields` **不能更改字段类型**，只能改标题和属性
+- `values` 的 key **必须**使用**字段标题**（field_title），**不能**使用 field_id
+- 不可写入的字段类型：创建时间、最后编辑时间、创建人、最后编辑人
+
+## 错误处理
+
+### MCP 错误响应处理（重要）
+
+当 `mcporter call` 返回结果中 `errcode` 不为 0 且 `help_message` 有值时，将 `help_message` 中面向用户的内容输出给用户。
+
+**输出原则：**
+
+- **完整性**：不截断、不摘要
+- **原样性**：不改写、不重新排版
+- **用户可读性**：只输出面向用户的内容，过滤掉给 Agent 的元指令（如"将以下内容告知用户"等引导语）；直接以 markdown 形式输出，不要包裹在代码块中
+
+### 错误码 850001：需要用户提供配置
+
+当 `errcode` 为 `850001` 时：
+
+1. 将 `help_message` 中面向用户的内容**原样输出**（遵循上方输出原则）
+2. 输出后**等待用户回复**，后续流程与「MCP Server 未配置」的场景 A / B / C 一致。配置成功后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
+
+### MCP Server 未配置
+
+如果 `mcporter call wecom-doc.*` 或 `mcporter list wecom-doc` 返回 **server not found**、**unknown server** 或类似错误，说明 wecom-doc MCP server 尚未配置。
+
+此时需要**检测运行环境**以提供针对性的提示。按以下步骤执行：
+
+#### 步骤一：检测是否在 OpenClaw 运行时中
+
+通过检测 `OPENCLAW_SHELL` 环境变量判断当前是否运行在 OpenClaw 中。该变量是 OpenClaw **运行时自动注入到子进程**中的标记，不会因为机器上安装了 openclaw 就存在——只有 skill 确实在 OpenClaw 中被调用时，exec 执行的命令才会携带此变量。
+
+```bash
+echo "OPENCLAW_SHELL=${OPENCLAW_SHELL:-}" && command -v openclaw 2>/dev/null && echo "OPENCLAW_CLI=FOUND" || echo "OPENCLAW_CLI=NOT_FOUND"
+```
+
+判断规则：
+- **`OPENCLAW_SHELL` 为空**（输出 `OPENCLAW_SHELL=`）→ 当前不在 OpenClaw 运行时中，跳到**「通用提示」**。
+- **`OPENCLAW_SHELL` 非空**（如 `exec`、`tui-local` 等）**且** `OPENCLAW_CLI=FOUND` → 确认在 OpenClaw 中且 CLI 可用，继续步骤二。
+- **`OPENCLAW_SHELL` 非空但 `OPENCLAW_CLI=NOT_FOUND`** → 虽然在 OpenClaw 中但 CLI 不可用，跳到**「通用提示」**。
+
+> 为什么不能仅用 `command -v openclaw`：同一台机器可能同时安装了 openclaw 和 claude 等其他 AI 工具。仅检测 CLI 是否存在无法区分"装了 openclaw"和"正在 openclaw 中运行"。`OPENCLAW_SHELL` 是进程级的运行时标记，从根本上解决此问题。
+
+#### 步骤二：查询 wecom channel 的 botId 配置
+
+```bash
+openclaw config get channels.wecom.botId 2>&1
+```
+
+- 如果命令返回了**具体的 botId 值**（非空、非报错），保存该值，跳到**「OpenClaw 场景 + 有 botId 提示」**。
+- 如果返回 `Config path not found`、报错或为空，跳到**「通用提示」**。
+
+#### 异常容错
+
+如果上述任何命令执行失败（如 exec 工具不可用、命令超时等），一律跳到**「通用提示」**。
+
+---
+
+#### OpenClaw 场景 + 有 botId 提示
+
+当确认是 OpenClaw 环境且获取到了 botId 时，**必须原样输出以下提示**（不要修改、不要摘要），将 `XXXX` 替换为实际获取到的 botId 值：
+
+> 若你是智能机器人创建者，可以[点击这里](https://work.weixin.qq.com/ai/aiHelper/authorizationPage?str_aibotid=XXXX&from=chat&forceInnerBrowser=1)授权当前机器人文档使用权限；
+> 若你不是机器人创建者，可联系该机器人创建者，前往企业微信「工作台-智能机器人」找到对应机器人进行授权
+> 若你已授权，可将对应机器人文档MCP的接入配置（StreamableHttp URL或者JSON Config）发送给我
+
+输出提示后**等待用户回复**，后续流程与下方「通用提示」的后续流程一致（场景 A / B / C）。配置成功后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
+
+---
+
+#### 通用提示
+
+当非 OpenClaw 环境、无法判断环境、或 OpenClaw 环境但未配置 wecom channel / botId 时，**必须原样输出以下提示文案**（不要修改、不要摘要）：
+
+> 机器人可通过MCP方式调用文档相关能力，当前暂未完成所需配置。请参考以下配置指引：
+>
+> 1. 请前往「企业微信-工作台-智能机器人应用」，以API模式创建机器人（如已创建，可忽略该步骤）
+>
+> 2. 授权该机器人「文档」使用权限。授权后，可自行选择StreamableHttp URL 或 JSON Config 进行配置。
+
+输出提示后**等待用户回复**。用户可能：
+
+**场景 A：用户提供了 StreamableHttp URL**
+
+从用户消息中提取 URL，执行：
+
+```bash
+mcporter config add wecom-doc \
+  --type streamable-http \
+  --url "<用户提供的URL>"
+```
+
+配置完成后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
+
+**场景 B：用户提供了 JSON 配置**
+
+如果用户提供了类似以下格式的 JSON：
+
+```json
+{
+  "name": "wecom-doc",
+  "type": "streamable-http",
+  "url": "http://xxx"
+}
+```
+
+从 JSON 中提取 `url` 字段，执行：
+
+```bash
+mcporter config add wecom-doc \
+  --type streamable-http \
+  --url "<从JSON提取的url>"
+```
+
+配置完成后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
+
+**场景 C：用户自行完成了配置**
+
+用户可能在管理后台或其他途径自行完成配置后告知已配置好，此时直接继续执行原来的操作。
+
+> **配置检测**：当用户输入的内容包含 URL（如 `http://...`）或 JSON（含 `"type": "streamable-http"`），应判断用户意图是在提供 MCP server 配置信息，自动执行配置命令。
+
+### Daemon 未启动
+
+如果返回 **connection refused** 或 **daemon not running** 错误，提示用户：
+
+```bash
+mcporter daemon start
+```
+
+
+## 注意事项
+
+- 所有调用通过 `mcporter call wecom-doc.<tool>` 执行，不要直接调用企业微信 API
+- `create_doc` 返回的 `docid` 需要保存，后续操作依赖此 ID
+- 添加记录前**必须**先 `smartsheet_get_fields` 获取字段元信息

package/skills/wecom-doc/references/doc-api.md

@@ -0,0 +1,224 @@
+# 企业微信文档 API 参考
+
+## 文档类型
+
+| doc_type | 类型 | doc_id 前缀 | URL 路径 |
+|----------|------|------------|---------|
+| 3 | 文档 | `w3_` | `/doc/` |
+| 10 | 智能表格 | `s3_` | `/smartsheet/` |
+
+## URL 格式
+
+### 文档
+
+```
+https://doc.weixin.qq.com/doc/{doc_id}?scode=xxx
+```
+
+示例：
+```
+https://doc.weixin.qq.com/doc/w3_AMEA4QYkACkCNN7hNRzRzQkaElHbQ?scode=AJEAIQdfAAodYknI73AMEA4QYkACk
+→ doc_id = w3_AMEA4QYkACkCNN7hNRzRzQkaElHbQ
+```
+
+### 智能表格
+
+```
+https://doc.weixin.qq.com/smartsheet/{doc_id}
+```
+
+示例：
+```
+https://doc.weixin.qq.com/smartsheet/s3_ATAA_QaoAKQCNIQ6XYeEYQ3q5Rv05
+→ doc_id = s3_ATAA_QaoAKQCNIQ6XYeEYQ3q5Rv05
+```
+
+> 始终忽略 `?` 之后的查询参数。
+
+## 智能表格字段类型（FieldType）
+
+完整 16 种类型：
+
+| 枚举值 | 说明 |
+|--------|------|
+| `FIELD_TYPE_TEXT` | 文本 |
+| `FIELD_TYPE_NUMBER` | 数字 |
+| `FIELD_TYPE_CHECKBOX` | 复选框 |
+| `FIELD_TYPE_DATE_TIME` | 日期时间 |
+| `FIELD_TYPE_IMAGE` | 图片 |
+| `FIELD_TYPE_USER` | 成员 |
+| `FIELD_TYPE_URL` | 链接 |
+| `FIELD_TYPE_SELECT` | 多选 |
+| `FIELD_TYPE_SINGLE_SELECT` | 单选 |
+| `FIELD_TYPE_PROGRESS` | 进度 |
+| `FIELD_TYPE_PHONE_NUMBER` | 手机号 |
+| `FIELD_TYPE_EMAIL` | 邮箱 |
+| `FIELD_TYPE_LOCATION` | 位置 |
+| `FIELD_TYPE_CURRENCY` | 货币 |
+| `FIELD_TYPE_PERCENTAGE` | 百分比 |
+| `FIELD_TYPE_BARCODE` | 条码 |
+
+## CellValue 类型完整对照
+
+### CellTextValue — 文本字段
+
+```json
+[
+  {"type": "text", "text": "普通文本"},
+  {"type": "url", "text": "链接文本", "link": "https://example.com"}
+]
+```
+
+- `type`（必填）：`"text"` 或 `"url"`
+- `text`（必填）：文本内容
+- `link`（当 type 为 url 时）：链接跳转 URL
+
+适用：`FIELD_TYPE_TEXT`
+
+### 数字类 — number
+
+直接传 number 值。
+
+```json
+85
+```
+
+适用：`FIELD_TYPE_NUMBER`、`FIELD_TYPE_PROGRESS`、`FIELD_TYPE_CURRENCY`、`FIELD_TYPE_PERCENTAGE`
+
+### 布尔值 — boolean
+
+```json
+true
+```
+
+适用：`FIELD_TYPE_CHECKBOX`
+
+### 字符串类 — string
+
+直接传字符串。
+
+适用场景：
+- `FIELD_TYPE_DATE_TIME`：毫秒 unix 时间戳字符串，如 `"1672531200000"`
+- `FIELD_TYPE_PHONE_NUMBER`：手机号字符串，如 `"13800138000"`
+- `FIELD_TYPE_EMAIL`：邮箱字符串，如 `"user@example.com"`
+- `FIELD_TYPE_BARCODE`：条码字符串，如 `"978-3-16-148410-0"`
+
+### CellUrlValue — 链接字段
+
+```json
+[{"type": "url", "text": "显示文本", "link": "https://example.com"}]
+```
+
+- `type`（必填）：固定 `"url"`
+- `link`（必填）：链接跳转 URL
+- `text`（可选）：链接显示文本
+
+> 注意：字段名是 **`link`** 不是 `url`。数组为预留能力，目前只支持 1 个链接。
+
+适用：`FIELD_TYPE_URL`
+
+### CellUserValue — 成员字段
+
+```json
+[{"user_id": "zhangsan"}]
+```
+
+- `user_id`（必填）：成员 ID
+
+适用：`FIELD_TYPE_USER`
+
+### CellImageValue — 图片字段
+
+```json
+[{
+  "id": "img1",
+  "title": "截图",
+  "image_url": "https://...",
+  "width": 800,
+  "height": 600
+}]
+```
+
+- `id`：图片 ID（自定义）
+- `title`：图片标题
+- `image_url`：图片链接（通过上传图片接口获取）
+- `width` / `height`：图片尺寸
+
+适用：`FIELD_TYPE_IMAGE`
+
+### CellAttachmentValue — 文件字段
+
+```json
+[{
+  "name": "文件名",
+  "size": 1024,
+  "file_ext": "DOC",
+  "file_id": "xxx",
+  "file_url": "https://...",
+  "file_type": "50"
+}]
+```
+
+- `file_ext` 取值：`DOC`、`SHEET`、`SLIDE`、`MIND`、`FLOWCHART`、`SMARTSHEET`、`FORM`，或文件扩展名
+- `file_type` 取值：`Folder`（文件夹）、`Wedrive`（微盘文件）、`30`（收集表）、`50`（文档）、`51`（表格）、`52`（幻灯片）、`54`（思维导图）、`55`（流程图）、`70`（智能表）
+
+### Option — 选项（单选/多选字段）
+
+```json
+[{"text": "选项A", "style": 1}, {"text": "选项B", "style": 5}]
+```
+
+- `text`：选项内容。新增选项时填写，已存在时优先匹配
+- `id`（可选）：选项 ID，已存在的选项通过 ID 识别
+- `style`（可选）：选项颜色，1-27
+
+适用：`FIELD_TYPE_SELECT`（多选，可传多个）、`FIELD_TYPE_SINGLE_SELECT`（单选，建议传 1 个）
+
+### CellLocationValue — 位置字段
+
+```json
+[{
+  "source_type": 1,
+  "id": "地点ID",
+  "latitude": "39.9042",
+  "longitude": "116.4074",
+  "title": "北京天安门"
+}]
+```
+
+- `source_type`（必填）：固定 `1`（腾讯地图）
+- `id`（必填）：地点 ID
+- `latitude`（必填）：纬度（字符串）
+- `longitude`（必填）：经度（字符串）
+- `title`（必填）：地点名称
+
+> 数组长度不大于 1。
+
+适用：`FIELD_TYPE_LOCATION`
+
+## 选项样式（Style）
+
+取值 1-27 对应颜色：
+
+| 值 | 颜色 | 值 | 颜色 | 值 | 颜色 |
+|----|------|----|------|----|------|
+| 1 | 浅红 | 10 | 浅蓝 | 19 | 浅橙 |
+| 2 | 浅橙 | 11 | 浅蓝 | 20 | 橙 |
+| 3 | 浅天蓝 | 12 | 蓝 | 21 | 浅黄 |
+| 4 | 浅绿 | 13 | 浅天蓝 | 22 | 浅黄 |
+| 5 | 浅紫 | 14 | 天蓝 | 23 | 黄 |
+| 6 | 浅粉红 | 15 | 浅绿 | 24 | 浅紫 |
+| 7 | 浅灰 | 16 | 绿 | 25 | 紫 |
+| 8 | 白 | 17 | 浅红 | 26 | 浅粉红 |
+| 9 | 灰 | 18 | 红 | 27 | 粉红 |
+
+## 限制
+
+| 维度 | 限制 |
+|------|------|
+| 文档名称 | 最多 255 字符 |
+| 子表字段数 | 单表最多 150 个 |
+| 记录数 | 单表最多 100,000 行 |
+| 单元格数 | 单表最多 15,000,000 个 |
+| 单次添加记录 | 建议 500 行内 |
+| 不可写入字段 | 创建时间、最后编辑时间、创建人、最后编辑人 |

package/src/mcp-config.ts

@@ -0,0 +1,183 @@
+/**
+ * MCP 配置拉取与持久化模块
+ *
+ * 负责:
+ * - 通过 WSClient 发送 aibot_get_mcp_config 请求
+ * - 解析服务端响应，提取 MCP 配置 (url、type、is_authed)
+ * - 将配置写入 ~/.openclaw/wecomConfig/config.json 的 mcpConfig 字段
+ */
+
+import os from "os";
+import path from "path";
+import type { WSClient } from "@wecom/aibot-node-sdk";
+import { generateReqId } from "@wecom/aibot-node-sdk";
+import {
+    readJsonFileWithFallback,
+    writeJsonFileAtomically,
+    withFileLock,
+} from "openclaw/plugin-sdk";
+import type { WecomRuntimeEnv } from "./monitor/types.js";
+import { withTimeout } from "./timeout.js";
+
+// ============================================================================
+// 常量
+// ============================================================================
+
+/** 获取 MCP 配置的 WebSocket 命令 */
+const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
+
+/** MCP 配置拉取超时时间（毫秒） */
+const MCP_CONFIG_FETCH_TIMEOUT_MS = 15_000;
+
+// ============================================================================
+// 类型
+// ============================================================================
+
+/**
+ * MCP 配置响应体
+ */
+export interface McpConfigBody {
+    /** MCP Server 的 StreamableHttp URL */
+    url: string;
+    /** 连接类型，如 "doc" */
+    type?: string;
+    /** 是否已授权 */
+    is_authed?: boolean;
+}
+
+// ============================================================================
+// MCP 配置拉取
+// ============================================================================
+
+/**
+ * 通过 WSClient 发送 aibot_get_mcp_config 命令，获取 MCP 配置
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @returns MCP 配置 (url、type、is_authed)
+ * @throws 响应错误码非 0 或缺少 url 字段时抛出错误
+ */
+export async function fetchMcpConfig(
+    wsClient: WSClient,
+): Promise<McpConfigBody> {
+    const reqId = generateReqId("mcp_config");
+
+    // 通过 reply 方法发送自定义命令
+    const response = await withTimeout(
+        wsClient.reply(
+            { headers: { req_id: reqId } },
+            { biz_type: "doc" },
+            MCP_GET_CONFIG_CMD,
+        ),
+        MCP_CONFIG_FETCH_TIMEOUT_MS,
+        `MCP config fetch timed out after ${MCP_CONFIG_FETCH_TIMEOUT_MS}ms`,
+    );
+
+    // 校验响应错误码
+    if (response.errcode && response.errcode !== 0) {
+        throw new Error(
+            `MCP config request failed: errcode=${response.errcode}, errmsg=${response.errmsg ?? "unknown"}`,
+        );
+    }
+
+    // 提取并校验 body
+    const body = response.body as McpConfigBody | undefined;
+    if (!body?.url) {
+        throw new Error(
+            "MCP config response missing required 'url' field",
+        );
+    }
+
+    return {
+        url: body.url,
+        type: "doc",
+        is_authed: body.is_authed,
+    };
+}
+
+// ============================================================================
+// 配置持久化
+// ============================================================================
+
+/**
+ * 将 MCP 配置写入 ~/.openclaw/wecomConfig/config.json 的 mcpConfig 字段
+ *
+ * 使用 OpenClaw SDK 提供的文件锁和原子写入，保证并发安全。
+ * 配置格式: { mcpConfig: { [type]: { type, url } } }
+ */
+async function saveMcpConfigToPluginJson(
+    config: McpConfigBody,
+    runtime: WecomRuntimeEnv,
+): Promise<void> {
+    const wecomConfigDir = path.join(os.homedir(), ".openclaw", "wecomConfig");
+    const wecomConfigPath = path.join(wecomConfigDir, "config.json");
+
+    const lockOptions = {
+        stale: 60_000,
+        retries: {
+            retries: 6,
+            factor: 1.35,
+            minTimeout: 8,
+            maxTimeout: 1200,
+            randomize: true,
+        },
+    };
+
+    await withFileLock(wecomConfigPath, lockOptions, async () => {
+        // 读取现有配置（不存在时使用空对象）
+        const { value: pluginJson } = await readJsonFileWithFallback<Record<string, unknown>>(
+            wecomConfigPath,
+            {},
+        );
+
+        // 确保 mcpConfig 字段存在且为对象
+        if (!pluginJson.mcpConfig || typeof pluginJson.mcpConfig !== "object") {
+            pluginJson.mcpConfig = {};
+        }
+
+        // 使用 type 作为键存储配置
+        const typeKey = config.type || "default";
+        (pluginJson.mcpConfig as Record<string, unknown>)[typeKey] = {
+            type: config.type,
+            url: config.url,
+        };
+
+        // 原子写入
+        await writeJsonFileAtomically(wecomConfigPath, pluginJson);
+
+        runtime.log?.(`[WeCom] MCP config saved to ${wecomConfigPath}`);
+    });
+}
+
+// ============================================================================
+// 组合入口
+// ============================================================================
+
+/**
+ * 拉取 MCP 配置并持久化到 ~/.openclaw/wecomConfig/config.json
+ *
+ * 认证成功后调用。失败仅记录日志，不影响 WebSocket 消息正常收发。
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @param accountId - 账户 ID（用于日志）
+ * @param runtime - 运行时环境（用于日志）
+ */
+export async function fetchAndSaveMcpConfig(
+    wsClient: WSClient,
+    accountId: string,
+    runtime: WecomRuntimeEnv,
+): Promise<void> {
+    try {
+        runtime.log?.(`[${accountId}] Fetching MCP config...`);
+
+        const config = await fetchMcpConfig(wsClient);
+        runtime.log?.(
+            `[${accountId}] MCP config fetched: url=${config.url}, type=${config.type ?? "N/A"}, is_authed=${config.is_authed ?? "N/A"}`,
+        );
+
+        await saveMcpConfigToPluginJson(config, runtime);
+    } catch (err) {
+        runtime.error?.(
+            `[${accountId}] Failed to fetch/save MCP config: ${String(err)}`,
+        );
+    }
+}

package/src/monitor.ts

@@ -1198,6 +1198,9 @@ async function startAgentForStream(params: {
   const config = target.config;
   const account = target.account;
 
+  // WS 长连接模式标记：跳过 Webhook 专属的 Agent 私信兜底逻辑
+  const isWsMode = Boolean(streamStore.getStream(streamId)?.wsMode);
+
   const userid = resolveWecomSenderUserId(msg) || "unknown";
   const chatType = msg.chattype === "group" ? "group" : "direct";
   const chatId = msg.chattype === "group" ? (msg.chatid?.trim() || "unknown") : userid;
@@ -1298,7 +1301,21 @@ async function startAgentForStream(params: {
         return;
       }
 
-      // 图片路径都读取失败时，切换到 Agent 私信兜底，并主动结束 Bot 流。
+      // 图片路径都读取失败时的兜底处理
+      if (isWsMode) {
+        // WS 模式：不走 Agent 私信兜底，直接提示错误并结束
+        const fallbackName = imagePaths.length === 1
+          ? (imagePaths[0]!.split("/").pop() || "image")
+          : `${imagePaths.length} 张图片`;
+        streamStore.updateStream(streamId, (s) => {
+          s.finished = true;
+          s.content = `图片读取失败（${fallbackName}），请重试。`;
+        });
+        streamStore.onStreamFinished(streamId);
+        return;
+      }
+
+      // Webhook 模式：切换到 Agent 私信兜底，并主动结束 Bot 流。
       const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
       const agentOk = Boolean(agentCfg);
       const fallbackName = imagePaths.length === 1
@@ -1355,6 +1372,18 @@ async function startAgentForStream(params: {
 
     // 2) 非图片文件：Bot 会话里提示 + Agent 私信兜底（目标锁定 userId）
     if (otherPaths.length > 0) {
+      if (isWsMode) {
+        // WS 模式：不走 Agent 私信兜底，提示文件路径
+        const filename = otherPaths.length === 1 ? otherPaths[0]!.split("/").pop()! : `${otherPaths.length} 个文件`;
+        streamStore.updateStream(streamId, (s) => {
+          s.finished = true;
+          s.content = `已生成文件（${filename}），文件路径：${otherPaths.join(", ")}`;
+        });
+        streamStore.onStreamFinished(streamId);
+        return;
+      }
+
+      // Webhook 模式：Agent 私信兜底
       const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
       const agentOk = Boolean(agentCfg);
 
@@ -1781,7 +1810,7 @@ async function startAgentForStream(params: {
         const now = Date.now();
         const deadline = current.createdAt + BOT_WINDOW_MS;
         const switchAt = deadline - BOT_SWITCH_MARGIN_MS;
-        const nearTimeout = !current.fallbackMode && !current.finished && now >= switchAt;
+        const nearTimeout = !isWsMode && !current.fallbackMode && !current.finished && now >= switchAt;
         if (nearTimeout) {
           const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
           const agentOk = Boolean(agentCfg);
@@ -1840,7 +1869,14 @@ async function startAgentForStream(params: {
               current.images.push({ base64, md5 });
               logVerbose(target, `media: 识别为图片 contentType=${contentType} filename=${filename}`);
             } else {
-              // Non-image media: Bot 不支持原样发送（尤其群聊），统一切换到 Agent 私信兜底，并在 Bot 会话里提示用户。
+              // Non-image media: Bot 不支持原样发送（尤其群聊）
+              if (isWsMode) {
+                // WS 模式：不走 Agent 私信兜底，跳过非图片媒体
+                logVerbose(target, `media: WS 模式跳过 Agent 私信兜底 filename=${filename} contentType=${contentType ?? "unknown"}`);
+                continue;
+              }
+
+              // Webhook 模式：统一切换到 Agent 私信兜底，并在 Bot 会话里提示用户。
               const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
               const agentOk = Boolean(agentCfg);
               const alreadySent = current.agentMediaKeys.includes(mediaPath);
@@ -1892,40 +1928,42 @@ async function startAgentForStream(params: {
             }
           } catch (err) {
             target.runtime.error?.(`Failed to process outbound media: ${mediaPath}: ${String(err)}`);
-            const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
-            const agentOk = Boolean(agentCfg);
-            const fallbackFilename = filename || mediaPath.split("/").pop() || "attachment";
-            if (agentCfg && current.userId && !current.agentMediaKeys.includes(mediaPath)) {
-              try {
-                await sendAgentDmMedia({
-                  agent: agentCfg,
+            if (!isWsMode) {
+              // Webhook 模式：Agent 私信兜底
+              const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
+              const agentOk = Boolean(agentCfg);
+              const fallbackFilename = filename || mediaPath.split("/").pop() || "attachment";
+              if (agentCfg && current.userId && !current.agentMediaKeys.includes(mediaPath)) {
+                try {
+                  await sendAgentDmMedia({
+                    agent: agentCfg,
+                    userId: current.userId,
+                    mediaUrlOrPath: mediaPath,
+                    contentType,
+                    filename: fallbackFilename,
+                  });
+                  streamStore.updateStream(streamId, (s) => {
+                    s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), mediaPath]));
+                  });
+                  logVerbose(target, `fallback(error): 媒体处理失败后已通过 Agent 私信发送 user=${current.userId}`);
+                } catch (sendErr) {
+                  target.runtime.error?.(`fallback(error): 媒体处理失败后的 Agent 私信发送也失败: ${String(sendErr)}`);
+                }
+              }
+              if (!current.fallbackMode) {
+                const prompt = buildFallbackPrompt({
+                  kind: "error",
+                  agentConfigured: agentOk,
                   userId: current.userId,
-                  mediaUrlOrPath: mediaPath,
-                  contentType,
                   filename: fallbackFilename,
+                  chatType: current.chatType,
                 });
                 streamStore.updateStream(streamId, (s) => {
-                  s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), mediaPath]));
+                  s.fallbackMode = "error";
+                  s.finished = true;
+                  s.content = prompt;
+                  s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
                 });
-                logVerbose(target, `fallback(error): 媒体处理失败后已通过 Agent 私信发送 user=${current.userId}`);
-              } catch (sendErr) {
-                target.runtime.error?.(`fallback(error): 媒体处理失败后的 Agent 私信发送也失败: ${String(sendErr)}`);
-              }
-            }
-            if (!current.fallbackMode) {
-              const prompt = buildFallbackPrompt({
-                kind: "error",
-                agentConfigured: agentOk,
-                userId: current.userId,
-                filename: fallbackFilename,
-                chatType: current.chatType,
-              });
-              streamStore.updateStream(streamId, (s) => {
-                s.fallbackMode = "error";
-                s.finished = true;
-                s.content = prompt;
-                s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
-              });
               try {
                 await sendBotFallbackPromptNow({ streamId, text: prompt });
                 logVerbose(target, `fallback(error): 群内提示已推送`);
@@ -1933,6 +1971,9 @@ async function startAgentForStream(params: {
                 target.runtime.error?.(`wecom bot fallback prompt push failed (error) streamId=${streamId}: ${String(pushErr)}`);
               }
             }
+            } // end if (!isWsMode)
+            // WS 模式：媒体处理失败时 continue 尝试下一个媒体，Webhook 模式 return 退出
+            if (isWsMode) continue;
             return;
           }
         }
@@ -1982,7 +2023,7 @@ async function startAgentForStream(params: {
 
   // Timeout fallback final delivery (Agent DM): send once after the agent run completes.
   const finishedState = streamStore.getStream(streamId);
-  if (finishedState?.fallbackMode === "timeout" && !finishedState.finalDeliveredAt) {
+  if (finishedState?.fallbackMode === "timeout" && !finishedState.finalDeliveredAt && !isWsMode) {
     const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
     if (!agentCfg) {
       // Agent not configured - group prompt already explains the situation.

package/src/timeout.ts

@@ -0,0 +1,45 @@
+/**
+ * 超时控制工具模块
+ *
+ * 为异步操作提供统一的超时保护机制
+ */
+
+/**
+ * 为 Promise 添加超时保护
+ *
+ * @param promise - 原始 Promise
+ * @param timeoutMs - 超时时间（毫秒）
+ * @param message - 超时错误消息
+ * @returns 带超时保护的 Promise
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  message?: string,
+): Promise<T> {
+  if (timeoutMs <= 0 || !Number.isFinite(timeoutMs)) {
+    return promise;
+  }
+
+  let timeoutId: ReturnType<typeof setTimeout>;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new TimeoutError(message ?? `Operation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timeoutId);
+  });
+}
+
+/**
+ * 超时错误类型
+ */
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}

package/src/ws-adapter.ts

@@ -32,6 +32,12 @@ import type { WecomRuntimeEnv, WecomWebhookTarget, StreamState } from "./monitor
 import { shouldProcessBotInboundMessage, buildInboundBody } from "./monitor.js";
 import { monitorState } from "./monitor/state.js";
 import { getWecomRuntime } from "./runtime.js";
+import { fetchAndSaveMcpConfig } from "./mcp-config.js";
+
+// ─── Constants ─────────────────────────────────────────────────────────
+
+/** "思考中" 占位消息，让用户立即看到机器人正在响应 */
+const THINKING_MESSAGE = "<think></think>";
 
 // ─── WSClient Instance Registry ────────────────────────────────────────
 
@@ -265,6 +271,16 @@ function setupMessageHandler(params: {
             s.wsMode = true;
         });
 
+        // 立即发送"思考中"占位消息，让用户看到即时反馈
+        const sendThinking = (target.account.config as any).sendThinkingMessage ?? true;
+        if (sendThinking) {
+            wsClient.replyStream(frame, streamId, THINKING_MESSAGE, false).catch((err) => {
+                target.runtime.error?.(
+                    `[${accountId}] ws-thinking: failed to send thinking message: ${String(err)}`,
+                );
+            });
+        }
+
         // 注册流式回复监听器
         watchStreamReply({
             wsClient,
@@ -448,6 +464,8 @@ export function startWsClient(params: StartWsClientParams): () => void {
     });
     wsClient.on("authenticated", () => {
         runtime.log?.(`[${accountId}] ws: authenticated successfully`);
+        // 认证成功后拉取 MCP 配置（非阻塞，失败仅记日志）
+        void fetchAndSaveMcpConfig(wsClient, accountId, runtime);
     });
     wsClient.on("disconnected", (reason: string) => {
         runtime.log?.(`[${accountId}] ws: disconnected - ${reason}`);