WhatsApp Web 机器人框架

简介

WhatsApp Web 机器人框架是一个用于控制 WhatsApp 账号发送和接收消息的强大工具。它基于 whatsapp-web.js，通过浏览器版 WhatsApp 进行连接。

入门指南

安装依赖项

项目使用 npm 包管理器进行依赖管理和运行时环境配置。安装所有依赖项：

npm install

使用 Docker

为了方便部署，项目提供了 Docker 镜像。拉取镜像并启动：

docker pull liuhuanjin0927/whatsapp-web-mcp:latest
docker run -it --rm liuhuanjin0927/whatsapp-web-mcp

快速上手

在 main.ts 文件中，你可以看到一个简单的运行示例：

import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';

async function run() {
    const WA = new WhatsApp({
        puppeteer: {
            executablePath: process.env.CHROME_PATH || undefined,
            args: ['--no-sandbox']
        },
        logLevel: 'info'
    });

    await WA.start();
    console.log('WhatsApp 已启动');
}

run().catch(console.error);

功能特性

• 消息收发：支持发送和接收文本、图片等消息
• 媒体处理：可以发送和下载图片、音频、文件等媒体内容
• 群组管理：提供群组聊天的创建、加入和退出功能
• 联系人管理：支持添加、删除和搜索联系人
• 日志系统：内置基于 Winston 的强大日志记录功能

操作指南

项目构建

从源代码构建项目：

npm run build

测试

使用 Jest 进行单元测试：

# 执行所有测试
npm test

# 监视模式下运行测试
npm run test:watch

# 生成覆盖报告
npm run test:coverage

格式化与代码质量

使用 ESLint 和 Prettier 维护代码规范：

# 运行检查
npm run lint

# 自动修复问题
npm run lint:fix

# 格式化代码
npm run format

故障排除

集成问题

• Claude Desktop 集成限制：由于 Claude 启动多个进程，无法在命令行模式下直接运行 wweb-mcp。为了解决这个问题，我们将应用拆分为 MCP 模式和 API 模式，以实现与 Claude 的兼容性。

未来计划

• 扩展媒体支持：支持发送视频、音频和文件
• 模板消息：提供常用场景的消息模板
• 高级群组功能：增强的群组管理特性
• 性能优化：提升机器人在高负载情况下的表现

贡献指南

如何贡献代码

1. Fork 项目仓库
2. 创建新的分支
3. 提交代码更改
4. 提交 Pull Request

开发注意事项

• 遵循项目的代码规范和风格
• 确保新增功能通过单元测试
• 提供详细的文档说明

日志记录

日志级别

项目支持以下日志级别：

• debug：调试信息
• info：一般信息
• warning：警告信息
• error：错误信息
• critical：严重错误
• fatal：致命错误

默认日志级别为 info。

故障排除指南

常见问题

1. 无法连接 WhatsApp 账号

   • 确保浏览器已登录目标账号
   • 检查网络连接状态
   • 查看控制台输出的错误信息

2. Docker 部署失败

   • 确保 Docker 服务正在运行
   • 检查镜像拉取日志
   • 核对端口映射和权限设置

贡献者名单

• 开发者：[你的名字]
• 维护人员：[维护者姓名]

许可证

本项目遵循 MIT License 协议。

感谢使用 WhatsApp Web 机器人框架！如有任何问题或建议，请随时联系我们。