定时任务插件

← 插件与自动化 · 所有分区

内置插件 ID 为 scheduled_tasks，提供公告、预设命令和备份。新安装插件与任务均默认停用，任务定义和执行历史使用 Bot 主数据库；插件启用与授权保存在 data/plugin-state.json。

定时任务

进入「扩展 → 插件管理」，在内置「定时任务」插件卡片点击「管理任务」，再点击「新建任务」。全新安装时插件和新任务均默认停用；可在插件卡片或任务页启用插件，再按需启用任务。支持：

• 间隔执行：1–43200 分钟。保存、修改或重新启用时，从当前时间重新计时。
• 指定星期与时间：选择周一至周日及 HH:MM，使用北京时间（Asia/Shanghai / UTC+8），不随服务器系统时区变化。
• 动作：群公告、游戏公告、执行服务器已配置的预设命令、创建备份。命令不能输入任意脚本，只能选「自动化 → 游戏指令」中允许的命令。

群公告最多 2000 字，游戏公告最多 600 字，均发送文字消息。

「立即执行」可以验证停用的单个任务，但必须先启用定时任务插件，并满足动作和目标权限；它不会启用单个任务或改变周期。游戏公告与命令提交后等待游戏插件确认；结果未确认不视为成功，先核对游戏状态再重试。待确认的任务不能再次执行。修改关联群或命令后，每次执行仍会重新检查配置。关闭任务或插件只停止未来执行，不撤回已经发送或提交的操作。

插件卡片的「权限」分别控制群公告、游戏公告、预设命令和备份，并可限制服务器与群范围；任务执行时重新检查权限。QQ 使用者名单适用于群命令，不适用于由面板管理的定时任务。团队成员仍需 schedules.manage 管理任务，plugins.manage 用于管理插件权限。

首次升级时保留所有任务和执行记录；若原有启用的任务，自动启用定时任务插件以延续原行为。此迁移只执行一次，停用后的插件不会因重启、重新加载或扫描再次启用。重新启用插件时跳过暂停期间已经到期的任务，不集中补发。

主程序每 2 秒检查一次任务。停机期间超过 60 秒的过期任务跳过，不会重放或集中补发；程序重启后没有确认的执行标记为未完成。QQ 断线、游戏离线、队列已满或备份容量耗尽时，本次记为失败，下次按正常周期执行。执行记录保留最多 500 项，面板显示最近 30 次；任务最多 100 项。

自动备份保存在 data/backups，不会触发浏览器下载。最多保留 100 份，默认不自动删除；可在「备份与恢复」设置保留策略，或定期下载并删除不需要的备份。备份包含连接密钥与密码哈希，请妥善保管。

API 与权限

团队管理员需要 schedules.manage 管理和执行任务，动作授权由具有 plugins.manage 权限的管理员调整。API 使用管理会话 Bearer 令牌，不接受网站或玩家令牌。

方法	路径	作用
GET / POST	/api/schedules	列表及最近执行 / 新建 {definition}
PUT	/api/schedules/plugin	{enabled,revision}，revision 取列表的 plugin_revision
PUT / DELETE	/api/schedules/{id}	完整更新 {definition,revision} / 删除 {revision}
POST	/api/schedules/{id}/run	立即执行 {revision}，游戏动作可能仍待确认

恢复后

从备份恢复后任务自动停用，未完成的游戏执行撤销。先检查服务器、关联群与预设命令，再手动启用。关停或恢复期间不重放已经过去的执行。

业务记录使用 Bot 主数据库：新安装默认 SQLite，也可按MySQL 存储指南配置 MySQL。不要把‘默认 SQLite’理解为仅支持 SQLite。配置目录下的插件状态和网站设置仍为各自 JSON 文件；具体备份范围见备份与恢复。

任务 definition 完整字段和白名单联动见自动化完整指南。