Add Windows GUI and WXWork export support

2026-05-17 07:07:07 +08:00
parent 16940a8771 de4cb092d9
commit 5c3e6adfcd
38 changed files with 10005 additions and 887 deletions
--- a/README.md
+++ b/README.md
@@ -1,49 +1,93 @@
 # WeChat 4.x Database Decryptor

-微信 4.0 (Windows、MacOS、Linux) 本地数据库解密工具。从运行中的微信进程内存提取加密密钥，解密所有 SQLCipher 4 加密数据库，并提供实时消息监听。
+微信 4.0 (Windows / macOS / Linux) 本地数据库解密工具。从运行中的微信进程内存提取加密密钥，解密所有 SQLCipher 4 加密数据库，并提供实时消息监听、MCP Server、批量导出和语音转录。

-## 更新日志
+---

-## 防失联tg: https://t.me/wechat_decrypt
+## ⭐ 快速开始

-### 2025-03-03 — 富媒体内容 & 组合消息修复
+<details open>
+<summary>macOS — 最小路径（展开查看）</summary>

- **表情包内联显示**: 自动从 emoticon.db 构建 MD5→CDN 映射，支持自定义表情（NonStore）和商店表情（Store），CDN 下载后本地缓存
- **富媒体内容解析**: 链接卡片（type 49）、文件、视频号、小程序、引用回复、位置分享等在 Web UI 中完整渲染
- **文字+图片组合消息不再丢失**: 修复同时发送文字和图片时只显示最后一条的问题（前端去重 key 增加消息类型）
- **隐藏消息检测**: 新增 `_check_hidden_messages` 机制，session.db 只保存最后一条消息摘要，现在会异步查 message DB 找回同一秒内的其他消息
- **MonitorDBCache 线程安全**: 引入 per-key 锁，防止多线程并发解密同一数据库导致文件损坏
- **Web UI 改进**: 消息气泡样式优化、群聊发送者显示、图片缩略图点击放大
+```bash
+# 1. 安装依赖
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+brew install whisper-cpp           # 语音转录加速（可选，推荐）

-## 原理
+# 2. 密钥提取（退出微信后先重签名）
+killall WeChat
+sudo codesign --force --deep --sign - /Applications/WeChat.app
+cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
+sudo ./find_all_keys_macos         # 扫描内存提取密钥

-微信 4.0 使用 SQLCipher 4 加密本地数据库：
- **加密算法**: AES-256-CBC + HMAC-SHA512
- **KDF**: PBKDF2-HMAC-SHA512, 256,000 iterations
- **页面大小**: 4096 bytes, reserve = 80 (IV 16 + HMAC 64)
- **每个数据库有独立的 salt 和 enc_key**
+# 3. 解密 + 导出 + 转录
+python3 decrypt_db.py              # 解密所有数据库
+python3 export_all_chats.py -t     # 导出全部聊天并转录语音

-WCDB (微信的 SQLCipher 封装) 会在进程内存中缓存派生后的 raw key，格式为 `x'<64hex_enc_key><32hex_salt>'`。三个平台（Windows / Linux / macOS）均可通过扫描进程内存匹配此模式，再通过 HMAC 校验 page 1 确认密钥正确性。
+# 或一条命令从零到完成：
+make all
+```

-## 使用方法
+</details>
+
+<details>
+<summary>Windows — 最小路径</summary>
+
+```bash
+# 1. 以管理员身份打开终端
+# 2. 安装依赖
+py -m pip install -r requirements.txt
+
+# 3. 提取密钥 + 解密
+python main.py decrypt
+
+# 4. 批量导出
+python export_all_chats.py
+```
+
+</details>
+
+<details>
+<summary>Linux — 最小路径</summary>
+
+```bash
+# 1. 安装依赖
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 2. 提取密钥（需要 root 或 CAP_SYS_PTRACE）
+sudo python3 main.py decrypt
+
+# 3. 批量导出
+python3 export_all_chats.py
+```
+
+</details>
+
+---
+
+## 📖 详细指南

 ### 环境要求

 - Python 3.10+
- 微信 4.x
- `pip install -r requirements.txt`
+- 微信 4.x 正在运行

-Windows：
+**macOS**:
+- Xcode Command Line Tools: `xcode-select --install`
+- 需要对 `/Applications/WeChat.app` 做 ad-hoc 重签名（允许进程内存读取）
+- 需要 root 权限运行扫描器

- Windows 10/11
+**Windows**:
+- 管理员权限（读取进程内存）
 - 微信正在运行
- 需要管理员权限（读取进程内存）

-Linux：
-
- 64-bit Linux
- 需要 root 权限或 `CAP_SYS_PTRACE`（读取 `/proc/<pid>/mem`）
- `db_dir` 默认类似 `~/Documents/xwechat_files/<wxid>/db_storage`
+**Linux**:
+- root 权限或 `CAP_SYS_PTRACE`
+- 微信正在运行

 ### 安装依赖

@@ -51,124 +95,180 @@ Linux：
 pip install -r requirements.txt
 ```

-Windows 如果遇到权限不足或全局环境不可写，可以改用：
+<details>
+<summary>⚠️ 安装失败？ 点击展开</summary>
+
+**问题：`error: externally-managed-environment` (PEP 668)**
+
+Homebrew Python (3.12+) 和部分 Linux 发行版禁止 `pip install` 直接写入系统 Python 环境。
+
+**解决：使用虚拟环境**
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate   # 激活虚拟环境
+pip install -r requirements.txt
+
+# 后续运行脚本时使用 .venv 中的 Python
+.venv/bin/python3 main.py
+.venv/bin/python3 decrypt_db.py
+```
+
+或使用 Makefile（已配置 `.venv/bin/python3`）：
+
+```bash
+make setup   # 一键安装所有依赖 + 编译扫描器
+make decrypt # 等价于 .venv/bin/python3 main.py decrypt
+make all     # 从密钥提取到导出全部完成
+```
+
+Windows 可改用：

 ```bash
 py -m pip install --user -r requirements.txt
 ```

-如果需要读取受保护的进程或把依赖安装到系统 Python，也可能需要以管理员身份打开终端。
+</details>

-### 快速开始
+### 配置

-Windows：
-
-```bash
-python main.py
-python main.py decrypt
-```
-
-Linux：
-
-```bash
-python3 main.py decrypt
-```
-
-程序会自动完成：配置检测 → 内存扫描提取密钥 → 解密。首次运行会自动检测微信数据目录并生成 `config.json`。微信只要在运行中即可，无需重启或重新登录。
-
-如果自动检测失败（例如微信安装在非默认位置），手动创建 `config.json`：
-```json
-{
-    "db_dir": "D:\\xwechat_files\\你的微信ID\\db_storage",
-    "keys_file": "all_keys.json",
-    "decrypted_dir": "decrypted",
-    "wechat_process": "Weixin.exe"
-}
-```
-
-Linux 版 `config.json` 示例：
+程序会自动检测微信数据目录并生成 `config.json`。如果自动检测失败，手动创建：

 ```json
 {
-    "db_dir": "/home/yourname/Documents/xwechat_files/your_wxid/db_storage",
+    "db_dir": "/path/to/your/wxid/db_storage",
    "keys_file": "all_keys.json",
    "decrypted_dir": "decrypted",
-    "wechat_process": "wechat"
+    "wechat_process": "WeChat"
 }
 ```

-`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`。
+各平台默认路径：
+- macOS: `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage`
+- Windows: 微信设置 → 文件管理中查看
+- Linux: `~/Documents/xwechat_files/<wxid>/db_storage`

-### Web UI 说明
+### 常用命令
+
+| 用途 | 命令 |
+|------|------|
+| 提取密钥（macOS） | `sudo ./find_all_keys_macos` |
+| 提取密钥（Windows/Linux） | `python find_all_keys.py` |
+| 解密全部数据库 | `python decrypt_db.py` |
+| 启动 Web UI（实时消息） | `python main.py` |
+| 批量导出聊天记录 | `python export_all_chats.py` |
+| 批量导出 + 语音转录 | `python export_all_chats.py --with-transcriptions` |
+| 转录单个文件语音 | `python transcribe_chat.py input.json [output.json]` |
+| 注册 MCP Server（Claude） | `claude mcp add wechat -- python /path/to/mcp_server.py` |
+
+### Web UI

 `python main.py` 启动后打开 http://localhost:5678 查看实时消息流。

- 30ms 轮询 WAL 文件变化 (mtime)
- 检测到变化后全量解密 + WAL patch (~70ms)
+- 30ms 轮询 WAL 文件变化
 - SSE 实时推送到浏览器
- 总延迟约 100ms
- **图片消息内联预览**（支持旧 XOR / V1 / V2 三种 .dat 加密格式）
+- 图片消息内联预览

-### MCP Server (Claude AI 集成)
+#### HTTP API

-将微信数据查询能力接入 [Claude Code](https://claude.ai/claude-code)，让 AI 直接读取你的微信消息。
+| 端点 | 说明 |
+|------|------|
+| `GET /api/history` | 最近消息列表 |
+| `GET /api/history?chat=群名` | 按会话过滤 |
+| `GET /api/history?since=1712000000` | 增量拉取 |
+| `GET /api/tags` | 联系人标签 |
+| `GET /stream` | SSE 实时消息推送 |
+
+### MCP Server（Claude AI 集成）
+
+将微信数据查询能力接入 Claude Code，让 AI 直接读取你的微信消息。
+
+**注册：**

 ```bash
-pip install -r requirements.txt
+claude mcp add wechat -- python /path/to/mcp_server.py
 ```

-注册到 Claude Code：
+**可用工具：**

-```bash
-claude mcp add wechat -- python C:\Users\你的用户名\wechat-decrypt\mcp_server.py
-```
+| 工具 | 功能 |
+|------|------|
+| `get_recent_sessions(limit)` | 最近会话列表 |
+| `get_chat_history(chat_name, limit, offset, start_time, end_time)` | 聊天记录 |
+| `search_messages(keyword, chat_name, limit, offset, ...)` | 搜索消息 |
+| `get_contacts(query, limit)` | 联系人搜索 |
+| `get_contact_tags()` | 联系人标签 |
+| `get_voice_messages(chat_name)` | 语音消息列表 |
+| `decode_voice(chat_name, local_id)` | 解码语音为 WAV |
+| `transcribe_voice(chat_name, local_id)` | 转录语音为文字 |

-或手动编辑 `~/.claude.json`：
+### ⚠️ 语音转录
+
+`export_all_chats.py -t`、`transcribe_chat.py` 和 `transcribe_voice` MCP 工具共享同一套转录配置。
+
+**后端对比：**
+
+| 后端 | 速度 | 隐私 | 依赖 | 配置 |
+|------|------|------|------|------|
+| `local`（默认） | CPU，较慢 | 数据不出本机 | `pip install -r requirements.txt` | 无需配置 |
+| `openai` | API，最快 | 语音上传至 OpenAI | `pip install openai` | 需 `openai_api_key` |
+| `whisper_cpp` | Metal GPU，3-5x | 数据不出本机 | `brew install whisper-cpp` + 模型 | 自动检测 |
+
+**配置方式（config.json）：**

 ```json
 {
-  "mcpServers": {
-    "wechat": {
-      "type": "stdio",
-      "command": "python",
-      "args": ["C:\\Users\\你的用户名\\wechat-decrypt\\mcp_server.py"]
-    }
-  }
+    "transcription_backend": "whisper_cpp"
 }
 ```

-注册后在 Claude Code 中即可使用以下工具：
-
-| Tool | 功能 |
-|------|------|
-| `get_recent_sessions(limit)` | 最近会话列表（含消息摘要、未读数） |
-| `get_chat_history(chat_name, limit, offset, start_time, end_time)` | 指定聊天的消息记录，支持时间范围和分页 |
-| `search_messages(keyword, chat_name, start_time, end_time, limit, offset)` | 统一搜索消息；支持全库、单个聊天对象、多个聊天对象、时间范围和分页 |
-| `get_contacts(query, limit)` | 搜索/列出联系人 |
-| `get_new_messages()` | 获取自上次调用以来的新消息 |
-
-前置条件：需要先运行 `python main.py` 或 `python find_all_keys.py` 完成密钥提取。
-
-说明：`search_messages` 的 `limit` 最大为 `500`；`get_chat_history` 支持更大的 `limit`，但消息很多时仍建议配合 `offset` 分页读取。
-
-**[查看使用案例 →](USAGE.md)**
-
-### 图片解密 (V2 格式)
-
-微信 4.0 (2025-08+) 的 .dat 图片文件使用 AES-128-ECB + XOR 混合加密 (V2 格式)。AES 密钥需要从运行中的微信进程内存中提取：
+启用 whisper_cpp 前需安装：

 ```bash
-# 1. 在微信中打开查看 2-3 张图片（点击看大图）
-# 2. 立即运行密钥提取（持续监控版）：
-python find_image_key_monitor.py
-
-# 或单次扫描版：
-python find_image_key.py
+brew install whisper-cpp
+# 模型自动检测常见路径，或手动下载：
+# curl -L -o ~/whisper-models/ggml-base.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
 ```

-密钥会自动保存到 `config.json` 的 `image_aes_key` 字段。之后 `monitor_web.py` 启动时会自动加载密钥，图片消息将显示内联预览。
+**注意事项：**
+- 首次启用 openai 或 whisper_cpp 时会打印一行提示
+- openai 缺 key 时静默回退 local
+- whisper_cpp 二进制未找到时静默回退 local
+- 切换后端后旧缓存自动失效并重新转录

-> **注意**: AES 密钥仅在微信查看图片时临时加载到内存中。如果扫描未找到密钥，请先在微信中查看几张图片，然后立即重新运行脚本。
+### 图片解密
+
+微信 4.0 的 .dat 图片文件使用三种加密格式之一：
+
+| 格式 | 时期 | 加密方式 |
+|------|------|---------|
+| 旧 XOR | ~2025-07 | 单字节 XOR |
+| V1 | 过渡期 | AES-ECB + XOR |
+| V2 | 2025-08+ | AES-128-ECB + XOR |
+
+macOS 图片密钥从磁盘 kvcomm 缓存派生，无需扫描进程内存：
+
+```bash
+python find_image_key_macos.py
+```
+
+密钥自动保存到 `config.json`，之后 Web UI 自动显示图片预览。
+
+### Makefile 命令
+
+```bash
+make setup      # 全自动：venv → pip install → brew install → 编译扫描器 → 配置
+make build      # 编译 macOS 密钥扫描器
+make keys       # 提取密钥（需要 root）
+make decrypt    # 解密全部数据库
+make web        # 启动 Web UI
+make all        # 从零到完成：setup → keys → decrypt → export
+make status     # 显示当前数据状态
+make clean      # 交互式清理：选择删除 decrypted / exported_chats / 临时文件
+make help       # 列出所有命令
+```
+
+---

 ## 文件说明

@@ -184,19 +284,36 @@ python find_image_key.py
 | `find_all_keys_windows.py` | Windows 版内存扫描提 key |
 | `find_all_keys_linux.py` | Linux 版内存扫描提 key |
 | `decrypt_db.py` | 全量解密所有数据库 |
+| `export_all_chats.py` | 批量导出所有聊天为 JSON（支持 `-t` 附带语音转录） |
+| `export_chat.py` | 单会话导出（供 export_all_chats.py 内部调用） |
+| `chat_export_helpers.py` | 导出格式化共享函数（两脚本共用，避免代码漂移） |
+| `transcribe_chat.py` | 语音消息转录（共享 config.json 配置的 backend） |
 | `find_wxwork_keys.py` | 企业微信 Windows 版内存扫描提 key |
 | `decrypt_wxwork_db.py` | 企业微信 wxSQLite3 AES-128 数据库解密 |
 | `export_wxwork_messages.py` | 企业微信聊天记录导出（按个人/群筛选，CSV / HTML / JSON） |
 | `mcp_server.py` | MCP Server，让 Claude AI 查询微信数据 |
-| `monitor_web.py` | 实时消息监听 (Web UI + SSE + 图片预览) |
+| `monitor_web.py` | 实时消息监听 (Web UI + SSE) |
 | `monitor.py` | 实时消息监听 (命令行) |
-| `decode_image.py` | 图片 .dat 文件解密模块 (XOR / V1 / V2) |
-| `find_image_key.py` | 从微信进程内存提取图片 AES 密钥 |
-| `find_image_key_monitor.py` | 持续监控版密钥提取（推荐） |
-| `latency_test.py` | 延迟测量诊断工具 |
+| `find_all_keys.py` | 平台分发入口（Windows / Linux） |
 | `find_all_keys_macos.c` | macOS 版内存密钥扫描器 (C, Mach VM API) |
+| `find_image_key.py` | 从进程内存提取图片 AES 密钥（Windows / Linux） |
+| `find_image_key_macos.py` | macOS 版图片密钥派生（从磁盘 kvcomm 缓存推算） |
+| `decode_image.py` | 图片 .dat 文件解密模块 (XOR / V1 / V2) |
+| `config.json` | 配置文件（自动生成，手动编辑） |
+| `setup.sh` | 一键安装脚本 |

-## 技术细节
+---
+
+## 🔧 技术细节
+
+### 原理
+
+微信 4.0 使用 SQLCipher 4 加密本地数据库：
+- **加密算法**: AES-256-CBC + HMAC-SHA512
+- **KDF**: PBKDF2-HMAC-SHA512, 256,000 iterations
+- **每个数据库有独立的 salt 和 enc_key**
+
+WCDB (微信的 SQLCipher 封装) 会在进程内存中缓存派生后的 raw key，格式为 `x'<64hex_enc_key><32hex_salt>'`。三个平台均可通过扫描进程内存匹配此模式，再通过 HMAC 校验 page 1 确认密钥正确性。

 ### GUI 工具箱 & 单 exe 打包

@@ -230,7 +347,7 @@ build.bat
 ### WAL 处理

 微信使用 SQLite WAL 模式，WAL 文件是**预分配固定大小** (4MB)。检测变化时：
- 不能用文件大小 (永远不变)
+- 不能用文件大小（永远不变）
 - 使用 mtime 检测写入
 - 解密 WAL frame 时需校验 salt 值，跳过旧周期遗留的 frame

@@ -310,16 +427,20 @@ cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
 # 运行（自动查找微信进程、扫描内存、匹配 DB salt）
 sudo ./find_all_keys_macos

-# 或指定 PID
-sudo ./find_all_keys_macos <pid>
-```
+<details>
+<summary>点击展开</summary>

-输出 `all_keys.json`，格式兼容 `decrypt_db.py`，可直接用于解密：
+#### 2025-03-03 — 富媒体内容 & 组合消息修复
+- 表情包内联显示
+- 富媒体内容解析（链接卡片、文件、视频号、小程序等）
+- 文字+图片组合消息不再丢失
+- 隐藏消息检测机制
+- Web UI 改进

-```bash
-python3 decrypt_db.py
-```
+</details>

-## 免责声明
+### 免责声明

 本工具仅用于学习和研究目的，用于解密**自己的**微信数据。请遵守相关法律法规，不要用于未经授权的数据访问。
+
+防失联 TG: https://t.me/wechat_decrypt