From 6d40c7f737f7fe2421bf4ffbb92736a61b836eb8 Mon Sep 17 00:00:00 2001 From: jackwener Date: Thu, 16 Apr 2026 22:24:22 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=EF=BC=8C?= =?UTF-8?q?=E4=BC=98=E5=8C=96=E7=BB=93=E6=9E=84=E5=92=8C=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E5=B1=95=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 318 ++++++++++++++++++++++++++---------------------------- 1 file changed, 153 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 623a55e..bb88ccd 100644 --- a/README.md +++ b/README.md @@ -1,189 +1,177 @@ +
+ # wx-cli -微信 4.x (macOS/Linux/Windows) 本地数据 CLI 工具。从运行中的微信进程内存提取加密密钥，后台常驻 daemon 持久缓存解密数据库，CLI 毫秒级响应。 +**从命令行查询本地微信数据** -单一 Rust 二进制，无运行时依赖。 +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#安装) +[![Rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org) + +会话 · 聊天记录 · 搜索 · 联系人 · 群成员 · 收藏 · 统计 · 导出 + +
+ +--- + +## 特性 + +- **零依赖安装** — 单一 Rust 二进制，一行命令装完 +- **毫秒级响应** — 后台 daemon 持久缓存解密数据库，mtime 不变则复用 +- **AI 友好** — `--json` 输出纯 JSON，方便 LLM agent 直接调用 +- **完全本地** — 数据不出本机，实时解密，无需全量预解密 + +--- + +## 安装 + +```bash +curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh | bash +``` + +> 支持：macOS Apple Silicon / Intel，Linux x86_64 / arm64 + +
+其他安装方式 + +**手动下载** + +从 [Releases](https://github.com/jackwener/wx-cli/releases) 下载对应平台文件，重命名为 `wx`，`chmod +x` 后放入 PATH： + +| 平台 | 文件 | +|------|------| +| macOS Apple Silicon | `wx-macos-arm64` | +| macOS Intel | `wx-macos-x86_64` | +| Linux x86_64 | `wx-linux-x86_64` | + +**从源码构建** + +```bash +git clone git@github.com:jackwener/wx-cli.git && cd wx-cli +cargo build --release +# 产物：target/release/wx +``` + +
+ +--- + +## 快速开始 + +微信 4.x（macOS 版）需要先做 ad-hoc 签名才能扫描内存： + +```bash +sudo codesign --force --deep --sign - /Applications/WeChat.app +``` + +保持微信运行，然后初始化（只需一次）： + +```bash +sudo wx init +``` + +之后直接用，daemon 会在首次调用时自动启动： + +```bash +wx sessions # 查看最近会话 +wx history "张三" # 查看聊天记录 +wx search "Claude" # 搜索消息 +``` + +--- + +## 命令 + +### 消息 + +```bash +wx sessions # 最近 20 个会话 +wx unread # 有未读消息的会话 +wx new-messages # 上次检查后的新消息（增量） +wx history "张三" # 最近 50 条记录 +wx history "AI群" --since 2026-04-01 --until 2026-04-15 +wx search "关键词" # 全库搜索 +wx search "会议" --in "工作群" --since 2026-01-01 +``` + +### 联系人 & 群组 + +```bash +wx contacts # 联系人列表 +wx contacts -q "李" # 按名字搜索 +wx members "AI交流群" # 群成员列表 +``` + +### 收藏 & 统计 + +```bash +wx favorites # 全部收藏 +wx favorites --type image # 按类型筛选（text/image/article/card/video） +wx favorites -q "关键词" # 搜索收藏内容 +wx stats "AI群" # 聊天统计 +wx stats "AI群" --since 2026-01-01 # 指定时间范围 +``` + +### 导出 + +```bash +wx export "张三" --format markdown -o chat.md +wx export "AI群" --since 2026-01-01 --format json +``` + +### JSON 输出（AI agent 用） + +所有命令加 `--json` 输出机器可读的 JSON： + +```bash +wx sessions --json +wx search "关键词" --json | jq '.[0].content' +wx new-messages --json +``` + +### Daemon 管理 + +```bash +wx daemon status +wx daemon stop +wx daemon logs --follow +``` + +--- ## 架构 ``` wx (CLI) ──Unix socket──▶ wx-daemon (后台进程) │ - ┌─────────┼─────────┐ - DBCache 联系人缓存 WAL 监听 - (mtime 感知) (500ms polling) + ┌─────────┴──────────┐ + DBCache 联系人缓存 + (mtime 感知复用) ``` -- **wx-daemon**：后台常驻，持有解密后的 DB 热缓存，mtime 不变则跨重启复用，无需重解密 -- **wx (CLI)**：发 JSON 请求到 Unix socket，格式化输出；首次调用自动启动 daemon - -## 快速开始 - -### 环境要求 - -- macOS（Apple Silicon / Intel）或 Linux -- WeChat 4.x（macOS 版） -- 首次使用需 `sudo`（内存扫描） - -### 安装 - -**方式一：cargo install（推荐）** - -```bash -cargo install wx-cli -``` - -**方式二：下载预编译二进制** - -从 [Releases](https://github.com/jackwener/wx-cli/releases) 下载对应平台的文件： - -| 平台 | 文件名 | -|------|--------| -| macOS Apple Silicon | `wx-macos-arm64` | -| macOS Intel | `wx-macos-x86_64` | -| Linux x86_64 | `wx-linux-x86_64` | -| Windows x86_64 | `wx-windows-x86_64.exe` | - -```bash -# macOS arm64 示例 -curl -L https://github.com/jackwener/wx-cli/releases/latest/download/wx-macos-arm64 -o wx -chmod +x wx -sudo mv wx /usr/local/bin/ -``` - -**方式三：从源码构建** - -```bash -git clone git@github.com:jackwener/wx-cli.git -cd wx-cli -cargo build --release -# 二进制位于 target/release/wx -``` - -### 初始化（首次使用） - -macOS 上微信需要 ad-hoc 签名才能被扫描内存： - -```bash -sudo codesign --force --deep --sign - /Applications/WeChat.app -``` - -打开微信并登录，然后运行初始化： - -```bash -sudo wx init -``` - -`wx init` 自动完成： -1. 检测微信数据目录（`~/Library/Containers/.../xwechat_files//db_storage`） -2. 扫描微信进程内存，提取所有数据库密钥 → `~/.wx-cli/all_keys.json` -3. 写入 `~/.wx-cli/config.json` - -### 使用 - -```bash -# 最近会话 -wx sessions - -# 聊天记录 -wx history "张三" -wx history "AI群" --since 2026-04-01 --until 2026-04-15 - -# 搜索消息 -wx search "Claude" -wx search "会议" --in "工作群" --since 2026-01-01 - -# 联系人 -wx contacts -wx contacts -q "李" - -# 导出聊天记录 -wx export "张三" --format markdown -o chat.md -wx export "AI群" --since 2026-01-01 --format json -o chat.json - -# 实时监听新消息（Ctrl+C 退出） -wx watch -wx watch --chat "AI交流群" -wx watch --json | jq .content - -# daemon 管理 -wx daemon status -wx daemon stop -wx daemon logs -wx daemon logs --follow -``` - -> daemon 在首次 CLI 调用时自动启动，无需手动运行。 - -## 命令参考 - -### `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` 持续追踪新日志。 - -## 原理 - -### 密钥提取 - -微信 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>'`。Rust 扫描器通过 macOS Mach VM API（`mach_vm_region` + `mach_vm_read`）或 Linux `/proc//mem` 扫描微信进程内存，匹配此模式后输出到 `~/.wx-cli/all_keys.json`。 - -### DBCache（mtime 感知缓存） - -daemon 首次解密后将结果（及 DB/WAL 的 mtime，精度纳秒）持久化到 `~/.wx-cli/cache/_mtimes.json`。重启时若 mtime 未变，直接复用已解密文件。 - -### WAL 监听 - -daemon 每 500ms 检测 `session.db-wal` 的 mtime，有变化时重新解密并通过 Unix socket 广播新消息给所有 `watch` 客户端。 - -### 数据文件路径 +daemon 首次解密后将数据库和 mtime 持久化到 `~/.wx-cli/cache/`。重启后 mtime 未变则直接复用，无需重解密。 ``` ~/.wx-cli/ -├── config.json # 配置（DB 目录、密钥文件路径） +├── config.json # 配置 ├── all_keys.json # 数据库密钥 ├── daemon.sock # Unix socket -├── daemon.pid # PID 文件 -├── daemon.log # daemon 日志 +├── daemon.pid / .log └── cache/ - ├── _mtimes.json # mtime 持久化索引 - └── *.db # 解密后的数据库缓存 + ├── _mtimes.json # mtime 索引 + └── *.db # 解密后的数据库 ``` -## 数据库结构 +--- -解密后约 26 个数据库： +## 原理 -| 路径 | 内容 | -|------|------| -| `session/session.db` | 会话列表（最新消息摘要、未读数） | -| `message/message_*.db` | 聊天记录（按 `Msg_` 分表） | -| `contact/contact.db` | 联系人（username、nick_name、remark） | +微信 4.x 使用 SQLCipher 4 加密本地数据库（AES-256-CBC + HMAC-SHA512，PBKDF2 256,000 次迭代）。WCDB 在进程内存中缓存派生后的 raw key，格式为 `x'<64hex_key><32hex_salt>'`。 + +wx-cli 通过 macOS Mach VM API（`mach_vm_region` + `mach_vm_read`）或 Linux `/proc//mem` 扫描微信进程内存，匹配该模式提取密钥，daemon 按需解密并缓存。 + +--- ## 免责声明 -本工具仅用于学习和研究目的，用于解密**自己的**微信数据。请遵守相关法律法规，不要用于未经授权的数据访问。 +本工具仅用于学习和研究目的，用于解密**自己的**微信数据。请遵守相关法律法规，不得用于未经授权的数据访问。