@wecom/wecom-openclaw-plugin 1.0.9-beta.0 → 1.0.9-beta.1

package/dist/src/const.d.ts

@@ -42,6 +42,12 @@ export declare const THINKING_MESSAGE = "<think></think>";
 export declare const MEDIA_IMAGE_PLACEHOLDER = "<media:image>";
 /** 仅包含文件时的消息占位符 */
 export declare const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
+/** 获取 MCP 配置的 WebSocket 命令 */
+export declare const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
+/** MCP 配置拉取超时时间（毫秒） */
+export declare const MCP_CONFIG_FETCH_TIMEOUT_MS = 15000;
+export declare const PLUGIN_JSON_FILENAME = "openclaw.plugin.json";
+export declare const PLUGIN_JSON_PATH: string;
 /** 默认媒体大小上限（MB） */
 export declare const DEFAULT_MEDIA_MAX_MB = 5;
 /** 文本分块大小上限 */

package/dist/src/interface.d.ts

@@ -21,6 +21,17 @@ export interface MessageState {
     /** 流式回复的 streamId，用于保持同一个流式回复使用相同的 streamId */
     streamId?: string;
 }
+/**
+ * MCP 配置响应体
+ */
+export interface McpConfigBody {
+    /** MCP Server 的 StreamableHttp URL */
+    url: string;
+    /** 连接类型，如 "streamable-http" */
+    type?: string;
+    /** 是否已授权 */
+    is_authed?: boolean;
+}
 /**
  * WebSocket 请求消息基础格式
  */

package/dist/src/mcp-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP 配置拉取与持久化模块
+ *
+ * 负责:
+ * - 通过 WSClient 发送 aibot_get_mcp_config 请求
+ * - 解析服务端响应,提取 MCP 配置(url、type、is_authed)
+ * - 将配置写入 openclaw.plugin.json 的 wecomMcp 字段
+ */
+import { type WSClient } from "@wecom/aibot-node-sdk";
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import type { McpConfigBody } from "./interface.js";
+/**
+ * 通过 WSClient 发送 aibot_get_mcp_config 命令,获取 MCP 配置
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @returns MCP 配置(url、type、is_authed)
+ * @throws 响应错误码非 0 或缺少 url 字段时抛出错误
+ */
+export declare function fetchMcpConfig(wsClient: WSClient): Promise<McpConfigBody>;
+/**
+ * 拉取 MCP 配置并持久化到 openclaw.plugin.json
+ *
+ * 认证成功后调用。失败仅记录日志,不影响 WebSocket 消息正常收发。
+ *
+ * @param wsClient - 已认证的 WSClient 实例
+ * @param accountId - 账户 ID(用于日志)
+ * @param runtime - 运行时环境(用于日志)
+ */
+export declare function fetchAndSaveMcpConfig(wsClient: WSClient, accountId: string, runtime: RuntimeEnv): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "1.0.9-beta.0",
+  "version": "1.0.9-beta.1",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/skills/wecom-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wecom-doc
-description: 文档与智能表格操作。当用户提到企业微信文档、创建文档、编辑文档、新建文档、写文档、智能表格时激活。支持文档创建/写入和智能表格的创建及子表/字段/记录写入。注意：所有企业微信文档创建和编辑请求都应使用此 skill，不要尝试用其他方式处理文档操作。
+description: 文档与智能表格操作。当用户提到企业微信文档、创建文档、编辑文档、新建文档、写文档、智能表格时激活。支持文档创建/写入和智能表格的创建及子表/字段/记录写入。注意：所有文档创建和编辑请求都应使用此 skill，不要尝试用其他方式处理文档操作。
 metadata:
   {
     "openclaw":
@@ -61,15 +61,39 @@ npm install -g mcporter
 
 > 好的，你也可以手动执行 `npm install -g mcporter` 安装后再找我。
 
-### 2. 检查 MCP Server 是否配置
+### 2. 确保 MCP Server 已配置
 
-确认 mcporter 存在后，执行：
+确认 mcporter 存在后，先检查配置是否已存在，仅在未配置时才尝试自动配置。
+
+**验证配置：**
 
 ```bash
 mcporter list wecom-doc --output json
 ```
 
-如果返回 **server not found**、**unknown server** 或类似错误，按下方"MCP Server 未配置"章节处理。
+如果返回正常（包含 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 列表
 
@@ -122,7 +146,7 @@ docid **只能**通过 `create_doc` 的返回结果获取。创建成功后需
 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_id）
+8. 添加数据记录 → `smartsheet_add_records`（values 的 key **必须**使用字段标题 field_title，不能用 field_id）
 
 ### 从零创建智能表完整流程
 
@@ -149,41 +173,41 @@ smartsheet_get_sheet(docid) → sheet_id
 
 ### 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` | 条码 |
+| 类型 | 说明 | 使用场景建议 |
+|------|------|-------------|
+| `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` 中每个字段的 value 必须匹配其字段类型：
+添加记录（`smartsheet_add_records`）时，`values` 中每个字段的 **key 必须使用字段标题（field_title），不能使用 field_id**。value 必须匹配其字段类型：
 
 | 字段类型 | CellValue 格式 | 示例 |
 |---------|---------------|------|
 | `TEXT` | CellTextValue 数组 | `[{"type": "text", "text": "内容"}]` |
 | `NUMBER` | number | `85` |
 | `CHECKBOX` | boolean | `true` |
-| `DATE_TIME` | **毫秒**时间戳**字符串** | `"1672531200000"` |
+| `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 数组 | `[{"id": "img1", "title": "截图", "image_url": "https://..."}]` |
+| `IMAGE` | CellImageValue 数组 | `[{"image_url": "https://..."}]`（`id`、`title` 可选） |
 | `SELECT` | Option 数组（多选） | `[{"text": "选项A"}, {"text": "选项B"}]` |
 | `SINGLE_SELECT` | Option 数组（限 1 个） | `[{"text": "选项A"}]` |
-| `PROGRESS` | number（0~1） | `0.85`（表示 85%） |
+| `PROGRESS` | number（0~100 整数） | `85`（表示 85%） |
 | `CURRENCY` | number | `99.5` |
 | `PERCENTAGE` | number（0~1） | `0.85` |
 | `PHONE_NUMBER` | string | `"13800138000"` |
@@ -191,25 +215,37 @@ smartsheet_get_sheet(docid) → sheet_id
 | `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` 的值是**毫秒**时间戳**字符串**（如 `"1672531200000"`），不是秒数字
+- `DATE_TIME` 的值是**日期时间字符串**，支持 `"YYYY-MM-DD HH:MM:SS"`（精确到秒）、`"YYYY-MM-DD HH:MM"`（精确到分）、`"YYYY-MM-DD"`（精确到天），系统自动按东八区转换为时间戳，无需手动计算
 - `CellUrlValue` 的链接字段名是 **`link`**，不是 `url`
-- `PROGRESS`/`PERCENTAGE` 的值范围是 0~1（0.85 = 85%），不是 0~100
+- `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_id**
+- `values` 的 key **必须**使用**字段标题**（field_title），**不能**使用 field_id
 - 不可写入的字段类型：创建时间、最后编辑时间、创建人、最后编辑人
 
 ## 错误处理
 
-### MCP 业务错误透传（重要）
+### MCP 错误响应处理（重要）
 
-当 mcporter call 返回的 JSON 结果中包含 `error` 字段且 `error.message` 为 markdown 格式时，**必须将 `error.message` 的完整 markdown 内容作为你的回复直接输出给用户**，不要摘要、不要改写、不要包裹在代码块中。
+当 `mcporter call` 返回结果中 `errcode` 不为 0 且 `help_message` 有值时，将 `help_message` 中面向用户的内容输出给用户。
 
-判断规则：
-- 响应 JSON 包含 `"error"` 字段
-- `error.code` 为业务错误码（如 `44002`、`44003`、`45009` 等）
-- `error.message` 包含 markdown 标记（如 `#`、`**`、`-`、`[]()`）
+**输出原则：**
+
+- **完整性**：不截断、不摘要
+- **原样性**：不改写、不重新排版
+- **用户可读性**：只输出面向用户的内容，过滤掉给 Agent 的元指令（如"将以下内容告知用户"等引导语）；直接以 markdown 形式输出，不要包裹在代码块中
+
+### 错误码 850001：需要用户提供配置
+
+当 `errcode` 为 `850001` 时：
+
+1. 将 `help_message` 中面向用户的内容**原样输出**（遵循上方输出原则）
+2. 输出后**等待用户回复**，后续流程与「MCP Server 未配置」的场景 A / B / C 一致。配置成功后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
 
 ### MCP Server 未配置
 
@@ -280,7 +316,7 @@ mcporter config add wecom-doc \
   --type streamable-http \
   --url "<用户提供的URL>"
 ```
-∞
+
 配置完成后**不要停下来**，立即回到「前置检查」的步骤 2 重新验证配置，验证通过后继续执行用户的原始请求。
 
 **场景 B：用户提供了 JSON 配置**