qq-bak-chat-history-export

QQ聊天记录， bak文件解码导出工具 — 将 QQ / NTQQ 聊天记录转换为 Agent 可读的 TXT、JSON、CSV

Python 3 · SQLite · SQLCipher 工作流 · NTQQ nt_msg.db · Codex Skill · 本地处理

快速开始 · 主要功能 · 真实 bak 文件流程 · 输出格式 · 安装为 Codex Skill · English

项目定位

qq-bak-chat-history-export 用于把 QQ 旧版 .bak 聊天记录备份、已导入 QQ 的历史聊天记录、或已解密的 NTQQ 本地数据库导出为文本和结构化文件。

适用场景：

主要功能

快速开始

先用合成数据验证脚本，不需要真实 QQ 账号、真实 bak 文件或真实聊天数据库。

git clone https://github.com/zywstudy123/qq-bak-chat-history-export.git
cd qq-bak-chat-history-export

python3 skills/qq-bak-chat-history-export/scripts/create_synthetic_ntqq_fixture.py \
  --out-dir /tmp/ntqq-fixture

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /tmp/ntqq-fixture \
  --list-groups

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /tmp/ntqq-fixture \
  --chat-type group \
  --peer 123456 \
  --self-uin 100000 \
  --out-dir /tmp/ntqq-export \
  --prefix synthetic \
  --keywords onboarding \
  --date 2023-11-14

预期输出：

synthetic_full.txt
synthetic_full.json
synthetic_full.csv
synthetic_summary.txt
synthetic_daily_counts.csv
synthetic_keyword_hits.txt
synthetic_keyword_hits.json
synthetic_keyword_hits.csv
synthetic_2023-11-14.txt
synthetic_2023-11-14.json
synthetic_2023-11-14.csv

真实 bak 文件流程

QQ .bak 文件
    ↓
QQ 官方导入历史聊天记录
    ↓
本机 NTQQ nt_db 数据库
    ↓
本地解密为 SQLite
    ↓
导出 TXT / JSON / CSV
    ↓
交给 agent 搜索、总结、整理

操作步骤：

1. 登录能导入该备份的 QQ 账号。
2. 在 QQ 的聊天记录管理界面导入 .bak 文件。
3. 打开目标群聊或私聊一次，让 QQ 加载消息。
4. 找到本机 NTQQ 的 nt_db 目录。
5. 使用本地解密工具把数据库解密成普通 SQLite 文件。
6. 对解密后的目录运行本项目导出脚本。

解密后的目录通常包含：

nt_msg.db
group_info.db
profile_info.db

导出命令

列出群聊：

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --list-groups \
  --query "关键词"

导出一个群聊：

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --chat-type group \
  --peer GROUP_UIN \
  --self-uin YOUR_UIN \
  --out-dir /path/to/output \
  --prefix group_export \
  --keywords "入职,体检,宿舍" \
  --date YYYY-MM-DD

导出一个私聊：

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --chat-type c2c \
  --peer TARGET_NT_UID_OR_UIN \
  --self-uin YOUR_UIN \
  --out-dir /path/to/output \
  --prefix c2c_export

导出导入后新增消息：

python3 skills/qq-bak-chat-history-export/scripts/export_ntqq_chat.py \
  --db-dir /path/to/post_import_decrypted_nt_db \
  --pre-msg-db /path/to/pre_import/nt_msg.db \
  --chat-type group \
  --peer GROUP_UIN \
  --out-dir /path/to/output \
  --prefix group_after_import

输出格式

安装为 Codex Skill

本仓库同时提供可安装的 Codex Skill。安装后可以让本地 agent 自动执行 QQ bak 聊天记录导出流程。

mkdir -p ~/.codex/skills
cp -R skills/qq-bak-chat-history-export ~/.codex/skills/

使用示例：

使用 $qq-bak-chat-history-export，把这个已解密 NTQQ 数据库里的群聊导出为 txt/json/csv。

目录结构

qq-bak-chat-history-export/
├── README.md
├── README_EN.md
├── LICENSE
└── skills/
    └── qq-bak-chat-history-export/
        ├── SKILL.md
        ├── agents/openai.yaml
        ├── references/schema.md
        └── scripts/
            ├── create_synthetic_ntqq_fixture.py
            └── export_ntqq_chat.py

常见问题

开发者与贡献者

维护者：@zywstudy123

欢迎提交 Issue 和 Pull Request，尤其是以下方向：

致谢

免责声明

本项目仅用于导出和整理使用者有权访问的本机聊天记录备份。请遵守当地法律法规、平台服务条款和数据授权边界。项目不提供 QQ 官方服务，不隶属于腾讯，不对任何账号、数据或法律后果承担责任。

License

MIT © 2026