wechat-bridge-linux 🤖

Linux WeChat native bridge — 把微信变成 AI Agent 的本地 API。

在 Linux 上运行官方原生微信，通过标准 Linux 接口（AT-SPI2 + SQLCipher）实现消息收发， 暴露轻量 HTTP API，供 Hermes Agent / n8n / Dify / 任意 AI 平台接入。

微信 (Linux 原生 QT) →  Xvfb + AT-SPI2 + DB 读取 → HTTP API (:18400) → AI Agent

✨ 特性

特性	状态
🟢 文本消息收发 — 纯 AT-SPI2 无障碍接口，零注入	✅
🔓 本地 DB 读取 — SQLCipher 解密接收消息，零延迟	✅
🖥️ Xvfb 无头运行 — 服务器无需显示器	✅
🔌 HTTP API — 兼容 wechat-bridge 协议	✅
🔄 开机自启 — systemd 保活	✅
🛡️ 全链路自愈 — 崩溃自动恢复	✅
🖼️ 图片/文件收发	🚧
🎙️ 语音消息	🚧
👥 群聊支持	🚧

🏗️ 架构

┌──────────────────────────────────────────┐
│          Linux WeChat (QT 原生)            │
│  官方 linux.weixin.qq.com 2024+           │
│  运行于 Xvfb :99 虚拟显示器               │
└────┬───────────────────────┬──────────────┘
     │ AT-SPI2 无障碍接口    │ SQLCipher 加密 DB
     ▼                       ▼
┌──────────────────────────────────────────┐
│         wechat-bridge-linux              │
│                                          │
│  ┌──────────────────┐                    │
│  │ DB Watcher       │ ← inotify + WAL   │
│  │ 密钥提取 → 解密   │   实时新消息      │
│  └──────────────────┘                    │
│  ┌──────────────────┐                    │
│  │ AT-SPI2 Sender   │ → 定位输入框       │
│  │ xdotool + Atspi  │   填入文字+发送    │
│  └──────────────────┘                    │
│  ┌──────────────────┐                    │
│  │ HTTP API (:18400)│ ← SSE 消息流       │
│  │ aiohttp          │   POST /send       │
│  └──────────────────┘                    │
└──────────┬───────────────────────────────┘
           │ Hermes Gateway 标准接口
           ▼
┌──────────────────────────────────────────┐
│        Hermes Agent / n8n / Dify         │
└──────────────────────────────────────────┘

🚀 快速开始

前置要求

• Linux (Debian 12 / Ubuntu 22.04+ 实测)
• Python 3.10+
• 一个微信个人号

一键安装

git clone https://github.com/djasdh/wechat-bridge-linux.git
cd wechat-bridge-linux
bash scripts/install.sh

手动安装

# 1. 安装系统依赖
sudo apt install -y xvfb at-spi2-core xdotool python3-gi python3-pip

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 启动微信
bash scripts/start-wechat.sh

# 4. 扫码登录

# 5. 启动 bridge
python -m src.main

验证

# 健康检查
curl http://127.0.0.1:18400/health

# 发送消息
curl -X POST http://127.0.0.1:18400/send \
  -H "Content-Type: application/json" \
  -d '{"wxid": "filehelper", "text": "你好，世界！"}'

# 查看联系人
curl http://127.0.0.1:18400/contacts

📡 API 文档

GET /health

Bridge 健康状态。

GET /messages/stream

SSE 消息流，实时推送新消息。

POST /send

发送消息。

{ "wxid": "目标ID", "text": "消息内容" }

GET /contacts?limit=20

联系人列表。

GET /chats?limit=20

最近会话列表。

🔧 与 Hermes Agent 集成

配置 ~/.hermes/config.yaml:

platforms:
  weixin:
    enabled: true
    extra:
      base_url: "http://127.0.0.1:18400"
      dm_policy: "open"

📜 许可证

MIT

🙏 致谢

• wechat-decrypt — DB 解密参考
• wechat-use — 架构灵感
• Hermes Agent — AI Agent 框架