docs: 重写 README，对齐 daemon + CLI 架构

2026-04-16 09:13:31 +08:00 · 2026-04-16 09:13:31 +08:00 · 181472a4ff
parent 152921acb2
commit 181472a4ff
1 changed files with 159 additions and 250 deletions
--- a/README.md
+++ b/README.md
@ -1,269 +1,178 @@
-# WeChat 4.x Database Decryptor
+# wx-cli

-微信 4.0 (Windows、MacOS、Linux) 本地数据库解密工具。从运行中的微信进程内存提取加密密钥，解密所有 SQLCipher 4 加密数据库，并提供实时消息监听。
+微信 4.x (macOS) 本地数据 CLI 工具。从运行中的微信进程内存提取加密密钥，后台常驻 daemon 持久缓存解密数据库，CLI 毫秒级响应。

-## 更新日志
+## 架构

-## 防失联tg: https://t.me/wechat_decrypt
+```
+wx (CLI) ──Unix socket──▶ wx-daemon (后台进程)
+                              │
+                    ┌─────────┼─────────┐
+               DBCache     联系人缓存   WAL 监听
+            (mtime 感知)              (500ms polling)
+```

-### 2025-03-03 — 富媒体内容 & 组合消息修复
+- **wx-daemon**：后台常驻，持有解密后的 DB 热缓存，首次解密后跨重启复用（mtime 不变则不重解密）
+- **wx (CLI)**：发 JSON 请求到 Unix socket，获得响应后格式化输出；首次调用自动启动 daemon

- **表情包内联显示**: 自动从 emoticon.db 构建 MD5→CDN 映射，支持自定义表情（NonStore）和商店表情（Store），CDN 下载后本地缓存
- **富媒体内容解析**: 链接卡片（type 49）、文件、视频号、小程序、引用回复、位置分享等在 Web UI 中完整渲染
- **文字+图片组合消息不再丢失**: 修复同时发送文字和图片时只显示最后一条的问题（前端去重 key 增加消息类型）
- **隐藏消息检测**: 新增 `_check_hidden_messages` 机制，session.db 只保存最后一条消息摘要，现在会异步查 message DB 找回同一秒内的其他消息
- **MonitorDBCache 线程安全**: 引入 per-key 锁，防止多线程并发解密同一数据库导致文件损坏
- **Web UI 改进**: 消息气泡样式优化、群聊发送者显示、图片缩略图点击放大
-
-## 原理
-
-微信 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**
-
-WCDB (微信的 SQLCipher 封装) 会在进程内存中缓存派生后的 raw key，格式为 `x'<64hex_enc_key><32hex_salt>'`。三个平台（Windows / Linux / macOS）均可通过扫描进程内存匹配此模式，再通过 HMAC 校验 page 1 确认密钥正确性。
-
-## 使用方法
+## 快速开始

 ### 环境要求

- Python 3.10+
- 微信 4.x
- `pip install -r requirements.txt`
-
-Windows：
-
- Windows 10/11
- 微信正在运行
- 需要管理员权限（读取进程内存）
-
-Linux：
-
- 64-bit Linux
- 需要 root 权限或 `CAP_SYS_PTRACE`（读取 `/proc/<pid>/mem`）
- `db_dir` 默认类似 `~/Documents/xwechat_files/<wxid>/db_storage`
-
-### 安装依赖
-
-```bash
-pip install -r requirements.txt
-```
-
-Windows 如果遇到权限不足或全局环境不可写，可以改用：
-
-```bash
-py -m pip install --user -r requirements.txt
-```
-
-如果需要读取受保护的进程或把依赖安装到系统 Python，也可能需要以管理员身份打开终端。
-
-### 快速开始
-
-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` 示例：
-
-```json
-{
-    "db_dir": "/home/yourname/Documents/xwechat_files/your_wxid/db_storage",
-    "keys_file": "all_keys.json",
-    "decrypted_dir": "decrypted",
-    "wechat_process": "wechat"
-}
-```
-
-`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`。
-
-### Web UI 说明
-
-`python main.py` 启动后打开 http://localhost:5678 查看实时消息流。
-
- 30ms 轮询 WAL 文件变化 (mtime)
- 检测到变化后全量解密 + WAL patch (~70ms)
- SSE 实时推送到浏览器
- 总延迟约 100ms
- **图片消息内联预览**（支持旧 XOR / V1 / V2 三种 .dat 加密格式）
-
-#### HTTP API
-
-| 端点 | 说明 |
-|------|------|
-| `GET /api/history` | 最近消息列表 (JSON) |
-| `GET /api/history?chat=群名` | 按群名/用户名过滤消息 |
-| `GET /api/history?since=1712000000` | 增量拉取（返回该时间戳之后的消息） |
-| `GET /api/history?chat=群名&since=ts&limit=100` | 参数可组合使用 |
-| `GET /api/tags` | 所有联系人标签及成员 (JSON) |
-| `GET /api/tags?name=同事` | 按标签名过滤 |
-| `GET /stream` | SSE 实时消息推送 |
-
-将特定群消息存到自己的数据库：监听 `/stream` 或轮询 `/api/history?chat=群名&since=上次时间戳`，写入即可。
-
-### MCP Server (Claude AI 集成)
-
-将微信数据查询能力接入 [Claude Code](https://claude.ai/claude-code)，让 AI 直接读取你的微信消息。
-
-```bash
-pip install -r requirements.txt
-```
-
-注册到 Claude Code：
-
-```bash
-claude mcp add wechat -- python C:\Users\你的用户名\wechat-decrypt\mcp_server.py
-```
-
-或手动编辑 `~/.claude.json`：
-
-```json
-{
-  "mcpServers": {
-    "wechat": {
-      "type": "stdio",
-      "command": "python",
-      "args": ["C:\\Users\\你的用户名\\wechat-decrypt\\mcp_server.py"]
-    }
-  }
-}
-```
-
-注册后在 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_contact_tags()` | 列出所有联系人标签及成员数量 |
-| `get_tag_members(tag_name)` | 获取指定标签下的所有联系人，支持模糊匹配 |
-| `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 密钥需要从运行中的微信进程内存中提取：
-
-```bash
-# 1. 在微信中打开查看 2-3 张图片（点击看大图）
-# 2. 立即运行密钥提取（持续监控版）：
-python find_image_key_monitor.py
-
-# 或单次扫描版：
-python find_image_key.py
-```
-
-密钥会自动保存到 `config.json` 的 `image_aes_key` 字段。之后 `monitor_web.py` 启动时会自动加载密钥，图片消息将显示内联预览。
-
-> **注意**: AES 密钥仅在微信查看图片时临时加载到内存中。如果扫描未找到密钥，请先在微信中查看几张图片，然后立即重新运行脚本。
-
-## 文件说明
-
-| 文件 | 说明 |
-|------|------|
-| `main.py` | **一键启动入口** — 自动配置、提取密钥、启动服务 |
-| `config.py` | 配置加载器（自动检测微信数据目录） |
-| `find_all_keys.py` | 平台分发入口（Windows / Linux） |
-| `find_all_keys_windows.py` | Windows 版内存扫描提 key |
-| `find_all_keys_linux.py` | Linux 版内存扫描提 key |
-| `decrypt_db.py` | 全量解密所有数据库 |
-| `mcp_server.py` | MCP Server，让 Claude AI 查询微信数据 |
-| `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_macos.c` | macOS 版内存密钥扫描器 (C, Mach VM API) |
-
-## 技术细节
-
-### WAL 处理
-
-微信使用 SQLite WAL 模式，WAL 文件是**预分配固定大小** (4MB)。检测变化时：
- 不能用文件大小 (永远不变)
- 使用 mtime 检测写入
- 解密 WAL frame 时需校验 salt 值，跳过旧周期遗留的 frame
-
-### 图片 .dat 加密格式
-
-微信本地图片 (.dat) 有三种加密格式：
-
-| 格式 | 时期 | Magic | 加密方式 | 密钥来源 |
-|------|------|-------|---------|---------|
-| 旧 XOR | ~2025-07 | 无 | 单字节 XOR | 自动检测 (对比 magic bytes) |
-| V1 | 过渡期 | `07 08 V1 08 07` | AES-ECB + XOR | 固定 key: `cfcd208495d565ef` |
-| V2 | 2025-08+ | `07 08 V2 08 07` | AES-128-ECB + XOR | 从进程内存提取 |
-
-V2 文件结构: `[6B signature] [4B aes_size LE] [4B xor_size LE] [1B padding]` + `[AES-ECB encrypted] [raw unencrypted] [XOR encrypted]`
-
-### 数据库结构
-
-解密后包含约 26 个数据库：
- `session/session.db` - 会话列表 (最新消息摘要)
- `message/message_*.db` - 聊天记录
- `contact/contact.db` - 联系人
- `media_*/media_*.db` - 媒体文件索引
- 其他: head_image, favorite, sns, emoticon 等
-
-## macOS 数据库密钥扫描 (WeChat 4.x)
-
-macOS 版微信 4.x 使用 SQLCipher 4 加密本地数据库，密钥格式为 `x'<64hex_key><32hex_salt>'`。C 版扫描器通过 Mach VM API 扫描微信进程内存提取密钥。
-
-### 前置条件
-
 - macOS (Apple Silicon / Intel)
- WeChat 4.x (macOS 版)
- Xcode Command Line Tools: `xcode-select --install`
- 微信需要 ad-hoc 签名（或安装了防撤回补丁）：
-  `sudo codesign --force --deep --sign - /Applications/WeChat.app`
+- WeChat 4.x (macOS 版，需 ad-hoc 签名，见下文)
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)（Python 包管理）
+- Xcode Command Line Tools：`xcode-select --install`

-### 编译和使用
+### 安装

 ```bash
-# 编译
-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>
+git clone git@github.com:jackwener/wx-cli.git
+cd wx-cli
+uv sync
 ```

-输出 `all_keys.json`，格式兼容 `decrypt_db.py`，可直接用于解密：
+### 初始化（首次使用）
+
+微信需要 ad-hoc 签名才能被扫描内存：

 ```bash
-python3 decrypt_db.py
+sudo codesign --force --deep --sign - /Applications/WeChat.app
+```
+
+然后打开微信并登录，运行初始化：
+
+```bash
+uv run python wx.py init
+```
+
+`wx init` 自动完成：
+1. 检测微信数据目录（`~/Library/Containers/.../xwechat_files/<wxid>/db_storage`）
+2. 编译 C 内存扫描器（如未编译）
+3. `sudo` 扫描微信进程内存，提取所有数据库密钥 → `all_keys.json`
+4. 更新 `config.json`
+
+### 使用
+
+```bash
+# 最近会话
+uv run python wx.py sessions
+
+# 聊天记录
+uv run python wx.py history "张三"
+uv run python wx.py history "AI群" --since 2026-04-01 --until 2026-04-15
+
+# 搜索消息
+uv run python wx.py search "Claude"
+uv run python wx.py search "会议" --in "工作群" --since 2026-01-01
+
+# 联系人
+uv run python wx.py contacts
+uv run python wx.py contacts -q "李"
+
+# 导出聊天记录
+uv run python wx.py export "张三" --format markdown -o chat.md
+uv run python wx.py export "AI群" --since 2026-01-01 --format json -o chat.json
+
+# 实时监听新消息（Ctrl+C 退出）
+uv run python wx.py watch
+uv run python wx.py watch --chat "AI交流群"
+uv run python wx.py watch --json | jq .content
+
+# daemon 管理
+uv run python wx.py daemon status
+uv run python wx.py daemon stop
+uv run python wx.py daemon logs
+uv run python wx.py daemon logs --follow
+```
+
+> **注**：daemon 在首次 CLI 调用时自动启动，无需手动运行。
+
+### 可选：设置别名
+
+```bash
+echo 'alias wx="uv run --directory /path/to/wx-cli python wx.py"' >> ~/.zshrc
+source ~/.zshrc
+
+# 之后可以直接用
+wx sessions
+wx history "张三"
+wx watch
+```
+
+## 命令参考
+
+### `wx init [--force]`
+首次初始化：检测数据目录、编译扫描器、提取密钥、写入配置。`--force` 强制重新扫描（微信更新后使用）。
+
+### `wx sessions [-n N] [--json]`
+列出最近 N 个会话（默认 20），显示未读数、最后消息摘要。
+
+### `wx history CHAT [-n N] [--offset N] [--since DATE] [--until DATE] [--json]`
+查看指定聊天的消息记录。`DATE` 格式：`YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM`。
+
+### `wx search KEYWORD [--in CHAT]... [-n N] [--since DATE] [--until DATE] [--json]`
+全库搜索消息，`--in` 可指定多个聊天范围。
+
+### `wx contacts [-q QUERY] [-n N] [--json]`
+列出或搜索联系人。
+
+### `wx export CHAT [-f FORMAT] [-o FILE] [-n N] [--since DATE] [--until DATE]`
+导出聊天记录。`-f` 支持 `markdown`（默认）、`txt`、`json`。`-o` 指定输出文件，不指定则输出到 stdout。
+
+### `wx watch [--chat CHAT] [--json]`
+实时监听新消息（WAL 变化推送，约 500ms 延迟）。`--json` 输出 JSON lines，方便 `jq` 处理。
+
+### `wx daemon status / stop / logs [-f] [-n N]`
+管理后台 daemon。`logs --follow` 等同 `tail -f`。
+
+## 原理
+
+### 密钥提取
+
+微信 4.x 使用 SQLCipher 4 加密本地数据库：
+- **加密**：AES-256-CBC + HMAC-SHA512
+- **KDF**：PBKDF2-HMAC-SHA512，256,000 次迭代
+- **页结构**：4096 bytes/page，reserve = 80（IV 16 + HMAC 64）
+
+WCDB 在进程内存中缓存派生后的 raw key，格式为 `x'<64hex_enc_key><32hex_salt>'`。C 扫描器（`find_all_keys_macos.c`）通过 macOS Mach VM API 扫描微信进程内存，匹配此模式，再用 HMAC 校验 page 1 确认密钥正确性，输出到 `all_keys.json`。
+
+### DBCache（mtime 感知缓存）
+
+daemon 首次解密后将结果（及 DB/WAL 的 mtime）持久化到 `~/.wechat-cli/cache/_mtimes.json`。重启时若 mtime 未变，直接复用已解密文件，无需重新解密。
+
+### WAL 监听
+
+微信使用 SQLite WAL 模式（WAL 文件固定预分配 4MB，不能靠文件大小判断变化）。daemon 每 500ms 检测 `session.db-wal` 的 mtime，有变化时重新解密并广播新消息给所有 `watch` 客户端。
+
+### 数据文件路径
+
+```
+~/.wechat-cli/
+├── daemon.sock       # Unix socket
+├── daemon.pid        # PID 文件
+├── daemon.log        # daemon 日志
+└── cache/
+    ├── _mtimes.json  # mtime 持久化索引
+    └── *.db          # 解密后的数据库缓存
+```
+
+## 数据库结构
+
+解密后约 26 个数据库：
+
+| 路径 | 内容 |
+|------|------|
+| `session/session.db` | 会话列表（最新消息摘要、未读数） |
+| `message/message_*.db` | 聊天记录（按 `Msg_<md5(username)>` 分表） |
+| `contact/contact.db` | 联系人（username、nick_name、remark） |
+| `media_*/media_*.db` | 媒体文件索引 |
+
+## 测试
+
+```bash
+uv run python -m pytest tests/ -v
 ```

 ## 免责声明