🔑 权限命令
本文按用途整理 Sparrow Sync 的命令与默认权限。<参数> 为必填项，[参数] 为可选项，输入时不需要保留括号。<player> 填写玩家名，<id> 填写快照的完整 UUID。
下列写法以默认配置为准。如果修改了 commands.yml 中的命令或权限，请使用修改后的内容；命令注册配置需要重启服务器才会生效。
⚙️ 插件状态和管理
| 命令 | 功能 | 默认权限 |
|---|---|---|
/sparrow-sync status [player] | 查看插件运行状态，或指定玩家的同步状态。 | sparrow_sync.command.status |
/sparrow-sync reload | 重载插件配置。 | sparrow_sync.command.reload |
不填写玩家名时，status 会显示服务器 ID、存储类型、Redis 连接状态、任务与会话等运行信息。填写玩家名后，可以查看该玩家的锁持有情况和最新快照等信息，适合在排查同步问题时使用。
reload 适用于支持重载的配置。配置注释中标明需要重启的选项，以及命令注册本身，都需要重启服务器才能生效。
🔍 快照查看
| 命令 | 功能 | 默认权限 |
|---|---|---|
/sparrow-sync snapshot list <player> [page] | 分页列出玩家的快照。 | sparrow_sync.command.view |
/sparrow-sync snapshot view <player> <id> | 打开指定快照的详情 GUI，仅玩家可执行。 | sparrow_sync.command.view |
/sparrow-sync exception list [player] [page] | 列出本服保存的异常档案，可按玩家筛选。 | sparrow_sync.command.view |
/sparrow-sync exception view <file> | 查看指定异常档案的报告。 | sparrow_sync.command.view |
可以先通过 snapshot list 找到需要检查的快照，再打开详情查看物品和其他数据。页码从 1 开始，省略时显示第一页。
异常档案保存在服务器本地，exception 命令只查看当前服务器的文件。<file> 使用异常列表中给出的相对路径。省略玩家名时，exception list 2 表示查看全部异常档案的第二页；如果玩家名完全由数字组成，请同时填写页码，以免被识别为页码。
📦 快照管理
| 命令 | 功能 | 默认权限 |
|---|---|---|
/sparrow-sync snapshot capture <player> | 为在线玩家立即创建一份快照。 | sparrow_sync.command.capture |
/sparrow-sync snapshot restore <player> <id> | 将玩家数据恢复到指定快照。 | sparrow_sync.command.restore |
/sparrow-sync snapshot pin <id> | 固定快照，使其不参与自动轮转清理。 | sparrow_sync.command.pin |
/sparrow-sync snapshot unpin <id> | 取消固定，使快照重新参与自动轮转清理。 | sparrow_sync.command.unpin |
/sparrow-sync snapshot delete <id> | 删除指定快照。 | sparrow_sync.command.delete |
/sparrow-sync exception delete <file> | 删除本服指定的异常档案及其关联诊断文件。 | sparrow_sync.command.exception.delete |
采集与回滚
capture 要求玩家在线，玩家可以位于当前服务器，也可以位于参与同步的其他服务器。它会采集玩家当前的数据并保存为新快照。
restore 支持在线和离线玩家。在线时，插件会在玩家所在服务器执行恢复；离线时，恢复的数据会在玩家下次登录时加载。指定的快照必须属于该玩家。
在线恢复受 synchronization.skip-online-restore-data 控制，默认跳过血量和位置。相关原因和配置方式见关键配置说明。
保留重要快照
对需要长期保留的记录，可以先执行 pin。固定用于避免自动清理，仍然可以通过 delete 主动删除。异常档案属于另一类本地文件，应使用 exception delete 清理。
📤 数据导出
| 命令 | 功能 | 默认权限 |
|---|---|---|
/sparrow-sync snapshot export <format> <id> | 将单份快照导出为文件。 | sparrow_sync.command.export |
/sparrow-sync snapshot import <file> | 将导出的单份快照导入数据库。 | sparrow_sync.command.import |
/sparrow-sync data dump_all [file] | 将数据库数据批量导出为 ZIP。 | sparrow_sync.command.dumpall |
/sparrow-sync data import_all <file> | 从 ZIP 批量导入数据。 | sparrow_sync.command.importall |
单份快照
snapshot export 的 <format> 支持 BINARY 和 JSON，分别生成 .snapshot 和 .json 文件。注意参数顺序：格式在前，快照 ID 在后。
导出文件位于 plugins/SparrowSync/snapshot/output/。执行 snapshot import 时，将文件放在该目录下，并填写相对于该目录的文件路径。
导入会将快照写入数据库。如果需要用这份快照回滚玩家，请在导入后执行 snapshot restore。
下面是一份导出的 JSON 快照，可以看到快照信息和各数据类型保存的内容：
批量导出与导入
批量操作使用 plugins/SparrowSync/snapshot/dump/ 目录。dump_all 可以指定 ZIP 文件名；省略时，插件会使用带时间戳的默认名称。
执行 import_all 时，将 ZIP 放入该目录，再填写相对文件路径。等待控制台报告处理结果后，再检查导入的数据。
🔄 数据迁移
| 命令 | 功能 | 默认权限 |
|---|---|---|
/sparrow-sync data migrate <source> | 从指定插件迁移玩家数据，仅控制台或 RCON 可执行。 | sparrow_sync.command.migrate |
<source> 填写 husksync 或 invsync。执行时，原插件需要保留在服务器中并正常启用，Sparrow Sync 才能读取它的数据。
迁移前建议限制玩家进入。迁移完成并确认数据无误后，关闭服务器、卸载原插件，再启动服务器并解除限制。完整步骤和失败档案的处理方式见数据迁移。
🖥️ GUI 与编辑权限
| 命令或权限 | 用途 | 默认命令权限 |
|---|---|---|
/sparrow-sync gui <player> | 打开指定玩家的快照列表 GUI，仅玩家可执行。 | sparrow_sync.command.view |
sparrow_sync.ui.edit | 允许在 GUI 中操作物品和使用管理功能。 | — |
gui 从玩家的快照列表开始浏览，snapshot view 则直接打开指定快照的详情。只有查看权限时，可以浏览快照内容；需要在界面中操作数据时，再授予 sparrow_sync.ui.edit。
快照列表
列表中的每本书代表一份快照。将鼠标移到快照上，可以查看保存时间、保存原因、来源服务器和完整 ID，再选择需要打开的记录。
快照详情
打开快照后，可以通过顶部按钮切换查看不同数据。下图展示了快照中保存的背包与装备：
sparrow_sync.ui.edit 不只控制物品交互，也控制界面中的删除、固定、导出、恢复、领取物品和传送等操作。GUI 中的这些操作使用独立的编辑权限检查，不会再逐项检查对应的命令权限。请只将它授予需要管理玩家数据的人员。