version: "1.0.1" name: pyweixin-rpa description: >- Automates Windows PC WeChat via pywinauto UI automation (messages, files, Moments, contacts). Use when the user mentions 微信, WeChat, pyweixin, 发消息, 朋友圈, or Windows WeChat RPA.

pyweixin RPA

Overview

Python 微信 RPA 工具，基于 pywinauto 实现，纯 UI 自动化，无 Hook 注入。

核心原则：所有方法均为静态方法，无需实例化类。

仅支持 Windows 平台。如果运行环境不是 Windows，则应输出：

This tool requires Windows. Aborting.

Resources

• scripts/requirements.txt — 依赖清单
• scripts/check_requirements.py — 依赖检查脚本
• scripts/check_visibility.py — 微信 UI 可见性检查脚本
• scripts/check_running_state.py — 微信运行状态检查脚本
• references/Weixin4.0.md — 微信 4.0+ UI 树可见性说明
• scripts/pyweixin/ — 微信 4.0+ 自动化源码
• references/api_reference.md — 方法签名速查（推荐优先阅读）

Check Requirements

首次调用该 Skill 时需要在仓库根目录（即 skills/pyweixin-rpa/）使用系统 Python 运行以下命令。注意：只有在当前系统中首次运行该 Skill 时才需要执行此步骤，后续不再需要。

python scripts/check_requirements.py

• 输出结果：JSON 对象 {"missing_package": list}
• 如果脚本退出码非零、输出无法解析为 JSON、或缺少 missing_package 键，则视为缺少依赖。
• 如果输出可解析且返回的 JSON 字符串中 missing_package 键对应的列表为空，则视为不缺少相关依赖。

处理：

1. 如果缺少相关依赖，输出：缺乏相关依赖，正在安装相关依赖，并在仓库根目录使用系统 Python 运行：

pip install -r scripts/requirements.txt

1. 如果不缺少相关依赖，可以继续进行其他操作。

Check Visibility

该 Skill 每次被调用时都需要经过这一阶段。在仓库根目录使用系统 Python 运行：

python scripts/check_visibility.py

• 输出结果：JSON 对象 {"visibility": bool}
• 如果脚本退出码非零、输出无法解析为 JSON、或缺少 visibility 键，则 visibility 视为 False。

1. 如果 visibility == False，继续运行：

python scripts/check_running_state.py

• 输出结果：JSON 对象 {"is_running": bool}
• 如果 is_running == false，输出：微信未启动，请自行启动并登录后再尝试进行相关自动化操作！
• 如果 is_running == true，告知用户微信 UI 树不可见，无法执行自动化操作。在控制台输出一份中文摘要：
• 3-5 条要点
• 最多 150 字
• 来源：references/Weixin4.0.md

1. 如果 visibility == True，可以继续进行其他操作。

Import List

# 所有可用类的具体导入方式（需要先 sys.path.insert）
from pyweixin import AutoReply, Collections, Call, Contacts, Files, FriendSettings, Messages, Moments, Monitor, Settings
from pyweixin import Tools, Navigator
from pyweixin import SystemSettings
from pyweixin.Config import GlobalConfig

Scripting Guidelines

原则一：导入前务必 sys.path.insert(0, 'scripts')

scripts/pyweixin/ 是本工具的本地源码目录。如果你的 Python 环境中安装了同名的第三方 pyweixin pip 包，from pyweixin import Messages 会优先加载 pip 包而非本地模块，导致报错（如 AttributeError: type object 'Messages' has no attribute 'dump_chat_history'）。

import sys
sys.path.insert(0, 'scripts')
from pyweixin import Messages, Files  # 现在会加载本地模块

注意： scripts/check_visibility.py 等检查脚本内部已处理路径，直接运行不受影响。仅在编写自定义脚本时需要关注。

原则二：dump_chat_history 返回 list[dict]，不要解包为两个变量

# ❌ 错误：返回值是 list[dict]，不是 tuple
messages, times = Messages.dump_chat_history(friend='xxx', number=5)
# ✅ 正确：直接拿 dict 列表
result = Messages.dump_chat_history(friend='xxx', number=5, close_weixin=False)
for msg in result:
    print(msg['消息发送人'], msg['消息内容'])

原则三：返回值以 API Reference 为准，无需探针

references/api_reference.md 中每个方法都已标注准确的返回类型和结构，这些标注直接从源码提取。

# ✅ 正确：查文档比跑探针更可靠
# api_reference.md 中：
# Messages.dump_chat_history(...) -> list[dict]
# 每个 dict 键: '消息发送人', '消息内容', '消息类型', '消息发送时间'
result = Messages.dump_chat_history(friend='xxx', number=5, close_weixin=False)
for msg in result:
    print(msg.get('消息内容'))  # 直接使用，无需 type() 探测

例外： 如果你修改了源码或使用了源码中未覆盖的方法，才需要探针验证。日常使用以文档为准。

原则四：已拉取的数据不要重复拉取

如果已经调用了一次 dump_chat_history（或其他拉取方法）拿到了数据，后续的处理步骤（如生成报告、分析、转发）应该接收现有数据，而不是再调一次拉取方法。

# ❌ 错误：拉取 + 报告各拉一次 = 两次 UI 自动化操作
result = Messages.dump_chat_history(friend='xxx', number=200, close_weixin=False)
# ... 然后又在一个新脚本里调了一次 dump_chat_history ...
# ✅ 正确：只拉一次，把结果传给下游
result = Messages.dump_chat_history(friend='xxx', number=200, close_weixin=False)
report = build_report(result)    # 复用数据，不再调用 dump_chat_history
send(report)

如果确实需要自包含的独立脚本（比如一次性工具），可以在脚本内部加一个已拉取检查，或者用全局配置控制只拉一次。

经验： 每条 dump_chat_history 调用 = 一次聊天窗口滚动操作。跑两次就是两次滚动操作，纯属浪费。拿到 list[dict] 后你想怎么处理都行，不需要重新拉。

💡 只读消息用 `pull_messages`，别用 `dump_chat_history`： pull_messages 只拉取已有聊天区域内的消息记录，不滚动窗口，比 dump_chat_history 轻量得多。验证、检查最新消息、确认发送结果，都应该用 pull_messages。需要翻历史记录时（消息数量超过当前可视区域），才用 dump_chat_history。

Send Messages

在发送消息时，注意消息中是否有文件（如图片、视频等）：

• 如果发送的内容只是文本字符串，使用 Messages 内的 send 操作即可。
• 如果消息中包含文件，使用 Files 内的 send 操作，且 with_messages 参数设置为 True。

Handle Exception

在自动化过程中，scripts/pyweixin 内代码可能引发的异常分为以下类别。对于所有异常，不要自动重试，直接结束相关自动化任务，是否重试由用户本人决定。

异常分类与处理

关于 MousePos 坐标异常

如果异常的源代码中涉及到了 MousePos 类，导致本次异常的原因大概率是点击坐标有偏差，未弹出期望窗口或控件。出现该异常后可以尝试在 `scripts/pyweixin/Uielements.py` 的 `MousePos` 类中直接修改点击坐标。

涉及 MousePos 的方法：

Scheduled Tasks：用 OpenClaw cron 触发脚本，不要在代码里写定时逻辑

如果需要「在某个时间点自动给好友发消息」之类的定时操作，不要在 Python 脚本里写 time.sleep、schedule 库或任何自身定时逻辑。而是：

1. 写一个纯干活脚本（只做一件事，不含时间判断）。
2. 用 OpenClaw 的 cron 设定触发时间，通过 systemEvent 在主 session 执行。

正确做法

Step 1：写脚本（只干活）

import sys
sys.path.insert(0, 'scripts')
from pyweixin import Messages
Messages.send_messages_to_friend(
    friend='文件传输助手',
    messages=['你好，这是定时消息'],
    close_weixin=False
)

Step 2：设 cron 任务（用 OpenClaw 的定时能力触发）

# 在 OpenClaw 中创建定时任务
# 09:51 时触发主 session 执行脚本

对应的 cron 参数：

❌ 不要这样做

# 错误：在脚本里自己控制时间
import time
time.sleep(120)  # ❌ 脚本挂起，阻塞
Messages.send_messages_to_friend(...)

# 错误：用 external scheduler 轮询
import schedule  # ❌ 引入额外依赖
schedule.every().day.at("09:51").do(send_msg)

为什么？

• OpenClaw cron 本身就是一个成熟的调度器，支持 at（一次性）、every（间隔）、cron（cron 表达式）三种模式。
• 脚本只负责干活，时间控制完全解耦，脚本可以被随时手动执行、调试。
• sessionTarget="main" 让主 session 收到定时事件后直接 exec 脚本，不需要 isolated session 去猜上下文。

Execution

Check Visibility 阶段没有任何问题后，便可以在 Windows 环境下运行相关自动化操作。通过阅读 references/api_reference.md 来获取各方法的完整签名、参数说明来生成对应的 Python 脚本。