@wecom/wecom-openclaw-plugin 2026.5.7-beta.0 → 2026.5.14-beta.0

package/openclaw.plugin.json

@@ -3,6 +3,11 @@
   "channels": [
     "wecom"
   ],
+  "contracts": {
+    "tools": [
+      "wecom_mcp"
+    ]
+  },
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.5.7-beta.0",
+  "version": "2026.5.14-beta.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,7 +24,8 @@
     "release": "node scripts/publish-all.mjs",
     "release:dry": "node scripts/publish-all.mjs --dry-run",
     "release:ci": "node scripts/publish-all.mjs --yes --restore=no",
-    "deploy:local": "bash scripts/dev-deploy.sh"
+    "deploy:local": "bash scripts/dev-deploy.sh",
+    "deploy:local:extensions": "bash scripts/dev-deploy.sh --target=extensions"
   },
   "keywords": [
     "wecom",

package/skills/{wecom-contact-lookup → wecom-contact}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wecom-contact-lookup
+name: wecom-contact
 description: 通讯录成员查询技能，基于 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。
 ---
 

package/skills/{wecom-doc-manager → wecom-doc}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wecom-doc-manager
+name: wecom-doc
 description: 企业微信文档管理技能。支持企业微信文档、智能表格和智能文档（原名智能主页）的管理。具体能力：(1) 获取文档或智能表格的完整内容，以 Markdown 格式导出 (2) 新建文档或智能表格 (3) 用 Markdown 覆写文档内容 (4) 创建智能文档，将本地 Markdown 文件发布为智能文档 (5) 导出智能文档内容为 Markdown 文件。
 ---
 
@@ -51,7 +51,9 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 | errcode | errmsg | 含义 | 处理方式 |
 |---------|--------|------|----------|
 | `851002` | `incompatible doc type` | 文档品类与所调用的接口不匹配 | 根据文档 URL 重新确认品类（参见上方「URL 品类识别与接口路由」表），然后使用该品类对应的正确接口重试 |
-| `851003` | `no authority` | 无权限调用该接口，**智能表格写入场景**下通常是企业可见范围 > 10 人的规模限制 | 若发生在需要写入数据的场景，引导用户走 Webhook 兜底方案，详见 [webhook-fallback.md](../wecom-smartsheet-data/references/webhook-fallback.md)；其他接口则按权限问题排查 |
+| `851003` | `no authority` | 无权限调用该接口，**智能表格写入场景**下通常是企业可见范围 > 10 人的规模限制 | 若发生在需要写入数据的场景，引导用户走 Webhook 兜底方案，详见 [webhook-fallback.md](../wecom-smartsheet/references/webhook-fallback.md)；其他接口则按权限问题排查 |
+
+---
 
 ## 文档
 
@@ -71,18 +73,20 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 - 轮询（携带上次返回的 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'`
 - 或通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/doc/xxx", "type": 2}'`
 
-参见 [API 详情](references/api-export-document.md)。
+参见 [API 详情](references/get-doc-content.md)。
 
 ### create_doc
 
 新建文档（doc_type=3）或智能表格（doc_type=10）。创建成功返回 url 和 docid。
 
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "项目周报"}'`
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "任务跟踪表"}'`
+- 创建文档：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "项目周报"}'`
+- 创建智能表格：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "任务跟踪表"}'`
 
-**注意**：docid 仅在创建时返回，需妥善保存。创建智能表格时默认包含一个子表，可通过 `smartsheet_get_sheet` 查询其 sheet_id。
+**注意**：
+- docid 仅在创建时返回，需妥善保存。创建智能表格时默认包含一个子表
+- 智能表格（doc_type=10）的详细管理功能（子表、字段、数据记录等）已迁移到 `wecom-smartsheet` skill，请使用该 skill 进行高级操作
 
-参见 [API 详情](references/api-create-doc.md)。
+参见 [API 详情](references/create-doc.md)。
 
 ### edit_doc_content
 
@@ -90,7 +94,9 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc edit_doc_content '{"docid": "DOCID", "content": "# 标题\n\n正文内容", "content_type": 1}'`
 
-参见 [API 详情](references/api-edit-doc-content.md)。
+参见 [API 详情](references/edit-doc-content.md)。
+
+---
 
 ## 智能文档（原名智能主页）
 
@@ -101,7 +107,7 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 
 适用场景：
 1. 将本地 Markdown 文件创建为智能文档
-2. 异步导出智能文档内容为 Markdown 文件
+2. 异步导出智能文档内容为 Markdown
 
 ### smartpage_create
 
@@ -114,15 +120,16 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 - docid 仅在创建时返回，需妥善保存
 - 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败。如果文件过大，需先拆分为多个子页面再创建
 
-参见 [API 详情](references/api-smartpage-create.md)。
+参见 [API 详情](references/smartpage-create.md)。
 
 ### smartpage_export_task
 
-发起智能文档内容导出任务（异步）。传入 docid 和 content_type，返回 task_id。这是异步导出的第一步，需配合 `smartpage_get_export_result` 轮询获取导出结果。
+发起智能文档内容导出任务（异步）。传入 docid（或 url）和 content_type，返回 task_id。这是异步导出的第一步，需配合 `smartpage_get_export_result` 轮询获取导出结果。
 
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`
+- 通过 docid：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`
+- 或通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"url": "https://doc.weixin.qq.com/smartpage/xxx", "content_type": 1}'`
 
-参见 [API 详情](references/api-smartpage-export-task.md)。
+参见 [API 详情](references/smartpage-export.md)。
 
 ### smartpage_get_export_result
 
@@ -132,17 +139,24 @@ description: 企业微信文档管理技能。支持企业微信文档、智能
 
 当 `task_done` 为 `true` 时，使用 Read 工具读取 `content_filepath` 指向的文件即可获取导出的 Markdown 内容。
 
-参见 [API 详情](references/api-smartpage-get-export-result.md)。
+参见 [API 详情](references/smartpage-export.md)。
+
+---
 
 ## 典型工作流
 
 > **关键提示**：读取内容前先看 URL 判断品类。`/doc/` 或 `/smartsheet/` → `get_doc_content`；`/smartpage/` → `smartpage_export_task`。只有用户明确提到「智能文档」或「智能主页」时才走 smartpage 流程，其他文档场景一律使用企微文档接口。
 
+### 文档操作
+
 1. **读取文档/智能表格内容**（URL 含 `/doc/` 或 `/smartsheet/`） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`，若 `task_done` 为 false 则携带 `task_id` 继续轮询
 2. **创建新文档** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "文档名"}'`，保存返回的 docid
 3. **编辑文档** → 先 get_doc_content 了解当前内容，再 edit_doc_content 覆写
-4. **创建智能文档**（仅当用户明确要求「智能文档」或「智能主页」时） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_create '{"title": "标题", "pages": [{"page_title": "子页面", "content_type": 1, "page_filepath": "/path/to/file.md"}]}'`，保存返回的 docid
-5. **获取智能文档内容**（URL 含 `/smartpage/`，异步两步）：
-   - **第一步**：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`，获取 `task_id`
-   - **第二步**：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_get_export_result '{"task_id": "TASK_ID"}'`，若 `task_done` 为 `false` 则继续轮询，直到 `task_done` 为 `true`
+
+### 智能文档操作
+
+1. **创建智能文档**（仅当用户明确要求「智能文档」或「智能主页」时） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_create '{"title": "标题", "pages": [{"page_title": "子页面", "content_type": 1, "page_filepath": "/path/to/file.md"}]}'`，保存返回的 docid
+2. **获取智能文档内容**（URL 含 `/smartpage/`，异步两步）：
+   - **第一步**：发起导出任务 → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`，获取 `task_id`
+   - **第二步**：轮询导出结果 → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_get_export_result '{"task_id": "TASK_ID"}'`，若 `task_done` 为 `false` 则继续轮询，直到 `task_done` 为 `true`
    - **第三步**：使用 Read 工具读取 `content_filepath` 指向的本地文件，获取 Markdown 内容

package/skills/{wecom-doc-manager/references/api-smartpage-create.md → wecom-doc/references/smartpage-create.md}

@@ -1,6 +1,6 @@
 # smartpage_create API
 
-创建智能文档（原智能主页）。支持传入多个子页面，每个子页面可指定标题、内容类型和文件路径。创建成功后返回文档访问链接和 docid。
+创建智能文档（原智能主页）。支持传入多个子页面，每个子页面可指定标题、内容类型和本地文件路径。创建成功后返回文档访问链接和 docid。
 
 ## 技能定义
 
@@ -58,7 +58,7 @@
 | pages | array | 是 | 子页面列表 |
 | pages[].page_title | string | 否 | 子页面标题 |
 | pages[].content_type | integer | 否 | 内容类型：1-Markdown，0-Text（纯文本）。**默认应传 1**，仅纯文本内容才传 0 |
-| pages[].page_filepath | string | 否 | 子页面内容对应的本地文件路径 |
+| pages[].page_filepath | string | 否 | 子页面内容对应的本地文件路径，需确保文件存在且可读 |
 
 ## ContentType 枚举
 
@@ -67,6 +67,25 @@
 | 1 | Markdown | 文件内容包含 Markdown 语法（标题、列表、链接、代码块等） |
 | 0 | Text（纯文本） | 文件内容为纯文本，不含任何 Markdown 语法 |
 
+除了标准的 markdown 格式以外，智能文档还支持扩展语法以提升表示的丰富性，包括：
+1. 背景块
+```markdown
+<card color="green">
+## 在扩展标签里面可以任意嵌套 markdown 语法
+- 背景块常用于展示重要信息
+- 颜色的使用根据需要表达的语义进行选择，卡片背景由 `color` 指定；支持 `green`, `blue`, `red`, `yellow`, `gray`, `purple`, `orange`, `cyan`, `indigo`，也支持 `dark_green`, `dark_blue`, `dark_red`, `dark_yellow`, `dark_gray`, `dark_purple`, `dark_orange`, `dark_cyan`, `dark_indigo` 等深色系。
+</card>
+```
+背景颜色推荐使用浅色背景，以完成区隔/高亮并且保持低饱和度确保正文内容的良好显示。
+2. 分栏
+使用分栏可以并列显示内容，常用于展示对比或者并列信息
+```markdown
+<grid>
+<area width-ratio="0.5">占据50%的空间</area>
+<area width-ratio="0.5">占据50%的空间</area>
+</grid>
+```
+width-ratio：子容器宽度占比，范围 0.1~1.0，所有的子容器宽度占比之和为 1
 
 ## 请求示例
 
@@ -98,11 +117,9 @@
     "url": "https://doc.weixin.qq.com/smartpage/a1_xxxxxx"
 }
 ```
-
 ## 注意事项
 
-- 响应透传 mcp 回包
 - `docid` 仅在创建时返回，后续无法再获取，务必保存
 - `page_filepath` 指向本地文件，需确保文件存在且可读
 - **`content_type` 必须与文件实际内容格式匹配**：`.md` 文件或包含 Markdown 语法的内容必须传 `1`，不要传 `0`
-- 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败；如果文件过大，需先拆分为多个子页面
+- 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败；如果文件过大，需先拆分为多个子页面

package/skills/wecom-doc/references/smartpage-export.md

@@ -0,0 +1,160 @@
+# smartpage_export_task / smartpage_get_export_result API
+
+导出智能文档（原智能主页）内容。采用异步两步操作：先通过 `smartpage_export_task` 提交导出任务获取 `task_id`，再通过 `smartpage_get_export_result` 轮询任务状态，直到任务完成后返回导出内容的本地文件路径。
+
+---
+
+## 第一步：smartpage_export_task — 提交导出任务
+
+发起智能文档内容导出任务（异步）。传入 `docid` 或 `url` 和 `content_type`，返回 `task_id`。
+
+### 技能定义
+
+```json
+{
+    "name": "smartpage_export_task",
+    "description": "发起智能文档（原智能主页）内容导出任务（异步）。传入 docid（或 url）和 content_type，返回 task_id。需配合 smartpage_get_export_result 轮询查询导出进度，直到任务完成后获取导出文件路径。",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "智能文档的 docid，与 url 二选一传入",
+                "title": "Doc ID",
+                "type": "string"
+            },
+            "url": {
+                "description": "智能文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "content_type": {
+                "description": "导出内容格式。0: Text，1: Markdown",
+                "enum": [0, 1],
+                "title": "Content Type",
+                "type": "integer"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "content_type"] },
+            { "required": ["url", "content_type"] }
+        ],
+        "title": "smartpage_export_taskArguments",
+        "type": "object"
+    }
+}
+```
+
+### 参数说明
+
+| 参数         | 类型    | 必填            | 说明                                          |
+| ------------ | ------- | --------------- | --------------------------------------------- |
+| docid        | string  | 与 url 二选一   | 智能文档的 docid                              |
+| url          | string  | 与 docid 二选一 | 智能文档的访问链接                            |
+| content_type | integer | 是              | 导出内容格式：0-Text，1-Markdown |
+
+### 请求示例
+
+```json
+// 通过 docid
+{
+    "docid": "DOCID",
+    "content_type": 1
+}
+
+// 通过 url
+{
+    "url": "https://doc.weixin.qq.com/smartpage/a1_xxxxxx",
+    "content_type": 1
+}
+```
+
+### 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "task_id": "TASK_ID"
+}
+```
+
+---
+
+## 第二步：smartpage_get_export_result — 查询导出结果
+
+查询智能文档导出任务进度。传入 `task_id` 进行轮询，当 `task_done` 为 `true` 时返回导出内容的本地文件路径。
+
+### 技能定义
+
+```json
+{
+    "name": "smartpage_get_export_result",
+    "description": "查询智能文档（原智能主页）导出任务进度。传入 task_id 轮询，当 task_done 为 true 时返回导出内容的本地文件路径 content_filepath，可通过读取该文件获取 Markdown 内容。",
+    "inputSchema": {
+        "properties": {
+            "task_id": {
+                "description": "导出任务 ID，由 smartpage_export_task 返回",
+                "title": "Task ID",
+                "type": "string"
+            }
+        },
+        "required": ["task_id"],
+        "title": "smartpage_get_export_resultArguments",
+        "type": "object"
+    }
+}
+```
+
+### 参数说明
+
+| 参数    | 类型   | 必填 | 说明                                         |
+| ------- | ------ | ---- | -------------------------------------------- |
+| task_id | string | 是   | 导出任务 ID，由 `smartpage_export_task` 返回 |
+
+### 请求示例
+
+```json
+{
+    "task_id": "TASK_ID"
+}
+```
+
+### 响应示例
+
+任务未完成：
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "task_done": false
+}
+```
+
+任务完成：
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "task_done": true,
+    "content_filepath": "/path/to/exported-content.md"
+}
+```
+
+---
+
+## 异步轮询机制
+
+1. **调用 smartpage_export_task**：传入 `docid`（或 `url`）和 `content_type: 1`，获取 `task_id`
+2. **首次轮询**：传入 `task_id` 调用 `smartpage_get_export_result`
+3. **检查响应**：若 `task_done` 为 `false`，继续轮询
+4. **获取内容**：当 `task_done` 为 `true` 时，读取 `content_filepath` 指向的本地文件获取导出内容
+
+## 注意事项
+
+- `smartpage_export_task` 是异步操作的第一步，调用后仅返回 `task_id`
+- `content_type` 建议使用 `1`（Markdown）以获取可编辑的文本格式
+- `docid` 和 `url` 二选一传入即可，无需同时传入
+- `content_filepath` 仅在 `task_done` 为 `true` 时返回
+- `content_filepath` 是本地文件路径，使用 Read 工具读取文件内容即可
+- 如果轮询多次仍未完成，建议适当增加轮询间隔