koishi-plugin-yyds-verifier

入群验证插件，支持多种验证方式，有效防止机器人和恶意用户入群。

功能特性

• 多种验证方式

  • 数字验证码：用户需要输入显示的数字
  • 算数验证：用户需要计算简单的加法或乘法（如 3+5=? 或 4×7=?）
  • 图像验证码：用户需要识别图片中的字符
  • 随机模式：随机选择以上三种方式之一

• 白名单功能：指定用户入群时无需验证

• 可配置参数

  • 验证超时时间
  • 最大尝试次数
  • 验证码长度
  • 自定义消息模板

• 安全特性

  • 验证失败自动踢出
  • 可选永久踢出（加入群黑名单）

安装

前置依赖

本插件需要 koishi-plugin-skia-canvas 作为依赖，请先安装：

npm install koishi-plugin-skia-canvas

安装插件

npm install koishi-plugin-yyds-verifier

配置项

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | mode | string | 'code' | 验证方式：code=数字验证码, math=算数验证, image=图像验证码, random=随机 | | timeout | number | 300 | 验证超时时间（秒） | | maxAttempts | number | 3 | 最大尝试次数 | | permanent | boolean | false | 是否永久踢出（加入群黑名单） | | codeLength | number | 4 | 验证码长度（仅对 code 和 image 模式有效） | | whitelist | string[] | [] | 白名单用户 ID 列表 | | messages | object | - | 自定义消息模板 |

消息模板

| 配置项 | 默认值 | 可用变量 | |--------|--------|----------| | messages.prompt | '欢迎加入！请在 {timeout} 内完成验证。{question} 当前第 {attempt}/{maxAttempts} 次机会。' | {timeout} {question} {attempt} {maxAttempts} | | messages.success | '验证成功！欢迎加入本群。' | - | | messages.failure | '验证失败，请重新输入。剩余 {remaining} 次机会。' | {remaining} | | messages.timeout | '验证超时，进入下一轮验证。剩余 {remaining} 次机会。' | {remaining} | | messages.kicked | '验证失败次数过多，已被移出群聊。' | - |

使用示例

基础配置

plugins:
  yyds-verifier:
    mode: code
    timeout: 300
    maxAttempts: 3

使用算数验证

plugins:
  yyds-verifier:
    mode: math
    timeout: 120
    maxAttempts: 3

使用图像验证码

plugins:
  yyds-verifier:
    mode: image
    timeout: 180
    codeLength: 4

配置白名单

plugins:
  yyds-verifier:
    mode: random
    whitelist:
      - '123456789'
      - '987654321'

验证流程

用户入群
    ↓
检查白名单 → 在白名单中 → 跳过验证
    ↓ 不在白名单
生成验证挑战
    ↓
发送验证提示
    ↓
等待用户输入 → 超时 → 还有机会? → 是 → 下一轮
    ↓                              ↓ 否
验证答案                          踢出用户
    ↓
正确 → 验证成功
    ↓ 错误
还有机会? → 是 → 提示错误，继续等待
    ↓ 否
踢出用户

注意事项

1. 机器人需要有踢人权限才能正常工作
2. 建议将验证超时时间设置在 60-300 秒之间
3. 图像验证码模式需要 koishi-plugin-skia-canvas 支持
4. 白名单中的用户 ID 需要是字符串格式

许可证

MIT