@mocrane/wecom 2026.3.14 → 2026.3.20

package/skills/wecom-smartsheet-data/references/cell-value-formats.md

@@ -0,0 +1,120 @@
+# 单元格值格式参考
+
+在 `smartsheet_add_records` 和 `smartsheet_update_records` 中，`values` 的 key **必须是字段标题（field_title）**，不能使用字段 ID。
+
+## 各字段类型的值格式
+
+### 1. 文本 (FIELD_TYPE_TEXT)
+
+**必须**使用数组格式，外层方括号不可省略：
+
+```json
+"字段标题": [{"type": "text", "text": "内容"}]
+```
+
+### 2. 数字 (NUMBER) / 货币 (CURRENCY) / 百分比 (PERCENTAGE) / 进度 (PROGRESS)
+
+直接传数字：
+
+```json
+"金额": 100,
+"完成率": 0.6,
+"进度": 80
+```
+
+### 3. 复选框 (CHECKBOX)
+
+直接传布尔值：
+
+```json
+"已完成": true
+```
+
+### 4. 单选 (SINGLE_SELECT) / 多选 (SELECT)
+
+**必须**使用数组格式，不能直接传字符串：
+
+```json
+"优先级": [{"text": "高"}],
+"标签": [{"text": "紧急"}, {"text": "重要"}]
+```
+
+选项可附带 `id`（已存在选项）和 `style`（颜色 1-27）。
+
+### 5. 日期时间 (DATE_TIME)
+
+传日期时间字符串，系统自动按东八区转换：
+
+```json
+"截止日期": "2026-01-15 14:30:00",
+"创建日期": "2026-01-15"
+```
+
+支持格式：`YYYY-MM-DD HH:MM:SS`、`YYYY-MM-DD HH:MM`、`YYYY-MM-DD`
+
+### 6. 手机号 (PHONE_NUMBER) / 邮箱 (EMAIL) / 条码 (BARCODE)
+
+直接传字符串：
+
+```json
+"电话": "13800138000",
+"邮箱": "test@example.com"
+```
+
+### 7. 成员 (USER)
+
+数组格式，需传 user_id。**user_id 不是姓名**，必须先通过 `wecom-contact-lookup` 技能查找目标人员的 `userid`，再填入此处。
+
+具体步骤：先使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取通讯录成员列表，在返回结果中按姓名/别名筛选出目标人员，取其 `userid` 值填入。
+
+```json
+"负责人": [{"user_id": "zhangsan"}]
+```
+
+多个成员：
+
+```json
+"负责人": [{"user_id": "zhangsan"}, {"user_id": "lisi"}]
+```
+
+### 8. 超链接 (URL)
+
+数组格式，目前仅支持一个链接：
+
+```json
+"参考链接": [{"type": "url", "text": "官网", "link": "https://example.com"}]
+```
+
+### 9. 图片 (IMAGE)
+
+数组格式：
+
+```json
+"封面": [{"image_url": "https://example.com/img.png"}]
+```
+
+### 10. 地理位置 (LOCATION)
+
+数组格式：
+
+```json
+"地点": [{"source_type": 1, "id": "地点ID", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]
+```
+
+## 完整添加记录示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet_id": "SHEETID",
+    "records": [{
+        "values": {
+            "任务名称": [{"type": "text", "text": "完成需求文档"}],
+            "优先级": [{"text": "高"}],
+            "截止日期": "2026-03-20",
+            "完成进度": 30,
+            "已完成": false
+        }
+    }]
+}
+```

package/skills/wecom-smartsheet-schema/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: wecom-smartsheet-schema
+description: 企业微信智能表格结构管理技能。提供子表（Sheet）和字段（Field/列）的增删改查能力。适用场景：(1) 查询智能表格的子表列表 (2) 添加、更新、删除子表 (3) 查询子表的字段/列信息 (4) 添加、更新、删除字段/列。当用户需要管理智能表格的表结构、列定义、子表配置时触发此 Skill。支持通过 docid 或文档 URL 定位文档。
+---
+
+# 企业微信智能表格结构管理
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+管理智能表格的子表和字段（列）结构。所有接口支持通过 `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` 展示给用户。
+
+## 子表管理
+
+### smartsheet_get_sheet
+
+查询文档中所有子表信息，返回 sheet_id、title、类型等。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_sheet '{"docid": "DOCID"}'`
+
+### smartsheet_add_sheet
+
+添加空子表。新子表不含视图、记录和字段，需通过其他接口补充。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'`
+
+**注意**：新建智能表格文档默认已含一个子表，仅需多个子表时调用。
+
+### smartsheet_update_sheet
+
+修改子表标题。需提供 sheet_id 和新 title。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_update_sheet '{"docid": "DOCID", "sheet_id": "SHEETID", "title": "新标题"}'`
+
+### smartsheet_delete_sheet
+
+永久删除子表，**操作不可逆**。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'`
+
+## 字段管理
+
+### smartsheet_get_fields
+
+查询子表的所有字段信息，返回 field_id、field_title、field_type。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'`
+
+### smartsheet_add_fields
+
+向子表添加一个或多个字段。单个子表最多 150 个字段。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT"}]}'`
+
+支持的字段类型参见 [字段类型参考](references/field-types.md)。
+
+### smartsheet_update_fields
+
+更新字段标题。**只能改名，不能改类型**（field_type 必须传原始类型）。field_title 不能更新为原值。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "新标题", "field_type": "FIELD_TYPE_TEXT"}]}'`
+
+### smartsheet_delete_fields
+
+删除一列或多列字段，**操作不可逆**。field_id 可通过 `smartsheet_get_fields` 获取。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'`
+
+## 典型工作流
+
+1. **了解表结构** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_sheet` → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartsheet_get_fields`
+2. **创建表结构** → `smartsheet_add_sheet` 添加子表 → `smartsheet_add_fields` 定义列
+3. **修改表结构** → `smartsheet_update_fields` 改列名 / `smartsheet_delete_fields` 删列
+

package/skills/wecom-smartsheet-schema/references/field-types.md

@@ -0,0 +1,43 @@
+# 智能表格字段类型参考
+
+## 支持的字段类型
+
+| 类型枚举值 | 说明 | 适用场景 |
+|---|---|---|
+| `FIELD_TYPE_TEXT` | 文本 | 名称、标题、描述、负责人姓名等自由文本 |
+| `FIELD_TYPE_NUMBER` | 数字 | 金额、工时、数量等数值 |
+| `FIELD_TYPE_CHECKBOX` | 复选框 | 是否完成等布尔值 |
+| `FIELD_TYPE_DATE_TIME` | 日期时间 | 截止日期、创建时间等 |
+| `FIELD_TYPE_IMAGE` | 图片 | 附件图片 |
+| `FIELD_TYPE_USER` | 用户/成员 | 需传入 user_id；仅在明确知道成员 ID 时使用，若只有姓名应用 TEXT |
+| `FIELD_TYPE_URL` | 链接 | 超链接 |
+| `FIELD_TYPE_SELECT` | 多选 | 标签、分类等可多选的选项 |
+| `FIELD_TYPE_PROGRESS` | 进度 | 完成进度（0-100 整数） |
+| `FIELD_TYPE_PHONE_NUMBER` | 手机号 | 联系电话 |
+| `FIELD_TYPE_EMAIL` | 邮箱 | 电子邮件 |
+| `FIELD_TYPE_SINGLE_SELECT` | 单选 | 状态、优先级、严重程度等有固定选项的字段 |
+| `FIELD_TYPE_LOCATION` | 位置 | 地理位置 |
+| `FIELD_TYPE_CURRENCY` | 货币 | 货币金额 |
+| `FIELD_TYPE_PERCENTAGE` | 百分比 | 比率类数值（完成率、转化率） |
+| `FIELD_TYPE_BARCODE` | 条码 | 条形码/二维码 |
+
+## 添加字段示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet_id": "SHEETID",
+    "fields": [
+        { "field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT" },
+        { "field_title": "优先级", "field_type": "FIELD_TYPE_SINGLE_SELECT" },
+        { "field_title": "截止日期", "field_type": "FIELD_TYPE_DATE_TIME" },
+        { "field_title": "完成进度", "field_type": "FIELD_TYPE_PROGRESS" }
+    ]
+}
+```
+
+## 更新字段注意事项
+
+- `smartsheet_update_fields` **只能更新字段标题**，不能更改字段类型
+- `field_type` 必须传字段当前的原始类型
+- `field_title` 不能更新为原值（即不能传与当前相同的标题）

package/src/agent/handler.ts

@@ -18,7 +18,7 @@ import {
     extractFileName,
     extractAgentId,
 } from "../shared/xml-parser.js";
-import { sendText, downloadMedia } from "./api-client.js";
+import { sendText, downloadMedia, uploadMedia, sendMedia as sendAgentMedia } from "./api-client.js";
 import { getWecomRuntime } from "../runtime.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import { buildWecomUnauthorizedCommandPrompt, resolveWecomCommandAuthorization } from "../shared/command-auth.js";
@@ -518,7 +518,9 @@ async function processAgentMessage(params: {
         CommandBody: finalContent,
         Attachments: attachments.length > 0 ? attachments : undefined,
         From: isGroup ? `wecom:group:${peerId}` : `wecom:${fromUser}`,
-        To: `wecom:${peerId}`,
+        // 使用 wecom-agent: 前缀标记 Agent 会话，确保 outbound 路由不会混入 Bot WS 发送路径。
+        // resolveWecomTarget 已支持剥离 wecom-agent: 前缀（target.ts L41），解析结果不变。
+        To: `wecom-agent:${fromUser}`,
         SessionKey: route.sessionKey,
         AccountId: route.accountId,
         ChatType: isGroup ? "group" : "direct",
@@ -553,18 +555,107 @@ async function processAgentMessage(params: {
         ctx: ctxPayload,
         cfg: config,
         dispatcherOptions: {
-            deliver: async (payload: { text?: string }, info: { kind: string }) => {
-                const text = payload.text ?? "";
-                if (!text) return;
-
-                try {
-                    // 统一策略：Agent 模式在群聊场景默认只私信触发者（避免 wr/wc chatId 86008）
-                    await sendText({ agent, toUser: fromUser, chatId: undefined, text });
-                    log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
-                } catch (err: unknown) {
-                    const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
-                    error?.(`[wecom-agent] reply failed: ${message}`);
-                }            },
+            deliver: async (payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string }, info: { kind: string }) => {
+                let text = payload.text ?? "";
+
+                // ── 1. 解析 MEDIA: 指令（兜底处理核心 splitMediaFromOutput 未覆盖的边界情况）──
+                const mediaDirectivePaths: string[] = [];
+                const mediaDirectiveRe = /^MEDIA:\s*`?([^\n`]+?)`?\s*$/gm;
+                let _mdMatch: RegExpExecArray | null;
+                while ((_mdMatch = mediaDirectiveRe.exec(text)) !== null) {
+                    let p = (_mdMatch[1] ?? "").trim();
+                    if (!p) continue;
+                    if (p.startsWith("~/") || p === "~") {
+                        const home = process.env.HOME || "/root";
+                        p = p.replace(/^~/, home);
+                    }
+                    if (!mediaDirectivePaths.includes(p)) mediaDirectivePaths.push(p);
+                }
+                // 从回复文本中移除 MEDIA: 指令行
+                if (mediaDirectivePaths.length > 0) {
+                    text = text.replace(/^MEDIA:\s*`?[^\n`]+?`?\s*$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
+                }
+
+                // ── 2. 合并所有媒体 URL ──
+                const mediaUrls = Array.from(new Set([
+                    ...(payload.mediaUrls || []),
+                    ...(payload.mediaUrl ? [payload.mediaUrl] : []),
+                    ...mediaDirectivePaths,
+                ]));
+
+                // ── 3. 发送文本部分 ──
+                if (text.trim()) {
+                    try {
+                        await sendText({ agent, toUser: fromUser, chatId: undefined, text });
+                        log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser} (textLen=${text.length})`);
+                    } catch (err: unknown) {
+                        const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
+                        error?.(`[wecom-agent] reply failed: ${message}`);
+                    }
+                }
+
+                // ── 4. 逐个发送媒体文件（通过 Agent API 上传 + 发送）──
+                for (const mediaPath of mediaUrls) {
+                    try {
+                        const isRemoteUrl = /^https?:\/\//i.test(mediaPath);
+                        let buf: Buffer;
+                        let contentType: string;
+                        let filename: string;
+
+                        if (isRemoteUrl) {
+                            const res = await fetch(mediaPath, { signal: AbortSignal.timeout(30_000) });
+                            if (!res.ok) throw new Error(`download failed: ${res.status}`);
+                            buf = Buffer.from(await res.arrayBuffer());
+                            contentType = res.headers.get("content-type") || "application/octet-stream";
+                            filename = new URL(mediaPath).pathname.split("/").pop() || "media";
+                        } else {
+                            const fs = await import("node:fs/promises");
+                            const pathModule = await import("node:path");
+                            buf = await fs.readFile(mediaPath);
+                            filename = pathModule.basename(mediaPath);
+                            const ext = pathModule.extname(mediaPath).slice(1).toLowerCase();
+                            const MIME_MAP: Record<string, string> = {
+                                jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
+                                webp: "image/webp", mp3: "audio/mpeg", wav: "audio/wav", amr: "audio/amr",
+                                mp4: "video/mp4", mov: "video/quicktime", pdf: "application/pdf",
+                                doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                                xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                                txt: "text/plain", csv: "text/csv", json: "application/json", zip: "application/zip",
+                            };
+                            contentType = MIME_MAP[ext] ?? "application/octet-stream";
+                        }
+
+                        // 确定企微媒体类型
+                        let mediaType: "image" | "voice" | "video" | "file" = "file";
+                        if (contentType.startsWith("image/")) mediaType = "image";
+                        else if (contentType.startsWith("audio/")) mediaType = "voice";
+                        else if (contentType.startsWith("video/")) mediaType = "video";
+
+                        log?.(`[wecom-agent] uploading media: ${filename} (${mediaType}, ${contentType}, ${buf.length} bytes)`);
+
+                        const mediaId = await uploadMedia({ agent, type: mediaType, buffer: buf, filename });
+
+                        await sendAgentMedia({
+                            agent,
+                            toUser: fromUser,
+                            mediaId,
+                            mediaType,
+                            ...(mediaType === "video" ? { title: filename, description: "" } : {}),
+                        });
+
+                        log?.(`[wecom-agent] media sent (${info.kind}) to ${fromUser}: ${filename} (${mediaType})`);
+                    } catch (err: unknown) {
+                        const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
+                        error?.(`[wecom-agent] media send failed: ${mediaPath}: ${message}`);
+                        // 降级：发文本通知用户
+                        try {
+                            await sendText({ agent, toUser: fromUser, chatId: undefined, text: `⚠️ 文件发送失败: ${mediaPath.split("/").pop() || mediaPath}\n${message}` });
+                        } catch { /* ignore */ }
+                    }
+                }
+
+                // 如果既没有文本也没有媒体，不做任何事（防止空回复）
+            },
             onError: (err: unknown, info: { kind: string }) => {
                 error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
             },

package/src/mcp/index.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP 模块统一导出
+ */
+
+export { createWeComMcpTool } from "./tool.js";
+export { sendJsonRpc, clearCategoryCache, McpRpcError, McpHttpError, type McpToolInfo } from "./transport.js";
+export { cleanSchemaForGemini } from "./schema.js";

package/src/mcp/schema.ts

@@ -0,0 +1,108 @@
+/**
+ * MCP Schema 清洗模块
+ *
+ * 负责内联 $ref/$defs 引用并移除 Gemini 不支持的 JSON Schema 关键词，
+ * 防止 Gemini 模型解析 function response 时报 400 错误。
+ */
+
+/** Gemini 不支持的 JSON Schema 关键词 */
+const GEMINI_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties", "additionalProperties", "$schema", "$id", "$ref", "$defs",
+  "definitions", "examples", "minLength", "maxLength", "minimum", "maximum",
+  "multipleOf", "pattern", "format", "minItems", "maxItems", "uniqueItems",
+  "minProperties", "maxProperties",
+]);
+
+/**
+ * 清洗 JSON Schema，内联 $ref 引用并移除 Gemini 不支持的关键词，
+ * 防止 Gemini 模型解析 function response 时报 400 错误。
+ */
+export function cleanSchemaForGemini(schema: unknown): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map(cleanSchemaForGemini);
+
+  const obj = schema as Record<string, unknown>;
+
+  // 收集 $defs/definitions 用于后续 $ref 内联解析
+  const defs: Record<string, unknown> = {
+    ...(obj.$defs && typeof obj.$defs === "object" ? obj.$defs as Record<string, unknown> : {}),
+    ...(obj.definitions && typeof obj.definitions === "object" ? obj.definitions as Record<string, unknown> : {}),
+  };
+
+  return cleanWithDefs(obj, defs, new Set());
+}
+
+function cleanWithDefs(
+  schema: unknown,
+  defs: Record<string, unknown>,
+  refStack: Set<string>,
+): unknown {
+  if (!schema || typeof schema !== "object") return schema;
+  if (Array.isArray(schema)) return schema.map((item) => cleanWithDefs(item, defs, refStack));
+
+  const obj = schema as Record<string, unknown>;
+
+  // 合并当前层级的 $defs/definitions 到 defs 中
+  if (obj.$defs && typeof obj.$defs === "object") {
+    Object.assign(defs, obj.$defs as Record<string, unknown>);
+  }
+  if (obj.definitions && typeof obj.definitions === "object") {
+    Object.assign(defs, obj.definitions as Record<string, unknown>);
+  }
+
+  // 处理 $ref 引用：尝试内联解析
+  if (typeof obj.$ref === "string") {
+    const ref = obj.$ref;
+    if (refStack.has(ref)) return {}; // 防止循环引用
+
+    const match = ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+    if (match && match[1] && defs[match[1]]) {
+      const nextStack = new Set(refStack);
+      nextStack.add(ref);
+      return cleanWithDefs(defs[match[1]], defs, nextStack);
+    }
+    return {}; // 无法解析的 $ref，返回空对象
+  }
+
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (GEMINI_UNSUPPORTED_KEYWORDS.has(key)) continue;
+
+    if (key === "const") {
+      cleaned.enum = [value];
+      continue;
+    }
+
+    if (key === "properties" && value && typeof value === "object" && !Array.isArray(value)) {
+      cleaned[key] = Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([k, v]) => [
+          k, cleanWithDefs(v, defs, refStack),
+        ]),
+      );
+    } else if (key === "items" && value) {
+      cleaned[key] = Array.isArray(value)
+        ? value.map((item) => cleanWithDefs(item, defs, refStack))
+        : cleanWithDefs(value, defs, refStack);
+    } else if ((key === "anyOf" || key === "oneOf" || key === "allOf") && Array.isArray(value)) {
+      // 过滤掉 null 类型的变体
+      const nonNull = value.filter((v) => {
+        if (!v || typeof v !== "object") return true;
+        const r = v as Record<string, unknown>;
+        return r.type !== "null";
+      });
+      if (nonNull.length === 1) {
+        // 只剩一个变体时直接内联
+        const single = cleanWithDefs(nonNull[0], defs, refStack);
+        if (single && typeof single === "object" && !Array.isArray(single)) {
+          Object.assign(cleaned, single as Record<string, unknown>);
+        }
+      } else {
+        cleaned[key] = nonNull.map((v) => cleanWithDefs(v, defs, refStack));
+      }
+    } else {
+      cleaned[key] = value;
+    }
+  }
+
+  return cleaned;
+}