微信聊天记录本地导出（wechat-local-reader）
把你自己电脑上登录的微信，变成一个可查询、可导出的本地数据源。
核心能力：解密微信本地数据库 → 读出会话、消息、联系人、群成员、收藏 → 导出成 Markdown / txt → 可选脱敏。
全程在本机完成，没有任何网络请求——工具代码里不存在上传逻辑，聊天数据不出你的电脑。
> 本版为改进版。原始 Skill（slug wechat-local-butler，显示名「微信本地管家」）由 SkillHub 用户「宜生」创作；
> 底层工具 wechat-cli 为 Apache-2.0 开源项目。本版修复了若干 Windows 实测缺陷，说明文档为重新撰写。
> 详细的许可证与归属信息见 tool/NOTICE，Apache-2.0 全文见 tool/README_CN.md「许可证」章节。
一、先确认适用范围
| 环境 | 支持情况 |
|---|---|
| Windows 微信 4.x | ✅ 开箱可用（4.1+ 走只读扫描，无需管理员权限） |
| macOS | ⚠️ SkillHub 禁止上传二进制可执行文件，发布包未内置 helper，需自行编译 find_all_keys_macos.c |
| Linux | ✅ 可用 |
| 手机 / 平板 / 鸿蒙 | ❌ 不支持。数据在 App 沙盒里，没有可扫描的桌面进程 |
只用于读取你本人、本机登录的微信。 拿去读别人的账号是侵犯隐私，责任自负。
二、安装
依赖 Python ≥ 3.10。
# Windows
.\tool\setup.ps1
# macOS / Linux
bash tool/setup.sh
脚本会建 .venv、装依赖、生成 wechat-cli.bat 启动器。
装完把 tool/ 加入 PATH，或用绝对路径调用 tool/wechat-cli.bat。
三、使用流程
第 1 步：提取密钥（只需做一次）
微信电脑版必须已登录且正在运行。
wechat-cli init
成功后密钥存到 ~/.wechat-cli/all_keys.json，之后所有查询都用它解密，不用再登录也不用联网。
什么时候需要重跑：
| 情况 | 要不要重跑 |
|---|---|
| 微信大版本升级 | ✅ wechat-cli init --force |
| 换账号登录 | ✅ 且要换 --db-dir |
| 提示「密钥文件不存在」 | ✅ |
| 日常导出 | ❌ |
第 2 步：看看有哪些会话
wechat-cli sessions --limit 20
这一步是为了拿到准确的群名/联系人名——后面的命令要求名字一字不差，包括全角符号。
第 3 步：导出
wechat-cli export "群名或联系人名" --format markdown --limit 500 --output "D:\导出\xxx.md"
参数：
| 参数 | 说明 |
|---|---|
--format |
markdown 或 txt |
--output |
输出路径；不写就打到屏幕 |
--limit |
条数 |
--start-time / --end-time |
时间区间，YYYY-MM-DD 或带时分秒 |
--mask |
脱敏手机号 / 身份证 / 银行卡 / 邮箱 |
按月份导出：
wechat-cli export "某某群" --start-time "2026-09-01" --end-time "2026-09-30" --output "9月.md"
第 4 步（可选）：清理明文缓存
wechat-cli clean
删掉解密产生的明文副本，不会动微信原始数据。公用电脑上建议用完就清。
四、全部命令
| 命令 | 作用 |
|---|---|
sessions |
最近会话列表 |
history "名字" --limit N |
某会话最近 N 条消息 |
search "关键词" |
全局搜消息内容，可加 --chat 限定在某个群 |
export "名字" |
导出为 md / txt |
new-messages |
自上次调用以来的增量消息 |
contacts --query "李" |
搜联系人 |
members "群名" |
群成员列表 |
stats |
聊天统计 |
unread |
未读会话 |
favorites |
微信收藏 |
clean |
清理解密缓存 |
五、排错
报「0/N salts 找到密钥」——先怀疑账号选错
一台电脑登录过多个微信号时，数据目录下会有多个账号的 db_storage。请先确认当前登录的是哪个账号：
Get-ChildItem "D:\xxx\xwechat_files" -Directory | ForEach-Object {
$db = Join-Path $_.FullName "db_storage"
if (Test-Path $db) {
$r = Get-ChildItem $db -Recurse -File | Sort-Object LastWriteTime -Descending | Select-Object -First 1
$_.Name + " | " + $r.LastWriteTime
}
}
最近有写入、体积最大的那个就是当前账号。然后显式指定：
wechat-cli init --db-dir "D:\xxx\xwechat_files\<当前账号>\db_storage"
> 本改进版已对候选目录按活跃度排序，但仍建议多账号环境显式指定，最稳妥。
提示找不到微信数据目录
微信没运行，或数据目录不在默认位置（被搬过家、改过路径）。用 --db-dir 手动指定。
Windows 下中文输出乱码
PowerShell 捕获 CLI 输出时，默认按 GBK 解码 Python 写出的 UTF-8 字节。调用前加：
$env:PYTHONIOENCODING = "utf-8"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
在 cmd 里直接运行不受影响（CLI 已自动把控制台代码页切到 65001）。
写 bat 脚本要注意
Windows 的 .bat 不能存成 UTF-8——cmd 按 ANSI 逐字节解析，中文会吞掉相邻字符，出现 set 变 et 之类的诡异报错。需要中文交互脚本时，用纯 ASCII 的 .bat 做引导器（powershell -File xxx.ps1），逻辑写在 UTF-8 带 BOM 的 .ps1 里。
解密失败 / 读不到消息
多半是微信升级导致密钥变了，重跑 wechat-cli init --force。
六、导出的内容边界
| 消息类型 | 效果 |
|---|---|
| 文字 | ✅ 完整 |
| 图片 | ⚠️ 只有占位 [图片] (local_id=xxx)，不导出图片文件 |
| 视频 | ⚠️ 输出原始 XML |
| 链接 / 文件 | ⚠️ 多数显示「当前版本不支持展示该内容」 |
| 语音 | ⚠️ 不支持 |
适合：文字内容的归档、整理、总结、日报。
不适合：图片和语音的完整备份。
七、隐私
- 全程本地，无网络上传（已审计：代码中无 http / socket / 上传行为）。
- 但这些文件是明文，别外传、别提交 git、别云同步：
~/.wechat-cli/all_keys.json—— 相当于你聊天库的钥匙~/.wechat-cli/decrypted/和系统临时目录里的解密副本- 任何导出的
.md/.txt - 用完执行
wechat-cli clean。
八、归属与许可
- 核心代码
wechat-cli：上游项目 freestylefly/wechat-cli，Apache License 2.0，全文见tool/README_CN.md「许可证」章节。 - Windows 4.1+ 密钥扫描算法：借鉴自 TANGandXUE/wcdb-key-tool，MIT License，署名保留在
tool/wechat_cli/keys/scanner_windows.py文件头。 - 原始 Skill 作者：SkillHub 用户「宜生」。
- 本改进版的修改清单：见
tool/NOTICE。
再分发时须保留 NOTICE 文件，并确保 Apache-2.0 许可全文随包分发（本包内嵌于 tool/README_CN.md）。
