Skip to content
ZitongShiPublic

About

No description, website, or topics provided.

Resources

Stars

9 stars

Watchers

0 watching

Forks

Repository files navigation

WeChatCustomerBot

Windows desktop WeChat vision-assisted daily chat proxy prototype.

This first version is intentionally read-only by default:

  • It detects WeChat windows.
  • It screenshots a configured chat region.
  • It uses a vision model to extract recent chat events.
  • It deduplicates messages.
  • It can generate a suggested daily-chat reply.
  • It can manually send text when you explicitly run the send command.
  • It does not auto-send replies unless --auto-send is explicitly enabled.

Quick Start

cd E:\WeChatCustomerBot
copy config.example.json config.json
$env:BOT_LLM_API_KEY="your-api-key"
$env:PYTHONPATH="E:\WeChatCustomerBot\src"
python -m wechat_customer_bot list-windows
python -m wechat_customer_bot watch --hwnd 132854 --suggest

Use an independent WeChat private chat window where possible. Do not use group chats for automation.

To allow automatic sending for a specific independent private chat window:

python -m wechat_customer_bot watch --hwnd 132854 --auto-send

Only suggest decisions are sent. ignore and handoff decisions are never auto-sent.

For multiple windows, use one serial watcher instead of starting multiple watch processes:

python -m wechat_customer_bot watch-many --hwnd 4329172 --hwnd 2362606 --auto-send

This avoids concurrent window activation and reduces the chance of reading the wrong window.

Relay: forward a secondary account to the main account

wechat_relay watches the WeChat 4.x main window of the account logged in on this PC, forwards every new private/group message to one chat (your main account), and sends your replies back to the right sender.

How it works:

  • Unread red badges in the session list are detected locally from pixels (no model call).
  • The bot opens the chat and reads the title bar and the messages in one vision-model call (qwen3.6:35b on soclaas, ~1-4s). Left/right is then decided from pixels (green bubble, avatar side), not by the model.
  • To open a chat by name, the vision model lists the session-list rows (or the search results) and the click is snapped to the avatar found locally at that position; the chat's title is then read back by the vision model and must match exactly before anything is typed. Windows OCR is only used for right-click menu items.
  • New messages are found by anchoring on the last messages seen in that chat.
  • It forwards them as one message per chat and then waits in the main chat, so every new message elsewhere shows up as a badge. Messages arriving in the open main chat get no badge, so its messages area is compared with the last read every second (pixels only) and read again when it changed. A verified title bar is cached by its pixels, so going back to a chat usually needs no title read.
  • Images are copied with WeChat's own 复制 menu and sent as originals. Voice bubbles are converted with WeChat's own 转文字 before reading.

Forward format:

#12【群】专业班子
张三:今天几点开会?
李四:[图片] 会议室白板

Reply from the main account by quoting a forwarded message and typing, or with #12 内容. /截图 #12 (or /截图 会话名, or /截图 while quoting a forward) sends a screenshot of that chat as it looks right now. /暂停 30 keeps the bot's hands off the mouse and keyboard for 30 minutes (then it resumes by itself); /停止 shuts it down and start_relay.ps1 does not restart it. /list shows recent chats, /help shows usage.

Whenever the bot opens a chat (to reply, to take a screenshot, or by mistake) it reads it and relays anything new, because opening a chat clears its unread badge.

Setup:

cd E:\zt-toys\WeChatBot
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt winocr
copy relay.example.json relay.json        # edit forward_to if needed
# put SOCLAAS_API_KEY / SOCLAAS_BASE_URL into data\relay\soclaas.env
$env:PYTHONPATH="src"; .\.venv\Scripts\python.exe -m wechat_relay layout   # check detection
.\start_relay.ps1

Requirements and limits:

  • WeChat light theme, main window not minimized; the bot drives mouse and keyboard, so do not use this PC while it runs.
  • If the same account reads messages on a phone first, the PC badge disappears and the message is not forwarded.
  • Only messages visible on screen are read; very long bursts are marked as possibly incomplete.

Pool monitoring (号池监控)

With pool_group set in relay.json, the bot watches the API account pool and posts risk alerts to that one group (strict name match). Once a minute a background thread runs ssh <pool_ssh_host> and, on the server itself, curls the gateway's read-only monitoring API on 127.0.0.1:18320 with the token in /etc/aiproxy/pool-monitor.token (the token never leaves the server):

  • /api/monitoring/account-pool/snapshot: 5-minute success rate, eligible accounts.
  • /api/monitoring/account-pool/auth-health: each account's authorization state with its email. Served to direct loopback requests only; anything through nginx or a tunnel (which always carries X-Forwarded-For/X-Real-IP) gets 403.

Alerts: an account whose authorization is not healthy (401 授权失效 / 403 封号 / 403 禁止访问 / other 授权异常) and its recovery; the 5-minute success rate below pool_success_threshold (default 80%, at least pool_min_requests requests, two polls in a row; a reminder every pool_realert_minutes while it stays low) and its recovery; no eligible account left; the monitor unreachable for 3 polls. What was reported is kept in state.json so a restart does not repeat it. /号池 开|关 in the main chat switches it.

Scheduled reports: at each pool_report_times (SGT, default ["09:00", "21:00"], [] for none) the group gets one line of state followed by the /号池 overview picture. A slot is skipped while alerts are muted, while monitoring is off, and when the bot was not running within pool_report_grace_minutes (30) of it; each slot is reported at most once (last_report in state.json).

Group commands (window mode; anyone in the group, read-only except muting). With pool_commands on, the group window is read with the vision model at most once every pool_read_interval_sec (10 s) when its pixels change:

Command Answer
/号池 (/状态) 5-minute success rate, eligible accounts, queue, remaining quota, auth problems
/账号 every account: email, pool (号池中 / 等待区 / 休息区), authorization state
/趋势 [6h|30分钟|1天] success rate per time slot (default 1 hour, at most 1 day, ≤ 12 lines)
/静音 [30分钟|2h] hold alerts (default 30 min, at most 12 h); the state is posted when it ends
/取消静音 alerts back on now
/帮助 this list

@BQ7 /号池 and a full-width / work too. The same commands (except /帮助) are accepted in the main chat.

/号池, /账号 and /趋势 answer with a picture (pool_charts.py, Pillow, 1080 px wide, drawn at 2x and downsampled); the low-success-rate and empty-pool alerts are followed by the trend / overview picture. Layout follows public status pages (an overall banner, a row of per-period slots colored by health); colors are status colors only where they mean good/bad, request volume and success rate are two panels rather than a dual axis. If a picture cannot be drawn the text answer goes out instead; "pool_images": false turns pictures off.

Speed: the pool server is reached through one long-lived ssh session (a command costs one round trip, ~0.5 s, instead of a ~3 s handshake). Argument-free commands (/号池, /账号, /趋势) are spotted with Windows OCR on the newest line of the group (~0.15 s) and answered before the vision model reads the chat; everything else, and anything OCR misreads, waits for the model's read, which skips what OCR already answered.

Account changes ("pool_admin": true, off by default)

Members of the ops group (only that group) can delete and add pool accounts, always in two steps: the bot posts a preview with a 4-digit code, and nothing changes until someone replies /确认 <code> within pool_admin_confirm_sec (120 s). /取消 drops what is waiting; a code works once.

In the group Preview
/删除 邮箱 (/删号) the account, its pool and authorization state; close emails are suggested when nothing matches
a .json file read from the file WeChat saved under wechat_files_dir/wxid_*/msg/file/YYYY-MM/
account JSON pasted as text copied through WeChat's own 复制 menu (the clipboard), never read off the screenshot

The server side is a local-only endpoint of the pool gateway (POST /api/monitoring/account-pool/bot/accounts/{import,delete}[-preview]) with its own write token, /etc/aiproxy/pool-bot-admin.token (root only); requests through nginx or a tunnel get 403 even with the token. It reuses the admin console's import and delete code: a deleted account file is backed up first, and the provider runtime restarts for a few seconds. Account JSON crosses the ssh session base64-encoded through echo (never on a command line), stays in the bot's memory only until confirmed or expired, and neither the bot's log nor its replies show a token. The main chat refuses these commands.

Skill

The reply advisor loads:

E:\WeChatCustomerBot\skills\wechat-tt-customer-service\SKILL.md

The raw exports stay local under data\raw_wechat and are ignored by git. The distilled notes are under data\distilled.

Voice Messages

Voice bubbles are detected as voice. The current safe behavior is:

  • if WeChat already shows a text transcript, treat the transcript as text
  • if there is no visible transcript, do not guess the content
  • return handoff and let the administrator or a later UI workflow perform WeChat's built-in "转文字"

Automatic right-click "转文字" is not enabled yet because it needs per-window menu calibration.

Safety Boundary

The bot should not automatically handle:

  • transfers, payments, collections, or loan requests
  • verification codes, passwords, accounts, or private information
  • meetups, addresses, schedules, or promises with real-world consequences
  • serious emotional conflict, threats, complaints, or legal/illegal topics
  • voice messages without visible transcript
  • unclear screenshots or images

High-risk events should be handed to the human user.

About

No description, website, or topics provided.

Resources

Stars

9 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages