Metadata-Version: 2.4
Name: wxauto-pc
Version: 0.1.3
Summary: 基于 uiautomation 的 Windows 微信桌面端自动化库
Author: Claude Code
License-Expression: MIT
Project-URL: Homepage, https://github.com/chungao435-eng/wxautopc
Project-URL: Repository, https://github.com/chungao435-eng/wxautopc
Project-URL: Issues, https://github.com/chungao435-eng/wxautopc/issues
Keywords: wechat,uiautomation,windows,automation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uiautomation>=2.0.20
Requires-Dist: pyperclip>=1.8.0
Dynamic: license-file

# wxauto_pc

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

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

---

## 功能简介

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

### 消息工具（6 个）
- `send_message`：发送文本消息
- `send_message_with_mention`：群聊 @ 后发送文本消息
- `get_messages`：获取当前聊天消息
- `get_history`：获取当前可见区域历史消息
- `get_next_new_message`：监听下一批新消息
- `send_bulk_messages`：批量发送文本消息

### 会话工具（5 个）
- `switch_chat`：切换聊天窗口
- `get_sessions`：获取会话列表
- `filter_sessions`：筛选会话列表
- `get_unread_sessions`：获取未读会话
- `get_recent_groups`：获取最近群聊

### 文件工具（1 个）
- `send_file`：发送文件（支持图片、文档等）

### 界面工具（1 个）
- `switch_to_contact`：切换到联系人页面

**总计：19 个已实现工具**

---

## 核心能力

### 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)` - 获取最新消息

**发送者信息**
- `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 安装（推荐）

```bash
pip install wxauto-pc
```

升级到最新版：

```bash
pip install -U wxauto-pc
```

### 方式二：本地源码安装

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

---

## 快速开始

### 1. 初始化微信连接

```python
from wxauto_pc.tools.system_tools import wechat_initialize

result = wechat_initialize()
print(result)
```

示例返回：

```python
{
    "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. 发送文本消息

```python
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. 群聊 @ 发送消息

```python
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. 获取未读会话

```python
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. 获取所有未读会话的消息

```python
from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.message_tools import get_unread_sessions, get_messages

client = WeChatClient()
unread_result = get_unread_sessions(client)

for row in unread_result["data"]:
    chat_name = row["chat_name"]
    unread_count = row["unread"]
    message_result = get_messages(client, chat_name, count=unread_count or 20)
    print(f"{chat_name}: {message_result}")
```

---

### 6. 发送文件

```python
from wxauto_pc.core.client import WeChatClient

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

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

---

### 7. 获取发送者详细信息

```python
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)
# 返回: {"张三": {...}, "李四": {...}}
```

---

## 推荐调用方式

项目提供两种调用方式：

### 方式一：工具层（推荐）
适合统一返回结构、直接接入系统。

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

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

工具层返回结构统一为：

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

### 方式二：核心类（高级）
适合自定义封装和复杂逻辑。

```python
from wxauto_pc.core.client import WeChatClient

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

---

## 开发与测试

### 手动测试脚本

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

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

# 测试获取所有未读消息
python tests/manual_test_get_all_unread_messages.py
```

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

### 运行单元测试

```bash
python -m pytest
```

---

## 构建与发布

### 安装构建工具

```bash
pip install build twine Cython
```

### 构建分发包

```bash
python -m build
```

构建完成后会在 `dist/` 目录生成：
- `.tar.gz` - 源码分发包
- `.whl` - 二进制分发包（包含 Cython 编译的 .pyd 文件）

### 检查分发包

```bash
twine check dist/*
```

### 上传到 PyPI

```bash
# 先上传到 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.1.3**

---

## 技术特性

### 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](https://github.com/chungao435-eng/wxautopc)
- **PyPI**: [https://pypi.org/project/wxauto-pc/](https://pypi.org/project/wxauto-pc/)
- **问题反馈**: [https://github.com/chungao435-eng/wxautopc/issues](https://github.com/chungao435-eng/wxautopc/issues)

---

## 许可证

MIT License

---

## 更新日志

### v0.1.3 (2026-04-06)
- ✨ 新增发送者信息获取功能
- ✨ 新增批量获取群聊发送者信息
- 🐛 修复消息读取相关问题
- 🔧 优化 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](https://github.com/chungao435-eng/wxautopc/issues)
- 查看项目文档和示例代码
- 参考 `CLAUDE.md` 了解项目架构

---

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