Metadata-Version: 2.4
Name: wx4py
Version: 0.1.0
Summary: wx4py - Python 微信自动化工具
Author: sang6438
License: Non-Commercial Open Source License 1.0
Project-URL: Homepage, https://github.com/sang6438/wx4py
Project-URL: Repository, https://github.com/sang6438/wx4py
Project-URL: Documentation, https://github.com/sang6438/wx4py/blob/main/README.md
Project-URL: Issues, https://github.com/sang6438/wx4py/issues
Keywords: wx4py,wechat,automation,uiautomation,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywin32>=305
Requires-Dist: comtypes>=1.2.0
Requires-Dist: uiautomation
Requires-Dist: pyperclip
Requires-Dist: markdown
Requires-Dist: beautifulsoup4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="docs/logo.png" alt="wx4py" width="200">

# wx4py

**Python 微信自动化工具**

**wx4py - Python 微信自动化工具**

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Non--Commercial-green)](./LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)](https://www.microsoft.com/windows)
[![WeChat Version](https://img.shields.io/badge/wechat-4.1.7%2B-orange)](https://weixin.qq.com/)

[快速开始](#-快速开始) • [功能特性](#-功能特性) • [文档](#-文档) • [示例](#-使用示例) • [贡献](#-贡献指南)

</div>

---

## 📖 项目简介

**wx4py** 是一个基于 UIAutomation 的微信自动化 Python 库，提供简洁的 API 实现消息群发、文件传输、聊天记录分析、群组管理等自动化操作。

通过简洁的 API 设计，轻松实现消息群发、文件传输、聊天记录分析、群组管理等复杂操作，大幅提升工作效率。

### 核心优势

- 🚀 **开箱即用** - 简洁的 API 设计，5 分钟上手
- 🎯 **功能完备** - 覆盖 90% 的日常微信自动化需求
- 🛡️ **稳定可靠** - 完善的错误处理和重试机制
- 📦 **零侵入** - 无需修改微信客户端，纯 UI 自动化
- 🔧 **易扩展** - 模块化设计，轻松自定义功能

---

## ✨ 功能特性

### 📨 消息管理

| 功能 | 方法 | 说明 |
|------|------|------|
| 发送消息 | `send_to(target, message)` | 发送消息给联系人或群 |
| 批量群发 | `batch_send(targets, message)` | 批量发送消息到多个目标 |
| 发送文件 | `send_file_to(target, file_path)` | 发送单个或多个文件 |
| 搜索联系人/群 | `search(keyword)` | 搜索并返回结果 |

**支持的消息类型**：
- ✅ 文本消息
- ✅ 单个文件（PDF、图片、文档等）
- ✅ 多个文件批量发送
- ✅ 文件 + 消息组合

### 📜 聊天记录

| 功能 | 方法 | 说明 |
|------|------|------|
| 获取聊天记录 | `get_chat_history(target, since)` | 按时间获取聊天记录 |
| 时间范围支持 | `since` 参数 | `today` / `yesterday` / `week` / `all` |

**返回数据**：
```python
{
    "type": "text",      # text / link / system
    "content": "消息内容",
    "time": "今天 15:30"
}
```

### 👥 群组管理

| 功能 | 方法 | 说明 |
|------|------|------|
| 获取群成员 | `get_group_members(group_name)` | 获取完整群成员列表 |
| 修改群昵称 | `set_group_nickname(group, nickname)` | 修改我在本群的昵称 |
| 消息免打扰 | `set_do_not_disturb(group, enable)` | 开关消息免打扰 |
| 置顶聊天 | `set_pin_chat(group, enable)` | 置顶/取消置顶聊天 |
| 修改群公告 | `modify_announcement_simple(group, content)` | 文本格式群公告 |
| Markdown 群公告 | `set_announcement_from_markdown(group, file)` | 支持 Markdown 格式 |

### 🔍 搜索功能

| 功能 | 说明 |
|------|------|
| 搜索联系人 | 返回联系人搜索结果 |
| 搜索群聊 | 返回群聊搜索结果 |
| 搜索聊天记录 | 返回聊天记录搜索结果 |
| 搜索网络结果 | 返回网络搜索结果 |

### 🎯 核心优势

- 🚀 **开箱即用** - 简洁的 API 设计，5 分钟上手
- 🎯 **功能完备** - 覆盖 90% 的日常微信自动化需求
- 🛡️ **稳定可靠** - 完善的错误处理和重试机制
- 📦 **零侵入** - 无需修改微信客户端，纯 UI 自动化
- 🔧 **易扩展** - 模块化设计，轻松自定义功能

---

## 🚀 快速开始

### 环境要求

- **操作系统**: Windows 10/11
- **Python**: 3.9 **或更高版本**
- **微信客户端**: Qt 版本（已测试 4.1.7.59、4.1.8.29）

### 安装

```bash
# 使用 pip 安装（推荐）
pip install wx4py

# 从源码安装
git clone https://github.com/sang6438/wx4py.git
cd wx4py
pip install .
```

### 基础示例

```python
from wx4py import WeChatClient

# 使用上下文管理器（推荐）
with WeChatClient() as wx:
    # 发送消息
    wx.chat_window.send_to("文件传输助手", "Hello, WeChat!")

    # 批量群发
    wx.chat_window.batch_send(
        ["技术部", "产品部", "设计部"],
        "明天下午 3 点开会",
        target_type='group'
    )

    # 发送文件
    wx.chat_window.send_file_to(
        "工作群",
        r"C:\reports\weekly.pdf",
        target_type='group'
    )

    # 获取聊天记录
    messages = wx.chat_window.get_chat_history(
        target="工作群",
        target_type='group',
        since='today'
    )
```

---

## 📚 文档

- 📖 [快速开始指南](./docs/QUICKSTART.md)
- 📋 [API 参考](./docs/QUICKSTART.md)
- 💡 [使用示例](./examples/)
- 🤖 [AI Skill 支持](#-ai-skill-支持)

---

## 💡 使用示例

### 场景1：定时群发通知

```python
import schedule
from wx4py import WeChatClient

def send_daily_notification():
    with WeChatClient() as wx:
        groups = ["技术部", "产品部", "运营部"]
        wx.chat_window.batch_send(
            groups,
            "【提醒】请提交日报",
            target_type='group'
        )

schedule.every().day.at("17:00").do(send_daily_notification)
```

### 场景2：聊天记录分析

```python
import pandas as pd
from wx4py import WeChatClient

with WeChatClient() as wx:
    messages = wx.chat_window.get_chat_history(
        "项目讨论组",
        target_type='group',
        since='week'
    )

    # 数据分析
    df = pd.DataFrame(messages)
    stats = df['type'].value_counts()
    print(f"本周消息统计:\n{stats}")
```

### 场景3：群组管理

```python
from wx4py import WeChatClient

with WeChatClient() as wx:
    # 批量管理多个群
    groups = ["工作群1", "工作群2", "工作群3"]

    for group in groups:
        wx.group_manager.set_pin_chat(group, enable=True)
        wx.group_manager.modify_announcement_simple(
            group,
            "工作时间: 9:00-18:00"
        )
```

更多示例请查看 [examples/](./examples/) 目录。

---

## 🤖 AI Skill 支持

本项目提供 **wx4-skill**，支持在 Claude Code / OpenClaw 中通过自然语言控制微信自动化。

### 使用方式

```
使用 wx4-skill 向这 3 个群发送通知：技术部、产品部、设计部
消息内容：明天下午 3 点开会
```

AI 会自动理解需求并生成可执行的 Python 代码。

详见项目仓库中的 `wx4-skill/SKILL.md`。

---

## 🏗️ 架构设计

```
wx4py/  # 源码包名
├── core/           # 核心模块
│   ├── window.py   # 窗口管理
│   └── uia_wrapper.py  # UIA 封装
├── pages/          # 页面对象
│   ├── chat_window.py  # 聊天窗口
│   └── group_manager.py  # 群组管理
├── utils/          # 工具模块
└── models/         # 数据模型
```

---

## ❓ 常见问题

<details>
<summary><b>Q: 支持哪些微信版本？</b></summary>

目前支持微信 Qt 版本，已测试版本：
- 4.1.7.59
- 4.1.8.29

</details>

<details>
<summary><b>Q: 可以在后台运行吗？</b></summary>

微信窗口需要在前台才能进行 UI 自动化操作，建议在专用机器上运行。

</details>

<details>
<summary><b>Q: 聊天记录能获取发送者吗？</b></summary>

受微信 UIA 限制，聊天记录暂无法获取发送者姓名，这是技术限制。

</details>

---

## 📝 更新日志

### v0.1.0 (2026-03-27)

- ✨ 首次发布
- ✅ 消息发送与群发
- ✅ 文件传输
- ✅ 聊天记录获取
- ✅ 群组管理功能

---

## 📄 许可证

本项目采用 **Non-Commercial Open Source License 1.0** 许可证。

- ✅ 允许个人、学习、研究、非营利用途
- ❌ 禁止商业使用（需获得授权）
- ⚠️ 衍生作品必须开源并使用相同许可

详见 [LICENSE](./LICENSE) 文件。

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star ⭐**

Made with ❤️ by wx4py Team

</div>
