@x.ken/wecom 1.0.0

package/README.md

@@ -0,0 +1,268 @@
+# Clawdbot WeCom Plugin
+
+企业微信（WeCom）集成插件，支持通过企业微信与 AI 进行对话。
+
+## 功能特性
+
+- ✅ **企业微信消息接收**：支持加密消息解密和多种消息类型（文本、图片、语音、视频、位置、链接）
+- ✅ **企业微信消息发送**：通过企业微信官方 API 发送消息
+- ✅ **Access Token 管理**：自动缓存和刷新 Access Token
+- ✅ **多账号管理**：支持配置多个独立账号
+
+## 快速开始
+
+### 1. 安装配置
+
+在 `~/.clawdbot/clawdbot.json` 中添加：
+
+```json5
+{
+  "plugins": {
+    "enabled": ["wecom"]
+  },
+
+  "channels": {
+    "wecom": {
+      "enabled": true,
+
+      // 企业微信应用配置
+      "corpid": "ww1234567890abcdef",        // 企业ID
+      "corpsecret": "your-corp-secret",      // 应用Secret
+      "agentid": 1000002,                    // 应用AgentId
+      "token": "your-token",                 // 消息验证Token
+      "encodingAESKey": "your-encoding-aes-key", // 消息加密密钥
+
+      // 自定义系统提示词（可选）
+      "systemPrompt": "你是一个专业的AI助手"
+    }
+  }
+}
+```
+
+**如何获取配置参数**：
+1. 登录[企业微信管理后台](https://work.weixin.qq.com/)
+2. 进入"应用管理" → 选择或创建应用
+3. 在应用详情页获取：
+   - `AgentId`：应用ID
+   - `Secret`：点击"查看Secret"获取
+4. 在"接收消息"设置中获取：
+   - `Token`：点击"随机获取"
+   - `EncodingAESKey`：点击"随机获取"
+5. 在"我的企业"中查看 `企业ID (CorpID)`
+
+### 2. 启动 Gateway
+
+```bash
+clawdbot gateway run --port 18789
+```
+
+### 3. 配置企业微信应用
+
+在企业微信管理后台，配置应用回调 URL：
+
+```
+http://your-gateway-host:18789/wecom/message
+```
+
+企业微信会发送 GET 请求验证 URL，插件会自动处理验证流程。
+
+### 4. 测试接收消息
+
+在企业微信应用中发送消息，Gateway 会自动接收、解密并转发给 Clawdbot 进行 AI 对话。
+
+## 架构设计
+
+### 消息接收流程（企业微信 → Clawdbot）
+
+```
+企业微信用户发送消息
+    ↓ POST /wecom/message（加密 XML）
+Gateway（接收）
+    ↓ 验证签名
+    ↓ 解密消息
+    ↓ 解析 XML
+    ↓ 转换为内部格式
+Clawdbot Agent（AI 处理）
+    ↓ 生成回复
+Gateway（发送回复）
+    ↓ 调用企业微信 API
+企业微信用户接收回复
+```
+
+### 消息发送流程（Clawdbot → 企业微信）
+
+```
+Clawdbot Agent（生成回复）
+    ↓
+Gateway（发送）
+    ↓
+企业微信官方 API（发送）
+    ↓
+企业微信用户接收
+```
+
+## API 端点
+
+### GET /wecom/message
+
+企业微信 URL 验证端点（首次配置时使用）
+
+**查询参数**：
+- `msg_signature`: 消息签名
+- `timestamp`: 时间戳
+- `nonce`: 随机数
+- `echostr`: 加密的验证字符串
+
+插件会自动验证签名、解密并返回明文 echostr。
+
+### POST /wecom/message
+
+接收企业微信加密消息
+
+**Content-Type**: `text/xml` 或 `application/xml`
+
+**查询参数**：
+- `msg_signature`: 消息签名
+- `timestamp`: 时间戳
+- `nonce`: 随机数
+
+**请求体**（XML）：
+```xml
+<xml>
+  <ToUserName><![CDATA[corpid]]></ToUserName>
+  <Encrypt><![CDATA[加密的消息内容]]></Encrypt>
+</xml>
+```
+
+**支持的消息类型**：
+- **文本消息**：直接处理文本内容
+- **图片消息**：提取图片 URL 并发送给 Clawdbot
+- **语音消息**：显示语音信息（格式、MediaId）
+- **视频消息**：显示视频信息（MediaId）
+- **位置消息**：格式化位置信息（坐标、标签）
+- **链接消息**：提取标题、描述、URL
+
+**响应**：返回 `success` 文本（企业微信要求）
+
+### GET /wecom/messages?email=xxx
+
+轮询获取待发送的消息（异步模式）
+
+**响应格式**：
+
+```json
+{
+  "messages": [
+    {
+      "text": "回复内容",
+      "mediaUrl": "https://..."
+    }
+  ]
+}
+```
+
+## 配置参数
+
+### 企业微信官方 API 配置
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `corpid` | string | 是 | 企业微信 Corp ID |
+| `corpsecret` | string | 是 | 企业微信应用 Secret |
+| `agentid` | number | 是 | 企业微信应用 Agent ID |
+| `token` | string | 是 | 企业微信应用 Token（用于消息验证）|
+| `encodingAESKey` | string | 是 | 消息加密密钥（43位字符）|
+
+**如何获取**：
+1. 登录[企业微信管理后台](https://work.weixin.qq.com/)
+2. 进入"应用管理" → 选择或创建应用
+3. 在应用详情页获取 `AgentId` 和 `Secret`
+4. 在"接收消息"设置中获取 `Token` 和 `EncodingAESKey`
+5. 在"我的企业"中查看 `企业ID (CorpID)`
+
+**配置命令**：
+```bash
+clawdbot config set channels.wecom.corpid "ww1234567890abcdef"
+clawdbot config set channels.wecom.corpsecret "your-corp-secret"
+clawdbot config set channels.wecom.agentid 1000002
+clawdbot config set channels.wecom.token "your-token"
+clawdbot config set channels.wecom.encodingAESKey "your-encoding-aes-key"
+```
+
+### 可选配置
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `systemPrompt` | string | 否 | 自定义系统提示词片段 |
+
+## 文件结构
+
+```
+clawdbot-wechat-plugin/
+├── src/
+│   ├── channel.ts          # 渠道插件定义
+│   ├── client.ts           # 消息发送客户端
+│   ├── config-schema.ts    # 配置 Schema
+│   ├── gateway.ts          # Gateway HTTP 路由
+│   ├── multipart.ts        # Multipart 解析器
+│   ├── runtime.ts          # 运行时管理
+│   ├── crypto.ts           # 加密/解密工具
+│   ├── message-parser.ts    # 消息解析
+│   ├── official-api.ts     # 企业微信官方 API
+│   └── access-token.ts     # Access Token 管理
+├── index.ts                # 插件入口
+├── package.json
+├── clawdbot.plugin.json
+└── README.md               # 本文档
+```
+
+## 开发
+
+### 构建
+
+```bash
+cd clawdbot-wechat-plugin
+pnpm install
+pnpm build
+```
+
+### 测试
+
+```bash
+# 单元测试
+pnpm test
+```
+
+## 故障排查
+
+### 企业微信发送失败
+
+**症状**：日志显示 "企业微信 API 调用失败"
+
+**解决方法**：
+1. 检查查 `corpid`、`corpsecret` 和 `agentid` 是否正确
+2. 确认收件人 UserID 在企业微信系统中存在
+3. 检查消息内容长度（最多 2048 字节）
+4. 验证 API 配额是否已用完
+
+### 消息验证失败
+
+**症状**：企业微信配置回调 URL 时验证失败
+
+**解决方法**：
+1. 检查 `token` 和 `encodingAESKey` 是否正确
+2. 确认 Gateway 正在运行并可访问
+3. 检查网络连接
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 联系方式
+
+- 项目主页: https://github.com/clawdbot/clawdbot
+- 文档: https://docs.clawd.bot

package/clawdbot.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "wecom",
+  "channels": [
+    "wecom"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/index.ts

@@ -0,0 +1,17 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+import { wecomPlugin } from "./src/channel.js";
+import { setWeComRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "wecom",
+  name: "WeCom",
+  description: "企业微信集成",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setWeComRuntime(api.runtime);
+    api.registerChannel({ plugin: wecomPlugin });
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@x.ken/wecom",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Clawdbot WeCom (企业微信) integration plugin",
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "fast-xml-parser": "^4.3.4"
+  },
+  "peerDependencies": {
+    "clawdbot": "*"
+  }
+}

package/src/access-token.ts

@@ -0,0 +1,56 @@
+interface AccessTokenCache {
+  token: string;
+  expiresAt: number;
+}
+
+export class WeComAccessTokenManager {
+  private cache: Map<string, AccessTokenCache> = new Map();
+
+  async getAccessToken(corpid: string, corpsecret: string): Promise<string> {
+    const cacheKey = `${corpid}:${corpsecret}`;
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && cached.expiresAt > Date.now() + 5 * 60 * 1000) {
+      return cached.token;
+    }
+
+    const url = `https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${encodeURIComponent(
+      corpid
+    )}&corpsecret=${encodeURIComponent(corpsecret)}`;
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to get access token: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+
+    if (data.errcode !== 0) {
+      throw new Error(
+        `WeChat API error: ${data.errcode} - ${data.errmsg}`
+      );
+    }
+
+    const expiresIn = (data.expires_in || 7200) * 1000;
+    const expiresAt = Date.now() + expiresIn - 10 * 60 * 1000;
+
+    this.cache.set(cacheKey, {
+      token: data.access_token,
+      expiresAt,
+    });
+
+    return data.access_token;
+  }
+
+  clearCache(corpid?: string, corpsecret?: string) {
+    if (corpid && corpsecret) {
+      this.cache.delete(`${corpid}:${corpsecret}`);
+    } else {
+      this.cache.clear();
+    }
+  }
+}
+
+export const accessTokenManager = new WeComAccessTokenManager();

package/src/channel.ts

@@ -0,0 +1,114 @@
+import {
+  buildChannelConfigSchema,
+  type ChannelPlugin,
+  type ResolvedChannelAccount,
+  DEFAULT_ACCOUNT_ID
+} from "clawdbot/plugin-sdk";
+import { WeComConfigSchema, type WeComAccountConfigSchema } from "./config-schema.js";
+import { startWeComAccount } from "./gateway.js";
+import { wecomClient } from "./client.js";
+import { getWeComRuntime } from "./runtime.js";
+import type { z } from "zod";
+
+type WeComConfig = z.infer<typeof WeComConfigSchema>;
+type ResolvedWeComAccount = ResolvedChannelAccount<WeComConfig>;
+
+export const wecomPlugin: ChannelPlugin<ResolvedWeComAccount> = {
+  id: "wecom",
+  meta: {
+    id: "wecom",
+    name: "WeCom",
+    description: "企业微信集成",
+    hidden: false,
+    quickstartAllowFrom: true,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    media: true,
+    text: true,
+    blockStreaming: true,
+  },
+  configSchema: buildChannelConfigSchema(WeComConfigSchema),
+  config: {
+    listAccountIds: (cfg) => {
+        const accounts = cfg.channels?.["wecom"]?.accounts;
+        const ids = accounts ? Object.keys(accounts) : [];
+        if (ids.length === 0 || !ids.includes(DEFAULT_ACCOUNT_ID)) {
+             ids.unshift(DEFAULT_ACCOUNT_ID);
+        }
+        return ids;
+    },
+    resolveAccount: (cfg, accountId) => {
+        const wecom = cfg.channels?.["wecom"];
+        const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
+        const account = wecom?.accounts?.[resolvedId];
+        const defaults = { ...wecom };
+        if (defaults.accounts) delete defaults.accounts;
+
+        const config = { ...defaults, ...account } as any;
+
+        return {
+            accountId: resolvedId,
+            name: account?.name || resolvedId,
+            enabled: account?.enabled ?? wecom?.enabled ?? true,
+            config: config,
+            tokenSource: "config",
+            token: "",
+        };
+    },
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: true,
+      tokenSource: "config",
+    }),
+  },
+  gateway: {
+    startAccount: startWeComAccount,
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async ({ to, text, accountId }) => {
+        const runtime = getWeComRuntime();
+        const cfg = await runtime.config.loadConfig();
+        const wecom = cfg.channels?.["wecom"];
+        const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
+        const account = wecom?.accounts?.[resolvedId];
+        const defaults = { ...wecom };
+        if (defaults.accounts) delete defaults.accounts;
+        const config = { ...defaults, ...account } as any;
+
+        await wecomClient.sendMessage(to, { text }, {
+            corpid: config.corpid,
+            corpsecret: config.corpsecret,
+            agentid: config.agentid,
+            token: config.token,
+            encodingAESKey: config.encodingAESKey
+        });
+
+        return { channel: "wecom", ok: true };
+    },
+    sendMedia: async ({ to, text, mediaUrl, accountId }) => {
+        const runtime = getWeComRuntime();
+        const cfg = await runtime.config.loadConfig();
+        const wecom = cfg.channels?.["wecom"];
+        const resolvedId = accountId ?? DEFAULT_ACCOUNT_ID;
+        const account = wecom?.accounts?.[resolvedId];
+        const defaults = { ...wecom };
+        if (defaults.accounts) delete defaults.accounts;
+        const config = { ...defaults, ...account } as any;
+
+        await wecomClient.sendMessage(to, { text, mediaUrl }, {
+            corpid: config.corpid,
+            corpsecret: config.corpsecret,
+            agentid: config.agentid,
+            token: config.token,
+            encodingAESKey: config.encodingAESKey
+        });
+
+        return { channel: "wecom", ok: true };
+    }
+  },
+};

package/src/client.ts

@@ -0,0 +1,124 @@
+import type { ServerResponse } from "node:http";
+import { wecomOfficialAPI } from "./official-api.js";
+
+export interface WeComMessage {
+  text?: string;
+  mediaUrl?: string;
+}
+
+export class WeComClient {
+  private outboundQueue = new Map<string, WeComMessage[]>();
+  private pendingRequests = new Map<string, ServerResponse>();
+
+  constructor() {}
+
+  registerPendingRequest(userId: string, res: ServerResponse, timeoutMs: number = 30000) {
+    if (this.pendingRequests.has(userId)) {
+      const oldRes = this.pendingRequests.get(userId);
+      if (oldRes && !oldRes.writableEnded) {
+        try {
+          oldRes.statusCode = 409;
+          oldRes.end(JSON.stringify({ error: "New synchronous request superseded this one" }));
+        } catch (e) {
+        }
+      }
+    }
+    this.pendingRequests.set(userId, res);
+
+    setTimeout(() => {
+      if (this.pendingRequests.get(userId) === res) {
+        this.pendingRequests.delete(userId);
+        if (!res.writableEnded) {
+          try {
+            res.statusCode = 202;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ status: "accepted", message: "Processing continued, poll for results." }));
+          } catch (e) {
+          }
+        }
+      }
+    }, timeoutMs);
+  }
+
+  async sendMessage(userId: string, message: WeComMessage, config: {
+    corpid?: string,
+    corpsecret?: string,
+    agentid?: number,
+    token?: string,
+    encodingAESKey?: string
+  }) {
+    const pendingRes = this.pendingRequests.get(userId);
+    if (pendingRes && !pendingRes.writableEnded) {
+      this.pendingRequests.delete(userId);
+      try {
+        pendingRes.statusCode = 200;
+        pendingRes.setHeader("Content-Type", "application/json");
+        pendingRes.end(JSON.stringify(message));
+        return;
+      } catch (e) {
+        console.error("WeCom: Failed to write sync response", e);
+      }
+    }
+
+    console.log("[WeCom Client] sendMessage called with config:", {
+      hasCorpid: !!config.corpid,
+      hasCorpsecret: !!config.corpsecret,
+      hasAgentid: !!config.agentid,
+      corpidValue: config.corpid,
+      agentidValue: config.agentid
+    });
+
+    if (config.corpid && config.corpsecret && config.agentid) {
+      try {
+        let finalText = message.text || "";
+
+        if (message.mediaUrl) {
+          finalText = finalText
+            ? `${finalText}\n\n📎 附件: ${message.mediaUrl}`
+            : `📎 附件: ${message.mediaUrl}`;
+        }
+
+        const payload = {
+          msgtype: "text" as const,
+          agentid: config.agentid,
+          touser: userId,
+          text: {
+            content: finalText,
+          },
+        };
+
+        console.log("[WeCom Client] Sending via official API, payload:", payload);
+
+        const result = await wecomOfficialAPI.sendMessage(
+          config.corpid,
+          config.corpsecret,
+          payload
+        );
+
+        console.log("[WeCom Client] Official API send success:", result);
+        return;
+      } catch (error) {
+        console.error("[WeCom Client] Official API error:", error);
+        throw error; // Re-throw so caller knows it failed
+      }
+    } else {
+      console.log("[WeCom Client] Config incomplete, falling back to queue:");
+      console.log("  - corpid:", config.corpid);
+      console.log("  - corpsecret:", config.corpsecret ? "set" : "missing");
+      console.log("  - agentid:", config.agentid);
+    }
+
+    console.log("消息加入队列:", userId);
+    const queue = this.outboundQueue.get(userId) ?? [];
+    queue.push(message);
+    this.outboundQueue.set(userId, queue);
+  }
+
+  getPendingMessages(userId: string): WeComMessage[] {
+    const messages = this.outboundQueue.get(userId) ?? [];
+    this.outboundQueue.delete(userId);
+    return messages;
+  }
+}
+
+export const wecomClient = new WeComClient();

package/src/config-schema.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const WeComAccountConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+
+  // 企业微信应用配置
+  corpid: z.string().optional().describe("企业微信 Corp ID"),
+  corpsecret: z.string().optional().describe("企业微信 Corp Secret"),
+  agentid: z.number().optional().describe("企业微信应用 Agent ID"),
+  token: z.string().optional().describe("企业微信应用 Token"),
+  encodingAESKey: z.string().optional().describe("企业微信消息加密密钥"),
+
+  // 自定义系统提示词
+  systemPrompt: z.string().optional().describe("自定义系统提示词片段"),
+}).strict();
+
+export const WeComConfigSchema = WeComAccountConfigSchema.extend({
+  accounts: z.record(z.string(), WeComAccountConfigSchema.optional()).optional(),
+}).strict();