wxauto-pc 0.2.2

基于 uiautomation 的 Windows 微信桌面端自动化库

wxauto_pc

一个基于 uiautomation 的 Windows 微信桌面端自动化库。

当前项目主要面向 Python PC 端微信自动化 场景，提供微信初始化、状态检查、消息发送、群聊 @、消息读取、未读会话获取、文件发送等能力。项目内所有交互描述尽量使用中文，便于直接集成到中文业务系统中。

---

功能简介

系统工具（6 个）

• wechat_initialize：初始化微信连接
• wechat_status：获取微信运行状态
• wechat_activate：激活微信窗口
• wechat_check_activation：检查微信是否处于激活状态
• wechat_list_tools：列出当前可用工具
• get_my_info：获取当前微信账号信息

消息工具（7 个）

• send_message：发送文本消息
• send_message_with_mention：群聊 @ 后发送文本消息
• get_messages：获取当前聊天消息
• get_history：获取当前可见区域历史消息
• get_next_new_message：监听下一批新消息
• get_unread_messages：获取所有未读消息内容（只读取真正的未读消息，不读取历史）
• send_bulk_messages：批量发送文本消息

会话工具（5 个）

• switch_chat：切换聊天窗口
• get_sessions：获取会话列表
• filter_sessions：筛选会话列表
• get_unread_sessions：获取未读会话
• get_recent_groups：获取最近群聊

文件工具（1 个）

• send_file：发送文件（支持图片、文档等）

界面工具（1 个）

• switch_to_contact：切换到联系人页面

总计：20 个已实现工具

---

核心能力

WeChatClient 核心类方法

除了工具层封装，WeChatClient 核心类还提供以下底层方法供高级用户使用：

连接与状态

• activate() - 激活微信窗口
• is_active() - 检查微信是否激活
• get_status() - 获取微信运行状态
• get_profile() - 获取个人资料缓存

会话管理

• switch_to_chat(chat_name) - 切换到指定聊天
• get_chat_name() - 获取当前聊天名称
• get_sessions() - 获取会话列表
• get_unread_chats(ignore_list) - 获取未读聊天列表
• get_recent_groups() - 获取最近群聊
• get_unread_count(chat_name) - 获取指定聊天未读数

消息操作

• send_message(chat_name, message) - 发送文本消息
• send_message_with_mention(chat_name, mention_names, message) - 群聊 @ 发送
• send_file(chat_name, file_path) - 发送文件
• get_latest_messages(count) - 获取最新消息
• read_unread_messages_from_chat(chat_name, unread_count) - 只读取指定聊天的未读消息（MessageReader）
• read_all_unread_messages(ignore_list) - 读取所有未读会话的未读消息（MessageReader）

发送者信息

• get_sender_info(sender_name) - 获取单个发送者信息（昵称、微信号、备注）
• get_group_senders_info(messages) - 批量获取群聊发送者信息

界面操作

• click_contacts_tab() - 点击联系人标签
• click_top_avatar() - 点击顶部头像

缓存管理

• clear_message_cache() - 清空消息缓存
• clear_old_cache(days) - 清理指定天数前的缓存

---

运行环境

系统要求

• Windows 10 / Windows 11
• Python 3.10 及以上
• 已安装并登录 PC 版微信
• 需要桌面图形界面环境

当前限制

• 仅支持 Windows
• 不支持 Linux
• 不支持 macOS
• 微信客户端版本变动可能影响控件定位
• 部分能力依赖当前微信界面状态

---

安装方式

方式一：通过 PyPI 安装（推荐）

pip install wxauto-pc

升级到最新版：

pip install -U wxauto-pc

方式二：本地源码安装

git clone https://github.com/chungao435-eng/wxautopc.git
cd wxautopc
pip install -e .

---

快速开始

1. 初始化微信连接

from wxauto_pc.tools.system_tools import wechat_initialize

result = wechat_initialize()
print(result)

示例返回：

{
    "success": True,
    "tool_name": "wechat_initialize",
    "message": "已成功初始化微信连接",
    "data": {
        "connected": True,
        "active": True,
        "visible": True,
        "chat_name": "",
        "profile_loaded": False
    },
    "timestamp": "2026-04-06T12:34:56"
}

---

2. 发送文本消息

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import send_message

client = WeChatClient()
result = send_message(client, "张三", "你好，这是一条测试消息")
print(result)

---

3. 群聊 @ 发送消息

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import send_message_with_mention

client = WeChatClient()
result = send_message_with_mention(
    client,
    "项目讨论群",
    ["张三", "李四"],
    "请看一下这条消息"
)
print(result)

---

4. 获取未读会话

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import get_unread_sessions

client = WeChatClient()
result = get_unread_sessions(client)
print(result)

默认会过滤这些会话：

• 服务号、公众号、腾讯新闻
• 文件传输助手、微信支付
• 服务通知、微信游戏

---

5. 获取所有未读消息（推荐）

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import get_unread_messages

client = WeChatClient()
result = get_unread_messages(client)

# 返回结构：
# {
#     "success": True,
#     "tool_name": "get_unread_messages",
#     "message": "已获取 3 个会话的未读消息",
#     "data": [
#         {
#             "chat_name": "张三",
#             "chat_type": "private",
#             "unread_count": 2,
#             "messages": [
#                 {
#                     "sender": "张三",
#                     "content": "你好",
#                     "timestamp": "12:34",
#                     "is_mine": False,
#                     "sender_info": {"nickname": "张三", "wechat_id": "zhangsan123", "remark": ""}
#                 }
#             ]
#         }
#     ]
# }

for chat in result["data"]:
    print(f"\n{chat['chat_name']} ({chat['unread_count']} 条未读):")
    for msg in chat["messages"]:
        sender_info = msg.get("sender_info", {})
        print(f"  [{msg['timestamp']}] {msg['sender']}: {msg['content']}")
        if sender_info:
            print(f"    微信号: {sender_info.get('wechat_id', '未知')}")

说明：

• 只读取真正的未读消息，不读取历史消息
• 自动获取发送者详细信息（昵称、微信号、备注）
• 默认过滤系统会话（服务号、公众号等）
• 性能优化：只对未读消息点击头像获取信息

---

6. 获取未读会话列表（不含消息内容）

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import get_unread_sessions

client = WeChatClient()
result = get_unread_sessions(client)

for row in result["data"]:
    print(f"{row['chat_name']}: {row['unread']} 条未读")

---

7. 发送文件

from wxauto_pc.core.client import WeChatClient

client = WeChatClient()
success, message = client.send_file(
    "张三",
    r"C:\Users\Administrator\Desktop\test.pdf"
)
print(success, message)

说明：

• 已兼容路径前面混入部分不可见字符的情况
• 发送前会自动检查文件是否存在
• 支持图片、文档等多种文件类型

---

8. 获取发送者详细信息

from wxauto_pc.core.client import WeChatClient

client = WeChatClient()

# 获取单个发送者信息
sender_info = client.get_sender_info("张三")
print(sender_info)
# 返回: {"nickname": "张三", "wechat_id": "zhangsan123", "remark": "张三备注"}

# 批量获取群聊发送者信息
messages = [
    {"sender": "张三", "content": "你好"},
    {"sender": "李四", "content": "在吗"}
]
senders_info = client.get_group_senders_info(messages)
print(senders_info)
# 返回: {"张三": {...}, "李四": {...}}

---

推荐调用方式

项目提供两种调用方式：

方式一：工具层（推荐）

适合统一返回结构、直接接入系统。

from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import send_message

client = WeChatClient()
result = send_message(client, "张三", "你好")
print(result)

工具层返回结构统一为：

{
    "success": bool,      # 操作是否成功
    "tool_name": str,     # 工具名称
    "message": str,       # 操作结果描述
    "data": dict,         # 返回的数据
    "timestamp": str      # 时间戳
}

方式二：核心类（高级）

适合自定义封装和复杂逻辑。

from wxauto_pc.core.client import WeChatClient

client = WeChatClient()
status = client.get_status()
success, msg = client.send_message("张三", "你好")

---

开发与测试

手动测试脚本

项目提供多个手动测试脚本，便于本地快速验证功能：

# 测试发送消息
python tests/manual_test_send_message.py "张三" "你好，这是测试消息"

# 测试获取最新未读消息（推荐）
python tests/manual_test_get_latest_unread.py

注意：运行测试前请确保微信已登录并处于运行状态。

运行单元测试

python -m pytest

---

构建与发布

安装构建工具

pip install build twine Cython

构建分发包

python -m build

构建完成后会在 dist/ 目录生成：

• .tar.gz - 源码分发包
• .whl - 二进制分发包（包含 Cython 编译的 .pyd 文件）

检查分发包

twine check dist/*

上传到 PyPI

# 先上传到 TestPyPI 测试（推荐）
twine upload --repository testpypi dist/*

# 确认无误后上传到正式 PyPI
twine upload dist/*

上传时建议使用 PyPI API Token，不要直接使用账号密码。

---

版本管理

每次发版前，请同步修改以下位置的版本号：

• pyproject.toml (第 7 行)
• wxauto_pc/__init__.py (第 8 行)

版本号规范：

• 0.1.x：修复 bug 或小改进
• 0.x.0：新增功能
• x.0.0：重大更新或稳定正式版本

当前版本：0.2.2

---

技术特性

Cython 编译优化

核心模块使用 Cython 编译为 .pyd 文件，提升性能并便于分发：

• wxauto_pc.core._client - 客户端核心逻辑
• wxauto_pc.core._message_reader - 消息读取逻辑
• wxauto_pc.core._unread_monitor - 未读监控逻辑

编译后的二进制文件包含在分发包中，用户无需安装 Cython。

消息缓存机制

使用 SQLite 数据库缓存已发送消息，支持：

• 消息历史记录
• 发送者信息缓存
• 自动清理过期数据

缓存文件位置：data/message_cache.db

剪贴板优化

发送消息时优先使用剪贴板方式（pyperclip），避免：

• 中文输入法问题
• 特殊字符丢失
• 长文本发送失败

发送完成后自动恢复原剪贴板内容。

---

注意事项

1. 平台限制：本项目仅支持 Windows 微信桌面版，不支持 Linux 和 macOS。
2. 登录要求：运行自动化前请确保微信已经登录。
3. 界面操作：自动化运行时，尽量不要手动频繁切换微信界面。
4. 版本兼容：微信版本升级后，部分控件定位可能需要调整。
5. 文件路径：文件路径建议手动输入，避免复制时混入隐藏字符（已自动处理）。
6. 群聊 @：群聊 @ 功能建议先在测试群验证。
7. 批量操作：批量发送等功能建议先在测试账号验证。
8. 桌面环境：需要桌面图形界面环境，不支持无头模式。

---

项目状态

已实现功能 ✅

系统管理

• ✅ 微信初始化与连接
• ✅ 状态检查与窗口激活
• ✅ 个人信息获取

消息功能

• ✅ 文本消息发送
• ✅ 群聊 @ 发送
• ✅ 批量消息发送
• ✅ 文件发送（图片、文档等）
• ✅ 消息读取（当前聊天、历史记录）
• ✅ 未读消息获取（只读取真正的未读消息，含发送者详细信息）
• ✅ 新消息监听

会话管理

• ✅ 会话列表获取
• ✅ 会话筛选
• ✅ 未读会话获取
• ✅ 最近群聊获取
• ✅ 聊天窗口切换

发送者信息

• ✅ 单个发送者信息获取
• ✅ 批量发送者信息获取

界面操作

• ✅ 联系人页面切换

计划功能 📋

• 📋 send_url_card - 发送链接卡片
• 📋 get_friends - 获取好友列表
• 📋 get_chat_info - 获取聊天详细信息
• 📋 send_directory_files - 批量发送目录文件
• 📋 check_file_exists - 检查文件是否存在
• 📋 get_new_friends - 获取新好友请求
• 📋 accept_new_friend - 接受好友请求
• 📋 add_friend - 添加好友
• 📋 授权机制（一机一码）

---

免责声明

本项目仅用于合法、合规、授权范围内的自动化测试、效率工具和个人学习研究。请勿将本项目用于任何违反平台规则或法律法规的用途。使用本项目所产生的一切后果由使用者自行承担。

---

项目链接

• GitHub: https://github.com/chungao435-eng/wxautopc
• PyPI: https://pypi.org/project/wxauto-pc/
• 问题反馈: https://github.com/chungao435-eng/wxautopc/issues

---

许可证

MIT License

---

更新日志

v0.2.2 (2026-04-06)

• ✨ 新增 get_unread_messages 工具：获取所有未读消息内容（只读取真正的未读消息）
• ✨ 新增 MessageReader.read_unread_messages_from_chat() 方法：只读取指定聊天的未读消息
• ✨ 新增 MessageReader.read_all_unread_messages() 方法：读取所有未读会话的未读消息
• ✨ 新增发送者信息获取功能（自动获取昵称、微信号、备注）
• ✨ 新增批量获取群聊发送者信息
• ⚡ 性能优化：只对未读消息点击头像获取信息，避免不必要的 UI 操作
• 🐛 修复消息读取相关问题
• 🔧 优化 Cython 编译配置
• 🔧 注释掉调试输出，提升用户体验

v0.1.0 (2026-03-31)

• 🎉 首个公开版本
• ✨ 实现 19 个核心工具
• ✨ 支持消息发送、读取、会话管理
• ✨ 支持文件发送和群聊 @
• 📦 使用 Cython 编译核心模块

---

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

---

联系方式

如果你在使用中遇到问题，可以：

• 在 GitHub 提交 Issue
• 查看项目文档和示例代码
• 参考 CLAUDE.md 了解项目架构

---

⭐ 如果这个项目对你有帮助，欢迎 Star 支持！