auto_GUI/wechat_auto/README.md at 26a0b3507d30c6159be297bc823af3e9ea086f16

quant-speed-AI/auto_GUI

Fork 0

Files

quant 26a0b3507d first commit

2026-03-04 17:22:39 +08:00

11 KiB

Raw Blame History

微信小程序活动发布自动化系统

一个基于 FastAPI + pyautogui + Qwen-VL 的微信小程序活动发布自动化工具，用于在桌面端微信中自动打开指定小程序、填写活动信息并提交发布。

系统整体采用「**规则脚本方案（pyautogui）优先，AI 视觉方案（Qwen）兜底」的双方案架构，配合任务调度与重试机制，提高自动化发布成功率。

功能概览

REST API 服务
- POST /api/publish：提交一个活动发布任务
- GET /api/task/{task_id}：查询单个任务状态
- GET /api/tasks：查看所有历史任务
- GET /api/health：健康检查
双方案自动化执行
- 方案 1：pyautogui 固定步骤
  - 通过 xdotool 查找并激活微信窗口
  - 使用相对坐标点击小程序入口 / 目标小程序 / 文本输入框 / 提交按钮
  - 自动输入活动标题和内容
  - 每个关键步骤都会截图留存
- 方案 2：Qwen AI 视觉控制（备选）
  - 截图当前桌面，通过 Qwen-VL 分析界面
  - 模型返回 JSON 控制指令（点击、输入、滚动、快捷键等）
  - 根据模型输出逐步操作，直到标记为 done 或超时
任务调度与重试
- 每个发布请求会生成独立 task_id
- 支持多次重试（指数退避），优先尝试 pyautogui
- 若 pyautogui 多次失败，会自动切换到 Qwen 方案
日志与截图
- 日志输出到控制台和文件（默认 /tmp/wechat_auto.log）
- 截图保存到指定目录（默认 /tmp/wechat_screenshots）

目录结构

wechat_auto/
  ├── main.py                      # FastAPI 应用入口（uvicorn 启动）
  ├── config.py                    # 配置加载（基于 pydantic-settings）
  ├── models/
  │   └── activity.py              # 活动模型 & 任务状态模型
  ├── api/
  │   └── trigger.py               # 对外 REST API 路由
  ├── core/
  │   ├── task_scheduler.py        # 任务调度与双方案执行
  │   ├── window_manager.py        # 微信窗口查找 / 激活 / 几何信息
  │   └── executor/
  │       ├── pyautogui_executor.py # 方案 1：规则脚本执行器
  │       └── qwen_ai_executor.py   # 方案 2：Qwen AI 执行器
  ├── utils/
  │   ├── logger.py                # 日志初始化
  │   └── retry.py                 # 同步 / 异步重试装饰器
  ├── .env.example                 # 环境变量示例文件（不含真实密钥）
  ├── .env                         # 实际环境配置（**请勿提交到仓库**）
  └── requirements.txt             # Python 依赖

环境要求

操作系统
- 建议：Linux 桌面环境（X11），当前实现依赖 xdotool、scrot 等工具
桌面环境
- 已安装并登录 PC 版微信（窗口标题默认是 WeChat，可通过配置修改）
系统工具依赖
- xdotool：窗口查找、激活、获取几何信息
- scrot：桌面截图（若无则退回 pyautogui.screenshot）

在 Debian/Ubuntu 上可通过下面命令安装：

sudo apt update
sudo apt install -y xdotool scrot

Python 环境
- Python 3.10+（建议使用虚拟环境）

安装步骤

1. 克隆项目并进入目录

cd /home/quant/data/dev/mini_auto
cd wechat_auto

（如果你是在其他目录，请根据实际路径调整。）

2. 创建并激活虚拟环境（推荐）

python -m venv .venv
source .venv/bin/activate

Windows PowerShell：

python -m venv .venv
.venv\Scripts\Activate.ps1

3. 安装 Python 依赖

pip install -r requirements.txt

如需使用 Qwen AI 方案，请确保能正常访问 DashScope 接口。

配置说明

项目通过 pydantic-settings 从 .env 文件和系统环境变量中加载配置，对应定义见 config.py 中 Settings 类。

1. 创建 `.env`

以 .env.example 为模板复制一份：

cp .env.example .env

然后根据实际情况修改 .env 中的配置项。

2. 关键配置项

FastAPI 服务
- HOST：服务监听地址（默认 0.0.0.0）
- PORT：服务端口（例如 8000 或 8001）
微信窗口相关
- WECHAT_WINDOW_NAME：微信窗口标题，默认 WeChat
  如果你的微信窗口标题不同（例如有多语言 / 带后缀），需要改成实际名称。
自动化行为
- CLICK_PAUSE：每次 pyautogui 操作之间的暂停秒数
- FAILSAFE：是否开启边角移动触发 FailSafe 保护
- ACTION_TIMEOUT：单步骤操作超时时间（秒）
- MAX_RETRIES：重试次数（用于调度和重试装饰器）
- RETRY_BASE_DELAY：重试基础延时（秒，配合指数退避）
日志与截图
- LOG_LEVEL：日志级别（如 INFO / DEBUG）
- LOG_FILE：日志文件路径（默认 /tmp/wechat_auto.log）
- SCREENSHOT_DIR：截图保存目录（默认 /tmp/wechat_screenshots）
Qwen API（如需启用 AI 方案）
- DASHSCOPE_API_KEY：DashScope 的 API Key
  - 在 .env.example 中为占位值，请在自己的 .env 中改成真实密钥
  - 安全提示：不要把包含真实密钥的 .env 提交到代码仓库

运行服务

确保：

已激活虚拟环境（如有）
.env 配置正确
微信 PC 客户端已启动并登录
DISPLAY 环境变量可用（例如 :0）

1. 直接运行入口脚本

在 wechat_auto 目录下执行：

python main.py

或显式调用：

python -m wechat_auto.main

启动成功后，日志中会输出类似信息：

服务地址: http://<HOST>:<PORT>
API 文档: http://<HOST>:<PORT>/docs

例如：

服务地址: http://0.0.0.0:8000
API文档: http://0.0.0.0:8000/docs

也可以手动启动 uvicorn（等价于入口里做的事情）：

uvicorn wechat_auto.main:app --host 0.0.0.0 --port 8000 --log-level info

API 使用说明

服务启动后，可以通过 swagger 文档直接调试：
http://<HOST>:<PORT>/docs

1. 发布活动：`POST /api/publish`

请求体模型：ActivityModel

示例 JSON：

{
  "title": "周末优惠活动",
  "content": "全场 8 折优惠，会员额外 9 折。",
  "start_time": "2026-03-10 10:00:00",
  "end_time": "2026-03-15 22:00:00",
  "images": ["/tmp/promotion.jpg"],
  "location": "线上",
  "organizer": "某某公司"
}

响应示例：

{
  "code": 200,
  "message": "任务已提交",
  "data": {
    "task_id": "xxx-uuid",
    "status": "success",
    "method": "pyautogui",
    "error": null
  }
}

说明：

method 字段指示实际使用的执行方案，可能为 pyautogui 或 qwen_ai

如果任务执行失败，status 会是 failed，error 中包含原因

2. 查询任务状态：`GET /api/task/{task_id}`

路径参数：

task_id：发布任务返回的 task_id

{
  "code": 200,
  "data": {
    "task_id": "xxx-uuid",
    "status": "success",
    "method": "pyautogui",
    "error": null,
    "created_at": "2026-03-04T12:00:00",
    "updated_at": "2026-03-04T12:00:15"
  }
}

3. 查询所有任务：`GET /api/tasks`

返回当前进程内维护的所有任务状态列表：

{
  "code": 200,
  "data": [
    {
      "task_id": "xxx-uuid",
      "status": "success",
      "method": "pyautogui",
      "error": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ]
}

注意：任务状态保存在内存中，重启进程后历史任务不会保留。

4. 健康检查：`GET /api/health`

简单返回服务状态：

{
  "status": "ok",
  "service": "wechat_auto"
}

执行流程与架构简要说明

HTTP 请求进入
- POST /api/publish 接收 ActivityModel，调用 TaskScheduler.publish_activity
任务调度
- 创建 task_id 与 TaskStatus，状态置为 running
- 调用 _execute_with_fallback，执行双方案逻辑
方案 1：pyautogui 执行
- 通过 WindowManager 使用 xdotool 查找微信窗口
- 如果未找到微信窗口或无法获取几何信息，则抛出异常
- 根据预设相对坐标依次执行：
  - 点击小程序入口 → 点击目标小程序 → 点击发布按钮
  - 填写标题与内容 → 点击提交按钮
- 每一步执行前后会截图记录
方案 2：Qwen AI 执行（备选）
- 若 pyautogui 连续多次失败，则切换到 Qwen 方案
- 周期性地对当前屏幕截图并编码为 base64
- 将截图和任务描述一并发送给 Qwen-VL 模型
- 解析模型返回的 JSON（action + params），执行对应鼠标 / 键盘操作
- 若模型返回 action = "done" 则认为任务完成，否则在最大步数内继续
状态更新与返回
- 根据执行结果更新 TaskStatus（success 或 failed）
- 将 status、method、error 等字段返回给调用方

常见问题与排查建议

微信窗口未找到
- 确认已登录 PC 版微信，且窗口标题与 WECHAT_WINDOW_NAME 配置一致
- 终端手动执行：
```
xdotool search --name WeChat
```
  确认能返回窗口 ID。
截图目录 / 日志目录权限问题
- 确保当前用户对 SCREENSHOT_DIR 和 LOG_FILE 目录有读写权限
- 如有需要，可在 .env 中改为当前用户有权限的路径
Qwen API 调用失败
- 确认 DASHSCOPE_API_KEY 已正确配置且未过期
- 检查服务器是否能访问 DashScope 接口
- 查看日志中 调用Qwen API失败 相关报错信息
坐标不匹配 / 点击错位
- 目前 pyautogui 方案使用固定相对坐标，适合「窗口大小 / DPI 固定」的场景
- 如果你使用不同分辨率或窗口布局，可能需要自行调整 _get_activity_steps 中的相对坐标
- 可以通过日志和截图对照，修正每一步操作的位置

开发与二次扩展建议

如需适配不同的小程序或表单结构：
- 可以扩展 PyAutoGUIExecutor._get_activity_steps，根据活动字段动态拼装步骤
- 或为不同小程序编写不同的步骤模板
如需增强 Qwen 方案：
- 可以在 QwenAIExecutor._build_prompt 中添加更详细的 UI 说明和约束
- 增加对更多 action 类型的支持（例如拖拽、选择框等）
如需持久化任务状态：
- 可以在 TaskScheduler 中将 tasks 从内存结构替换为数据库存储（如 SQLite / Redis）

免责声明

本项目涉及对桌面环境和微信客户端的自动化控制，请在遵守微信相关用户协议和所在地区法律法规的前提下使用。
如用于生产环境，请务必充分测试自动化脚本的稳定性与安全性，避免误操作造成损失。

11 KiB Raw Blame History Unescape Escape