koishi-plugin-discord-ai-guard

用于 Koishi 的 Discord 频道 AI 审核插件。它会把指定频道里的消息发给 OpenAI 兼容接口，判断是否为诈骗广告或色情广告，并按配置执行撤回、踢出、禁用/封禁。插件还提供可选 Web 管理页面和 Minecraft 服务器状态监控。

功能

• 监听指定 Discord 频道，频道 ID 可用 Koishi inspect 插件查看。
• 支持 OpenAI 官方接口，也支持 OpenAI 兼容中转站。
• 支持配置多个 AI 接口，主接口失败后会自动切换到备用接口。
• 支持获取模型列表，方便从中转站返回的模型里选择。
• 支持诈骗广告、色情广告两类审核，可单独启用。
• 支持撤回消息、踢出成员、禁用/封禁成员三个动作。
• 支持演练模式，只记录命中结果，不实际处罚。
• 支持测试命令检查 AI 接口是否可用。
• 支持读取 Discord Embed/富文本消息中的标题、描述、字段和链接，空正文广告也会进入 AI 审核。
• 支持图片上下文：可只发送图片链接，也可对支持视觉输入的模型启用 vision 模式。
• 支持 Koishi Console Web 管理页面，管理Web备用AI接口、获取模型列表、测试接口、管理Minecraft服务器。
• 支持 Minecraft Java/Bedrock 服务器状态检测，启动后只发一条 Discord 状态消息，后续按间隔编辑这条消息；状态消息可选普通文本或 Discord Embed，Embed可在右侧显示服务器图标。

安装

npm install koishi-plugin-discord-ai-guard

然后在 Koishi 控制台启用 discord-ai-guard。

如果你的 Koishi 跑在官方 Docker 镜像里，进入容器后建议用 yarn 安装或升级：

docker exec -it koishi sh
cd /koishi
yarn add [email protected]
exit
docker restart koishi

Web 管理页面依赖 Koishi 的 console 服务。未启用 console 时，插件的命令和审核功能仍可正常使用。

Discord 权限

机器人需要按启用的动作授予对应权限：

• 撤回消息：Manage Messages
• 踢出成员：Kick Members
• 禁用/封禁成员：Ban Members
• 编辑 Minecraft 状态消息：机器人需要能在目标频道发送消息，并且 Discord 适配器需要支持编辑自己发送的消息。

如果机器人角色低于目标成员角色，Discord 会拒绝踢出或封禁。

基础配置

channelIds 填需要审核的 Discord 频道 ID。留空表示审核所有 Discord 频道。

deleteMessage、kickMember、banMember 分别控制撤回、踢出、禁用/封禁。banMember 开启时不会重复执行踢出。

建议第一次使用时先打开 dryRun，确认 AI 判断稳定后再启用实际动作。

Web 管理页面

启用 Koishi console 后，侧边栏会出现 Discord AI Guard 页面。页面提供：

• 查看当前有效 AI 接口和插件版本。
• 添加只由 Web 页面管理的备用 AI 接口，配置会保存到 webConfigFile，默认是 data/discord-ai-guard/settings.json。
• 获取模型列表和测试 AI 接口。
• 添加 Minecraft 服务器配置，启动/停止状态监控，执行单次检测。

Web 页面保存的是插件自己的运行时配置文件，不会直接改 Koishi 的插件配置文件。运行时会把 Schema 中的 providers、minecraftServers 与 Web 页面保存的配置合并使用。

AI/中转站配置

插件调用的是 OpenAI Chat Completions 兼容接口：

POST {baseURL}{apiPath}

默认配置：

baseURL = https://api.openai.com/v1
apiFormat = auto
apiPath = /chat/completions
model = auto

如果你使用中转站，把 baseURL 改成中转站提供的地址即可，例如：

baseURL = https://你的中转站域名/v1
apiKey = 你的中转站 key
model = 中转站支持的模型名

如果中转站要求额外请求头，可以在 extraHeaders 中填写 JSON 对象：

{"x-api-key":"your-key"}

部分中转站不支持 OpenAI JSON mode，所以 jsonMode 默认关闭。接口支持时可以开启。

备用 AI 接口

providers 用来配置备用接口。主接口失败后，插件会按 providers 的顺序尝试下一个接口。每个备用接口都有自己的 baseURL、apiKey、model、apiFormat、apiPath 和 extraHeaders。

建议配置方式：

主接口：填写 baseURL/apiKey/model
备用接口：在 providers 表格里新增一行，填写另一个中转站或另一个 key

备用接口的 model 也可以填 auto，插件会对该接口单独请求 /models 并缓存自动选择结果。

智能识别

apiFormat 默认是 auto。插件会按顺序探测常见 OpenAI 兼容接口：

• {baseURL}/chat/completions
• {baseURL}/v1/chat/completions
• {baseURL}/responses
• {baseURL}/v1/responses

model 填 auto 或留空时，插件会先请求：

{baseURL}/v1/models
{baseURL}/models

如果 baseURL 已经以 /v1、/v4 这类版本段结尾，会优先请求 {baseURL}/models。如果地址以 /anthropic、/claudecode、/api/coding 等兼容子路径结尾，还会剥离这些子路径后再尝试 /v1/models 和 /models。

然后从返回的模型列表里自动选择一个可用于聊天的模型。中转站不支持模型列表接口时，请手动填写模型名。

需要查看某个接口支持哪些模型时，在 Koishi 中执行：

discord-ai-guard.models

也可以只查某个接口名称或地址：

discord-ai-guard.models 备用接口 1

命令会按上面的候选地址顺序请求模型列表，返回模型列表和建议模型。Koishi 配置 Schema 没有稳定的通用按钮接口，所以这里用管理命令实现“获取模型列表”功能。

如果你已经知道接口格式，也可以手动固定：

apiFormat = chat
apiPath = /chat/completions

或：

apiFormat = responses
apiPath = /responses

图片审核

imageMode 有三种：

• off：不发送图片信息。
• link：发送图片链接，兼容性最好。
• vision：按 OpenAI 兼容视觉输入发送图片，需要模型和中转站都支持图片输入。

测试命令

在 Koishi 中执行：

discord-ai-guard.test

也可以指定测试文本：

discord-ai-guard.test 免费领取 Discord Nitro，点击链接验证账号。

如果接口可用，会返回实际使用的供应商、模型、接口格式、端点、判断结果、分类、置信度和原因。

Minecraft 服务器检测

先在 minecraftServers 表格或 Web 管理页面里添加服务器：

name = survival
host = play.example.com
port = 25565
edition = java
interval = 60
channelId = 目标 Discord 频道 ID

常用命令：

discord-ai-guard.mc.list
discord-ai-guard.mc.once survival
discord-ai-guard.mc.start survival
discord-ai-guard.mc.stop survival

start 会先发送一条“检测中”的状态消息，然后按间隔编辑同一条消息。channelId 优先级为：服务器单独配置的 channelId、全局 minecraftChannelId、执行命令的频道。

基岩版服务器把 edition 设为 bedrock，默认端口通常是 19132。

如果希望状态消息显示成 Discord 卡片，把 minecraftMessageMode 设为 embed。插件会优先调用 Discord 原生 embeds 发送和编辑消息；如果当前平台不是 Discord 或适配器不支持原生接口，会自动回退为普通文本。

Embed相关配置：

• minecraftEmbedTitleTemplate：Embed标题模板，留空使用默认标题。
• minecraftEmbedFooterTemplate：Embed底部文本模板，留空不显示。
• minecraftEmbedThumbnailTemplate：Embed右侧缩略图URL模板。留空时自动使用Java服务器favicon，也可以填写固定图片链接。
• minecraftEmbedShowIcon：是否在Embed右侧显示服务器图标，默认开启。Java服务器返回 favicon 时显示；Bedrock服务器通常不会返回图标。
• minecraftEmbedPendingColor：检测中颜色，默认 #FEE75C。
• minecraftEmbedOnlineColor：在线颜色，默认 #57F287。
• minecraftEmbedOfflineColor：离线颜色，默认 #ED4245。

如果想做成类似 Discord 原始 JSON 的格式，不是直接粘整段 JSON，而是这样填：

minecraftMessageMode = embed
minecraftEmbedTitleTemplate = {name}服务器状态
minecraftEmbedFooterTemplate = Minecraft服务器状态监测
minecraftEmbedThumbnailTemplate = https://你的图片链接.png
minecraftEmbedOnlineColor = 5814783

然后把正文模板填成：

**状态：** {status}
**地址：** `{host}:{port}`
**版本：** `{edition}`
**在线：** `{online}/{max}`
**延迟：** `{latency}ms`

**MOTD：** {motd}
**检测时间：** `{time}`
**错误：** {error}

状态消息模板

可以在 Koishi 配置或 Web 管理页面里自定义三种模板：

• minecraftPendingTemplate：检测中
• minecraftOnlineTemplate：在线
• minecraftOfflineTemplate：离线

支持占位符：

{name} {host} {port} {address} {edition} {status}
{players} {online} {max} {latency} {motd} {favicon} {error} {time}

其中 {status} 的实际值为英文：checking、online、offline。

在线模板示例：

## Minecraft服务器状态
**{name}**
状态：**在线**
地址：`{address}`
玩家：`{players}`
延迟：`{latency}ms`
MOTD：`{motd}`

不要使用 > 引用符，部分 Discord 适配会把它显示成 >。

判断逻辑

AI 必须返回 JSON：

{"violation":true,"categories":["scam"],"confidence":0.91,"reason":"钓鱼领取链接"}

只有同时满足以下条件才会执行动作：

• violation 为 true
• confidence 不低于 confidenceThreshold
• 返回分类在 enabledCategories 中

备注

审核结果依赖模型和提示词。涉及自动封禁时，建议提高 confidenceThreshold，并先运行一段时间的 dryRun。