📁 GroupFS - QQ群文件管理插件

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

✨ 功能特性

• 文件搜索与预览: 使用 /sf 指令快速搜索文件并预览 .txt 和 .zip 内容
• 智能重复检测: 使用 /ddf 指令调用AI分析群文件，找出疑似重复的文件
• 文件管理: 支持精准删除和批量删除（管理员权限）
• 失效文件检测: 自动扫描并清理失效文件
• 定时自动化: 支持 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 文件关键词
• 预览文件: /sf 文件关键词 序号

🗑️ 文件管理 (仅限管理员)

• 删除单个文件: /df 文件关键词 序号
• 批量删除搜索结果: /df 文件关键词 0
• 检查失效文件: /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分钟后删除。

重复文件检测说明

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

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

📝 更新日志

❓ 常见问题 (FAQ)

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

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

1. 重载插件
2. 重启 NapCat (对于群文件的频繁遍历和大文件发送都极可能导致影响NapCat的正常运作)
3. 重启 AstrBot

❤️ 支持

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