wxzdh WeChat Auto Customer Service MVP

What This Is

wxzdh is a local Windows MVP for automating one WeChat customer-service conversation. It runs a FastAPI control service, keeps a target WeChat chat visible, watches the chat through window-bound screenshots, routes new work through an LLM decision step, optionally calls a local image-editing API, and sends the final reply back through the WeChat desktop UI.

This project is an unofficial local automation tool. It is not affiliated with, endorsed by, or sponsored by WeChat, Tencent, OpenAI, Yunwu, or any image API provider.

What It Does

• Starts a FastAPI service on 127.0.0.1:8787.
• Finds and controls the Windows WeChat desktop window.
• Keeps one configured target chat open.
• Captures screenshots from the WeChat window handle instead of the foreground screen.
• Detects chat changes through a simple hash-based watcher.
• Saves original images from WeChat through GUI Save As.
• Builds brain_input.json from the latest chat context and available images.
• Sends the task to an OpenAI-compatible LLM provider.
• Calls a local GPT2 image API at http://127.0.0.1:7865/img2img when image editing is required.
• Saves processed images and sends reply text/images back to WeChat.

Final Result

When running, the project exposes local control endpoints and supervises one chat loop:

WeChat desktop chat
  -> wxzdh screenshot and change watcher
  -> task state in local SQLite/runtime files
  -> LLM decision
  -> optional local image API
  -> WeChat desktop reply

The MVP is intended for supervised local testing. It is not a production multi-customer queue.

Who It Is For

This repository is for developers who want to study or extend a local Windows GUI automation pattern around WeChat, FastAPI, simple task state, and an external LLM/image tool. It assumes the operator controls the Windows desktop session and can observe failures.

Prerequisites

Direct Dependencies

• Windows desktop session with WeChat installed and already logged in.
• Python 3.11+.
• FastAPI.
• Uvicorn.
• httpx.
• Pillow.
• pyautogui.
• pyperclip.
• pywin32.
• psutil.

Install Python dependencies with:

python -m pip install -r requirements.txt

Configure the required local settings:

$env:WXZDH_TARGET_CHAT = "your-target-chat"
$env:WXZDH_LLM_API_KEY = "your-api-key"

Optional settings:

$env:WXZDH_ROOT = "C:\path\to\wxzdh"
$env:WXZDH_LLM_BASE_URL = "https://yunwu.ai/v1"
$env:WXZDH_LLM_MODEL = "gpt-5.5"
$env:WXZDH_GPT2_IMAGE_BASE_URL = "http://127.0.0.1:7865"
$env:WXZDH_GPT2_IMAGE_ACCOUNT_ID = "gpt1"
$env:WXZDH_GPT2_START_BAT = "C:\path\to\start-gpt2.bat"

Indirect Dependencies

These are replaceable or environment-specific dependencies:

• Local GPT2 image API compatible with http://127.0.0.1:7865/img2img.
• OpenAI-compatible LLM provider configured in app/config.py.
• Stable WeChat desktop UI layout.
• A visible/restorable WeChat main window.

Detailed Implementation Flow

1. app.main starts the FastAPI service and initializes runtime state.
2. /runtime/start starts GuiWorker.
3. GuiWorker locates the WeChat window, keeps the target chat active, and captures a window-handle screenshot.
4. message_watcher compares screenshots and determines whether a new user-side message appears.
5. image_acquirer saves original images through the WeChat GUI when an image task is detected.
6. task_runner writes the latest task state and prepares a brain request.
7. llm asks the configured model whether the task needs text reply, image edit, or both.
8. image_tools calls the local GPT2 image API when image editing is required.
9. wechat_sender serializes the GUI action and sends the result back to WeChat.
10. Runtime state can be inspected through /runtime/state and /tasks/latest.

How To Test It

Start the local GPT2 image API first:

Invoke-RestMethod http://127.0.0.1:7865/health

Start wxzdh:

cd C:\path\to\wxzdh
python -m uvicorn app.main:app --host 127.0.0.1 --port 8787

Or use:

.\run.ps1

Start the worker:

Invoke-RestMethod -Method Post http://127.0.0.1:8787/runtime/start

Check state:

Invoke-RestMethod http://127.0.0.1:8787/runtime/state

Expected state includes:

status = running
target_chat = configured target chat
rect = [0,0,1100,850]
latest_screenshot = <repo>\data\runtime\wechat_latest.png

For image tests, send one image plus a text instruction in the target chat, then inspect:

Invoke-RestMethod http://127.0.0.1:8787/tasks/latest

Stop the worker:

Invoke-RestMethod -Method Post http://127.0.0.1:8787/runtime/stop

Run a syntax check:

python -m compileall app

Common Errors

• worker hwnd is not ready: start the worker and confirm WeChat is logged in and visible.
• Screenshot shows another window: verify the worker selected the real WeChat main window, not a foreground screen region.
• Image acquisition fails: WeChat's image viewer or Save As dialog changed, or the original image cannot be saved through GUI automation.
• Image tool timeout: the local GPT2 image API is busy, stalled, or not running.
• Repeated old tasks: stop the worker, inspect /tasks/latest, then retry or restart after the UI settles.
• Text appears in the chat box instead of an image path being handled: original-image acquisition failed and the task should be retried after fixing the GUI flow.

Review

The latest local review passed the MVP acceptance checks with one external risk: successful image generation depends on the local GPT2 image API being stable.

Verified behavior includes:

• WeChat window-handle selection.
• Window-bound screenshot capture.
• Original image acquisition through GUI Save As.
• LLM JSON decision for image-edit intent.
• Suppression of self-sent message retriggers.
• python -m compileall app passing.

Version History

• v1: Initial open-source snapshot for the single-chat Windows WeChat automation MVP.

Related Links

• project-manifest.json: machine-readable snapshot metadata.
• docs/source.md: source material used to generate this repository snapshot.
• docs/reproduce.md: focused reproduction steps.
• docs/troubleshooting.md: operational failure notes.
• docs/review.md: review and verification notes.