wechat-ai-history
把本机微信 4.x 的聊天记录，变成 AI 可以直接调用的能力。
密钥提取 → 数据库解密 → MCP server → Agent Skill，全链路本地只读。
这是什么
一句话：在你的电脑上，给 AI 装上一双能读微信的眼睛。
以前想把群里的一段记录给 AI，你得截图、复制、粘贴，格式全乱、上下文丢一半。 现在一句话就行，而且 AI 拿到的是结构化的、带时间戳和发送者的原文。
| 能力 | 说明 |
|---|---|
| 列会话 / 找群 | 列出全部会话和群，直接给群名和 wxid |
| 读某个群 | 支持全部历史，不只是最近 7 天 |
| 全文搜索 | 跨多个消息分片库检索，百万条消息随便搜 |
| 摘要 / 系统事件 | 撤回、转账、拍一拍、进群退群等独立入口 |
这东西是给谁用的？
能力是通用的，数据是你自己的。 三层作用域说清楚：
| 层 | 换账号 / 换电脑还成立吗 | 说明 |
|---|---|---|
| 技术内核（提 key、解密、zstd、XML 解析、搜索、MCP、Skill） | ✅ 完全成立 | 与「谁的微信」无关。任何 Windows 机器 + 任何微信 4.x 账号，跑同一套流程 |
| 密钥 | 🔁 一号一钥匙 | raw key 按账号派生，一把 key 只开得了它所属的账号。换账号就重跑一次「提 key → 解密」，代码一行不改 |
| 明文库 / 导出产物 | ❌ 不迁移 | 只属于这台机器这个账号。已全部 .gitignore，从未进仓库 |
换账号不用改代码：密钥自己会认账号。decrypt_all.py 会拿 key 逐个探测数据根下的所有账号目录，
只解开能打开的那一个——不会像「按文件修改时间猜活跃账号」那样在多账号机器上选错。
想锁定某个账号：--account <目录名或wxid>，或设环境变量 WECHAT_ACCOUNT。
仓库里不含任何真实账号 id、群 id、路径或聊天内容。已用测试锁死 （
tests/test_account_portability.py）：源码里出现具体 wxid 或机器专属路径，测试直接失败。
为什么现成工具都不行
| 方案 | 卡在哪 |
|---|---|
| 微信官方 | 没有导出接口，备份是加密的、换机就废 |
| 常规「内存扫密钥」 | 微信 4.x 把 OpenSSL 全静态链接进 DLL，扫 8773 个导出符号没有 PBKDF2/HMAC/sqlite3_key 可钩 |
| WeFlow | 做得很全，但 README 明说「依赖自定义的原生解密组件，需自行设计」——这块留空了 |
| wx-cli | 只认 ~/Documents/xwechat_files，认不出自定义数据路径 |
本仓库填的就是那块空。
快速开始（全新 Windows 电脑）
git clone https://github.com/nanlis/wechat-ai-history.git
cd wechat-ai-history
bash install.sh
安装脚本会自动完成：探测 Python → 探测微信 → 探测数据目录 → 建 venv 装依赖 → 创建目录联接 → 注册 MCP server → 安装 Skill 到各运行时。
换一台新电脑意味着什么
这套东西的形态是仓库 + 本地能力，不是打包好的 exe。所以「换机」这件事 要拆成两块看：
| 要带走的东西 | 换机后怎么办 | 说明 |
|---|---|---|
| 代码与知识（解析器、MCP、Skill、测试） | git clone 一条命令 |
全部在 GitHub 上，零成本带走 |
| 密钥（能解密数据库的那把钥匙） | 必须重新提取 | 密钥与设备绑定，不是文件拷贝能解决的 |
| 明文数据库（115 万条聊天记录） | 重新解密生成 | 一次操作，几分钟 |
| AI 客户端配置（MCP + Skill） | install.sh 自动重写 |
指向新机器的真实路径 |
也就是说：换电脑要重跑一次「提密钥 → 解密」，但不用重写任何一行代码。
新机器上的完整流程：
git clone https://github.com/nanlis/wechat-ai-history.git
cd wechat-ai-history
bash install.sh # 自动探测，装依赖、注册 MCP 和 Skill
# 启动微信并登录一次
bash scripts/windows/refresh_key.sh # 提密钥 + 解密全部库
装完之后在这台新电脑上，AI 拿到的仍然是完整能力： 读群、翻历史、全文搜索、导出、看系统事件 —— 数据是这台电脑上这个微信账号的。
关于「不用再装一遍」
install.sh 是幂等的，可以重跑。它会：
- 探测 Python / 微信 / 数据目录，探测不到才问你
- 已存在的 venv 跳过，已有的联接识别为「就绪」
- 旧版本留下的空目录自动备份后重建（不会卡住）
- 用目录联接把整个仓库挂成 Skill，保证
references/手册页和scripts/运行时脚本都能被 AI 读到（只复制一个 SKILL.md 是不够的）
装完先跑一次只读体检：
.venv/Scripts/python.exe scripts/common/doctor.py --json
它会告诉你：密钥在不在、库能不能读、MCP 有没有注册、Skill 有没有装对。
前置条件
| 项 | 要求 |
|---|---|
| 操作系统 | Windows 10+ x64 |
| 微信 | 4.0 及以上（4.1.x 已验证） |
| Python | 3.11+（frida 17 要求；3.13 已验证） |
| 终端 | Git Bash 以管理员身份运行（读微信进程内存需要） |
| 磁盘 | ≥3 GB（明文库约为主库的 1.3 倍） |
| 网络 | 仅安装依赖与克隆仓库时需要，运行期全程离线 |
关于数据目录
脚本会自动探测以下常见位置，探测不到会交互式询问：
C:\Users\<你>\Documents\xwechat_files # 微信默认
D:\WeChatData\xwechat_files # 数据目录被挪到别的盘
E:\Chat\xwechat_files
也可以显式指定（Windows 或 Git Bash 两种写法都接受）：
bash install.sh "D:\WeChatData\xwechat_files"
bash install.sh /d/WeChatData/xwechat_files
然后三步
# 1. 从桌面双击启动微信并登录
# （登录会重新派生数据库密钥 —— 这是提取密钥的唯一可靠时机）
# 2. 提取密钥 + 解密全部数据库
bash scripts/windows/refresh_key.sh
# 3. 在 WorkBuddy / Claude Code 里点一次「信任」wechat-local
# （连接器管理页 → 右上角自定义连接器入口）
之后直接说：
「把 XX 群的记录发给我」
「搜一下我微信里关于 XX 的聊天」
架构
AI 客户端 WorkBuddy · Claude Code · Codex
↓
Skill skill/SKILL.md —— 教 AI 何时调、怎么调、有哪些坑
↓
MCP Server server.py —— 7 个工具，stdio，本地
↓
内核 scripts/windows/ —— 提密 → 解密 → 查询
↓
数据 微信本地数据目录（SQLCipher 4 加密）
三层缺一不可：只有 Skill，AI 每次要现拼命令；只有 MCP，AI 不知道工具存在；只有内核，那只是脚本，不是能力。
核心突破：怎么拿到密钥
微信 4.x 把 OpenSSL 全部静态链接进 DLL，没有任何可钩的导出符号。 最终方案是钩 SHA-512 压缩函数，从 HMAC 内层的 ipad 块还原明文 key：
HMAC 内层：ipad = key ⊕ 0x36
→ 抓到 ipad，XOR 回 0x36 即得明文 key
三个必须同时满足的条件（换版本会踩的坑）：
- 钩全部模块 —— 只钩
Weixin.dll会抓到 TLS 的 HMAC 假货 - 候选落盘再离线验证 —— 在线验证会漏，4 个 TLS 假货就是这么混进来的
- 微信登录那一刻 —— SQLCipher 只在首次打开某个库时派生密钥
SQLCipher 4 参数
enc = PBKDF2-HMAC-SHA512(raw_key, db_salt, 256000, 32) # 每库独立
mack = PBKDF2-HMAC-SHA512(enc, db_salt ^ 0x3A, 2, 32)
AES-256-CBC · page 4096 · reserve 80
工具清单
| 脚本 | 作用 |
|---|---|
scripts/windows/hook_raw_key_broad.py |
钩全部模块，捕获并落盘密钥候选 |
scripts/windows/decrypt_stream.py |
流式解密（676MB 主库 8 秒，避免 MemoryError） |
scripts/windows/decrypt_all.py |
全量解密 |
scripts/windows/wxread.py |
列会话 / 读群 / 搜索 / 导出 txt |
scripts/windows/refresh_key.sh |
一键提密钥 + 重解密 |
scripts/windows/find_k1.py |
内存中定位单库的派生密钥 |
scripts/windows/find_ctx.py |
按 kdf_iter=256000 常量定位 SQLCipher ctx |
scripts/windows/dump_exports.py |
扫描 DLL 导出符号 |
server.py |
MCP server（7 工具） |
install.sh |
全新电脑一键安装 |
已验证的规模
下表是某台机器某个账号的实测值，用来证明这套方案在百万级数据上跑得通。 你的数字会不一样——技术路径不变，规模随你的聊天记录量走。
| 项 | 数值 |
|---|---|
| 解密数据库 | 21 个 / 1.3 GB 明文 |
| 消息总数 | 1,157,006 条 |
| 会话 | 7,521 个（含 179 个群） |
| 群成员 | 26,659 人 |
integrity_check |
ok |
| 测试环境 | Windows · 微信 4.1.15.56 |
已知限制
- 富媒体正文解不开：图片/表情/视频/语音的正文由 WCDB 单独加密，工具只能标注类型。
文本消息 100% 可读。仓库内有
export_media.py/voice_decode.py可进一步接驳。 - 密钥随微信登录/升级失效：跑
refresh_key.sh重新提取。 - 微信 4.x 不再填充
SessionTable.type：群靠@chatroom后缀识别。 - 需要管理员权限读取微信进程内存。
安全边界
- 密钥（
key_windows.txt）等同微信账号的钥匙，绝不入库、不外传、不打印到对话 - 解密后的明文库涉及群友隐私，全程本机，零联网
.gitignore已强制排除密钥、decrypted/、*.db及各类中间产物- 只操作用户本机、用户有权访问的数据
请负责任地使用本工具，遵守相关法律法规。
开发者
.venv/Scripts/pip install -r requirements-dev.txt # 运行时依赖 + pytest
.venv/Scripts/python.exe -m pytest -q
测试全部使用合成数据库，不需要微信运行、不需要真实密钥， 在一台刚 clone 下来的干净机器上也能全绿。
仓库自带脱敏审计工具，会扫描工作区 + 全部 git 历史 + 提交信息：
.venv/Scripts/python.exe scripts/common/scrub_audit.py
CI 说明
上游仓库自带 GitHub Actions 配置（跑 pytest + 校验 MCP 工具数为 7）。
由于推送用的 OAuth token 缺少 workflow scope，配置文件暂存于
.github-ci/workflows/tests.yml。补齐 scope 后一条命令恢复：
gh auth refresh -h github.com -s workflow
git mv .github-ci/workflows .github/workflows
git push
致谢与出处
本仓库基于 tzwkb/wechat-decrypt（MIT License, Copyright (c) 2026 cocofeng）演进而来。原仓库提供了跨平台解密框架骨架， 本仓库在 Windows 微信 4.x 上的关键突破为：
- SHA-512 压缩函数挂钩方案与全模块覆盖策略
- 大库流式解密（
decrypt_stream.py） - 跨分片搜索、MCP server 接入、Agent Skill 封装
- 全新电脑一键安装流程
上游原始说明见 README.upstream.md / README_ZH.upstream.md，
技术细节见 docs/windows-4.x-key-extraction.md 与 docs/architecture.md。
License
MIT