agent-wechat（WeChat History MCP）

一个运行在 macOS 上的 MCP 服务器：读取本机微信的登录态与聊天记录，供 Claude Code / Codex 等 Agent 调用——按联系人读取近期记录生成回复建议、 全量导出聊天记录到本地检索库用于分析与 LLM 蒸馏，或把朋友圈导出成 可离线阅读的 HTML 时间线。

仅限本机、本人已登录的微信账号、纯本地处理。 解密自己的聊天数据库涉及合规争议 ——同类开源项目 chatlog 于 2025-10 被微信官方函件后删库。本仓库公开仅供阅读与审计， 不构成对合规性的背书，使用风险自负；不得用于获取他人数据。详见 SECURITY.md §5。

核心特性

适用场景

• 回复建议：把「帮我回复 XXX」交给 Agent，它读近期上下文后给出候选回复， 替代手动截图聊天记录。
• 历史检索：「我和 XXX 聊过 XX 吗」——本地毫秒级全文检索。
• LLM 蒸馏：全量导出为结构化数据，供本地分析对话风格、构建个人知识库。

架构概览

┌────────────────────────────────────────────────────────────┐
│ 消费层   Claude Code (MCP+Skill) │ Codex (MCP) │ 终端 CLI  │
└──────────┬───────────────────────┬──────────────┬───────────┘
           │      stdio (JSON-RPC) │              │
┌──────────▼───────────────────────▼──────────────▼───────────┐
│ mcp_server.py —— 15 个工具的薄适配层（无业务逻辑）            │
├──────────────────────────────────────────────────────────────┤
│ 核心层（Python，可脱离 MCP 独立使用）                         │
│  account   登录态/账号发现（pgrep + lsof，只读）              │
│  keys      passphrase 缓存 + PBKDF2 派生 + HMAC 自验证        │
│  bootstrap lldb 断点捕获 passphrase（唯一需要 sudo 的环节）   │
│  decrypt   db+wal+shm 快照 → sqlcipher 解密（用后即焚）       │
│  reader    消息解码（zstd/类型掩码/群前缀）与流式产出          │
│  export    流式导出管道（幂等 upsert + 水位线 + 长任务）      │
│  store     本地检索库（SQLite + FTS5 trigram）                │
│  search    检索路由（trigram / LIKE 兜底）                    │
│  vector    向量索引与语义检索（本地 fastembed + sqlite-vec）  │
│  purge     本地数据销毁（清单→计划→执行→核查，CLI 专属）      │
│  exclusions 被销毁会话的排除清单（唯一不可重建的产物）        │
├──────────────────────────────────────────────────────────────┤
│ 数据层                                                        │
│  微信容器（只读） │ ~/.agent-wechat/（0700：密钥缓存+索引库） │
└──────────────────────────────────────────────────────────────┘

核心设计：一次性特权引导 → 之后完全无特权。bootstrap 是唯一需要 sudo 的 环节，产出 passphrase 缓存；此后 MCP Server 常驻运行零特权。详见 ARCHITECTURE.md。

快速开始

# 1. 安装（macOS + 微信 4.1.x，见 INSTALL.md 的完整前置条件）
cd ~/agent-wechat && uv sync

# 2. 一次性引导（仅首次 / 微信升级后；需 sudo，期间要在微信里重新登录一次）
killall WeChat
sudo codesign --force --deep --sign - /Applications/WeChat.app
open /Applications/WeChat.app        # 然后在微信中登录
sudo uv run --directory ~/agent-wechat agent-wechat bootstrap
#    启动后 5 分钟内：微信内 退出登录 → 重新登录，触发密钥捕获

# 3. 验证
uv run agent-wechat status --verify-keys     # 期望：HMAC 33/33

# 4. 使用
uv run agent-wechat recent filehelper -n 5   # 实时读取
uv run agent-wechat export                   # 全量导出（~2 分钟）
uv run agent-wechat search "关键词"           # 检索

# 5.（可选）向量语义检索：先建索引（首次会下载约 95MB 本地模型，之后完全离线）
uv run agent-wechat vector-build
uv run agent-wechat semantic "上次说的那个爬山的安排"

接入 Claude Code / Codex 的 MCP 配置见 INSTALL.md； 工具清单见 TOOLS.md。

支持的平台与版本

目录结构

agent-wechat/
├── README.md              ← 本文件
├── CONTEXT.md             领域词表（代码与文档共用的术语）
├── .mcp.json              Claude Code 项目级 MCP 配置
├── .codex/config.toml     Codex 项目级 MCP 配置（与 .mcp.json 同构的 TOML 版）
├── src/agent_wechat/      核心包（模块职责见 ARCHITECTURE.md）
│   ├── paths.py           路径常量与账号目录解析
│   ├── account.py         登录态检测与账号识别
│   ├── keys.py            密钥派生/校验/缓存
│   ├── bootstrap.py       lldb 捕获（sudo）
│   ├── decrypt.py         快照与解密
│   ├── errors.py          统一错误契约
│   ├── messages.py        messages 行契约
│   ├── appmsg.py          appmsg 原始载荷的规范化与解析
│   ├── msgextra.py        位置/名片原始载荷的解析
│   ├── roster.py          显示名规则（群昵称/备注/昵称优先级）
│   ├── schema.py          微信库结构声明与能力探测
│   ├── reader.py          消息读取与解码
│   ├── media.py           媒体导出（图片解密 / 语音 SILK→WAV / 视频定位）
│   ├── moments.py         朋友圈解析（sns.db，只读不联网）
│   ├── sns_media.py       朋友圈远程媒体下载与解密（HTTP、默认关；media.py 另有贴纸 CDN 取件一条，同为 HTTP、默认关——两者是本项目仅有的两条外发路径）
│   ├── moments_html.py    朋友圈渲染（单文件 HTML）
│   ├── chat_text.py       两个会话模板共享的措辞与纯函数
│   ├── chatview.py        会话时间线组装与落盘
│   ├── chat_html.py       会话时间线的 HTML 模板
│   ├── chat_md.py         会话时间线的 Markdown 模板
│   ├── chat_index.py      会话索引页模板
│   ├── export.py          导出管道与水位线续跑
│   ├── store.py           本地检索库
│   ├── search.py          检索路由
│   ├── vector.py          向量索引与语义检索
│   ├── tasks.py           长任务注册表
│   ├── usecases.py        用例层（两个入口共享的入口策略）
│   ├── purge.py           数据销毁（CLI 专属）
│   ├── exclusions.py      会话销毁的排除清单（唯一不可重建的产物）
│   ├── webui.py           本地只读工作台（Phase 07，仅 loopback）
│   ├── derived.py         本地 OCR/ASR 派生文本与事实记忆（Phase 06）
│   ├── retrieval.py       统一检索与两阶段披露（Phase 05）
│   ├── sync.py            同步编排与只读诊断（Phase 04）
│   ├── mcp_server.py      MCP 工具层
│   └── cli.py             命令行入口
├── tests/                 集成测试（合成加密库，不依赖真机）
├── skills/                随仓库分发的 Claude Code Skill（wechat-reply）
├── spike/                 密钥可行性探索脚本（一次性，留档）
└── docs/
    ├── INSTALL.md         安装与配置
    ├── USAGE.md           使用指南
    ├── TOOLS.md           MCP 工具参考
    ├── ARCHITECTURE.md    架构设计
    ├── DATA_MODEL.md      数据与存储
    ├── SECURITY.md        隐私与安全
    ├── TROUBLESHOOTING.md 故障排查
    ├── FAQ.md             常见问题
    ├── schema-4.1.13.md   微信库结构实测记录
    ├── CHANGELOG.md       版本记录
    └── CONTRIBUTING.md    贡献指南

文档索引

许可证与免责声明

本项目以 GNU General Public License v3.0 发布，全文见 LICENSE。 （pilk——SILK 语音解码——本身是 GPL-3.0，本项目的许可证与之兼容。）

Copyright (C) 2026 Yanjin Li

免责声明：本项目通过读取本机微信进程内存（仅一次、断点瞬间）获取本人账号的 数据库密钥，并解密本人设备上的聊天数据库。此行为可能违反《微信软件许可及服务协议》， 且"规避技术保护措施"的法律定性存在争议。使用本项目的一切后果由使用者自行承担， 包括但不限于账号受限。开发者不对任何人因使用本项目而遭受的损失负责。请勿用于 读取他人账号数据或任何商业用途。

版本：0.2.0rc1（发布候选；验收矩阵见 docs/roadmap/PHASE_07_RELEASE_AUDIT.md）。