diff --git a/README.md b/README.md index 7aa1f39..f234043 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,51 @@ +
+ # WeChat CLI +**Query your local WeChat data from the command line.** + +[![npm version](https://img.shields.io/npm/v/@canghe_ai/wechat-cli.svg)](https://www.npmjs.com/package/@canghe_ai/wechat-cli) +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg)](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. +
-## 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 + +[![Star History Chart](https://api.star-history.com/svg?repos=freestylefly/wechat-cli&type=Date)](https://star-history.com/#freestylefly/wechat-cli&Date) diff --git a/README_CN.md b/README_CN.md index 569fa3d..b91aa35 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,39 +1,51 @@ +
+ # WeChat CLI +**命令行查询本地微信数据，专为 AI 集成设计。** + +[![npm version](https://img.shields.io/npm/v/@canghe_ai/wechat-cli.svg)](https://www.npmjs.com/package/@canghe_ai/wechat-cli) +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg)](https://github.com/freestylefly/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 或纯文本 +## ✨ 功能亮点 -## 快速开始 +- **🚀 开箱即用** — `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 + +[![Star History Chart](https://api.star-history.com/svg?repos=freestylefly/wechat-cli&type=Date)](https://star-history.com/#freestylefly/wechat-cli&Date)