Files
ItxiaohuiContentGuard/README.md
T

85 lines
5.4 KiB
Markdown

# 小慧内容卫士 · ItxiaohuiContentGuard
Minecraft Java Edition 服务端内容审核插件,使用 Java 21。当前版本为开发候选。请先查看[兼容验收记录](docs/验收摘要.md),再决定是否在隔离环境试用。
## 构建与试用
```powershell
.\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 |
## 敏感词和处理动作
```yaml
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`。公共聊天的权限快照在加入服务器或执行命令时刷新。
## 兼容与复测
[架构与复测命令](docs/兼容架构.md)介绍上游、独立运行目录和测试客户端。[验收记录](docs/验收摘要.md)包含 Minecraft 小版本矩阵、实际 JAR 摘要、日志、功能证据和未覆盖清单。