@sunnoy/wecom 2.1.0 → 2.2.1

package/README.md

@@ -435,11 +435,15 @@ Webhook 只负责群通知。
 
 ### Workspace 模板
 
-`workspaceTemplate` 目录中的 bootstrap 文件会在动态 Agent 首次创建时复制到工作区：
+`workspaceTemplate` 目录中的模板文件会在动态 Agent 首次创建时复制到工作区：
 
 - `AGENTS.md`、`BOOTSTRAP.md`、`CLAUDE.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`system-prompt.md`
 
-模板支持 mtime 变更检测 — 当模板文件更新后，下次 Agent 启动会增量同步。
+插件会在工作区里写入 `.openclaw/wecom-template-state.json` 记录首次模板同步状态。已有 state 的工作区后续只补缺，不覆盖已有文件。
+
+`BOOTSTRAP.md` 只会在工作区还没有 `memory/` 或 `MEMORY.md` 时参与同步；一旦工作区已经出现记忆痕迹，插件就不再回种 bootstrap，避免打断已完成 onboarding 的会话。
+
+历史工作区如果还没有 state，插件会先补写 state，再按“只补缺、不覆盖”处理，避免存量工作区被重新整批同步。
 
 ### Bindings
 

package/index.js

@@ -1,6 +1,7 @@
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { logger } from "./logger.js";
 import { wecomChannelPlugin } from "./wecom/channel-plugin.js";
+import { createWeComMcpTool } from "./wecom/mcp-tool.js";
 import { setOpenclawConfig, setRuntime } from "./wecom/state.js";
 import { buildReplyMediaGuidance } from "./wecom/ws-monitor.js";
 import { listAccountIds, resolveAccount } from "./wecom/accounts.js";
@@ -16,6 +17,7 @@ const plugin = {
     setRuntime(api.runtime);
     setOpenclawConfig(api.config);
     api.registerChannel({ plugin: wecomChannelPlugin });
+    api.registerTool(createWeComMcpTool(), { name: "wecom_mcp" });
 
     // Register HTTP callback endpoints for all accounts that have callback config
     for (const accountId of listAccountIds(api.config)) {

package/openclaw.plugin.json

@@ -2,6 +2,9 @@
   "id": "wecom",
   "name": "OpenClaw WeCom",
   "description": "Enterprise WeChat (WeCom) messaging channel plugin for OpenClaw",
+  "skills": [
+    "./skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "2.1.0",
+    "version": "2.2.1",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -8,11 +8,12 @@
         "index.js",
         "wecom",
         "dynamic-agent.js",
-        "image-processor.js",
+
         "logger.js",
         "README.md",
         "LICENSE",
         "CONTRIBUTING.md",
+        "skills",
         "think-parser.js",
         "utils.js",
         "openclaw.plugin.json"
@@ -59,6 +60,7 @@
     "author": "",
     "license": "ISC",
     "dependencies": {
-        "@wecom/aibot-node-sdk": "^1.0.1"
+        "@wecom/aibot-node-sdk": "^1.0.2",
+        "file-type": "^21.3.0"
     }
 }

package/skills/wecom-contact-lookup/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: wecom-contact-lookup
+description: 通讯录成员查询技能，基于 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。
+---
+
+# 通讯录成员查询技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取本 skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通该 category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户对应 category 未开通。
+
+通过 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
+
+## 操作
+
+### 1. 获取全量通讯录成员
+
+获取当前用户可见范围内的所有企业成员信息：
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "userlist": [
+        {
+            "userid": "zhangsan",
+            "name": "张三",
+            "alias": "Sam"
+        },
+        {
+            "userid": "lisi",
+            "name": "李四",
+            "alias": ""
+        }
+    ]
+}
+```
+
+**返回字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `userlist` | array | 用户列表 |
+| `userlist[].userid` | string | 用户唯一 ID |
+| `userlist[].name` | string | 用户姓名 |
+| `userlist[].alias` | string | 用户别名，可能为空 |
+
+---
+
+### 2. 按姓名/别名搜索人员
+
+`get_userlist` 返回全量成员后，在本地对结果进行筛选匹配：
+
+- **精确匹配**：`name` 或 `alias` 与关键词完全一致，直接使用
+- **模糊匹配**：`name` 或 `alias` 包含关键词，返回所有匹配结果
+- **无结果**：告知用户未找到对应人员
+
+**搜索示例：**
+
+用户问："帮我找一下张三是谁？"
+
+1. 调用 `get_userlist` 获取全量成员
+2. 在 `userlist` 中筛选 `name` 或 `alias` 包含"张三"的成员
+3. 返回匹配结果
+
+---
+
+## 注意事项
+
+- `get_userlist` 返回的是当前用户**可见范围内**的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 `userid`、`name`（姓名）和 `alias`（别名）
+- ⚠️ **超过 10 人时接口将报错**：若 `userlist` 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
+
+  > 当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
+  > 本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
+  > 建议缩小可见范围后重试，或通过其他方式查询目标人员。
+
+- `userid` 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
+- `alias` 字段可能为空字符串，搜索时需做空值判断
+- 若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
+- 若 `errcode` 不为 `0`，说明接口调用失败，需告知用户错误信息（`errmsg`）
+
+---
+
+## 典型工作流
+
+### 工作流 1：查询人员信息
+
+用户问："帮我查一下 Sam 是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 在结果中筛选 `alias` 为 `Sam` 或 `name` 包含 `Sam` 的成员
+3. 若找到唯一匹配，直接展示结果：
+
+```
+📇 找到成员：
+- 姓名：张三
+- 别名：Sam
+- 用户ID：zhangsan
+```
+
+4. 若找到多个匹配，展示候选列表请用户确认：
+
+```
+🔍 找到多个匹配成员，请确认您要查询的是哪位：
+
+1. 张三（别名：Sam，ID：zhangsan）
+2. 张三丰（别名：Sam2，ID：zhangsan2）
+
+请问您要查询的是哪一位？
+```
+
+---
+
+### 工作流 2：为其他功能提供 userid 转换
+
+用户问："帮我发消息给张三"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员
+
+2. 筛选 `name` 为"张三"的成员，确认 `userid`
+3. 将 `userid` 传递给消息发送接口
+
+---
+
+### 工作流 3：批量查询多个人员
+
+用户问："帮我查一下张三和李四分别是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 分别筛选"张三"和"李四"的匹配结果
+3. 汇总后一并展示
+
+> 注意：只需调用一次 `get_userlist`，在本地对结果进行多次筛选，避免重复调用接口。
+
+---
+
+## 快速参考
+
+### 接口说明
+
+| 接口 | 用途 | 输入 | 返回 |
+|------|------|------|------|
+| `get_userlist` | 获取可见范围内全量通讯录成员 | 无 | 用户列表（userid、name、alias） |
+
+### 本地筛选策略
+
+| 场景 | 策略 |
+|------|------|
+| 精确匹配（name 或 alias 完全一致） | 直接使用，无需用户确认 |
+| 模糊匹配（name 或 alias 包含关键词），唯一结果 | 直接使用，向用户展示结果 |
+| 模糊匹配，多个结果 | 展示候选列表，请用户选择 |
+| 无匹配结果 | 告知用户未找到对应人员 |

package/skills/wecom-doc-manager/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: wecom-doc-manager
+description: 企业微信文档管理技能。提供文档的创建、读取和编辑能力，支持通过 docid 或文档 URL 操作企业微信文档（doc_type=3）和智能表格（doc_type=10）。适用场景：(1) 以 Markdown 格式导出获取文档完整内容（异步轮询） (2) 新建文档或智能表格 (3) 用 Markdown 格式覆写文档内容。当用户需要查看文档内容、创建新文档、编辑文档正文时触发此 Skill。
+---
+
+# 企业微信文档管理
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：仅在当前会话**第一次**准备调用 `wecom_mcp`、且尚未确认工具可用时，按 `wecom-preflight` 技能执行前置条件检查。若当前回合工具列表里已经有 `wecom_mcp`，或当前会话里刚刚成功调用过 `wecom_mcp`，则**不要重复读取 `wecom-preflight`**。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取本 skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通该 category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户对应 category 未开通。
+> - 在读取文档前，先调用 `wecom_mcp` 执行 `list` + `category=doc` 探测当前 bot 实际暴露的 doc 工具列表。只有当列表里确实存在 `get_doc_content` 时，才允许继续调用它。
+> - 如果 `list doc` 的结果中不存在 `get_doc_content`，说明当前 bot 的 doc 类 MCP 仅开放了创建/编辑能力，没有开放读取能力。此时必须立即停止，直接告诉用户“当前文档读取能力未开通”；不要再继续尝试 `get_doc_content`、浏览器抓页面、read/find/exec 探路或 HTML fallback。
+
+管理企业微信文档的创建、读取和编辑。所有接口支持通过 `docid` 或 `url` 二选一定位文档。
+
+## 调用方式
+
+通过 `wecom_mcp` tool 调用，品类为 `doc`：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc <tool_name> '<json_params>'` 调用指定技能
+
+## 返回格式说明
+
+所有接口返回 JSON 对象，包含以下公共字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功，非 `0` 表示失败 |
+| `errmsg` | string | 错误信息，成功时为 `"ok"` |
+
+当 `errcode` 不为 `0` 时，说明接口调用失败，可重试 1 次；若仍失败，将 `errcode` 和 `errmsg` 展示给用户。
+
+### get_doc_content
+
+仅当 `wecom_mcp list doc` 的结果中明确包含 `get_doc_content` 时，才可以使用本接口。
+
+获取文档完整内容数据，只能以 Markdown 格式返回。采用**异步轮询机制**：首次调用无需传 `task_id`，接口返回 `task_id`；若 `task_done` 为 false，需携带该 `task_id` 再次调用，直到 `task_done` 为 true 时返回完整内容。
+
+- 首次调用（不传 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`
+- 轮询（携带上次返回的 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)。
+
+### 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": "任务跟踪表"}'`
+
+**注意**：
+
+- `docid` 仅在创建时返回，需妥善保存。
+- 创建智能表格时默认包含一个子表，可通过 `smartsheet_get_sheet` 查询其 `sheet_id`。
+- **当需要把文档发给用户时，必须原样使用 `create_doc` 返回的完整 `url` 字段。**
+- **不要自行根据 `docid`、短链路径或 `/doc/...` 重新拼接链接。**
+- **不要删除 `url` 里的查询参数，例如 `?scode=...`。**
+- 若最终回复里需要展示链接，优先直接粘贴 `create_doc` 返回的完整 `url`，不要做截短、美化或重写。
+
+参见 [API 详情](references/api-create-doc.md)。
+
+### edit_doc_content
+
+用 Markdown 内容覆写文档正文。`content_type` 固定为 `1`（Markdown）。
+
+使用 `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)。
+
+## 典型工作流
+
+1. **探测当前 doc 能力** → 先调用 `wecom_mcp` 执行 `list` + `category=doc`
+2. **读取文档** → 只有当第 1 步结果中存在 `get_doc_content` 时，才调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`；若 `task_done` 为 false 则携带 `task_id` 继续轮询
+3. **读取能力未开通时立即停止** → 如果第 1 步结果里没有 `get_doc_content`，直接回复用户当前 bot 未开通文档读取能力；不要改用浏览器、HTML 抓取或其他探路方式伪造结果
+4. **创建新文档** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "文档名"}'`，保存返回的 `docid` 和完整 `url`
+5. **编辑文档** → 若第 1 步确认支持读取，可先 get_doc_content 了解当前内容，再 edit_doc_content 覆写；若不支持读取，只在用户明确提供要覆写的内容时再执行 edit
+6. **回复用户链接** → 若要把新文档发给用户，直接返回第 4 步 `create_doc` 的完整 `url`；禁止自行拼接、截短或去掉查询参数
+
+## 输出约束
+
+当你刚创建完企业微信文档并准备回复用户时，严格遵守以下规则：
+
+1. 只从 `create_doc` 的原始返回结果中取 `url`
+2. 不要把 `docid` 转成新的链接
+3. 不要删除 `?scode=...`、`from=` 等查询参数
+4. 不要把链接改写成 markdown 链接文本后再手工抄写 URL
+5. 如果需要摘要，摘要单独写；链接单独保留完整原文
+
+正确示例：
+
+```text
+文档已创建，完整链接如下：
+https://doc.weixin.qq.com/doc/xxx?scode=abc
+```
+
+错误示例：
+
+```text
+https://doc.weixin.qq.com/doc/xxx
+```

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

@@ -0,0 +1,56 @@
+# create_doc API
+
+新建文档、表格或智能表格。创建成功后返回文档访问链接和 docid。
+
+## 技能定义
+
+```json
+{
+    "name": "create_doc",
+    "description": "新建文档、表格或智能表格。支持在指定空间和目录下创建，可设置文档管理员。创建成功后返回文档访问链接和 docid（docid 仅在创建时返回，需妥善保存）。注意：创建智能表格（doc_type=10）时，文档会默认包含一个子表，可通过 smartsheet_get_sheet 查询其 sheet_id，无需额外调用 smartsheet_add_sheet。",
+    "inputSchema": {
+        "properties": {
+            "doc_type": {
+                "description": "文档类型：3-文档，10-智能表格",
+                "enum": [3, 10],
+                "title": "Doc Type",
+                "type": "integer"
+            },
+            "doc_name": {
+                "description": "文档名字，最多 255 个字符，超过会被截断",
+                "title": "Doc Name",
+                "type": "string"
+            }
+        },
+        "required": ["doc_type", "doc_name"],
+        "title": "create_docArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "doc_type": 3,
+    "doc_name": "项目周报"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "url": "https://doc.weixin.qq.com/doc/xxx",
+    "docid": "DOCID"
+}
+```
+
+## 注意事项
+
+- `doc_type=3` 创建普通文档
+- `doc_type=10` 创建智能表格，默认包含一个子表
+- docid 仅在创建时返回，后续无法再获取，务必保存

package/skills/wecom-doc-manager/references/api-edit-doc-content.md

@@ -0,0 +1,68 @@
+# edit_doc_content API
+
+编辑（覆写）文档内容。
+
+## 技能定义
+
+```json
+{
+    "name": "edit_doc_content",
+    "description": "编辑文档内容",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档 id，与 url 二选一传入",
+                "title": "Docid",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "content": {
+                "description": "覆写的文档内容",
+                "title": "Content",
+                "type": "string"
+            },
+            "content_type": {
+                "description": "内容类型格式。1:markdown",
+                "enum": [1],
+                "title": "Content Type",
+                "type": "integer"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "content", "content_type"] },
+            { "required": ["url", "content", "content_type"] }
+        ],
+        "title": "edit_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "content": "# 标题\n\n正文内容",
+    "content_type": 1
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+## 注意事项
+
+- `content_type` 当前仅支持 `1`（Markdown 格式）
+- 此操作为**覆写**，会替换文档全部内容
+- 建议先调用 `get_document` 了解当前内容再编辑

package/skills/wecom-doc-manager/references/api-export-document.md

@@ -0,0 +1,88 @@
+# get_doc_content API
+
+获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。
+
+## 技能定义
+
+```json
+{
+    "name": "get_doc_content",
+    "description": "获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档的 docid，与 url 二选一传入",
+                "title": "Doc ID",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "type": {
+                "description": "内容返回格式。2: Markdown 格式",
+                "enum": [2],
+                "title": "Type",
+                "type": "integer"
+            },
+            "task_id": {
+                "description": "任务 ID，用于异步轮询。初次调用时不填，后续轮询时填写上次返回的 task_id",
+                "title": "Task ID",
+                "type": "string"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "type"] },
+            { "required": ["url", "type"] }
+        ],
+        "title": "get_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 与 url 二选一 | 文档的 docid |
+| url | string | 与 docid 二选一 | 文档的访问链接 |
+| type | integer | 是 | 内容返回格式，固定传 `2`（Markdown 格式） |
+| task_id | string | 否 | 任务 ID，初次调用不填，后续轮询时填写上次返回的 task_id |
+
+## 异步轮询机制
+
+1. **首次调用**：传入 `docid`/`url` 和 `type: 2`，不传 `task_id`
+2. **检查响应**：若 `task_done` 为 `false`，记录返回的 `task_id`
+3. **轮询调用**：携带 `task_id` 再次调用，直到 `task_done` 为 `true`
+4. **获取内容**：当 `task_done` 为 `true` 时，`content` 字段包含完整的 Markdown 内容
+
+## 请求示例
+
+```json
+// 首次调用
+{
+    "docid": "DOCID",
+    "type": 2
+}
+
+// 轮询调用
+{
+    "docid": "DOCID",
+    "type": 2,
+    "task_id": "xxx"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "content": "# 文档标题\n\n文档正文内容...",
+    "task_id": "xxxxx",
+    "task_done": true
+}
+```