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

一个基于 **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`）

---

## 目录结构

```text
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 上可通过下面命令安装：

```bash
sudo apt update
sudo apt install -y xdotool scrot
```

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

---

## 安装步骤

### 1. 克隆项目并进入目录

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

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

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

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

Windows PowerShell：

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

### 3. 安装 Python 依赖

```bash
pip install -r requirements.txt
```

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

---

## 配置说明

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

### 1. 创建 `.env`

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

```bash
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` 目录下执行：

```bash
python main.py
```

或显式调用：

```bash
python -m wechat_auto.main
```

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

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

例如：

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

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

```bash
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：

```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": "某某公司"
}
```

- **响应示例**：

```json
{
  "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`

返回：

```json
{
  "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`

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

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

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

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

简单返回服务状态：

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

---

## 执行流程与架构简要说明

1. **HTTP 请求进入**
   - `POST /api/publish` 接收 `ActivityModel`，调用 `TaskScheduler.publish_activity`

2. **任务调度**
   - 创建 `task_id` 与 `TaskStatus`，状态置为 `running`
   - 调用 `_execute_with_fallback`，执行双方案逻辑

3. **方案 1：pyautogui 执行**
   - 通过 `WindowManager` 使用 `xdotool` 查找微信窗口
   - 如果未找到微信窗口或无法获取几何信息，则抛出异常
   - 根据预设相对坐标依次执行：
     - 点击小程序入口 → 点击目标小程序 → 点击发布按钮
     - 填写标题与内容 → 点击提交按钮
   - 每一步执行前后会截图记录

4. **方案 2：Qwen AI 执行（备选）**
   - 若 pyautogui 连续多次失败，则切换到 Qwen 方案
   - 周期性地对当前屏幕截图并编码为 base64
   - 将截图和任务描述一并发送给 Qwen-VL 模型
   - 解析模型返回的 JSON（`action` + `params`），执行对应鼠标 / 键盘操作
   - 若模型返回 `action = "done"` 则认为任务完成，否则在最大步数内继续

5. **状态更新与返回**
   - 根据执行结果更新 `TaskStatus`（`success` 或 `failed`）
   - 将 `status`、`method`、`error` 等字段返回给调用方

---

## 常见问题与排查建议

- **微信窗口未找到**
  - 确认已登录 PC 版微信，且窗口标题与 `WECHAT_WINDOW_NAME` 配置一致
  - 终端手动执行：
    ```bash
    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）

---

## 免责声明

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