Wx4py

版本： 0.2.1
路径： E:/webchat-ai
状态： 已实测通过（2026-06-07）

基于 wx4py 的微信 PC 端自动化工具，无需 wxautox4 商业激活。支持 私聊 / 群聊发消息、AI 自动回复监听、语音 / 视频通话，可接入 WorkBuddy / Cursor MCP。

---

一、工具用途

场景	说明
自动回复	私聊或群聊有人发消息时，AI 自动回复（MiniMax 等）
批量发消息	脚本或 MCP 给指定联系人 / 群发送文本
远程控制微信	通过 MCP 工具在 Cursor / WorkBuddy 中调用
通话触发	私聊收到「视频通话」「语音通话」指令时自动拨打
语音转文字	监听时自动识别对方语音消息，转写后交给 AI 回复
图片识别	监听时自动识别对方图片中的文字与内容，交给 AI 回复
群管理辅助	监听指定群，按规则回复（不含 @ 强制，与私聊相同逻辑）

适用人群

• 需要用 AI 自动回微信私聊 / 群聊的开发者
• 已在 PC 上登录微信，希望用 Python 自动操作的用户
• 使用 WorkBuddy、Cursor MCP 的 Agent 工作流

不适用

• 手机微信（仅 PC 版）
• 未登录或频繁最小化到托盘且无法恢复的环境
• 需要 100% 实时（本工具为轮询，默认 15 秒间隔）

---

二、目录结构

E:/webchat-ai/
├── README.md                 ← 本文档（用途与使用说明）
├── start-all.bat             ← 一键开启监听（输入联系人）
├── stop-all.bat              ← 一键停止全部监听
├── docs/
│   ├── 操作手册.md             ← ★ 日常操作详细步骤（推荐阅读）
│   ├── INTEGRATION.md          ← WorkBuddy / OpenClaw 集成
│   └── 2026-06-07-功能整理.md  ← 开发细节与测试记录
├── wx4py_mcp/                ← 核心 Python 包
│   ├── open_chat.py          ← 打开会话（列表优先）
│   ├── last_message.py       ← 读最后一条 + 左/右气泡判断
│   ├── voice_message.py      ← 语音转文字
│   ├── image_message.py      ← 图片截图 + 视觉识别
│   ├── vision_client.py      ← MiniMax-M3 等多模态 API
│   ├── call_control.py       ← 语音/视频通话
│   ├── listen_control.py     ← 停止监听、通话指令
│   ├── state_store.py        ← 监听状态持久化
│   ├── conversation_memory.py ← 每用户对话记忆（上下文）
│   └── ...
├── scripts/                  ← 可执行脚本
│   ├── start_listen.py             ← 启动监听（支持 --interactive / --welcome）
│   ├── stop_listen.py              ← 停止监听
│   ├── listen-wechat.ps1           ← 单联系人私聊监听
│   ├── listen-wechat-group.ps1     ← 群聊监听
│   ├── stop-wechat.ps1             ← 停止私聊监听
│   ├── stop-wechat-group.ps1       ← 停止群聊监听
│   ├── poll_private_chat.py        ← 私聊轮询核心
│   ├── poll_group_chat.py          ← 群聊轮询核心
│   └── run_full_test.py            ← 全面自动化测试
├── config/
│   ├── listen-defaults.json        ← 默认监听对象（--all 时使用）
│   └── ai-config.json              ← AI 模型配置
├── mcp-config.example.json   ← MCP 配置示例
└── pyproject.toml

---

三、安装

环境要求

• Windows 10/11
• 微信 PC 版已登录
• Python 3.11（推荐）：C:/Users/Administrator/AppData/Local/Programs/Python/Python311/python.exe
• AI：WorkBuddy / mmx 配置（~/.mmx/config.json）或环境变量 WX4PY_AI_*

安装步骤

cd E:/webchat-ai
pip install -e .
pip install wx4py mcp Pillow

---

四、使用方法

日常操作请看详细步骤： docs/操作手册.md

4.0 一键开启 / 停止（最推荐）

操作	文件	说明
开启监听	双击 E:\webchat-ai\start-all.bat	输入联系人 → 自动发自我介绍 → 后台监听
停止监听	双击 E:\webchat-ai\stop-all.bat	停止全部私聊 + 群聊监听

开启示例：

1. 双击 start-all.bat
2. 输入 coco（或多个：Air,coco）
3. 回车，可选输入群名或跳过
4. 完成 — 任务栏会出现 WebChat-私聊-coco 最小化窗口

停止方式： 双击 stop-all.bat，或让对方发送 停止监听。

4.1 私聊 AI 监听（命令行）

监听指定联系人，对方发消息后 AI 自动回复。

# 监听 Air（默认 15 秒轮询，WorkBuddy AI）
powershell -File E:/webchat-ai/scripts/listen-wechat.ps1 Air

# 监听多人
powershell -File E:/webchat-ai/scripts/start_workbuddy_private_reply.ps1 -Contacts "Air,娟子"

# Echo 测试（不调用 AI，回复「收到：xxx」）
powershell -File E:/webchat-ai/scripts/listen-wechat.ps1 Air -Echo

停止： 让对方发送 停止监听 → 工具回复确认后进程退出。
再次监听需重新运行上述命令（启动时会自动检测最后一条对方消息，含语音/图片识别，补回复后再进入轮询）。

多媒体消息： 对方发 语音、图片 或 文件 时：

• 图片/文档：识别/解析后 直接整理成文字发回（不走闲聊 AI）
• 语音：转文字后走 AI 回复

4.2 群聊 AI 监听

# 监听测试群1
powershell -File E:/webchat-ai/scripts/listen-wechat-group.ps1 测试群1

# 多群
powershell -File E:/webchat-ai/scripts/start_workbuddy_group_reply.ps1 -Groups "测试群1,VIP群"

规则与私聊相同；无语音/视频通话。
停止方式：群里发 停止监听。

4.3 手动发消息（Python）

import sys
sys.path.insert(0, r"E:/webchat-ai")

from wx4py import WeChatClient
from wx4py_mcp.open_chat import send_message_smart

with WeChatClient() as wx:
    # 私聊
    send_message_smart(wx.chat_window, "Air", "你好", "contact")
    # 群聊
    send_message_smart(wx.chat_window, "测试群1", "大家好", "group")

4.4 MCP 接入（Cursor / WorkBuddy）

1. 复制 mcp-config.example.json 到客户端 MCP 配置
2. 修改 cwd 为 E:/webchat-ai
3. 启动：python -m wx4py_mcp

MCP 工具	功能
wechat_send	发送文本
wechat_voice_call	发起语音通话
wechat_video_call	发起视频通话
wechat_get_history	读取聊天记录
wechat_send_file	发送文件
wechat_status	检查连接

4.5 私聊通话（指令触发）

监听运行中，对方发送：

指令	效果
视频通话 / 视频对话	自动点击标题栏 → 视频通话
语音通话	自动点击标题栏 → 语音通话

也可单独测试：

python E:/webchat-ai/scripts/test_call.py Air --type video

---

五、模型 API 配置（供本工具及其他应用共用）

项目提供统一配置文件，填写一次即可被 WebChat AI 监听脚本及本机其他 Python 应用读取。

5.1 配置文件位置

E:/webchat-ai/config/
├── ai-config.example.json   ← 模板（可提交 git）
├── ai-config.json           ← 实际配置（含 api_key，勿提交）
└── README.md

5.2 首次配置

# 1. 从模板生成 ai-config.json
python E:/webchat-ai/scripts/ai-config.py --init

# 2. 编辑 config/ai-config.json，填写 api_key
notepad E:/webchat-ai/config/ai-config.json

# 3. 查看是否生效
python E:/webchat-ai/scripts/ai-config.py --status

5.3 配置示例

{
  "base_url": "https://api.minimaxi.com/v1",
  "model": "MiniMax-M2.5",
  "api_key": "你的API密钥",
  "api_format": "completions",
  "active_profile": "",
  "profiles": {
    "glm": {
      "base_url": "https://open.bigmodel.cn/api/paas/v4",
      "model": "glm-4-flash",
      "api_key": "智谱API密钥",
      "api_format": "completions"
    }
  }
}

• 顶层字段为默认配置
• profiles 可预设多套（MiniMax / 智谱 / DeepSeek 等）
• active_profile 填 "glm" 即切换到对应 profile

5.4 读取优先级

1. 环境变量 WX4PY_AI_*（最高）
2. config/ai-config.json（项目配置，推荐）
3. 本机 mmx / OpenClaw / WorkBuddy models.json

5.5 视觉模型（图片识别）

监听脚本读到对方 图片消息 时会：

1. 先截取聊天气泡 缩略图
2. 若分辨率过低或检测到 模糊 → 双击 打开预览并再次双击放大，截高清图
3. 调用 MiniMax-M3 提取文字并描述内容
4. 解析完成后自动关闭预览，再交给 AI 回复

config/ai-config.json 可选 vision 段（见 ai-config.example.json）。api_key 留空 时自动复用本机 MiniMax Key。

也可通过环境变量覆盖：

$env:WX4PY_VISION_API_KEY = "你的密钥"
$env:WX4PY_VISION_MODEL = "MiniMax-M3"
$env:WX4PY_VISION_BASE_URL = "https://api.minimaxi.com/v1"

5.6 其他应用如何调用

import sys
sys.path.insert(0, r"E:/webchat-ai")

from wx4py_mcp.ai_config import load_ai_config, AI_CONFIG_FILE, config_status

# 读取配置
cfg = load_ai_config()
if cfg:
    print(cfg.base_url, cfg.model, cfg.source)

# 指定 profile
cfg_glm = load_ai_config(profile="glm")

# 自定义路径
cfg2 = load_ai_config(config_path=r"D:/my-app/ai-config.json")

# 状态检查（密钥脱敏）
print(config_status())

环境变量 WEBCHAT_AI_CONFIG 可指向任意 JSON 路径，便于多项目共用同一份配置。

---

六、工作原理

6.1 打开会话（不反复开关微信）

当前聊天已是目标？ → 是 → 直接操作
        ↓ 否
左侧会话列表有目标？ → 是 → 点击切换
        ↓ 否
Ctrl+F 搜索一次

6.2 监听回复

每 15 秒轮询
    ↓
打开目标会话，读最后一条消息
    ↓
左侧灰色（对方）？ → 否 → 跳过
    ↓ 是
已回复过 / 是自己发的？ → 是 → 跳过
    ↓ 否
AI 生成回复（带最近对话上下文）→ 发送 → 记录状态 + 写入对话记忆

6.3 防循环

• __last_replied__：同一条消息只回一次
• __outgoing__：记录自己发出的内容，避免误当成对方消息

6.4 对话记忆（上下文）

每个联系人 / 群 单独一个本地 JSON 文件，默认保留最近 10 条消息（用户 + AI 回复合计，约 5 轮对话），供 AI 回复时带入上下文。

路径	说明
~/.wx4py-mcp/memory/private/Air.json	私聊 Air 的对话记忆
~/.wx4py-mcp/memory/group/测试群1.json	群聊记忆

• 自动写入：每次成功回复后追加「用户消息 + AI 回复」
• 自动读取：下次回复时把历史 messages 传给模型
• 关闭记忆：WX4PY_MEMORY_SIZE=0
• 调整条数：WX4PY_MEMORY_SIZE=20（默认 10）

---

七、状态与变量

状态文件（自动生成）

文件	说明
~/.wx4py-mcp/private_seen.json	私聊监听状态
~/.wx4py-mcp/group_seen.json	群聊监听状态
~/.wx4py-mcp/wechat.ui.lock	UI 操作互斥锁

环境变量（可选）

变量	说明
WX4PY_AI_BASE_URL	AI API 地址
WX4PY_AI_API_KEY	API Key
WX4PY_AI_MODEL	模型名
WX4PY_STATE_DIR	状态目录
WX4PY_MEMORY_SIZE	每用户对话记忆条数（默认 10，0=关闭）

默认使用本机 WorkBuddy / mmx 的 MiniMax 配置，一般无需设置。

---

八、测试

# 全面自动化测试（约 2 分钟）
python E:/webchat-ai/scripts/run_full_test.py

# 会话切换压力测试
python E:/webchat-ai/scripts/stress_test_session.py --case all

结果输出：~/.wx4py-mcp/full-test-results.json

---

九、注意事项

1. 名称必须完全一致：联系人备注、群名大小写敏感（Air ≠ air）
2. 微信保持可见：最小化可能导致识别变慢，但不应反复开关窗口
3. 不要同时跑两个监听进程（私聊 + 群聊也建议分开测）
4. 停止监听后需重新启动脚本才能继续轮询
5. 本工具基于 UI 自动化，微信大版本更新后可能需要适配

---

十、常见问题

Q：监听没反应？
A：检查是否已因「停止监听」退出；重新运行 listen-wechat.ps1。确认最后一条是对方发的（左侧灰色）。

Q：一直走搜索、不开列表？
A：确保微信主窗口可见，目标在左侧列表中；见 open_chat.py 日志 [session]。

Q：AI 回复失败？
A：检查 ~/.mmx/config.json 或 WX4PY_AI_* 环境变量。

Q：群聊和私聊区别？
A：群聊无通话功能，其余规则相同。

---

十一、更新记录

版本	日期	说明
0.2.1	2026-06-09	一键启停 bat、输入联系人、启动自我介绍、图片/文档直回、对话记忆
0.2.1	2026-06-07	新增 config/ai-config.json 统一模型 API 配置
0.1.0	2026-06-07	私聊轮询、MCP 基础工具

---

十二、相关路径

• E 盘记忆库： E:/agent-hub/memory/projects/wx4py-mcp.md
• 原开发目录： E:/SKILLS/wx4py-mcp/（与本文档同步）

如有问题，先看日志中的 [session]、[Air]、[测试群1] 前缀行。