koishi-plugin-qqmonitor-guard

Koishi 插件：对接 QQMonitor API，校验群成员是否存在有效绑定并按策略处理（可踢出、可演练）。

功能

• 入群自动校验（可开关）
• 定时巡检指定群成员（可开关）
• 校验失败自动踢群（可开关）
• 白名单豁免
• 踢人日志通知到指定群
• qqm.check <qq> 手动校验命令

安装

在该工作区执行：

npm install
npm run build

把编译产物作为本地插件接入 Koishi（或直接在 Koishi 项目里以源码方式引用）。

Koishi 控制台配置分组

插件配置页分为 3 组：

1. QQMonitor API 配置
   • apiUrl
   • token
   • secret（密码样式显示）
2. 请求与重试
   • timeoutMs
   • retries
   • retryDelayMs
3. 校验与处置策略
   • kickOnFail
   • dryRun
   • rejectAddRequest
   • enableJoinCheck
   • enableScheduledCheck
   • scheduleIntervalMinutes
   • monitoredGroups
   • whitelistQQ
   • notifyGroupId

Koishi 配置示例

import {} from "koishi-plugin-qqmonitor-guard";

export default {
  plugins: {
    "qqmonitor-guard": {
      apiUrl: "https://your-aa-site/qqmonitor/api/v1/verify-qq/",
      token: "your-public-token",
      secret: "your-very-strong-secret",
      timeoutMs: 8000,
      retries: 1,
      retryDelayMs: 800,
      kickOnFail: true,
      dryRun: false,
      rejectAddRequest: false,
      enableJoinCheck: true,
      enableScheduledCheck: false,
      scheduleIntervalMinutes: 60,
      monitoredGroups: ["123456789"],
      whitelistQQ: ["10000"],
      notifyGroupId: "123456789",
    },
  },
};

QQMonitor API 对接约定

插件按以下头部发起请求：

• X-QQM-TOKEN
• X-QQM-TIMESTAMP
• X-QQM-SIGNATURE = hmac_sha256(secret, "${token}.${timestamp}.${qq_number}")

请求体：

{
  "qq_number": "123456789"
}

行为说明

• 当返回 ok=false 或 exists=false 或 in_alliance=false 时，判定为失败。
• 失败后如 kickOnFail=true，则执行踢人；如 dryRun=true，只记录日志不踢人。
• 踢人能力依赖适配器暴露的 OneBot setGroupKick / set_group_kick 接口。

兼容性说明

• 已实现逻辑优先兼容 OneBot 风格 QQ 适配器。
• 若你使用的是其他适配器，请按 src/index.ts 中 kickMember 与 listGroupMembers 适配对应 API。