@gloablehive/celphone-wechat-plugin 1.0.0

package/INSTALL.md

@@ -0,0 +1,231 @@
+# WorkPhone WeChat 插件安装指南
+
+> 本指南详细介绍如何将 WorkPhone WeChat 通道插件安装到 OpenClaw 系统。
+
+## 前置要求
+
+### 系统要求
+
+| 组件 | 要求 |
+|------|------|
+| Node.js | ≥ 18.0.0 |
+| pnpm | ≥ 8.0.0 |
+| OpenClaw | ≥ 1.0.0 |
+
+### 账号要求
+
+- ✅ WorkPhone 商业账号（需开通 WeChat API 权限）
+- ✅ WorkPhone API Key
+- ✅ 微信号已绑定到 WorkPhone
+
+## 安装步骤
+
+### 步骤 1：获取插件
+
+```bash
+# 方式 A：从本地目录安装（开发时）
+cd /path/to/openclaw
+pnpm add ./channels/celphone-wechat-plugin
+
+# 方式 B：从 npm 安装（生产环境）
+pnpm add @gloablehive/celphone-wechat-plugin
+```
+
+### 步骤 2：配置 OpenClaw
+
+编辑 OpenClaw 配置文件（通常是 `openclaw.json` 或 `.env`）：
+
+```json
+{
+  "channels": {
+    "celphone-wechat": {
+      "apiKey": "your-workphone-api-key",
+      "baseUrl": "https://api.workphone.example.com",
+      "wechatAccountId": "wp-wechat-001",
+      "wechatId": "wxid_xxxxx",
+      "nickName": "客服小微",
+      "accountId": "wechat-service-001",
+      "allowFrom": [],
+      "dmSecurity": "allowlist"
+    }
+  }
+}
+```
+
+#### 配置参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `apiKey` | ✅ | WorkPhone API 密钥 |
+| `wechatAccountId` | ✅ | WorkPhone 中的 WeChat 账号 ID |
+| `baseUrl` | - | WorkPhone API 地址（默认提供） |
+| `wechatId` | - | 微信实际 ID（wxid_xxx） |
+| `nickName` | - | 显示名称 |
+| `accountId` | - | 内部账号标识（用于 bindings 路由） |
+| `allowFrom` | - | 白名单：允许接收消息的微信 ID |
+| `dmSecurity` | - | 安全策略：`allowlist`/`blocklist`/`allowall` |
+
+### 步骤 3：配置消息路由（bindings）
+
+在 `openclaw.json` 中添加 bindings 配置，将消息路由到对应的 Agent：
+
+```json5
+{
+  "bindings": [
+    {
+      "agentId": "service-frontdesk",
+      "match": {
+        "channel": "celphone-wechat",
+        "accountId": "wechat-service-001"
+      }
+    }
+  ]
+}
+```
+
+### 步骤 4：配置 Webhook
+
+你需要配置 WorkPhone 将消息推送到你的 OpenClaw 实例：
+
+```
+Webhook URL: https://your-openclaw-instance.com/celphone-wechat/webhook
+```
+
+**如果使用 ngrok 本地开发：**
+
+```bash
+# 启动 ngrok 隧道
+ngrok http 3000
+
+# 将得到的 URL 配置到 WorkPhone 后台
+# 例如：https://abc123.ngrok.io/celphone-wechat/webhook
+```
+
+### 步骤 5：验证安装
+
+```bash
+# 启动 OpenClaw
+pnpm run dev
+
+# 检查日志中是否有以下输出：
+# [Channel] celphone-wechat initialized
+# [Webhook] Listening on /celphone-wechat/webhook
+```
+
+发送测试消息到微信号，确认消息能到达 OpenClaw。
+
+## 多微信号配置
+
+如果你需要管理多个微信号：
+
+```json
+{
+  "channels": {
+    "celphone-wechat": {
+      "accounts": [
+        {
+          "accountId": "wechat-service-001",
+          "wechatAccountId": "wp-wechat-001",
+          "wechatId": "wxid_cs001",
+          "nickName": "客服小微"
+        },
+        {
+          "accountId": "wechat-service-002",
+          "wechatAccountId": "wp-wechat-002",
+          "wechatId": "wxid_sales01",
+          "nickName": "销售小王"
+        }
+      ]
+    }
+  },
+  "bindings": [
+    {
+      "agentId": "service-frontdesk",
+      "match": {
+        "channel": "celphone-wechat",
+        "accountId": "wechat-service-001"
+      }
+    },
+    {
+      "agentId": "service-sales",
+      "match": {
+        "channel": "celphone-wechat",
+        "accountId": "wechat-service-002"
+      }
+    }
+  ]
+}
+```
+
+## 本地开发
+
+```bash
+# 进入插件目录
+cd channels/celphone-wechat-plugin
+
+# 安装依赖
+pnpm install
+
+# 运行测试
+pnpm test
+
+# 构建
+pnpm build
+```
+
+## 常见问题
+
+### Q: 消息收不到？
+
+1. 检查 Webhook URL 是否正确配置
+2. 检查 `dmSecurity` 设置是否正确
+3. 检查日志输出 `allowFrom` 列表
+
+### Q: 发送消息失败？
+
+1. 确认 API Key 权限
+2. 检查 wechatAccountId 是否正确
+3. 查看错误日志
+
+### Q: 如何开启安全模式？
+
+```json
+{
+  "dmSecurity": "allowlist",
+  "allowFrom": [
+    "wxid_customer001",
+    "wxid_customer002"
+  ]
+}
+```
+
+## 目录结构
+
+```
+celphone-wechat-plugin/
+├── package.json              # 插件清单
+├── openclaw.plugin.json      # 插件配置
+├── index.ts                  # 入口
+├── setup-entry.ts            # 轻量入口
+├── src/
+│   ├── channel.ts            # 通道实现
+│   ├── client.ts             # API 客户端
+│   └── cache/                # 本地缓存
+│       ├── manager.ts
+│       ├── writer.ts
+│       ├── indexer.ts
+│       ├── extractor.ts
+│       ├── compactor.ts
+│       ├── syncer.ts
+│       ├── saas-connector.ts
+│       └── message-queue.ts
+├── test-cache.ts             # 单元测试
+└── test-integration.ts       # 集成测试
+```
+
+## 相关文档
+
+- [README](./README.md) - 完整功能说明
+- [API 手册](../../data/apifox-workphone-3/handbooks/apifox-workphone-api-manual.md)
+- [缓存设计](./doc/spec/celphone-wechat-cache.md)
+- [Harness 工程规范](../../harness/AGENTS.md)

package/README.md

@@ -0,0 +1,259 @@
+# WorkPhone WeChat Channel Plugin
+
+OpenClaw channel plugin for connecting to WorkPhone's WeChat API. Enables sending and receiving WeChat messages through the WorkPhone platform.
+
+## ⚠️ Important: Human Account Model
+
+Unlike Telegram/WhatsApp bots, this channel connects to a **real human WeChat account**:
+
+- **Bot Mode** (Telegram/WhatsApp): One bot account → communicates with many users
+- **Human Mode** (This plugin): One real WeChat account → Agent manages ALL their friends and groups
+
+The agent needs to handle conversations with:
+- All friends (1-on-1 DM)
+- All group chats (chatrooms)
+- Friend requests
+- Moments interactions
+
+## Features
+
+- **Send/Receive Messages**: Send text, media, links, and more to WeChat friends and groups
+- **Friend Management**: Get friend list, update remarks, manage labels
+- **Group Chat**: Send messages to WeChat chatrooms (groups)
+- **Moments (朋友圈)**: Read and post to WeChat Moments
+- **Webhook Integration**: Receive real-time message callbacks from WorkPhone
+
+## Requirements
+
+- OpenClaw instance
+- WorkPhone account with WeChat API access
+- WorkPhone API key
+
+## Installation
+
+```bash
+# If using as a local plugin
+pnpm add ./channels/celphone-wechat-plugin
+
+# Or link from your plugin registry
+pnpm add @gloablehive/celphone-wechat-plugin
+```
+
+## Configuration
+
+Add to your OpenClaw config:
+
+```json
+{
+  "channels": {
+    "celphone-wechat": {
+      "apiKey": "your-workphone-api-key",
+      "baseUrl": "https://api.workphone.example.com",
+      "accountId": "your-workphone-account-id",
+      "wechatAccountId": "workphone-wechat-account-id",  // REQUIRED
+      "wechatId": "wxid_xxxxx",  // Actual WeChat ID
+      "nickName": "My WeChat",
+      "allowFrom": ["friend-wxid-1", "friend-wxid-2"],
+      "dmSecurity": "allowlist"
+    }
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | Yes | WorkPhone API key for authentication |
+| `wechatAccountId` | string | Yes | WeChat account ID from WorkPhone |
+| `baseUrl` | string | No | WorkPhone API base URL (default: provided by WorkPhone) |
+| `accountId` | string | No | WorkPhone account ID |
+| `wechatId` | string | No | Actual WeChat ID (wxid_xxx) |
+| `nickName` | string | No | Display name for this account |
+| `allowFrom` | string[] | No | WeChat IDs that can DM the agent |
+| `dmSecurity` | string | No | Policy: `allowlist`, `blocklist`, or `allowall` |
+| `webhookSecret` | string | No | Secret for webhook signature verification |
+
+## OpenClaw Configuration (bindings)
+
+To route WeChat messages to the correct agent, configure in `openclaw.json`:
+
+```json5
+{
+  // ... other config ...
+
+  bindings: [
+    // Internal management agents
+    {
+      agentId: "merchant-setup",
+      match: {
+        channel: "celphone-wechat",
+        accountId: "wechat-admin-001",
+      },
+    },
+    {
+      agentId: "merchant-ops",
+      match: {
+        channel: "celphone-wechat",
+        accountId: "wechat-ops-001",
+      },
+    },
+
+    // Service agents (customer-facing)
+    {
+      agentId: "service-frontdesk",
+      match: {
+        channel: "celphone-wechat",
+        accountId: "wechat-service-001",
+      },
+    },
+    {
+      agentId: "service-orders",
+      match: {
+        channel: "celphone-wechat",
+        accountId: "wechat-service-002",
+      },
+    }
+  ]
+}
+```
+
+### Multi-WeChat Account Support
+
+For enterprises managing multiple WeChat accounts:
+
+```json
+{
+  "channels": {
+    "celphone-wechat": {
+      // Account 1: Customer service
+      "apiKey": "xxx",
+      "wechatAccountId": "wp-wechat-001",
+      "wechatId": "wxid_customer_service",
+      "nickName": "客服小微",
+      "accountId": "wechat-service-001"
+    }
+  }
+}
+```
+
+Each WeChat account maps to a different `accountId` in bindings for routing.
+
+## Webhook Setup
+
+To receive messages, configure WorkPhone to send webhooks to your OpenClaw instance:
+
+```
+Your OpenClaw URL: https://your-instance.com/celphone-wechat/webhook
+```
+
+The webhook will POST message events to OpenClaw in real-time.
+
+## Supported Message Types
+
+### Outbound (Sending) - Both DM and Group
+
+- **Direct Messages (DM)**: Text, images, videos, files, links to friends
+- **Group Messages**: Text, images, videos, files to chatrooms (supports @mention)
+
+### Inbound (Receiving)
+
+- Text messages from friends
+- Text messages from group chats
+- Media messages (images, videos, files)
+- Friend requests
+- Group invitations (if enabled)
+
+## API Coverage
+
+This plugin integrates with the WorkPhone WeChat API (131 APIs). Key covered areas:
+
+- **WeChat Accounts**: List accounts, get account info
+- **Friends**: Get friends, add friends, accept requests, update remarks/labels
+- **Chatrooms**: Get group list, send to groups, update group name/announcement
+- **Messages**: Send/receive friend messages and chatroom messages
+- **Moments**: Read posts, publish moments, comment, like
+
+See [API Manual](./docs/apifox-workphone-api-manual.md) for full API documentation.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+```
+
+## File Structure
+
+```
+celphone-wechat-plugin/
+├── package.json              # Plugin manifest
+├── openclaw.plugin.json      # Plugin config schema
+├── index.ts                  # Entry point
+├── setup-entry.ts            # Lightweight setup entry
+├── src/
+│   ├── channel.ts            # Channel plugin implementation
+│   └── client.ts             # WorkPhone API client
+└── README.md
+```
+
+## License
+
+---
+
+## 附录：与企业平台集成要点
+
+根据企业场景总方案，这个 channel 需要与外部平台集成：
+
+### 1. 用户画像查询（外部平台提供）
+
+Service agent 应通过外部平台 API 查询用户画像：
+
+```
+Service Agent -> 外部平台 API -> 返回: displayTier, serviceState, riskFlags, preferenceHints
+```
+
+### 2. 沟通记录归档
+
+消息需要回写到外部平台：
+
+```
+WorkPhone Webhook -> OpenClaw -> 外部平台 ConversationLog
+```
+
+具体实现：在 `handleInboundMessage` 中添加归档逻辑。
+
+### 3. 外部平台作为 Source of Truth
+
+按照总方案：
+- **用户主数据外置** - 不存 OpenClaw
+- **沟通记录归档** - 写到外部平台
+- **OpenClaw 只保留运行时缓存**
+
+### 4. Security 注意事项
+
+- `dmSecurity: "allowlist"` - 只接受白名单用户消息
+- Service agent 权限最小化（workspace 只读）
+- 敏感操作需要审批
+
+---
+
+## 附录：API 文档关联
+
+配套的 WorkPhone WeChat API 手册位置：
+
+- 完整手册：`../../data/apifox-workphone-3/handbooks/apifox-workphone-api-manual.md`
+- JSON 索引：`../../data/apifox-workphone-3/handbooks/apifox-workphone-api-manual.json`
+- 原始 API：`../../data/apifox-workphone-3/raw/*.json`
+
+如有 OpenClaw skill 需要基于这些文档回答问题，可参考 `../../skills/workphone-apifox-api/`
+
+## License
+
+MIT

package/dist/index-simple.js

@@ -0,0 +1,9 @@
+/**
+ * OpenClaw Channel Plugin Entry Point - Simplified Version
+ *
+ * WorkPhone WeChat Plugin - 最小可运行版本
+ */
+import { celPhoneWeChatPlugin } from "./src/channel.js";
+// 直接导出插件，不使用复杂包装
+export default celPhoneWeChatPlugin;
+export { celPhoneWeChatPlugin };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OpenClaw Channel Plugin Entry Point
+ *
+ * WorkPhone WeChat Plugin - enables OpenClaw to send/receive WeChat messages
+ * through the WorkPhone API platform.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk/core").OpenClawPluginConfigSchema;
+    register: (api: import("openclaw/plugin-sdk/core").OpenClawPluginApi) => void;
+    channelPlugin: import("openclaw/plugin-sdk/core").ChannelPlugin<import("./src/channel.js").CelPhoneWeChatResolvedAccount, unknown, unknown>;
+    setChannelRuntime?: (runtime: import("openclaw/plugin-sdk/core").PluginRuntime) => void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * OpenClaw Channel Plugin Entry Point
+ *
+ * WorkPhone WeChat Plugin - enables OpenClaw to send/receive WeChat messages
+ * through the WorkPhone API platform.
+ */
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { celPhoneWeChatPlugin, handleInboundMessage } from "./src/channel.js";
+export default defineChannelPluginEntry({
+    id: "celphone-wechat",
+    name: "WorkPhone WeChat",
+    description: "Connect OpenClaw to WorkPhone WeChat API for sending and receiving WeChat messages",
+    plugin: celPhoneWeChatPlugin,
+    registerCliMetadata(api) {
+        api.registerCli(({ program }) => {
+            program
+                .command("celphone-wechat")
+                .description("WorkPhone WeChat channel management")
+                .option("-a, --account <id>", "WeChat account ID")
+                .option("-l, --list", "List configured WeChat accounts");
+        }, {
+            descriptors: [
+                {
+                    name: "celphone-wechat",
+                    description: "WorkPhone WeChat channel",
+                    hasSubcommands: true,
+                },
+            ],
+        });
+    },
+    registerFull(api) {
+        // Register webhook endpoint for receiving messages from WorkPhone
+        api.registerHttpRoute({
+            path: "/celphone-wechat/webhook",
+            auth: "plugin", // Plugin-managed auth - verify signatures yourself
+            handler: async (req, res) => {
+                try {
+                    // Parse the webhook payload
+                    // The exact format depends on WorkPhone's webhook configuration
+                    const payload = req.body;
+                    // Verify the request is from WorkPhone
+                    // Add signature verification here if needed
+                    const signature = req.headers["x-workphone-signature"];
+                    if (!signature) {
+                        res.statusCode = 401;
+                        res.end("Missing signature");
+                        return true;
+                    }
+                    // Handle the inbound message
+                    await handleInboundMessage(api, payload);
+                    res.statusCode = 200;
+                    res.end("ok");
+                    return true;
+                }
+                catch (error) {
+                    console.error("Webhook error:", error);
+                    res.statusCode = 500;
+                    res.end("Internal error");
+                    return true;
+                }
+            },
+        });
+        // Register gateway method for outbound media handling
+        api.registerGatewayMethod({
+            method: "POST",
+            path: "/celphone-wechat/media",
+            handler: async (req, res) => {
+                const { messageId, mediaUrl, mediaType } = req.body;
+                // Handle media upload/send through WorkPhone
+                // This is called when the bot needs to send media files
+                res.statusCode = 200;
+                res.json({ success: true, messageId });
+                return true;
+            },
+        });
+    },
+});

package/dist/mock-server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mock WorkPhone API Server for Testing
+ *
+ * 模拟 WorkPhone 的 API 端点，用于本地测试
+ */
+export {};