# wechat-robot

**Repository Path**: GODlpp/wechat-robot

## Basic Information

- **Project Name**: wechat-robot
- **Description**: 一个用于自动化微信添加好友的机器人工具，支持批量添加好友、自动发送消息等功能。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-30
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h3>中文 | <a href='./README.en.md'>English</a ></h3>
</div>

# 微信机器人工具

一个用于自动化微信添加好友的机器人工具，支持批量添加好友、自动发送消息等功能。

## 项目结构

```
wechat-robot/
├── src/                    # 源代码目录
│   ├── config/            # 配置管理
│   │   ├── __init__.py
│   │   └── config_manager.py
│   ├── core/              # 核心业务逻辑
│   │   ├── __init__.py
│   │   ├── database.py    # 数据库管理
│   │   └── wechat_robot.py # 微信机器人主类
│   └── utils/             # 工具类
│       ├── __init__.py
│       ├── automation_utils.py # 自动化操作工具
│       ├── csv_utils.py        # CSV文件操作工具
│       ├── image_utils.py      # 图像识别工具
│       └── logger.py           # 日志工具
├── config/                # 配置文件
│   └── robot.yaml        # 机器人配置
├── assets/               # 资源文件
│   └── images/          # 图像文件
├── tests/               # 测试文件
│   ├── __init__.py
│   └── test_image_recognition.py
├── scripts/             # 脚本文件
│   ├── run_robot.py     # 启动脚本
│   └── test_images.py   # 测试脚本
├── docs/                # 文档目录
├── requirements.txt     # 依赖包
└── README.md           # 项目说明
```

## 功能特性

- 🤖 **自动化操作**: 自动点击、输入、发送消息
- 🖼️ **图像识别**: 基于OpenCV的图像识别技术
- 🗄️ **多数据源支持**: 支持MySQL数据库和CSV文件两种数据源
- ⚙️ **配置管理**: 灵活的配置文件和环境变量支持
- 📝 **日志记录**: 完整的操作日志记录
- 🧪 **测试工具**: 内置图像识别测试工具
- 🔧 **模块化设计**: 清晰的代码结构和模块分离

## 安装依赖

```bash
pip3 install -r requirements.txt
```

## 配置说明

### 数据源配置

在 `config/robot.yaml` 中配置数据源：

```yaml
robot:
  # 数据源配置
  data_source:
    type: "database"  # 可选值: "database" 或 "csv"
    csv_file: "data/customer.csv"  # CSV文件路径（当type为csv时使用）
    page_size: 10  # 每页数据量
  
  # 数据库配置（当type为database时使用）
  db:
    host: localhost
    port: 3306
    user: root
    pass: your_password
    dbName: your_database
    page: 0
```

### CSV文件格式

当使用CSV数据源时，文件格式如下：

```csv
id,mobile,name
1,186****8887,测试1
2,186****8888,测试2
```

### 数据库配置

当使用数据库数据源时，需要配置数据库连接信息：

```yaml
robot:
  data_source:
    type: "database"
  db:
    host: localhost
    port: 3306
    user: root
    pass: your_password
    dbName: your_database
    page: 0
```

### 环境变量支持

也可以通过环境变量配置：

```bash
# 数据源配置
export DATA_SOURCE_TYPE=database  # 或 csv
export CSV_FILE=data/customer.csv
export PAGE_SIZE=10

# 数据库配置（当使用数据库时）
export DB_HOST=localhost
export DB_PORT=3306
export DB_USER=root
export DB_PASS=your_password
export DB_NAME=your_database
export DB_PAGE=0
```

## 数据库表结构

### 手机号表 (wt_customer)

```sql
CREATE TABLE wt_customer (
    id INT AUTO_INCREMENT PRIMARY KEY,
    mobile VARCHAR(20) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 消息模板表 (wt_message)

```sql
CREATE TABLE wt_message (
    id INT AUTO_INCREMENT PRIMARY KEY,
    message TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 使用方法

### 1. 启动机器人

```bash
python3 scripts/run_robot.py
```

### 2. 测试图像识别

```bash
python3 scripts/test_images.py
```

### 3. 新的推荐方式：
```bash
# 启动机器人
python3 main.py

# 测试图像识别
python3 main.py --test-images

# 调试模式
python3 main.py --debug
```

### 4. 编程方式使用

```python
from src.core import WeChatRobot
from src.config import ConfigManager

# 创建配置管理器
config_manager = ConfigManager()

# 创建机器人实例
robot = WeChatRobot(config_manager)

# 运行机器人
robot.run()
```

## 图像文件说明

在 `assets/images/` 目录下需要准备以下图像文件：

- `address_book.png` - 通信录按钮
- `new_customer.png` - 新的客户按钮
- `add.png` - 添加按钮
- `lastadd.png` - 最后添加按钮
- `wechat.png` - 微信图标
- `send.png` - 发送按钮
- `del.png` - 删除按钮
- `ok.png` - 确定按钮

## 注意事项

1. **屏幕分辨率**: 确保在不同分辨率下测试图像识别效果
2. **界面状态**: 保持微信界面状态一致，避免动画效果
3. **权限设置**: macOS需要授予辅助功能权限
4. **网络安全**: 注意遵守相关法律法规，合理使用

## 故障排除

### 图像识别失败

1. 检查图像文件是否清晰
2. 确保目标界面完全可见
3. 使用测试工具验证识别效果
4. 调整置信度参数

### 数据库连接失败

1. 检查数据库配置信息
2. 确认数据库服务是否运行
3. 验证用户权限

### 自动化操作失败

1. 检查macOS辅助功能权限
2. 确保微信界面稳定
3. 调整等待时间参数

## 开发指南

### 添加新功能

1. 在相应的模块中添加方法
2. 更新配置文件
3. 添加测试用例
4. 更新文档

### 代码规范

- 使用Python 3.7+
- 遵循PEP 8代码规范
- 添加类型注解
- 编写详细的文档字符串

## 许可证

本项目仅供学习和研究使用，请遵守相关法律法规。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 更新日志

### v2.1.0
- 添加多数据源支持（数据库/CSV文件）
- 新增CSV文件读取工具类
- 支持通过配置文件切换数据源
- 改进数据源配置管理
- 增强错误处理和日志记录

### v2.0.0
- 重构项目结构
- 添加模块化设计
- 改进配置管理
- 增强错误处理
- 添加测试工具

### v1.0.0
- 基础功能实现
- 图像识别
- 数据库集成