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.
Files changed (36) hide show
  1. wxexport-0.1.0/PKG-INFO +238 -0
  2. wxexport-0.1.0/README.md +223 -0
  3. wxexport-0.1.0/pyproject.toml +27 -0
  4. wxexport-0.1.0/setup.cfg +4 -0
  5. wxexport-0.1.0/src/wxexport/__init__.py +4 -0
  6. wxexport-0.1.0/src/wxexport/__main__.py +6 -0
  7. wxexport-0.1.0/src/wxexport/cli.py +181 -0
  8. wxexport-0.1.0/src/wxexport/config.py +40 -0
  9. wxexport-0.1.0/src/wxexport/crypto/__init__.py +23 -0
  10. wxexport-0.1.0/src/wxexport/crypto/profiles.py +215 -0
  11. wxexport-0.1.0/src/wxexport/export/__init__.py +3 -0
  12. wxexport-0.1.0/src/wxexport/export/exporter.py +155 -0
  13. wxexport-0.1.0/src/wxexport/key/__init__.py +3 -0
  14. wxexport-0.1.0/src/wxexport/key/memory.py +280 -0
  15. wxexport-0.1.0/src/wxexport/key/offsets.json +68 -0
  16. wxexport-0.1.0/src/wxexport/key/store.py +65 -0
  17. wxexport-0.1.0/src/wxexport/media/__init__.py +3 -0
  18. wxexport-0.1.0/src/wxexport/media/resolver.py +346 -0
  19. wxexport-0.1.0/src/wxexport/model/__init__.py +3 -0
  20. wxexport-0.1.0/src/wxexport/model/entities.py +117 -0
  21. wxexport-0.1.0/src/wxexport/model/normalizer.py +325 -0
  22. wxexport-0.1.0/src/wxexport/ops/__init__.py +3 -0
  23. wxexport-0.1.0/src/wxexport/ops/pipeline.py +149 -0
  24. wxexport-0.1.0/src/wxexport/preview/__init__.py +34 -0
  25. wxexport-0.1.0/src/wxexport/preview/index.html +265 -0
  26. wxexport-0.1.0/src/wxexport/schema/__init__.py +3 -0
  27. wxexport-0.1.0/src/wxexport/schema/codec.py +130 -0
  28. wxexport-0.1.0/src/wxexport/schema/wechat3.py +252 -0
  29. wxexport-0.1.0/src/wxexport/source/__init__.py +3 -0
  30. wxexport-0.1.0/src/wxexport/source/discovery.py +154 -0
  31. wxexport-0.1.0/src/wxexport.egg-info/PKG-INFO +238 -0
  32. wxexport-0.1.0/src/wxexport.egg-info/SOURCES.txt +34 -0
  33. wxexport-0.1.0/src/wxexport.egg-info/dependency_links.txt +1 -0
  34. wxexport-0.1.0/src/wxexport.egg-info/entry_points.txt +2 -0
  35. wxexport-0.1.0/src/wxexport.egg-info/requires.txt +3 -0
  36. wxexport-0.1.0/src/wxexport.egg-info/top_level.txt +1 -0
@@ -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)。
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """本地导出微信 3.x 聊天记录为 JSON。"""
2
+
3
+ __version__ = "0.1.0"
4
+ SCHEMA_VERSION = "wxexport/1.0"
@@ -0,0 +1,6 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ sys.exit(main())
@@ -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())