okooo5km/wxeasy

Latest recorded source activity: September 17, 2026 at 08:23

SkillsMP catalog refreshed: October 29, 2026 at 18:30

skills collected: 1

GitHub stars: 0
GitHub forks: 0

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/okooo5km/wxeasy.

Repository README

Repository README source: README.md

Read the source README

Expand full README

<div align="center"> # wxeasy **从命令行查询本地微信数据** 当前版本：[v0.4.2](https://github.com/okooo5km/wxeasy/releases/tag/v0.4.2) · [更新说明](doc/release-v0.4.2.md) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#安装) [![Rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org) 会话 · 聊天记录 · 搜索 · 联系人 · 群成员 · 群昵称 · 收藏 · 统计 · 导出 </div> --- 公开仓库：[okooo5km/wxeasy](https://github.com/okooo5km/wxeasy) · [最新下载](https://github.com/okooo5km/wxeasy/releases/latest) · [问题反馈](https://github.com/okooo5km/wxeasy/issues) 克隆源码、安装 Skill 和下载 Release 无需 GitHub 登录或 SSH 密钥。 ## AI Agent Skill 通过 [skills CLI](https://github.com/vercel-labs/skills) 一键安装到 Claude Code、Cursor、Codex 等 agent： ```bash npx skills add okooo5km/wxeasy ``` 或全局安装： ```bash npx skills add okooo5km/wxeasy -g ``` 安装后 agent 会自动读取 `SKILL.md`，了解如何安装和调用 wxeasy。 --- ## 特性 - **单文件安装** — 查询功能使用单一 Rust 二进制；macOS 实时提钥另需系统 LLDB - **毫秒级响应** — 后台 daemon 持久缓存解密数据库，mtime 不变则复用 - **AI 友好** — `history` / `search` / `sessions` / `new-messages` / `stats` / `attachments` 默认返回 `{..., meta}` wrapper，agent 能直接消费 freshness / source 信息 - **完全本地** — 数据不出本机，实时解密，无需全量预解密 --- ## 安装 **优先使用 Release 二进制或源码构建。npm 发布已停用，npm 包可能落后。** v0.4.2 提供 Windows x86_64 与 macOS ARM／Intel 二进制；Linux 请从源码构建。 **macOS（curl）** ```bash curl -fsSL https://raw.githubusercontent.com/okooo5km/wxeasy/main/install.sh | bash ``` **Windows**（PowerShell；安装到当前用户目录） ```powershell irm https://raw.githubusercontent.com/okooo5km/wxeasy/main/install.ps1 | iex ``` <details> <summary>其他安装方式</summary> **手动下载** 从 [Releases](https://github.com/okooo5km/wxeasy/releases) 下载对应平台文件： | 平台 | 文件 | |------|------| | macOS Apple Silicon | [wxeasy-macos-arm64](https://github.com/okooo5km/wxeasy/releases/download/v0.4.2/wxeasy-macos-arm64) | | macOS Intel | [wxeasy-macos-x86_64](https://github.com/okooo5km/wxeasy/releases/download/v0.4.2/wxeasy-macos-x86_64) | | Windows x86_64 | [wxeasy-windows-x86_64.exe](https://github.com/okooo5km/wxeasy/releases/download/v0.4.2/wxeasy-windows-x86_64.exe) | 手动下载后，Windows 将文件重命名为 `wxeasy.exe` 并放入 PATH；macOS 将对应架构文件重命名为 `wxeasy`，然后执行 `chmod +x wxeasy && sudo mv wxeasy /usr/local/bin/`。 **从源码构建** ```bash git clone https://github.com/okooo5km/wxeasy.git cd wxeasy cargo build --release --locked # 产物：target/release/wxeasy（Windows: wxeasy.exe） ``` </details> --- ## 微信版本先看版本，并保持在 **4.1.9 及以下**： ```bash wxeasy wechat-version ``` **强烈建议钉在 4.1.9。** 新电脑直接装 4.1.9，登录后在微信设置里关闭自动更新。已经装了 4.1.10+ 的，先卸载微信、删掉本机数据目录，再装 4.1.9。不要「先低后高」。 | 平台 | 推荐版本 | 安装包 | |------|----------|--------| | macOS | 4.1.9.58 | [WeChatMac-4.1.9.58.dmg](https://github.com/zsbai/wechat-versions/releases/download/4.1.9.58/WeChatMac-4.1.9.58.dmg)（[发布页](https://github.com/zsbai/wechat-versions/releases/tag/4.1.9.58)） | | Windows | 4.1.9.57 | [weixin_4.1.9.57.exe](https://github.com/cscnk52/wechat-windows-versions/releases/download/v4.1.9.57/weixin_4.1.9.57.exe)（[发布页](https://github.com/cscnk52/wechat-windows-versions/releases/tag/v4.1.9.57)） | Mac 历史版本存档：[okooo5km/wechat-versions](https://github.com/okooo5km/wechat-versions)（fork 自 [zsbai/wechat-versions](https://github.com/zsbai/wechat-versions)）。安装包版权归腾讯，链接来自第三方存档，请自行核验文件。删数据会清掉本机聊天记录，先自行备份。macOS 目录：`~/Library/Containers/com.tencent.xinWeChat`。Windows 目录：`%APPDATA%\Tencent\xwechat`。提钥路径由微信桌面版版本决定，不要一上来就走 4.1.10+ 的 live-hook。 | 微信版本 | 默认 `wxeasy init` | 缺钥时 | |---------|-------------------|--------| | **4.1.9.x 及更早** | 原始稳态扫描 + 历史密钥复用 | 确认微信在跑，macOS 用 `sudo wxeasy init` | | **4.1.10+** | **只复用**已有 `all_keys.json`（page1 校验），不自动扫描、不自动 live-hook | 显式 `wxeasy init --live` 或 `--relaunch` | | 读不到版本 | 先尝试原始扫描再复用 | 看终端提示，确认版本后再选路径 | 实测结论： - **4.1.9 + 原始扫描**可以一次成型。 - **4.1.10+** 内存不再常驻 raw key，且可能监测本地数据库解密。不要无故 `--force` / `--live`。正确做法是退回 4.1.9，而不是继续升版本。 --- ## 快速开始先把微信钉在 4.1.9 并关闭自动更新，再初始化（只需一次）。`init` 会读取本机微信版本后选择路径。 **macOS** `4.1.9` 及更早用原始扫描；`4.1.10+` 默认只复用密钥。 ```bash # 4.1.9：原始稳态扫描（需要 sudo / 调试权限） sudo wxeasy init ``` Apple Silicon 在 **4.1.10+ 且缺钥** 时才用 LLDB： ```bash # 附加运行中的微信，打开会话触发开库，最多等待约 120 秒 wxeasy init --live # 显式重启微信，在登录时抓取 wxeasy init --relaunch ``` LLDB 路径需要 Xcode Command Line Tools 的 LLDB／Python 和可用的调试权限。上游提钥流程要求关闭 SIP；wxeasy 不自动修改 SIP、签名或 TCC。Intel 暂不支持 LLDB 抓取，只保留原始扫描和历史密钥复用。上游的 ARM 4.1.7+ 范围不等于本集成的真实设备兼容性保证。实现、权限边界与验证状态见 [上游分析](doc/pandorafuture-wx-cli-analysis.md)。 **Linux** ```bash sudo wxeasy init ``` **Windows**（以管理员身份运行 PowerShell） ```powershell wxeasy init ``` > **Windows 说明**：`4.1.9` 走原始内存扫描。`4.1.10+` 磁盘加密格式未变，但进程内存中往往不再常驻 `x'<key><salt>'` / 明文 raw key，默认 `init` **只 page1 校验复用** `~/.wxeasy/all_keys.json`（并兼容 `~/.wx-cli/all_keys.json`），**不再自动**切硬件断点。升级微信前请备份该文件。缺钥时才显式 `wxeasy init --live` 或 `--relaunch`。详见 [Windows 4.1.10+ 密钥扫描与复用](docs/windows-4.1.10-keys-and-reuse.md)。验证安装： ```bash wxeasy sessions ``` 能看到最近会话即表示一切正常。daemon 在首次调用时自动启动。 --- ## 命令 ### 消息 ```bash wxeasy sessions # 最近 20 个会话 wxeasy unread # 有未读消息的会话 wxeasy unread --filter private,group # 只看真人未读（过滤公众号/折叠入口） wxeasy new-messages # 上次检查后的新消息（增量） wxeasy history "张三" # 最近 50 条记录 wxeasy history "张三" -n 2000 # 拉更多历史消息 wxeasy history "AI群" --since 2026-04-01 --until 2026-04-15 wxeasy search "关键词" # 全库搜索 wxeasy search "关键词" -n 500 # 放宽搜索结果条数 wxeasy search "会议" --in "工作群" --since 2026-01-01 ``` `history` / `search` / `export` 都支持 `-n` / `--limit` 指定条数。默认值只是为了避免一次性输出过多消息，不是硬上限。会话/消息输出里都带 `chat_type` 字段，取值为 `private` / `group` / `official_account` / `folded`。`official_account` 涵盖公众号、订阅号、服务号及 `mphelper` / `qqsafe` 等系统通知；`folded` 对应微信里的"订阅号折叠"和"折叠群聊"两个聚合入口。群聊里的 `last_sender`、`sender` 和 `stats` 的 `top_senders` 会优先使用群昵称（群名片）。如果本地数据库里没有对应群昵称，则回退到联系人备注、微信昵称或 username。 `history` / `search` / `sessions` / `unread` / `new-messages` / `stats` / `attachments` 现在都会附带 `meta`： - `status`: `ok` / `possibly_stale` / `possibly_stale_unknown_shards` / `windowed` - `unknown_shards`: 磁盘上存在、但 daemon 当前没有 key 的 `message_N.db` 分片；非空时应先跑 `wxeasy init --force` - `chat_latest_timestamp` / `chat_latest_db`: 当前命中数据里最新一条消息的时间和分片来源 - `session_last_timestamp`: `session.db` 里 WeChat 自己记录的最新时间；如果明显领先于 `chat_latest_timestamp`，说明结果可能漏了消息默认情况下，人类用户会在 stderr 看到可执行的 warning；agent / 脚本可直接读 stdout 里的 `meta`。传 `--with-meta` 会额外返回 `per_shard_latest` / `cache_mode_per_shard`，传隐藏 flag `--debug-source` 还会带真实 `shard_paths`。引用消息会在 `history` / `search` / `new-messages` 输出中显示当前回复和被引用原文： ```text [引用] 当前回复 ↳ 发送者: 被引用内容 ``` `--type link` / `--type file` 会包含微信 appmsg 里的链接、文件、合并聊天记录和引用消息等变体；搜索时也会匹配解压后可见的引用原文。 ### 朋友圈（SNS）三个独立命令，区分"通知"和"帖子"： ```bash wxeasy sns-notifications # 点赞/评论通知（默认仅未读） wxeasy sns-notifications --include-read -n 100 # 含已读 wxeasy sns-feed # 近 20 条朋友圈（时间线） wxeasy sns-feed --user "张三" # 限定作者 wxeasy sns-feed --since 2026-04-01 -n 100 # 按时间 wxeasy sns-search "关键词" # 全文搜索朋友圈正文 wxeasy sns-search "婚礼" --user "李四" --since 2023-01-01 ``` - **sns-notifications** 返回互动通知：`type`（`like`/`comment`）、`from_nickname`、`content`（评论正文）、`feed_preview` + `feed_author`（对应原帖） - **sns-feed** / **sns-search** 返回朋友圈帖子：`author`、`content`（正文）、`media`、`media_count`、`location`、`timestamp`；`media` 字段含每张图的 url/thumb/key/token/md5/enc_idx/size，供下游做图片代理或离线渲染。`media_count = media.len()`，按 DOM 解析的合法 `<media>` 子节点计数（malformed XML 返回 0）朋友圈数据只覆盖你本地刷到过的帖子（微信 app 按需下载）。 ### 公众号文章公众号文章推送存在独立的 `biz_message_0.db`，用 `biz-articles` 单独查： ```bash wxeasy biz-articles # 最近 50 篇 wxeasy biz-articles -n 200 # 更多 wxeasy biz-articles --account "返朴" # 限定公众号（名称模糊匹配） wxeasy biz-articles --since 2026-05-01 --until 2026-05-10 wxeasy biz-articles --unread # 仅有未读的公众号，每号取最新 1 篇 wxeasy biz-articles --json | jq '.[].url' # 下游消费 URL ``` 每条返回：`account` / `account_username` / `title` / `url` / `digest` / `cover_url` / `time` / `timestamp` / `recv_time_str`。多图文推送会展开成多行。 ### 附件提取（图片）聊天里的附件本体存在 `xwechat_files/<wxid>/msg/attach/...` 下的 `.dat` 文件，需要按消息所在 `message_resource.db` 的 md5 + 平台相关 image key 解码才能拿到原图。 ```bash # 1) 列出会话里的图片附件，先拿到不透明的 attachment_id wxeasy attachments "张三" wxeasy attachments "AI群" --kind image -n 100 wxeasy attachments "AI群" --since 2026-04-01 --until 2026-04-15 # 2) 把单个 attachment_id 解密写出去（扩展名建议保留 .jpg / .mp4 等） wxeasy extract <attachment_id> -o ~/Desktop/photo.jpg wxeasy extract <attachment_id> -o /tmp/x.jpg --overwrite ``` `attachments` 输出每条带：`attachment_id` / `kind` / `type` / `local_id` / `timestamp` / `time`，群聊里还有 `sender`。当前 `kind` 固定为 `image`；命令名保留成 `attachments` 是为了后续扩到其他附件类型时不 break CLI。同一张图在 `Img/` 下最多有三档：`<md5>_h.dat`（高清原图，在微信里点开或下载过才有）、`<md5>.dat`（中尺寸，常为 HEVC）、`<md5>_t.dat`（缩略图）。`extract` 按 `_h` > 无后缀 > `_t` 取最好的一档；想要原图但 `dat_path` 不是 `_h.dat`，说明本地还没有高清版本。 `extract` 输出报告里带：`md5` / `dat_path` / `dat_size` / `output` / `output_size` / `format`（实际识别出的图片格式：jpg / png / gif / webp / hevc 等）/ `decoder`（实际选用的解码器：`legacy_xor` / `v1_aes` / `v2`）。支持的解码档位： - **legacy XOR**：早期单字节 XOR，无 magic（按文件首字节探测格式自动反推） - **V1 fixed-AES**（`07 08 V1 08 07`）：AES-128-ECB + 固定 key `cfcd208495d565ef` - **V2 AES + XOR**（`07 08 V2 08 07`）：AES-128-ECB + raw + XOR；AES key 平台派生 V2 image key 提取： - **macOS**：`kvcomm` cache（`key_<uin>_*.statistic` 文件名取 uin → `md5(str(uin) + wxid)[:16]`）+ brute-force fallback（`md5(str(uin))[:4] == wxid_suffix` 枚举 2^24）；xor_key = `uin & 0xff`，**不是硬编码 0x88** - **Windows**：扫 `Weixin.exe` 内存匹配 `[A-Za-z0-9]{32|16}` 候选，按 V2 template ciphertext-block 反验 - **Linux**：上游空白，遇到 V2 .dat 会报 unsupported ### 联系人 & 群组 ```bash wxeasy contacts # 联系人列表（仅真人） wxeasy contacts --query "李" # 按名字搜索 wxeasy groups # 群聊列表 wxeasy groups --query "AI" # 按群名搜索 wxeasy members "AI交流群" # 群成员列表 ``` `wxeasy groups --json` 每个群包含 `username`、`display` 与 `member_count`（成员数来自本地 contact.db 的成员表；老版本微信没有 `chatroom_member` 表时省略该字段）。 `wxeasy members --json` 返回的成员字段包括： - `username`：微信内部 username - `display`：用于展示的名称，优先使用群昵称 - `contact_display`：联系人备注或微信昵称 - `group_nickname`：群昵称；本地没有记录时为空字符串 - `is_owner`：是否群主 ### 收藏 & 统计 ```bash wxeasy favorites # 全部收藏 wxeasy favorites --type image # 按类型筛选（text/image/article/card/video） wxeasy favorites --query "关键词" # 搜索收藏内容 wxeasy stats "AI群" # 聊天统计 wxeasy stats "AI群" --since 2026-01-01 # 指定时间范围 ``` ### 导出 ```bash wxeasy export "张三" --format markdown -o chat.md wxeasy export "张三" -n 2000 --format markdown -o chat.md wxeasy export "AI群" --since 2026-01-01 --format json ``` ### 输出格式默认输出 YAML；`--json` 可切换为 JSON。对 agent 而言，`history` / `search` / `sessions` / `new-messages` / `stats` / `attachments` 的 stdout 现在是 wrapper，而不是裸数组： ```bash wxeasy sessions --json wxeasy search "关键词" --json | jq '.results[0].content' wxeasy new-messages --json wxeasy history "张三" --json | jq '.meta' wxeasy history "张三" --json --with-meta | jq '.meta.cache_mode_per_shard' ``` ### Daemon 管理 ```bash wxeasy daemon status wxeasy daemon stop wxeasy daemon logs --follow ``` --- ## 架构 ``` wxeasy (CLI) ──Unix socket──▶ wxeasy-daemon (后台进程) │ ┌─────────┴──────────┐ DBCache 联系人缓存 (mtime 感知复用) ``` daemon 首次解密后将数据库和 mtime 持久化到 `~/.wxeasy/cache/`。重启后 mtime 未变则直接复用，无需重解密。 ``` ~/.wxeasy/ ├── config.json # 配置 ├── all_keys.json # 数据库密钥 ├── daemon.sock # Unix socket ├── daemon.pid / .log └── cache/ ├── _mtimes.json # mtime 索引 └── *.db # 解密后的数据库 ``` --- ## 原理微信 4.x 的本地数据库使用 SQLCipher 4 风格的加密页布局，常见参数为 AES-256-CBC、HMAC-SHA512、4096 字节页和 80 字节保留区。wxeasy 保存的是逐库 AES `enc_key`，daemon 按需解密并缓存。密钥提取按微信版本分流： - **≤4.1.9**：各平台进程内存扫描 `x'<key><salt>'`（wx-cli 同源的原始方法）。这条路径还在 `main`，没有删。 - **≥4.1.10**：默认只校验复用已有密钥。Windows 可用硬件断点在 AES 设钥时捕获；macOS Apple Silicon 可显式通过 LLDB 捕获 PBKDF2 原始输入，按每个数据库的 salt 派生 AES 密钥并验证 HMAC。两条都要显式 `--live` / `--relaunch`，默认 `init` 不会自动切过去。 **PBKDF2 原始输入与派生后的 AES 密钥不能混用。** 磁盘密钥未轮换时，重启微信通常不会使已保存的密钥失效。详见 [Windows 实现记录](docs/wechat-4.1.11-key-extraction-rust.md) 和 [macOS 上游分析](doc/pandorafuture-wx-cli-analysis.md)。 --- ## 致谢本项目受 [ylytdeng/wechat-decrypt](https://github.com/ylytdeng/wechat-decrypt) 启发，在其基础上进行了重新设计与实现。感谢原作者的研究与探索。 macOS LLDB 提钥参考并适配了 [pandorafuture/wx-cli](https://github.com/pandorafuture/wx-cli) 的实现，保留其 [MIT 许可](doc/pandorafuture-MIT.txt)。 --- ## 免责声明本仓库是作者自用的本地只读工具，用来阅读本机、自己账号下的微信聊天记录，方便整理工作。它不是产品，不面向公众提供服务，也不承诺可用性。只允许处理你自己的数据。禁止用于他人账号、未授权访问、传播他人聊天内容，或任何违法用途。使用即自行承担风险，并遵守法律与微信用户协议。作者不对封号、投诉、数据丢失或其他后果负责。微信客户端与安装包版权归腾讯所有。本项目不修改、不分发微信安装包；文中下载链接来自第三方历史版本存档，请自行核验。

Loading the repository README…

Skills in this repository

Software Developers

1 occupation category · 100% classified

skill

occupation

description

updated

wxeasy

Software Developers

wxeasy — 从本地微信数据库查询聊天记录、联系人、会话、收藏等。用户提到微信聊天记录、联系人、消息历史、群成员、收藏内容时，使用此 skill 安装并调用 wxeasy。

Source text: Chinese

2026-09-17

Showing 1 of 1 collected skill.