e64006bafe
A CLI tool to query local WeChat data with 11 commands: sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, and init. Features: - Self-contained init with key extraction (no external deps) - On-the-fly SQLCipher decryption with caching - JSON output by default for LLM/AI tool integration - Message type filtering and chat statistics - Markdown/txt export for conversations - Cross-platform: macOS, Windows, Linux
233 lines
6.3 KiB
Markdown
233 lines
6.3 KiB
Markdown
# WeChat CLI
|
||
|
||
[English](README.md)
|
||
|
||
命令行工具，查询本地微信数据——聊天记录、联系人、会话、收藏等。默认 JSON 输出，专为 LLM 集成设计。
|
||
|
||
## 功能亮点
|
||
|
||
- **开箱即用** — `pip install` + `wechat-cli init`，无外部依赖
|
||
- **11 个命令** — sessions、history、search、contacts、members、stats、export、favorites、unread、new-messages、init
|
||
- **默认 JSON** — 结构化输出，方便程序解析
|
||
- **跨平台** — macOS、Windows、Linux
|
||
- **即时解密** — SQLCipher 数据库透明解密，带缓存
|
||
- **消息类型过滤** — 按文本、图片、链接、文件、视频等过滤
|
||
- **聊天统计** — 发言排行、类型分布、24 小时活跃分布
|
||
- **Markdown 导出** — 将聊天记录导出为 markdown 或纯文本
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install wechat-cli
|
||
```
|
||
|
||
或从源码安装：
|
||
|
||
```bash
|
||
git clone https://github.com/canghe/wechat-cli.git
|
||
cd wechat-cli
|
||
pip install -e .
|
||
```
|
||
|
||
### 初始化
|
||
|
||
确保微信正在运行，然后：
|
||
|
||
```bash
|
||
# macOS/Linux: 可能需要 sudo 权限
|
||
sudo wechat-cli init
|
||
|
||
# Windows: 在有足够权限的终端中运行
|
||
wechat-cli init
|
||
```
|
||
|
||
这一步会：
|
||
1. 自动检测微信数据目录
|
||
2. 从微信进程内存中提取加密密钥
|
||
3. 将配置和密钥保存到 `~/.wechat-cli/`
|
||
|
||
完成后即可使用所有命令。
|
||
|
||
## 命令一览
|
||
|
||
### sessions — 最近会话
|
||
|
||
```bash
|
||
wechat-cli sessions # 最近 20 个会话 (JSON)
|
||
wechat-cli sessions --limit 10 # 最近 10 个
|
||
wechat-cli sessions --format text # 纯文本输出
|
||
```
|
||
|
||
### history — 聊天记录
|
||
|
||
```bash
|
||
wechat-cli history "张三" # 最近 50 条消息
|
||
wechat-cli history "张三" --limit 100 --offset 50
|
||
wechat-cli history "交流群" --start-time "2026-04-01" --end-time "2026-04-03"
|
||
wechat-cli history "张三" --type link # 只看链接/文件
|
||
wechat-cli history "张三" --format text
|
||
```
|
||
|
||
**选项：** `--limit`、`--offset`、`--start-time`、`--end-time`、`--type`、`--format`
|
||
|
||
### search — 搜索消息
|
||
|
||
```bash
|
||
wechat-cli search "Claude" # 全局搜索
|
||
wechat-cli search "Claude" --chat "交流群" # 指定聊天搜索
|
||
wechat-cli search "开会" --chat "群A" --chat "群B" # 多个聊天
|
||
wechat-cli search "报告" --type file # 只搜文件
|
||
```
|
||
|
||
**选项：** `--chat`（可多次指定）、`--start-time`、`--end-time`、`--limit`、`--offset`、`--type`、`--format`
|
||
|
||
### contacts — 联系人搜索与详情
|
||
|
||
```bash
|
||
wechat-cli contacts --query "李" # 搜索联系人
|
||
wechat-cli contacts --detail "张三" # 查看详情
|
||
wechat-cli contacts --detail "wxid_xxx" # 通过 wxid 查看
|
||
```
|
||
|
||
详情包括：昵称、备注、微信号、个性签名、头像 URL、账号类型。
|
||
|
||
### members — 群成员列表
|
||
|
||
```bash
|
||
wechat-cli members "AI交流群" # 成员列表 (JSON)
|
||
wechat-cli members "AI交流群" --format text
|
||
```
|
||
|
||
显示成员昵称、wxid、备注和群主。
|
||
|
||
### stats — 聊天统计
|
||
|
||
```bash
|
||
wechat-cli stats "AI交流群"
|
||
wechat-cli stats "张三" --start-time "2026-04-01" --end-time "2026-04-03"
|
||
wechat-cli stats "AI交流群" --format text
|
||
```
|
||
|
||
返回：消息总数、类型分布、发言 Top 10、24 小时活跃分布（含柱状图）。
|
||
|
||
### export — 导出聊天记录
|
||
|
||
```bash
|
||
wechat-cli export "张三" --format markdown # 输出到 stdout
|
||
wechat-cli export "张三" --format txt --output chat.txt # 输出到文件
|
||
wechat-cli export "群聊" --start-time "2026-04-01" --limit 1000
|
||
```
|
||
|
||
**选项：** `--format markdown|txt`、`--output`、`--start-time`、`--end-time`、`--limit`
|
||
|
||
### favorites — 微信收藏
|
||
|
||
```bash
|
||
wechat-cli favorites # 最近收藏
|
||
wechat-cli favorites --type article # 只看文章
|
||
wechat-cli favorites --query "计算机网络" # 搜索收藏
|
||
```
|
||
|
||
**类型：** text、image、article、card、video
|
||
|
||
### unread — 未读会话
|
||
|
||
```bash
|
||
wechat-cli unread # 所有未读会话
|
||
wechat-cli unread --limit 10 --format text
|
||
```
|
||
|
||
### new-messages — 增量新消息
|
||
|
||
```bash
|
||
wechat-cli new-messages # 首次: 返回未读消息 + 保存状态
|
||
wechat-cli new-messages # 后续: 仅返回上次以来的新消息
|
||
```
|
||
|
||
状态保存在 `~/.wechat-cli/last_check.json`，删除此文件可重置。
|
||
|
||
## 消息类型过滤
|
||
|
||
`--type` 选项（适用于 `history` 和 `search`）：
|
||
|
||
| 值 | 说明 |
|
||
|---|------|
|
||
| `text` | 文本消息 |
|
||
| `image` | 图片 |
|
||
| `voice` | 语音 |
|
||
| `video` | 视频 |
|
||
| `sticker` | 表情 |
|
||
| `location` | 位置 |
|
||
| `link` | 链接/应用消息 |
|
||
| `file` | 文件 |
|
||
| `call` | 音视频通话 |
|
||
| `system` | 系统消息 |
|
||
|
||
## 使用场景
|
||
|
||
### AI 工具集成
|
||
|
||
```bash
|
||
# 供 Claude Code、Cursor 等 AI 工具调用
|
||
wechat-cli sessions --limit 5
|
||
wechat-cli history "张三" --limit 20 --format text
|
||
wechat-cli search "截止日期" --chat "项目组" --type text
|
||
```
|
||
|
||
所有命令默认输出 JSON，适合 AI Agent 工具调用。
|
||
|
||
### 聊天分析
|
||
|
||
```bash
|
||
# 群里谁最活跃？
|
||
wechat-cli stats "项目组" --format text
|
||
|
||
# 查看所有分享的链接
|
||
wechat-cli history "张三" --type link --limit 50
|
||
|
||
# 搜索特定文件
|
||
wechat-cli search "报告.xlsx" --type file
|
||
```
|
||
|
||
### 数据备份
|
||
|
||
```bash
|
||
wechat-cli export "项目组" --format markdown --output project.md
|
||
wechat-cli export "张三" --start-time "2026-01-01" --format txt --output chat.txt
|
||
```
|
||
|
||
### 消息监控
|
||
|
||
```bash
|
||
# 定时检查新消息
|
||
*/5 * * * * wechat-cli new-messages --format text
|
||
```
|
||
|
||
## 平台支持
|
||
|
||
| 平台 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| macOS (Apple Silicon) | 支持 | 内置 arm64 二进制用于密钥提取 |
|
||
| macOS (Intel) | 支持 | 需要 x86_64 二进制 |
|
||
| Windows | 支持 | 读取 Weixin.exe 进程内存 |
|
||
| Linux | 支持 | 读取 /proc/pid/mem，需要 root |
|
||
|
||
## 工作原理
|
||
|
||
微信将聊天数据存储在本地的 SQLCipher 加密 SQLite 数据库中。WeChat CLI：
|
||
|
||
1. **提取密钥** — 扫描微信进程内存获取加密密钥（`wechat-cli init`）
|
||
2. **即时解密** — 透明解密数据库，使用页级 AES-256-CBC + 缓存
|
||
3. **本地查询** — 所有数据留在本机，无需网络访问
|
||
|
||
## 环境要求
|
||
|
||
- Python >= 3.10
|
||
- 微信在本地运行（用于 `init` 密钥提取）
|
||
|
||
## 开源协议
|
||
|
||
[Apache License 2.0](LICENSE)
|