AdvancedSensitiveWords
AdvancedSensitiveWords 是一款基于 DFA 词匹配、基于事件的内容检查、模块化违规等级以及可选的 LLM 辅助聊天审查构建的 Paper 管理插件。
2.x 是一个破坏性更新版本。 它仅针对 Paper,使用带有 Kotlin DSL 的 Gradle,并生成新的 kebab-case 配置模型。在未经仔细审查所有设置的情况下,请勿复用 2.0 之前的配置文件。
要求
| 组件 |
要求 |
| 服务器 |
Paper 1.21.11 或更高版本 |
| Java |
Java 21 |
| 代理(可选) |
Velocity 及对应的 Velocity jar 包 |
| 可选集成 |
TrChat, PacketEvents, PlaceholderAPI, floodgate, AuthMe |
自 2.x 版本起不再支持 Spigot、CraftBukkit 和 BungeeCord。
安装
- 从发行版下载 Paper 工件,或在本地构建
paper:shadowJar。
- 将 Paper jar 放入服务器的
plugins/ 目录并启动一次 Paper。
- 配置
plugins/AdvancedSensitiveWords/config.yml 以及生成的 messages_en.yml 或 messages_zhcn.yml。
- 更改词典后运行
/asw reload all,或仅更改配置后运行 /asw reload config。
对于 Velocity 通知和代理命令,请在代理上安装 Velocity 工件,在 Paper 上设置 plugin.hook-velocity: true,然后重启两端。代理模块本身不进行聊天过滤。
2.x 过滤器涵盖范围
- 聊天和命令:Paper
AsyncChatEvent、命令预处理、跨消息聊天上下文、可配置的替换或取消、取消时的虚假消息,以及与 TrChat 虚假消息/影子封禁的兼容性。
- 书籍:基于事件的 writable-book 检查,取消模式下的可选跨页检查,以及对已处理书籍内容的有界缓存。
- 告示牌:逐行、多行及最近告示牌上下文检查。在取消模式下,可选的 PacketEvents 虚假视图可以让作者看到其尝试输入的文本,而其他玩家则保留真实、干净的告示牌视图。
- 铁砧和物品:重命名结果过滤,以及使用 Adventure 组件进行的物品显示名称和描述过滤。
- 玩家名称和广播:拒绝登录被屏蔽的名称,以及可选的广播过滤。
- 可选 LLM 聊天审查:对未匹配 DFA 或聊天上下文的异步、按成本限制的审查。默认禁用,且不会撤回聊天;它可以通知、记录、增加单独的 AI VL,并在验证响应后执行配置的操作。
快速配置
配置以 lowercase kebab-case 生成。生成的文件是默认的权威列表及内联注释。
plugin:
language: en
enable-chat-check: true
enable-sign-edit-check: true
chat:
method: CANCEL # REPLACE or CANCEL
fake-message-on-cancel: false
context-check: true
REPLACE 会将匹配的文本替换为配置的替换内容。CANCEL 会拒绝受影响的交互。虚假聊天消息和告示牌虚假视图仅为取消模式功能。
命令参数规则
chat.command-white-list 还定义了哪些命令参数会被检查。在默认的 invert-command-white-list: true 下,列出的命令路径会被检查,而列表外的命令将被跳过。
chat:
invert-command-white-list: true
command-white-list:
- "[default:include] /msg [ignore:1]"
- "[default:include] /bc [ignore:1,-1]"
- "[default:ignore] /mail send [include:2..]"
参数从命令路径后的 1 开始编号。-1 表示最后一个参数;2.. 表示从第二个参数到末尾。include 和 ignore 指令按顺序处理。被忽略的参数会分割检测段,因此被屏蔽的词无法跨越跳过的玩家名称、服务器名称、数量或其他参数进行匹配。
惩罚与违规等级
每个过滤器模块都有其自己的 punishment 列表及其各自的 VL:CHAT、AI、BOOK、SIGN、ANVIL 和 ITEM。命令共享 CHAT VL。plugin.manual-punishment 中的手动默认列表是例外:其 VL 条件使用跨模块的总和。
chat:
punishment:
- "COMMAND|kick %player% Blocked content|VL>2"
- "SHADOW|60|VL>5"
支持的操作类型包括 COMMAND、COMMAND_PROXY、DAMAGE、HOSTILE、EFFECT 和 SHADOW。在命令动作中使用 %player% 或 %PLAYER%。空列表会保持检测、日志记录、通知和 VL 计数处于活动状态,同时禁用自动操作。
可选 LLM 审核
仅在配置了兼容提供商和 API 密钥后启用 LLM 审查。Paper 通过 plugin.yml 加载 LangChain4j 库,因此服务器需要在首次启动期间具有网络访问权限或现有的 Paper 库缓存。
ai:
enabled: true
base-url: https://api.deepseek.com
api-mode: CHAT_COMPLETIONS # CHAT_COMPLETIONS, RESPONSES, or ANTHROPIC_MESSAGES
api-key-environment: DEEPSEEK_API_KEY
model-name: deepseek-v4-flash
在发出请求之前,ASW 要求直接 DFA 和聊天上下文检查均未命中,然后应用消息长度、熵、每位玩家的冷却时间、飞行中、并发性和队列限制。LLM 输出在采取任何后续操作之前会在本地进行严格解析。
每个类别在 ai.category-policy 下都有独立的通知和惩罚置信度阈值及操作。LLM 请求和响应会在 plugins/AdvancedSensitiveWords/llm-history/ 中进行审计。将此目录视为敏感的操作数据。
ai.server-context-can-override 是一项服务器所有者策略开关。启用时,ai.server-context 会被插入到可信系统策略中,并且故意不包含在用户 JSON 负载中。请保持策略文本由管理员控制;切勿在其中放置玩家输入、凭证或私有数据。
命令
| 命令 |
用途 |
/asw help [query] |
显示命令帮助。 |
/asw status |
显示插件总体状态。 |
/asw ai status |
显示 LLM 运行时计数器、队列状态、模型、API 模式及分类策略。 |
/asw reload [all|config] |
重新加载配置,或重新加载配置与词库。 |
/asw test <text...> |
对文本进行 DFA 过滤器测试。 |
/asw word add/remove <word> [word...] |
仅在当前运行时修改屏蔽词列表。 |
/asw allow add/remove <word> [word...] |
仅在当前运行时修改白名单(允许词)列表。 |
/asw player info <online-player> |
显示单个模块及总体的违规等级(VL)。 |
/asw player reset <online-player> [module] |
重置所有或指定模块的违规等级(VL)。 |
/asw player punish <online-player> [method...] |
执行配置好的手动惩罚措施或指定的操作。 |
/asw teleport <world-id> <x> <y> <z> |
将工作人员传送至被举报的位置。 |
/asw 与 /advancedsensitivewords 等效。在完全重新加载词库或服务器重启时,运行时的词列表变更将被丢弃。
权限
| 权限节点 |
默认值 |
用途 |
advancedsensitivewords.bypass |
false |
绕过过滤。 |
advancedsensitivewords.notice |
op |
接收工作人员通知。 |
advancedsensitivewords.update |
op |
接收更新通知。 |
advancedsensitivewords.command.* |
false |
所有管理命令的父节点。 |
advancedsensitivewords.command.help |
op |
使用帮助命令。 |
advancedsensitivewords.command.status |
op |
使用总体状态命令。 |
advancedsensitivewords.command.ai.status |
op |
使用 AI 状态命令。 |
advancedsensitivewords.command.reload.all |
op |
重新加载配置和词库。 |
advancedsensitivewords.command.reload.config |
op |
仅重新加载配置。 |
advancedsensitivewords.command.test |
op |
使用 DFA 测试。 |
advancedsensitivewords.command.word.add |
op |
在运行时添加屏蔽词。 |
advancedsensitivewords.command.word.remove |
op |
在运行时移除屏蔽词。 |
advancedsensitivewords.command.allow.add |
op |
在运行时添加允许词。 |
advancedsensitivewords.command.allow.remove |
op |
在运行时移除允许词。 |
advancedsensitivewords.command.player.info |
op |
检查玩家违规等级(VL)。 |
advancedsensitivewords.command.player.reset |
op |
重置玩家违规等级(VL)。 |
advancedsensitivewords.command.player.punish |
op |
施加手动惩罚。 |
集成与 API
- TrChat:支持假聊天消息与阴影禁令(shadowban)显示的兼容性。TrChat 仍负责其自身的格式化管道。
- PacketEvents:可选依赖,仅用于告示牌的假视图功能。若未安装,告示牌取消行为仍将生效,但不会显示假视图。
- PlaceholderAPI:启用
plugin.enable-placeholder 以暴露 %asw_version%、%asw_total_filtered%、%asw_is_shadow% 和 %asw_violation_count% 占位符。
- Floodgate / AuthMe:可选支持 Bedrock 用户名与认证状态处理。
其他 Paper 插件无需依赖实现类即可访问阴影禁令 API:
import io.wdsj.asw.bukkit.api.AdvancedSensitiveWordsApi;
import java.time.Duration;
AdvancedSensitiveWordsApi.shadowBan().shadow(player, Duration.ofMinutes(5));
AsyncModerationResponseEvent 在 LLM 响应后异步触发。事件处理器可以观察、取消 ASW 的后续操作,或替换已验证的结果,但必须自行安排 Bukkit 实体/世界的操作。
从源码构建
.\gradlew.bat --no-daemon build
许可证
AdvancedSensitiveWords 采用 GNU AGPL-3.0 许可证授权。
链接
AdvancedSensitiveWords
AdvancedSensitiveWords is a Paper moderation plugin built around DFA word matching, event-based content inspection, modular violation levels, and optional LLM-assisted chat review.
2.x is a breaking release. It targets Paper only, uses Gradle with Kotlin DSL, and generates a new kebab-case configuration model. Do not reuse pre-2.0 configuration files without reviewing every setting.
Requirements
| Component |
Requirement |
| Server |
Paper 1.21.11 or higher |
| Java |
Java 21 |
| Proxy (optional) |
Velocity with the matching Velocity jar |
| Optional integrations |
TrChat, PacketEvents, PlaceholderAPI, floodgate, AuthMe |
Spigot, CraftBukkit, and BungeeCord are not supported since version 2.x.
Installation
- Download the Paper artifact from the release, or build
paper:shadowJar locally.
- Put the Paper jar in the server
plugins/ directory and start Paper once.
- Configure
plugins/AdvancedSensitiveWords/config.yml and the generated messages_en.yml or messages_zhcn.yml.
- Run
/asw reload all after changing dictionaries or /asw reload config after changing only configuration.
For Velocity notifications and proxy commands, install the Velocity artifact on the proxy, set plugin.hook-velocity: true on Paper, then restart both sides. The proxy module does not filter chat by itself.
What 2.x Filters
- Chat and commands: Paper
AsyncChatEvent, command preprocessing, cross-message chat context, configurable replacement or cancellation, fake messages on cancellation, and TrChat fake-message/shadowban compatibility.
- Books: event-based writable-book checking, optional cross-page checking in cancel mode, and a bounded cache for processed book content.
- Signs: per-line, multi-line, and recent-sign context checking. In cancel mode, optional PacketEvents fake view can show the author their attempted text while other players retain the real, clean sign view.
- Anvils and items: rename-result filtering plus item display-name and lore filtering using Adventure components.
- Player names and broadcasts: login rejection for blocked names and optional broadcast filtering.
- Optional LLM chat review: asynchronous, cost-gated review for messages that did not match DFA or chat context. It is disabled by default and never retracts chat; it can notify, record, increment the separate AI VL, and run configured actions after a validated response.
Quick Configuration
Configuration is generated in lower kebab-case. The generated file is the authoritative list of defaults and inline comments.
plugin:
language: en
enable-chat-check: true
enable-sign-edit-check: true
chat:
method: CANCEL # REPLACE or CANCEL
fake-message-on-cancel: false
context-check: true
REPLACE changes matched text with the configured replacement. CANCEL rejects the affected interaction. Fake chat messages and sign fake view are cancellation-only features.
Command Argument Rules
chat.command-white-list also defines which command arguments are inspected. With the default invert-command-white-list: true, listed command paths are inspected and commands outside the list are skipped.
chat:
invert-command-white-list: true
command-white-list:
- "[default:include] /msg [ignore:1]"
- "[default:include] /bc [ignore:1,-1]"
- "[default:ignore] /mail send [include:2..]"
Arguments are numbered after the command path, starting at 1. -1 is the final argument; 2.. means the second argument through the end. include and ignore directives are processed in order. Ignored arguments split detection segments, so a blocked word cannot match across a skipped player name, server name, count, or other parameter.
Punishments and Violation Levels
Each filter module has its own punishment list and its own VL: CHAT, AI, BOOK, SIGN, ANVIL, and ITEM. Commands share the CHAT VL. The manual default list at plugin.manual-punishment is the exception: its VL conditions use the total across modules.
chat:
punishment:
- "COMMAND|kick %player% Blocked content|VL>2"
- "SHADOW|60|VL>5"
Supported action types are COMMAND, COMMAND_PROXY, DAMAGE, HOSTILE, EFFECT, and SHADOW. Use %player% or %PLAYER% in command actions. Empty lists keep detection, logging, notification, and VL counting active while disabling automatic actions.
Optional LLM Moderation
Enable LLM review only after configuring a compatible provider and API key. Paper loads LangChain4j libraries through plugin.yml, so the server needs network access or an existing Paper library cache during the first startup.
ai:
enabled: true
base-url: https://api.deepseek.com
api-mode: CHAT_COMPLETIONS # CHAT_COMPLETIONS, RESPONSES, or ANTHROPIC_MESSAGES
api-key-environment: DEEPSEEK_API_KEY
model-name: deepseek-v4-flash
Before a request, ASW requires that direct DFA and chat-context checks miss, then applies message-length, entropy, per-player cooldown, in-flight, concurrency, and queue limits. LLM output is strictly parsed locally before any follow-up action.
Each category has independent notification and punishment confidence thresholds and actions under ai.category-policy. LLM requests and responses are audited in plugins/AdvancedSensitiveWords/llm-history/. Treat this directory as sensitive operational data.
ai.server-context-can-override is a server-owner policy switch. When enabled, ai.server-context is inserted into the trusted system policy and is intentionally omitted from the user JSON payload. Keep policy text administrator-controlled; never place player input, credentials, or private data there.
Commands
| Command |
Purpose |
/asw help [query] |
Show command help. |
/asw status |
Show general plugin status. |
/asw ai status |
Show LLM runtime counters, queue state, model, API mode, and category policies. |
/asw reload [all|config] |
Reload configuration, or configuration plus dictionaries. |
/asw test <text...> |
Test text against the DFA filter. |
/asw word add/remove <word> [word...] |
Mutate the blocked-word list for the current runtime only. |
/asw allow add/remove <word> [word...] |
Mutate the allowed-word list for the current runtime only. |
/asw player info <online-player> |
Show per-module and total VL. |
/asw player reset <online-player> [module] |
Reset all or one module VL. |
/asw player punish <online-player> [method...] |
Execute configured manual punishment or one supplied action. |
/asw teleport <world-id> <x> <y> <z> |
Teleport a staff member to a reported location. |
/asw and /advancedsensitivewords are equivalent. Runtime word-list mutations are discarded on a full dictionary reload or server restart.
Permissions
| Permission |
Default |
Purpose |
advancedsensitivewords.bypass |
false |
Bypass filtering. |
advancedsensitivewords.notice |
op |
Receive staff notifications. |
advancedsensitivewords.update |
op |
Receive update notices. |
advancedsensitivewords.command.* |
false |
Parent node for all management commands. |
advancedsensitivewords.command.help |
op |
Use help. |
advancedsensitivewords.command.status |
op |
Use general status. |
advancedsensitivewords.command.ai.status |
op |
Use AI status. |
advancedsensitivewords.command.reload.all |
op |
Reload configuration and dictionaries. |
advancedsensitivewords.command.reload.config |
op |
Reload configuration only. |
advancedsensitivewords.command.test |
op |
Use DFA test. |
advancedsensitivewords.command.word.add |
op |
Add blocked words at runtime. |
advancedsensitivewords.command.word.remove |
op |
Remove blocked words at runtime. |
advancedsensitivewords.command.allow.add |
op |
Add allowed words at runtime. |
advancedsensitivewords.command.allow.remove |
op |
Remove allowed words at runtime. |
advancedsensitivewords.command.player.info |
op |
Inspect player VL. |
advancedsensitivewords.command.player.reset |
op |
Reset player VL. |
advancedsensitivewords.command.player.punish |
op |
Apply manual punishment. |
Integrations and API
- TrChat: compatibility for fake chat messages and shadowban display. TrChat remains responsible for its own formatting pipeline.
- PacketEvents: optional and soft-required only for sign fake view. Without it, sign cancel behavior remains active without a fake view.
- PlaceholderAPI: enable
plugin.enable-placeholder to expose %asw_version%, %asw_total_filtered%, %asw_is_shadow%, and %asw_violation_count%.
- Floodgate / AuthMe: optional Bedrock-name and authentication-state handling.
Other Paper plugins can access the shadowban API without depending on implementation classes:
import io.wdsj.asw.bukkit.api.AdvancedSensitiveWordsApi;
import java.time.Duration;
AdvancedSensitiveWordsApi.shadowBan().shadow(player, Duration.ofMinutes(5));
AsyncModerationResponseEvent is fired asynchronously after an LLM response. Event handlers may observe, cancel ASW follow-up, or replace the validated result, but must schedule Bukkit entity/world work themselves.
Building From Source
.\gradlew.bat --no-daemon build
License
AdvancedSensitiveWords is licensed under the GNU AGPL-3.0.
Links
评论 0
登录后参与评分
还没有评论,来抢沙发吧