# my_wx4py_dev

**Repository Path**: MythicalCreature/my_wx4py_dev

## Basic Information

- **Project Name**: my_wx4py_dev
- **Description**: wx4py v0.2.1 个人二次开发版，新增私聊监听、真人模拟打字防风控
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wx4py 个人二开定制版（v0.2.1-personal）

> 基于开源项目 [claw-codes/wx4py](https://github.com/claw-codes/wx4py) v0.2.1 独立二次开发
> 新增私聊监听、真人模拟打字、多层防风控策略，更适合长期自动化运行

---

## 📖 项目简介

wx4py 是一款 Windows 平台下的微信 4.x 自动化库，通过 UI 自动化模拟真实用户操作，实现群聊/私聊消息监听、自动回复、批量群发、聊天记录导出等功能。

本项目为**个人维护的二开版本**，在不破坏原版架构的前提下：

- ✅ 修复上游已知 Bug
- ✅ 新增**私聊消息监听**（与群聊监听完全对齐）
- ✅ 新增**智能模拟人类打字发送**（底层私有逻辑）
- ✅ 内置**多层防风控策略**（时段拦截、限流、随机延时、发送兜底）

⚠️ **说明**

- 本仓库不向原项目提交 PR
- 仅个人学习与自用维护，非商业用途
- 完整保留原版 MIT 协议版权声明

---

## 🆕 相较于原版的核心改进

| 功能             | 原版 wx4py | 本二开版                     |
| ---------------- | ---------- | ---------------------------- |
| 私聊监听         | ❌ 不支持   | ✅ `WeChatContactListener` |
| 发送模式         | 直接粘贴   | ✅ 短文本逐字输入 + 长文本粘贴 |
| 风控防护         | 基础延时   | ✅ 时段拦截 + 限流 + 随机停顿 + 发送兜底 |
| 消息限流         | 需自行实现 | ✅ 内置群/私聊独立限流器      |
| 多窗口并发       | 易焦点冲突 | ✅ 全局发送锁，队列化发送     |

---

## 🛠 环境要求

- **操作系统**：Windows 10 / 11
- **Python**：≥ 3.9
- **微信**：微信 4.x（推荐 4.1.7.59 / 4.1.8.29）
- **依赖库**：`pywin32`、`pyautogui`、`pyperclip`、`psutil`

⚠️ 运行时要求：

- 微信已登录
- 微信窗口处于**前台**（不可最小化）
- 屏幕分辨率、DPI 缩放保持默认（100%）

---

## 📥 安装方法

```bash
git clone https://gitee.com/MythicalCreature/my_wx4py_dev.git
cd my_wx4py_dev
pip install -e .
```

---

## 🚀 快速开始

### 1️⃣ 最简连接测试

```python
from wx4py import WeChatClient

with WeChatClient() as wx:
    wx.chat_window.send_to("文件传输助手", "wx4py 二开版连接成功！")
```

### 2️⃣ 群聊 + 私聊双监听（核心示例）

```python
from wx4py import (
    WeChatClient,
    WeChatGroupListener,
    WeChatContactListener
)

def group_msg_handler(event):
    """群聊消息回调"""
    content = event.message.content
    sender = event.message.sender
    print(f"[群消息] {sender}: {content}")

    # 仅 @ 当前登录用户时回复
    if event.is_at_me:
        return f"群聊自动回复：收到 {sender} 的消息"

def contact_msg_handler(event):
    """私聊消息回调"""
    content = event.message.content
    sender = event.message.sender
    print(f"[私聊] {sender}: {content}")

    if "你好" in content:
        return "你好呀，我是自动化助手~"

def start_listener(wx_client):
    # 启动群聊监听
    group_listener = WeChatGroupListener(
        client=wx_client,
        groups=["测试群"],
        on_message=group_msg_handler,
        ignore_client_sent=True,
        auto_reply=True,
        reply_on_at=True,
        outgoing_ttl=5.0
    )
    group_listener.start(block=False)

    # 启动私聊监听
    contact_listener = WeChatContactListener(
        client=wx_client,
        contacts=["好友A", "好友B"],
        on_message=contact_msg_handler,
        ignore_client_sent=True,
        auto_reply=True,
        outgoing_ttl=5.0
    )
    contact_listener.start(block=False)

    return group_listener, contact_listener

if __name__ == "__main__":
    with WeChatClient() as wx:
        gl, cl = start_listener(wx)
        input("监听已启动，按回车停止...\n")
        gl.stop()
        cl.stop()
```

✅ **业务层无需关心发送细节**

- 只在 `on_message` 中 `return 回复文本`
- 底层自动处理：窗口聚焦 → 延时 → 打字/粘贴 → 回车 → 风控校验

---

## 🤖 智能模拟人类打字（防风控核心）

底层自动根据文本长度切换发送模式（不可外部调用）：

```python
TEXT_LENGTH_THRESHOLD = 50  # 可修改源码调整阈值
```

| 文本长度  | 发送方式       | 行为特征                   |
| --------- | -------------- | -------------------------- |
| ≤ 50 字符 | 逐字输入       | 随机字符间隔 + 中途停顿     |
| ＞ 50 字符 | 剪贴板粘贴     | Ctrl+V + 粘贴后停顿        |

📌 相关私有方法（禁止外部调用）：

- `_send_in_subwindow`
- `_poll_session`

---

## 🛡 内置防风控策略

| 策略           | 规则                                        |
| -------------- | ------------------------------------------- |
| **时段拦截**   | 01:00 – 06:00 自动关闭自动回复              |
| **消息限流**   | 群聊：60s ≤ 6 条<br>私聊：60s ≤ 8 条       |
| **随机延时**   | 正态分布基础等待 + 低概率超长停顿           |
| **全局发送锁** | 多窗口排队发送，避免焦点抢占                |
| **发送兜底**   | 校验输入框残留，自动二次补发回车             |

---

## 📚 API 使用须知

### ✅ 稳定公开接口（推荐）

- `start()` / `stop()`
- `reply()` / `enqueue_reply()`

### ❌ 禁止直接调用的内部接口

- 单下划线 `_` 开头的方法
- 版本迭代可能无通知修改

### ✅ 推荐用法

```python
def on_message(event):
    # 业务逻辑
    return "需要回复的内容"
```

---

## 🐞 已修复问题

- 修复上游 Issue [#22](https://github.com/claw-codes/wx4py/issues/22)
- 修复消息回流导致的死循环回复
- 修复多窗口并发时的焦点丢失问题

---

## 📄 开源协议

- 基于原项目 **wx4py（MIT License）**
- 本二开版本沿用 MIT 协议
- 保留原版所有版权声明
- 非商业用途，仅个人维护

---

## 🙏 致谢

- 原项目：[claw-codes/wx4py](https://github.com/claw-codes/wx4py)
- UI 自动化：pywin32 / pyautogui
- 剪贴板管理：pyperclip

---

## ⚠️ 免责声明

本工具仅用于**学习与研究**，请勿用于刷屏、骚扰、违规营销等行为。
使用本工具产生的任何后果由使用者自行承担。