wx4-skill

name	wx4-skill
description	微信自动化操作 skill，用于帮助用户快速完成微信消息群发、文件发送、群管理、聊天记录获取、多群监听、AI 自动回复等自动化任务。当用户需要批量发送微信消息、管理微信群、获取聊天记录、监听群消息、或接入 AI 群聊机器人时使用此 skill。

微信自动化操作 Skill

⚠️ 使用前必读：安装检查

在执行任何操作前，必须先确认 wx4py 库已安装。

步骤1：检查是否已安装

try:
    from wx4py import WeChatClient
    print("✅ wx4py 已安装")
except ImportError:
    print("❌ 未安装 wx4py")

步骤2：如果未安装，执行安装

# 方法1：从 PyPI 安装（推荐）
pip install wx4py

# 方法2：从 GitHub 安装（最新版）
pip install git+https://github.com/claw-codes/wx4py.git

# 方法3：从本地安装
cd /path/to/wx4py
pip install .

步骤3：验证安装成功

from wx4py import WeChatClient

# 测试导入
print("✅ 安装成功！")

# 检查版本（可选）
import wx4py
print(f"版本: {wx4py.__version__}")

重要提示：

• 如果用户提示 ModuleNotFoundError: No module named 'wx4py'，说明未安装
• 必须先安装库再执行后续操作
• 安装只需要一次，后续无需重复

---

概述

本 skill 基于 wx4py 库，帮助用户通过 Python 代码自动化控制 Windows 微信客户端，完成重复性的消息发送、群管理等任务。

适用场景：

• 批量群发通知到多个群或联系人
• 定时发送文件、图片、消息
• 获取和分析聊天记录
• 管理群公告、群昵称、免打扰等设置
• 监听多个群聊消息，并在被 @ 时自动回复
• 接入 OpenAI 兼容接口或自定义 AI 回调，构建群聊机器人
• 自动化日常微信操作

前置要求：

• Windows 系统
• 微信 PC 客户端已安装并登录（Qt 版本，已测试 4.1.7.59、4.1.8.29）
• Python >=3.9
• 终端、编辑器、脚本文件统一使用 UTF-8 编码环境，避免中文消息、群名、文件名出现乱码

编码环境建议：

• Python 源码文件保存为 UTF-8
• PowerShell / 终端优先使用 UTF-8 编码
• 读写文本、JSON、Markdown 文件时显式指定 encoding='utf-8'
• 如果要输出中文日志或生成中文文件内容，优先验证终端和编辑器都已切换到 UTF-8

核心功能

1. 消息发送

发送单条消息到联系人或群

from wx4py import WeChatClient

wx = WeChatClient()
wx.connect()

# 发送给联系人
wx.chat_window.send_to("文件传输助手", "测试消息")

# 发送到群
wx.chat_window.send_to("工作群", "下午3点开会", target_type='group')

wx.disconnect()

批量群发消息

wx = WeChatClient()
wx.connect()

# 批量发送到多个群
groups = ["群1", "群2", "群3"]
message = "重要通知：明天放假"
wx.chat_window.batch_send(groups, message)

# 批量发送到多个联系人
contacts = ["张三", "李四", "王五"]
wx.chat_window.batch_send(contacts, "周末聚餐通知", target_type='contact')

wx.disconnect()

2. 文件发送

发送单个文件

wx = WeChatClient()
wx.connect()

# 发送文件给联系人
wx.chat_window.send_file_to("文件传输助手", r"C:\reports\weekly.pdf")

# 发送文件到群
wx.chat_window.send_file_to("工作群", r"C:\data.xlsx", target_type='group', message='可以携带消息')

wx.disconnect()

批量发送多个文件

wx = WeChatClient()
wx.connect()

# 发送多个文件
files = [
    r"C:\images\photo1.png",
    r"C:\images\photo2.png",
    r"C:\documents\report.pdf"
]
wx.chat_window.send_file_to("文件传输助手", files)

wx.disconnect()

3. 聊天记录获取

获取指定时间范围的聊天记录

wx = WeChatClient()
wx.connect()

# 获取今天的聊天记录
messages = wx.chat_window.get_chat_history(
    target="工作群",
    target_type='group',
    since='today'  # 'today' | 'yesterday' | 'week' | 'all'
)

# 处理消息
for msg in messages:
    print(f"[{msg['time']}] {msg['content']}")

wx.disconnect()

返回格式：

{
    "type": "text",      # text / link / system
    "content": "消息内容",
    "time": "今天 15:30"
}

4. 群管理

获取群成员列表

wx = WeChatClient()
wx.connect()

members = wx.group_manager.get_group_members("工作群")
print(f"群成员数量：{len(members)}")
for member in members:
    print(member)

wx.disconnect()

修改群昵称

wx = WeChatClient()
wx.connect()

wx.group_manager.set_group_nickname("工作群", "张三的小号")

wx.disconnect()

获取群昵称

wx = WeChatClient()
wx.connect()

nickname = wx.group_manager.get_group_nickname("工作群")
print(f"我在本群的昵称：{nickname}")

wx.disconnect()

设置消息免打扰

wx = WeChatClient()
wx.connect()

# 开启免打扰
wx.group_manager.set_do_not_disturb("工作群", enable=True)

# 关闭免打扰
wx.group_manager.set_do_not_disturb("工作群", enable=False)

wx.disconnect()

置顶/取消置顶聊天

wx = WeChatClient()
wx.connect()

# 置顶聊天
wx.group_manager.set_pin_chat("工作群", enable=True)

# 取消置顶
wx.group_manager.set_pin_chat("工作群", enable=False)

wx.disconnect()

修改群公告（如果修改不成功，很大概率是因为不是管理员的原因）

wx = WeChatClient()
wx.connect()

# 优先使用这种方式，从 Markdown 文件设置公告（支持表格、列表等格式）
wx.group_manager.set_announcement_from_markdown("工作群", "markdown文件路径")

# 直接设置文本公告
wx.group_manager.modify_announcement_simple("工作群", "本群禁止发广告，违者移出")

wx.disconnect()

5. 群聊监听与 AI 自动回复

监听多个群聊消息

from wx4py import CallbackHandler, MessageEvent, WeChatClient

groups = ["工作群1", "工作群2", "工作群3"]

def on_message(event: MessageEvent):
    print(f"[{event.group}] {event.content}")
    return ""  # 只监听，不自动回复

with WeChatClient(auto_connect=True) as wx:
    wx.process_groups(
        groups,
        [CallbackHandler(on_message)],
        block=True,
    )

只在被 @ 时自动回复

from wx4py import AsyncCallbackHandler, MessageEvent, WeChatClient

groups = ["工作群1", "工作群2"]

def reply(event: MessageEvent):
    if not event.is_at_me:
        return ""
    return f"收到：{event.content}"

with WeChatClient(auto_connect=True) as wx:
    wx.process_groups(
        groups,
        [AsyncCallbackHandler(reply, auto_reply=True, reply_on_at=True)],
        block=True,
    )

监听指定群消息并转发给指定联系人或群

from wx4py import ForwardRuleHandler, GroupForwardRule, WeChatClient

rules = [
    GroupForwardRule(
        source_group="告警群",
        targets=["值班同学"],
        target_type="contact",
        prefix_template="[告警群] ",
    ),
    GroupForwardRule(
        source_group="项目群A",
        targets=["项目群B"],
        target_type="group",
        prefix_template="[项目群A] ",
    ),
]

with WeChatClient(auto_connect=True) as wx:
    wx.process_groups(
        ["告警群", "项目群A"],
        [ForwardRuleHandler(rules)],
        block=True,
    )

适用场景：

• 监听告警群，把消息转发给值班联系人
• 监听业务群，把消息同步到另一个群
• 针对不同来源群，配置不同的联系人或群作为目标

使用内置 AIClient 接入 OpenAI 兼容接口

import os
from wx4py import AIClient, AIConfig, AIResponder, AsyncCallbackHandler, WeChatClient

ai = AIClient(
    AIConfig(
        base_url="https://api.example.com/v1",
        api_format="completions",
        model="your-model-id",
        api_key=os.environ["AI_API_KEY"],
        enable_thinking=False,
    )
)

with WeChatClient(auto_connect=True) as wx:
    wx.process_groups(
        ["工作群"],
        [
            AsyncCallbackHandler(
                AIResponder(ai, context_size=8, reply_on_at=True),
                auto_reply=True,
            )
        ],
        block=True,
    )

使用自定义 AI 或业务系统

from wx4py import AsyncCallbackHandler, MessageEvent, WeChatClient

def custom_reply(event: MessageEvent):
    if not event.is_at_me:
        return ""

    # 这里可以调用公司内部接口、其他 AI SDK 或业务系统。
    return f"自定义回复：{event.content}"

with WeChatClient(auto_connect=True) as wx:
    wx.process_groups(
        ["工作群"],
        [AsyncCallbackHandler(custom_reply, auto_reply=True, reply_on_at=True)],
        block=True,
    )

实现说明：

• 每个群优先打开独立聊天窗口，适合同时监听多个群。
• 自动回复通过发送队列串行执行，避免多个群同时回复时抢占窗口。
• 本库发送的消息会自动记录，避免机器人监听到自己的回复后再次触发。

使用模式

推荐：使用上下文管理器

from wx4py import WeChatClient

with WeChatClient() as wx:
    # 自动连接和断开
    wx.chat_window.send_to("文件传输助手", "Hello!")

手动连接管理

wx = WeChatClient()
wx.connect()

try:
    # 执行操作
    wx.chat_window.send_to("文件传输助手", "Hello!")
finally:
    wx.disconnect()

实用脚本示例

示例1：定时群发通知

from wx4py import WeChatClient
import schedule
import time

def send_daily_notification():
    with WeChatClient() as wx:
        groups = ["工作群1", "工作群2", "工作群3"]
        message = "早安！今日工作提醒..."
        wx.chat_window.batch_send(groups, message, target_type='group')
        print("通知已发送")

# 每天早上9点发送
schedule.every().day.at("09:00").do(send_daily_notification)

while True:
    schedule.run_pending()
    time.sleep(60)

示例2：收集昨天的聊天记录并保存

from wx4py import WeChatClient
import json
from datetime import datetime

with WeChatClient() as wx:
    # 获取昨天的聊天记录
    messages = wx.chat_window.get_chat_history(
        target="工作群",
        target_type='group',
        since='yesterday'
    )

    # 保存到文件
    filename = f"chat_history_{datetime.now().strftime('%Y%m%d')}.json"
    with open(filename, 'w', encoding='utf-8') as f:
        json.dump(messages, f, ensure_ascii=False, indent=2)

    print(f"已保存 {len(messages)} 条消息到 {filename}")

示例3：批量发送文件到多个群

from wx4py import WeChatClient
import os

# 准备要发送的文件
files_dir = r"C:\weekly_reports"
files = [os.path.join(files_dir, f) for f in os.listdir(files_dir) if f.endswith('.pdf')]

groups = ["管理群", "开发群", "产品群"]

with WeChatClient() as wx:
    for group in groups:
        print(f"正在向 {group} 发送文件...")
        wx.chat_window.send_file_to(group, files, target_type='group')
        print(f"已完成 {group}")

注意事项

操作限制

• 仅支持 Windows 系统
• 需要微信客户端已登录
• 操作期间不要手动操作微信窗口
• 受微信 UIA 限制，聊天记录无法获取发送者姓名

最佳实践

• 使用上下文管理器确保连接正确释放
• 批量操作时添加适当延迟，避免操作过快
• 重要操作前先测试小范围验证
• 群聊机器人优先使用 reply_on_at=True，避免普通群消息触发自动回复
• AI 回调耗时会影响监听延迟，大规模群监听时建议使用响应更快的模型或业务接口
• 捕获异常并记录日志
• 需要系统查看方法说明时，优先参考 docs/guide/API_GUIDE.md

异常处理

from wx4py import WeChatClient, WeChatNotFoundError, ControlNotFoundError

try:
    with WeChatClient() as wx:
        wx.chat_window.send_to("目标", "消息")
except WeChatNotFoundError:
    print("错误：未找到微信窗口，请确保微信已打开并登录")
except ControlNotFoundError as e:
    print(f"错误：未找到控件 - {e}")
except Exception as e:
    print(f"未知错误：{e}")

工作流程指导

当用户请求微信自动化任务时，按以下步骤操作：

1. 理解需求

   • 确认目标（联系人/群组）
   • 确认操作类型（发消息/发文件/获取记录/管理设置）
   • 确认是否批量操作

2. 编写脚本

   • 使用上述示例作为模板
   • 添加必要的错误处理
   • 考虑操作延迟和频率限制

3. 验证和测试

   • 先用小范围测试（如"文件传输助手"）
   • 确认脚本正确运行后再扩大范围

4. 执行和反馈

   • 运行脚本并观察结果
   • 提供清晰的执行反馈
   • 必要时保存日志

快速参考

操作	方法	示例
发消息给联系人	chat_window.send_to(target, message)	wx.chat_window.send_to("张三", "Hi")
发消息到群	chat_window.send_to(target, message, target_type='group')	wx.chat_window.send_to("工作群", "Hi", target_type='group')
批量群发	chat_window.batch_send(targets, message, target_type)	wx.chat_window.batch_send(["群1", "群2"], "Hi", target_type='group')
发送文件	chat_window.send_file_to(target, file_path)	wx.chat_window.send_file_to("张三", r"C:\file.pdf")
获取聊天记录	chat_window.get_chat_history(target, target_type, since)	wx.chat_window.get_chat_history("工作群", 'group', 'today')
获取群成员	group_manager.get_group_members(group_name)	wx.group_manager.get_group_members("工作群")
获取群昵称	group_manager.get_group_nickname(group_name)	wx.group_manager.get_group_nickname("工作群")
设置群昵称	group_manager.set_group_nickname(group_name, nickname)	wx.group_manager.set_group_nickname("工作群", "小张")
消息免打扰	group_manager.set_do_not_disturb(group_name, enable)	wx.group_manager.set_do_not_disturb("工作群", True)
置顶聊天	group_manager.set_pin_chat(group_name, enable)	wx.group_manager.set_pin_chat("工作群", True)
修改群公告	group_manager.modify_announcement_simple(group_name, content)	wx.group_manager.modify_announcement_simple("工作群", "新公告")
监听/处理多个群聊	process_groups(groups, handlers, block=True)	wx.process_groups(["群1"], [handler], block=True)
监听群消息并转发	process_groups(groups, [ForwardRuleHandler(rules)], block=True)

常见问题

Q: 脚本运行时提示找不到微信窗口？ A: 确保微信已打开并登录，窗口不要最小化。

Q: 批量发送时部分失败？ A: 检查目标名称是否正确，建议在每次发送间添加延迟。

Q: 中文消息、群名或导出文件出现乱码？ A: 先确认终端、编辑器、Python 源文件和读写文件逻辑都使用 UTF-8；写文件时显式传入 encoding='utf-8'，避免依赖系统默认编码。

Q: 可以获取图片和语音消息吗？ A: 目前主要支持文本消息，图片和语音的完整获取受限于微信 UIA。

Q: AI 自动回复会回复所有群消息吗？ A: 不会，推荐传入 reply_on_at=True。普通消息只监听，只有群消息 @ 当前群昵称时才会触发回复。

Q: 可以不用内置 AIClient，接入自己的 AI 服务吗？ A: 可以。process_groups() 接收任意 handler；最简单的方式是使用 AsyncCallbackHandler 包装你自己的回调，回调返回字符串即可入队发送。

Q: 多个群同时触发回复会抢占窗口吗？ A: 自动回复会进入发送队列串行执行，避免多个独立聊天窗口同时发送导致焦点抢占。

Q: 脚本可以在后台运行吗？ A: 微信窗口需要在前台才能进行 UI 自动化操作。