Admin Tool - Koishi 群管理工具

🔧 功能强大的 Koishi 群管理插件，提供定时禁言、撤回转发、警告系统等全方位管理功能

✨ 主要功能

• 🕒 智能定时禁言 - 支持定时起止禁言、临时禁言、时间单位解析
• 🤖 自动问候系统 - 5个时间段个性化问候，支持AI总结图模板
• 📢 撤回消息转发 - 监听指定群组撤回消息并转发到目标位置
• ⚠️ 警告管理系统 - 完整的用户警告流程，支持证据收集和处罚记录
• 🎯 群打卡功能 - 支持群打卡功能、立即打卡，帮助群组获得活跃度
• ⏰ 高精度时间同步 - 多时间源支持，确保定时任务准确执行
• 👥 权限管理系统 - 主人、管理员分级权限控制
• 🔍 批量消息管理 - 支持批量撤回、关键词撤回等高级功能

📦 安装要求

• Koishi 4.x
• 数据库服务（推荐 MySQL）
• HTTP 服务（用于网络时间同步）

🚀 快速开始

基础配置

1. 设置主人QQ号：在配置中填入主人QQ号，获得最高权限
2. 配置管理员列表：添加管理员QQ号，允许使用管理命令
3. 选择时间源：推荐选择"QQ时间"获得最佳精度
4. 启用所需功能：根据需要开启自动问候、撤回转发等功能

权限说明

• 主人：拥有所有权限，包括添加/删除管理员、系统管理等
• 管理员：可以使用禁言、警告、撤回等群管理功能
• 普通用户：只能查看部分状态信息

📝 命令大全

⏰ 定时禁言相关

admin.schedule 23:00 06:00 [群号]     # 设置定时禁言（晚11点到早6点）
admin.cancelschedule [群号]           # 取消定时禁言
admin.mute 30m [群号]                 # 临时禁言30分钟（支持时间单位）
admin.mute 12h [群号]                 # 临时禁言12小时
admin.mute 1d [群号]                  # 临时禁言1天
admin.unmute [群号]                   # 立即解除禁言
admin.status [群号]                   # 查看禁言状态
admin.list                            # 查看所有禁言任务（仅主人）
admin.reload                          # 重载定时任务（仅主人）

支持的时间单位：

• s - 秒（如：60s）
• m - 分钟（如：30m）
• h - 小时（如：12h）
• d - 天（如：1d）

🌟 自动问候相关

admin.greeting.status                 # 查看问候功能状态
admin.greeting.test [群号]            # 测试当前时段问候消息
admin.greeting.testunmute [群号]      # 测试解禁问候消息
admin.greeting.testall [群号]         # 测试所有时间段问候消息
admin.greeting.preview <时间段> [群号] # 预览指定时间段问候消息
admin.greeting.checkimage [群号] [日期] # 检查AI总结图可用性

时间段说明：

• morning - 早上（06:00-11:59）
• noon - 中午（12:00-13:59）
• afternoon - 下午（14:00-17:59）
• evening - 晚上（18:00-21:59）
• night - 深夜（22:00-05:59）

📢 撤回转发相关

admin.recall.status                   # 查看撤回转发状态
admin.recall.clear                    # 清除撤回缓存
admin.recall                          # 撤回指定消息（回复目标消息使用）
admin.forcerecall <消息ID> [群号]     # 强制撤回指定消息
admin.batchrecall <用户ID> <数量> [群号] # 批量撤回用户最近消息
admin.recallkeyword <关键词> <最大数量> [群号] # 撤回包含关键词的消息

⚠️ 警告管理相关

admin.warning <目标QQ号> <警告通知群>  # 发起警告流程（禁告）
admin.revoke-warning <警告ID>         # 撤销警告记录

警告流程：

1. 执行 admin.warning 命令
2. 按提示上传证据（支持合并转发）
3. 输入处理说明
4. 设置处罚时间（支持时间单位）
5. 系统自动执行并记录

🎯 群打卡相关

admin.checkin.schedule <时间> [群号]      # 设置群打卡功能
admin.checkin.cancel [群号]              # 取消群打卡功能
admin.checkin.now [群号]                 # 立即执行群打卡
admin.checkin.status [群号]              # 查看打卡任务状态
admin.checkin.list                       # 查看所有打卡任务（仅主人）
admin.checkin.reload                     # 重载打卡任务（仅主人）

使用示例：

• admin.checkin.schedule 00:00 - 设置每天00:00自动打卡
• admin.checkin.schedule 08:00 123456789 - 设置指定群每天08:00打卡
• admin.checkin.now - 在当前群立即打卡

功能特点：

• 支持设置每日定时打卡，默认时间为00:00
• 使用 OneBot API 的 sendGroupSign 接口
• 自动数据库持久化，重启后任务自动恢复
• 高精度时间调度，确保准时执行

👥 权限管理相关

admin.addadmin <用户ID>               # 添加管理员（仅主人）
admin.removeadmin <用户ID>            # 移除管理员（仅主人）
admin.adminlist                      # 查看管理员列表

⚙️ 系统管理相关

admin.help                           # 查看所有可用命令
admin.timeinfo                       # 查看时间同步信息（仅主人）
admin.synctime                       # 手动同步网络时间（仅主人）
admin.syncqq                         # 手动同步QQ时间（仅主人）
admin.stats                          # 查看执行统计信息（仅主人）

⚙️ 详细配置说明

基本设置

• 主人QQ号：拥有最高权限的用户
• 管理员列表：可以使用管理命令的用户列表
• 调试模式：开启后显示详细的调试信息
• @主人自动禁言：有人@主人时自动禁言10分钟

时间同步设置

• 时间源选择：
  • QQ时间：从QQ服务器同步（推荐，最准确）
  • 网络时间：从网络时间服务器同步
  • 系统时间：使用本地系统时间
• 精度模式：
  • 标准模式：1秒检查间隔，5分钟同步一次
  • 高精度模式：0.5秒检查间隔，3秒同步一次（消耗更多资源）
• 时区设置：如 Asia/Shanghai
• 时间漂移阈值：检测到超过此阈值的时间偏差时发出警告

自动问候功能

• 启用状态：是否开启自动问候功能
• 5个时间段问候语：可自定义每个时间段的问候内容
• 解禁问候语：禁言结束时的专用问候语
• 模板变量支持：
  • {{昨日AI总结图}}：自动插入昨日的AI总结图片

撤回消息转发

• 启用状态：是否开启撤回转发功能
• 监听配置：
  • 监听群组ID列表：需要监听撤回消息的群组
  • 监听用户ID列表：需要监听撤回消息的私聊用户
• 转发配置：
  • 转发群组ID列表：撤回消息转发的目标群组
  • 转发用户ID列表：撤回消息转发的目标私聊用户
• 内容设置：
  • 消息缓存时间：撤回消息的缓存时长
  • 包含图片内容：是否转发图片
  • 包含@信息：是否转发@用户信息

警告系统设置

• 警告执行群号：只有在此群内才能使用禁告指令

群打卡功能设置

• 启用状态：是否开启群打卡功能
• API要求：需要 OneBot 协议支持 sendGroupSign 接口
• 权限要求：Bot需要在目标群组具有相应权限

🔧 高级功能

智能时间单位解析

支持多种时间格式输入：

admin.mute 60s    # 60秒
admin.mute 30m    # 30分钟  
admin.mute 12h    # 12小时
admin.mute 1d     # 1天
admin.mute 600    # 600秒（不带单位默认为秒）
admin.mute 1.5h   # 1.5小时（支持小数）

模板变量系统

问候语支持动态模板变量：

• {{昨日AI总结图}}：自动获取昨日聊天记录的AI总结图
• 如果图片不存在，会自动替换为提示文本

高精度时间系统

• 多时间源：QQ时间、网络时间、系统时间三重保障
• 漂移检测：实时监控系统时间偏差
• 自动同步：根据精度模式自动调整同步频率
• 执行统计：记录定时任务的执行精度和延迟情况

数据持久化

• 定时任务：自动保存到数据库，重启后自动恢复
• 警告记录：完整记录用户违规历史
• 撤回缓存：智能缓存消息，支持撤回转发

🎯 使用场景

定时禁言场景

• 夜间禁言：admin.schedule 23:00 07:00 - 晚11点到早7点禁言
• 学习时间：admin.schedule 14:00 17:00 - 下午2点到5点禁言
• 临时安静：admin.mute 1h - 临时禁言1小时

撤回监控场景

• 重要群组监控：监听关键群组的撤回消息
• 证据保存：自动转发撤回消息到管理群
• 用户行为追踪：记录特定用户的撤回行为

警告管理场景

• 违规处理：完整的证据收集和处罚流程
• 记录查询：通过警告ID查询历史记录
• 撤销机制：支持撤销错误的警告决定

群打卡场景

• 每日打卡：admin.checkin.schedule 00:00 - 每天零点自动打卡
• 上班打卡：admin.checkin.schedule 09:00 - 每天上班时间打卡
• 活动打卡：admin.checkin.now - 特殊活动时立即打卡
• 多群管理：为不同群组设置不同的打卡时间

🐛 常见问题

Q: 定时任务不执行怎么办？

A: 检查以下项目：

1. 确认时间源配置正确（推荐使用QQ时间）
2. 查看 admin.timeinfo 确认时间同步状态
3. 确认机器人在目标群组有管理员权限
4. 检查 admin.list 查看任务是否正确加载

Q: 撤回转发不工作怎么办？

A: 确认以下配置：

1. 撤回转发功能已启用
2. 监听群组/用户ID配置正确
3. 转发目标群组/用户ID配置正确
4. 机器人在相关群组中正常运行

Q: 警告流程如何使用？

A: 警告流程：

1. 在指定的警告执行群中使用 admin.warning <QQ号> <通知群号>
2. 按提示上传证据（可发送"无需证据"跳过）
3. 输入处理说明
4. 设置处罚时间（支持时间单位，0表示不禁言）
5. 系统自动执行并生成警告ID

Q: 群打卡功能如何使用？

A: 群打卡功能使用：

1. 在配置中启用群打卡功能
2. 使用 admin.checkin.schedule <时间> 设置定时打卡（如：00:00）
3. 使用 admin.checkin.now 立即执行打卡
4. 使用 admin.checkin.status 查看当前打卡任务状态
5. 注意：需要OneBot协议支持且Bot在群内有相应权限

📊 性能说明

资源消耗

• 标准模式：CPU使用率低，适合一般场景
• 高精度模式：CPU使用率较高，适合对时间精度要求极高的场景
• 内存占用：约10-50MB（取决于缓存大小和任务数量）
• 网络流量：时间同步产生少量流量

建议配置

• 小型群组（<100人）：标准模式 + QQ时间
• 大型群组（>500人）：高精度模式 + QQ时间
• 多群管理：根据实际需求选择精度模式

🔄 版本更新

当前版本特性

• ✅ 模块化架构，便于维护和扩展
• ✅ 智能时间单位解析系统
• ✅ 高精度时间同步机制
• ✅ 完整的警告管理流程
• ✅ 强大的撤回转发功能
• ✅ 群打卡功能，支持定时和立即打卡
• ✅ 灵活的权限管理系统

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

💡 提示：使用过程中遇到问题，可以开启调试模式查看详细日志，或使用 admin.help 查看完整命令列表。