Metadata-Version: 2.4
Name: wxauto-pc
Version: 0.1.2
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 端微信自动化** 场景，提供微信初始化、状态检查、消息发送、群聊 @、消息读取、未读会话获取、文件发送等能力。项目内所有交互描述尽量使用中文，便于直接集成到中文业务系统中。

---

## 功能简介

当前已实现或已提供基础能力的功能包括：

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

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

### 联系人工具
- `switch_chat`：切换聊天窗口
- `get_chat_info`：待完善
- `get_friends`：待完善

### 会话工具
- `get_sessions`：获取会话列表
- `filter_sessions`：筛选会话列表
- `get_unread_sessions`：获取未读会话
- `get_recent_groups`：获取最近群聊

### 文件工具
- `send_file`：发送文件
- `send_image`：待补充工具层封装
- `send_directory_files`：待完善
- `check_file_exists`：待完善

### 好友请求工具
- `get_new_friends`：待完善
- `accept_new_friend`：待完善
- `add_friend`：待完善

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

---

## 运行环境

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

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

---

## 安装方式

### 方式一：通过 PyPI 安装

当项目发布到 PyPI 后，可直接执行：

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

升级到最新版：

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

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

```bash
git clone <你的仓库地址>
cd wxaoto-claude
pip install -e .
```

### 安装依赖

如果你只想先安装打包与发布工具：

```bash
pip install build twine
```

---

## 快速开始

---

### 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-03-31T12:34:56"
}
```

---

### 2. 获取微信运行状态

```python
from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.system_tools import wechat_status

client = WeChatClient()
result = wechat_status(client)
print(result)
```

---

### 3. 激活微信窗口

```python
from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.system_tools import wechat_activate

client = WeChatClient()
result = wechat_activate(client)
print(result)
```

---

### 4. 获取当前账号个人信息

```python
from wxauto_pc.core.client import WeChatClient
from wxauto_pc.tools.system_tools import get_my_info

client = WeChatClient()
result = get_my_info(client)
print(result)
```

---

### 5. 发送文本消息

```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)
```

---

### 6. 群聊 @ 发送消息

```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)
```

---

### 7. 获取当前聊天消息

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

client = WeChatClient()
result = get_messages(client, "张三", count=20)
print(result)
```

---

### 8. 获取未读会话

```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)
```

默认会过滤这些会话：
- 服务号
- 公众号
- 腾讯新闻
- 文件传输助手
- 微信支付
- 服务通知
- 微信游戏

---

### 9. 获取所有未读会话的消息

```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(chat_name, message_result)
```

---

### 10. 发送文件

```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)
```

说明：
- 已兼容路径前面混入部分不可见字符的情况
- 发送前会检查文件是否存在

---

## 推荐调用方式

当前项目有两种调用方式：

### 方式一：调用核心类
适合你自己做二次封装。

例如：

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

client = WeChatClient()
print(client.get_status())
```

### 方式二：调用工具层
适合统一返回结构、直接接入系统。

例如：

```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": True,
    "tool_name": "send_message",
    "message": "发送成功",
    "data": {...},
    "timestamp": "2026-03-31T12:34:56"
}
```

---

## 手动测试脚本

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

- `tests/manual_test_wechat_initialize.py`：测试微信初始化与激活
- `tests/manual_test_get_my_info.py`：测试获取个人信息
- `tests/manual_test_send_message.py`：测试发送文本消息
- `tests/manual_test_send_message_with_mention.py`：测试群聊 @ 发送消息
- `tests/manual_test_send_file.py`：测试发送文件
- `tests/manual_test_get_all_unread_messages.py`：测试读取所有未读消息

例如：

```bash
python "g:/wxaoto-claude/tests/manual_test_send_message.py" "张三" "你好，这是测试消息"
```

---

## 发布到 PyPI

如果你要把当前项目发布到 PyPI，建议按下面步骤操作。

### 1. 安装发布工具

```bash
pip install build twine
```

### 2. 运行测试

```bash
python -m pytest
```

### 3. 构建发布包

```bash
python -m build
```

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

- `.tar.gz`
- `.whl`

### 4. 检查发布包

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

### 5. 上传到 TestPyPI（推荐先测试）

```bash
twine upload --repository testpypi dist/*
```

### 6. 上传到正式 PyPI

```bash
twine upload dist/*
```

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

---

## 版本管理建议

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

- `pyproject.toml`
- `wxauto_pc/__init__.py`

例如：
- `0.1.0`：首个公开版本
- `0.1.1`：修复 bug
- `0.2.0`：新增功能
- `1.0.0`：稳定正式版本

---

## 注意事项

1. 本项目仅支持 Windows 微信桌面版。
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`
- 授权机制（一机一码，当前暂不启用）

---

## 免责声明

本项目仅用于合法、合规、授权范围内的自动化测试、效率工具和个人学习研究。请勿将本项目用于任何违反平台规则或法律法规的用途。

---

## 联系与反馈

如果你在使用中遇到问题，可以在项目仓库中提交 Issue。
