koishi-plugin-group-verification 1.0.30 → 1.0.32

package/lib/index.d.ts

@@ -5,6 +5,7 @@ declare module 'koishi' {
         group_verification_config: GroupVerificationConfig;
         group_verification_stats: GroupVerificationStats;
         group_verification_pending: PendingVerification;
+        group_verification_blacklist: GroupBlacklistEntry;
     }
 }
 export interface GroupVerificationConfig {
@@ -29,6 +30,11 @@ export interface GroupVerificationStats {
     totalJoined: number;
     lastUpdated: string | Date;
 }
+export interface GroupBlacklistEntry {
+    id: number;
+    groupId: string;
+    entries: Record<string, string>;
+}
 export interface PendingVerification {
     id: number;
     groupId: string;
@@ -46,6 +52,10 @@ export interface Config {
     invalidGroupMessage?: string;
     parameterConflictMessage?: string;
     noKeywordsMessage?: string;
+    blacklistAddSuccess?: string;
+    blacklistRemoveSuccess?: string;
+    blacklistListEmpty?: string;
+    blacklistInfoTemplate?: string;
 }
 export declare const Config: Schema<Config>;
 export declare const inject: string[];
@@ -114,4 +124,6 @@ export declare function verifyApplication(config: GroupVerificationConfig, messa
     requiredThreshold: string;
 }>;
 export declare function handleFailedVerification(ctx: Context, session: any, config: GroupVerificationConfig, matchedCount?: number, requiredThreshold?: string): Promise<void>;
+export declare function isUserBlacklisted(ctx: Context, groupId: string, userId: string): Promise<boolean>;
+export declare function processBlacklistCommand(ctx: Context, session: any, rawArgs: string, config?: Config): Promise<string>;
 export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -28,9 +28,11 @@ __export(src_exports, {
   handleGuildMemberRequestEvent: () => handleGuildMemberRequestEvent,
   incrementTotal: () => incrementTotal,
   inject: () => inject,
+  isUserBlacklisted: () => isUserBlacklisted,
   mergeReminder: () => mergeReminder,
   name: () => name,
   parseConfigArgs: () => parseConfigArgs,
+  processBlacklistCommand: () => processBlacklistCommand,
   resolveThreshold: () => resolveThreshold,
   syncTotalStats: () => syncTotalStats,
   tokenize: () => tokenize,
@@ -49,7 +51,11 @@ var Config = import_koishi.Schema.object({
   permissionDeniedMessage: import_koishi.Schema.string().description("权限不足时返回给调用者的提示").default("权限不足：需要群主/管理员权限或koishi三级以上权限"),
   invalidGroupMessage: import_koishi.Schema.string().description("无效群号或机器人未在该群时的提示").default("群号 {group} 格式不合法或机器人不在该群中"),
   parameterConflictMessage: import_koishi.Schema.string().description("参数冲突时提示").default("参数冲突：-? 或 -r 不能与其他参数或关键词一起使用（仅可搭配 -i）"),
-  noKeywordsMessage: import_koishi.Schema.string().description("未提供关键词且无法从现有配置继承时的提示").default("请先提供关键词创建配置，或使用 -? 查询配置，-r 删除配置")
+  noKeywordsMessage: import_koishi.Schema.string().description("未提供关键词且无法从现有配置继承时的提示").default("请先提供关键词创建配置，或使用 -? 查询配置，-r 删除配置"),
+  blacklistAddSuccess: import_koishi.Schema.string().description("将用户加入黑名单后的提示，可使用 {user},{group},{reason}").default("已将用户 {user} 加入群 {group} 黑名单{reason}"),
+  blacklistRemoveSuccess: import_koishi.Schema.string().description("从黑名单移除用户后的提示，可使用 {user},{group}").default("已从群 {group} 的黑名单中移除用户 {user}"),
+  blacklistListEmpty: import_koishi.Schema.string().description("黑名单为空时提示").default("群 {group} 的黑名单为空"),
+  blacklistInfoTemplate: import_koishi.Schema.string().description("查询指定用户状态时的模板，可用 {global},{group}").default("全局黑名单: {global}\n本群黑名单: {group}")
 }).description("群组验证插件配置");
 var inject = ["database"];
 var ESC_QUOTE = "\0";
@@ -342,7 +348,7 @@ async function checkPermission(session, targetGroupId) {
     });
   }
   if (koishiAuthority && koishiAuthority >= 3) {
-    logger.info(`权限检查 - 通过koishi权限检查: ${koishiAuthority}`);
+    logger.debug(`权限检查 - 通过koishi权限检查: ${koishiAuthority}`);
     return [true];
   }
   try {
@@ -392,6 +398,23 @@ async function handleGuildMemberRequestEvent(ctx, session) {
     await updateStats(ctx, guildId, "rejected");
     return;
   }
+  try {
+    const blacklisted = await isUserBlacklisted(ctx, guildId, userId);
+    if (blacklisted) {
+      logger.info(`用户 ${userId} 在群 ${guildId} 或全局黑名单中，自动拒绝申请`);
+      if (requestId) {
+        try {
+          await session.bot.handleGuildMemberRequest(requestId, false);
+        } catch (e) {
+          logger.warn("自动拒绝失败", e);
+        }
+      }
+      await updateStats(ctx, guildId, "rejected");
+      return;
+    }
+  } catch (e) {
+    logger.warn("黑名单检查失败", e);
+  }
   const { isValid, matchedCount, requiredThreshold } = await verifyApplication(config, message, session);
   logger.debug(`验证结果 guild=${guildId} user=${userId} msg="${message}" matched=${matchedCount} threshold=${requiredThreshold} valid=${isValid}`);
   if (isValid) {
@@ -603,6 +626,218 @@ async function handleFailedVerification(ctx, session, config, matchedCount, requ
   }
 }
 __name(handleFailedVerification, "handleFailedVerification");
+async function isUserBlacklisted(ctx, groupId, userId) {
+  const globalRows = await ctx.database.get("group_verification_blacklist", { groupId: "all" });
+  if (globalRows.length > 0) {
+    const entries = globalRows[0].entries || {};
+    if (entries[userId] !== void 0) return true;
+  }
+  const groupRows = await ctx.database.get("group_verification_blacklist", { groupId });
+  if (groupRows.length > 0) {
+    const entries = groupRows[0].entries || {};
+    if (entries[userId] !== void 0) return true;
+  }
+  return false;
+}
+__name(isUserBlacklisted, "isUserBlacklisted");
+async function processBlacklistCommand(ctx, session, rawArgs, config) {
+  const parts = rawArgs.trim().split(/\s+/).filter(Boolean);
+  const op = parts[0]?.toLowerCase();
+  if (!op || !["a", "r", "l", "i"].includes(op)) {
+    return [
+      "用法：",
+      "  gvb a id [reason] [group]   将用户加入黑名单",
+      "  gvb r id [group]            将用户移出黑名单",
+      "  gvb l [group]               查询群黑名单",
+      "  gvb i id [group]            查询账号黑名单",
+      "  [group]传入all表全局"
+    ].join("\n");
+  }
+  const getCurrentGroup = /* @__PURE__ */ __name(() => session.guildId || "", "getCurrentGroup");
+  let group;
+  let targetUser;
+  let reason = "";
+  if (op === "a") {
+    targetUser = parts[1];
+    if (!targetUser) return "请提供用户ID";
+    const rest = parts.slice(2);
+    if (rest.length === 1) {
+      reason = rest[0];
+    } else if (rest.length > 1) {
+      const last = rest[rest.length - 1];
+      if (/^\d+$/.test(last) || last.toLowerCase() === "all") {
+        group = last;
+        reason = rest.slice(0, -1).join(" ");
+      } else {
+        reason = rest.join(" ");
+      }
+    }
+    group = group || getCurrentGroup();
+    if (!group) return "请在群聊中使用此命令或指定群号";
+    if (group.toLowerCase() === "all") {
+      const auth = session.author?.authority || session.user?.authority;
+      if (!(auth && auth >= 3)) return "设置全局黑名单需要 koishi 3 级以上权限";
+    } else {
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || "群号 {group} 格式不合法或机器人不在该群中").replace("{group}", group);
+        }
+      }
+      const [ok, err] = await checkPermission(session, group);
+      if (!ok) return err || "权限不足";
+    }
+    const rows = await ctx.database.get("group_verification_blacklist", { groupId: group });
+    const timePrefix = (/* @__PURE__ */ new Date()).toLocaleString();
+    const storedReason = reason ? `${timePrefix} ${reason}` : timePrefix;
+    if (rows.length > 0) {
+      const row = rows[0];
+      const entries = row.entries || {};
+      if (entries[targetUser] !== void 0) {
+        return `用户 ${targetUser} 已在群 ${group} 的黑名单中：${entries[targetUser]}`;
+      }
+      entries[targetUser] = storedReason;
+      await ctx.database.set("group_verification_blacklist", { id: row.id }, { entries });
+    } else {
+      const entries = {};
+      entries[targetUser] = storedReason;
+      await ctx.database.create("group_verification_blacklist", { groupId: group, entries });
+    }
+    if (session.bot && typeof session.bot.kickGuildMember === "function") {
+      try {
+        await session.bot.kickGuildMember(group, targetUser);
+        logger.info(`已将黑名单用户 ${targetUser} 从群 ${group} 踢出`);
+      } catch (e) {
+        logger.warn(`踢出用户 ${targetUser} 失败`, e);
+      }
+    }
+    const tmpl = config && config.blacklistAddSuccess || "已将用户 {user} 加入群 {group} 黑名单{reason}";
+    return tmpl.replace("{user}", targetUser).replace("{group}", group).replace("{reason}", reason ? `，原因：${reason}` : "");
+  }
+  if (op === "r") {
+    targetUser = parts[1];
+    if (!targetUser) return "请提供用户ID";
+    group = parts[2] || getCurrentGroup();
+    if (!group) return "请在群聊中使用此命令或指定群号";
+    if (group.toLowerCase() === "all") {
+      const auth = session.author?.authority || session.user?.authority;
+      if (!(auth && auth >= 3)) return "修改全局黑名单需要 koishi 3 级以上权限";
+    } else {
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || "群号 {group} 格式不合法或机器人不在该群中").replace("{group}", group);
+        }
+      }
+      const [ok, err] = await checkPermission(session, group);
+      if (!ok) return err || "权限不足";
+    }
+    const rows = await ctx.database.get("group_verification_blacklist", { groupId: group });
+    if (rows.length > 0) {
+      const row = rows[0];
+      const entries = row.entries || {};
+      delete entries[targetUser];
+      await ctx.database.set("group_verification_blacklist", { id: row.id }, { entries });
+    }
+    const tmpl = config && config.blacklistRemoveSuccess || "已从群 {group} 的黑名单中移除用户 {user}";
+    return tmpl.replace("{user}", targetUser).replace("{group}", group);
+  }
+  if (op === "l") {
+    group = parts[1] || getCurrentGroup();
+    if (!group) return "请在群聊中使用此命令或指定群号";
+    if (group.toLowerCase() === "all") {
+      const auth = session.author?.authority || session.user?.authority;
+      if (!(auth && auth >= 3)) return "查看全局黑名单需要 koishi 3 级以上权限";
+    } else {
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || "群号 {group} 格式不合法或机器人不在该群中").replace("{group}", group);
+        }
+      }
+      const [ok, err] = await checkPermission(session, group);
+      if (!ok) return err || "权限不足";
+    }
+    const rows = await ctx.database.get("group_verification_blacklist", { groupId: group });
+    if (rows.length === 0) {
+      if (group && group.toLowerCase() === "all") {
+        return "全局黑名单为空";
+      }
+      const tmpl = config && config.blacklistListEmpty || "群 {group} 的黑名单为空";
+      return tmpl.replace("{group}", group);
+    }
+    const entries = rows[0].entries || {};
+    let prefix = group && group.toLowerCase() === "all" ? "全局黑名单: \n" : `群 ${group} 黑名单: 
+`;
+    let msg = prefix;
+    for (const uid in entries) {
+      msg += `${uid}${entries[uid] ? `：${entries[uid]}` : ""}
+`;
+    }
+    return msg;
+  }
+  if (op === "i") {
+    targetUser = parts[1];
+    if (!targetUser) return "请提供用户ID";
+    const groupArg = parts[2];
+    const globalRows = await ctx.database.get("group_verification_blacklist", { groupId: "all" });
+    const globalHit = globalRows.length > 0 && (globalRows[0].entries || {})[targetUser] !== void 0;
+    const tmpl = config && config.blacklistInfoTemplate || "全局黑名单: {global}\n本群黑名单: {group}";
+    const formatReply = /* @__PURE__ */ __name((localHit, groupsList) => {
+      if (groupsList) {
+        return tmpl.replace("{global}", globalHit ? "有" : "无").replace(
+          "{group}",
+          groupsList.length ? groupsList.join(",") : "无"
+        );
+      }
+      return tmpl.replace("{global}", globalHit ? "有" : "无").replace("{group}", localHit ? "有" : "无");
+    }, "formatReply");
+    if (!groupArg) {
+      const groupId2 = getCurrentGroup();
+      if (!groupId2) return "请在群聊中使用此命令";
+      const [ok2, err2] = await checkPermission(session, groupId2);
+      if (!ok2) return err2 || "权限不足";
+      const rows2 = await ctx.database.get("group_verification_blacklist", { groupId: groupId2 });
+      const localReason2 = rows2.length > 0 ? (rows2[0].entries || {})[targetUser] : void 0;
+      const globalReason2 = globalHit ? globalRows[0].entries[targetUser] : void 0;
+      return `全局黑名单: ${globalReason2 || "无"}
+群${groupId2}黑名单: ${localReason2 || "无"}`;
+    }
+    if (groupArg.toLowerCase() === "all") {
+      const auth = session.author?.authority || session.user?.authority;
+      if (!(auth && auth >= 3)) return "权限不足：查看全局/所有群黑名单需要 koishi 3 级以上权限";
+      const rows2 = await ctx.database.get("group_verification_blacklist", {});
+      const globalReason2 = globalHit ? globalRows[0].entries[targetUser] : "无";
+      const lines = [];
+      for (const r of rows2) {
+        if (r.groupId === "all") continue;
+        const reason2 = (r.entries || {})[targetUser];
+        if (reason2 !== void 0) {
+          lines.push(`群${r.groupId}:${reason2}`);
+        }
+      }
+      let reply = `全局黑名单: ${globalReason2}`;
+      if (lines.length) {
+        reply += "\n群黑名单: \n" + lines.join("\n");
+      } else {
+        reply += "\n群黑名单: 无";
+      }
+      return reply;
+    }
+    const groupId = groupArg;
+    if (config?.enableStrictGroupCheck && groupId.toLowerCase() !== "all") {
+      if (!/^\d{5,15}$/.test(groupId)) {
+        return (config.invalidGroupMessage || "群号 {group} 格式不合法或机器人不在该群中").replace("{group}", groupId);
+      }
+    }
+    const [ok, err] = await checkPermission(session, groupId);
+    if (!ok) return err || "权限不足";
+    const rows = await ctx.database.get("group_verification_blacklist", { groupId });
+    const localReason = rows.length > 0 ? (rows[0].entries || {})[targetUser] : void 0;
+    const globalReason = globalHit ? globalRows[0].entries[targetUser] : void 0;
+    return `全局黑名单: ${globalReason || "无"}
+群${groupId}黑名单: ${localReason || "无"}`;
+  }
+  return "";
+}
+__name(processBlacklistCommand, "processBlacklistCommand");
 function apply(ctx, config) {
   ctx.model.extend("group_verification_config", {
     id: "unsigned",
@@ -655,13 +890,25 @@ function apply(ctx, config) {
     primary: "id",
     autoInc: true
   });
+  ctx.model.extend("group_verification_blacklist", {
+    id: "unsigned",
+    groupId: "string",
+    entries: "json"
+  }, {
+    primary: "id",
+    autoInc: true,
+    indexes: [["groupId"]]
+  });
   ctx.on("guild-member-request", async (session) => {
     logger.info("收到 guild-member-request 事件，转发给处理函数");
     await handleGuildMemberRequestEvent(ctx, session);
   });
   ctx.on("guild-member-added", async (session) => {
-    const groupId = session.guildId;
-    const userId = session.userId;
+    const groupId = session.guildId || "";
+    const userId = session.userId || "";
+    if (!groupId || !userId) {
+      return;
+    }
     await incrementTotal(ctx, groupId);
     const set = autoQueue.get(groupId);
     if (set && set.has(userId)) {
@@ -1083,10 +1330,11 @@ ${reminderMessage}
           return `用户 ${request2.userId} 的申请缺少 requestId，无法自动同意`;
         }
         try {
-          await session.bot.handleGuildMemberRequest(request2.requestId, true);
-          await ctx.database.remove("group_verification_pending", { groupId, userId: request2.userId });
           const displayName = request2.userName && request2.userName !== request2.userId ? `${request2.userName}(${request2.userId})` : request2.userId;
-          return `已同意用户 ${displayName} 的加群申请`;
+          const reply = `已同意用户 ${displayName} 的加群申请`;
+          session.bot.handleGuildMemberRequest(request2.requestId, true).catch((e) => logger.warn("自动同意失败", e));
+          await ctx.database.remove("group_verification_pending", { groupId, userId: request2.userId });
+          return reply;
         } catch (error) {
           return `处理申请时出错: ${error.message}`;
         }
@@ -1104,10 +1352,11 @@ ${reminderMessage}
       return `用户 ${userId} 的申请缺少 requestId，无法自动同意`;
     }
     try {
-      await session.bot.handleGuildMemberRequest(request.requestId, true);
-      await ctx.database.remove("group_verification_pending", { groupId, userId });
       const displayName = request.userName && request.userName !== request.userId ? `${request.userName}(${request.userId})` : request.userId;
-      return `已同意用户 ${displayName} 的加群申请`;
+      const reply = `已同意用户 ${displayName} 的加群申请`;
+      session.bot.handleGuildMemberRequest(request.requestId, true).catch((e) => logger.warn("自动同意失败", e));
+      await ctx.database.remove("group_verification_pending", { groupId, userId });
+      return reply;
     } catch (error) {
       return `处理申请时出错: ${error.message}`;
     }
@@ -1257,6 +1506,17 @@ ${reminderMessage}
     });
     return result;
   });
+  groupVerify.subcommand(".blacklist [args:text]", "管理加群黑名单").alias(
+    "gvb",
+    "gv.blacklist",
+    "gverify.blacklist",
+    "group-verify.blacklist",
+    "gv.黑名单",
+    "gverify.黑名单",
+    "group-verify.黑名单"
+  ).action(async ({ session }, args) => {
+    return await processBlacklistCommand(ctx, session, args || "", config);
+  });
   groupVerify.subcommand(".help", "显示帮助信息").alias("gv.帮助", "gverify.帮助", "group-verify.帮助", "帮助", "hlp", "帮助信息").action(() => {
     return `群组验证命令帮助：
 主指令别名：gv, gverify
@@ -1309,6 +1569,19 @@ ${reminderMessage}
     gv.cfg -m 2 -t 80
     gv.cfg -nomsg
 
+黑名单命令 (.blacklist / gvb):
+  a id [reason] [group]   添加黑名单，可指定原因和群号；group为all表示全局
+  r id [group]            删除条目；group 为 all 时移除全局黑名单
+  l [group]               查询群黑名单；传入 all 时查看全局黑名单
+  i id [group]            查询账号黑名单；不带参数时查询本群与全局，
+                          指定群号查询该群与全局，传入 all 则列出所有群及全局（需Koishi 3级）
+使用示例：
+    gvb a 12345 作弊记录
+    gvb r 12345 67890
+    gvb l
+    gvb l all
+    gvb i 12345
+
 快捷命令：
   gvc - 配置命令快捷方式
   gva - 同意申请快捷命令
@@ -1409,9 +1682,11 @@ __name(apply, "apply");
   handleGuildMemberRequestEvent,
   incrementTotal,
   inject,
+  isUserBlacklisted,
   mergeReminder,
   name,
   parseConfigArgs,
+  processBlacklistCommand,
   resolveThreshold,
   syncTotalStats,
   tokenize,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koishi-plugin-group-verification",
-  "description": "Koishi 群组加群验证插件，支持多关键词匹配审核、多种审核方式和详细统计功能。",
+  "description": "Koishi 群组加群验证插件，支持多关键词匹配审核、多种审核方式和详细统计功能",
   "repository": {
     "type": "git",
     "url": "https://github.com/LHDyx/koishi-plugin-group-verification.git"
@@ -8,7 +8,7 @@
   "bugs": {
     "url": "https://github.com/LHDyx/koishi-plugin-group-verification/issues"
   },
-  "version": "1.0.30",
+  "version": "1.0.32",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -62,6 +62,7 @@ group-verify.config -i 123456789 关键词1,关键词2 -m 1 -t 1
 
 > **命令增强**
 > - 未提供参数时 `gva`/`gvr` 会处理最近一条申请，`all` 可以批量处理。
+> - 手动使用 `gva` 时会先在群内返回“已同意用户…的加群申请”等提示，随后再将用户加入群，避免用户看到提示时已在群中的尴尬情形。
 > - 如果申请记录缺少 requestId，则无法通过机器人接口处理，会提示管理员请在客户端手动操作。
 > - 输出结果会智能展示用户名和ID，避免出现 "12345(12345)" 这样的重复显示。
 
@@ -101,6 +102,36 @@ group-verify.stats 123456789
 group-verify.stats total
 ```
 
+### 黑名单命令
+```
+# 添加黑名单条目（可指定原因和群号）
+group-verify.blacklist a <用户ID> [原因] [群号]
+# 别名：gvb, gv.blacklist, gverify.blacklist, group-verify.blacklist
+#      gv.黑名单, gverify.黑名单, group-verify.黑名单
+
+# 删除黑名单条目
+group-verify.blacklist r <用户ID> [群号]
+
+# 查看群黑名单
+group-verify.blacklist l [群号]
+# 传入 all 可查看全局黑名单
+
+# 查询用户在黑名单的状态
+group-verify.blacklist i <用户ID> [群号|all]
+
+* 不指定群号时会查询当前群和全局黑名单状态（必须在群聊中使用）。
+* 指定单个群号时会查询该群和全局状态，执行此操作需要该群的管理员权限或 Koishi 三级以上权限。
+* 输入 `all` 会列出用户在所有群的黑名单条目与全局黑名单（仅限 Koishi `authority>=3`）。
+```
+
+### 黑名单消息模板
+插件会在配置界面显示当前黑名单存在状态的提示词，用户可以通过修改以下字段自定义这些提示：
+
+- `blacklistLocalExists`：当前群已有黑名单条目时的提示，例如 “本群已设置黑名单”。
+- `blacklistGlobalExists`：全局黑名单存在时的提示，例如 “已启用全局黑名单”。
+
+如果将这两个字段留空，则对应的提示不会显示（界面将保持简洁）。
+
 ## ⚙️ 参数说明
 
 ### 审核方式 (-m)
@@ -186,6 +217,7 @@ group-verify.stats total
 - `group_verification_config` - 群组配置表
 - `group_verification_stats` - 统计信息表
 - `group_verification_pending` - 待审核申请表
+- `group_verification_blacklist` - 群组黑名单条目，每行记录一个用户（groupId=all 表示全局）
 
 ## 📝 使用示例
 

package/src/index.ts

@@ -11,6 +11,7 @@ declare module 'koishi' {
     group_verification_config: GroupVerificationConfig
     group_verification_stats: GroupVerificationStats
     group_verification_pending: PendingVerification
+    group_verification_blacklist: GroupBlacklistEntry
   }
 }
 
@@ -41,6 +42,14 @@ export interface GroupVerificationStats {
   lastUpdated: string | Date
 }
 
+// 黑名单行：每个群/全局对应一条记录，entries 保存 userId->reason 对象
+export interface GroupBlacklistEntry {
+  id: number
+  groupId: string   // 群号或 "all" 表示全局
+  entries: Record<string, string> // key=userId, value=reason
+}
+
+
 // 待审核申请表
 export interface PendingVerification {
   id: number
@@ -62,6 +71,11 @@ export interface Config {
   invalidGroupMessage?: string
   parameterConflictMessage?: string
   noKeywordsMessage?: string
+  // 黑名单提示消息
+  blacklistAddSuccess?: string
+  blacklistRemoveSuccess?: string
+  blacklistListEmpty?: string
+  blacklistInfoTemplate?: string
 }
 
 export const Config: Schema<Config> = Schema.object({
@@ -74,6 +88,10 @@ export const Config: Schema<Config> = Schema.object({
   invalidGroupMessage: Schema.string().description('无效群号或机器人未在该群时的提示').default('群号 {group} 格式不合法或机器人不在该群中'),
   parameterConflictMessage: Schema.string().description('参数冲突时提示').default('参数冲突：-? 或 -r 不能与其他参数或关键词一起使用（仅可搭配 -i）'),
   noKeywordsMessage: Schema.string().description('未提供关键词且无法从现有配置继承时的提示').default('请先提供关键词创建配置，或使用 -? 查询配置，-r 删除配置'),
+  blacklistAddSuccess: Schema.string().description('将用户加入黑名单后的提示，可使用 {user},{group},{reason}').default('已将用户 {user} 加入群 {group} 黑名单{reason}'),
+  blacklistRemoveSuccess: Schema.string().description('从黑名单移除用户后的提示，可使用 {user},{group}').default('已从群 {group} 的黑名单中移除用户 {user}'),
+  blacklistListEmpty: Schema.string().description('黑名单为空时提示').default('群 {group} 的黑名单为空'),
+  blacklistInfoTemplate: Schema.string().description('查询指定用户状态时的模板，可用 {global},{group}').default('全局黑名单: {global}\n本群黑名单: {group}')
 })
   .description('群组验证插件配置')
 
@@ -480,7 +498,7 @@ export async function checkPermission(session: any, targetGroupId?: string): Pro
   }
   
   if (koishiAuthority && koishiAuthority >= 3) {
-    logger.info(`权限检查 - 通过koishi权限检查: ${koishiAuthority}`)
+    logger.debug(`权限检查 - 通过koishi权限检查: ${koishiAuthority}`)
     return [true]
   }
   
@@ -533,6 +551,21 @@ export async function handleGuildMemberRequestEvent(ctx: Context, session: any)
     return;
   }
 
+  // 黑名单优先检查（仅在非全拒模式下）
+  try {
+    const blacklisted = await isUserBlacklisted(ctx, guildId, userId);
+    if (blacklisted) {
+      logger.info(`用户 ${userId} 在群 ${guildId} 或全局黑名单中，自动拒绝申请`);
+      if (requestId) {
+        try { await session.bot.handleGuildMemberRequest(requestId, false); } catch (e) { logger.warn('自动拒绝失败', e); }
+      }
+      await updateStats(ctx, guildId, 'rejected');
+      return;
+    }
+  } catch (e) {
+    logger.warn('黑名单检查失败', e);
+  }
+
   const { isValid, matchedCount, requiredThreshold } = await verifyApplication(config, message, session);
   logger.debug(`验证结果 guild=${guildId} user=${userId} msg="${message}" matched=${matchedCount} threshold=${requiredThreshold} valid=${isValid}`);
 
@@ -744,7 +777,7 @@ export async function handleFailedVerification(
   try {
     const guild = await session.bot.getGuild(guildId)
     groupName = guild.name || groupName
-  } catch (error) {
+  } catch (error: any) {
     // 无法获取群名称时使用默认值
   }
 
@@ -809,6 +842,241 @@ export async function handleFailedVerification(
   }
 }
 
+// 黑名单相关辅助函数 ----------------------------------------------------------
+
+// 检查指定用户是否在黑名单（群级或全局）中
+export async function isUserBlacklisted(ctx: Context, groupId: string, userId: string): Promise<boolean> {
+  // 全局黑名单
+  const globalRows = await ctx.database.get('group_verification_blacklist', { groupId: 'all' })
+  if (globalRows.length > 0) {
+    const entries = globalRows[0].entries || {}
+    if (entries[userId] !== undefined) return true
+  }
+  // 群级黑名单
+  const groupRows = await ctx.database.get('group_verification_blacklist', { groupId })
+  if (groupRows.length > 0) {
+    const entries = groupRows[0].entries || {}
+    if (entries[userId] !== undefined) return true
+  }
+  return false
+}
+
+// 解析并执行黑名单管理命令，返回要回复的字符串
+export async function processBlacklistCommand(ctx: Context, session: any, rawArgs: string, config?: Config): Promise<string> {
+  const parts = rawArgs.trim().split(/\s+/).filter(Boolean)
+  const op = parts[0]?.toLowerCase()
+  if (!op || !['a','r','l','i'].includes(op)) {
+    // present a multiline Chinese usage guide without angle brackets
+    return [
+      '用法：',
+      '  gvb a id [reason] [group]   将用户加入黑名单',
+      '  gvb r id [group]            将用户移出黑名单',
+      '  gvb l [group]               查询群黑名单',
+      '  gvb i id [group]            查询账号黑名单',
+      '  [group]传入all表全局'
+    ].join('\n')
+  }
+
+  const getCurrentGroup = () => session.guildId || ''
+  let group: string | undefined
+  let targetUser: string | undefined
+  let reason = ''
+
+  if (op === 'a') {
+    targetUser = parts[1]
+    if (!targetUser) return '请提供用户ID'
+    // handle optional reason and group at end
+    // 规则：如果只有一个附加参数，则作为 reason；两个及以上时最后一个为群号，其余拼成 reason
+    const rest = parts.slice(2)
+    if (rest.length === 1) {
+      reason = rest[0]
+    } else if (rest.length > 1) {
+      const last = rest[rest.length - 1]
+      if (/^\d+$/.test(last) || last.toLowerCase() === 'all') {
+        group = last
+        reason = rest.slice(0, -1).join(' ')
+      } else {
+        // 虽然数量>=2，但最后一个不是数字，全部作为reason
+        reason = rest.join(' ')
+      }
+    }
+    group = group || getCurrentGroup()
+    if (!group) return '请在群聊中使用此命令或指定群号'
+    // 权限检查
+    if (group.toLowerCase() === 'all') {
+      const auth = session.author?.authority || session.user?.authority
+      if (!(auth && auth >= 3)) return '设置全局黑名单需要 koishi 3 级以上权限'
+    } else {
+      // 严格群号检查（若开启）
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || '群号 {group} 格式不合法或机器人不在该群中').replace('{group}', group)
+        }
+      }
+      const [ok, err] = await checkPermission(session, group)
+      if (!ok) return err || '权限不足'
+    }
+    // add entry to map with timestamp, but refuse duplicates
+    const rows = await ctx.database.get('group_verification_blacklist', { groupId: group })
+    // build stored reason with current time prefix
+    const timePrefix = new Date().toLocaleString()
+    const storedReason = reason ? `${timePrefix} ${reason}` : timePrefix
+    if (rows.length > 0) {
+      const row = rows[0]
+      const entries = row.entries || {}
+      if (entries[targetUser] !== undefined) {
+        return `用户 ${targetUser} 已在群 ${group} 的黑名单中：${entries[targetUser]}`
+      }
+      entries[targetUser] = storedReason
+      await ctx.database.set('group_verification_blacklist', { id: row.id }, { entries })
+    } else {
+      const entries: Record<string,string> = {}
+      entries[targetUser] = storedReason
+      await ctx.database.create('group_verification_blacklist', { groupId: group, entries })
+    }
+    // 添加成功后尝试踢人
+    if (session.bot && typeof session.bot.kickGuildMember === 'function') {
+      try {
+        await session.bot.kickGuildMember(group, targetUser)
+        logger.info(`已将黑名单用户 ${targetUser} 从群 ${group} 踢出`)        
+      } catch (e) {
+        logger.warn(`踢出用户 ${targetUser} 失败`, e)
+      }
+    }
+    const tmpl = (config && config.blacklistAddSuccess) || '已将用户 {user} 加入群 {group} 黑名单{reason}'
+    return tmpl.replace('{user}', targetUser).replace('{group}', group).replace('{reason}', reason ? `，原因：${reason}` : '')
+  }
+  if (op === 'r') {
+    targetUser = parts[1]
+    if (!targetUser) return '请提供用户ID'
+    group = parts[2] || getCurrentGroup()
+    if (!group) return '请在群聊中使用此命令或指定群号'
+    if (group.toLowerCase() === 'all') {
+      const auth = session.author?.authority || session.user?.authority
+      if (!(auth && auth >= 3)) return '修改全局黑名单需要 koishi 3 级以上权限'
+    } else {
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || '群号 {group} 格式不合法或机器人不在该群中').replace('{group}', group)
+        }
+      }
+      const [ok, err] = await checkPermission(session, group)
+      if (!ok) return err || '权限不足'
+    }
+    const rows = await ctx.database.get('group_verification_blacklist', { groupId: group })
+    if (rows.length > 0) {
+      const row = rows[0]
+      const entries = row.entries || {}
+      delete entries[targetUser]
+      await ctx.database.set('group_verification_blacklist', { id: row.id }, { entries })
+    }
+    const tmpl = (config && config.blacklistRemoveSuccess) || '已从群 {group} 的黑名单中移除用户 {user}'
+    return tmpl.replace('{user}', targetUser).replace('{group}', group)
+  }
+  if (op === 'l') {
+    group = parts[1] || getCurrentGroup()
+    if (!group) return '请在群聊中使用此命令或指定群号'
+    if (group.toLowerCase() === 'all') {
+      const auth = session.author?.authority || session.user?.authority
+      if (!(auth && auth >= 3)) return '查看全局黑名单需要 koishi 3 级以上权限'
+    } else {
+      if (config?.enableStrictGroupCheck) {
+        if (!/^\d{5,15}$/.test(group)) {
+          return (config.invalidGroupMessage || '群号 {group} 格式不合法或机器人不在该群中').replace('{group}', group)
+        }
+      }
+      const [ok, err] = await checkPermission(session, group)
+      if (!ok) return err || '权限不足'
+    }
+    const rows = await ctx.database.get('group_verification_blacklist', { groupId: group })
+    if (rows.length === 0) {
+      // 特殊处理 all 表示全局黑名单
+      if (group && group.toLowerCase() === 'all') {
+        // 不使用模板，因为默认模板会产生 "群 all 的黑名单为空" 这种奇怪输出
+        return '全局黑名单为空'
+      }
+      const tmpl = (config && config.blacklistListEmpty) || '群 {group} 的黑名单为空'
+      return tmpl.replace('{group}', group)
+    }
+    const entries = rows[0].entries || {}
+    // 构造列表消息，all 也是专用前缀
+    let prefix = group && group.toLowerCase() === 'all' ? '全局黑名单: \n' : `群 ${group} 黑名单: \n`
+    let msg = prefix
+    for (const uid in entries) {
+      msg += `${uid}${entries[uid] ? `：${entries[uid]}` : ''}\n`
+    }
+    return msg
+  }
+  if (op === 'i') {
+    targetUser = parts[1]
+    if (!targetUser) return '请提供用户ID'
+    const groupArg = parts[2]
+    const globalRows = await ctx.database.get('group_verification_blacklist', { groupId: 'all' })
+    const globalHit = globalRows.length > 0 && (globalRows[0].entries || {})[targetUser] !== undefined
+
+    // helper to format reply using template
+    const tmpl = (config && config.blacklistInfoTemplate) || '全局黑名单: {global}\n本群黑名单: {group}'
+    const formatReply = (localHit: boolean, groupsList?: string[]) => {
+      if (groupsList) {
+        return tmpl.replace('{global}', globalHit ? '有' : '无').replace(
+          '{group}', groupsList.length ? groupsList.join(',') : '无'
+        )
+      }
+      return tmpl.replace('{global}', globalHit ? '有' : '无').replace('{group}', localHit ? '有' : '无')
+    }
+
+    // no group specified -> use current session guild
+    if (!groupArg) {
+      const groupId = getCurrentGroup()
+      if (!groupId) return '请在群聊中使用此命令'
+      const [ok, err] = await checkPermission(session, groupId)
+      if (!ok) return err || '权限不足'
+      const rows = await ctx.database.get('group_verification_blacklist', { groupId })
+      const localReason = rows.length > 0 ? (rows[0].entries || {})[targetUser] : undefined
+      const globalReason = globalHit ? globalRows[0].entries[targetUser] : undefined
+      return `全局黑名单: ${globalReason || '无'}\n群${groupId}黑名单: ${localReason || '无'}`
+    }
+
+    // groupArg provided
+    if (groupArg.toLowerCase() === 'all') {
+      const auth = session.author?.authority || session.user?.authority
+      if (!(auth && auth >= 3)) return '权限不足：查看全局/所有群黑名单需要 koishi 3 级以上权限'
+      const rows = await ctx.database.get('group_verification_blacklist', {})
+      const globalReason = globalHit ? globalRows[0].entries[targetUser] : '无'
+      const lines: string[] = []
+      for (const r of rows) {
+        if (r.groupId === 'all') continue
+        const reason = (r.entries || {})[targetUser]
+        if (reason !== undefined) {
+          lines.push(`群${r.groupId}:${reason}`)
+        }
+      }
+      let reply = `全局黑名单: ${globalReason}`
+      if (lines.length) {
+        reply += '\n群黑名单: \n' + lines.join('\n')
+      } else {
+        reply += '\n群黑名单: 无'
+      }
+      return reply
+    }
+
+    // specific group provided
+    const groupId = groupArg
+    if (config?.enableStrictGroupCheck && groupId.toLowerCase() !== 'all') {
+      if (!/^\d{5,15}$/.test(groupId)) {
+        return (config.invalidGroupMessage || '群号 {group} 格式不合法或机器人不在该群中').replace('{group}', groupId)
+      }
+    }
+    const [ok, err] = await checkPermission(session, groupId)
+    if (!ok) return err || '权限不足'
+    const rows = await ctx.database.get('group_verification_blacklist', { groupId })
+    const localReason = rows.length > 0 ? (rows[0].entries || {})[targetUser] : undefined
+    const globalReason = globalHit ? globalRows[0].entries[targetUser] : undefined
+    return `全局黑名单: ${globalReason || '无'}\n群${groupId}黑名单: ${localReason || '无'}`
+  }
+  return ''
+}
+
 export function apply(ctx: Context, config: Config) {
   // 创建数据库表
   ctx.model.extend('group_verification_config', {
@@ -873,6 +1141,17 @@ export function apply(ctx: Context, config: Config) {
     autoInc: true
   })
 
+  // 黑名单表：每条记录对应一个群（或全局），entries 存储 userId->reason 键值对
+  ctx.model.extend('group_verification_blacklist', {
+    id: 'unsigned',
+    groupId: 'string',
+    entries: 'json'
+  } as any, {
+    primary: 'id',
+    autoInc: true,
+    indexes: [ ['groupId'] ]
+  })
+
 
 
   // 监听 guild-member-request 事件，以便对新申请执行自动审批或拒绝
@@ -882,9 +1161,13 @@ export function apply(ctx: Context, config: Config) {
   })
 
   // 监听群成员增加事件（包括手动邀请入群）
-  ctx.on('guild-member-added', async (session) => {
-    const groupId = session.guildId
-    const userId = session.userId
+  ctx.on('guild-member-added', async (session: any) => {
+    const groupId = session.guildId || ''
+    const userId = session.userId || ''
+    if (!groupId || !userId) {
+      // 无效会话，忽略
+      return
+    }
 
     // 无论什么情况只要检测到加入就累加总入群
     await incrementTotal(ctx, groupId)
@@ -991,7 +1274,7 @@ export function apply(ctx: Context, config: Config) {
           return [true]
         }
       }
-    } catch (error) {
+    } catch (error: any) {
       logger.warn(`权限检查 - 获取群成员信息失败:`, error)
       return [false, `无法获取群 ${groupId} 的成员信息，请确认机器人已在该群中`]
     }
@@ -1020,7 +1303,7 @@ export function apply(ctx: Context, config: Config) {
     .option('disableMessage', '-nomsg 禁用提醒消息')
     .option('query', '-? 查询当前配置')
     .option('remove', '-r 删除配置')
-    .action(async ({ session, options }, keywords) => {
+    .action(async ({ session, options }: any, keywords: any) => {
       // 详细调试：记录所有输入信息
       logger.info(`=== 命令解析调试 ===`)
       logger.info(`session内容: guildId=${session.guildId}, userId=${session.userId}`)
@@ -1115,7 +1398,7 @@ export function apply(ctx: Context, config: Config) {
       try {
         const guild = await session.bot.getGuild(targetGroupId)
         groupName = guild.name || groupName
-      } catch (error) {
+      } catch (error: any) {
         // 无法获取群名称时使用默认值
       }
       
@@ -1388,7 +1671,7 @@ export function apply(ctx: Context, config: Config) {
       'gv.同意', 'gverify.同意', 'group-verify.同意',
       'gva'
     )
-    .action(async ({ session }, userId) => {
+    .action(async ({ session }: any, userId: any) => {
       // 权限检查
       const [hasPermission, errorMsg] = await checkPermission(session)
       if (!hasPermission) {
@@ -1421,7 +1704,7 @@ export function apply(ctx: Context, config: Config) {
               try {
                 await session.bot.handleGuildMemberRequest(request.requestId, true)
                 approvedCount++
-              } catch (error) {
+              } catch (error: any) {
                 logger.warn(`处理申请 ${request.id} 时出错:`, error)
               }
             } else {
@@ -1445,12 +1728,14 @@ export function apply(ctx: Context, config: Config) {
             return `用户 ${request.userId} 的申请缺少 requestId，无法自动同意`;
           }
           try {
-            await session.bot.handleGuildMemberRequest(request.requestId, true)
-            // 清除该用户的所有待审核记录
-            await ctx.database.remove('group_verification_pending', { groupId, userId: request.userId })
             const displayName = request.userName && request.userName !== request.userId ? `${request.userName}(${request.userId})` : request.userId
-            return `已同意用户 ${displayName} 的加群申请`
-          } catch (error) {
+            const reply = `已同意用户 ${displayName} 的加群申请`
+            // 先返回提示消息，再异步执行批准请求
+            session.bot.handleGuildMemberRequest(request.requestId, true).catch((e:any) => logger.warn('自动同意失败', e))
+            // 清除该用户的所有待审核记录（异步也可以，顺序无关）
+            await ctx.database.remove('group_verification_pending', { groupId, userId: request.userId })
+            return reply
+          } catch (error: any) {
             return `处理申请时出错: ${error.message}`
           }
         }
@@ -1471,12 +1756,12 @@ export function apply(ctx: Context, config: Config) {
         return `用户 ${userId} 的申请缺少 requestId，无法自动同意`
       }
       try {
-        await session.bot.handleGuildMemberRequest(request.requestId, true)
-        // 删除该用户的所有记录
-        await ctx.database.remove('group_verification_pending', { groupId, userId })
         const displayName = request.userName && request.userName !== request.userId ? `${request.userName}(${request.userId})` : request.userId
-        return `已同意用户 ${displayName} 的加群申请`
-      } catch (error) {
+        const reply = `已同意用户 ${displayName} 的加群申请`
+        session.bot.handleGuildMemberRequest(request.requestId, true).catch((e:any) => logger.warn('自动同意失败', e))
+        await ctx.database.remove('group_verification_pending', { groupId, userId })
+        return reply
+      } catch (error: any) {
         return `处理申请时出错: ${error.message}`
       }
     })
@@ -1489,7 +1774,7 @@ export function apply(ctx: Context, config: Config) {
       'gv.rej', 'gverify.rej', 'group-verify.rej',
       'gvr'
     )
-    .action(async ({ session }, userId) => {
+    .action(async ({ session }: any, userId: any) => {
       // 权限检查
       const [hasPermission, errorMsg] = await checkPermission(session)
       if (!hasPermission) {
@@ -1547,7 +1832,7 @@ export function apply(ctx: Context, config: Config) {
             await updateStats(ctx, groupId, 'rejected')
             const displayName = request.userName && request.userName !== request.userId ? `${request.userName}(${request.userId})` : request.userId
             return `已拒绝用户 ${displayName} 的加群申请`
-          } catch (error) {
+          } catch (error: any) {
             return `处理申请时出错: ${error.message}`
           }
         }
@@ -1574,7 +1859,7 @@ export function apply(ctx: Context, config: Config) {
         await updateStats(ctx, groupId, 'rejected')
         const displayName = request.userName && request.userName !== request.userId ? `${request.userName}(${request.userId})` : request.userId
         return `已拒绝用户 ${displayName} 的加群申请`
-      } catch (error) {
+      } catch (error: any) {
         return `处理申请时出错: ${error.message}`
       }
     })
@@ -1586,7 +1871,7 @@ export function apply(ctx: Context, config: Config) {
       'gv.统计', 'gverify.统计', 'group-verify.统计',
       'gvs'
     )
-    .action(async ({ session }, target) => {
+    .action(async ({ session }: any, target: any) => {
       // 参数验证：只能是群号、all、total或空
       const validTargets = ['all', 'total']
       const isGroupId = target && /^\d+$/.test(target)
@@ -1637,7 +1922,7 @@ export function apply(ctx: Context, config: Config) {
       'gv.待处理', 'gverify.待处理', 'group-verify.待处理',
       'gvp'
     )
-    .action(async ({ session }) => {
+    .action(async ({ session }: any) => {
       if (!session.guildId) {
         return '请在群聊中使用此命令'
       }
@@ -1662,6 +1947,18 @@ export function apply(ctx: Context, config: Config) {
       return result
     })
 
+  // Subcommand: blacklist management
+  groupVerify
+    .subcommand('.blacklist [args:text]', '管理加群黑名单')
+    .alias(
+      'gvb',
+      'gv.blacklist', 'gverify.blacklist', 'group-verify.blacklist',
+      'gv.黑名单', 'gverify.黑名单', 'group-verify.黑名单'
+    )
+    .action(async ({ session }: any, args: any) => {
+      return await processBlacklistCommand(ctx, session, args || '', config)
+    })
+
   // Subcommand: help information
   groupVerify
     .subcommand('.help', '显示帮助信息')
@@ -1718,6 +2015,19 @@ export function apply(ctx: Context, config: Config) {
     gv.cfg -m 2 -t 80
     gv.cfg -nomsg
 
+黑名单命令 (.blacklist / gvb):
+  a id [reason] [group]   添加黑名单，可指定原因和群号；group为all表示全局
+  r id [group]            删除条目；group 为 all 时移除全局黑名单
+  l [group]               查询群黑名单；传入 all 时查看全局黑名单
+  i id [group]            查询账号黑名单；不带参数时查询本群与全局，
+                          指定群号查询该群与全局，传入 all 则列出所有群及全局（需Koishi 3级）
+使用示例：
+    gvb a 12345 作弊记录
+    gvb r 12345 67890
+    gvb l
+    gvb l all
+    gvb i 12345
+
 快捷命令：
   gvc - 配置命令快捷方式
   gva - 同意申请快捷命令