ArkShield-AI

基于 AI 大模型的 Minecraft 聊天违禁词检测插件

🏢 筑梦方舟网络科技工作室版权所有

简介

ArkShield-AI 是一款适用于 Minecraft Purpur 1.21.1 服务器的聊天内容审核插件。通过接入 AI 大模型（默认 DeepSeek），对玩家发送的聊天消息进行智能违禁词检测，支持三级检测力度、自动禁言、管理员手动禁言等功能。

功能特性

• AI 智能检测 — 基于大语言模型分析聊天内容，比传统关键词匹配更准确
• 三级检测力度 — 简易 / 普通 / 严格，可在配置文件或命令中切换
• 异步不阻塞 — AI 请求异步执行，不影响服务器 TPS
• 自动禁言 — 达到违规次数阈值自动禁言，支持配置时长和阈值
• 管理员手动禁言/解禁 — 命令控制，灵活管理
• 结果缓存 — 相同消息不重复请求 AI，减少 API 调用
• 日志记录 — 被拦截消息可输出到控制台和日志文件
• 管理员通知 — 被拦截消息实时通知在线管理员
• 权限系统 — 支持 bypass 权限绕过检测

环境要求

快速开始

1. 构建

mvn clean package

构建产物位于 target/ArkShield-AI-1.0.0.jar。

2. 部署

将 ArkShield-AI-1.0.0.jar 复制到服务器的 plugins/ 目录下，重启服务器。

3. 配置 API Key

首次启动后会自动生成 plugins/ArkShield-AI/config.yml，编辑其中的 ai.api-key 字段：

ai:
  base-url: "https://api.deepseek.com/v1"
  api-key: "sk-your-api-key-here"  # 替换为你的真实 API Key
  model: "deepseek-chat"

支持任何 OpenAI 兼容接口，只需修改 base-url 和 api-key 即可。

4. 重启服务器

配置完成后重启服务器，插件即可生效。

命令

权限节点

检测等级

配置文件说明

配置文件路径：plugins/ArkShield-AI/config.yml

# AI 接口配置
ai:
  base-url: "https://api.deepseek.com/v1"  # API 地址
  api-key: "sk-your-api-key-here"           # API 密钥
  model: "deepseek-chat"                    # 模型名称
  enable-thinking: false                    # 思考模式（仅 reasoner）
  timeout: 15                               # 请求超时（秒）

# 检测等级（1/2/3）
level: 2

# 禁言配置
mute:
  enabled: true               # 开启自动禁言
  violation-threshold: 3      # 触发禁言所需违规次数
  duration-minutes: 10        # 禁言时长（分钟）
  violation-reset-minutes: 60 # 违规计数重置时间（分钟）

# 消息配置（支持 & 颜色代码）
messages:
  blocked: "&c[ArkShield] &f你的消息包含不当内容，已被拦截。"
  admin-alert: "&e[ArkShield] &f玩家 &c%player% &f发送了被拦截的消息: &7%message%"

# 管理员通知
admin-notify:
  enabled: true
  permission: "arkshield.admin"

# 日志配置
logging:
  log-to-console: true
  log-to-file: true
  log-file: "blocked_messages.log"

# 缓存配置
cache:
  enabled: true
  expire-minutes: 30
  max-size: 1000

工作流程

玩家发送消息
    │
    ├── 有 bypass 权限？ ──→ 直接放行
    │
    ├── 被禁言中？ ──→ 拦截并提示剩余时间
    │
    ├── 发送者立即看到自己的消息
    │
    ├── 异步发送 AI 检测请求
    │       │
    │       ├── AI 返回正常 ──→ 消息广播给其他玩家
    │       │
    │       └── AI 返回违禁 ──→ 拦截消息
    │               ├── 通知玩家
    │               ├── 通知管理员
    │               ├── 记录日志
    │               ├── 记录违规次数
    │               └── 达到阈值？ ──→ 自动禁言
    │
    └── AI 请求异常 ──→ 默认放行（不影响聊天）

文件结构

ArkShield-AI/
├── pom.xml
├── README.md
└── src/main/
    ├── java/com/arkshield/ai/
    │   ├── ArkShieldAI.java           # 插件主类
    │   ├── command/
    │   │   └── ArkShieldCommand.java  # 管理命令
    │   ├── config/
    │   │   └── ConfigManager.java     # 配置管理
    │   ├── listener/
    │   │   └── ChatListener.java      # 聊天事件监听
    │   └── service/
    │       ├── AIService.java         # AI 接口服务
    │       ├── HeartbeatService.java  # 心跳上报服务(用于使用者数量统计)
    │       └── MuteService.java       # 禁言管理服务
    └── resources/
        ├── config.yml                 # 默认配置
        └── plugin.yml                 # 插件描述

许可证

本项目基于 MIT 许可证 开源。

Copyright © 2026 筑梦方舟网络科技工作室