跳到主要内容

KnotLink Command API

实现 IFolderRewindKnotLinkCommandHandler 后，插件可扩展 Host 可识别的 KnotLink 命令。

接口​

  • GetKnotLinkCommandDefinitions()：声明命令名与说明
  • TryHandleKnotLinkCommandAsync(...)：按命令分发处理

推荐分发结构​

建议用 switch（或映射表）按命令大写分发：

return command.ToUpperInvariant() switch
{
	"PING" => HandlePingAsync(args, hostContext),
	"BACKUP_CURRENT" => HandleBackupAsync(args, settingsValues, hostContext),
	_ => Task.FromResult<string?>(null)
};

返回 null 代表“本插件不处理该命令”，Host 可继续尝试其他处理者。

返回约定​

  • 返回 null：表示不处理该命令
  • 返回字符串：表示已处理并作为响应返回

建议使用统一格式：

  • 成功：OK:<message>
  • 失败：ERROR:<reason>

命令实现建议​

  • 快速返回：耗时操作放入后台任务
  • 参数校验：缺少参数时直接返回 ERROR:Missing ...
  • 幂等与状态：避免重复触发同一长流程
  • 可观测性：对关键路径写日志并广播状态事件

MineRewind 命令示例​

  • BACKUP_CURRENT
  • BACKUP <config_id> <folder_index|folder_name> [comment] [FORCE_FULL]
  • RESTORE_CURRENT_LATEST
  • LIST_BACKUPS_CURRENT
  • RESTORE_CURRENT <backup_file>

这些命令配合 KnotLink 广播实现“保存-退出-还原-重进”链路。

请求/响应示例​

列出当前活跃世界备份​

请求：

LIST_BACKUPS_CURRENT

响应：

OK:save_001.7z;save_002.7z

指定备份热还原​

请求：

RESTORE_CURRENT save_002.7z

响应：

OK:Hot restore triggered for 'WorldName' with backup 'save_002.7z'

强制执行一次完整备份​

当配置当前处于智能增量模式，但你希望通过远程命令临时执行一次 Full 备份时，可在 BACKUP 命令末尾追加 FORCE_FULL：

请求：

BACKUP demo_config 0 手动校验 FORCE_FULL

响应：

OK:Backup task queued

说明：

  • FORCE_FULL 会绕过当前配置的备份模式，仅对本次远程触发生效。
  • 建议在升级旧配置、准备重要里程碑或怀疑增量链异常时使用。
  • 不要把长时间运行的完整备份放在高频请求路径里。

设计建议​

  • 快速返回，耗时任务丢到后台执行
  • 命令参数要先校验再执行
  • 给关键路径打日志并广播状态事件

与专题文档联动​

相关链接​