wechat

---
name: wechat
description: Read WeChat local data from SQLite databases. Supports listing contacts, chat sessions, searching messages, and viewing favorites. Use when the user needs to access their own WeChat data stored locally. Requires access to WeChat data directory. Read-only operations only.
---

# 微信本地数据读取工具

安全读取微信本地 SQLite 数据库，获取联系人、聊天记录、收藏等信息。

⚠️ **重要声明**：本工具**仅读取**本地数据，不会修改任何文件。仅供用户查看自己的微信数据使用。

## 支持平台

- ✅ macOS (通过 ~/Library/Containers/com.tencent.xinWeChat/)
- ⚠️ Windows (通过自定义路径)
- ❌ iOS/Android (无法直接访问本地数据库)

## 前提条件

### 1. 确保微信在电脑上登录过

本工具读取的是电脑版微信的本地数据库文件。

### 2. 权限检查

```bash
# 检查是否有权限访问微信数据目录
ls -la ~/Library/Containers/com.tencent.xinWeChat/
```

如果权限不足，可能需要：
```bash
# 授予终端完全磁盘访问权限
# 系统设置 → 隐私与安全 → 完全磁盘访问权限 → 添加终端
```

## 使用方法

### 列出找到的数据库

```bash
python3 scripts/wechat.py list
```

### 查看联系人列表

```bash
python3 scripts/wechat.py contacts
```

输出示例：
```
👥 联系人列表 (50 个):

序号   昵称/备注              微信号
--------------------------------------------------
1      张三                   zhangsan123
2      李四(同事)             lisi_work
3      家人群                 chatroom_xxx
```

### 查看最近会话

```bash
python3 scripts/wechat.py sessions --limit 20
```

输出示例：
```
💬 最近会话 (20 个):

📌    家人群                  2024-01-15 20:30:15
      💬 [图片]

🔴 5  张三                    2024-01-15 19:45:22
      💬 明天见！
```

### 搜索消息内容

```bash
python3 scripts/wechat.py search "关键词" --limit 50
```

### 查看收藏内容

```bash
python3 scripts/wechat.py favorites --limit 20
```

### 查看统计数据

```bash
python3 scripts/wechat.py stats
```

输出示例：
```
📊 微信数据统计:

📁 contact: /Users/xxx/Library/.../Contact.sqlite
📁 session: /Users/xxx/Library/.../Session.sqlite
📁 chat: /Users/xxx/Library/.../Chat.sqlite

----------------------------------------
👥 联系人数量: 1234
💬 会话数量: 156
📨 消息数量: 45678
⭐ 收藏数量: 89
```

## 命令参考

| 命令 | 功能 | 示例 |
|------|------|------|
| `list` | 列出数据库文件 | `wechat.py list` |
| `contacts` | 联系人列表 | `wechat.py contacts --limit 50` |
| `sessions` | 会话列表 | `wechat.py sessions --limit 20` |
| `search` | 搜索消息 | `wechat.py search "关键词"` |
| `favorites` | 收藏内容 | `wechat.py favorites` |
| `stats` | 统计信息 | `wechat.py stats` |

## 自定义路径

如果微信安装在非默认位置：

```bash
python3 scripts/wechat.py --path /path/to/wechat/data contacts
```

Windows 路径示例：
```bash
python3 scripts/wechat.py --path "C:/Users/用户名/Documents/WeChat Files/" contacts
```

## 数据库说明

| 数据库 | 内容 | 说明 |
|--------|------|------|
| Contact.sqlite | 联系人信息 | 微信号、昵称、备注 |
| Session.sqlite | 会话列表 | 最近聊天、未读消息 |
| Chat.sqlite | 聊天记录 | 消息内容、时间 |
| Favorite.sqlite | 收藏内容 | 收藏的消息、链接、笔记 |
| Brand.sqlite | 公众号 | 关注的公众号信息 |

## 技术说明

- 使用 **SQLite 只读模式** (`mode=ro`) 打开数据库
- 所有操作均为**查询**，不会执行 INSERT/UPDATE/DELETE
- 时间戳为毫秒级 Unix 时间戳，会自动转换为可读格式

## 常见问题

**错误：Permission denied**
→ 授予终端"完全磁盘访问权限"：
   系统设置 → 隐私与安全 → 完全磁盘访问权限 → 添加终端

**错误：未找到数据库文件**
→ 确认微信已登录过，或指定自定义路径 `--path`

**错误：database is locked**
→ 关闭微信后重试（微信运行时可能锁定数据库）

**读取的内容是加密的？**
→ 部分字段可能经过加密，这是微信的安全机制

## 隐私与安全

- ✅ 本工具**只读取**本地数据，不上传任何信息
- ✅ 所有操作在本地完成
- ✅ 需要用户明确授权才能访问数据目录
- ⚠️ 读取的数据包含个人隐私，请妥善保管

## 参考

- 微信数据存储格式基于 SQLite
- 参考文档: [references/api.md](references/api.md)