5.4 KiB
小慧内容卫士 · ItxiaohuiContentGuard
Minecraft Java Edition 服务端内容审核插件,使用 Java 21。当前版本为开发候选。请先查看兼容验收记录,再决定是否在隔离环境试用。
构建与试用
.\gradlew.bat build compatProbeJar
将 build/libs/ItxiaohuiContentGuard-0.2.0-dev.jar 放入测试服务器的 plugins 目录。构建目录中的 -thin.jar 缺少运行库。-compat-probe.jar 用于复现验收。启动后执行 /icg info 查看实际核心、Minecraft 和调度器,执行 /icg status 查看 AI、SMTP 和 SQLite 的运行状态。
首次启动生成下列设置。用编辑器保存后执行 /icg reload。配置解析失败时保留最后一组可用设置。运行中的 AI 和邮件任务允许用提交时的服务设置完成。
| 文件或目录 | 内容 |
|---|---|
config.yml |
邮件中的服务器名称、书本绕过开关、审计保留天数 |
words.yml |
主词库、匹配选项、全局替换字符串和输入限制 |
blacklist.yml |
附加敏感词规则 |
whitelist.yml |
白名单和忽略词 |
rules.yml |
等级对应的动作、通知阈值、禁言时长和重复违规邮件 |
ai.yml |
OpenAI 兼容审核 |
smtp.yml |
邮件通知 |
database/ |
SQLite 审计、WAL 文件 |
logs/ |
管理员导出的 UTF-8 CSV |
敏感词和处理动作
rules:
- word: '违规词示例'
mode: CONTAINS
category: INSULT
severity: MEDIUM
replacement: '***'
CONTAINS匹配字段片段。EXACT匹配整个标准化字段。书本的标题和每页正文分别匹配。- 字符串简写使用
CONTAINS、OTHER和LOW。词库更新后以/icg test <内容>检查实际效果。 - 将白名单词放在
whitelist.yml的words或ignored列表。敏感词命中完全落在例外范围中时放行。 - 去分隔符和重复字符匹配可以通过
settings关闭。词库会在标准化后查找命中,再按原文位置替换。 - 单条内容使用最高命中等级在
rules.yml配置的动作。BLOCK拦截,REPLACE替换,RECORD记录,WARN警告,NOTIFY通知管理员,EMAIL发邮件。 MUTE和KICK可以显式添加,默认关闭。默认禁言适配器使用进程内状态,覆盖受控聊天和私聊入口。
第三方 Bukkit 插件可从 ServicesManager 加载 dev.itxiaohui.contentguard.api.ContentGuardApi 并调用 inspect(String)。可在异步线程调用。返回值包括原文、标准化文本、过滤结果、命中规则和输入限制状态。第三方私聊实现可以在自己的发送入口调用此服务。
AI 审核
设置 base-url、api-key、model。例如兼容服务给出的基础地址为 https://example.org/v1 时使用该地址,插件会请求其 chat/completions 路径。供应商专用请求参数填写到 request-parameters 的 JSON 对象里。可调整系统提示词、审核提示词及类别列表。
| 模式 | 行为 |
|---|---|
OFF |
默认。使用本地审核。 |
RECORD |
内容按本地规则处理,AI 异步记录结果。 |
AUTO |
等待 AI 结果,结合校验后的建议与等级动作处理。 |
STRICT |
等待审核,safe=true 后允许发送。 |
failure-allow: false 会在 AUTO、STRICT 的审核失败时拦截。设置为 true 时沿用本地结果。请求超时、含排队的总期限、并发、队列、速率、缓存、重试和熔断均在 ai.yml 配置。启用 AI 会将玩家待审内容发给配置的供应商。异步聊天恢复使用服务端系统消息,延迟路径不保留原有的客户端签名和其他聊天插件的专用渲染信息。执行 /icg ai test 验证接口。
SMTP
设置 enabled: true、host、port、from 和 to。需要认证时填写 username 和 password。使用直接 TLS 时设置 ssl: true,使用 STARTTLS 时设置 starttls: true。二者按邮件服务商要求选择。执行 /icg email test,并核对收件箱。邮件包含玩家原文、审核结果等数据。请按权限管理配置目录、SQLite、导出文件和收件邮箱。
管理命令
| 命令 | 操作 |
|---|---|
/icg help |
显示当前权限可用的子命令 |
/icg info、/icg status |
核心识别、适配器与服务状态 |
/icg reload |
异步热重载 YAML |
/icg words [页码] |
浏览词库 |
/icg add <词语>、/icg remove <词语> |
更新主词库 |
/icg test <内容> |
测试本地文字匹配 |
/icg logs [编号] |
最近记录或指定记录 |
/icg player <玩家>、/icg stats |
玩家记录、按类别计数 |
/icg export |
导出审计 CSV |
/icg ai status、/icg ai test [内容] |
AI 状态与接口检查 |
/icg email test |
发送 SMTP 测试邮件 |
权限前缀为 itxiaohui.contentguard.。后缀 admin 可管理插件,logs 可读审计,test 可用本地测试,notify 可接收告警。显式授权 bypass 可以绕过公共聊天与匹配到的私聊命令。书本绕过还要求 book.allow-bypass: true。公共聊天的权限快照在加入服务器或执行命令时刷新。
兼容与复测
架构与复测命令介绍上游、独立运行目录和测试客户端。验收记录包含 Minecraft 小版本矩阵、实际 JAR 摘要、日志、功能证据和未覆盖清单。