微信聊天记录读取与分析

技能文档

---
name: wechat-cli
title: 微信聊天记录读取与分析
category: 办公效率
description: "通过 wechat-cli 命令行工具读取和分析本地微信聊天记录、联系人、收藏等数据，支持会话浏览、消息搜索、记录导出与统计分析。当用户想查看、搜索、导出或分析微信消息、联系人、收藏时触发。"
---

# WeChat CLI — 微信聊天记录读取与分析

本技能通过 `wechat-cli` 命令行工具，帮助用户读取和分析本地微信的聊天记录、联系人、收藏等数据。支持会话浏览、消息搜索、聊天记录导出、统计分析等功能。

## 适用场景

- 查看最近会话列表 / 未读消息
- 查看指定联系人或群聊的聊天记录
- 按关键词搜索消息
- 导出聊天记录为 Markdown 或纯文本
- 聊天统计分析（消息数量、活跃度等）
- 查看微信收藏
- 获取增量新消息（断点续传）
- 对聊天记录进行分类总结、重点提取等分析任务

## 前置条件

### 系统支持
- Windows（Weixin.exe）
- macOS（WeChat）
- Linux（wechat）

### 必须满足
1. **使用指定版本的微信** — wechat-cli 仅兼容微信 4.0+ 新版架构，不支持 3.x 旧版。需自行安装微信 4.0 及以上版本，详见下方「微信安装」
2. **微信客户端已安装并登录** — 工具读取本地微信数据库，微信必须已登录
3. **初始化时微信必须处于运行状态** — 密钥提取需要扫描微信进程内存
4. **Python 3.10+** — wechat-cli 是 Python 工具

### 微信安装（重要）

wechat-cli **仅支持微信 4.0 及以上版本**，不支持微信 3.x 旧版。

**为什么需要 4.0+：**
- 微信 4.0 采用了全新的跨平台架构，进程名从 `WeChat.exe` 变为 `Weixin.exe`（Windows），数据目录从 `WeChat Files` 变为 `xwechat_files`
- wechat-cli 的密钥提取逻辑针对 4.0 架构设计，无法识别 3.x 版本的进程和数据库

需使用微信 4.0 及以上版本：

#### Windows 安装指引

1. **安装微信**：从微信官网下载并安装微信 4.0 及以上版本
2. **运行微信**：启动微信（Windows 新版进程名为 `Weixin.exe`）
3. **扫码登录**：用手机微信扫码登录
4. 确认微信已完全启动并登录后，再执行 `wechat-cli init`

#### macOS 安装指引

**第一步：安装微信**

1. 从微信官网下载 macOS 版微信 4.0+ 安装包
2. 将 **WeChat** 图标拖拽到 **Applications（应用程序）** 文件夹完成安装

**第二步：重新签名 WeChat（必须）**

macOS 默认禁止读取其他进程内存，需要对微信进行 ad-hoc 重签名，wechat-cli 才能提取密钥。

1. **打开终端**：在「启动台」搜索「终端」或「Terminal」并打开
2. **提取微信原有权限**：
```bash
codesign -d --entitlements - --xml /Applications/WeChat.app > ~/wechat_ent.plist
```
3. **复制 WeChat 到用户目录**（推荐，最安全）：
```bash
rm -rf ~/Applications/WeChat.app
cp -R /Applications/WeChat.app ~/Applications/
```
4. **对副本进行签名**：
```bash
codesign --force --deep --sign - --entitlements ~/wechat_ent.plist ~/Applications/WeChat.app
```
5. **以后运行这个副本**：
```bash
open ~/Applications/WeChat.app
```

**第三步：登录并初始化**

1. **打开微信**：运行上一步签名后的副本（`~/Applications/WeChat.app`）
2. **处理安全提示**：首次打开可能提示"无法验证开发者"或"来自身份不明的开发者"：
   - 点击 **取消**
   - 进入 **系统设置 → 隐私与安全性**，找到关于 WeChat 的安全提示，点击 **仍要打开**
   - 再次打开 WeChat，点击 **打开**
3. **扫码登录**：用手机微信扫码登录
4. 确认微信已完全启动并登录后，执行初始化：
```bash
sudo wechat-cli init --force
```

> **为什么需要重新签名？** macOS 出于安全考虑，禁止进程读取其他进程的内存。wechat-cli 需要扫描微信进程内存来提取数据库解密密钥，因此必须对微信进行 ad-hoc 重签名以放开此限制。
>
> **注意**：微信更新后需要重新签名。每次微信自动更新后，重复上述第二步即可。

#### 已安装旧版微信怎么办？

如果电脑上已经安装了旧版微信（3.x），需要先卸载或退出旧版，再安装上述指定版本。Windows 绿色版无需卸载原有微信，但建议退出正在运行的旧版微信后再启动新版。

> **注意**：不同微信版本的进程与数据库架构可能存在差异，密钥提取失败时请参考故障排查章节。

## 安装

```bash
pip install wechat-cli
```

依赖包（自动安装）：`click`、`pycryptodome`、`zstandard`

安装完成后验证：
```bash
wechat-cli --version
# 输出: wechat-cli, version 0.2.4
```

## 初始化（首次使用必读）

初始化会提取微信数据库的加密密钥并生成配置文件。**只需执行一次**。

### 步骤

1. **确保微信正在运行且已登录**（这是必须的，密钥从微信进程内存中提取）

2. **执行初始化命令**：
```bash
wechat-cli init
```
工具会自动：
- 检测微信数据目录
- 扫描微信进程内存提取数据库密钥
- 在 `~/.wechat-cli/` 下生成 `config.json` 和 `all_keys.json`

3. **如果自动检测失败**，手动指定数据目录：
```bash
wechat-cli init --db-dir "C:\path\to\db_storage"
```

### 微信数据目录位置参考

| 系统 | 默认路径 |
|------|----------|
| Windows | `%APPDATA%\Tencent\xwechat\config\*.ini` 指向的目录下 `xwechat_files\<wxid>\db_storage` |
| macOS | `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage` |
| Linux | `~/Documents/xwechat_files/<wxid>/db_storage` |

> **提示**：`<wxid>` 是你的微信内部 ID，类似 `wxid_xxxxxxxxxxxxx`。

### 重新初始化

如果密钥过期（如微信更新后），强制重新提取：
```bash
wechat-cli init --force
```

### 配置文件说明

初始化后，配置保存在 `~/.wechat-cli/` 目录：

| 文件 | 说明 |
|------|------|
| `config.json` | 主配置，记录 `db_dir`（数据库路径） |
| `all_keys.json` | 数据库解密密钥 |
| `last_check.json` | `new-messages` 命令的状态文件（记录上次读取位置） |

## 快速入门

### 1. 查看最近会话
```bash
wechat-cli sessions
```

### 2. 查看某人的聊天记录
```bash
wechat-cli history "张三" --limit 20
```

### 3. 搜索消息
```bash
wechat-cli search "关键词"
```

### 4. 查看未读会话
```bash
wechat-cli unread
```

### 5. 导出聊天记录
```bash
wechat-cli export "张三" --format markdown --output chat.md
```

## 命令总览

| 命令 | 说明 | 常用参数 |
|------|------|----------|
| `init` | 初始化（提取密钥） | `--db-dir`, `--force` |
| `sessions` | 最近会话列表 | `--limit`, `--format` |
| `history` | 指定聊天的消息记录 | `--limit`, `--offset`, `--start-time`, `--end-time`, `--type`, `--media` |
| `search` | 搜索消息内容 | `--chat`, `--start-time`, `--end-time`, `--limit`, `--type` |
| `contacts` | 搜索/列出联系人 | `--query`, `--detail`, `--limit` |
| `export` | 导出聊天记录 | `--format`, `--output`, `--start-time`, `--end-time`, `--limit` |
| `members` | 群聊成员列表 | `--format` |
| `stats` | 聊天统计分析 | `--start-time`, `--end-time`, `--format` |
| `unread` | 未读会话 | `--limit`, `--format` |
| `new-messages` | 增量新消息 | `--format` |
| `favorites` | 微信收藏 | `--type`, `--query`, `--limit`, `--format` |

> 完整命令参数详见 `references/commands.md`

## 输出格式

大多数命令支持 `--format` 参数：
- `json`（默认）— 结构化 JSON，适合程序处理
- `text` — 纯文本，适合人类阅读

时间格式：`YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS`

消息类型过滤（`--type`）：`text`、`image`、`voice`、`video`、`sticker`、`location`、`link`、`file`、`call`、`system`

## 重要注意事项

- **默认限制**：`history` 默认返回 50 条，`search` 最大 500 条，`sessions` 默认 20 个。导出大量数据时用 `--limit 100000`
- **系统占位会话**：`brandsessionholder`、`@placeholder_foldgroup` 是系统占位符，导出时会失败，属正常现象
- **隐私安全**：所有数据仅在本地处理，不会上传任何信息
- **微信需运行**：虽然查询操作不需要微信运行，但初始化（密钥提取）必须微信在线

## 技能工作流

当用户需要分析聊天记录时，推荐工作流详见 `references/analysis-guide.md`。

典型流程：
1. `sessions` — 浏览会话列表，确定分析对象
2. `history` — 读取目标聊天的消息记录
3. 对消息内容进行分类、总结、提取重点
4. 如需深度分析，用 `stats` 获取统计数据辅助

## 故障排查

常见问题及解决方案详见 `references/troubleshooting.md`。

## 微信 4.1.12+ 密钥提取（重要适配，2026-08-10 实测）

> **背景**：微信 4.1+ 不再在进程内存缓存明文密钥（`x'...'` 格式），`wechat-cli init` 的内存扫描在 4.1+ 上 0 命中属正常。wx_key（DLL 注入工具）已被 DMCA 下架，GitHub release 全删。实测发现：**4.1.12 的 `com.Tencent.WCDB.Config.Cipher` 对象里存的是每个数据库的（派生后密钥 32B + salt 16B）十六进制对，密钥可直接用于解密，无需 PBKDF2**。

### 前提
- 微信 4.1.12+ 正在运行且已登录
- **必须确认当前登录账号与目标 db_storage 目录一致**（多开/多账号环境：内存里的密钥属于当前登录账号！用 `check_account` 逻辑扫描内存中 `wxid_xxx` 出现次数确认）
- Python 环境：本机安装的 Python 3.10+

### 步骤
1. **扫描并 dump Config.Cipher blob**（脚本内改 DB_DIR 为目标账号目录）：
   ```
   python scripts/dump_config_blobs.py
   ```
   产出 `C:/Users/Administrator/AppData/Local/Temp/config_dump/blob_*.bin`
2. **提取密钥并生成配置**（脚本内改 DB_DIR）：
   ```
   python scripts/gen_keys.py
   ```
   自动对 blob 中所有 64~192 hex 串取 32B 窗口，用 HMAC 校验匹配数据库 salt，生成 `~/.wechat-cli/all_keys.json` + `config.json`
3. **验证**：
   ```
   wechat-cli sessions --limit 5 --format text
   ```

### 已知限制
- 实测 16/18 库成功；`message\weclaw.db`、`solitaire\solitaire.db` 未提取到（非核心库，不影响聊天记录查询）
- 微信重启/更新后密钥可能变化，需重新执行上述步骤
- 若 Config.Cipher 扫描 nodes=0：微信版本过新或进程选择错误，先确认登录账号
- 密钥对是 (key+salt)，**直接当加密密钥用，不要做 PBKDF2 派生**（那是 4.1.x 早期版本的 passphrase 路线）


## 参考文档

- [完整命令参考](references/commands.md)
- [消息分析工作流指南](references/analysis-guide.md)
- [常见问题排查](references/troubleshooting.md)

使用说明

# 微信聊天记录读取与分析

通过 wechat-cli 读取和分析本地微信聊天记录、联系人与收藏，支持会话浏览、消息搜索、导出与统计分析。需微信 4.0+ 已登录及 Python 3.10+。

## 快速开始

```text
帮我导出和某某的最近聊天记录并做一份聊天分析
```

## 使用说明

详细的工作流、参数与计费说明见 SKILL.md；按任务的深入指引见 references/ 目录。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。