# WeChat 消息自动点击器

自动点击微信桌面端未读消息中的图片和文件，触发原始文件下载到本地目录。

## 背景

微信桌面端不会自动下载图片/文件的原始数据，需要用户手动点击预览后才会触发下载。本工具通过 macOS 辅助功能 API 自动完成这个操作，配合信息收集系统实现群聊数据的自动化入库。

## 系统要求

- macOS Sonoma 14+
- Python 3.11+
- 微信桌面端 v4.1.9+（已登录）

## 安装

### 1. 安装 Python 依赖

```bash
cd wechat_msg_clicker
pip install -r requirements.txt
```

依赖包：
- `pyobjc-framework-Quartz` — macOS 图形框架绑定
- `pyobjc-framework-ApplicationServices` — 辅助功能 API 绑定
- `pyobjc-framework-Cocoa` — macOS 应用框架绑定
- `PyYAML` — 配置文件解析

### 2. 授权辅助功能权限

脚本需要 macOS 辅助功能权限才能操作微信 UI 元素：

1. 打开 **系统设置** > **隐私与安全性** > **辅助功能**
2. 点击左下角 **+** 号
3. 添加你使用的终端应用（如 Terminal.app 或 iTerm2）
4. 如果通过 Python 直接运行，还需要添加 Python 解释器路径（如 `/Users/你的用户名/miniconda3/bin/python3`）
5. 确保添加后开关为 **开启** 状态

> 首次运行时如果未授权，脚本会弹出系统提示框引导你授权。

### 3. 准备配置文件

```bash
cp config.example.yaml config.yaml
```

按需编辑 `config.yaml`，主要配置项：

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `scan.interval_seconds` | 30 | 扫描间隔（秒） |
| `scan.max_chats_per_scan` | 5 | 每次最多处理几个聊天 |
| `schedule.start_hour` | 8 | 工作开始时间 |
| `schedule.end_hour` | 23 | 工作结束时间 |
| `filter.mode` | all | 过滤模式：all / whitelist / blacklist |
| `filter.blacklist` | 微信系统号 | 排除的聊天名称 |
| `media.click_images` | true | 是否点击图片 |
| `media.click_files` | true | 是否点击文件 |
| `media.click_videos` | false | 是否点击视频（默认关闭） |
| `media.max_media_per_chat` | 20 | 每个聊天最多点击几个媒体 |

### 4. 确保微信就绪

- 微信桌面端已启动并登录
- 微信窗口保持可见（不能最小化到 Dock）
- 建议在专用电脑上运行，脚本运行时会操作微信前台窗口

## 验证流程

建议按以下顺序逐步验证，确认每步正常后再进入下一步：

### Step 1：验证 UI 访问

```bash
python main.py --dump-ui
```

预期输出：微信的 UI 元素树，包括窗口、按钮、聊天列表等信息。

**如果报错**：
- `辅助功能权限未授予` → 检查系统设置中的辅助功能授权
- `微信未运行` → 确保微信桌面端已启动
- `未找到微信主窗口` → 确保微信已登录，窗口未最小化

### Step 2：试运行扫描

```bash
python main.py --dry-run --once --debug
```

预期输出：扫描聊天列表，显示有未读消息的聊天和媒体数量，但**不会实际点击**。

检查日志确认：
- 能正确识别未读聊天
- 聊天名称解析正确
- 未读数量解析正确

### Step 3：单次完整执行

```bash
python main.py --once --debug
```

这会执行一次完整的循环：扫描 → 点击聊天 → 点击图片/文件 → 关闭预览 → 关闭会话。

观察过程中：
- 微信窗口是否正常被操作
- 图片预览是否正常打开和关闭
- 是否能正确返回聊天列表

### Step 4：正式运行

```bash
python main.py
```

脚本会持续运行，按配置的间隔和工作时间自动处理新消息。

后台运行建议使用 `nohup` 或 `tmux`：

```bash
# 方式一：nohup
nohup python main.py > /dev/null 2>&1 &

# 方式二：tmux（推荐，方便查看日志）
tmux new -s wechat
python main.py
# Ctrl+B D 分离会话
# tmux attach -t wechat 重新连接
```

## 命令参考

| 命令 | 说明 |
|---|---|
| `python main.py` | 持续运行 |
| `python main.py --once` | 单次扫描后退出 |
| `python main.py --dry-run` | 只扫描不点击 |
| `python main.py --dump-ui` | 输出微信 UI 元素树 |
| `python main.py --debug` | 开启 DEBUG 级别日志 |
| `python main.py --config path/to/config.yaml` | 指定配置文件 |

参数可组合使用，如 `python main.py --dry-run --once --debug`。

## 日志

日志同时输出到控制台和文件 `wechat_clicker.log`（可在配置中修改）。

日志文件自动轮转，默认最大 10MB，保留 5 个备份。

## 注意事项

- **封号风险**：工具内置了多种拟人策略（随机延迟、长休息、工作时间限制），但自动化操作始终存在被检测的可能，请自行评估风险
- **微信更新**：微信版本更新可能改变 UI 结构，导致脚本失效。如遇到问题，先用 `--dump-ui` 检查 UI 变化
- **前台占用**：脚本运行时会操作微信窗口，不建议同时手动使用微信