wechat_msg_clicker/CLAUDE.md

WeChat 消息自动点击器

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

项目背景

配合另一个信息收集项目使用：信息收集脚本负责将微信消息入库，但图片和文件需要被点击预览后微信才会下载原始文件到本地。本工具自动完成这个"点击"操作。

技术架构

• 语言: Python 3.11+
• 核心技术: macOS Accessibility API (AXUIElement) via pyobjc
• 目标应用: 微信桌面端 v4.1.9+ (bundle ID: com.tencent.xinWeChat)
• 运行平台: macOS Sonoma 14+

模块结构

wechat_clicker/
├── ax_bridge.py      # AXUIElement 底层封装（属性读取、鼠标点击、键盘事件、滚动）
├── wechat_ui.py      # 微信 UI 导航（聊天列表、消息列表、预览界面元素查找）
├── state_machine.py  # UI 状态机（窗口状态检测、恢复、Preview.app 管理）
├── automator.py      # 主自动化逻辑（扫描→进入聊天→滚动→点击图片/文件→循环）
├── human_like.py     # 拟人行为（高斯分布延迟、长休息、工作时间）
├── config.py         # YAML 配置加载
└── logger_setup.py   # 日志配置

关键设计决策

• 聊天列表项为 AXStaticText（无 AXPress），使用 CGEvent 鼠标坐标点击
• AXValue 位置/尺寸需用 AXValueGetValue 解包 CGPoint/CGSize
• 消息类型通过 title 内容判断："图片" → 图片，"文件\n..." → 文件
• 图片/文件气泡偏移点击：AXStaticText 覆盖整行（575px宽），实际气泡仅在左侧 ~80-170px 区域，使用 click_at_element_offset(x=120, y=height/2) 命中
• 图片处理：点击缩略图 → 点击"..." → 点击"使用预览打开" → 关闭 Preview.app
• 文件处理：直接点击触发下载
• 滚动方向：macOS CGEvent ScrollWheel 负值=向下滚（看新消息），正值=向上滚（看旧消息）
• 进入聊天后先滚到底部（负值），再向上滚动 5 轮（正值）加载历史消息
• 滚动使用 kCGEventMouseMoved + ScrollWheel（不触发点击），避免误点 UI 元素
• "..."按钮搜索限制在预览区域（独立窗口或主窗口 x>200），排除侧边栏
• 媒体去重基于消息列表子元素索引（child index），同一元素跨滚动轮次只处理一次
• 可见性检查基于元素中心点是否在消息列表可见区域内（30px margin）
• 状态检测基于窗口计数 + AXMinimized 属性：区分窗口存在但最小化 vs 真正可见
• 窗口恢复策略：NSRunningApplication.unhide（隐藏）→ AX API 设置 AXMinimized=False（最小化）→ activate（前台）；AppleScript 不可靠（微信不支持 miniaturized 属性）

使用方法

# 前置条件
pip install -r requirements.txt
# 系统设置 > 隐私与安全 > 辅助功能 → 添加终端/Python

# 复制配置
cp config.example.yaml config.yaml

# 运行
python main.py              # 持续运行
python main.py --once       # 单次扫描
python main.py --dry-run    # 只扫描不点击
python main.py --dump-ui    # 输出 UI 元素树
python main.py --dump-ui --chat "聊天名"  # 进入指定聊天 dump 消息元素树（诊断用）
python main.py --debug      # 详细日志

配置重点

• config.yaml 中可设置扫描间隔、延迟范围、白/黑名单、工作时间、媒体类型开关
• 默认不处理视频（media.click_videos: false）
• 默认黑名单包含微信系统账号

注意事项

• 微信窗口最小化或隐藏时工具会自动恢复（通过 AX API 设置 AXMinimized=False + NSRunningApplication activate）
• 运行时会占用微信前台操作
• 建议在专用电脑上运行