🚀 WhatsApp Web 项目文档
WhatsApp Web 是基于 WhatsApp 的网络客户端，借助网页浏览器就能使用 WhatsApp 功能。此项目提供了丰富的 API 及协议实现，极大地方便了开发者进行集成与扩展。
🚀 快速开始
WhatsApp Web 项目为开发者提供了便捷的集成和扩展途径，通过丰富的 API 和协议实现，可轻松实现与 WhatsApp Web 功能的交互。
✨ 主要特性
- 基于网页浏览器，支持使用 WhatsApp 功能。
- 提供丰富 API 和协议实现，便于开发者集成扩展。
- 架构灵活，支持多种部署场景。
📦 安装指南
构建
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
# 验证代码（检查 + 测试）
npm run validate
🔧 技术细节
架构
核心组件
- WhatsApp 客户端：实现与 WhatsApp Web 浏览器应用的交互。
- 核心业务逻辑：处理 WhatsApp 的消息收发、联系人管理等核心功能。
- WhatsApp API 客户端：提供对 WhatsApp API 服务器的访问接口。
- REST API 路由：实现 HTTP 接口，供外部系统调用。
- MCP 协议实现：实现模型上下文协议（Model Context Protocol）的支持。
部署选项
- WhatsApp API 服务器：独立运行的 REST API 服务。
- MCP 服务器（独立运行）：直接连接 WhatsApp Web 的 MCP 实现。
- MCP 服务器（API 客户端）：通过 API 服务器进行连接。
这种架构设计使得系统可以灵活部署，支持以下场景：
- 在不同机器上分别运行 API 服务器和 MCP 服务器。
- 使用 MCP 服务器作为现有 API 服务器的客户端。
- 所有组件在单台机器上运行。
项目结构
src/
├── whatsapp-client.ts # WhatsApp Web 客户端实现
├── whatsapp-service.ts # 核心业务逻辑实现
├── whatsapp-api-client.ts # 对 WhatsApp API 服务器的客户端访问
├── api.ts # REST API 路由实现
├── mcp-server.ts # MCP 协议实现
└── main.ts # 应用程序入口点
💻 使用示例
基础用法
项目使用过程中的基础操作，可参考以下命令：
# 构建项目
npm run build
# 执行所有测试
npm test
高级用法
在开发过程中，可使用以下命令进行更高级的操作：
# 监视模式下运行测试（开发中）
npm run test:watch
# 生成测试覆盖率报告
npm run test:coverage
⚙️ 故障排除
Claude Desktop 集成问题
- 由于 Claude 打开多个进程，无法在命令行独立模式下运行 wweb-mcp。为了解决此限制，我们将应用拆分为 API 和 MCP 模式，以支持与 Claude 的良好集成。
📈 计划功能
- 创建 webhook 用于接收消息和其他 WhatsApp 事件。
- 支持发送媒体文件（图片、音频、文档）。
- 群组聊天管理功能。
- 联系人管理（添加/删除联系人）。
- 消息模板实现常见场景。
- 增强错误处理和恢复机制。
🤝 贡献指南
- 叉取仓库。
- 创建功能分支。
- 提交更改。
- 推送到分支。
- 创建拉取请求。
请确保您的 PR：
- 代码清晰且经过适当测试。
- 遵循代码规范和命名约定。
- 提供详细的提交信息和描述。
📄 依赖项
| 属性 | 详情 |
|---|---|
| 包名 | express、ws、winston、dotenv |
| 版本 | ^4.18.2、^7.5.3、^3.0.1、^16.3.1 |
| 描述 | 实现 HTTP 服务器、WebSocket 支持、日志库、加载环境变量 |
📝 日志系统
级别
- debug：调试信息。
- info：一般信息。
- warn：警告信息。
- error：错误信息。
- fatal：严重错误。
配置
const logger = winston.createLogger({
level: 'info',
transports: [
new winston.transports.Console({ colorize: true })
]
});
⚠️ 安全注意事项
- 禁止在生产环境中暴露调试端点。
- 配置适当的认证机制保护 API 接口。
- 定期更新依赖库以修复安全漏洞。
- 使用 HTTPS 提供 API 服务。
📄 许可证
本项目遵循 MIT 协议。请查看 LICENSE 文件获取详细信息。
以上文档为 WhatsApp Web 项目的开发指南，更多细节请参考相关代码和注释。