nasseroth/whatsapp-chat-date-filter

# WhatsApp 聊天日期筛选器 一条命令即可将 WhatsApp 的聊天记录导出文件——包括 `.txt` 转录文件**和附加媒体**——筛选至单个日期范围内。 WhatsApp 的*导出聊天记录*功能会导出完整的历史记录。当你只需要特定时间段的记录（用于法律证据、新闻报道、个人存档、LLM 上下文窗口等）时，你必须手动删减数百条消息并删除所有不再属于该时间段的媒体文件。这个脚本可以为你完成这项工作，实现无损且可重复的筛选。 ## 功能 - 将聊天 `.txt` 文件裁剪至用户指定的日期范围（包含边界值）。 - 仅复制被保留消息引用的媒体文件 —— 不在范围内的所有音频、图片、PDF、视频或文档都会被排除。 - 自动检测导出文件中使用的日期格式（`DD/MM/YYYY`、`MM/DD/YYYY`、两位或四位数的年份、AM/PM 等）。 - 完全按照原样保留多行消息。 - `--dry-run` 模式会在你确认写入任何内容之前，报告哪些内容*将*被保留/移除。 - 纯标准库 —— 无需 `pip install` 步骤。 ## 为什么 CLI 要使用美国日期格式？ 聊天记录导出会保留生成该文件的手机的日期格式（在美国以外通常为 `DD/MM/YYYY`）。脚本的**命令行参数**特意使用了美国惯例 `MM/DD/YYYY`，这样来自任何国家的任何人访问此代码库时，都能以相同的方式阅读示例。同时也支持 ISO `YYYY-MM-DD` 格式。 ## 环境要求 - Python 3.9 或更高版本。 - 导出的聊天记录文件夹，包含： - `WhatsApp conversation with .txt`（或其本地化名称）； - 随导出文件一起生成的所有媒体文件。 ## 安装 ``` git clone https://github.com/nasseroth/whatsapp-chat-date-filter.git cd whatsapp-chat-date-filter ``` 没有第三方依赖项。 ## 使用方法 ``` python whatsapp_chat_filter.py \ --input ./chat \ --output ./chat_filtered \ --start 08/10/2023 \ --end 05/29/2025 ``` 上面的示例保留了**从 2023 年 8 月 10 日到 2025 年 5 月 29 日**的所有消息，将相应的媒体文件复制到 `./chat_filtered` 中，并保持原始文件夹原封不动。 ### 参数 | 标志 | 必填 | 描述 | |------|----------|-------------| | `--input`, `-i` | ✓ | 包含原始聊天 `.txt` 及其媒体的文件夹。 | | `--output`, `-o` | ✓ | 目标文件夹（如不存在则会创建）。必须与 `--input` 不同。 | | `--start`, `-s` | ✓ | 范围起始日期（包含）。格式为 `MM/DD/YYYY` 或 `YYYY-MM-DD`。 | | `--end`, `-e` | ✓ | 范围结束日期（包含）。格式与 `--start` 相同。 | | `--chat-file` | | `.txt` 文件的路径（当 `--input` 中只存在一个此类文件时将自动检测）。 | | `--chat-date-format` | | 聊天中使用的 `strptime` 格式。省略时将自动检测。 | | `--encoding` | | 默认为 `utf-8`。 | | `--dry-run` | | 打印摘要而不写入输出文件夹。 | ### 示例输出 ``` Chat file: ./chat/WhatsApp conversation with Someone.txt Detected format: %d/%m/%Y %H:%M Range: 2023-08-10 .. 2025-05-29 Messages kept: 327 / 601 Media kept: 117 Media dropped: 49 Wrote filtered chat to: ./chat_filtered/WhatsApp conversation with Someone.txt ``` ## 工作原理 1. **解析转录文件。** 每一行以可识别的 `date time -` 前缀开头的文本都会作为一条新消息的开始；任何不符合该模式的行都会被视为上一条消息的延续（从而保持多段落引用的完整性）。 2. **按日期范围过滤。** 时间戳落在 `[--start, --end]` 范围内（包含两端）的消息会被保留；其余消息将被丢弃。 3. **追踪被引用的媒体。** 对于每条保留的消息，脚本会查找两种模式： - `‎FILENAME (arquivo anexado)` —— WhatsApp 为任何附加文件添加的标记，同时也支持识别其英文、西班牙文和法文版本。 - 在纯文本中提到的 `IMG-YYYYMMDD-WAxxxx.ext` 样式的名称。 4. **通过文件名日期进行合理性检查。** WhatsApp 会在自动生成的文件名中编码捕获日期（例如 `PTT-20250505-WA0036.opus` → `2025-05-05`）。即使引用文件的消息碰巧被裁剪掉，只要文件名中嵌入的日期在范围内，这些文件依然会被保留。 5. **写入输出文件夹。** 将仅包含存活消息的内容写入新的 `.txt` 文件，并将保留的媒体文件复制过去。 原始文件夹绝不会被修改。 ## 日期格式速查表 | 导出文件中显示的区域设置 | `--chat-date-format` | |----------------------------|----------------------| | `05/05/2025 16:19`（巴西、葡萄牙、大部分欧盟国家） | `"%d/%m/%Y %H:%M"` | | `5/5/25, 16:19`（紧凑型 24 小时制） | `"%d/%m/%y, %H:%M"` | | `5/5/25, 4:19 PM`（美国，12 小时制） | `"%m/%d/%y, %I:%M %p"` | | `2025-05-05 16:19`（ISO） | `"%Y-%m-%d %H:%M"` | 仅在自动检测选错格式时，才通过 `--chat-date-format` 传入该参数。 ## 局限性 - 被 WhatsApp 标记为 `` / `` 的消息不包含文件名，因此无法与媒体文件夹进行匹配。只要它们的时间戳在范围内，仍会被保留在裁剪后的 `.txt` 文件中，但不会为它们复制任何附件。 - 该脚本从不删除输入文件夹中的任何内容；它会生成一个全新的输出文件夹，以便你随时可以使用不同的范围重新运行。 - 导出后在手机上进行的编辑/删除操作不会反映出来 —— WhatsApp 不包含该操作历史记录。 ## 贡献 欢迎提交 Pull request。如果你的手机导出的聊天记录格式未被自动检测器识别，请提交一个 Issue，并附上隐去隐私信息的前几行样本（只需包含日期/时间前缀即可）以及你设备的区域设置。

标签：dry-run, LLM上下文窗口, Python, WhatsApp, 个人数据归档, 多行消息保留, 媒体文件处理, 数字取证, 数字取证, 数据清洗, 文本处理, 文档结构分析, 新闻调查工具, 无后门, 无损处理, 日期格式自动检测, 日期范围过滤, 法律证据收集, 电子数据展示, 聊天导出, 聊天记录过滤, 自动化脚本, 自动化脚本