这是一个面向 Windows NTQQ 的群聊图片缓存清理工具。
仅限学习交流。 本项目涉及 QQ 本地数据库、缓存文件和第三方取 key/解密资料，仅供技术研究和个人数据整理使用。使用前请确认你有权访问和处理相关数据，并遵守当地法律、QQ 软件许可协议及上游项目许可证。
重要警告：请务必先备份。 数据库解密、文件匹配、移动和删除操作都有造成数据丢失、文件损坏或误操作的风险。请先退出 QQ，备份原始数据库和图片目录，优先使用副本测试；任何数据丢失、程序异常、系统故障或其他意外后果，均由使用者自行承担，项目作者不作任何明示或默示保证。
完整流程分为两阶段：
- 准备 Windows NTQQ 的原始加密数据库和对应的 key，并将数据库解密为普通 SQLite 数据库。
- 根据解密后的数据库和 QQ 图片缓存目录，识别指定群聊的图片文件，生成清单并在确认后清理。
本项目当前负责第 2 阶段。数据库取 key 和数据库解密请按照下面的 QQDecrypt 教程完成；项目中的 windows_ntqq_get_key.ps1 是取 key 的辅助脚本。
- 默认只扫描和预览，不删除文件。
- 只处理 manifest 中列出的本地图片，不修改数据库和消息记录。
- 使用
--extract-dir时只复制图片，原始 QQ 缓存文件不会被移动或删除。 - 删除阶段只读取已经确认的 manifest，不重新扫描数据库。
- 删除前会重新检查文件是否存在以及文件大小是否变化；发生变化时跳过。
- 建议先退出 QQ，备份原始数据库和图片目录，并在副本上操作。
- 不要把原始数据库、解密数据库、key、聊天记录或 manifest 提交到版本库。
- Windows x86-64
- Python 3.14 或更高版本
- uv
- 已安装的 Windows NTQQ
本项目的 pyproject.toml 会安装 protobuf 依赖。
你需要两项输入：
- 原始加密数据库：
<你的原始 nt_msg.db 路径> - 对应的数据库 key：
<你的数据库 key>
请参考 QQDecrypt 的 Windows NTQQ 教程获取它们：
也可以在 PowerShell 中运行项目内的脚本：
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\windows_ntqq_get_key.ps1脚本输出的 key 只供你本地使用，不要写入 README、源代码或提交到 Git。
按照“统一解密 NTQQ 数据库”教程，将下面两项填入解密脚本：
INPUT_DB = r"<你的原始 nt_msg.db 路径>"
DB_KEY = "<你的数据库 key>"解密成功后，得到：
nt_msg_clear.db：去除 NTQQ 文件头后的中间文件nt_msg_plain.db：最终的未加密 SQLite 数据库
后续清理步骤使用 nt_msg_plain.db，不要把原始加密数据库直接传给清理器。
在本项目根目录执行。请将示例中的占位符替换成你自己的值：
uv run python -m ntqq_media_cleaner `
--group "<你的QQ群号>" `
--db "<你的 nt_msg_plain.db 路径>" `
--cache-dir "<你的 QQ\Image\Group2 图片目录>" `
--hash `
--manifest "<你的清单文件路径>.json" `
--extract-dir "<你的群聊图片查看目录>"说明：
--group：要处理的QQ群号。--db：第二步生成的未加密数据库。--cache-dir：QQ 的Image\Group2图片缓存目录。--hash：在文件名和大小匹配基础上使用 MD5 校验，扫描较慢但更可靠。--manifest：预览结果保存位置。--extract-dir：将匹配到的图片复制到一个独立文件夹，便于集中查看；原始缓存文件不变。
命令只扫描、保存清单并复制查看用图片，不会删除原始文件。请先打开提取目录查看照片，也可以直接在资源管理器中删除整个提取目录；这不会影响 QQ 原始缓存。若不需要复制图片，可以省略 --extract-dir。
如果想查看 Group2 中哪些群聊匹配到的图片最多，可以使用只读统计模式。它不会生成 manifest，也不会复制、移动或删除任何文件：
uv run python -m ntqq_media_cleaner `
--stats `
--db "<你的 nt_msg_plain.db 路径>" `
--cache-dir "<你的 QQ\Image\Group2 图片目录>" `
--hash输出列为：排名、群号、匹配本地文件数、图片总大小（MiB）、图片消息数。默认按匹配本地文件数从多到少排序；文件名和大小匹配不到时，--hash 会使用 MD5 继续匹配。
默认先移动到一个集中暂存目录，不直接永久删除。确认图片无误后，可以在 Windows 资源管理器中右键删除整个暂存目录，让 Windows 统一将它放入回收站：
uv run python -m ntqq_media_cleaner `
--group "<你的QQ群号>" `
--manifest "<你的清单文件路径>.json" `
--stage-dir "<你的图片暂存目录>" `
--delete程序会要求输入确认字符串。此步骤会把 manifest 中的原始图片集中移动到暂存目录，成功移动后原位置不再保留这些文件；它不会直接调用 Windows 回收站。确认暂存目录中的图片后，再删除整个暂存目录即可。
旧参数 --trash-dir 仍可使用，它与 --stage-dir 完全等价，但推荐使用名称更准确的 --stage-dir。
如果你已经确认过匹配结果，不想保存或读取 manifest，也可以直接扫描后处理。此模式必须同时提供数据库和图片缓存目录，程序会先显示本次扫描到的文件数量，再要求输入确认字符串：
uv run python -m ntqq_media_cleaner `
--group "<你的QQ群号>" `
--db "<你的 nt_msg_plain.db 路径>" `
--cache-dir "<你的 QQ\Image\Group2 图片目录>" `
--hash `
--stage-dir "<你的图片暂存目录>" `
--delete直接处理模式不会读取或生成 manifest。若省略 --cache-dir，程序会拒绝执行，避免在没有重新扫描依据时误处理文件。
需要由程序永久删除时，额外加上 --permanent，并完成更严格的确认：
uv run python -m ntqq_media_cleaner `
--group "<你的QQ群号>" `
--manifest "<你的清单文件路径>.json" `
--delete `
--permanent- 已支持：从
group_msg_table识别群图片消息，按文件名、大小和可选 MD5 匹配Image\Group2文件，保存 manifest，并安全移动或删除匹配文件。 - 当前不负责：从 QQ 客户端复制原始数据库、自动获取 key、执行完整数据库解密、恢复无法匹配到本地文件的图片。
- 原始数据库和 key 的获取、数据库解密格式及版本兼容性以 QQDecrypt 教程为准。
数据库 key 提取脚本和数据库解密流程参考：
本项目自己的媒体扫描、统计和清理代码采用 GNU GPLv3，完整条款见 LICENSE。
数据库 key 提取脚本和解密流程来自外部项目，不能将其默认为本项目原创代码。windows_ntqq_get_key.ps1 遵循其上游项目的 CC BY-NC-SA 4.0 条款，不因本项目包含 GPLv3 而改变；相关来源、许可证和发布注意事项见 NOTICE.md。