qq-bak-chat-history-export

name	qq-bak-chat-history-export
description	Export QQ bak files, imported QQ chat history, local Tencent QQ / NTQQ nt_db directories, and decrypted NTQQ SQLite databases into agent-readable TXT, JSON, and CSV files. Use when the task involves QQ .bak recovery, QQ聊天记录导出, QQ聊天记录转txt/json/csv, NTQQ nt_msg.db inspection, local chat search, summarization, or preparation for AI agent analysis.

QQ Bak Chat History Export

Overview

Use this skill to turn QQ bak backups, imported QQ chat history, and decrypted NTQQ databases into files an agent can read safely: plain text for review, JSON for programmatic analysis, CSV for spreadsheets, and smaller derived views such as daily counts or keyword hits.

Work locally by default. The expected output is a local export folder containing TXT, JSON, CSV, summary, date slices, keyword hits, or post-import diff files.

Workflow

1. Identify the input source:

   • .bak archive: prefer official QQ import first, then export from the current NTQQ database.
   • raw nt_db directory: decrypt it with a runtime key.
   • already decrypted SQLite files: export directly.

2. Locate the NTQQ database directory. Typical macOS location:

~/Library/Containers/com.tencent.qq/Data/Library/Application\ Support/QQ/nt_qq_*/nt_db

3. If raw databases are encrypted, obtain the user's local NTQQ runtime database key. Do not print or commit the key. If an existing tool such as qq-cli, QQDecrypt, or another local key scanner is available, use it. Keep the key in an environment variable.

4. Decrypt the required databases locally:

   • nt_msg.db for message rows.
   • group_info.db for group names and group member names.
   • profile_info.db for friend names and UIN mappings.

5. Discover the target chat:

   • Use scripts/export_ntqq_chat.py --list-groups to find a group.
   • Use scripts/export_ntqq_chat.py --list-c2c to find a one-to-one chat.

6. Export the chat with scripts/export_ntqq_chat.py to TXT, JSON, and CSV.

7. Generate optional local views:

   • daily counts,
   • one-day extracts,
   • keyword hit files,
   • new-message diffs against a pre-import snapshot.

Official Import Path For .bak

Use this when the user has a QQ .bak backup that cannot be read directly or only re-exports as .bak:

1. Open QQ with the same account that created or owns the backup.
2. Use QQ's chat history management UI to import the .bak.
3. Wait until QQ reports the import has completed.
4. Open the target chat once so QQ loads the message list.
5. Re-decrypt the current nt_db directory and export from the local database.

Do not assume the .bak can be decrypted with the current NTQQ key. Some backups contain additional QQ-specific wrapping. If direct .bak probing fails, treat official import plus local database export as the reliable path.

Decryption Notes

NTQQ databases commonly use SQLCipher with a 1024-byte QQ header. If manually decrypting:

tail -c +1025 nt_msg.db > nt_msg.clean.db

sqlcipher nt_msg.clean.db <<'SQL'
PRAGMA key = 'REPLACE_WITH_LOCAL_PKEY';
PRAGMA cipher_page_size = 4096;
PRAGMA kdf_iter = 4000;
PRAGMA cipher_hmac_algorithm = HMAC_SHA1;
PRAGMA cipher_default_kdf_algorithm = PBKDF2_HMAC_SHA512;
ATTACH DATABASE 'nt_msg.plain.db' AS plaintext KEY '';
SELECT sqlcipher_export('plaintext');
DETACH DATABASE plaintext;
SQL

Prefer an existing local decrypt tool if available. This skill's bundled exporter expects decrypted SQLite files.

Export Commands

List groups:

python3 scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --list-groups

List one-to-one chats:

python3 scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --list-c2c

Export a group by group UIN:

python3 scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --chat-type group \
  --peer 123456789 \
  --self-uin 100000000 \
  --out-dir /path/to/output \
  --prefix group_123456789 \
  --keywords "onboarding,medical check,apartment"

Export a one-to-one chat by NT UID or UIN:

python3 scripts/export_ntqq_chat.py \
  --db-dir /path/to/decrypted_nt_db \
  --chat-type c2c \
  --peer u_xxxxxxxxxxxxxxxxxxxxx \
  --self-uin 100000000 \
  --out-dir /path/to/output \
  --prefix c2c_target

Compare against a pre-import decrypted message database:

python3 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 123456789 \
  --out-dir /path/to/output \
  --prefix group_after_import

Output Files

The exporter writes:

File	Purpose
<prefix>_full.txt	Chronological readable transcript
<prefix>_full.json	Structured messages for agent processing
<prefix>_full.csv	Spreadsheet-friendly table
<prefix>_summary.txt	Counts, date range, and export metadata
<prefix>_daily_counts.csv	Message counts by date
<prefix>_keyword_hits.*	Optional keyword-focused files
<prefix>_<date>.*	Optional single-day files when --date is set
<prefix>_new_after_import.*	Optional diff files when --pre-msg-db is set

Local Data Handling

• Keep QQ databases, decrypted SQLite files, runtime keys, and exported transcripts on the user's machine unless the user explicitly asks for another destination.
• Put generated files in a clear output directory, then report the output paths and file count.
• If the user asks for agent reading, prefer *_full.txt for direct reading and *_full.json for structured processing.
• If the user asks for only relevant content, use --keywords, --date, or --pre-msg-db instead of exporting unnecessary scope.

When To Read References

Read references/schema.md when modifying SQL queries or adapting the exporter to a new NTQQ schema version.