ReadWechatMessage

一个完全离线、开源的微信一对一聊天记录统计工具。它从已经导出的 CSV 或 XLSX 文件读取消息，统计双方每天的文字量及比例，并保留原 MATLAB 脚本的 输入列位置和核心输出名称，便于无缝迁移。

本项目不连接微信、不读取 iPhone 备份、不解密数据库、不上传数据，也不需要 MATLAB 或其他闭源运行时。

功能

• 支持 Windows 和 Linux，以及 Python 3.11～3.14。
• 支持 CSV（UTF-8、UTF-8 BOM、GB18030）和 XLSX。
• 默认兼容旧脚本第 4、5、9 列的位置约定。
• 也支持按列名读取，列名可在本地 TOML 配置中修改。
• legacy 模式复现旧 MATLAB 统计规则；strict 模式按时区和 Unicode 用户可见字符进行更可靠的统计。
• 输出旧名称 MessageCount.csv、MessageRatio.csv、 MessageRatio1.txt，并增加带日期和元数据的现代结果。
• 默认遇到无效行即失败；显式跳过时只报告行号和错误类型，不回显聊天内容。
• 流式读取数据，不在内存中保存完整聊天记录。

仅支持两人一对一聊天。群聊中的第三方发送者在严格模式下会被拒绝，避免 生成有误导性的双方比例。

快速开始

uv（推荐）

安装 uv 后，在仓库目录运行：

uv sync --locked
uv run read-wechat-message analyze D:\private\messages.xlsx

Linux 路径示例：

uv sync --locked
uv run read-wechat-message analyze /private/messages.csv

结果默认写入输入文件旁边的 <文件名>-analysis 目录。已有非空结果目录不会 被覆盖，除非显式添加 --overwrite。

pip

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\read-wechat-message.exe analyze D:\private\messages.xlsx

Linux:

python3.12 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/read-wechat-message analyze /private/messages.csv

Conda

conda create -n readwechat python=3.12 pip
conda activate readwechat
python -m pip install .
read-wechat-message analyze D:\private\messages.xlsx

这些方式都不要求修改 Windows 系统环境变量。

兼容模式与严格模式

项目	legacy（默认）	strict
时间戳	Unix 秒	秒、毫秒或 ISO 8601
日期分组	旧脚本的 UTC/86400 分桶	指定时区的本地自然日
文字长度	UTF-16 代码单元，兼容 MATLAB length	Unicode 字素簇，更接近用户看到的字符
非文本消息	按旧脚本字符串处理	图片、语音、XML 等占位内容计 0
未知发送者	忽略并警告	作为无效行处理
行顺序	保留旧脚本首末时间范围规则	可无序，按最早和最晚日期汇总

严格模式示例：

uv run read-wechat-message analyze D:\private\messages.xlsx `
  --mode strict `
  --timestamp-unit auto `
  --timezone Asia/Shanghai

自动时间单位要求整份输入保持一致；秒、毫秒和 ISO 8601 混用会报错。详细差异 见 迁移指南。

输入

默认 legacy 模式使用一基列号：

字段	默认列
时间戳	4
消息	5
发送者	9

发送者 0 表示自己，1 表示对方。按列名读取的示例：

uv run read-wechat-message analyze D:\private\messages.csv `
  --schema named `
  --mode strict

默认列名为 timestamp、message、owner。XLSX 含多个非空工作表时必须通过 --sheet 明确选择。完整约束见 输入格式。

本地配置

复制示例文件，但不要把真实配置提交到 Git：

Copy-Item config.example.toml config.local.toml

程序会自动读取当前工作目录下的 config.local.toml，也可显式指定：

uv run read-wechat-message analyze D:\private\messages.xlsx `
  --config D:\private\wechat-analysis.toml

配置优先级从高到低为：

1. 命令行参数；
2. --config 指定的文件；
3. 当前目录的 config.local.toml；
4. 内置默认值。

项目不会读取或修改 Windows 系统环境变量。config.local.toml、CSV/XLSX、 数据库和结果目录均已加入 .gitignore。

输出

每次成功运行会原子性地产生一个完整结果目录：

• MessageCount.csv：无表头，两列分别为自己和对方的每日文字量；
• MessageRatio.csv：无表头，每日“对方 ÷ 自己”的比例；
• MessageRatio1.txt：全部日期的总比例；
• daily.csv：包含日期、双方文字量、比例及比例状态；
• summary.json：模式、输入哈希、记录数、警告及汇总结果；
• validation_report.json：仅在使用 --skip-invalid 且存在无效行时生成。

分母为零时，兼容文件使用 Inf 或 NaN；JSON 使用 null，并通过状态字段 区分 infinite 与 undefined。详见 输出格式。

常用命令

# 查看版本
uv run read-wechat-message --version

# 明确选择工作表和输出目录
uv run read-wechat-message analyze D:\private\messages.xlsx `
  --sheet Messages `
  --output-dir D:\private\result

# 跳过无效行并生成安全的校验报告
uv run read-wechat-message analyze D:\private\messages.csv `
  --mode strict `
  --skip-invalid

退出码：0 成功，2 配置错误，3 数据校验错误，4 输入或输出错误。

隐私边界

• 输入文件仅在本机读取，程序不包含网络请求。
• 日志、异常和校验报告不写入消息正文。
• summary.json 只记录输入文件 SHA-256、大小和格式，不记录输入绝对路径。
• 测试数据全部为合成数据。
• 本仓库不包含聊天导出、数据库、.mat、第三方 EXE 或 ZIP。

请仍然把聊天文件放在仓库外的私有目录中，并在分享结果前检查其内容。安全问题 报告方式见 SECURITY.md。

开发与验证

uv sync --locked --extra dev
uv run ruff check src test scripts
uv run ruff format --check src test scripts
uv run mypy src scripts
uv run pytest --cov=read_wechat_message --cov-branch --cov-fail-under=95
python scripts/check_repository_privacy.py
uv build

CI 在 Windows 和 Linux 上覆盖 Python 3.11、3.12、3.13、3.14，并执行格式、 静态类型、分支覆盖率、依赖漏洞、构建和安装冒烟测试。

一次性 GNU Octave 兼容对照及发布验证范围记录在 验证记录。

许可证

MIT，Copyright © 2026 zhaowl94。