QQNT Toolbox

面向 LiteLoaderQQNT 的 QQNT 功能扩展，集中提供消息处理、本地贴纸、媒体预览、语音工具、阻止撤回、互动功能和界面调整。

下载最新版本 · 安装与更新 · 功能概览 · 问题反馈

Caution

传播与官方渠道

• 不要在国内平台宣传、推荐或传播本插件。
• 不要在 QQ 官方群聊中发送任何能明显看出你使用了第三方插件的截图、录屏或其他内容，也不要将此类材料提交到 QQ 官方客服与反馈渠道。
• 插件问题请仅通过本仓库的 Issues 反馈，不要将第三方插件导致的现象提交给 QQ 官方渠道。

Warning

第三方插件风险

QQNT Toolbox 是非官方项目，与腾讯、QQ 和 LiteLoaderQQNT 项目方不存在隶属或担保关系。使用第三方插件可能带来账号、隐私、数据和兼容性风险，请自行判断并承担后果。请勿利用伪造合并转发、自定义图片外显、自动回应等功能冒充他人、实施欺诈、骚扰他人或制造误导内容。

使用须知

• 首次安装时，除悬浮工具箱入口外，所有会修改消息、菜单或界面的功能均为关闭状态。
• 插件依赖 QQNT 内部接口和页面结构，QQ 更新可能造成部分功能临时失效；更新 QQ 前建议确认最新 Release 和 Issues。
• 当前主要在 Windows QQNT 上开发和测试。插件清单同时声明支持 Linux 和 macOS，少数依赖 Windows 原生接口的功能会明确标注平台限制。
• 仅从本仓库 Releases 获取安装包；更新或排查问题前建议备份 LiteLoaderQQNT/data/qqnt_toolbox。
• 不要同时启用多个插件中的同类功能，重复注入消息菜单、阻止撤回、复读或界面精简可能造成冲突。

安装与更新

环境要求

• 使用 QQNT 客户端，并已正确安装支持 Manifest V4 插件的 LiteLoaderQQNT。
• 语音发送、音视频转换、音视频发送修复和部分语音预览需要 FFmpeg。
• Release 压缩包已经包含 silk-wasm 和加密 ZIP 组件，普通用户不需要安装 Node.js，也不需要执行 npm install。

检查 FFmpeg

在终端执行：

ffmpeg -version

能够显示版本信息即表示配置成功。也可以设置环境变量 FFMPEG_PATH，其值为 ffmpeg.exe 的完整路径，例如：

C:\ffmpeg\bin\ffmpeg.exe

设置环境变量后需要完全退出并重新启动 QQ。

手动安装

1. 完全退出 QQ。

2. 从 Releases 下载最新的 QQNT-Toolbox-v*.zip。

3. 解压后，将其中的 QQNT-Toolbox 文件夹放到 LiteLoaderQQNT/plugins。

4. 确认最终路径中直接存在 manifest.json：

   LiteLoaderQQNT\plugins\QQNT-Toolbox\manifest.json
   

5. 重新启动 QQ。

更新插件时同样建议先退出 QQ，再覆盖 QQNT-Toolbox 插件目录。用户配置和语音库位于 LiteLoaderQQNT 的 data 目录中，正常覆盖插件目录不会删除这些数据。

插件内更新

“其他 > 插件更新”提供手动检查与重启安装：

• “启动时检查更新”默认关闭；开启后每 12 小时最多通过 GitHub Releases API 检查一次。默认匿名访问；匿名 API 限流时会自动改用公开 Release 页面定位版本，不填写令牌也可以更新。也可在“其他 > 网络”填写 GitHub 令牌提高 API 限额。
• 手动点击“检查更新”会立即刷新版本状态，不受上述时间间隔限制。
• 发现更高版本后，点击“下载更新”会下载 Release ZIP，并校验资产大小（公开页面未提供时校验实际下载内容）、GitHub 提供的 SHA256（若有）、ZIP 路径、插件标识、版本号和关键运行文件。
• 校验完成的更新先进入 data\qqnt_toolbox\updater 暂存目录，不会覆盖正在运行的插件。
• 点击“重启安装”后，Toolbox 会先确认更新助手已启动，再退出 QQ。助手等待本次 QQ 完全退出后，在原插件目录中交换完整版本；失败时恢复旧版本，完成安装或回滚后才重新启动 QQ。
• 自动更新不会再按版本创建新目录。已有 QQNT-Toolbox-v* 目录会保留当前名称并原位更新；全新手动安装使用固定的 QQNT-Toolbox 目录。
• “其他 > 网络”可填写统一代理地址并配置可选的 GitHub 下载镜像；代理地址留空时跟随系统网络设置。GitHub 令牌只发送给 GitHub API，不会发送给第三方镜像。
• 使用旧版更新器的用户需要从 GitHub Releases 手动安装一次新版；项目不再提供 update.json 兼容迁移。
• Windows、Linux 和 macOS 共用同一套 JavaScript 更新助手；它由 QQ 自带的运行时执行，不要求另外安装 Node.js、PowerShell 或 shell 工具。

快速开始

• 在 QQ“设置”中打开 QQNT Toolbox 设置页，按需启用功能。
• 默认按键盘右侧的 Ctrl（RCtrl）打开或关闭悬浮工具箱。
• 拖动标题栏可以在当前 QQ 窗口内移动面板。
• 点击右上角关闭按钮只会隐藏面板，不会退出插件。
• 分组标题可以展开或折叠，面板内容区域支持滚动。
• Toolbox 自有窗口统一使用不占布局宽度的 QQ 风格悬浮滚动条；内容可滚动时，滚动或将鼠标移到边缘即可看到滑块。
• 在可见的 Toolbox 面板或对话框中按 Esc 可以关闭当前界面；正在录入快捷键时按 Esc 仍会取消录入。
• 大多数开关会立即生效；依赖消息重新渲染的选项可能需要切换一次会话或重启 QQ。
• “其他 > 悬浮窗”可以关闭悬浮工具箱或重新绑定唤出快捷键；绑定过程中按 Esc 取消。

功能概览

类别	主要功能
消息与发送	文件发送修复、NoSeq 提示、消息转图片、消息复读、伪造合并转发、移除回复 @、自定义图片外显
本地贴纸	本地贴纸包、最近使用、入口替换、点击直发、Telegram 贴纸下载
媒体与语音	TG 样式媒体预览、语音消息发送、离线语音库、在线音源、语音保存与转发
阻止撤回	消息保留、可选标记、黑白名单、群文件自动暂存与归档、撤回记录持久化与独立查看器
娱乐互动	表情回应解限、回应面板保持、自动回应、戳戳、窗口抖动
界面与菜单	消息、头像与会话列表菜单排序、完整未读数、二维码识别、单窗口预览、界面精简
维护与诊断	插件内更新、配置持久化、诊断报告、日志轮转与隐私脱敏

详细功能

文件发送修复

开启“消息相关 > 文件发送修复”后，插件会监听发送状态为 Failed / NoSeq 的受支持文件消息，并按类型生成内容不同的本地变体，再向原会话重试一次。

• 整个过程自动完成，不需要手动重新发送。
• 图片：无损重写 PNG 的压缩表示并加入随机数据；每次文件哈希不同，但解码后的像素完全不变。
• 视频：使用 FFmpeg 无损重封装，只复制原码流；原消息是 QQ 原生视频时仍按视频重发，原消息是带视频预览的文件时仍保留该预览样式，两者都会使用模糊化的新封面。
• 音频：使用 FFmpeg 无损重封装并保持音频文件形式；音视频都会校验前后时长不变。
• 其他文件：生成同名 AES-256 加密 ZIP；ZIP 内保留原文件名，密码在工具箱面板中设置。
• 图片、视频、音频和其他文件可以分别开关；首次安装时这些选项均关闭，未设置密码时不会重试其他文件。
• “自动删除失败消息”默认关闭；开启后，只有替代消息被 QQ 确认为发送成功，插件才会删除本地的原失败条目。
• 压缩密码保存在插件的 config.json 中，请不要复用重要账户密码。
• 每条失败消息只重试一次，避免循环发送。

提示 NoSeq 消息

开启“消息相关 > 提示 NoSeq 消息”后，插件会给 sendStatus 为 NoSeq 的非灰条消息添加一个小型感叹号标记。鼠标悬停标记时会显示“这条消息可能未成功发送（NoSeq）”。

NoSeq 通常表示消息在弱网环境下可能没有成功发送，或者被服务器拦截。这个功能只负责提示，不会自动修改或重发消息；文件消息的自动重试由上面的“文件发送修复”单独控制。

消息转图片

开启“消息相关 > 消息转图片”后，消息右键菜单会增加“转图”。如需批量转换，先使用 QQ 原生“多选”勾选消息，再点击底部操作栏中的“转图”；所选消息会按聊天顺序合成为一张 PNG。

该功能会在离屏区域复制、清理并重新排版 QQ 已渲染的消息 DOM，而不是截取当前窗口。它可覆盖文本、图片、视频缩略图、文件、语音、回复、卡片及混合消息，并会排除 QQ 多选灰层、+1 和 Toolbox 控件。“仅包含消息”默认开启，因此不会保留精华标记与表情回应；关闭后可将这些消息附加信息一并导出。包含聊天背景时默认按消息范围紧凑裁剪，开启“包含背景留白”后才会保留消息外侧的完整会话宽度。尚未加载完成的媒体会按当时界面中的加载状态输出。

生成结果会直接保存到指定目录，默认位置为 data\qqnt_toolbox\message-images，同名文件会自动追加序号。默认命名为 {source}-{yyyy}{MM}{dd}-{HH}{mm}{ss}：{source} 会规范生成为“昵称(QQ号)”“群名(群号)”“多人消息”或“未知来源”。设置中还可使用 {yyyy}、{MM}、{dd}、{HH}、{mm}、{ss}、{count}、{qq_number}、{nickname}、{group_number}、{group_name} 自定义格式。单条消息或同一发送者的多条消息只填充发送者占位符；群聊中包含多位发送者时只填充群聊占位符。还可选择生成后自动复制到剪贴板。保存完成后会以轻量提示显示结果，不再弹出另存为窗口。

点击“管理图片”可打开独立管理页面，对已保存图片进行预览、复制、重命名、删除、分类和排序。保存目录根层级的 PNG 属于“未分类”，每个一级文件夹对应一个分类；在面板中移动或重命名分类时，磁盘上的图片和文件夹也会同步变化。也可以直接在保存目录中建立一级文件夹，刷新管理页面后会自动识别。

自定义图片外显

开启“消息相关 > 自定义图片外显”并填写“外显文字”后，发送图片时会将图片消息的摘要替换为指定文字。该功能只修改图片消息的外显摘要，不修改图片文件、画质或缩略图；外显文字留空时不作修改。

移除表情回应限制

开启“娱乐互动 > 移除表情回应限制”后，会在 QQ 原生回应面板中补回默认被隐藏的 Unicode emoji，不再限制面板内可选的回应表情。表情 ID、名称与图片直接读取 QQ 数据目录中的 face_config.json 和 emoji_res，不会下载或内置另一套表情包；最近表情及其排序仍完全由 QQ 管理。

回应后不关闭回应窗口

开启“娱乐互动 > 回应后不关闭回应窗口”后，点击任意原生或补全表情都不会关闭回应面板，便于连续添加或取消回应。该开关独立于“移除表情回应限制”；关闭时，补全表情也会与 QQ 原生表情一样在回应后收起面板。

自动回应表情

开启“娱乐互动 > 自动回应表情”后，可选择多个回应表情，并按“@ 自己”“回复自己”或“自己的每条消息”自动回应群消息；启用多个条件时，满足任意一个即可触发。“排除 @ 全体成员”优先于其它条件。每次触发会添加全部已选表情，自己的消息会在 QQ 确认发送成功后再回应。

开启“娱乐互动 > 发送窗口抖动”后，好友私聊输入栏会显示一个原生样式按钮；每次点击发送一条 QQ 窗口抖动消息。群聊、频道和临时会话不提供该入口。

消息复读

开启“消息相关 > 复读”后，可选择以下一种入口：

• 关闭“右键菜单”：鼠标悬停消息时，在消息旁显示 +1。
• 开启“右键菜单”：隐藏消息旁的 +1，在消息的 QQ 原生右键菜单中显示“复读”；合并转发详情中的嵌套聊天记录卡片原本没有右键菜单，Toolbox 会为它补充同样样式的单项“复读”菜单。

“双击复读”只作用于消息旁的 +1，用于减少误触。右键菜单模式仍然是单击“复读”后发送。

复读会尽量保留原始消息元素，包括群聊中的真实 @ 信息、合并转发聊天记录，以及尚未下载到本地的文件和视频。语音消息会作为原生 PTT 复读。插件不会在消息元素不完整时偷偷发送残缺内容；无法完整复读时会终止本次操作。

消息旁的 +1 和撤回标记以真实消息气泡为定位基准。显示发送时间、展开语音转文字等附加内容不会再将它们推离消息气泡。

伪造合并转发

开启“消息相关 > 伪造合并转发”后，聊天输入功能栏会显示对应入口。可为每条消息填写发送者 QQ、显示昵称、时间和消息内容，支持文字与多图组合，以及单独的视频、文件或聊天记录，并可调整消息顺序后发送到当前好友或群聊。

右侧空白编辑区就是普通消息的新增入口；填写发送者和内容后点击“添加消息”即可。左侧只保留“添加子合并”入口，点击后进入子合并编辑，其中至少需要添加一条消息；点击“完成此子合并”后，它会立即作为一张子合并草稿卡片加入父层，即使还没有填写显示发送者，也可以继续创建下一张同级子合并。之后点击左侧标记为“待填写显示信息”的卡片，补充发送者 QQ 和昵称，再点击“保存显示信息”即可。只有在子合并内部点击“添加下一级”时，才会继续向下嵌套。记录通过 QQ 原生合并转发结构生成，最多嵌套 3 层，整棵记录最多包含 300 条消息。

编辑内容只在本地生成，并通过 QQ 原生合并转发接口发送，不会提交给第三方聊天记录生成服务。未发送的消息列表会按当前账号保留为草稿。

本地贴纸

开启“本地贴纸”后即可使用。Toolbox 会自动在自身数据目录下创建 stickers 作为默认贴纸目录；已有自定义目录会原样保留，不会迁移文件。目录本身及其子目录中的 png、jpg、jpeg、gif、webp 图片会按文件夹组成贴纸包。入口可以选择以下三种模式：

• 右键 QQ 原版“表情”按钮打开本地贴纸，原按钮左键行为保持不变。
• 用本地贴纸面板替换原版“表情”按钮的左键行为。
• 在聊天输入功能栏中显示独立的“本地贴纸”按钮；独立入口可以移动到功能栏左侧。

一级设置只保留启用方式和入口选择，其余内容集中在“管理本地贴纸”页面：

• “贴纸集”可直接打开、更改或刷新目录，并拖动调整贴纸集顺序。
• “面板”包含每行数量、面板尺寸、发送形式和最近使用设置。
• “Telegram”负责下载贴纸包，并直接显示所需的转换工具配置。

“直接发送方式”可在 Alt + 单击（默认）与“单击”之间选择，本地贴纸以及 QQ 原生面板中除“默认表情”外的收藏表情、贴纸包和图片表情共用这一设置；未匹配直发手势时仍会插入当前 QQ 输入框。按住 Ctrl 操作本地贴纸后会保持面板打开。“发送形式”选择“贴纸”时使用 QQ 贴纸子类型，选择“图片”时按普通图片发送。最近使用记录保存在所选目录的 recentStickers.json 中；插件只在面板打开或手动刷新时扫描目录，不会常驻监听整个文件树。

“贴纸集排序”会打开独立管理页，可拖动贴纸集调整顺序，也可直接展开任一贴纸集并删除单张贴纸，或从标题行删除整个贴纸集；删除后会同步清理最近使用记录。“Telegram 贴纸”页支持填写 t.me/addstickers/... 链接下载普通贴纸包，并提供以下配置：

• Telegram Bot Token：在 Telegram 中通过 @BotFather 获取，只保存在 Toolbox 本地配置中。
• FFmpeg：用于将带 Alpha 的 Telegram WebM 视频贴纸转换为透明 GIF，并为保留为 WebM 的贴纸生成发送预览图；路径留空时自动从 PATH 查找。不带 Alpha 的视频贴纸仍原样保存为 WebM。
• tgsToGif：用于把 TGS 动画贴纸转换为 GIF；路径留空时自动从 PATH 查找，可从 tgs_to_gif Releases 下载，未找到时会跳过 TGS。

Telegram 贴纸下载与插件更新共用“其他 > 网络”中的代理地址，支持 HTTP、HTTPS 和 SOCKS。地址留空时会优先读取可用的代理环境变量，再使用 Chromium 的系统代理/PAC。这些设置只作用于 Toolbox 发起的网络请求，不会修改 QQ 的全局网络设置。

Telegram 下载结果直接保存在所选贴纸目录内，不建立额外缓存目录。单个贴纸、整包大小、贴纸数量、并发数与请求时间均有上限；Bot Token 不会写入 Toolbox 诊断日志。

每个贴纸包目录可放置可选的 sticker.json：

{
  "label": "贴纸包名称",
  "index": 10,
  "icon": "cover.png"
}

label 控制显示名称，index 控制贴纸包顺序，icon 必须指向同一目录内的受支持图片。

移除回复 @

开启“消息相关 > 移除回复 @”后，回复消息时会移除 QQ 自动附带的 @ 标记；回复后仍可主动 @ 其他成员。

发送音频或视频中的声音

1. 在目标聊天中打开 QQ 原版“语音消息”输入面板。
2. 将音频或视频文件拖入这个语音面板。
3. 插件只取第一条音轨并发送到当前会话；拖放默认使用“转换发送”。

支持的常见音频格式包括 aac、amr、flac、m4a、mp3、ogg、opus、wav、weba、webm；常见视频格式包括 avi、flv、mkv、mov、mp4、mpeg、ts、webm、wmv 等。

注意：

• 文件必须拖到已经打开的 QQ 原版语音面板，而不是聊天空白处或普通文件发送区域。
• 拖放成功后会直接发送，不需要再点击 QQ 的发送按钮。
• 视频只提取音轨，不会发送视频画面；视频音轨同样支持“转换发送”和“保留原编码”。
• “转换发送”会将音频（包括视频中的音轨）转换为 QQ 桌面端兼容的 Silk/PTT；“保留原编码”会尽量不重新编码，视频仅做无损抽取音轨。
• 聊天中自己或他人发送的非 Silk/AMR 语音可直接点击原语音气泡播放；插件仅在确认 QQ 桌面端不支持该编码后透明接管，不增加额外按钮或窗口，也不会改变原生语音的播放方式。
• 新发送的语音会根据实际音频振幅生成波形，不再复用固定波形。
• 可在“消息相关 > 语音消息 > 修改语音时长”中将显示时长设为 1–300 秒；该设置只改变消息气泡的显示时长和宽度，不改变实际播放长度。
• 插件会自动跟随 QQ 设置中的“聊天消息保存目录”；自定义盘符、中文或空格路径无需建立目录链接。
• 不要手动把 .silk 文件再次拖入 QQ。

语音库

在聊天输入区右键 QQ 原版“语音消息”图标，可以打开语音库窗口。

• “选择发送”：先选“转换发送”或“原格式发送”，再选择本地音频或视频直接发送到当前会话，不加入语音库。
• “添加到语音库”：选择文件并保存原始媒体到当前语音库文件夹，之后可在文件菜单中按需选择发送方式。
• 点击文件夹行即可进入，顶部返回按钮可以回到上级目录；面板内可以新建文件夹。
• 底部播放器始终可见，支持播放、暂停、拖动进度和上/下一首；切换文件夹、离线/在线视图或重新搜索不会丢失当前播放项。尚未播放时播放器保持空闲状态，不会虚构选中项。
• 点击文件行即可预览。播放器发送按钮、文件右键菜单和三点菜单会直接列出可用发送方式；QQ 桌面端已经兼容的语音只显示必要的发送入口，需要兼容处理的音频或视频音轨可选择“转换发送”或“原格式发送”。
• 文件菜单同时支持移动、重命名和删除；删除前会二次确认，文件夹删除会连同其内容一起删除。
• 手动放入 voices 目录的文件或文件夹会在刷新后被识别。
• 音视频的时长统一显示为 00:00 格式；新增或手动放入的媒体会按需读取时长，不会在刷新时一次性转换全部文件。
• 语音面板分为“离线语音库”和“在线音源”两个独立视图：离线搜索只筛选当前语音库文件夹，在线搜索显示歌曲列表；面板会在当前 QQ 运行期间记住关闭前的模式、目录、搜索结果、列表位置、窗口位置和播放器进度。
• 在线页支持推荐、搜索、排行榜和歌单；QQ 音乐与网易云音乐可浏览排行榜、热门/最新歌单及歌单详情。在线歌曲可以试听、按可用方式发送，或下载保存到当前离线语音库；遇到临时失效或 403 的播放地址时会重新解析一次。
• 在 Toolbox 设置的“语音消息 - 在线音源”中导入、刷新或删除音源脚本。支持 LXMusic User API、CeruMusic CommonJS 插件、QT MusicPlugin，以及 MusicFree 插件清单；Toolbox 会在脚本负责解析歌曲地址的前提下，为酷我、咪咕、酷狗、QQ 音乐和网易云音乐提供统一的列表搜索入口。
• MusicFree 的 .json 清单会按条目下载并分别导入模块，清单自身和其中的 yourinfo 不会保存。单个模块导入失败不会影响其他模块；仅提供搜索而未提供音频地址的模块会保留在管理页，但不会出现在可发送的音源选择中。
• Toolbox 不会安装、启动或嵌入 LXMusic、CeruMusic、QT 或 MusicFree，只在受限环境中运行你导入的脚本来搜索或解析音频地址。脚本属于可执行代码，请只导入可信来源。
• 如果脚本自己声明了 search 或 musicSearch，Toolbox 会优先使用脚本返回的完整 musicInfo；没有统一搜索协议且不属于上述内置发现平台的脚本只能用于解析已知歌曲，在线页不会要求用户手填歌曲信息 JSON。
• MusicFree 模块可使用其 search() 与 getMediaSource() 能力；为避免脚本取得本机权限，Toolbox 只提供受限的网络、HTML 解码、表单编码、日期、常用加密和大整数兼容层，不会提供 Node、文件系统或子进程权限。

保存 QQ 语音消息

同时开启“语音消息”和“右键保存语音”后，右键聊天中的语音消息，QQ 原生菜单中会出现“保存”。保存后的文件会进入语音库。

如果 QQ 本地缓存中还没有这条语音，请先播放一次，再重新右键保存。

转发 QQ 语音消息

同时开启“语音消息”和“右键转发语音”后，右键聊天中的语音消息，QQ 原生菜单中会出现“转发”。选择一个或多个好友、群聊后，插件会向目标会话发送原生 PTT 语音消息。

“右键保存语音”和“右键转发语音”是两个独立开关，可以只启用其中一项。

阻止撤回

开启“阻止撤回 > 启用”后，QQ 收到撤回事件时会尽量保留原消息，并在消息附近显示撤回标记。

可选项包括：

• 撤回提示可选择原有图标或气泡描边；图标与描边共用浅色、深色主题颜色。
• 防撤回范围可设为全部、黑名单或白名单；名单管理会读取完整的 QQ 好友与已加入群列表，可搜索、筛选并勾选。
• 拦截自己的撤回操作。
• 持久化保存撤回记录，使其在切换会话或重启后仍可查看。
• 恢复并归档被撤回图片到插件数据目录。
• 设置防撤回保护窗口，范围为 5 分钟至 30 天，默认 24 小时；未在保护期内撤回的暂存资源会自动清理。
• 设置每个账号的暂存总容量，默认 5 GB；容量满时暂停接收新的暂存资源，不会淘汰仍在保护期内的内容，空间释放后会继续处理。
• 打开独立撤回消息窗口，统一查看文本、图片、文件、语音和卡片等内容；支持按群名、群号、发送者、消息文本或文件名搜索，也可以预览图片、播放语音、打开归档文件和定位原消息。
• 打开当前账号的防撤回归档目录，或清理该账号的撤回消息、图片、文件、暂存数据和下载中间文件。

“群文件防撤回下载”与“启用消息防撤回”是两个独立开关，但共用上述保护窗口、暂存容量、归档目录和撤回查看器：

• 只处理功能开启后实时收到的白名单群普通文件；私聊文件、未选择的群、历史消息及开启前已经收到的文件不会被自动下载。未选择任何群时，该功能不会下载文件。
• 文件大小使用包含上下限的闭区间，默认范围为 0.5 KB 至 600 MB；上下限可使用 B、KB、MB 或 GB 表示，支持的单文件最大值为 600 MB。
• 符合条件的文件先下载到插件自有暂存目录。若消息在保护窗口内被撤回，文件会直接从暂存区转入长期归档，不额外复制第二份；若未被撤回，则在保护窗口到期后删除暂存文件。
• 已归档文件会保留到手动清理。恢复后的 QQ 文件卡片继续显示为原生已下载状态，可使用 QQ 的打开文件及在资源管理器或 Finder 中显示等交互，也可从撤回消息查看器直接打开。

撤回记录、图片、文件、暂存区和内存缓存均按当前 QQ 账号隔离，切换账号不会看到或清理其他账号的数据。缺失或不完整的撤回图片会优先尝试 QQ 原生下载，并通过腾讯图片 CDN 作为即时回退；点击定位前会先将当前消息的图片归档到本地，避免原聊天页面持续加载。为补齐腾讯 CDN 所需的全局 rkey，插件使用与 lite-tools 相同的 rkey.furrycloud.top 服务，该请求不包含 QQ 号、消息内容或图片地址。

启用消息防撤回，或启用群文件防撤回下载并选择至少一个群后，Toolbox 会请求系统避免 QQ 在后台被挂起，并在设置中显示后台与暂存状态。macOS 可另行开启“接电关盖继续运行”；首次启用需要管理员授权安装 helper，仅在接通电源且防撤回任务活动时生效，关闭功能、退出 QQ 或卸载 helper 时会恢复系统设置。其他平台不支持关盖 helper，其余防撤回能力不受影响。

已经成功恢复并保存的消息会在聊天列表刷新或重新定位时继续替换 QQ 的撤回占位；后续切换开关或黑白名单只影响新撤回消息，历史恢复消息会保留到手动清理撤回缓存。

阻止撤回只能处理插件启用后捕获到的消息和撤回事件，无法恢复插件安装前已经撤回的内容。自定义颜色修改后，可能需要切换会话或重新加载消息才能看到变化。

戳戳

戳戳功能包括：

• 自动回戳：可分别选择在被戳、消息 @ 自己或回复自己时戳发送者，并可排除 @ 全体成员；连续戳戳互动可设置回戳阈值，0 表示不限制次数。
• 双击头像戳戳：在消息列表中双击用户头像发送戳戳；开启后会替代 QQ 原有的头像点击行为。
• 右键头像戳戳：控制头像右键菜单中的“戳一戳”入口；新旧 QQ 版本均可单独开关。
• 戳戳发送成功后，被戳用户的头像会在本机短暂晃动，作为操作反馈。

临时会话不支持戳戳。插件会识别 QQ 的临时会话类型；开启头像戳戳功能后，临时会话中的双方头像不会显示右键入口，双击也不会发送请求。

QQ 9.9.32-50969 及更新实现优先调用 QQ 自带的戳戳和撤回接口；较早版本使用 Windows x64 原生桥接发送，并由插件为自己发出的戳戳灰条提供撤回入口。QQ 9.9.25-42905 与 9.9.32-50969 已通过实机验证，官方安装包中的 9.9.21-39038 和 9.9.31-49599 已通过静态签名验证；采用相同内部实现的中间版本也可以自动适配。签名不存在或不唯一时桥接会拒绝安装，不会尝试未知地址。其他操作系统上的旧版戳戳桥接不可用，其余 Toolbox 功能不受此限制。

界面调整

“界面调整”中目前包含：

• TG 样式媒体预览：以单个独立全屏窗口接管 QQ 原本的图片和视频打开请求；未下载媒体会继续调用 QQ 原生下载，并只预加载当前项前后各一项。支持按钮、方向键或滚轮切换媒体，使用 Ctrl + 滚轮 缩放，放大后可拖动，右下角可旋转媒体；更多菜单和媒体右键菜单可复制图片或视频当前帧。视频音量和静音状态会分别记忆；普通预览播放时保留底部播放条并自动淡出周边控件，全屏播放时整套控件都会自动隐藏，移动鼠标即可恢复。单击空白或按 Esc 关闭，单击视频切换播放；可在缩进子项中选择透明、白色、半透明或黑色背景。
• 以图片方式打开表情：开启后，点击消息中的商城表情图像会调用图片查看流程；若同时开启 TG 样式媒体预览，则由 TG 查看器承接。普通小黄脸、头像、回复缩略图和消息空白区域不受影响。
• 单击查看媒体：只把消息中图片和视频（包括 Markdown 消息内的图片）的打开手势改为单击，不指定查看器；使用 QQ 原生查看器或 TG 样式媒体预览时均独立生效。
• 显示完整未读数：消息列表直接显示真实未读数量，不再以 99+ 封顶；仅改变徽标显示，不修改未读状态。
• 自定义菜单排序：分别管理消息、头像与会话列表右键菜单；各类顺序互不影响，基础项目会直接列出，QQ 新增或条件菜单项会在出现后自动补充。未保存自定义顺序的类别始终保持 QQ 原顺序，原生分隔线也可独立移动。
• 图片查看器优化：仅作用于 QQ 原生图片查看器，支持点击空白关闭和拖动图片窗口；TG 查看器不依赖此开关。
• 二维码主动识别：开启后在消息菜单、QQ 原生图片查看器和 TG 样式媒体查看器中提供“识别二维码”，仅在点击时识别，不干预 QQ 自带的二维码识别。
• 单窗口媒体预览：打开新图片或视频时关闭旧的 QQ 媒体预览窗口，避免预览进程不断累积。
• 单窗口预览合并转发：同一范围内新打开的外层记录会替换旧记录；记录内部继续打开合并转发时，关闭当前窗口会返回上一级。可选“群聊隔离”，让不同群分别保留一个记录窗口，同群的新记录仍会替换旧记录。
• 保持聊天页浏览位置：消息右键菜单或窗口切换后保持当前消息浏览位置；主动滚动、切换会话和消息区尺寸变化不受干预。
• 屏蔽窗口抖动：保留窗口抖动消息，只阻止它触发当前聊天窗口移动；普通戳戳与其它消息不受影响。
• 鼠标侧键返回会话主列表。
• 阻止消息窗口中的误选和误拖。
• 阻止拖拽左侧消息列表中的会话，防止意外拖出独立聊天窗口。
• 禁止输入栏中的表情、截图与文件入口因悬停自动展开，点击打开仍保持 QQ 原有行为。
• 禁止鼠标悬停显示用户与群资料卡，点击操作不受影响。
• 删除消息气泡装扮。
• 隐藏天气、经典模式、帮助、锁定、退出账号、检查更新及更新通知等入口；按控件自身标签识别，不会因消息或会话文案相同而误隐藏内容。
• 隐藏 VIP 彩色昵称。

功能精简

“精简”分为侧边栏、顶部功能栏和聊天功能栏三个区域。这里的开关表示“保留对应项目”：

• 开启某个项目的开关：保留显示。
• 关闭某个项目的开关：隐藏它。

可精简项目会根据当前 QQ 页面动态识别，因此打开菜单时可能需要等待页面元素加载完成。

诊断工具

“其他 > 调试功能”提供一套按需启用的诊断工具。开启“诊断记录”后，插件会记录页面类型、功能开关摘要以及复读、语音、媒体预览、戳戳、防撤回、文件重试等关键操作的结果；关闭后立即停止采集，也不会创建新日志。下方的报告与日志操作在关闭采集时仍可使用。

遇到问题时，先开启诊断记录并复现一次，再使用下方操作：

• 复制诊断报告：将版本、运行环境、功能状态和最近 250 条事件复制到剪贴板，适合直接粘贴到 Issue。
• 导出诊断报告：生成 JSON 文件并在资源管理器中定位。
• 打开日志目录：打开 data\qqnt_toolbox\debug，其中保留当前日志和一份轮转日志。
• 清空诊断记录：删除上述两份日志。

单份日志最多约 1 MiB。诊断内容不会保存消息正文、压缩密码、令牌、完整 QQ/群标识、绝对路径或二进制内容。日常使用建议保持关闭。

开发与发布

在仓库根目录安装依赖后，可以使用以下命令检查和构建：

npm ci
npm run check
node --test test/toolbox-scrollbars.test.js test/voice-media.test.js test/window-overlay-drag.test.js
npm test
npm run release:build

npm run release:build 会读取 manifest.json 和 package.json 的相同版本号，生成 dist/QQNT-Toolbox-v<版本>.zip，并检查发布包中的运行文件和依赖是否完整。dist、release 和压缩包均为构建产物，不应手动提交到 Git。

数据与隐私

插件数据统一存放在：

LiteLoaderQQNT\data\qqnt_toolbox

主要内容：

qqnt_toolbox
├─ config.json                 # 工具箱设置
├─ stickers                    # 默认本地贴纸目录及最近使用记录
├─ message-images              # 默认消息转图保存目录
├─ message-image-library.json  # 消息图片分类顺序与图片排序信息
├─ debug                       # 启用诊断记录后按需创建
├─ updater                     # 下载并校验通过的待安装更新
├─ file-retry                  # 发生文件发送修复时按需创建，临时变体 24 小时后清理
├─ prevent-recall
│  └─ <QQ号>                  # 当前账号独立存放以下防撤回数据
│     ├─ active-recall-cache.bin # 持久化撤回消息记录
│     ├─ candidates             # 保护窗口内资源的恢复日志
│     ├─ staging               # 尚未撤回的临时图片和文件
│     ├─ images                # 已归档的撤回图片
│     └─ files                 # 已归档的撤回文件
└─ voice\library\voices       # 语音库文件和文件夹

可以直接在 voices 目录中手动整理音频、视频和子文件夹，完成后重新打开语音库或刷新列表。

不要手动移动、修改或删除 prevent-recall 内的单个文件；请使用“阻止撤回 > 清理撤回缓存”按当前账号完整清理，避免记录与暂存、归档状态不一致。

config.json 可能包含其他文件的加密 ZIP 密码和 Telegram Bot Token，请勿上传或发给他人。内置诊断报告会主动隐藏密码、令牌、完整账号标识和绝对路径，但公开提交前仍建议检查一次导出内容。

常见问题

快捷键没有打开工具箱

• 前往 QQ“设置 > QQNT Toolbox > 其他 > 悬浮窗”，确认“启用悬浮窗”已经开启。
• 查看“唤出快捷键”当前绑定的按键；默认是键盘右侧的 Ctrl。
• 完全退出 QQ 后重新启动。
• 检查插件目录是否多嵌套了一层文件夹。
• 检查 LiteLoaderQQNT 的插件管理页面是否已经加载 QQNT Toolbox。

音视频无法发送

• 先执行 ffmpeg -version，确认 FFmpeg 可用。
• 确认已经进入目标聊天并打开 QQ 原版语音面板。
• 确认拖入的是受支持的本地音频或视频文件。
• 若刚修改 PATH 或 FFMPEG_PATH，需要完全退出并重新启动 QQ。

右键菜单出现重复项目或界面异常

不要同时启用多个插件中的同类功能。特别是 lite-tools 的复读、阻止撤回和界面精简，可能与 QQNT Toolbox 重复注入相同位置。保留一个插件负责对应功能即可。

QQ 更新后部分功能失效

本插件使用 QQNT 内部接口和 DOM 结构，QQ 更新可能改变这些实现。请查看 Issues 或最新 Release；反馈问题时可以临时开启诊断记录，并附上导出的诊断报告。

如何安全反馈问题

• 只在本仓库 Issues 反馈插件问题，不要前往 QQ 官方群聊、客服或反馈渠道提交第三方插件相关材料。
• 写明操作系统、QQ 版本、LiteLoaderQQNT 版本、Toolbox 版本、复现步骤和相关功能开关。
• 优先附上内置“导出诊断报告”的结果，不要上传 config.json、整个数据目录或包含账号、群号、好友信息的未处理截图。
• 截图和录屏前请遮挡账号、群聊、联系人、文件路径及其他隐私信息。

致谢

• QAuxiliary：参考 NoSeq 消息提示、图片修复、自定义图片外显、消息复读与伪装语音时长的行为设计。
• lite-tools：参考阻止撤回持久化、界面调整、撤回查看器及本地贴纸包设计。
• qwqnt-message-to-image：参考消息右键转图片的功能入口。
• html2canvas：用于将清理后的消息 DOM 绘制为 PNG，遵循 MIT License。
• LiteLoaderQQNT-Media-Local-View：参考 openMediaViewer 拦截方式。
• LiteLoaderQQNT-Audio-Sender：原始语音文件发送思路及早期实现参考。
• silk-wasm：Release 中包含的 Silk 编解码运行库，遵循其自身许可证。
• zip.js：其他文件的流式 AES 加密 ZIP 支持，遵循 BSD-3-Clause 许可证。

许可证

QQNT Toolbox 使用 GNU Affero General Public License v3.0 发布。