📁 QQ 群文件管家

🤖 全能文件管理，自动清理备份

📖 简介

一款为 AstrBot 设计的 QQ 群文件管理插件，专注于群文件的搜索、预览、清理、备份、同步与容量监控，帮助管理员高效维护群内各类资源。

Tip

推荐搭配 QQ 文件预览 使用。本插件会自动检测并复用该插件维护的群文件缓存，大幅减少 API 调用并显著提高响应速度。

---

✨ 功能特性

🔍 搜索与预览

• 全能预览: 支持预览 .txt、.md、.json、.py、.log 等 30+ 种文本格式，支持 EPUB 电子书内容预览，并可将 .pdf 文件转换为 图片预览。
• 压缩包解析: 支持 .zip、.7z 等 10+ 种主流压缩格式 的内部结构查看与文本预览。
• 智能交互: 支持翻页（下一页/跳转）、引用预览、序号指定等多种便捷交互方式。

🧹 维护与清理

• 失效清理: 自动扫描群文件，精准识别并批量删除已失效的“僵尸文件”。
• 智能查重: 利用 LLM (大语言模型) 深度分析文件名，智能识别群内高度疑似的重复资源。
• 灵活管理: 支持按序号、关键词、批量范围或直接引用消息进行删除与重命名。

🤖 自动化监控

• 容量预警: 实时监控群文件总数及空间占用，触发阈值即刻发送提醒。
• 定时任务: 支持 Cron 表达式，全自动定期执行失效文件检查并生成报告。

💾 安全备份

• 多模式备份: 支持全量备份、按日期增量备份，确保存量资源永不丢失。
• 高级压缩: 自动分卷压缩、加密保护，优化大文件和敏感文件的传输限制。

📁 文件同步

• 跨群同步：支持配置“源群 → 目标群”单向同步，按文件路径与文件名完成全量对齐。
• 增量同步：优先匹配同路径同体积文件，减少重复上传；支持重命名/移动场景的智能对齐。

---

💿 安装与依赖

1. 进入容器安装依赖：如果你的 AstrBot 运行在 Docker 容器中，请先进入容器内部。

   docker ps  # 找到你的 AstrBot 容器ID
   docker exec -it <容器ID> bash  # 或者 sh

   然后在容器内安装 zip 依赖库：

   # 对于 Debian/Ubuntu 系统
   apt-get update && apt-get install zip p7zip-full
   
   # 对于 Alpine Linux 系统   
   apk add zip p7zip

2. 安装插件: 下载本插件的完整文件夹，并放入 AstrBot 的 data/plugins/ 目录下。

3. 重启 AstrBot。

---

⚙️ 配置

首次加载后，请在 AstrBot 后台 -> 插件 页面找到本插件进行设置。所有配置项都有详细的说明和介绍。

---

📖 使用指南

确保 Bot 在目标群组拥有管理员权限，否则它可能无法执行某些操作。

📋 指令列表

指令	中文别名	作用
/sf	搜索	搜索群文件，支持翻页
/preview	预览	预览文本内容或压缩包结构
/df	删除	删除指定文件 (管理员)
/rn	重命名	修改群文件名 (管理员)
/cf	检查群文件	扫描失效文件并发送报告 (管理员)
/cdf	清理失效文件, 清理失效群文件	扫描并批量清理失效文件 (管理员)
/ddf	重复文件检测, 重复群文件检测, 群文件查重	AI 智能分析重复文件 (管理员)
/gfb	备份群文件, 群文件备份	备份群文件 (管理员)
/gfs	同步群文件, 群文件同步	手动同步群文件 (管理员)

💡 使用方法

🔍 搜索与预览

• 搜索文件: /sf 文件关键词
• 翻页操作: 搜索后输入 /sf 下一页、/sf 上一页 或 /sf 跳转 <页码>。
• 预览文件:
  • 基本预览: /preview 序号 (需先搜索) 或 /preview 文件名。
  • 压缩包预览:
    • 内部路径: /preview 序号 内部路径 (如 /preview 1 folder/test.txt)。
    • 内部序号: /preview 序号 内部序号 (如 /preview 1 2 预览压缩包内第 2 个文件)。
  • 引用预览: 引用一个文件消息，直接输入 /preview。
    • 注：引用预览同样支持带内部序号或路径，如回复压缩包消息后输入 /preview 1。

🗑️ 文件管理

• 删除文件:
  • 序号删除: /df 序号 (需先搜索) 或 /df 关键词 序号。
  • 多选删除: /df 1,3,5 (需先搜索) 或 /df 关键词 1,3,5。
  • 批量删除: /df 0 (删除最近一次搜索结果中的所有文件) 或 /df 关键词 0。
  • 引用删除: 引用一个文件消息，直接输入 /df。
• 重命名文件:
  • 序号重命名: /rn 序号 新文件名。
  • 搜索重命名: /rn 旧文件名 新文件名。
  • 引用重命名: 引用一个文件消息，输入 /rn 新文件名。
• 检查失效文件: /cf (仅扫描并发送报告)。
• 清理失效文件: /cdf (扫描并自动删除所有失效文件)。
• 检测重复文件: /ddf (调用 AI 智能分析群内疑似重复的文件)。

Caution

重复文件检测 (/ddf) 依赖 LLM 进行智能分析：

• 文件数量限制：当群文件数量很多时，生成的文件列表可能会很长。请确您使用的 LLM 支持足够长的输入。
• 分析准确性：AI 分析结果仅供参考，建议人工复核后再删除文件。

💾 备份文件

• 备份当前群: /gfb
• 备份指定群: /gfb <群号>
• 增量备份: /gfb <群号> <日期>
  • 日期格式支持: YYYY-MM-DD, YYYYMMDD, YYYY/MM/DD
  • 示例: /gfb 123456789 2024-01-01 (只备份2024年1月1日及以后的文件)

Caution

一键备份 (/gfb) 指令稳定性取决于备份文件大小，核心问题出在 Bot 后端 (NapCat/NTQQ) 的大文件上传，当备份文件较大（超过几百 MB）时，Bot 后端在文件上传过程中容易触发 网络超时 或 内部传输失败。

• 建议搭配清理工具：由于 NTQQ 客户端传输大文件时会产生大量且可能残留的临时文件，建议搭配 QQ 缓存管家 使用，较新版本的 Napcat 可安装官方提供的缓存清理插件。
• 监控目录：请确保 QQ 缓存管家 或其他清理工具能定时清理以下关键的 NTQQ 内部目录，以下仅供参考：
  • /app/.config/QQ/NapCat/temp/ (NapCat 临时目录)
  • /app/.config/QQ/nt_qq_*/nt_data/File (NTQQ 核心文件缓存目录)
• 本地部署用户：可以直接访问插件的临时目录（{data_path}/plugins_data/astrbot_plugin_GroupFS/temp_backup_cache），手动获取已下载和压缩完成的文件，临时文件将于10分钟后删除。

Tip

• 云端备份方案：如果您需要云端备份方案，可尝试 OpenList 助手，支持将群文件手动或自动备份到网盘（通过 OpenList）。
• 平台备份方案：如果您需要将群文件备份至其他平台如 Telegram，可尝试 QQ 文件预览，支持将新上传的群文件备份至指定会话。

🔄 同步文件

• 手动同步: /gfs (无参数，在当前群匹配并执行关联的同步任务)
• 全部同步: /gfs all (逐一执行所有已配置的同步任务)
• 指定同步: /gfs <源群号> <目标群号> (执行指定的源群到目标群同步)

⚙️ 自动化功能

• 容量监控、定时检查、定时同步为被动触发功能，只需在配置文件中正确设置，插件便会自动在后台执行。
• 定时报告文本过长时会自动合并转发，避免刷屏。

Important

首次执行同步任务时，若文件规模较大，可能会出现部分文件同步失败的情况。插件会在后续的定时任务中继续同步，直至全部文件同步完成。

---

📝 更新日志

详见 CHANGELOG

---

❓ 常见问题

Q: 插件工作异常，该怎么办？

A: 在遇到任何插件运行错误或功能异常时，请按照以下步骤进行排查和解决：

1. 重载插件
2. 重启 NapCat
3. 重启 AstrBot

---

❤️ 支持

• AstrBot 帮助文档
• 如果您在使用中遇到问题，欢迎在本仓库提交 Issue。

---

如果本插件对你有帮助，欢迎点个 ⭐ Star 支持一下！