Voidkit Inspector 0.1.0-beta.1

Voidkit Inspector 0.1.0-beta.1

Voidkit 套件的操作审计模块。记录玩家对世界做了什么，出问题时能智能回滚——
不是简单地「按时间倒着撤销」，而是分五层判断哪些该回、哪些不该回。

下载

三条版本线挂在同一个 release 下，按文件名后缀区分，下载前先看清自己的环境：

Minecraft	加载器	文件
1.21.1	NeoForge 21.1.x	voidkit_inspector-0.1.0-beta.1+mc1.21.1-neoforge.jar
1.21.1	Forge 52.1.x	voidkit_inspector-0.1.0-beta.1+mc1.21.1-forge.jar
1.20.1	Forge 47.4.x	voidkit_inspector-0.1.0-beta.1+mc1.20.1-forge.jar

三条线均已在真实服务端上完成端到端验证（发布态 jar实际起服加载 + 审计库落盘）。

⚠️ 必须同时安装 voidkit_core，且core 的版本线要与本jar 一致。
Inspector 通过 voidkit_core 的 API 暴露数据与注册中心，缺 core 时 mod 会被加载器
静默跳过——服务端照常启动，只是没有审计，非常难发现。
core 也分版本线，从 KokuuWork/voidkit 的 release 下载对应的那一个
（NeoForge 版与 Forge 版的 jar 内含不同加载器 API，不能互相顶替）。

记录面：来源闸门

科技整合包里绝大多数方块变化是自动化产线干的，不是玩家。所以本模块的核心不是
「记录一切」，而是先分清来源：

来源	判定方式	默认
真人玩家	有网络连接的真 ServerPlayer	记
自动化	官方 FakePlayer，或ServerPlayer 但无网络连接	不记
自然	树叶腐烂 / 流体 / 重力方块	不记
强制名单	配置里点名的来源（爆炸、末影人搬方块等）	记

判定不只看「有没有连接」——官方 FakePlayer 自带 FakeConnection，只判 connection == null
会把产线全记进来。

恢复面：智能回滚五层

1. 分类感知 —— 按方块性质决定回滚策略；模组机器默认跳过（要 --include-machines），
   避免回滚把整条产线拆了
2. 结构感知 —— 门 / 床这类双格方块按「一对」处理；模组机器看6 向邻接识别连通体
3. 因果链聚类 —— 按「5 分钟内 + 32 格内 + 同维度」把一串操作聚成一条因果链，
   跨维度自动断链，回滚时整链一起处理
4. 预览 / 分帧执行 —— 先出预览（TTL 300s）确认范围，再分帧执行，不卡 TPS
5. 回滚撤销 —— 30 分钟内可撤销回滚本身（原子抢占，不会并发重复执行）

性能

• 写入：主线程只做 O(1) 入队，唯一写线程批量事务落库；队列满自动丢弃，绝不卡 TPS
• 查询：独立线程池 + 各自读连接，与写入并行
• 雪崩闸门：单 tick 入队上限 + 单来源每秒上限
• 存储：嵌入式 SQLite 单文件，零配置；全字典化 + keyset 分页，几十万条翻页毫秒级

命令

/voidkit inspect <玩家> [半径] [条数]     # 查某玩家的操作记录
/voidkit rollback <玩家> <半径> [条数]     # 智能回滚（先给预览）
/voidkit rollback confirm <会话>          # 确认执行预览中的回滚
/voidkit undo                # 撤销上一次回滚
/voidkit purge <玩家> [条数]               # 清理记录

权限

三个节点分离，管理员可以只给查询权不给回滚权：

• voidkit.inspector.node.view —— 查询
• voidkit.inspector.node.rollback —— 回滚 / 撤销
• voidkit.inspector.node.purge —— 清库

刻意不并入 voidkit.admin：审计模块的权限应该独立授予，
这样「能管服务器的人」不必自动获得「能抹掉审计记录的人」。

配置

零配置开箱即用，默认值就是推荐值。配置文件落在
<服务端>/voidkit/inspector/config.json，带中文注释。

已知限制

• 玩家数据存全量 NBT，模组作者若把大对象塞进方块实体，会让库快速变大
• 回滚只覆盖方块 / 容器 / 实体，不恢复玩家背包与末影箱内容
• 跨维度因果链会被断开，避免「在主城放个方块结果回滚了下界」这种误伤

反馈

这是 beta，欢迎在 KokuuWork/voidkit-inspector 提 issue。