Files
ItxiaohuiContentGuard/README.md
T

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 摘要、日志、功能证据和未覆盖清单。