一个统一的微信通信SDK，支持 QClaw 和 WorkBuddy 两种通信方式。简化开发流程，提供一致的API接口，完善的文档和丰富的示例。
- ✅ 双模式支持：QClaw（WebSocket + JPRX）和 WorkBuddy（Centrifuge + HTTP）
- ✅ 统一接口：无论选择哪种模式，都使用相同的API
- ✅ 自动认证：支持OAuth、扫码登录、token自动刷新
- ✅ 可靠消息：断线重连、消息队列、持久化存储
- ✅ 完善文档：API文档、集成指南、代码示例
- ✅ TypeScript支持：完整的类型定义和IDE自动补全
- ✅ 易于扩展：插件式架构，轻松支持新的通信方式
wechat-customer/
├── src/
│ ├── sdk/ # 核心SDK
│ │ ├── index.ts # SDK入口
│ │ ├── types.ts # 通用类型定义
│ │ ├── error.ts # 错误定义
│ │ │
│ │ ├── channels/ # 通信方式实现
│ │ │ ├── index.ts # 导出
│ │ │ ├── base.ts # 基础接口
│ │ │ ├── qclaw/ # QClaw实现
│ │ │ │ ├── client.ts
│ │ │ │ ├── auth.ts
│ │ │ │ └── types.ts
│ │ │ └── workbuddy/ # WorkBuddy实现
│ │ │ ├── client.ts
│ │ │ ├── auth.ts
│ │ │ └── types.ts
│ │ │
│ │ ├── message/ # 消息处理
│ │ │ ├── adapter.ts # 消息适配器
│ │ │ ├── queue.ts # 消息队列
│ │ │ └── types.ts # 消息类型
│ │ │
│ │ └── utils/ # 工具函数
│ │ ├── storage.ts # 文件存储
│ │ ├── logger.ts # 日志记录
│ │ └── retry.ts # 重试机制
│ │
│ ├── examples/ # 使用示例
│ │ ├── basic.ts # 基础示例
│ │ ├── qclaw-login.ts # QClaw登录示例
│ │ ├── workbuddy-login.ts # WorkBuddy登录示例
│ │ └── message-handling.ts # 消息处理示例
│ │
│ └── __tests__/ # 单元测试
│ ├── channels.test.ts
│ ├── message.test.ts
│ └── auth.test.ts
│
├── docs/ # 文档
│ ├── README-CN.md # 中文文档
│ ├── ARCHITECTURE.md # 架构设计
│ ├── API.md # API文档
│ ├── INTEGRATION.md # 集成指南
│ ├── EXAMPLES.md # 示例详解
│ └── TROUBLESHOOTING.md # 故障排查
│
├── package.json
├── tsconfig.json
├── jest.config.js
├── .eslintrc.json
└── .prettierrc
npm install @myorg/wechat-sdk
# 或
yarn add @myorg/wechat-sdkimport { WeChatSDK, LoginRequiredError } from '@myorg/wechat-sdk';
// mode 是必填项（'qclaw' 或 'workbuddy'）
// 首次启动：提供凭证，连接成功后自动保存到 ~/.wechat-sdk/{mode}/session.json
const sdk = new WeChatSDK({
mode: 'qclaw', // 必填 —— 'qclaw' 或 'workbuddy'
credentials: {
mode: 'qclaw',
channelToken: '...', // 见下方"凭证快速参考"
jwtToken: '...',
// guid 无需提供，SDK 自动生成
},
});
await sdk.connect();
// 后续启动：只需指定 mode，SDK 自动从 ~/.wechat-sdk/qclaw/session.json 恢复凭证
// const sdk = new WeChatSDK({ mode: 'qclaw' });
// await sdk.connect();
// 监听消息
sdk.on('message', (msg) => {
console.log('收到消息:', msg.content);
});
// 发送消息
await sdk.sendMessage({ to: 'user_id', content: '你好' });
await sdk.disconnect();详细说明（字段含义、获取方式、会话持久化）请查看 凭证指南。
const sdk = new WeChatSDK({
mode: 'qclaw', // ← 必填，决定存储路径（~/.wechat-sdk/qclaw/）
credentials: {
mode: 'qclaw',
channelToken: '...', // 扫码/JPRX 鉴权后获得
jwtToken: '...', // 与 channelToken 同步返回
userId: '...', // 可选，用户 ID
// guid 无需提供——SDK 自动生成并保存到 ~/.wechat-sdk/qclaw/device.json（oicq 模式）
},
});const sdk = new WeChatSDK({
mode: 'workbuddy', // ← 必填，决定存储路径（~/.wechat-sdk/workbuddy/）
credentials: {
mode: 'workbuddy',
userId: '...', // OAuth 返回的用户 ID
accessToken: '...', // OAuth 访问令牌
refreshToken: '...', // OAuth 刷新令牌（建议提供，用于自动刷新）
},
});// mode 必填；credentials 可不传，SDK 自动从 ~/.wechat-sdk/{mode}/session.json 恢复
const sdk = new WeChatSDK({ mode: 'qclaw' });
await sdk.connect();
// 本地没有会话时触发 loginRequired 事件并抛出 LoginRequiredError
sdk.on('loginRequired', ({ mode, ...rest }) => {
const guid = (rest as any).guid; // QClaw 模式携带自动生成的 guid
console.log(`需要登录 [${mode}]，guid=${guid ?? 'n/a'}`);
// 完成登录后提供凭证并重新 connect()
});
// 需要重新登录时清除会话（device.json 保留）
await sdk.clearSession();| 文档 | 内容 |
|---|---|
| 凭证指南 | 凭证字段说明、获取方式、会话持久化完整指南 |
| API文档 | 完整的API参考 |
| 集成指南 | 详细的集成步骤 |
| 架构设计 | SDK设计和实现细节 |
| 代码示例 | 常见场景的代码示例 |
| 故障排查 | 常见问题和解决方案 |
┌─────────────────────────────────────┐
│ 应用层（你的应用代码） │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ WeChatSDK 统一接口层 │
│ ├─ 连接管理 │
│ ├─ 消息处理 │
│ ├─ 事件分发 │
│ └─ 认证管理 │
└──────────────┬──────────────────────┘
│
┌───────┴───────┐
│ │
┌──────▼──────┐ ┌────▼─────────┐
│ QClaw │ │ WorkBuddy │
│ 通信层 │ │ 通信层 │
│ │ │ │
│ WebSocket │ │ Centrifuge │
│ + JPRX │ │ + HTTP │
└─────────────┘ └──────────────┘
│ │
└───────┬───────┘
│
┌──────▼──────────┐
│ 微信服务 API │
└─────────────────┘
- QClaw：通过微信JPRX网关的WebSocket连接
- WorkBuddy：通过Centrifuge和HTTP的混合模式
- 自动处理OAuth流程
- 支持扫码登录
- 自动token刷新
- 安全存储凭证
- 统一的消息格式
- 自动重试机制
- 消息队列
- 断线恢复
connected：连接已建立disconnected：连接已断开message：收到新消息error：发生错误tokenRefreshed：Token已刷新
interface SDKConfig {
// 通信模式：'auto' 自动选择、'qclaw' 或 'workbuddy'
mode?: 'auto' | 'qclaw' | 'workbuddy';
// 凭证信息
credentials?: ChannelCredentials;
// 连接配置
connection?: {
timeout?: number; // 连接超时时间（毫秒）
reconnectInterval?: number; // 重连间隔（毫秒）
maxReconnectAttempts?: number; // 最大重连次数
};
// 消息配置
message?: {
timeout?: number; // 消息发送超时（毫秒）
retryAttempts?: number; // 重试次数
queueSize?: number; // 队列大小
};
// 日志配置
logger?: {
level?: 'debug' | 'info' | 'warn' | 'error';
output?: (log: string) => void;
};
// 存储配置
storage?: {
dir?: string; // 存储目录
enablePersist?: boolean; // 是否持久化
};
}-
凭证管理
- 不要在代码中硬编码凭证
- 使用环境变量或安全的密钥管理服务
- 定期轮换token
-
连接安全
- 始终使用HTTPS/WSS
- 验证服务器证书
- 使用强密码和OAuth 2.0
-
消息安全
- 加密敏感信息
- 验证消息来源
- 实施消息签名
# 运行所有测试
npm test
# 运行特定测试
npm test -- channels.test.ts
# 生成覆盖率报告
npm test -- --coverage| 指标 | 目标值 |
|---|---|
| 连接建立时间 | < 2s |
| 消息延迟 | < 100ms |
| 消息吞吐量 | > 100 msg/s |
| 内存占用 | < 50MB |
| CPU占用 | < 5% |
如遇问题，请提供：
- 完整的错误信息和堆栈跟踪
- 复现步骤
- SDK版本和环境信息
- 相关日志
- ✅ QClaw通信方式
- ✅ WorkBuddy通信方式
- ✅ 统一SDK接口
- ✅ 完整文档和示例
MIT LICENSE
欢迎贡献代码、报告bug或提出建议！
- Fork 项目
- 创建特性分支
- 提交更改
- 推送到分支
- 创建 Pull Request
开始使用：查看 集成指南 了解详细步骤。