# WeChat Local Reader

[![CI](https://github.com/zgkthu23/wechat-local-reader/actions/workflows/ci.yml/badge.svg)](https://github.com/zgkthu23/wechat-local-reader/actions/workflows/ci.yml)

本地读取 macOS 微信已同步的群聊、私聊和普通文件附件，提供增量监听、持久通知队列、JSON 命令行、Python API 和 stdio MCP 接口。

**使用前提：你已具备自己微信数据库的可用密钥。** 本项目负责读取和监听，不包含取钥、进程注入、修改微信签名或发送消息。无需操作微信窗口。微信升级、数据库结构或加密方式变化时，需要重新验证兼容性。

## 功能

- 精确匹配群名或联系人备注，并通过 `allowed_chats` 限定可读取范围；同名会话停止查询。
- 查询时间区间、分页、文本、引用和链接摘要；普通附件输出 `available` / `not_downloaded`。
- 从本机缓存核验附件文件名、大小、消息 MD5（若存在），并计算 SHA256。
- 增量监听多个会话，记录每个消息分片的游标，重启继续读取；首次建立历史基线，不补发历史通知。
- 消息与文件就绪事件进入 SQLite 持久队列，消费者显式确认；MCP 只提供查询，不消费队列。
- 从加密 DB/WAL 临时副本查询；SQLCipher 密钥通过标准输入传递，不放入命令参数或查询结果。

## 环境

Python 3.12+，使用 [uv](https://docs.astral.sh/uv/guides/projects/) 管理；macOS 上需要 SQLCipher 4。读取逻辑最初在 macOS Apple Silicon、微信 4.1.13 和 SQLCipher 4.19 上验证。本仓库测试使用自动生成的加密数据，不包含真实聊天记录。其他微信版本的兼容性需要实测，不能推断为全部支持。

## 快速开始

```bash
brew install uv sqlcipher
git clone https://github.com/zgkthu23/wechat-local-reader.git
cd wechat-local-reader
uv sync --locked
mkdir -p ~/.config/wechat-local-reader
chmod 700 ~/.config/wechat-local-reader
cp examples/config.example.json ~/.config/wechat-local-reader/config.json
chmod 600 ~/.config/wechat-local-reader/config.json
```

编辑仓库外的配置，设置自己的数据库目录、已有密钥文件和授权会话。密钥格式见[配置说明](docs/configuration.md)。示例中的 `ACCOUNT` 和会话名称必须替换。

```bash
uv run wechat-reader messages --chat '示例项目群' --limit 20
uv run wechat-reader files --chat '示例项目群'
uv run wechat-reader poll
uv run wechat-reader watch
```

`poll` 执行一次检查，`watch` 按配置间隔持续检查，按 Ctrl-C 停止。安装项目本身不会注册后台任务或启用通知。后台运行见 [macOS 部署](docs/macos.md)。

通知由你自己的消费者读取：

```bash
uv run wechat-reader notifications --limit 100
# 将本批内容成功交付后，用该批返回的 through 数值确认：
uv run wechat-reader ack --through 12
```

`12` 只是示例。每个状态目录只运行一个通知消费者；失败时不确认，下次可重试。该项目本身不向任何聊天软件、远程服务器或 AI 模型发送消息。

## Python API

```python
from wechat_local_reader import Client, Config

client = Client(Config.load())
result = client.messages("示例项目群", limit=20)
files = client.files("示例项目群")
health = client.watcher.status()
```

## MCP

通用 MCP 客户端使用下面的 stdio 配置，替换仓库绝对路径：

```json
{
  "mcpServers": {
    "wechat-local-reader": {
      "command": "uv",
      "args": ["run", "--locked", "--directory", "/absolute/path/wechat-local-reader", "wechat-reader", "mcp"]
    }
  }
}
```

提供 `read_wechat_messages`、`list_wechat_files`、`get_wechat_watch_status` 三个工具。支持 `WECHAT_READER_CONFIG` 环境变量。配置 MCP 客户端后，查询结果会提供给该客户端；请按自己的数据使用要求配置客户端。

## 文档与开发

- [配置、授权和密钥格式](docs/configuration.md)
- [CLI、Python、MCP 接口与通知数据格式](docs/interfaces.md)
- [架构与监听语义](docs/architecture.md)
- [macOS 后台运行、迁移与排障](docs/macos.md)
- [安全与数据边界](SECURITY.md)、[参与开发](CONTRIBUTING.md)

```bash
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
uv build --no-sources
```

目录：`src/wechat_local_reader/` 是配置、快照、读取、监听及接口实现；`tests/` 是合成数据测试；`docs/` 是部署和接口文档；`examples/` 只含虚构配置。

## 范围

只覆盖当前电脑同步的记录；不能补齐手机历史或下载尚未缓存的云端文件。图片、语音、视频和表情返回类型标记，未实现媒体解码或转写。普通文件采用本地校验；无消息 MD5 时，只能通过唯一文件名和大小关联，输出会明确标为 `unique_filename_size`。

MIT 许可证。项目整理自本地独立编写的读取与监听实现，相关研究来源见 [NOTICE](NOTICE)。