📁 GroupFS - QQ群文件管理插件

一款为 AstrBot 设计的QQ群文件管理插件，旨在简化和自动化群组的文件维护工作。

✨ 功能特性

🔍 搜索与预览

• 全能预览: 支持预览 .txt、.md、.json、.py、.log 等 30+ 种文本格式。
• 压缩包解析: 支持 .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 后台 -> 插件 页面找到本插件进行设置。所有配置项都有详细的说明和提示。

📖 使用指南

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

📋 指令列表

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

💡 指令示例与用法演示

🔍 搜索与预览

• 搜索文件: /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 智能分析群内疑似重复的文件)。

💾 备份文件

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

⚙️ 自动化功能

• 容量监控与定时检查均为被动触发功能，只需在配置文件中正确设置，插件便会自动在后台执行。

⚠️ 使用注意事项

备份功能说明

一键备份 (/gfb) 指令稳定性取决于备份文件大小。

核心问题出在 Bot 后端 (NapCat/NTQQ) 的大文件上传：

• 远程部署/大文件：当备份文件较大（超过几百 MB）或您的 Bot 部署在远程服务器时，Bot 后端在文件上传过程中极易触发 网络超时 或 内部传输失败（rich media transfer failed）。目前还没找到办法解决。

建议：

• 搭配清理工具：由于 NTQQ 客户端传输大文件时会产生大量且可能残留的临时文件，强烈建议搭配 astrbot_plugin_napdog 插件使用。
• 监控目录：请确保 napdog 或其他清理工具能定时清理以下关键的 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分钟后删除。
• 外部备份方案：如果您需要更稳定、自动化的云端备份，推荐尝试 astrbot_plugin_openlistfile，支持将群文件手动或自动备份到网盘（通过 OpenList）。

重复文件检测说明

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

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

📝 更新日志

点击展开更新日志

• v1.0
  • 新增 /preview 指令。
  • 新增 /rn 重命名指令。
  • 新增 指令中文别名。
  • 优化 预览功能。
  • 优化 消息发送方式。
  • 优化 项目结构。
• v0.9
  • 新增 重复文件检测指令 (/ddf)。
  • 优化 备份指令 (/gfb)。
  • 优化 ZIP 预览功能。
  • 优化 数据目录管理。
• v0.8.1
  • 新增 一键备份指令 (/gfb)。
• v0.8
  • 新增 压缩包预览 功能。
• v0.7
  • 新增 长消息自动合并转发 功能。
• v0.6
  • 新增 定时任务 功能。
  • 优化项目结构。
• v0.5
  • 新增 批量检查指令 (/cf)。
  • 新增 批量清理指令 (/cdf)。
  • 优化 删除指令 (/df)。
• v0.4
  • 新增 群文件容量监控 功能。
• v0.3
  • 新增 文本文件预览 功能。
• v0.2
  • 新增 文件搜索指令 (/sf)。
  • 优化 删除指令 (/df)。
• v0.1
  • 实现 基础的文件删除 功能。

❓ 常见问题

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

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

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

❤️ 支持

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