Whatsapp Web

🚀 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

🔧 技術細節

架構

核心組件

1. WhatsApp 客戶端：實現與 WhatsApp Web 瀏覽器應用的交互。
2. 核心業務邏輯：處理 WhatsApp 的消息收發、聯繫人管理等核心功能。
3. WhatsApp API 客戶端：提供對 WhatsApp API 服務器的訪問接口。
4. REST API 路由：實現 HTTP 接口，供外部系統調用。
5. MCP 協議實現：實現模型上下文協議（Model Context Protocol）的支持。

部署選項

1. WhatsApp API 服務器：獨立運行的 REST API 服務。
2. MCP 服務器（獨立運行）：直接連接 WhatsApp Web 的 MCP 實現。
3. 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 事件。
• 支持發送媒體文件（圖片、音頻、文檔）。
• 群組聊天管理功能。
• 聯繫人管理（添加/刪除聯繫人）。
• 消息模板實現常見場景。
• 增強錯誤處理和恢復機制。

🤝 貢獻指南

1. 叉取倉庫。
2. 創建功能分支。
3. 提交更改。
4. 推送到分支。
5. 創建拉取請求。

請確保您的 PR：

• 代碼清晰且經過適當測試。
• 遵循代碼規範和命名約定。
• 提供詳細的提交信息和描述。

📄 依賴項

📝 日誌系統

級別

• debug：調試信息。
• info：一般信息。
• warn：警告信息。
• error：錯誤信息。
• fatal：嚴重錯誤。

配置

const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console({ colorize: true })
  ]
});

⚠️ 安全注意事項

1. 禁止在生產環境中暴露調試端點。
2. 配置適當的認證機制保護 API 接口。
3. 定期更新依賴庫以修復安全漏洞。
4. 使用 HTTPS 提供 API 服務。

📄 許可證

本項目遵循 MIT 協議。請查看 LICENSE 文件獲取詳細信息。

以上文檔為 WhatsApp Web 項目的開發指南，更多細節請參考相關代碼和註釋。