微信聊天记录读取与分析
通过 wechat-cli 命令行工具读取和分析本地微信的聊天记录、联系人、收藏等数据。当用户想查看、搜索、导出或分析微信消息时调用此技能。支持 SQLCipher 数据库解密、关键词搜索、聊天统计、增量新消息、多账号切换,以及导出为 Markdown / 单文件 HTML。
skillhub install @user_514405d2/wechat-cli
README 文档
6,001 字WeChat CLI — 微信聊天记录读取与分析
通过 wechat-cli 读取本地微信的聊天记录、联系人、收藏等数据。支持会话浏览、消息搜索、聊天记录导出(Markdown / 纯文本 / 排版精美的 HTML)、统计分析等。
适用场景
- 查看最近会话列表 / 未读消息
- 查看指定联系人或群聊的聊天记录
- 按关键词搜索消息
- 导出聊天记录为 Markdown、纯文本,或排版精美的单文件 HTML
- 聊天统计分析(消息数量、活跃度、发言排行)
- 查看微信收藏
- 获取增量新消息(断点续传)
- 对聊天记录做分类总结、重点提取等分析任务
前置条件
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows(Weixin.exe)/ macOS(WeChat)/ Linux(wechat) |
| 微信版本 | 4.0+(4.1.x 亦支持,见下文密钥提取)。3.x 旧版不兼容 |
| 微信状态 | 提取密钥时必须已启动并登录;纯查询不需要微信运行 |
| Python | 3.10+,且 pip 可用 |
| pandoc | 仅生成 HTML 时需要(脚本会自动查找,不必加入 PATH) |
进程名与数据目录:微信 4.0+ 是
Weixin.exe/xwechat_files;3.x 是WeChat.exe/WeChat Files。
⚠️ 安装:PyPI 上的 wechat-cli 不是这个工具
这是最容易踩的坑。 PyPI 上名为 wechat-cli 的包是另一个同名项目——Frida 注入方案,命令是 setup / doctor / start / chats / messages,且要求微信精确匹配 4.1.15.53,与本技能配套的命令体系完全不同:
pip install wechat-cli # ❌ 装错!这不是本技能用的工具
本技能配套的是 py-wechat-cli(GitHub: jidechao/py-wechat-cli,版本 0.2.4),它未发布到 PyPI,必须从源码安装:
# 1) 若已误装,先卸载
pip uninstall -y wechat-cli
# 2) 克隆源码(GitHub 直连不通时用镜像)
git clone --depth 1 https://github.com/jidechao/py-wechat-cli.git
# 国内镜像示例:
# curl -sL -o py-wechat-cli.zip \
# "https://ghproxy.net/https://github.com/jidechao/py-wechat-cli/archive/refs/heads/main.zip"
# 3) 源码安装
cd py-wechat-cli && pip install .
安装完成后验证:
wechat-cli --version
# 输出: wechat-cli, version 0.2.4
依赖(自动安装):click、pycryptodome、zstandard。
Python 环境隔离提示:在 WorkBuddy / 其他 AI 助手里操作时,务必确认
wechat-cli装在正确的 Python 环境里。若托管环境缺pip,先执行python -m ensurepip --upgrade。找不到命令:
wechat-cli不在 PATH 时,直接用绝对路径调用,例如C:/Users/<你>/.workbuddy/binaries/python/envs/default/Scripts/wechat-cli.exe。
密钥提取(首次必做)
wechat-cli 需要微信数据库的 SQLCipher 密钥才能解密。这一步必须在微信运行时执行。
关键:微信 4.1.12+ 的密钥格式变了
| 版本 | 密钥存放形态 | 能否用 wechat-cli init |
|---|---|---|
| 4.0.x | 明文 raw key 缓存在进程内存,形如 x'<key><salt>' | ✅ 可以 |
| 4.1.12+ | 改存于运行时 com.Tencent.WCDB.Config.Cipher 对象,且整段经过 32 字节循环 XOR 掩码混淆 | ❌ 会 0 命中,属正常现象 |
4.1.12+ 的 blob 固定 99 字节,XOR 解码后形如:
x'<64 hex 密钥><32 hex salt>'
└─ 32 字节 AES-256 密钥,可直接解密,无需 PBKDF2
└─ 16 字节数据库 salt,用于判断密钥属于哪个库
掩码中多数字节为 0x00,所以原始 blob 里能看到零散的真实十六进制字符(例如 a4c8、037)——这是识别掩码混淆的特征。wechat-cli init 内置的扫描器只认 x'...' 明文格式,因此在 4.1.12+ 上必然失败。
正确做法:使用本技能自带的提取脚本
# 先确认微信已登录,然后:
python scripts/extract_keys.py --db-dir "C:/Users/<你>/xwechat_files/<wxid>/db_storage"
脚本会自动:扫描进程内存 → 转储 Config.Cipher blob → XOR 解码 → 按内嵌 salt 定位所属库 → HMAC-SHA512 校验 → 写出 ~/.wechat-cli/all_keys.json。
- 兼容 4.0.x / 4.1.x(XOR 与明文两种形态都会尝试,并含明文回退)
- 校验不通过的密钥不会写入
- 建议以管理员身份运行(读取其他进程内存需要权限)
成功输出示例:
[*] 数据库: 21 个, salt: 21 个
[*] PID=22100 内存区=2053 Config.Cipher 命中=1
[*] 转储 blob: 136 个
[OK] contact\contact.db
...
[*] 校验通过: 21/21
[+] 已写入 21 个密钥 -> ~/.wechat-cli/all_keys.json
配置
~/.wechat-cli/ 下的文件:
| 文件 | 说明 |
|---|---|
config.json | 主配置,至少包含 dbdir 指向目标账号的 dbstorage |
all_keys.json | 各数据库的解密密钥 |
last_check.json | new-messages 的增量状态(记录上次读取位置) |
db_cache.json | 解密数据库缓存索引 |
config.json 最小内容:
{ "db_dir": "C:/Users/<你>/xwechat_files/<wxid>/db_storage" }
多账号:每个账号有独立的
xwechatfiles/<wxid>/dbstorage,而内存里的密钥只属于当前登录账号。切账号需重新运行extractkeys.py并更新config.json的dbdir。密钥会失效:微信重启或版本更新后密钥可能变化,重跑
extract_keys.py即可。纯查询不需要微信运行,只有重新提取密钥时需要。
快速入门
wechat-cli sessions # 最近会话
wechat-cli sessions --limit 10 --format text # 最近 10 个,纯文本
wechat-cli history "张三" --limit 20 # 查看聊天记录
wechat-cli history "AI交流群" --start-time "2026-04-01"
wechat-cli search "关键词" # 全局搜索
wechat-cli search "关键词" --chat "AI交流群" # 指定聊天搜索
wechat-cli contacts --query "李" # 搜索联系人
wechat-cli unread # 未读会话
wechat-cli stats "张三" --format text # 聊天统计
wechat-cli export "张三" --format markdown --output chat.md
导出与排版(本技能提供的增强脚本)
1. 导出为「可读」Markdown
wechat-cli export 的原始输出有三个影响阅读的问题:
- 语音消息原样吐出整段
<msg><voicemsg .../></msg>XML(含aeskey/voiceurl几十字符乱码) - 图片消息带
(local_id=N)后缀,纯噪音 - 头部「时间范围」是占位符
最早 ~ 最新,工具没填
用封装脚本一步搞定:
python scripts/export_markdown.py "某某群" -o output.md
它会导出并清洗(语音 → [语音 6.4秒],图片 → [图片],补齐真实时间范围),同时保留 output.raw.md 原始版。
保留 raw 的意义:
aeskey+voiceurl是解码语音 SILK 音频的凭据。若要还原语音内容,请留好*.raw.md。不想要就加--no-raw。
2. 转成排版精美的单文件 HTML
不要直接 pandoc x.md -o x.html——导出的 markdown 里,多行消息(如收货地址清单)内部含空行,而 markdown 中空行会终止列表项,pandoc 会提前闭合 <ul>,导致后续几十条消息被当成普通段落,列表完全碎片化。
用封装脚本自动处理:
python scripts/md2html.py output.md
# 或指定输出与标题
python scripts/md2html.py output.md -o chat.html --title "群聊记录"
三步流程:
- 修复 markdown:每条消息压成单个完整列表项,内部换行转
<br /> - pandoc 转换:
--standalone --embed-resources,CSS 全内嵌 → 单文件可直接分享/打印
(额外加 -f markdown-citations,否则 @某人 会被解析成引文标记)
- HTML 后处理:注入时间戳/发言人/引用回复/自己/系统消息的样式钩子
排版效果(样式见 assets/chat_style.css):
- 时间戳等宽小字弱化;发言人加粗着色
- 自己发言整条卡片暖色高亮;系统消息虚线边框 + 灰斜体
↳ 回复 某人独立成缩进块- 响应式 + 打印样式(避免卡片跨页断开)
命令总览
| 命令 | 说明 | 常用参数 |
|---|---|---|
init | 提取密钥(微信 4.1.12+ 无效,改用 scripts/extract_keys.py) | --db-dir, --force |
sessions | 最近会话列表 | --limit, --format |
history | 指定聊天的消息记录 | --limit, --offset, --start-time, --end-time, --type, --media |
search | 搜索消息内容 | --chat, --start-time, --end-time, --limit, --type |
contacts | 搜索/列出联系人 | --query, --detail, --limit |
export | 导出聊天记录 | --format, --output, --start-time, --end-time, --limit |
members | 群聊成员列表 | --format |
stats | 聊天统计分析 | --start-time, --end-time, --format |
unread | 未读会话 | --limit, --format |
new-messages | 增量新消息 | --format |
favorites | 微信收藏 | --type, --query, --limit, --format |
本技能附带的脚本
| 脚本 | 用途 |
|---|---|
scripts/extract_keys.py | 密钥提取(4.1.x 兼容,含 XOR 解码) |
scripts/export_markdown.py | 导出 + 清洗为可读 Markdown |
scripts/md2html.py | Markdown → 排版精美的单文件 HTML |
scripts/wcdbkeytool_windows.py | 底层工具(密钥提取 / 数据库解密),含 XOR 掩码常量 |
scripts/dumpconfigblobs.py、gen_keys.py | 早期手动分步流程,已被 extract_keys.py 取代 |
scripts/switch_account.py | 多账号切换(需按需调整路径) |
完整命令参数详见
references/commands.md;消息分析工作流见references/analysis-guide.md。
输出格式
大多数命令支持 --format:
json(默认)— 结构化 JSON,适合程序处理 / LLM 解析text— 纯文本,适合人类阅读
时间格式:YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS
消息类型过滤(--type):text、image、voice、video、sticker、location、link、file、call、system
重要注意事项
- 默认限制:
history默认 50 条,search最大 500 条,sessions默认 20 个。导出大量数据请加--limit 100000 - 系统占位会话:
brandsessionholder、@placeholder_foldgroup是系统占位符,导出时会失败,属正常现象 - 隐私安全:所有数据仅在本地处理,不上传任何信息。
all_keys.json含解密密钥,注意文件权限(脚本会设为0600) - 微信需运行:查询操作不需要,密钥提取必须微信在线
- Windows 终端乱码:若报
UnicodeEncodeError,先chcp 65001并设置PYTHONIOENCODING=utf-8
故障排查
常见问题及解决方案详见 references/troubleshooting.md。高频问题速查:
| 现象 | 原因 | 解决 |
|---|---|---|
wechat-cli --version 显示 0.2.1 且命令是 setup/chats | 装成了 PyPI 同名包 | 卸载后从源码装 py-wechat-cli |
wechat-cli init 显示 0/18 salts matched | 微信 4.1.12+,密钥不在明文内存 | 用 scripts/extract_keys.py |
| 找到 blob 但密钥 0 命中 | 漏了 XOR 解码 | 用本技能的 extract_keys.py(含掩码) |
报 Weixin.exe 未运行 | 微信没开,或用的是 3.x(进程名 WeChat.exe) | 启动微信并登录;确认版本 4.0+ |
| 报无法打开进程 | 权限不足 | 以管理员身份运行 |
| pandoc 转 HTML 后列表碎片化 | 多行消息含空行 | 用 scripts/md2html.py,勿直接 pandoc |
@某人 变成 <span class="citation"> | pandoc 把 @ 当引文 | 转换时加 -f markdown-citations |
| 导出的 HTML 里语音是一堆 XML | 未清洗 | 用 scripts/export_markdown.py |
参考文档
- 完整命令参考
- 消息分析工作流指南
- 常见问题排查
- 第三方组件声明
- 样式资源:assets/chat_style.css
同分类其他技能
查看全部 ›中国金融机构数据爬取与分析综合 Skill v12.1.0。2334家/43大类机构名单、60+财经媒体源舆情、 A股报告/公告/研报、
303 99.4万 MysteelAI - 智能问数我的钢铁网(Mysteel)大宗商品价格行情数据查询技能,基于钢联/隆众数据平台提供专业价格数据服务。覆盖黑色金属、有色金属、能源化工、
9 75万 smart-charts32种图表,3 个主题,2步生成: 1.上传数据 — 将 CSV / Excel / JSON 等格式的数据文件拖入对话框; 2.查看结
149 74.3万 论文配图一键生成论文配图一键生成:一条命令从 JSON/CSV/Excel 生成顶刊级学术图表,科研绘图 与期刊配图全场景覆盖。41 种图表(森林图/K
91 52.8万 smart-chartsIntelligent chart generation and data analysis skill. Reads user-sup
2 37.9万 股票/基金/期货量化分析工具全球智能投研工具(stock-researcher)v14.0:多源数据 + 概率预测 + 批量研究 + 可导出报告。 核心能力: -
152 26.5万