Agent Skill

微信聊天记录读取与分析

通过 wechat-cli 命令行工具读取和分析本地微信的聊天记录、联系人、收藏等数据。当用户想查看、搜索、导出或分析微信消息时调用此技能。支持 SQLCipher 数据库解密、关键词搜索、聊天统计、增量新消息、多账号切换,以及导出为 Markdown / 单文件 HTML。

数据分析·Water·来自 skill_hub·skillhub.cn ↗
skillhub install @user_514405d2/wechat-cli
4 Stars·9万 综合热度·6,001 字文档·源站更新 2026-11-22

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 旧版不兼容
微信状态提取密钥时必须已启动并登录;纯查询不需要微信运行
Python3.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.jsonnew-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 "群聊记录"

三步流程:

  1. 修复 markdown:每条消息压成单个完整列表项,内部换行转 <br />
  2. pandoc 转换:--standalone --embed-resources,CSS 全内嵌 → 单文件可直接分享/打印

(额外加 -f markdown-citations,否则 @某人 会被解析成引文标记)

  1. 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.pyMarkdown → 排版精美的单文件 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

同分类其他技能

查看全部 ›