WeChat LocalMind (wechat-localmind)

零依赖 macOS & Windows 微信（WeChat 3.x / 4.x）本地群聊只读提取、结构化清洗、CLI 与 MCP Server 能力层

English | 简体中文 | llms.txt | SKILL.md | CONTRIBUTING | SECURITY | LICENSE

WeChat LocalMind（wechat-localmind） 是一个零第三方运行时依赖的本地优先（Local-First）只读数据提取能力层，专为 AI Agent、自动化工作流与个人数据归档设计。它通过离线快照解密 macOS 与 Windows 本地的微信 3.x / 4.x（WCDB）加密分片数据库，仅提取并清洗**微信群聊（@chatroom）**对话与沙盒媒体附件，在架构层面 100% 物理拦截一对一私聊（wxid_*）与公众号（gh_*），输出高信噪比的 JSON / Markdown 结构化结果或通过标准 MCP Stdio 协议交付给 Claude、Cursor、Google Antigravity 等智能体消费。

*-localmind 本地即时通讯只读提取能力层家族

本仓库与姊妹仓 whatsapp-localmind（macOS WhatsApp 本地群聊提取能力层）同属 qilaidev 下的 *-localmind 本地聊天提取家族，两仓严格遵循统一的五项架构哲学： 100% 离线只读快照 + 物理拦截一对一私聊 + 四级实名还原 + 单调增量游标 + CLI & MCP 双协议交付。

定位边界：它是什么 / 它不是什么

Related MCP server: wxq

合规与隐私安全声明

• 合法授权用途：本工具严格仅用于用户本人设备上的个人本地数据备份与经授权的离线研究。使用本工具处理群聊数据时，请遵守所在地法律法规及群聊参与方的隐私约定。

• 100% 离线只读快照：所有解密与聚合操作均在独立快照目录（macOS: ~/Library/Application Support/WeChat-LocalMind/snapshot；Windows: %LOCALAPPDATA%\WeChat-LocalMind\snapshot）中完成，绝不修改微信原始数据库、绝不注入或干扰微信客户端运行态、绝不发起任何网络请求、绝不发送任何消息。

• 三重 @chatroom 物理隔离：在分片提取层（snapshot.py）、SQL 查询层（db.py 强制 chat_id LIKE '%@chatroom'）与附件导出/策略层（config.py / media.py）三重物理拦截一对一私聊（wxid_*）与公众号（gh_*），越权访问直接返回 EXIT_POLICY_DENIED（退出码 3）。

六大核心架构支柱

1. 原生 CommonCrypto SQLCipher 3 / 4 离线解密引擎

   • 优先调用 macOS 系统原生 CommonCrypto（/usr/lib/libSystem.B.dylib CCCrypt）与标准库 hashlib.pbkdf2_hmac，零 pip 依赖即可实现 C 语言级 AES-256-CBC 逐页验证与解密，全面兼容 WeChat 4.x WCDB（reserve=80）与 WeChat 3.x（reserve=48）。

2. WeChat 4.x zstd 内存级解压与多片库自动聚合

   • 优先调用 Python 3.14+ 内置 compression.zstd 与原生 libzstd.dylib（ctypes）实现零子进程开销的内存解压；自动跨 message_0.db ~ message_N.db 解析 Msg_<md5> / Chat_<md5> / MSG 表与分片内 Name2Id 映射，按时间序生成全局单调递增游标 msg_id。

3. 三重 @chatroom 隐私隔离护栏

   • 提取、查询、导出三层硬编码校验 chat_id LIKE '%@chatroom'，物理隔离 wxid_* 私聊与 gh_* 公众号，支持群聊黑/白名单精细化控制与个人身份锚点标记。

4. 四级实名还原与 @wxid_ 自动转实名

   • 自动关联 contact.db 与 chatroom_member，按 通讯录备注 (remark) > 群内昵称 (group_nickname) > 微信昵称 (nick_name) > 脱敏 wxid (微信群友(xxxx)) 四级优先级还原发言人身份，并将正文中残留的 @wxid_xxx 与 \u2005 特殊空格自动替换为 @实名 或 [@我(实名)]。

5. XML / Protobuf 富媒体深度解析与 150 字引用链还原

   • 内置纯 Python 零依赖 Protobuf Wire 解析器与 XML 解析器，精准还原 <appmsg type="57"><refermsg> 150 字父消息引用链、文件卡片（type=6）、网页链接（type=5）、小程序（type=33/36）、视频号/直播卡片（type=51/63）、合并转发（type=19）与群公告（type=87）；自动剔除撤回消息（revokemsg）、拍一拍与系统通知，并自动折叠连续「收到 / OK / +1 / 红包」噪音。

6. 微信 .dat 异或加密图片向量化还原

   • export-media 内置自适应 Magic Header 异或密钥推导器与向量化大整数位运算引擎，导出微信 .dat 加密图片时自动解密还原为标准 .jpg / .png / .gif / .webp / .heic。

安装与快速上手

前置要求：Python >= 3.10（零第三方运行时依赖）。

git clone https://github.com/qilaidev/wechat-localmind.git
cd wechat-localmind

# 一键将 wechat-localmind 软链挂载到 ~/.local/bin 并同步 AI Skill 技能包
./bin/wechat-localmind install --bin-dir ~/.local/bin --skill-dir ~/.gemini/config/skills

30 秒快速体验

# 1. 检查本地微信 3.x/4.x 数据库与密钥状态
wechat-localmind doctor --format md

# 2. 导入或设置 SQLCipher 密钥后，拉取最近 24 小时群聊记录
wechat-localmind fetch --chats ALL_ALLOWED --since 24h --format md

CLI 子命令速查

# 配置 SQLCipher 密钥（支持全局密钥、分片密钥或内存转储扫描）
wechat-localmind key --set "<64-hex-key>"
wechat-localmind key --set "contact.db:<64-hex-key>"
wechat-localmind key --scan-dump ./wechat_memory.dump

# 设置本人身份锚点（将本人消息标记为 [我(姓名)]）
wechat-localmind config set-identity --name "张工" --wxid "wxid_example123456"

# 按关键词筛选群聊（包含已屏蔽群）
wechat-localmind groups --keyword "项目" --include-blocked --format json

MCP Stdio Server 接入与工具契约

在 Claude Desktop、Cursor、Google Antigravity 或 Codex 的 MCP 配置中添加：

{
  "mcpServers": {
    "wechat-localmind": {
      "command": "wechat-localmind",
      "args": ["mcp-serve"]
    }
  }
}

暴露的 4 个只读 MCP Tools

环境变量与 POSIX 退出码契约

• WECHAT_LOCALMIND_DATA_DIR：自定义微信数据根目录（如 xwechat_files 或 WeChat Files）

• WECHAT_LOCALMIND_ACCOUNT_DIR：显式指定单个登录账号目录

• WECHAT_LOCALMIND_SNAPSHOT_DIR：自定义统一只读快照与附件导出目录

• WECHAT_LOCALMIND_KEY：全局 64 位 Hex SQLCipher 密钥

常见问题（FAQ）

同时支持 macOS 与 Windows 的 WeChat 3.x（reserve=48，如 msg_*.db / MSG*.db）和 WeChat 4.x WCDB（reserve=80，如 xwechat_files/db_storage/message_*.db 与 contact.db）。工具会自动探测数据目录格式、分片结构与 zstd 压缩载荷并统一聚合。

零封号风险。 wechat-localmind 100% 在离线独立快照目录中工作，绝不向微信客户端进程注入代码、绝不修改原始数据库文件、绝不发起任何网络请求，也绝不包含任何自动发送消息或模拟操作逻辑。

系统在分片提取层、SQL 查询层与策略导出层实施三重物理拦截：所有查询强制附带 chat_id LIKE '%@chatroom'，一旦检测到 wxid_* 私聊或 gh_* 公众号标识，立即拒绝执行并返回 EXIT_POLICY_DENIED（退出码 3）。

在 macOS 上直接通过 ctypes 调用系统原生 CommonCrypto（CCCrypt）与 libzstd.dylib（Python 3.14+ 优先使用内置 compression.zstd），配合标准库 hashlib.pbkdf2_hmac 实现 C 语言级 AES-256-CBC 逐页验证与解密，无需安装 pysqlcipher3 或 cryptography 等重型编译依赖。

运行 wechat-localmind export-media --msg-ids <id> 或调用 MCP 工具 wechat_export_media 时，内置的自适应 Magic Header 异或密钥推导器会自动识别文件头特征，通过向量化大整数位运算将 .dat 还原为标准 .jpg / .png / .gif / .webp / .heic 图片。

只需在客户端 MCP 配置中将 command 指向 wechat-localmind、参数设为 ["mcp-serve"] 即可（详见上方 MCP Stdio Server 接入）。若使用支持 Agent Skills 的客户端，可通过 ./bin/wechat-localmind install 一键同步 skills/wechat-localmind/SKILL.md。

仓库结构与单元测试

wechat-localmind/
├── README.md                        # 中文文档
├── README.en.md                     # 英文文档
├── llms.txt                         # AI Agent / LLM 检索规范索引 (llmstxt.org)
├── LICENSE                          # MIT 开源协议
├── SECURITY.md                      # 隐私护栏与安全漏洞报告策略
├── CONTRIBUTING.md                  # 贡献指南与 PR 自检清单
├── CHANGELOG.md                     # 版本变更日志
├── pyproject.toml                   # Python 包配置（>=3.10，零第三方运行时依赖）
├── bin/wechat-localmind             # 免安装 CLI 可执行入口
├── skills/wechat-localmind/         # AI Agent 标准技能包 (SKILL.md + scripts/)
├── src/wx_localmind/                # 核心源码（crypto, snapshot, db, cleaner, media, mcp_server 等）
└── tests/test_wx_localmind.py       # 合成 SQLCipher / Protobuf / .dat 单元测试套件

# 运行全部单元测试（无需真实微信数据库）
PYTHONPATH=src python3 -m unittest discover -s tests -v