Redesign READMEs: add badges, AI agent guides, npm as recommended install
- Add npm version, license, and platform badges - Feature npm as primary installation method - Add Claude Code and OpenClaw integration guides - Add section icons and Star History chart
This commit is contained in:
canghe
parent
f51e89ce12
commit
e6f79aff0b
245
README.md
245
README.md
@ -1,39 +1,51 @@
|
||||
<div align="center">
|
||||
|
||||
# WeChat CLI
|
||||
|
||||
**Query your local WeChat data from the command line.**
|
||||
|
||||
[](https://www.npmjs.com/package/@canghe_ai/wechat-cli)
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
[](https://github.com/freestylefly/wechat-cli)
|
||||
|
||||
Chat history · Contacts · Sessions · Favorites · Statistics · Export
|
||||
|
||||
[中文文档](README_CN.md)
|
||||
|
||||
A command-line tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration with JSON output by default.
|
||||
</div>
|
||||
|
||||
## Features
|
||||
---
|
||||
|
||||
- **Self-contained** — `pip install` + `wechat-cli init`, no external dependencies
|
||||
- **11 commands** — sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, init
|
||||
- **JSON by default** — structured output for programmatic access
|
||||
- **Cross-platform** — macOS, Windows, Linux
|
||||
- **On-the-fly decryption** — SQLCipher databases decrypted transparently with caching
|
||||
- **Message type filtering** — filter by text, image, link, file, video, etc.
|
||||
- **Chat statistics** — top senders, type breakdown, hourly activity distribution
|
||||
- **Markdown export** — export conversations as markdown or plain text
|
||||
## ✨ Highlights
|
||||
|
||||
## Quick Start
|
||||
- **🚀 Zero-config install** — `npm install -g` and you're done, no Python needed
|
||||
- **📦 11 commands** — sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, init
|
||||
- **🤖 AI-first** — JSON output by default, designed for LLM agent tool calls
|
||||
- **🔒 Fully local** — on-the-fly SQLCipher decryption, data never leaves your machine
|
||||
- **📊 Rich analytics** — top senders, message type breakdown, 24-hour activity charts
|
||||
- **📝 Flexible export** — Markdown or plain text, with time range filtering
|
||||
|
||||
### Install
|
||||
---
|
||||
|
||||
**Via pip (requires Python >= 3.10):**
|
||||
## 📥 Installation
|
||||
|
||||
```bash
|
||||
pip install wechat-cli
|
||||
```
|
||||
|
||||
**Via npm (standalone binary, no Python needed):**
|
||||
### npm (Recommended)
|
||||
|
||||
```bash
|
||||
npm install -g @canghe_ai/wechat-cli
|
||||
```
|
||||
|
||||
> Currently only **macOS arm64** binary is available. Other platforms (macOS Intel, Linux, Windows) can use the pip install method. PRs with additional platform binaries are welcome.
|
||||
> Currently ships a **macOS arm64** binary. Other platforms can use the pip method below. PRs with additional platform binaries are welcome.
|
||||
|
||||
Or install from source:
|
||||
### pip
|
||||
|
||||
```bash
|
||||
pip install wechat-cli
|
||||
```
|
||||
|
||||
Requires Python >= 3.10.
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/freestylefly/wechat-cli.git
|
||||
@ -41,7 +53,11 @@ cd wechat-cli
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Initialize
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Step 1 — Initialize
|
||||
|
||||
Make sure WeChat is running, then:
|
||||
|
||||
@ -53,67 +69,118 @@ sudo wechat-cli init
|
||||
wechat-cli init
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Auto-detect your WeChat data directory
|
||||
2. Extract encryption keys from WeChat process memory
|
||||
3. Save config and keys to `~/.wechat-cli/`
|
||||
This auto-detects your WeChat data directory, extracts encryption keys, and saves config to `~/.wechat-cli/`.
|
||||
|
||||
That's it — you're ready to go.
|
||||
|
||||
## Commands
|
||||
|
||||
### sessions — Recent Chats
|
||||
### Step 2 — Use It
|
||||
|
||||
```bash
|
||||
wechat-cli sessions # Last 20 sessions (JSON)
|
||||
wechat-cli sessions # Recent chats
|
||||
wechat-cli history "Alice" --limit 20 # Chat messages
|
||||
wechat-cli search "deadline" --chat "Team" # Search messages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Using with AI Agents
|
||||
|
||||
WeChat CLI is designed as an AI agent tool. All commands output structured JSON by default.
|
||||
|
||||
### Claude Code
|
||||
|
||||
Add to your project's `CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
## WeChat CLI
|
||||
|
||||
You can use `wechat-cli` to query my local WeChat data.
|
||||
|
||||
Common commands:
|
||||
- `wechat-cli sessions --limit 10` — list recent chats
|
||||
- `wechat-cli history "NAME" --limit 20 --format text` — read chat history
|
||||
- `wechat-cli search "KEYWORD" --chat "CHAT_NAME"` — search messages
|
||||
- `wechat-cli contacts --query "NAME"` — search contacts
|
||||
- `wechat-cli unread` — show unread sessions
|
||||
- `wechat-cli new-messages` — get messages since last check
|
||||
- `wechat-cli members "GROUP"` — list group members
|
||||
- `wechat-cli stats "CHAT" --format text` — chat statistics
|
||||
```
|
||||
|
||||
Then in conversation you can ask Claude things like:
|
||||
- "Check my unread WeChat messages"
|
||||
- "Search for messages about the project deadline in the Team group"
|
||||
- "Who sent the most messages in the AI group this week?"
|
||||
|
||||
### OpenClaw / MCP Integration
|
||||
|
||||
WeChat CLI works with any AI tool that can execute shell commands:
|
||||
|
||||
```bash
|
||||
# Get recent conversations
|
||||
wechat-cli sessions --limit 5
|
||||
|
||||
# Read specific chat
|
||||
wechat-cli history "Alice" --limit 30 --format text
|
||||
|
||||
# Search with filters
|
||||
wechat-cli search "report" --type file --limit 10
|
||||
|
||||
# Monitor for new messages (great for cron/automation)
|
||||
wechat-cli new-messages --format text
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Command Reference
|
||||
|
||||
### `sessions` — Recent Chats
|
||||
|
||||
```bash
|
||||
wechat-cli sessions # Last 20 sessions
|
||||
wechat-cli sessions --limit 10 # Last 10
|
||||
wechat-cli sessions --format text # Human-readable
|
||||
```
|
||||
|
||||
### history — Chat Messages
|
||||
### `history` — Chat Messages
|
||||
|
||||
```bash
|
||||
wechat-cli history "Alice" # Last 50 messages
|
||||
wechat-cli history "Alice" --limit 100 --offset 50
|
||||
wechat-cli history "Team" --start-time "2026-04-01" --end-time "2026-04-03"
|
||||
wechat-cli history "Alice" --type link # Only links/files
|
||||
wechat-cli history "Alice" --type link # Only links
|
||||
wechat-cli history "Alice" --format text
|
||||
```
|
||||
|
||||
**Options:** `--limit`, `--offset`, `--start-time`, `--end-time`, `--type`, `--format`
|
||||
|
||||
### search — Search Messages
|
||||
### `search` — Search Messages
|
||||
|
||||
```bash
|
||||
wechat-cli search "hello" # Global search
|
||||
wechat-cli search "hello" --chat "Alice" # In specific chat
|
||||
wechat-cli search "meeting" --chat "TeamA" --chat "TeamB" # Multiple chats
|
||||
wechat-cli search "report" --type file # Only files
|
||||
wechat-cli search "hello" --start-time "2026-04-01" --limit 50
|
||||
```
|
||||
|
||||
**Options:** `--chat` (repeatable), `--start-time`, `--end-time`, `--limit`, `--offset`, `--type`, `--format`
|
||||
|
||||
### contacts — Contact Search & Details
|
||||
### `contacts` — Contact Search & Details
|
||||
|
||||
```bash
|
||||
wechat-cli contacts --query "Li" # Search contacts
|
||||
wechat-cli contacts --detail "Alice" # View contact details
|
||||
wechat-cli contacts --detail "Alice" # Contact details
|
||||
wechat-cli contacts --detail "wxid_xxx" # By WeChat ID
|
||||
```
|
||||
|
||||
Details include: nickname, remark, WeChat ID (alias), bio, avatar URL, account type.
|
||||
Returns: nickname, remark, WeChat ID, bio, avatar URL, account type.
|
||||
|
||||
### members — Group Members
|
||||
### `members` — Group Members
|
||||
|
||||
```bash
|
||||
wechat-cli members "Team Group" # List all members (JSON)
|
||||
wechat-cli members "Team Group" # All members (JSON)
|
||||
wechat-cli members "Team Group" --format text
|
||||
```
|
||||
|
||||
Shows member list with display names and group owner.
|
||||
|
||||
### stats — Chat Statistics
|
||||
### `stats` — Chat Statistics
|
||||
|
||||
```bash
|
||||
wechat-cli stats "Team Group"
|
||||
@ -123,7 +190,7 @@ wechat-cli stats "Team Group" --format text
|
||||
|
||||
Returns: total messages, type breakdown, top 10 senders, 24-hour activity distribution.
|
||||
|
||||
### export — Export Conversations
|
||||
### `export` — Export Conversations
|
||||
|
||||
```bash
|
||||
wechat-cli export "Alice" --format markdown # To stdout
|
||||
@ -133,7 +200,7 @@ wechat-cli export "Team" --start-time "2026-04-01" --limit 1000
|
||||
|
||||
**Options:** `--format markdown|txt`, `--output`, `--start-time`, `--end-time`, `--limit`
|
||||
|
||||
### favorites — WeChat Bookmarks
|
||||
### `favorites` — WeChat Bookmarks
|
||||
|
||||
```bash
|
||||
wechat-cli favorites # Recent bookmarks
|
||||
@ -143,25 +210,27 @@ wechat-cli favorites --query "machine learning" # Search
|
||||
|
||||
**Types:** text, image, article, card, video
|
||||
|
||||
### unread — Unread Sessions
|
||||
### `unread` — Unread Sessions
|
||||
|
||||
```bash
|
||||
wechat-cli unread # All unread sessions
|
||||
wechat-cli unread --limit 10 --format text
|
||||
```
|
||||
|
||||
### new-messages — Incremental New Messages
|
||||
### `new-messages` — Incremental New Messages
|
||||
|
||||
```bash
|
||||
wechat-cli new-messages # First call: return unread + save state
|
||||
wechat-cli new-messages # First: return unread + save state
|
||||
wechat-cli new-messages # Subsequent: only new since last call
|
||||
```
|
||||
|
||||
State persists at `~/.wechat-cli/last_check.json`. Delete it to reset.
|
||||
State saved at `~/.wechat-cli/last_check.json`. Delete to reset.
|
||||
|
||||
## Message Type Filter
|
||||
---
|
||||
|
||||
The `--type` option (available on `history` and `search`) accepts:
|
||||
## 🔍 Message Type Filter
|
||||
|
||||
The `--type` option (on `history` and `search`):
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
@ -176,69 +245,35 @@ The `--type` option (available on `history` and `search`) accepts:
|
||||
| `call` | Voice/video calls |
|
||||
| `system` | System messages |
|
||||
|
||||
## Use Cases
|
||||
---
|
||||
|
||||
### LLM / AI Tool Integration
|
||||
|
||||
```bash
|
||||
# For Claude Code, Cursor, or any AI tool that can run shell commands
|
||||
wechat-cli sessions --limit 5
|
||||
wechat-cli history "Alice" --limit 20 --format text
|
||||
wechat-cli search "deadline" --chat "Team" --type text
|
||||
```
|
||||
|
||||
All commands output JSON by default, making them ideal for AI agent tool calls.
|
||||
|
||||
### Chat Analysis
|
||||
|
||||
```bash
|
||||
# Who talks the most in a group?
|
||||
wechat-cli stats "Team Group" --format text
|
||||
|
||||
# Find all shared links in a conversation
|
||||
wechat-cli history "Alice" --type link --limit 50
|
||||
|
||||
# Search for a specific file
|
||||
wechat-cli search "report.xlsx" --type file
|
||||
```
|
||||
|
||||
### Data Backup
|
||||
|
||||
```bash
|
||||
# Export important conversations
|
||||
wechat-cli export "Team Group" --format markdown --output team_chat.md
|
||||
wechat-cli export "Alice" --start-time "2026-01-01" --format txt --output alice_2026.txt
|
||||
```
|
||||
|
||||
### Notification Monitoring
|
||||
|
||||
```bash
|
||||
# Cron job to check for new messages every 5 minutes
|
||||
*/5 * * * * wechat-cli new-messages --format text
|
||||
```
|
||||
|
||||
## Platform Support
|
||||
## 🖥️ Platform Support
|
||||
|
||||
| Platform | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| macOS (Apple Silicon) | Supported | Bundled arm64 binary for key extraction |
|
||||
| macOS (Intel) | Supported | x86_64 binary needed |
|
||||
| Windows | Supported | Reads Weixin.exe process memory |
|
||||
| Linux | Supported | Reads /proc/pid/mem, requires root |
|
||||
| macOS (Apple Silicon) | ✅ Supported | Bundled arm64 binary |
|
||||
| macOS (Intel) | ✅ Supported | x86_64 binary needed |
|
||||
| Windows | ✅ Supported | Reads Weixin.exe process memory |
|
||||
| Linux | ✅ Supported | Reads /proc/pid/mem, requires root |
|
||||
|
||||
## How It Works
|
||||
---
|
||||
|
||||
WeChat stores chat data in SQLCipher-encrypted SQLite databases on your local machine. WeChat CLI:
|
||||
## 🔧 How It Works
|
||||
|
||||
1. **Extracts keys** — scans WeChat process memory to find encryption keys (`wechat-cli init`)
|
||||
2. **Decrypts on-the-fly** — transparently decrypts databases with page-level AES-256-CBC + caching
|
||||
3. **Queries locally** — all data stays on your machine, no network access required
|
||||
WeChat stores chat data in SQLCipher-encrypted SQLite databases locally. WeChat CLI:
|
||||
|
||||
## Requirements
|
||||
1. **Extracts keys** — scans WeChat process memory for encryption keys (`init`)
|
||||
2. **Decrypts on-the-fly** — transparent page-level AES-256-CBC decryption with caching
|
||||
3. **Queries locally** — all data stays on your machine, no network access
|
||||
|
||||
- Python >= 3.10
|
||||
- WeChat running locally (for `init` key extraction)
|
||||
---
|
||||
|
||||
## License
|
||||
## 📄 License
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Star History
|
||||
|
||||
[](https://star-history.com/#freestylefly/wechat-cli&Date)
|
||||
|
||||
233
README_CN.md
233
README_CN.md
@ -1,39 +1,51 @@
|
||||
<div align="center">
|
||||
|
||||
# WeChat CLI
|
||||
|
||||
**命令行查询本地微信数据，专为 AI 集成设计。**
|
||||
|
||||
[](https://www.npmjs.com/package/@canghe_ai/wechat-cli)
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
[](https://github.com/freestylefly/wechat-cli)
|
||||
|
||||
聊天记录 · 联系人 · 会话 · 收藏 · 统计 · 导出
|
||||
|
||||
[English](README.md)
|
||||
|
||||
命令行工具，查询本地微信数据——聊天记录、联系人、会话、收藏等。默认 JSON 输出，专为 LLM 集成设计。
|
||||
</div>
|
||||
|
||||
## 功能亮点
|
||||
---
|
||||
|
||||
- **开箱即用** — `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 或纯文本
|
||||
## ✨ 功能亮点
|
||||
|
||||
## 快速开始
|
||||
- **🚀 开箱即用** — `npm install -g` 一键安装，无需 Python
|
||||
- **📦 11 个命令** — sessions、history、search、contacts、members、stats、export、favorites、unread、new-messages、init
|
||||
- **🤖 AI 优先** — 默认 JSON 输出，专为 LLM Agent 工具调用设计
|
||||
- **🔒 全程本地** — SQLCipher 即时解密，数据不出本机
|
||||
- **📊 丰富统计** — 发言排行、消息类型分布、24 小时活跃图
|
||||
- **📝 灵活导出** — Markdown 或纯文本，支持时间范围过滤
|
||||
|
||||
### 安装
|
||||
---
|
||||
|
||||
**通过 pip（需要 Python >= 3.10）：**
|
||||
## 📥 安装
|
||||
|
||||
```bash
|
||||
pip install wechat-cli
|
||||
```
|
||||
|
||||
**通过 npm（独立二进制，无需 Python）：**
|
||||
### npm（推荐）
|
||||
|
||||
```bash
|
||||
npm install -g @canghe_ai/wechat-cli
|
||||
```
|
||||
|
||||
> 目前仅提供 **macOS arm64** 二进制。其他平台（macOS Intel、Linux、Windows）可使用 pip 安装。欢迎提交其他平台的二进制 PR。
|
||||
> 目前提供 **macOS arm64** 二进制。其他平台可使用下方 pip 安装。欢迎提交其他平台二进制 PR。
|
||||
|
||||
或从源码安装：
|
||||
### pip
|
||||
|
||||
```bash
|
||||
pip install wechat-cli
|
||||
```
|
||||
|
||||
需要 Python >= 3.10。
|
||||
|
||||
### 从源码安装
|
||||
|
||||
```bash
|
||||
git clone https://github.com/freestylefly/wechat-cli.git
|
||||
@ -41,7 +53,11 @@ cd wechat-cli
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### 初始化
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 第一步 — 初始化
|
||||
|
||||
确保微信正在运行，然后：
|
||||
|
||||
@ -53,36 +69,90 @@ sudo wechat-cli init
|
||||
wechat-cli init
|
||||
```
|
||||
|
||||
这一步会：
|
||||
1. 自动检测微信数据目录
|
||||
2. 从微信进程内存中提取加密密钥
|
||||
3. 将配置和密钥保存到 `~/.wechat-cli/`
|
||||
这一步会自动检测微信数据目录、提取加密密钥，并保存到 `~/.wechat-cli/`。
|
||||
|
||||
完成后即可使用所有命令。
|
||||
|
||||
## 命令一览
|
||||
|
||||
### sessions — 最近会话
|
||||
### 第二步 — 开始使用
|
||||
|
||||
```bash
|
||||
wechat-cli sessions # 最近 20 个会话 (JSON)
|
||||
wechat-cli sessions # 最近会话
|
||||
wechat-cli history "张三" --limit 20 # 聊天记录
|
||||
wechat-cli search "截止日期" --chat "项目组" # 搜索消息
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤖 AI 工具集成
|
||||
|
||||
WeChat CLI 专为 AI Agent 设计，所有命令默认输出结构化 JSON。
|
||||
|
||||
### Claude Code
|
||||
|
||||
在项目的 `CLAUDE.md` 中添加：
|
||||
|
||||
```markdown
|
||||
## WeChat CLI
|
||||
|
||||
你可以使用 `wechat-cli` 查询我的本地微信数据。
|
||||
|
||||
常用命令：
|
||||
- `wechat-cli sessions --limit 10` — 列出最近会话
|
||||
- `wechat-cli history "名称" --limit 20 --format text` — 读取聊天记录
|
||||
- `wechat-cli search "关键词" --chat "聊天名"` — 搜索消息
|
||||
- `wechat-cli contacts --query "名称"` — 搜索联系人
|
||||
- `wechat-cli unread` — 显示未读会话
|
||||
- `wechat-cli new-messages` — 获取上次以来的新消息
|
||||
- `wechat-cli members "群名"` — 列出群成员
|
||||
- `wechat-cli stats "聊天名" --format text` — 聊天统计
|
||||
```
|
||||
|
||||
然后在对话中可以直接问 Claude：
|
||||
- "帮我看看微信有没有未读消息"
|
||||
- "在项目群里搜索关于截止日期的消息"
|
||||
- "看看这周 AI 群里谁发言最多？"
|
||||
|
||||
### OpenClaw / MCP 集成
|
||||
|
||||
WeChat CLI 兼容任何能执行 shell 命令的 AI 工具：
|
||||
|
||||
```bash
|
||||
# 获取最近会话
|
||||
wechat-cli sessions --limit 5
|
||||
|
||||
# 读取指定聊天
|
||||
wechat-cli history "张三" --limit 30 --format text
|
||||
|
||||
# 带过滤条件搜索
|
||||
wechat-cli search "报告" --type file --limit 10
|
||||
|
||||
# 监控新消息（适合定时任务）
|
||||
wechat-cli new-messages --format text
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 命令一览
|
||||
|
||||
### `sessions` — 最近会话
|
||||
|
||||
```bash
|
||||
wechat-cli sessions # 最近 20 个会话
|
||||
wechat-cli sessions --limit 10 # 最近 10 个
|
||||
wechat-cli sessions --format text # 纯文本输出
|
||||
```
|
||||
|
||||
### history — 聊天记录
|
||||
### `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 "张三" --type link # 只看链接
|
||||
wechat-cli history "张三" --format text
|
||||
```
|
||||
|
||||
**选项：** `--limit`、`--offset`、`--start-time`、`--end-time`、`--type`、`--format`
|
||||
|
||||
### search — 搜索消息
|
||||
### `search` — 搜索消息
|
||||
|
||||
```bash
|
||||
wechat-cli search "Claude" # 全局搜索
|
||||
@ -93,7 +163,7 @@ wechat-cli search "报告" --type file # 只搜文件
|
||||
|
||||
**选项：** `--chat`（可多次指定）、`--start-time`、`--end-time`、`--limit`、`--offset`、`--type`、`--format`
|
||||
|
||||
### contacts — 联系人搜索与详情
|
||||
### `contacts` — 联系人搜索与详情
|
||||
|
||||
```bash
|
||||
wechat-cli contacts --query "李" # 搜索联系人
|
||||
@ -103,16 +173,14 @@ wechat-cli contacts --detail "wxid_xxx" # 通过 wxid 查看
|
||||
|
||||
详情包括：昵称、备注、微信号、个性签名、头像 URL、账号类型。
|
||||
|
||||
### members — 群成员列表
|
||||
### `members` — 群成员列表
|
||||
|
||||
```bash
|
||||
wechat-cli members "AI交流群" # 成员列表 (JSON)
|
||||
wechat-cli members "AI交流群" # 成员列表
|
||||
wechat-cli members "AI交流群" --format text
|
||||
```
|
||||
|
||||
显示成员昵称、wxid、备注和群主。
|
||||
|
||||
### stats — 聊天统计
|
||||
### `stats` — 聊天统计
|
||||
|
||||
```bash
|
||||
wechat-cli stats "AI交流群"
|
||||
@ -120,9 +188,9 @@ wechat-cli stats "张三" --start-time "2026-04-01" --end-time "2026-04-03"
|
||||
wechat-cli stats "AI交流群" --format text
|
||||
```
|
||||
|
||||
返回：消息总数、类型分布、发言 Top 10、24 小时活跃分布（含柱状图）。
|
||||
返回：消息总数、类型分布、发言 Top 10、24 小时活跃分布。
|
||||
|
||||
### export — 导出聊天记录
|
||||
### `export` — 导出聊天记录
|
||||
|
||||
```bash
|
||||
wechat-cli export "张三" --format markdown # 输出到 stdout
|
||||
@ -132,7 +200,7 @@ wechat-cli export "群聊" --start-time "2026-04-01" --limit 1000
|
||||
|
||||
**选项：** `--format markdown|txt`、`--output`、`--start-time`、`--end-time`、`--limit`
|
||||
|
||||
### favorites — 微信收藏
|
||||
### `favorites` — 微信收藏
|
||||
|
||||
```bash
|
||||
wechat-cli favorites # 最近收藏
|
||||
@ -142,14 +210,14 @@ wechat-cli favorites --query "计算机网络" # 搜索收藏
|
||||
|
||||
**类型：** text、image、article、card、video
|
||||
|
||||
### unread — 未读会话
|
||||
### `unread` — 未读会话
|
||||
|
||||
```bash
|
||||
wechat-cli unread # 所有未读会话
|
||||
wechat-cli unread --limit 10 --format text
|
||||
```
|
||||
|
||||
### new-messages — 增量新消息
|
||||
### `new-messages` — 增量新消息
|
||||
|
||||
```bash
|
||||
wechat-cli new-messages # 首次: 返回未读消息 + 保存状态
|
||||
@ -158,7 +226,9 @@ wechat-cli new-messages # 后续: 仅返回上次以来的新
|
||||
|
||||
状态保存在 `~/.wechat-cli/last_check.json`，删除此文件可重置。
|
||||
|
||||
## 消息类型过滤
|
||||
---
|
||||
|
||||
## 🔍 消息类型过滤
|
||||
|
||||
`--type` 选项（适用于 `history` 和 `search`）：
|
||||
|
||||
@ -175,68 +245,35 @@ wechat-cli new-messages # 后续: 仅返回上次以来的新
|
||||
| `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 |
|
||||
| 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 + 缓存
|
||||
1. **提取密钥** — 扫描微信进程内存获取加密密钥（`init`）
|
||||
2. **即时解密** — 透明页级 AES-256-CBC 解密，带缓存
|
||||
3. **本地查询** — 所有数据留在本机，无需网络访问
|
||||
|
||||
## 环境要求
|
||||
---
|
||||
|
||||
- Python >= 3.10
|
||||
- 微信在本地运行（用于 `init` 密钥提取）
|
||||
|
||||
## 开源协议
|
||||
## 📄 开源协议
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Star History
|
||||
|
||||
[](https://star-history.com/#freestylefly/wechat-cli&Date)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user