ai_member_only/wechat_msg_crawler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7158422618
wechat_msg_crawler/README_CN.md

345 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div align="center">
# 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)
</div>
---
## ✨ 功能亮点
- **🚀 开箱即用** — `npm install -g` 一键安装，无需 Python
- **📦 11 个命令** — sessions、history、search、contacts、members、stats、export、favorites、unread、new-messages、init
- **🤖 AI 优先** — 默认 JSON 输出，专为 LLM Agent 工具调用设计
- **🔒 全程本地** — SQLCipher 即时解密，数据不出本机
- **📊 丰富统计** — 发言排行、消息类型分布、24 小时活跃图
- **📝 灵活导出** — Markdown 或纯文本，支持时间范围过滤
---
## 📥 安装（给人类看）
AI Agent 请直接移步到“安装（给 Agent 看）”
### npm（推荐）
```bash
npm install -g @canghe_ai/wechat-cli
```
> 目前提供 **macOS arm64** 二进制。其他平台可使用下方 pip 安装。欢迎提交其他平台二进制 PR。
**更新到最新版本：**
```bash
npm update -g @canghe_ai/wechat-cli
```
### pip
```bash
pip install wechat-cli
```
需要 Python >= 3.10。
### 从源码安装
```bash
git clone https://github.com/freestylefly/wechat-cli.git
cd wechat-cli
pip install -e .
```
---
## 📥 安装（给 Agent 看）
直接将在你的 Claude Code 或者 OpenClaw 中输入以下提示即可：
```bash
帮我配置并安装：npm install -g @canghe_ai/wechat-cli
```
比如在 Claude Code 中输入：
![install-claude-code-1](image/install-claude-code-1.png)
注意：请先确保有 node.js 环境。没雨可以让你的 cc 安装环境。
## 🚀 快速开始
### 第一步 — 初始化
确保微信正在运行，然后：
```bash
# macOS/Linux: 可能需要 sudo 权限
sudo wechat-cli init
# Windows: 在有足够权限的终端中运行
wechat-cli init
```
这一步会自动检测微信数据目录、提取加密密钥，并保存到 `~/.wechat-cli/`。
![init-claude-code-1](image/init-claude-code-1.png)
如果是 mac，需要执行 sudo 命令，然后需要输入密码：
![init-claude-code-code-2](image/init-claude-code-2.png)
特别注意，如果你本地有登录微信多个账号，会有多份数据需要你做选择，选择你当前登录的微信账号（默认是第一个）：
![init-claude-code-3](image/init-claude-code-3.png)
这里不确定自己现在的登录微信号，可以找到该文件夹，然后按照修改时间排序，你就可以看到了。（）
![init-claude-code-4](image/init-claude-code-4.png)
#### macOS 遇到 `task_for_pid failed` 错误？
在某些 macOS 系统上，即使使用了 `sudo`，`init` 也可能报 `task_for_pid failed`。这是 macOS 的安全策略限制了进程内存访问。
**WeChat CLI 会自动尝试修复此问题**——对微信重新签名以获取必要权限。按提示操作即可：
1. 工具会自动对微信重新签名
2. 完全退出微信（不是最小化）
3. 重新打开微信并登录
4. 再次执行 `sudo wechat-cli init`
如果自动签名失败，可以手动执行：
```bash
# 先退出微信，然后：
sudo codesign --force --sign - --entitlements /dev/stdin /Applications/WeChat.app <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.get-task-allow</key>
<true/>
</dict>
</plist>
EOF
```
> 注意：如果微信自动更新了，可能需要重新执行签名。
### 第二步 — 开始使用
```bash
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` — 聊天记录
```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交流群" # 成员列表
wechat-cli members "AI交流群" --format text
```
### `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` | 系统消息 |
---
## 🖥️ 平台支持
| 平台 | 状态 | 说明 |
|------|------|------|
| macOS (Apple Silicon) | ✅ 支持 | 内置 arm64 二进制 |
| macOS (Intel) | ✅ 支持 | 需要 x86_64 二进制 |
| Windows | ✅ 支持 | 读取 Weixin.exe 进程内存 |
| Linux | ✅ 支持 | 读取 /proc/pid/mem，需要 root |
---
## 🔧 工作原理
微信将聊天数据存储在本地的 SQLCipher 加密 SQLite 数据库中。WeChat CLI：
1. **提取密钥** — 扫描微信进程内存获取加密密钥（`init`）
2. **即时解密** — 透明页级 AES-256-CBC 解密，带缓存
3. **本地查询** — 所有数据留在本机，无需网络访问
---
## 📄 开源协议
[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)
Reference in New Issue View Git Blame Copy Permalink