wxexport 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wxexport-0.1.0/PKG-INFO +238 -0
- wxexport-0.1.0/README.md +223 -0
- wxexport-0.1.0/pyproject.toml +27 -0
- wxexport-0.1.0/setup.cfg +4 -0
- wxexport-0.1.0/src/wxexport/__init__.py +4 -0
- wxexport-0.1.0/src/wxexport/__main__.py +6 -0
- wxexport-0.1.0/src/wxexport/cli.py +181 -0
- wxexport-0.1.0/src/wxexport/config.py +40 -0
- wxexport-0.1.0/src/wxexport/crypto/__init__.py +23 -0
- wxexport-0.1.0/src/wxexport/crypto/profiles.py +215 -0
- wxexport-0.1.0/src/wxexport/export/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/export/exporter.py +155 -0
- wxexport-0.1.0/src/wxexport/key/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/key/memory.py +280 -0
- wxexport-0.1.0/src/wxexport/key/offsets.json +68 -0
- wxexport-0.1.0/src/wxexport/key/store.py +65 -0
- wxexport-0.1.0/src/wxexport/media/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/media/resolver.py +346 -0
- wxexport-0.1.0/src/wxexport/model/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/model/entities.py +117 -0
- wxexport-0.1.0/src/wxexport/model/normalizer.py +325 -0
- wxexport-0.1.0/src/wxexport/ops/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/ops/pipeline.py +149 -0
- wxexport-0.1.0/src/wxexport/preview/__init__.py +34 -0
- wxexport-0.1.0/src/wxexport/preview/index.html +265 -0
- wxexport-0.1.0/src/wxexport/schema/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/schema/codec.py +130 -0
- wxexport-0.1.0/src/wxexport/schema/wechat3.py +252 -0
- wxexport-0.1.0/src/wxexport/source/__init__.py +3 -0
- wxexport-0.1.0/src/wxexport/source/discovery.py +154 -0
- wxexport-0.1.0/src/wxexport.egg-info/PKG-INFO +238 -0
- wxexport-0.1.0/src/wxexport.egg-info/SOURCES.txt +34 -0
- wxexport-0.1.0/src/wxexport.egg-info/dependency_links.txt +1 -0
- wxexport-0.1.0/src/wxexport.egg-info/entry_points.txt +2 -0
- wxexport-0.1.0/src/wxexport.egg-info/requires.txt +3 -0
- wxexport-0.1.0/src/wxexport.egg-info/top_level.txt +1 -0
wxexport-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wxexport
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: 本地导出微信 3.x 聊天记录为 JSON/JSONL
|
|
5
|
+
Author: axiao-boy
|
|
6
|
+
Project-URL: Homepage, https://github.com/axiao-boy/wxexport
|
|
7
|
+
Project-URL: Repository, https://github.com/axiao-boy/wxexport
|
|
8
|
+
Project-URL: Issues, https://github.com/axiao-boy/wxexport/issues
|
|
9
|
+
Keywords: wechat,export,json,backup
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
Requires-Dist: pycryptodome>=3.19
|
|
13
|
+
Requires-Dist: pilk>=0.2
|
|
14
|
+
Requires-Dist: lz4>=4.3
|
|
15
|
+
|
|
16
|
+
# wxexport
|
|
17
|
+
|
|
18
|
+
将本机 **Windows 微信 3.x** 聊天记录导出为 JSON/JSONL,并导出图片、语音、视频、文件和自定义表情,附带本地 HTML 预览。
|
|
19
|
+
|
|
20
|
+
当前实现已在本机 **WeChat 3.9.12.55** 上验证。微信 4.0 的数据目录与密钥结构不同,暂不支持。
|
|
21
|
+
|
|
22
|
+
## 功能
|
|
23
|
+
|
|
24
|
+
- 自动发现微信账号、数据库和客户端版本。
|
|
25
|
+
- 从运行中的微信进程读取数据库密钥,支持 DPAPI 本地缓存和手工密钥。
|
|
26
|
+
- 解密 SQLCipher 数据库,不修改微信原始数据库。
|
|
27
|
+
- 导出文本、图片、语音、视频、文件、表情、链接、引用、转账、红包和系统消息等。
|
|
28
|
+
- 图片 `.dat` 解码、SILK 语音转 WAV、视频与文件导出、自定义表情提取。
|
|
29
|
+
- 每个会话生成 `messages.jsonl`,并生成会话索引和导出清单。
|
|
30
|
+
- 内置本地 HTML 预览,支持会话切换、搜索、分页和附件查看。
|
|
31
|
+
|
|
32
|
+
## 使用前提
|
|
33
|
+
|
|
34
|
+
1. Windows 10/11,Python 3.10+(本机使用 Python 3.11 验证)。
|
|
35
|
+
2. 微信 3.x 已登录并保持运行;自动读取密钥时不要退出微信。
|
|
36
|
+
3. 仅导出本人本机账号数据。请妥善保管导出的明文消息、附件和密钥缓存。
|
|
37
|
+
4. 首次全量导出需要足够磁盘空间:工作目录会保存明文数据库,导出目录会保存 JSON 与附件。
|
|
38
|
+
|
|
39
|
+
## 安装
|
|
40
|
+
|
|
41
|
+
在项目根目录执行:
|
|
42
|
+
|
|
43
|
+
```powershell
|
|
44
|
+
py -3.11 -m venv .venv
|
|
45
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
46
|
+
.\.venv\Scripts\Activate.ps1
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
安装后可直接使用 `wxexport` 命令。依赖为 `pycryptodome`、`pilk` 和 `lz4`。
|
|
50
|
+
|
|
51
|
+
也可以不安装包,直接在项目根目录运行:
|
|
52
|
+
|
|
53
|
+
```powershell
|
|
54
|
+
$env:PYTHONPATH = "$PWD\src"
|
|
55
|
+
python -m pip install pycryptodome pilk lz4
|
|
56
|
+
python -m wxexport detect
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
以下示例均使用安装后的 `wxexport` 命令。
|
|
60
|
+
|
|
61
|
+
## 快速开始
|
|
62
|
+
|
|
63
|
+
### 1. 检测账号与数据库
|
|
64
|
+
|
|
65
|
+
```powershell
|
|
66
|
+
wxexport detect
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
默认扫描 `%USERPROFILE%\Documents\WeChat Files`。有多个账号时,在后续命令中添加:
|
|
70
|
+
|
|
71
|
+
```powershell
|
|
72
|
+
wxexport export --account wxid_xxxxxxxx
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### 2. 全量导出
|
|
76
|
+
|
|
77
|
+
```powershell
|
|
78
|
+
wxexport export
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
默认产物位置:
|
|
82
|
+
|
|
83
|
+
- 工作目录:当前目录下的 `.wxexport`
|
|
84
|
+
- 导出目录:当前目录下的 `export`
|
|
85
|
+
|
|
86
|
+
指定其他位置:
|
|
87
|
+
|
|
88
|
+
```powershell
|
|
89
|
+
wxexport export --work-dir D:\wx-work --out D:\wx-backup
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### 3. 打开 HTML 预览
|
|
93
|
+
|
|
94
|
+
```powershell
|
|
95
|
+
wxexport preview
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
浏览器会打开 `http://127.0.0.1:8765/index.html`。按 `Ctrl+C` 停止服务。
|
|
99
|
+
|
|
100
|
+
```powershell
|
|
101
|
+
# 指定导出目录和端口,不自动打开浏览器
|
|
102
|
+
wxexport preview --out D:\wx-backup --port 9000 --no-browser
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
请通过本地 HTTP 服务打开预览,不要直接双击 `index.html`,否则浏览器可能阻止读取 JSONL。
|
|
106
|
+
|
|
107
|
+
## 常用导出方式
|
|
108
|
+
|
|
109
|
+
```powershell
|
|
110
|
+
# 只导出指定会话:名称、wxid 或会话 ID 需精确匹配
|
|
111
|
+
wxexport export --chat "文件传输助手"
|
|
112
|
+
|
|
113
|
+
# 只导出指定时间之后的消息
|
|
114
|
+
wxexport export --since 2025-01-01
|
|
115
|
+
|
|
116
|
+
# 不导出附件,只导出消息与附件元数据
|
|
117
|
+
wxexport export --no-media
|
|
118
|
+
|
|
119
|
+
# 基于上次状态追加新消息
|
|
120
|
+
wxexport export --incremental
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
注意:
|
|
124
|
+
|
|
125
|
+
- 非增量导出会重建 `--out/conversations`,并使用本次筛选结果重写 `index.json` 和 `manifest.json`。试导出单个会话时,建议使用独立的 `--out`。
|
|
126
|
+
- 增量导出依赖 `--work-dir/state.json`,请保持工作目录和导出目录不变。
|
|
127
|
+
- 已解密数据库按源文件大小和修改时间复用;源库变化后会重新解密。
|
|
128
|
+
- 导出期间微信仍在写入数据。若遇到坏页或结果不完整,可在消息同步较少时重新导出。
|
|
129
|
+
|
|
130
|
+
## 命令与参数
|
|
131
|
+
|
|
132
|
+
| 命令 | 用途 |
|
|
133
|
+
| --- | --- |
|
|
134
|
+
| `wxexport detect` | 发现账号、客户端版本与数据库 |
|
|
135
|
+
| `wxexport keys` | 获取并验证密钥,默认写入 DPAPI 缓存 |
|
|
136
|
+
| `wxexport decrypt` | 只解密数据库,不导出消息 |
|
|
137
|
+
| `wxexport export` | 导出 JSON/JSONL、附件和 HTML 预览页 |
|
|
138
|
+
| `wxexport preview` | 启动本地 HTML 预览服务 |
|
|
139
|
+
|
|
140
|
+
公共参数写在子命令之后:
|
|
141
|
+
|
|
142
|
+
| 参数 | 说明 |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `--wechat-root PATH` | 微信数据根目录,默认 `Documents/WeChat Files` |
|
|
145
|
+
| `--account WXID` | 多账号时指定账号 |
|
|
146
|
+
| `--work-dir PATH` | 密钥缓存、明文库和增量状态目录 |
|
|
147
|
+
| `--out PATH` | 导出目录 |
|
|
148
|
+
| `--key HEX` | 手工指定数据库密钥;微信 3.x 通常为 64 位 hex |
|
|
149
|
+
| `--db-dir PATH` | 直接读取已解密数据库,不再获取密钥 |
|
|
150
|
+
|
|
151
|
+
`export` 额外支持 `--chat`、`--since`、`--no-media`、`--incremental`;`preview` 额外支持 `--port`、`--no-browser`。
|
|
152
|
+
|
|
153
|
+
## 密钥相关
|
|
154
|
+
|
|
155
|
+
自动模式优先按客户端版本从 `WeChatWin.dll` 读取密钥,未知版本会尝试邻域搜索。密钥验证成功后,默认以 Windows DPAPI 加密保存到 `.wxexport/key.bin`,仅当前 Windows 用户可解。
|
|
156
|
+
|
|
157
|
+
```powershell
|
|
158
|
+
# 获取密钥但不写入缓存
|
|
159
|
+
wxexport keys --no-persist
|
|
160
|
+
|
|
161
|
+
# 使用已有密钥
|
|
162
|
+
wxexport export --key <64位hex密钥>
|
|
163
|
+
|
|
164
|
+
# 使用其他工具解密后的数据库
|
|
165
|
+
wxexport export --db-dir D:\plain-db
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`--db-dir` 需要保持账号相对目录结构,例如:
|
|
169
|
+
|
|
170
|
+
```text
|
|
171
|
+
D:\plain-db\
|
|
172
|
+
└─ Msg\
|
|
173
|
+
├─ MicroMsg.db
|
|
174
|
+
└─ Multi\
|
|
175
|
+
├─ MSG0.db
|
|
176
|
+
├─ MediaMSG0.db
|
|
177
|
+
└─ ...
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
安全提示:`wxexport keys` 会在终端显示原始密钥;不要把密钥、`.wxexport` 或导出目录提交到 Git 或发送给他人。
|
|
181
|
+
|
|
182
|
+
## 导出目录结构
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
export\
|
|
186
|
+
├─ index.html # 本地预览页
|
|
187
|
+
├─ index.json # 会话索引
|
|
188
|
+
├─ manifest.json # 导出清单与统计
|
|
189
|
+
└─ conversations\
|
|
190
|
+
└─ <conversation_id>\
|
|
191
|
+
├─ conversation.json # 会话信息、成员与时间范围
|
|
192
|
+
├─ messages.jsonl # 每行一条消息
|
|
193
|
+
└─ media\ # 图片、语音、视频、文件、表情
|
|
194
|
+
|
|
195
|
+
.wxexport\
|
|
196
|
+
├─ key.bin # DPAPI 加密的密钥缓存
|
|
197
|
+
├─ state.json # 增量导出状态
|
|
198
|
+
└─ plain\ # 解密后的数据库
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
附件按内容 SHA-256 命名并去重。消息中的 `attachments[].status` 含义:
|
|
202
|
+
|
|
203
|
+
| 状态 | 含义 |
|
|
204
|
+
| --- | --- |
|
|
205
|
+
| `ok` | 附件已导出 |
|
|
206
|
+
| `partial` | 只找到缩略图,例如视频本体未下载 |
|
|
207
|
+
| `unresolved` | 本机没有对应文件或无法解析,保留已有元数据与原因;已找到的加密原始数据也会保留 |
|
|
208
|
+
| `skipped` | 使用了 `--no-media`,未执行附件导出 |
|
|
209
|
+
|
|
210
|
+
`unresolved` 不一定表示程序错误:微信服务器上存在但本机未下载的图片、语音、视频或表情无法离线恢复。
|
|
211
|
+
|
|
212
|
+
部分自定义表情以 `V1MMWX` 加密封装保存在本机。当前版本会将原始数据保存为 `.v1mmwx` 并标记为 `unresolved`,不会将密文误报为可查看的 GIF;预览页可下载原始数据。明文 GIF、PNG、JPEG 等表情仍正常导出并显示为 `ok`。
|
|
213
|
+
|
|
214
|
+
## 常见问题
|
|
215
|
+
|
|
216
|
+
### 找不到 WeChat.exe
|
|
217
|
+
|
|
218
|
+
请先登录微信并保持运行,再执行 `keys` 或 `export`。
|
|
219
|
+
|
|
220
|
+
### 无法读取进程内存
|
|
221
|
+
|
|
222
|
+
尝试用管理员身份打开 PowerShell 后重试;仍失败时使用 `--key`,或使用 `--db-dir` 导入已解密数据库。
|
|
223
|
+
|
|
224
|
+
### 当前版本无法自动获取密钥
|
|
225
|
+
|
|
226
|
+
版本偏移表之外的客户端会回退到邻域搜索。若仍失败,可手工提供 `--key`。微信 4.0 不在当前支持范围内。
|
|
227
|
+
|
|
228
|
+
### 预览页空白或提示读取失败
|
|
229
|
+
|
|
230
|
+
确认 `export/index.json` 存在,并使用 `wxexport preview` 访问本地地址。若端口被占用,改用 `--port 9000`。
|
|
231
|
+
|
|
232
|
+
### 如何彻底重新导出
|
|
233
|
+
|
|
234
|
+
先停止预览服务,再使用新的 `--out`,或清理旧的导出目录后执行非增量导出。删除 `.wxexport` 会同时删除密钥缓存、明文库和增量状态,下次将重新获取密钥并解密。
|
|
235
|
+
|
|
236
|
+
## 设计文档
|
|
237
|
+
|
|
238
|
+
架构、JSON 规范和版本差异见 [导出微信聊天记录为 JSON:设计方案](docs/导出微信聊天记录为JSON-设计方案.md)。
|
wxexport-0.1.0/README.md
ADDED
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
# wxexport
|
|
2
|
+
|
|
3
|
+
将本机 **Windows 微信 3.x** 聊天记录导出为 JSON/JSONL,并导出图片、语音、视频、文件和自定义表情,附带本地 HTML 预览。
|
|
4
|
+
|
|
5
|
+
当前实现已在本机 **WeChat 3.9.12.55** 上验证。微信 4.0 的数据目录与密钥结构不同,暂不支持。
|
|
6
|
+
|
|
7
|
+
## 功能
|
|
8
|
+
|
|
9
|
+
- 自动发现微信账号、数据库和客户端版本。
|
|
10
|
+
- 从运行中的微信进程读取数据库密钥,支持 DPAPI 本地缓存和手工密钥。
|
|
11
|
+
- 解密 SQLCipher 数据库,不修改微信原始数据库。
|
|
12
|
+
- 导出文本、图片、语音、视频、文件、表情、链接、引用、转账、红包和系统消息等。
|
|
13
|
+
- 图片 `.dat` 解码、SILK 语音转 WAV、视频与文件导出、自定义表情提取。
|
|
14
|
+
- 每个会话生成 `messages.jsonl`,并生成会话索引和导出清单。
|
|
15
|
+
- 内置本地 HTML 预览,支持会话切换、搜索、分页和附件查看。
|
|
16
|
+
|
|
17
|
+
## 使用前提
|
|
18
|
+
|
|
19
|
+
1. Windows 10/11,Python 3.10+(本机使用 Python 3.11 验证)。
|
|
20
|
+
2. 微信 3.x 已登录并保持运行;自动读取密钥时不要退出微信。
|
|
21
|
+
3. 仅导出本人本机账号数据。请妥善保管导出的明文消息、附件和密钥缓存。
|
|
22
|
+
4. 首次全量导出需要足够磁盘空间:工作目录会保存明文数据库,导出目录会保存 JSON 与附件。
|
|
23
|
+
|
|
24
|
+
## 安装
|
|
25
|
+
|
|
26
|
+
在项目根目录执行:
|
|
27
|
+
|
|
28
|
+
```powershell
|
|
29
|
+
py -3.11 -m venv .venv
|
|
30
|
+
.\.venv\Scripts\python.exe -m pip install -e .
|
|
31
|
+
.\.venv\Scripts\Activate.ps1
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
安装后可直接使用 `wxexport` 命令。依赖为 `pycryptodome`、`pilk` 和 `lz4`。
|
|
35
|
+
|
|
36
|
+
也可以不安装包,直接在项目根目录运行:
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
$env:PYTHONPATH = "$PWD\src"
|
|
40
|
+
python -m pip install pycryptodome pilk lz4
|
|
41
|
+
python -m wxexport detect
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
以下示例均使用安装后的 `wxexport` 命令。
|
|
45
|
+
|
|
46
|
+
## 快速开始
|
|
47
|
+
|
|
48
|
+
### 1. 检测账号与数据库
|
|
49
|
+
|
|
50
|
+
```powershell
|
|
51
|
+
wxexport detect
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
默认扫描 `%USERPROFILE%\Documents\WeChat Files`。有多个账号时,在后续命令中添加:
|
|
55
|
+
|
|
56
|
+
```powershell
|
|
57
|
+
wxexport export --account wxid_xxxxxxxx
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### 2. 全量导出
|
|
61
|
+
|
|
62
|
+
```powershell
|
|
63
|
+
wxexport export
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
默认产物位置:
|
|
67
|
+
|
|
68
|
+
- 工作目录:当前目录下的 `.wxexport`
|
|
69
|
+
- 导出目录:当前目录下的 `export`
|
|
70
|
+
|
|
71
|
+
指定其他位置:
|
|
72
|
+
|
|
73
|
+
```powershell
|
|
74
|
+
wxexport export --work-dir D:\wx-work --out D:\wx-backup
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 3. 打开 HTML 预览
|
|
78
|
+
|
|
79
|
+
```powershell
|
|
80
|
+
wxexport preview
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
浏览器会打开 `http://127.0.0.1:8765/index.html`。按 `Ctrl+C` 停止服务。
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
# 指定导出目录和端口,不自动打开浏览器
|
|
87
|
+
wxexport preview --out D:\wx-backup --port 9000 --no-browser
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
请通过本地 HTTP 服务打开预览,不要直接双击 `index.html`,否则浏览器可能阻止读取 JSONL。
|
|
91
|
+
|
|
92
|
+
## 常用导出方式
|
|
93
|
+
|
|
94
|
+
```powershell
|
|
95
|
+
# 只导出指定会话:名称、wxid 或会话 ID 需精确匹配
|
|
96
|
+
wxexport export --chat "文件传输助手"
|
|
97
|
+
|
|
98
|
+
# 只导出指定时间之后的消息
|
|
99
|
+
wxexport export --since 2025-01-01
|
|
100
|
+
|
|
101
|
+
# 不导出附件,只导出消息与附件元数据
|
|
102
|
+
wxexport export --no-media
|
|
103
|
+
|
|
104
|
+
# 基于上次状态追加新消息
|
|
105
|
+
wxexport export --incremental
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
注意:
|
|
109
|
+
|
|
110
|
+
- 非增量导出会重建 `--out/conversations`,并使用本次筛选结果重写 `index.json` 和 `manifest.json`。试导出单个会话时,建议使用独立的 `--out`。
|
|
111
|
+
- 增量导出依赖 `--work-dir/state.json`,请保持工作目录和导出目录不变。
|
|
112
|
+
- 已解密数据库按源文件大小和修改时间复用;源库变化后会重新解密。
|
|
113
|
+
- 导出期间微信仍在写入数据。若遇到坏页或结果不完整,可在消息同步较少时重新导出。
|
|
114
|
+
|
|
115
|
+
## 命令与参数
|
|
116
|
+
|
|
117
|
+
| 命令 | 用途 |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `wxexport detect` | 发现账号、客户端版本与数据库 |
|
|
120
|
+
| `wxexport keys` | 获取并验证密钥,默认写入 DPAPI 缓存 |
|
|
121
|
+
| `wxexport decrypt` | 只解密数据库,不导出消息 |
|
|
122
|
+
| `wxexport export` | 导出 JSON/JSONL、附件和 HTML 预览页 |
|
|
123
|
+
| `wxexport preview` | 启动本地 HTML 预览服务 |
|
|
124
|
+
|
|
125
|
+
公共参数写在子命令之后:
|
|
126
|
+
|
|
127
|
+
| 参数 | 说明 |
|
|
128
|
+
| --- | --- |
|
|
129
|
+
| `--wechat-root PATH` | 微信数据根目录,默认 `Documents/WeChat Files` |
|
|
130
|
+
| `--account WXID` | 多账号时指定账号 |
|
|
131
|
+
| `--work-dir PATH` | 密钥缓存、明文库和增量状态目录 |
|
|
132
|
+
| `--out PATH` | 导出目录 |
|
|
133
|
+
| `--key HEX` | 手工指定数据库密钥;微信 3.x 通常为 64 位 hex |
|
|
134
|
+
| `--db-dir PATH` | 直接读取已解密数据库,不再获取密钥 |
|
|
135
|
+
|
|
136
|
+
`export` 额外支持 `--chat`、`--since`、`--no-media`、`--incremental`;`preview` 额外支持 `--port`、`--no-browser`。
|
|
137
|
+
|
|
138
|
+
## 密钥相关
|
|
139
|
+
|
|
140
|
+
自动模式优先按客户端版本从 `WeChatWin.dll` 读取密钥,未知版本会尝试邻域搜索。密钥验证成功后,默认以 Windows DPAPI 加密保存到 `.wxexport/key.bin`,仅当前 Windows 用户可解。
|
|
141
|
+
|
|
142
|
+
```powershell
|
|
143
|
+
# 获取密钥但不写入缓存
|
|
144
|
+
wxexport keys --no-persist
|
|
145
|
+
|
|
146
|
+
# 使用已有密钥
|
|
147
|
+
wxexport export --key <64位hex密钥>
|
|
148
|
+
|
|
149
|
+
# 使用其他工具解密后的数据库
|
|
150
|
+
wxexport export --db-dir D:\plain-db
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`--db-dir` 需要保持账号相对目录结构,例如:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
D:\plain-db\
|
|
157
|
+
└─ Msg\
|
|
158
|
+
├─ MicroMsg.db
|
|
159
|
+
└─ Multi\
|
|
160
|
+
├─ MSG0.db
|
|
161
|
+
├─ MediaMSG0.db
|
|
162
|
+
└─ ...
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
安全提示:`wxexport keys` 会在终端显示原始密钥;不要把密钥、`.wxexport` 或导出目录提交到 Git 或发送给他人。
|
|
166
|
+
|
|
167
|
+
## 导出目录结构
|
|
168
|
+
|
|
169
|
+
```text
|
|
170
|
+
export\
|
|
171
|
+
├─ index.html # 本地预览页
|
|
172
|
+
├─ index.json # 会话索引
|
|
173
|
+
├─ manifest.json # 导出清单与统计
|
|
174
|
+
└─ conversations\
|
|
175
|
+
└─ <conversation_id>\
|
|
176
|
+
├─ conversation.json # 会话信息、成员与时间范围
|
|
177
|
+
├─ messages.jsonl # 每行一条消息
|
|
178
|
+
└─ media\ # 图片、语音、视频、文件、表情
|
|
179
|
+
|
|
180
|
+
.wxexport\
|
|
181
|
+
├─ key.bin # DPAPI 加密的密钥缓存
|
|
182
|
+
├─ state.json # 增量导出状态
|
|
183
|
+
└─ plain\ # 解密后的数据库
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
附件按内容 SHA-256 命名并去重。消息中的 `attachments[].status` 含义:
|
|
187
|
+
|
|
188
|
+
| 状态 | 含义 |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| `ok` | 附件已导出 |
|
|
191
|
+
| `partial` | 只找到缩略图,例如视频本体未下载 |
|
|
192
|
+
| `unresolved` | 本机没有对应文件或无法解析,保留已有元数据与原因;已找到的加密原始数据也会保留 |
|
|
193
|
+
| `skipped` | 使用了 `--no-media`,未执行附件导出 |
|
|
194
|
+
|
|
195
|
+
`unresolved` 不一定表示程序错误:微信服务器上存在但本机未下载的图片、语音、视频或表情无法离线恢复。
|
|
196
|
+
|
|
197
|
+
部分自定义表情以 `V1MMWX` 加密封装保存在本机。当前版本会将原始数据保存为 `.v1mmwx` 并标记为 `unresolved`,不会将密文误报为可查看的 GIF;预览页可下载原始数据。明文 GIF、PNG、JPEG 等表情仍正常导出并显示为 `ok`。
|
|
198
|
+
|
|
199
|
+
## 常见问题
|
|
200
|
+
|
|
201
|
+
### 找不到 WeChat.exe
|
|
202
|
+
|
|
203
|
+
请先登录微信并保持运行,再执行 `keys` 或 `export`。
|
|
204
|
+
|
|
205
|
+
### 无法读取进程内存
|
|
206
|
+
|
|
207
|
+
尝试用管理员身份打开 PowerShell 后重试;仍失败时使用 `--key`,或使用 `--db-dir` 导入已解密数据库。
|
|
208
|
+
|
|
209
|
+
### 当前版本无法自动获取密钥
|
|
210
|
+
|
|
211
|
+
版本偏移表之外的客户端会回退到邻域搜索。若仍失败,可手工提供 `--key`。微信 4.0 不在当前支持范围内。
|
|
212
|
+
|
|
213
|
+
### 预览页空白或提示读取失败
|
|
214
|
+
|
|
215
|
+
确认 `export/index.json` 存在,并使用 `wxexport preview` 访问本地地址。若端口被占用,改用 `--port 9000`。
|
|
216
|
+
|
|
217
|
+
### 如何彻底重新导出
|
|
218
|
+
|
|
219
|
+
先停止预览服务,再使用新的 `--out`,或清理旧的导出目录后执行非增量导出。删除 `.wxexport` 会同时删除密钥缓存、明文库和增量状态,下次将重新获取密钥并解密。
|
|
220
|
+
|
|
221
|
+
## 设计文档
|
|
222
|
+
|
|
223
|
+
架构、JSON 规范和版本差异见 [导出微信聊天记录为 JSON:设计方案](docs/导出微信聊天记录为JSON-设计方案.md)。
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wxexport"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "本地导出微信 3.x 聊天记录为 JSON/JSONL"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
authors = [{ name = "axiao-boy" }]
|
|
12
|
+
keywords = ["wechat", "export", "json", "backup"]
|
|
13
|
+
dependencies = ["pycryptodome>=3.19", "pilk>=0.2", "lz4>=4.3"]
|
|
14
|
+
|
|
15
|
+
[project.urls]
|
|
16
|
+
Homepage = "https://github.com/axiao-boy/wxexport"
|
|
17
|
+
Repository = "https://github.com/axiao-boy/wxexport"
|
|
18
|
+
Issues = "https://github.com/axiao-boy/wxexport/issues"
|
|
19
|
+
|
|
20
|
+
[project.scripts]
|
|
21
|
+
wxexport = "wxexport.cli:main"
|
|
22
|
+
|
|
23
|
+
[tool.setuptools.packages.find]
|
|
24
|
+
where = ["src"]
|
|
25
|
+
|
|
26
|
+
[tool.setuptools.package-data]
|
|
27
|
+
wxexport = ["preview/*.html", "key/offsets.json"]
|
wxexport-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
import json
|
|
5
|
+
import sys
|
|
6
|
+
from datetime import datetime
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from .config import Settings, default_export_dir, default_wechat_root, default_work_dir
|
|
10
|
+
from .export import Exporter
|
|
11
|
+
from .media import MediaResolver
|
|
12
|
+
from .ops.pipeline import prepare, resolve_account
|
|
13
|
+
from .preview import serve, write_preview
|
|
14
|
+
from .source.discovery import discover
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _common() -> argparse.ArgumentParser:
|
|
18
|
+
parser = argparse.ArgumentParser(add_help=False)
|
|
19
|
+
parser.add_argument("--wechat-root", type=Path, default=default_wechat_root(),
|
|
20
|
+
help="微信数据根目录(默认 Documents/WeChat Files)")
|
|
21
|
+
parser.add_argument("--account", help="账号 wxid,多个账号时必填")
|
|
22
|
+
parser.add_argument("--work-dir", type=Path, default=default_work_dir(),
|
|
23
|
+
help="工作目录(密钥缓存、明文库)")
|
|
24
|
+
parser.add_argument("--out", type=Path, default=default_export_dir(),
|
|
25
|
+
help="导出目录")
|
|
26
|
+
parser.add_argument("--key", dest="key_hex", help="手工指定 32/64 位 hex 密钥")
|
|
27
|
+
parser.add_argument("--db-dir", type=Path, help="已解密数据库目录(相对账号根结构)")
|
|
28
|
+
return parser
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
32
|
+
parser = argparse.ArgumentParser(
|
|
33
|
+
prog="wxexport", description="本地导出微信 3.x 聊天记录为 JSON"
|
|
34
|
+
)
|
|
35
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
36
|
+
|
|
37
|
+
sub.add_parser("detect", parents=[_common()], help="发现账号与数据库")
|
|
38
|
+
|
|
39
|
+
keys = sub.add_parser("keys", parents=[_common()], help="从微信进程内存获取密钥")
|
|
40
|
+
keys.add_argument("--no-persist", action="store_true", help="不写入 DPAPI 缓存")
|
|
41
|
+
|
|
42
|
+
sub.add_parser("decrypt", parents=[_common()], help="解密数据库到工作目录")
|
|
43
|
+
|
|
44
|
+
export = sub.add_parser("export", parents=[_common()], help="导出为 JSON/JSONL")
|
|
45
|
+
export.add_argument("--chat", help="只导出指定会话(名称 / wxid / 会话 ID)")
|
|
46
|
+
export.add_argument("--since", help="起始日期,如 2024-01-01")
|
|
47
|
+
export.add_argument("--no-media", action="store_true", help="不导出附件")
|
|
48
|
+
export.add_argument("--incremental", action="store_true", help="增量导出")
|
|
49
|
+
|
|
50
|
+
preview = sub.add_parser("preview", parents=[_common()], help="本地预览已导出数据")
|
|
51
|
+
preview.add_argument("--port", type=int, default=8765)
|
|
52
|
+
preview.add_argument("--no-browser", action="store_true")
|
|
53
|
+
return parser
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _settings(args) -> Settings:
|
|
57
|
+
return Settings(
|
|
58
|
+
wechat_root=args.wechat_root,
|
|
59
|
+
work_dir=args.work_dir,
|
|
60
|
+
export_dir=args.out,
|
|
61
|
+
account=args.account,
|
|
62
|
+
key_hex=args.key_hex,
|
|
63
|
+
db_dir=args.db_dir,
|
|
64
|
+
only_chat=getattr(args, "chat", None),
|
|
65
|
+
since=_parse_since(getattr(args, "since", None)),
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _parse_since(value: str | None) -> int | None:
|
|
70
|
+
if not value:
|
|
71
|
+
return None
|
|
72
|
+
if value.isdigit():
|
|
73
|
+
return int(value)
|
|
74
|
+
try:
|
|
75
|
+
return int(datetime.fromisoformat(value).timestamp())
|
|
76
|
+
except ValueError:
|
|
77
|
+
raise SystemExit(f"无法解析日期:{value}")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def cmd_detect(args) -> int:
|
|
81
|
+
accounts = discover(args.wechat_root)
|
|
82
|
+
if not accounts:
|
|
83
|
+
print(f"未在 {args.wechat_root} 发现微信数据")
|
|
84
|
+
return 1
|
|
85
|
+
for account in accounts:
|
|
86
|
+
info = account.summary()
|
|
87
|
+
print(json.dumps(info, ensure_ascii=False, indent=2))
|
|
88
|
+
return 0
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def cmd_keys(args) -> int:
|
|
92
|
+
settings = _settings(args)
|
|
93
|
+
settings.ensure_dirs()
|
|
94
|
+
account = resolve_account(settings)
|
|
95
|
+
prepared = prepare(settings, persist_key=not args.no_persist)
|
|
96
|
+
print(json.dumps(
|
|
97
|
+
{"wxid": account.wxid, "profile": prepared.profile, "key": prepared.key_hex},
|
|
98
|
+
ensure_ascii=False, indent=2,
|
|
99
|
+
))
|
|
100
|
+
print("提示:密钥已写入 DPAPI 缓存,仅当前 Windows 用户可解")
|
|
101
|
+
prepared.schema.close()
|
|
102
|
+
return 0
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def cmd_decrypt(args) -> int:
|
|
106
|
+
settings = _settings(args)
|
|
107
|
+
prepared = prepare(settings)
|
|
108
|
+
print(f"明文库目录:{prepared.plain_root}")
|
|
109
|
+
prepared.schema.close()
|
|
110
|
+
return 0
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def cmd_export(args) -> int:
|
|
114
|
+
settings = _settings(args)
|
|
115
|
+
settings.ensure_dirs()
|
|
116
|
+
prepared = prepare(settings)
|
|
117
|
+
account = prepared.account
|
|
118
|
+
schema = prepared.schema
|
|
119
|
+
|
|
120
|
+
print("读取会话列表……")
|
|
121
|
+
conversations = schema.conversations(since=settings.since)
|
|
122
|
+
if settings.only_chat:
|
|
123
|
+
needle = settings.only_chat.lower()
|
|
124
|
+
conversations = [
|
|
125
|
+
c for c in conversations
|
|
126
|
+
if needle in {c.name.lower(), c.username.lower(), c.id.lower()}
|
|
127
|
+
]
|
|
128
|
+
if not conversations:
|
|
129
|
+
raise SystemExit(f"未找到会话:{settings.only_chat}")
|
|
130
|
+
print(f"待导出会话:{len(conversations)}")
|
|
131
|
+
|
|
132
|
+
resolver = MediaResolver(
|
|
133
|
+
account.root, settings.export_dir, schema, enabled=not args.no_media
|
|
134
|
+
)
|
|
135
|
+
exporter = Exporter(
|
|
136
|
+
account, schema, settings.export_dir, resolver,
|
|
137
|
+
settings.work_dir / "state.json", incremental=args.incremental,
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
def progress(index: int, total: int, conv, count: int) -> None:
|
|
141
|
+
print(f"[{index}/{total}] {conv.name}:{count} 条")
|
|
142
|
+
|
|
143
|
+
manifest = exporter.run(conversations, progress=progress)
|
|
144
|
+
write_preview(settings.export_dir)
|
|
145
|
+
schema.close()
|
|
146
|
+
|
|
147
|
+
stats = manifest["stats"]
|
|
148
|
+
print(json.dumps({
|
|
149
|
+
"export_dir": str(settings.export_dir),
|
|
150
|
+
"conversations": stats["conversations"],
|
|
151
|
+
"messages": stats["messages"],
|
|
152
|
+
"attachments_ok": stats["attachments_ok"],
|
|
153
|
+
"attachments_unresolved": stats["attachments_unresolved"],
|
|
154
|
+
}, ensure_ascii=False, indent=2))
|
|
155
|
+
print("完成。运行 `wxexport preview` 打开本地预览。")
|
|
156
|
+
return 0
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def cmd_preview(args) -> int:
|
|
160
|
+
export_root = args.out
|
|
161
|
+
if not (export_root / "index.json").exists():
|
|
162
|
+
raise SystemExit(f"{export_root} 中没有导出数据,请先运行 export")
|
|
163
|
+
write_preview(export_root)
|
|
164
|
+
serve(export_root, port=args.port, open_browser=not args.no_browser)
|
|
165
|
+
return 0
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def main(argv: list[str] | None = None) -> int:
|
|
169
|
+
args = build_parser().parse_args(argv)
|
|
170
|
+
handlers = {
|
|
171
|
+
"detect": cmd_detect,
|
|
172
|
+
"keys": cmd_keys,
|
|
173
|
+
"decrypt": cmd_decrypt,
|
|
174
|
+
"export": cmd_export,
|
|
175
|
+
"preview": cmd_preview,
|
|
176
|
+
}
|
|
177
|
+
return handlers[args.command](args)
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
if __name__ == "__main__":
|
|
181
|
+
sys.exit(main())
|