@jiexiaoyin/wecom-api 0.0.2

package/README.md

@@ -0,0 +1,228 @@
+# openclaw-wecom-api
+
+企业微信 API OpenClaw 插件，为 OpenClaw 提供完整的企业微信 API 调用能力和事件回调处理。
+
+## 与其他 OpenClaw 企业微信插件的关系
+
+| 插件 | 职责 | 通道 |
+|------|------|------|
+| **其他 Channel 插件**（如 @sunnoy/wecom） | 消息收发（WebSocket 长连接） | `"wecom"` 通道 |
+| **openclaw-wecom-api** | API 调用 + 事件回调 | Skill 方式被 AI 触发 |
+
+两者**不冲突**，共用同一套 `corpId`/`corpSecret` 凭证。
+
+## 功能特性
+
+- **32+ API 模块**：消息、会议、审批、打卡、客户联系、通讯录等
+- **事件回调**：支持客户变更、审批、签到、会议等事件的 HTTP 接收
+- **零额外部署**：继承 OpenClaw HTTP 端口（80/443），无需单独开端口
+- **智能权限控制**：admin / manager / staff 三级数据隔离
+- **回调路径隔离**：与 Channel 插件使用不同路径，互不干扰
+
+## HTTP 回调路径
+
+| 插件 | 回调路径 |
+|------|---------|
+| @sunnoy/wecom | `/plugins/wecom/agent/default` |
+| openclaw-wecom-api | `/plugins/wecom-api/callback` |
+
+## 安装
+
+### 方式一：Git 克隆
+
+```bash
+# 克隆到扩展目录
+git clone https://github.com/jiexiaoyin/openclaw-wecom-api.git /root/.openclaw/extensions/wecom-api
+
+# 安装依赖
+cd /root/.openclaw/extensions/wecom-api
+npm install
+```
+
+### 方式二：OpenClaw CLI
+
+```bash
+openclaw plugins install https://github.com/jiexiaoyin/openclaw-wecom-api
+```
+
+## 配置
+
+### 1. 修改 openclaw.json
+
+在 `plugins.entries` 中添加插件注册：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "wecom-api": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### 2. 创建 config.json
+
+```bash
+cd /root/.openclaw/extensions/wecom-api
+cp config.example.json config.json
+# 编辑 config.json 填入你的凭证
+```
+
+```json
+{
+  "corpId": "你的企业ID",
+  "corpSecret": "你的应用Secret",
+  "agentId": "你的应用AgentID",
+  "token": "回调Token",
+  "encodingAESKey": "EncodingAESKey"
+}
+```
+
+| 参数 | 说明 | 必填 |
+|------|------|------|
+| corpId | 企业ID | ✅ |
+| corpSecret | 应用Secret | ✅ |
+| agentId | 应用AgentID | ✅ |
+| token | 回调Token | ✅ |
+| encodingAESKey | 回调加密Key | ✅ |
+
+### 3. 重启 OpenClaw
+
+```bash
+systemctl --user restart openclaw-gateway
+# 或
+nohup systemctl --user restart openclaw-gateway > /tmp/restart.log 2>&1 &
+```
+
+### 4. 配置企业微信后台
+
+登录 [企业微信管理后台](https://console.work.weixin.qq.com)，找到你的自建应用，在「接收消息」设置中：
+
+- 填写「URL」：`https://你的域名/plugins/wecom-api/callback`
+- 填写「Token」和「EncodingAESKey」：与 config.json 中一致
+
+## 与其他 OpenClaw 企业微信插件共用应用
+
+当本插件与其他 OpenClaw 企业微信 Channel 插件（如 @sunnoy/wecom）共用同一个企业微信自建应用时，需要使用 Nginx Mirror 将企业微信的回调同时分发给两个插件：
+
+```nginx
+# 企业微信回调入口（其他 Channel 插件的路径，以 @sunnoy/wecom 为例）
+location /plugins/wecom/agent/default {
+    mirror /plugins/wecom-api/callback;
+    mirror_request_body on;
+    proxy_pass http://127.0.0.1:18789;
+}
+
+# openclaw-wecom-api 的回调路径（mirror 目标）
+location = /plugins/wecom-api/callback {
+    internal;
+    proxy_pass http://127.0.0.1:18789;
+}
+```
+
+两者共用同一套凭证（corpId / corpSecret / token / encodingAESKey），各自验证签名、解析消息，互不干扰。
+
+## 使用方式
+
+插件安装后，OpenClaw 会自动注册 Skill，通过自然语言即可调用：
+
+```
+查一下 JieXiaoYin 的客户列表
+发送消息给 张三，内容是测试
+查询昨天的客户统计
+查一下审批列表
+获取通讯录
+```
+
+### 命令行测试
+
+```bash
+# 测试连接
+/skill wecom-api test_connection
+
+# 查看配置状态
+/skill wecom-api status
+```
+
+## 支持的 API 模块
+
+| 模块 | 说明 |
+|------|------|
+| `addressbook` | 通讯录管理 |
+| `approval` | 审批管理 |
+| `checkin` | 打卡考勤 |
+| `contact` | 客户联系 |
+| `contact_stats` | 客户统计 |
+| `customer` | 客户管理 |
+| `document` | 文档管理 |
+| `meeting` | 会议管理 |
+| `message` | 消息收发 |
+| `schedule` | 日程管理 |
+| `media` | 素材管理 |
+| ... | 更多模块 |
+
+## 支持的回调事件
+
+- **客户联系**：`add_external_contact`、`del_external_contact`、`change_external_contact` 等
+- **客户群**：`create_chat`、`update_chat`、`dismiss_chat`
+- **审批**：`submit_approval`、`Approval`
+- **打卡**：`checkin`、`report_checkin`
+- **会议**：`meeting_start`、`meeting_end`、`meeting_created` 等
+- **通讯录**：`change_member`、`change_department`、`change_tag`
+
+## 文件结构
+
+```
+openclaw-wecom-api/
+├── openclaw.plugin.json     # 插件清单
+├── plugin.cjs               # 插件入口（HTTP 回调注册）
+├── package.json
+│
+├── src/
+│   ├── index.js             # WeComPlugin 主类
+│   ├── callback-helper.js   # 回调处理工具
+│   ├── crypto.js           # 加密/解密
+│   ├── config.js            # 配置加载
+│   │
+│   └── modules/             # 32+ API 模块
+│       ├── approval/
+│       ├── contact/
+│       ├── contact_stats/
+│       ├── customer/
+│       ├── message/
+│       ├── meeting/
+│       ├── schedule/
+│       └── ...
+│
+└── skills/
+    └── wecom-api/          # Skill 入口（供 AI 调用）
+        ├── index.js
+        └── SKILL.md
+```
+
+## 更新
+
+```bash
+cd /root/.openclaw/extensions/wecom-api
+git pull
+npm install
+systemctl --user restart openclaw-gateway
+```
+
+## 常见问题
+
+**Q: 与 @sunnoy/wecom 冲突吗？**
+A: 不冲突。@sunnoy/wecom 负责消息收发，本插件负责 API 调用和事件回调，走不同的 HTTP 路径。
+
+**Q: 回调验证失败？**
+A: 确认 Token / EncodingAESKey 与企业微信后台一致，且 URL 能在公网访问。
+
+**Q: 如何查询昨天的客户新增数？**
+A: 通过 `contact_stats` 模块查询，配合事件回调可以获取实时数据。
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,7 @@
+{
+  "corpId": "YOUR_CORP_ID",
+  "corpSecret": "YOUR_CORP_SECRET",
+  "agentId": "YOUR_AGENT_ID",
+  "token": "",
+  "encodingAESKey": ""
+}

package/config.js

@@ -0,0 +1,76 @@
+/**
+ * 企业微信插件 - 配置加载器
+ * 
+ * 使用方法：
+ * 1. 编辑 config.json 填入配置
+ * 2. const wecom = require('./config').createWecom();
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// 读取配置文件
+const configPath = path.join(__dirname, 'config.json');
+let fileConfig = {};
+
+if (fs.existsSync(configPath)) {
+  try {
+    fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    console.error('配置文件读取失败:', e.message);
+  }
+}
+
+/**
+ * 创建企业微信插件实例
+ * @param {object} overrideConfig 覆盖配置
+ * @returns {WeComPlugin}
+ */
+function createWecom(overrideConfig = {}) {
+  const WeComPlugin = require('./src/index');
+  
+  // 合并配置：文件配置 < 环境变量 < 代码传入
+  const config = {
+    ...fileConfig,
+    ...overrideConfig,
+    // 环境变量优先
+    corpId: process.env.WECOM_CORP_ID || fileConfig.corpId || overrideConfig.corpId,
+    corpSecret: process.env.WECOM_CORP_SECRET || fileConfig.corpSecret || overrideConfig.corpSecret,
+    agentId: process.env.WECOM_AGENT_ID || fileConfig.agentId || overrideConfig.agentId,
+    token: process.env.WECOM_TOKEN || fileConfig.token || overrideConfig.token,
+    encodingAESKey: process.env.WECOM_ENCODING_AES_KEY || fileConfig.encodingAESKey || overrideConfig.encodingAESKey,
+  };
+  
+  // 验证必填配置
+  if (!config.corpId || config.corpId === 'YOUR_CORP_ID') {
+    throw new Error('请先在 config.json 中配置 corpId（企业ID）');
+  }
+  if (!config.corpSecret || config.corpSecret === 'YOUR_CORP_SECRET') {
+    throw new Error('请先在 config.json 中配置 corpSecret（应用Secret）');
+  }
+  if (!config.agentId || config.agentId === 'YOUR_AGENT_ID') {
+    throw new Error('请先在 config.json 中配置 agentId（应用AgentID）');
+  }
+  
+  return new WeComPlugin(config);
+}
+
+/**
+ * 获取配置（完整版，供插件使用）
+ */
+function getConfig() {
+  return {
+    ...fileConfig,
+    corpId: process.env.WECOM_CORP_ID || fileConfig.corpId,
+    corpSecret: process.env.WECOM_CORP_SECRET || fileConfig.corpSecret,
+    agentId: process.env.WECOM_AGENT_ID || fileConfig.agentId,
+    token: process.env.WECOM_TOKEN || fileConfig.token,
+    encodingAESKey: process.env.WECOM_ENCODING_AES_KEY || fileConfig.encodingAESKey,
+  };
+}
+
+module.exports = {
+  createWecom,
+  getConfig,
+  config: fileConfig
+};

package/docs/approval-templates.example.json

@@ -0,0 +1,11 @@
+{
+  "_meta": {
+    "description": "企业微信审批模板ID配置示例",
+    "usage": "调用审批相关 API 时，必须通过 template_id 查询审批单号、审批单详情等",
+    "note": "template_id 获取方式：企业微信后台 → 应用管理 → 审批 → 查看模板ID",
+    "important": "实际使用时需要替换为真实的 template_id"
+  },
+  "分组名称": [
+    { "name": "模板名称", "template_id": "替换为真实的 template_id" }
+  ]
+}

package/docs/nginx-mirror.md

@@ -0,0 +1,193 @@
+# Nginx Mirror 企业微信多插件分发方案
+
+适用于企业微信自建应用只能配置一个回调 URL，但需要多个 OpenClaw 插件同时接收消息的场景。
+
+## ✨ 适用场景
+
+- 1 个企业微信自建应用
+- 仅 1 个回调地址
+- 需同时分发给多个插件
+- 无需新建应用、无需重复配置
+
+## 🌍 环境兼容
+
+- 物理机 / 虚拟机
+- Docker / 1Panel / 宝塔面板（容器环境自动适配）
+
+## 🚀 核心说明
+
+### 1. 主回调地址
+
+示例（@YanHaidao/wecom 默认）：
+```
+/plugins/wecom/agent/default
+```
+
+使用者可根据自己使用的插件修改。
+
+### 2. 容器环境特别说明
+
+如果你的 Nginx 运行在 1Panel / Docker / 宝塔面板容器中：
+
+```nginx
+# 容器内 127.0.0.1 指向自身，无法访问宿主机
+# 正确写法：
+proxy_pass http://host.docker.internal:18789$request_uri;
+```
+
+非容器环境（物理机）：
+```nginx
+proxy_pass http://127.0.0.1:18789$request_uri;
+```
+
+### 3. 扩展插件
+
+复制以下结构即可添加新插件：
+
+```nginx
+# 在主回调 location 中添加：
+mirror /mirror/your-plugin;
+
+# 添加新的 mirror location：
+location /mirror/your-plugin {
+    internal;
+    proxy_pass http://host.docker.internal:18789/plugins/your-plugin/callback;
+}
+```
+
+## ⚠️ 重要安全提示
+
+- 企业微信加密消息只能解密一次
+- 主插件负责解密，其他插件建议兼容明文模式
+- 所有镜像路由均使用 `internal`，外部无法访问
+
+## 📋 完整 Nginx 配置
+
+```nginx
+# ================================================================
+# 【通用模板】Nginx Mirror - 企业微信单回调 → 多插件分发
+# 适用：OpenClaw 生态 / 企业微信自建应用 / 单回调多插件场景
+# 兼容：物理机 / 虚拟机 / Docker / 1Panel / 宝塔面板
+# 说明：无任何隐私信息，安全可开源
+# ================================================================
+
+server {
+    listen 80;
+    listen 443 ssl;
+    server_name your-domain.com; # 【必填】修改为你的域名
+    index index.html;
+
+    # 日志路径
+    access_log /path/to/access.log main;
+    error_log /path/to/error.log;
+
+    # ------------------------------
+    # 通用安全规则
+    # ------------------------------
+    location ~ ^/(\.user\.ini|\.htaccess|\.git|\.env|\.svn|\.project|LICENSE|README\.md) {
+        return 404;
+    }
+    location ^~ /.well-known/acme-challenge {
+        allow all;
+        root /usr/share/nginx/html;
+    }
+    if ($uri ~ "^/\.well-known/.*\.(php|jsp|py|js|css|lua|ts|go|zip|tar\.gz|rar|7z|sql|bak)$") {
+        return 403;
+    }
+
+    # ------------------------------
+    # 【核心】主回调入口
+    # ------------------------------
+    location = /plugins/wecom/agent/default {
+
+        # 镜像分发（可无限添加）
+        mirror /mirror/wecom-api;
+        # mirror /mirror/your-plugin;
+
+        # 【A 非容器环境：物理机/虚拟机】
+        # proxy_pass http://127.0.0.1:18789$request_uri;
+
+        # 【B 容器环境：1Panel/Docker/宝塔】
+        proxy_pass http://host.docker.internal:18789$request_uri;
+
+        # 通用代理配置
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $websocket_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400;
+    }
+
+    # ------------------------------
+    # 镜像路由 → wecom-api
+    # ------------------------------
+    location /mirror/wecom-api {
+        internal;
+        proxy_pass http://host.docker.internal:18789/plugins/wecom-api/callback;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400;
+    }
+
+    # ------------------------------
+    # 全局插件代理
+    # ------------------------------
+    location ^~ /plugins/ {
+        proxy_pass http://host.docker.internal:18789$request_uri;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $websocket_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 86400;
+    }
+
+    # ------------------------------
+    # HTTP → HTTPS
+    # ------------------------------
+    if ($scheme = http) {
+        return 301 https://$host$request_uri;
+    }
+
+    # ------------------------------
+    # SSL 证书（必须修改）
+    # ------------------------------
+    ssl_certificate /path/to/fullchain.pem;
+    ssl_certificate_key /path/to/privkey.pem;
+
+    # ------------------------------
+    # SSL 通用安全配置
+    # ------------------------------
+    ssl_protocols TLSv1.3 TLSv1.2;
+    ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:!aNULL:!eNULL:!MD5;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
+}
+```
+
+## 🔧 使用步骤
+
+1. 修改 `your-domain.com` 为你的域名
+2. 填写 SSL 证书路径
+3. 选择容器 / 非容器代理地址（注释掉不需要的）
+4. 添加 / 删除 mirror 规则
+5. 重启 Nginx
+
+## 📁 文件说明
+
+```
+wecom-api/
+├── README.md                 # 主文档
+├── nginx-mirror.md          # 本文档（Nginx 配置说明）
+└── nginx.conf              # 完整 Nginx 配置（可选）
+```

package/openclaw.plugin.json

@@ -0,0 +1,15 @@
+{
+  "id": "wecom-api",
+  "channels": [],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "corpId": { "type": "string" },
+      "corpSecret": { "type": "string" },
+      "agentId": { "type": "string" },
+      "token": { "type": "string" },
+      "encodingAESKey": { "type": "string" }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jiexiaoyin/wecom-api",
+  "version": "0.0.2",
+  "description": "企业微信 API OpenClaw 插件，提供 32+ API 模块和事件回调处理",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "openclaw",
+    "wecom",
+    "enterprise-wechat",
+    "wechatwork",
+    "chatbot"
+  ],
+  "author": "jiexiaoyin <jiexiaoyin@jysm.vip>",
+  "license": "MIT",
+  "homepage": "https://github.com/jiexiaoyin/openclaw-wecom-api#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jiexiaoyin/openclaw-wecom-api.git"
+  },
+  "dependencies": {
+    "xml2js": "^0.6.2"
+  },
+  "openclaw": {
+    "extensions": [
+      "./plugin.cjs"
+    ]
+  },
+  "engines": {
+    "openclaw": ">=2026.0.0"
+  }
+}