QQ Suite 是一个 Windows 本地 NTQQ 聊天记录整理工具：从指定群聊按日期导出消息，调用 OpenAI-compatible API 生成中文日报，并在浏览器中预览、下载 Markdown 与 Figma 风格 PNG 长图。
所有数据库、聊天记录、报告、API Key 和数据库密钥均保留在本机，默认不会进入 Git。
- 本地 Web UI，中文界面与实时执行日志
- 根据群名称识别群号，并校验群名/群号一致性，避免跨群混入
- 按群号和日期精确导出 NTQQ 群消息
- 支持开始时间、结束时间和指定成员筛选
- 支持 DeepSeek、NewAPI 及其他 OpenAI-compatible API
- 长聊天自动裁剪并在模型 context window 不足时压缩重试
- Markdown 渲染预览，不显示源码标记
- 每次总结同步生成 Figma 风格 PNG 报告
- 表单自动缓存于浏览器
localStorage
启动后访问 http://127.0.0.1:8765/。如果端口占用，程序会继续尝试 8766～8774。
页面左侧填写 AI、聊天范围和导出选项；右侧显示生成日志、Markdown 渲染预览以及报告下载按钮。
- Windows 11（当前主要验证平台）
- Python 3.12+
- uv（重新导出时用于运行 Python 3.14 的结构化转换器）
- 已登录并产生本地消息的 NTQQ
- 16 字节 NTQQ 数据库密钥
- 可用的 OpenAI-compatible API Key
硬件要求不高；数据库首次解密和结构化导出会占用数 GB 磁盘空间。
git clone --recurse-submodules https://github.com/raclen/qq-suite.git
Set-Location .\qq-suite如果已经普通克隆：
git submodule update --init --recursivewinget install --id Astral-sh.uv -e重新打开 PowerShell，确认：
uv --version双击 start_web.bat，或在 PowerShell 执行：
.\start_web.bat脚本会创建 qq-daily/.venv、安装依赖并打开浏览器。
- 填写 Provider、API Key、模型和 Base URL。
- 填写群名称与精确群号。
- 选择日期；按需填写开始/结束时间。
- 首次使用或需要最新记录时，勾选“重新导出聊天记录”。
- 填写 16 字节 NTQQ 数据库密钥。
- 点击“生成聊天总结”。
勾选重新导出后，程序依次执行：
定位 nt_msg.db
→ 剥离 1024 字节 NTQQ 自定义头
→ SQLCipher 解密为明文 SQLite
→ Protobuf 结构化转换
→ 按群号与日期导出 JSON
→ 调用 AI 生成 Markdown
→ 渲染 PNG
项目以 Git submodule 引入 QQBackup/qq-win-db-key。Windows NTQQ 脚本位于：
third_party/qq-win-db-key/scripts/windows/ntqq/windows_ntqq_get_key.ps1
请按该项目 README 和许可证说明使用。数据库密钥只随当前 Web 请求传给本地子进程，不写入 config.local.yaml。
页面中的“QQ 数据库路径”可以留空，程序会查找：
%USERPROFILE%\Documents\Tencent Files\<QQ号>\nt_qq\nt_db\nt_msg.db
%USERPROFILE%\Documents\Tencent Files\<QQ号>\nt_qq\nt_data\nt_msg.db
存在多个 QQ 账号时，建议填写 nt_msg.db 的完整路径。
页面字段会缓存到浏览器。命令行模式可复制模板：
Copy-Item .\qq-daily\config.yaml.example .\qq-daily\config.local.yaml示例：
ai:
provider: newapi
api_key: YOUR_API_KEY
model: YOUR_MODEL
base_url: https://YOUR_HOST/v1
max_tokens: 8000
qq:
db_path: C:\Users\YOUR_NAME\Documents\Tencent Files\YOUR_QQ\nt_qq\nt_db\nt_msg.db
export_limit: 100000
chat_summary:
chat_name: 示例交流群
chat_id: "123456789"
date: "2026-08-13"
mode: group
speaker: ""
start_time: ""
end_time: ""
render_png: true
input_json: ""命令行运行：
.\run.bat --cli config.local.yamlqq-suite/
├─ qq-daily/ # AI 总结、Web UI、Markdown/PNG 渲染
├─ qq-export/ # 旧版直接导出接口，保留兼容
├─ scripts/ # 项目包装脚本
├─ third_party/
│ ├─ nt_msg_db_util/ # GPL-3.0，解密与 Protobuf 结构化转换
│ └─ qq-win-db-key/ # 上游自定义非商用许可，密钥提取工具
├─ data/ # 本地数据库和聊天 JSON，不提交
├─ temp/ # 临时文件，不提交
├─ refresh_chat_export.py # Web 重新导出编排
├─ start_web.bat # Windows Web UI 入口
└─ PROJECT_RULES.md # 项目长期开发规则
| 路径 | 内容 |
|---|---|
data/nt_msg_plain.db |
解密后的明文 SQLite |
data/nt_msg_export.db |
结构化消息数据库 |
data/chat-<群号>-<日期>.json |
指定群/日期聊天记录 |
qq-daily/group_daily_exports/*.md |
Markdown 总结 |
qq-daily/group_daily_exports/*.png |
PNG 报告 |
这些目录和文件都已加入 .gitignore。
群聊必须使用精确群号。当前版本会从明文联系人库读取群名/群号映射：
- 只填精确群名且匹配唯一时，自动识别群号；
- 群名与群号不一致时直接停止；
- 旧 JSON 只有群号和日期都匹配时才会复用。
程序默认限制输入字符数，并在上游仍返回 context window 错误时自动进一步压缩。也可以在本地配置设置：
ai:
input_char_limit: 12000git submodule update --init --recursive首次解密会完整扫描本地数据库，数百 MB 数据通常需要数分钟。页面会持续显示后端日志，请保持页面和启动窗口打开。
- 不要提交
config.local.yaml、.env、数据库、聊天 JSON、报告或日志。 - API Key、数据库密钥和聊天内容属于敏感数据。
- Web 服务仅监听
127.0.0.1，不要改为公网监听。 - 如果密钥曾出现在公开提交中，应立即轮换相应 API Key。
- 主项目代码：MIT，见 LICENSE。
third_party/nt_msg_db_util：上游 QQBackup/nt_msg_db_util，GPL-3.0，以 submodule 形式保留上游许可证。third_party/qq-win-db-key：上游 QQBackup/qq-win-db-key，使用其仓库内自定义非商用许可证。
使用第三方组件时，以各自目录中的许可证为准。
.\qq-daily\.venv\Scripts\python.exe -m py_compile `
.\qq-daily\main.py `
.\qq-daily\web_ui.py `
.\qq-export\qq_exporter.py `
.\refresh_chat_export.py `
.\scripts\decrypt_ntqq.py修改 qq-daily/web.html 的内联 JavaScript 后，还应抽取 <script> 内容并运行 node --check。
MIT © QQ Suite Contributors