# Chat Moderator – AI-Assisted Chat Moderation for Paper 1.21
一个轻量级、免费的、AI辅助的聊天审核插件，适用于Paper 1.21版本的Minecraft服务器。ChatMod结合了快速的正则表达式/语言过滤，以及可选的离线ONNX模型分类器，可以在不使用付费API的情况下准确地审核有毒、仇恨、性暗示和骚扰消息。
## 特性
- 混合审核：正则表达式 + 可选的RoBERTa ONNX AI
- 具备身份意识的仇恨检测（无需API密钥）
- 语言检测和阻止
- 可调整的阈值、惩罚和严格模式
- 管理工具用于审核、训练和状态
- 具有自动保存的持久性统计数据（SQLite/MySQL）和自动迁移
- 文件/数据库日志记录和审核工具
- 使用异步分类和缓存进行性能优化
- 完全离线工作（无需付费API）
- 高度可配置和可扩展
## 安装
1. 将`ChatModer.jar`放入服务器的`plugins/`目录
2. 重启服务器以生成`plugins/ChatModer/config.yml`
3. （可选）在`plugins/ChatModer/models/`下添加一个ONNX模型文件夹，并将配置文件指向ONNX文件
## AI模型设置（Hugging Face RoBERTa）
ChatModer支持Hugging Face RoBERTa ONNX模型，例如`protectai/unbiased-toxic-roberta-onnx`。
创建一个文件夹，例如：
```
plugins/ChatModer/models/unbiased-toxic-roberta-onnx/
```
将以下文件放入其中：
- `model_quantized.onnx` (推荐) 或 `model.onnx`
- `config.json` (包含id2label/label2id)
- `tokenizer.json` (首选)，或 `vocab.json` + `merges.txt`
- 可选：`tokenizer_config.json`, `special_tokens_map.json`
配置片段：
```yaml
moderation:
ai:
enabled: true
model_path: plugins/ChatModer/models/unbiased-toxic-roberta-onnx/model_quantized.onnx
max_sequence_length: 128
async_threads: 2
timeout_ms: 500
```
分词器/配置文件从ONNX文件的相同文件夹中自动加载。
### 标签映射
- `obscene` -> `profanity`
- `insult`/`threat` -> `harassment`
- `sexual_explicit` -> `sexual`
- `identity_attack` -> `hate`
- `toxicity`/`severe_toxicity` 略微提升 profanity/harassment 的评分
- 仅身份的标签（例如`black`、`muslim`）本身不会被标记；当与 insult/toxicity 结合时，它们起到上下文的作用
## 模式
- __regex__: 仅正则表达式/词列表启发式方法
- __ai-only__: 仅ONNX模型（如果启用）；仍然使用语言阻止和白名单
- __hybrid__ (推荐)：结合正则表达式 + AI；AI评分可以通过`moderation.ai.weight`进行加权
```yaml
moderation:
enabled: true
mode: hybrid # regex | ai-only | hybrid
ai:
enabled: true
weight: 0.8
```
## 数据库 & 自动保存
统计数据默认持久化到SQLite或MySQL，如果已配置。 该插件可以将现有的SQLite统计数据自动迁移到MySQL。
```yaml
database:
type: sqlite
sqlite_file: plugins/ChatModer/data.db
mysql:
host: 127.0.0.1
port: 3306
database: chatmoder
user: root
password: "secret"
useSSL: false
sqlite_migrate_file: plugins/ChatModer/data.db
stats:
autosave_seconds: 300
```
## 阈值 & 惩罚
调整每个类别的审核灵敏度和操作。
```yaml
thresholds:
profanity: 0.7
harassment: 0.6
hate: 0.6
sexual: 0.7
spam: 0.8
punishments:
profanity: block # warn | tempmute | kick | tempban | block | command:
harassment: warn
hate: tempmute
sexual: block
spam: block
```
## 日志记录 & 审核
- __文件日志__: JSONL写入到`plugins/ChatModer/logs/flags.log`
- __数据库日志__: SQLite/MySQL `flags` 表 (可选)
- __审核__: `/chatmod review ` 从数据库读取 (如果已启用)，否则读取文件日志。 支持 legacy 漂亮的打印日志和紧凑型 JSONL。
## 命令
- `/chatmod toggle` — 启用/禁用审核。
- `/chatmod status` — 实时统计信息概览。
- `/chatmod review ` — 审核最近标记的消息。
- `/chatmod whitelist add|remove ` — 管理白名单。
- `/chatmod strict reload` — 重新加载严格列表。
- `/chatmod train add|capture|fromlog|words|stats|export` — 数据集工具。
- `/chatmod stats reset confirm` — 清除内存中的统计数据并立即持久化。
## 训练工作流 (可选)
- __Capture__: 记录最近的消息作为训练的上下文
- __From log__: 将标记日志挖掘到数据集中
- __Words__: 词频分析
- __Stats__: 训练数据集统计信息
- __Export__: 输出 `dataset.jsonl`，为微调做好准备
所有工具都可在`/chatmod train ...`下使用。
## 严格模式
对于即时阻止（例如，高严重性令牌），启用严格规则并重新加载它们，无需重启：
```
/chatmod strict reload
```
## 权限
- `chatmod.admin` — 访问管理命令
- `chatmod.bypass` — 绕过审核
- `chatmod.review` — 访问审核工具
## 性能
- 仅正则表达式模式，以实现最少的开销
- AI 异步运行并使用 CPU 上的量化 ONNX 模型
- 令牌和消息缓存以减少重复工作
## 隐私
所有处理都是本地的。 除非你启用了webhook，否则不会进行任何外部API调用。
## 兼容性
- Paper 1.21 (大多数现代分支应可以使用)
- Java 17+
- SQLite 包含在内；MySQL 需要有效的凭据
## 故障排除
- __ONNX模型未加载__: 检查 `moderation.ai.model_path` 并确保 `config.json` 和 `tokenizer.json`（或 `vocab.json` + `merges.txt`）在同一目录下。
- __分类超时__: 增加 `moderation.ai.timeout_ms` 或减少 `max_sequence_length`。
- __CPU使用率高__: 使用 `model_quantized.onnx` 并将 `max_sequence_length` 保持在 128/256。
- __审核显示没有条目__: 确保启用日志记录（文件或数据库）并且你的日志不是空的。
## 支持
在项目存储库中打开一个 issue，提供日志、配置和重现步骤。 如果你使用自定义模型，请提供模型详细信息。