Metadata-Version: 2.4
Name: wxpy4
Version: 0.4.5
Summary: Python 微信自动化工具 — 基于 UIAutomation 的微信桌面客户端自动化库（Windows Qt 版微信）
Project-URL: Homepage, https://github.com/shiack/db-app
Project-URL: Repository, https://github.com/shiack/db-app
Project-URL: Issues, https://github.com/shiack/db-app/issues
Project-URL: Documentation, https://github.com/shiack/db-app/tree/main/lib/wx4py
Author: wx4py Team
License: MIT
Keywords: automation,bot,chat,messaging,uiautomation,wechat,windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.8
Requires-Dist: beautifulsoup4>=4.9
Requires-Dist: comtypes>=1.4
Requires-Dist: markdown>=3.3
Requires-Dist: pillow>=9.0
Requires-Dist: pywin32>=300
Description-Content-Type: text/markdown

# wx4py

Python 微信自动化工具 — 基于 UIAutomation 的 Windows Qt 版微信桌面客户端自动化库。

## 功能

| 模块 | 功能 |
|------|------|
| **消息发送** | 向联系人或群聊发送文本消息、文件，支持批量发送 |
| **消息监听** | 实时监听群聊消息，基于轮询模式的稳定监听器 |
| **自动回复** | 处理器管线（Handler/Action），支持多 handler 组合 |
| **消息转发** | 跨群转发文本/图片/卡片消息，含转发规则引擎 |
| **AI 集成** | 内置 OpenAI 兼容接口的 AI 客户端，支持流式回复 |
| **群组管理** | 获取群列表、搜索群聊、管理群成员 |
| **剪贴板** | Markdown → HTML → 剪贴板，支持富文本发送 |
| **窗口控制** | 自动连接微信窗口、注册表修复、托盘恢复 |

## 安装

```bash
pip install wxpy4
```

**系统要求**: Windows 10+，Qt 版微信客户端（WeChat.exe）。

## 快速开始

```python
from wx4py import WeChatClient

# 连接微信
wx = WeChatClient()
wx.connect()

# 发送消息给联系人
wx.chat_window.send_to("张三", "你好！")

# 发送文件到群聊
wx.chat_window.send_file_to("测试群", "report.xlsx", target_type="group")

# 批量发送
wx.chat_window.batch_send(["群1", "群2"], "通知：明天 9 点开会")

# 使用上下文管理器（自动 disconnect）
with WeChatClient() as wx:
    wx.chat_window.send_to("张三", "Hello from context manager")
```

## 群消息监听与自动回复

```python
from wx4py import WeChatClient, MessageHandler, ReplyAction

class EchoHandler(MessageHandler):
    def handle(self, msg):
        if "你好" in msg.text:
            return ReplyAction(f"你好 {msg.sender}！")
        return None

wx = WeChatClient()
wx.connect()
processor = wx.process_groups(["测试群"], EchoHandler())
# processor.run_forever()  # 阻塞运行
processor.stop()  # 或按需停止
```

## 消息转发

```python
from wx4py import WeChatClient, GroupForwardRule, ForwardRuleHandler

rule = GroupForwardRule(
    source_groups=["源群A"],
    target_groups=["目标群B"],
    text_only=True,
)
handler = ForwardRuleHandler(rule)

wx = WeChatClient()
wx.connect()
processor = wx.process_groups(["源群A"], handler)
```

## AI 自动回复

```python
from wx4py import WeChatClient, AIResponder, AIConfig

config = AIConfig(
    base_url="https://api.openai.com/v1",
    api_key="sk-xxx",
    model="gpt-4o",
)
responder = AIResponder(config, system_prompt="你是一个友好的助手")

wx = WeChatClient()
wx.connect()
processor = wx.process_groups(["客服群"], responder.to_handler())
```

## API 概览

### 核心类

| 类 | 说明 |
|----|------|
| `WeChatClient` | 主入口：连接微信、获取聊天窗口和群管理器 |
| `ChatWindow` | 聊天窗口：发送消息、文件、搜索 |
| `GroupManager` | 群管理器：获取群列表、搜索群 |
| `WeChatGroupListener` | 群消息监听器：轮询新消息 |
| `WeChatGroupProcessor` | 消息处理器：管理监听生命周期 |

### 消息处理

| 类 | 说明 |
|----|------|
| `MessageHandler` | 抽象处理器基类 |
| `CallbackHandler` | 回调式处理器（函数式风格） |
| `AsyncCallbackHandler` | 异步回调处理器 |
| `ReplyAction` | 回复动作 |
| `ForwardAction` | 转发动作 |

### 消息转发

| 类 | 说明 |
|----|------|
| `GroupForwardRule` | 转发规则定义 |
| `ForwardRuleHandler` | 转发规则处理器 |
| `ForwardTarget` | 转发目标 |
| `ForwardPayload` | 转发载荷 |

### AI 集成

| 类 | 说明 |
|----|------|
| `AIClient` | OpenAI 兼容 API 客户端 |
| `AIConfig` | AI 配置（base_url, api_key, model） |
| `AIResponder` | AI 自动回复器 |
| `MessageEvent` | 消息事件数据类 |

## 技术栈

- **UIAutomation**: Windows UI 自动化框架
- **COM (comtypes)**: Windows 组件对象模型交互
- **pywin32**: Windows API 调用
- **BeautifulSoup**: HTML 解析（聊天内容解析）
- **Pillow**: 图片处理
- **Markdown**: Markdown → HTML 转换

## 注意事项

1. **仅支持 Windows** — 依赖 UIAutomation、pywin32、comtypes 等 Windows 专用库
2. **仅支持 Qt 版微信** — 不支持 UWP 版（Microsoft Store 版本）
3. **微信需要保持前台运行** — 自动化通过 UI 操作实现，微信窗口不能被最小化到系统托盘
4. **首次使用需要管理员权限** — 用于注册 COM 组件
5. **Python 3.8+** — 使用了 `from __future__ import annotations`

## License

MIT
