WeChat Web Client

一个基于 FastAPI + React 的微信 Web 客户端示例项目，用于连接本地或远程微信 Hook/协议服务，提供会话列表、聊天消息、媒体加载、发送消息和实时回调展示等能力。

注意：本项目涉及微信 Hook/协议相关能力，请仅在你拥有授权的环境中学习、测试和使用，并自行遵守相关法律法规与平台规则。

功能特性

• 支持 local_hook、remote_hook、remote_protocol 三种连接模式；其中 remote_hook 表示远程客户端 Hook。
• 支持远程客户端 DLL 通过 ws://.../agent 或 wss://.../agent 主动连到后端，客户端不需要公网 IP，后端复用现有接口封装向 DLL 发送 JSON 调用。
• 支持多微信账号管理，按远程 Hook agent_id 与回调 selfwxid 隔离不同账号的数据、会话和联系人缓存。
• 支持访问密钥进入系统，进入后先展示微信账号卡片，再进入对应账号的聊天窗口，避免未授权用户直接看到聊天记录。
• 后端使用 FastAPI 封装微信 Hook/协议接口，并通过 WebSocket 向前端推送账号状态、会话、联系人和新消息。
• 前端使用 React + TypeScript + Vite，实现类似 PC 微信和手机微信的聊天、通讯录和个人资料界面。
• 支持会话列表、置顶标识、未读数、@我提示、右键菜单、头像缓存、历史消息缓存和本地 SQLite 预加载。
• 支持联系人通讯录：首次点击通讯录时调用 InitContact 获取完整 wxid/gid 列表，再按每批最多 100 个调用 GetContact 补全头像、昵称和画像；后续优先读取本地 SQLite。
• 通讯录按个人、群聊、公众号、服务号、企业微信联系人分类展示，并显示好友、群、公众号、服务号、企微数量；企业微信联系人使用 企微 标识。
• 支持群聊成员详情缓存，可通过 GetChatrooMmemberDetail 获取群成员头像、昵称并复用到群资料页。
• 支持文本、图片、文件发送，以及图片、表情、语音、视频、网址消息等展示；图片/文件类接口支持 fileData 方式，适配远程 Hook。
• 支持单号群发和多号群发，可按所有好友/所有群分类发送，支持 _NoSrc 高效发送和普通发送两种方式。
• 多号群发支持账号手动选择、全选/取消全选、当前账号进度、总进度和用户配置的并发上限。
• 支持手机端自适应访问，包含 Chats / Contacts / Me 底部导航、联系人分类页、资料页、聊天页，以及左右滑动进入/返回的页面过渡。
• 支持白天/夜晚模式，PC 和手机页面统一主题风格。
• 提供自动登录脚本 backend/login_remote_hook.py，可优先尝试免扫码登录，失败后回退到扫码登录。

页面效果

以下图片为脱敏示意效果图，只展示布局和功能区域，不包含真实聊天记录、账号密钥或业务数据。

PC 端

手机端

技术栈

• 后端：Python、FastAPI、Uvicorn、httpx、WebSocket、PyYAML
• 前端：React、TypeScript、Vite、Tailwind CSS
• 通信：REST API + WebSocket

目录结构

wechat_web/
├── backend/              # FastAPI 后端与微信接口封装
├── frontend/             # React + Vite 前端
├── config.example.yaml   # 脱敏配置模板
├── prompts.example.yaml  # 通用提示词模板
├── prompts.yaml          # 本地提示词（不会提交到 Git）
├── config.yaml           # 本地运行配置（不会提交到 Git）
└── README.md

快速开始

1. 准备配置

复制配置模板：

cp config.example.yaml config.yaml

然后根据你的 Hook/协议服务地址、端口和回调公网 IP 修改 config.yaml。

首次启动如果没有配置访问密钥，项目会自动使用默认 key：admin。建议启动后立即修改 config.yaml 中的 web_access_key 参数，避免继续使用默认密钥。

2. 启动后端

后端使用 Python 3.13。Windows 上运行 start-all.bat 时会自动检查 Python 3.13；未安装时会优先通过 winget 安装，无法使用 winget 时改用 Python 官网安装程序。若系统里有多个 Python，可通过 PYTHON_BIN 指定 3.13 解释器。

cd backend
pip install -r requirements.txt
python login_remote_hook.py
python main.py

远程 Hook DLL 若使用 RemoteWS="ws://公网IP:5000/agent" 直连后端，server_host 需要配置为 0.0.0.0，并确保云服务器安全组放行 5000。如果只通过前端端口或 Nginx 代理 /api、/agent，后端可以只监听 127.0.0.1:5000。

3. 启动前端

cd frontend
npm install
npm run dev

前端开发服务默认由 Vite 启动，接口通过同源代理访问后端。

Windows Server 2012 R2 不在当前 Node.js 的官方支持范围内。start-all.bat 会在检测到该系统时自动设置 NODE_SKIP_PLATFORM_CHECK=1 并验证 Node/npm 是否能够实际运行；如果仍出现系统 API 或 DLL 缺失错误，需要升级到 Windows Server 2016 或更高版本。

Windows 批处理文件以 CRLF 换行直接存入 Git，保证从 GitHub 下载 ZIP 后也可以正常调用子程序标签。如果旧下载包提示 The system cannot find the batch label specified - ensure_web_access_key，请重新下载最新版本并替换 start-all.bat、stop-all.bat 和 scripts/start-frontend-dev.bat，保留已有的 config.yaml 和 backend/db/。该标签错误与上面的 Node.js 兼容性警告是不同问题。

Windows 启动时会先清理当前项目遗留的后端、Vite 和 npm 进程，并等待 server_port 确认可用后再启动；stop-all.bat 也使用相同的进程识别和端口复检逻辑。若后端端口被其他项目占用，脚本会显示占用 PID 并停止，不会误杀无关进程。

常用命令

# 前端构建
cd frontend
npm run build

# 指定 Python 3.13 启动（Linux/macOS 示例）
PYTHON_BIN=/usr/bin/python3.13 ./start-all.sh

# 前端代码检查
cd frontend
npm run lint

配置说明

config.yaml 不会被提交到仓库。公开部署或提交代码前，请确认没有把真实 IP、Token、账号信息、日志、缓存文件或聊天媒体数据提交到 Git。

配置示例和公开文档中的服务地址统一使用 127.0.0.1，MCP 系统名称统一使用 mcp系统名称。实际部署地址、名称和密钥只保存在本地 config.yaml。首次克隆后运行 git config core.hooksPath .githooks，启用提交和推送检查：禁止跟踪 config.yaml、prompts.yaml 和数据库，阻止提交真实 IP、实际系统名称、源码中的服务地址和提示词。也可运行 python scripts/check-public-config.py --staged 手动检查暂存内容。

AI 提示词统一放在 YAML 配置中：复制 prompts.example.yaml 为本地 prompts.yaml 后修改；config.yaml 的 prompt_config_file 指向本地文件，缺少本地文件或对应条目时读取 prompt_example_file 指定的公开模板。明确配置为空的提示词会报错，防止执行不完整的指令。修改后重启后端即可更新桥接任务使用的提示词。

网络默认值使用 network_* 配置；MCP 默认名称、地址、Token 检查端口及默认回复模板使用 mcp_defaults；触发昵称、显示昵称和报表作者使用 workflow；业务任务标题及回复前缀使用 labels。协议会话列表密钥使用 protocol_session_list_key，公开模板留空。前端从后端读取所需配置，构建时不打包本地 YAML 或完整提示词。/api/client-settings 仅向已登录用户返回配置允许的公开资源和触发名称字段。

应用数据库统一使用标准 SQLite，默认无数据库密码，无需单独部署数据库服务。所有数据库及相关记录、迁移备份放在 backend/db/，该目录的运行数据不会提交到 Git：

• access_users.sqlite3：用户、访问密钥摘要及微信归属；hook_profiles.access_key 明文记录每条 Hook 配置所属的密钥，登录时可据此恢复原账号关联。
• wechat_cache.sqlite3 / wechat_protocol_cache.sqlite3：Hook / 协议模式的聊天和智能回复数据。
• users/<用户ID>.sqlite3：独立用户的聊天缓存。
• hook_instances.json、rdv_wxid_mapping.json 及配置迁移备份：相关运行记录。

从旧版本升级时，先停止旧后端，再启动新后端；程序自动将 backend/.sqlite_cache/ 和旧位置的 RDV 映射迁入 backend/db/。若新目录已有同名文件则保留新文件，将冲突的旧文件及其 SQLite 日志保存在 backend/db/legacy/（重名时添加序号），不会覆盖现有数据。备份时请先停止后端，再完整复制 backend/db/。

远程 Hook DLL 启动参数

使用远程 Hook 模式时，DLL 启动微信的参数必须带 RemoteWS。该参数用于让远程微信客户端主动建立到 Web 后端的 WebSocket 长连接。后端的 Hook API 调用和 DLL 的实时消息回调都会复用这条连接，不再需要配置 CallBackURL。

示例：

"C:\Program Files (x86)\Tencent\WeChat391016\WeChat\WeChat.exe" RecvType=1&ConnectType=http&RemoteWS="ws://127.0.0.1:5000/agent"&StartPort=30001&RDV=<客户端自己的RDV>

RemoteWS 支持两种形式：

• ws://host:port/agent：普通 WebSocket，适合内网、测试环境，或后端端口直接暴露的部署方式。
• wss://host/agent：TLS 加密 WebSocket，适合公网正式部署，通常由 Nginx/Caddy 等反向代理提供 HTTPS/WSS 证书，并转发到后端服务端口。

如果有多个微信客户端，每个客户端仍连接同一个 RemoteWS 地址；项目会根据远程 Hook 上报的 agent_id 和回调里的 selfwxid 区分不同微信号。

主要配置项：

• wechat_mode：微信使用方式，1=本地 Hook，2=远程客户端 Hook（客户端 DLL 主动连本后端 WS/WSS），3=远程服务器协议。旧配置 login 仍兼容，可选 local_hook、remote_hook、remote_protocol。
• *_host / *_api_port / *_mgr_port：不同模式下的服务地址和端口。
• 本地/远程 Hook 的账号页使用“启动微信”，通过对应 *_host:*_mgr_port（默认 29999）调用 /StartWechat，填写新接口端口、RDV 和微信目录（*_wechat_path，留空读取管理器注册表）。Hook 按返回的进程 ID 及接口端口查询 /IsLoginStatus、/GetLoginQRCode，不使用协议 session_id。远程 Hook 启用长连接时额外传入 RemoteWS，本地 Hook 使用 HTTP 回调。协议模式独立保留“扫码上号 / 老号登录”。
• ip：部署机器的 IP 或域名，作为相关网络配置的默认主机值。
• server_host / server_port：后端主服务监听地址和端口；DLL 直连 ws://公网IP:5000/agent 时用 server_host: "0.0.0.0"，只走前端或 Nginx 代理时可用 127.0.0.1。
• web_access_key：Web 前端和 /api/* 接口访问密钥；首次启动未配置时默认使用 admin，建议在本地 config.yaml 中改成自己的值。不要提交真实值，也可通过环境变量 WECHAT_WEB_ACCESS_KEY 配置。
• hook_api_concurrency：Hook/API 并发数；本地 Hook 默认 20，使同一条消息命中的多条规则回复可并发提交；远程 Hook/远程协议默认 10。修改后需重启后端。
• mcp_connections[].url：MCP 服务完整地址，默认 http://127.0.0.1:5222/mcp。可直接修改 config.yaml 中该连接的 url，保留原 id；重启后端或打开「AI 与 MCP 设置」重新加载后生效。未配置 mcp_connections 时，使用环境变量 MCP_URL 或默认地址；显式配置 mcp_connections: [] 可关闭全部连接。
• QueryDB 历史查询：不再使用旧的全局查询锁；同一账号的同一个数据库文件最多并发 4 路，第 5 个请求最多等待 10 秒，超时返回空结果并在日志中记录 pooled connection unavailable。
• frontend_host / frontend_port：前端开发服务器监听地址和端口，由 Vite 直接读取 config.yaml。Windows 的 start-all.bat 会从 frontend_port 开始检查最多 10 个连续端口，将首个空闲端口回写到 config.yaml，并在页面可访问后自动打开 http://127.0.0.1:<frontend_port>。
• agent_ws_enabled：仅远程 Hook（wechat_mode: 2）使用。启用后，远程客户端 DLL 主动连接本后端的 /agent WebSocket，Hook API 调用通过该长连接发送；本地 Hook（wechat_mode: 1）始终直连本机 HTTP 接口，不使用 RemoteWS。
• agent_ws_path：DLL 连接路径，默认 /agent。
• client_wss_host / client_wss_port / client_wss_scheme：生成 DLL 侧 RemoteWS 地址用的公网主机、端口和协议；无证书直连后端可用 client_wss_scheme: "ws"、client_wss_port: 5000，DLL 配置 RemoteWS="ws://127.0.0.1:5000/agent"；正式 TLS 部署用 client_wss_scheme: "wss"、client_wss_port: 443，DLL 配置 RemoteWS="wss://127.0.0.1/agent"。
• 使用前端端口代理 /agent 时，后端 server_port 不需要暴露公网；直连 server_port 时，需要云服务器安全组放行该端口。若使用 Nginx/Caddy，也需要保留 WebSocket Upgrade 头。
• recvtype：Hook 消息接收类型，默认 1；1 为 Hook 直接返回 msglist，2 为 protobuf/raw pb_msg。旧配置 recv_type 仍兼容。
• WECHAT_FILES_BASE：可选环境变量，用于指定本机微信文件目录；不设置时会按默认微信文件目录推导。

日志目录

日志按类型和日期分别存放，每天自动创建一个文件：

• 通用后端和 Hook API 日志：backend/logs/main/YYYY-MM-DD.log
• 智能回复收件、匹配、发送和耗时日志：backend/logs/smart_reply/YYYY-MM-DD.log
• 登录脚本日志：backend/logs/login/YYYY-MM-DD.log

智能回复触发的发送接口请求也写入 smart_reply 日志，不会混入 main 日志。日志通过后台线程写盘，不阻塞消息回复链路。

消息类型参考

历史消息来自 MSG*.db 的 MSG.Type 字段。当前已知类型：

Type	说明
1	文本消息
3	图片消息
34	语音消息
37	好友确认消息
40	POSSIBLEFRIEND_MSG
42	共享名片
43	视频消息
47	动画表情
48	位置消息
49	分享链接/文件/应用消息；appmsg.type=57 或 SubType=57 为引用消息。带 CompressContent 时优先调用 /GetMsgStruct 获取完整 XML。
50	VOIPMSG
51	微信初始化消息
52	VOIPNOTIFY
53	VOIPINVITE
62	小视频
9999	SYSNOTICE
10000	系统消息
10002	撤回消息

开源前注意事项

• frontend/node_modules/、后端缓存、上传文件、日志和本地配置均已通过 .gitignore 排除。
• 如果你已经误提交敏感配置，请立即撤销对应密钥或令牌，并清理 Git 历史。
• 本仓库默认不包含可运行的微信 Hook 服务本体，需要你自行准备对应服务。