wechat_msg_clicker/project.md

项目规划：WeChat 消息自动点击器

项目目标

创建一个长期稳定运行的自动化工具，自动点击微信桌面端中未读消息的图片和文件，触发微信下载原始文件到本地目录，配合信息收集系统完成数据入库流程。

项目状态

已完成 (v0.1.0 - 2026/04/22)

• 项目结构搭建
• 配置系统（YAML 配置文件、默认值、白/黑名单）
• AXUIElement 底层封装（ax_bridge.py）
• 微信 UI 导航（wechat_ui.py）— 聊天列表解析、消息类型分类
• UI 状态机（state_machine.py）— 基于窗口计数的状态检测与恢复
• 拟人行为引擎（human_like.py）— 高斯分布延迟、长休息、工作时间
• 主自动化逻辑（automator.py）— 完整扫描-点击-关闭循环
• 入口脚本（main.py）— 参数解析、信号处理
• 调试工具（--dump-ui, --dry-run）

待验证

• 在真实环境中测试 AXUIElement 对微信的访问能力
• 验证聊天列表 title 解析的准确性
• 验证图片点击后预览关闭的可靠性
• 长时间运行稳定性测试

未来可能的改进

• 聊天列表滚动支持（处理不在可见区域的聊天）
• 消息滚动支持（处理更早的图片消息）
• 已处理消息去重（记录已点击的媒体，避免重复）
• 微信版本适配（检测 UI 结构变化并自动调整）
• 运行状态 Web 面板（远程监控）
• 与信息收集系统直接集成

技术细节

微信 UI 结构 (v4.1.9)

• 主窗口 "微信" 包含侧边栏 + 聊天列表
• 聊天列表：AXList name="会话"，子元素为 AXStaticText
• 点击聊天项打开独立会话窗口
• 消息列表：AXList name="消息"
• 图片消息 title = "图片"，文件消息 title 以 "文件\n" 开头

防封策略

• 高斯分布随机延迟（非均匀）
• ±20% 扫描间隔抖动
• 5% 概率长休息（30-120 秒）
• 工作时间限制
• 每次最多 5 个聊天 / 每聊天最多 20 个媒体

依赖

• pyobjc-framework-Quartz
• pyobjc-framework-ApplicationServices
• pyobjc-framework-Cocoa
• PyYAML

系统要求

• macOS Sonoma 14+
• Python 3.11+
• 辅助功能权限（终端/Python 需要授权）
• 微信桌面端 v4.1.9+