Endstone-ZJRAnticheat反作弊插件

ZJRAnticheat 插件介绍
项目        内容
插件名称        ZJRAnticheat
插件作者        zjr11693269（QQ：3508611589）
插件版本        V1.0.0Beta
适用平台        Minecraft 基岩版 (Bedrock) + Endstone 0.11+
运行环境        Python 3.11 及以上
许可证        Apache-2.0
说明：此插件有些阈值可能需要自己调节。

目录
插件简介
游戏内控制面板
检测模块
基岩版兼容处理
审计与记录
中文目录
AI 智能查找
物品栏查看与打包
性能设计
注意事项
安装与更新
联系方式

一、插件简介
ZJRAnticheat 是面向 Minecraft 基岩版 Endstone 服务端的反作弊与管理插件。
设计目标有三个：

1. 减少误判
   基岩版存在大量服务端无法完全复现的行为，例如载具位移、鞘翅加速、激流冲刺、爆炸击退、传送门切换、高延迟下的移动包成批到达等。插件针对这些情况做了专门兼容，避免正常玩家被误判，虽然做了大量兼容，但是还是有一些行为可能会误判，可能要自己改一下阈值，可直接在操作面板操作，如果您有什么好的建议，欢迎评论
2. 保留可调查性
   所有违规、惩罚、方块操作、玩家攻击与物品交互都会写入审计日志，管理员可以事后追溯，而不是只看到一次踢出。

3. 管理员不需要记命令
   执行 /ac 即可打开完整的游戏内控制面板，所有功能都能通过按钮完成。

   二、游戏内控制面板
   入口：在游戏内输入 /ac
   主菜单包含：
   入口        功能
   总览        实时 TPS、MSPT、在线人数、违规数、有效封禁、VL 排行、最近告警、检测引擎状态、VL 衰减参数
   玩家        玩家档案，可查看 VL、坐标、IP、设备、游戏模式、安全点、封禁状态，并执行拉回、警告、踢出、封禁、解封、清空 VL、单玩家检测豁免、查看个人日志、物品栏打包
   封禁        封禁中心，临时封禁、永久封禁、解封、封禁记录查询
   检测        检测模块开关，分类查看每个检测项，可单独开关、设置违规拉回与违规踢出、调整数值阈值
   VL阈值        全局惩罚阈值：拉回、警告、踢出、临时封禁
   日志        审计日志中心，分页浏览、按玩家与时段搜索
   方块        方块放置、破坏、交互记录
   行为        玩家攻击与交互记录
   AI        日志、方块、行为记录的自然语言查找
   物品栏        在线与离线玩家物品栏查看、打包成潜影盒
   系统        性能、VPN 与维护
   关于插件        名称、作者、版本与说明
   插件介绍        本介绍的完整内容
   所有开关状态统一显示为「当前：开」或「当前：关」。

   三、检测模块
   移动检测
   检测项        说明
   异常飞行        持续异常向上位移，超出跳跃与重力合理范围
   移动超速        水平移动速度超过当前状态允许的上限
   穿入方块        玩家身体进入实心方块内部
   水上行走        在没有支撑的水面上行走
   空中悬停        无支撑物长时间悬停在空中
   自动跳跃        地面连续且间隔完全一致地跳跃
   战斗检测
   检测项        说明
   超距攻击        攻击距离超过合法范围
   多目标攻击        同一 tick 多次攻击或极短时间内攻击多个目标
   怪物光环        极短时间攻击多个目标且视线没有转向
   光环超距        攻击距离明显超出客户端可及范围
   自动连点        点击间隔高度固定或 CPS 超过人类范围
   无击退响应        服务端施加击退后客户端没有相应位移
   攻击未挥手        造成伤害但没有对应挥手动作（默认关闭，见注意事项）
   方块交互检测
   检测项        说明
   异常快速挖掘        方块被破坏速度快于理论挖掘时间
   范围速破        同一 tick 或一秒内破坏过多方块
   异常快速放置        方块放置频率或间隔异常
   非法放置        目标位置被占用、超出距离或放置后无支撑
   背包清理        一秒内大量丢弃或清理物品
   方块交互超距        破坏或放置方块的距离超过合法范围
   协议检测
   检测项        说明
   数据包加速        发包速率显著高于正常值
   移动包瞬移        先静默后突发移动包（已按延迟自适应）
   非法数据包        数据包字段异常
   单 tick 多发移动包        同一 tick 收到过多移动包
   外挂专向检测（针对阿波罗 Apollon 客户端）
   检测项        说明
   自动搭路        脚下悬空时连续自动铺路
   梯子飞行        贴着梯子持续异常向上飞行
   异常放置朝向        方块放置朝向与玩家视线明显矛盾

   四、基岩版兼容处理
   以下行为不会被误判：
   创造模式、旁观模式
   死亡、重生、起床
   船、矿车、马、骆驼等载具
   鞘翅滑翔、烟花加速
   三叉戟激流冲刺
   重锤范围猛击
   荆棘附魔反伤
   击退、爆炸、活塞、风弹造成的位移
   水边、岸边台阶、楼梯、地毯
   进出下界门、末地门
   中键选取方块
   弓箭、弩、投掷物
   高延迟、低 TPS、服务器位置修正
   阈值会根据玩家延迟和服务器 TPS 自适应，但都保留硬上限，不会无限放宽。

   五、审计与记录
   所有时间均使用中国标准时间（UTC+8）。
   文件        路径        内容
   审计日志        logs/anticheat.log        违规、惩罚、系统事件，含玩家名、XUID、IP、检测项、VL、坐标、维度、时间
   方块记录        logs/blocks.log        放置、破坏、方块左右键交互
   行为记录        logs/activities.log        玩家攻击目标、伤害、功能性方块交互
   玩家档案        profiles.json        VL、违规计数、惩罚档位、封禁计数、检测豁免，服务器重启后自动恢复
   日志支持分页浏览，按玩家、时段、动作搜索。

   六、中文目录
   内置完整中文数据：
   类别        数量
   方块        1164 条
   物品        381 条
   实体        135 条
   附魔        43 项，含最高等级、适用物品、互斥关系与效果
   完整清单位于 docs 目录下的四个中文文档：
   BLOCK_CATALOG_ZH.md
   ITEM_CATALOG_ZH.md
   ENTITY_CATALOG_ZH.md
   ENCHANT_CATALOG_ZH.md
   物品栏可直接查看：
   物品中文名与数量
   自定义名称（命名牌、重命名物品）
   附魔中文名与等级，例如「锋利 V」「耐久 III」
   附魔合法性提示：超过上限、重复出现、互斥冲突
   潜影盒内的物品，支持潜影盒套潜影盒
   未知方块或物品显示为「未知方块」「未知物品」，不会直接暴露 minecraft: 英文 ID。

   七、AI 智能查找
   支持用一句话查询日志、方块记录和行为记录，例如：

   谁刚才攻击了
   Steve 今天放置了橡木楼梯
   最近 2 小时谁和箱子交互了
   昨天谁开挂了

   支持的服务商：
   DeepSeek
   OpenAI
   Anthropic Claude
   Google Gemini
   本地 Ollama
   自定义 OpenAI 兼容接口
   API Key 由管理员在面板内手动输入，按服务商分别保存。未配置或请求失败时自动回退到本地解析。
   查询只发送管理员输入的那句话，不发送玩家 IP、坐标或审计记录。

   八、物品栏查看与打包
   场景        行为
   在线玩家        实时读取主背包、装备、副手、末影箱
   离线玩家        使用退出时保存的快照
   打包        可选择打包全部、主背包、装备、副手、末影箱；结果以潜影盒形式放入管理员物品栏
   拆分        超过 27 件自动拆分为多个潜影盒
   如果写入失败，插件会明确提示打包失败，不会给管理员一个空盒子。

   九、性能设计
   事件处理器中不做文件、数据库、网络 I/O
   日志使用异步线程与有界队列
   VPN 在线订阅与数据库查询在后台线程执行
   移动检测使用距离平方比较，避免开方
   每 60 秒统计检测耗时，面板可查看平均与最大值

   十、注意事项

4. 阈值需要自己调节
   不同服务器版本、玩法、插件组合和玩家网络环境差异较大。建议先运行一段时间，观察日志里的误判记录，再到「检测」或「VL阈值」里微调具体数值，而不是一次性大幅放宽。
5. 「攻击未挥手」默认关闭
   该检测依赖客户端挥手动画，不同设备和延迟下容易误判，正常生存服建议保持关闭。
6. 透视类功能无法可靠检测
   Xray、ESP、FreeCam、夜视、无雾等属于纯客户端显示功能，服务端无法可靠判断。建议通过隐藏矿物、限制坐标广播、混料等方式降低收益。
7. 离线数据从安装后开始记录
   离线物品栏快照、玩家档案都在玩家退出或事件发生时保存，安装插件之前的操作无法追溯。

8. 提示信息为纯文本
   封禁、踢出、警告提示不带颜色代码，避免在部分客户端显示为乱码。

   十一、安装与更新
   安装：

   pip install endstone\\\_zjranticheat-1.0.0b0-py3-none-any.whl

   更新：

   pip uninstall -y endstone-zjranticheat
   pip install --force-reinstall endstone\\\_zjranticheat-1.0.0b0-py3-none-any.whl

   首次启动会在 plugins/zjranticheat 目录下生成：
   文件        用途
   config.toml        主配置
   profiles.json        玩家档案
   bans.json        封禁记录
   inventory\\\_snapshots.json        离线物品栏快照
   logs/        日志目录
   配置修改后可在面板内热重载，无需重启服务器。

   十二、联系方式
   作者：zjr11693269
   QQ：3508611589
   使用前请先备份配置与数据文件。