koishi-plugin-group-control 1.0.1 → 1.0.3

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 muyni
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 muyni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/database.d.ts

@@ -1,80 +1,96 @@
-import { Context } from 'koishi';
-export interface BlacklistedGuild {
-    platform: string;
-    guildId: string;
-    timestamp: number;
-    reason: string;
-}
-export interface CommandFrequencyRecord {
-    platform: string;
-    guildId: string;
-    commandCount: number;
-    lastCommandTime: number;
-    warningSent: boolean;
-    blockExpiryTime: number;
-    firstWarningTime: number;
-    blockCount: number;
-    lastBlockNotifyTime: number;
-}
-export interface GroupBotStatus {
-    platform: string;
-    guildId: string;
-    botEnabled: boolean;
-}
-export interface SmallGroupWhitelist {
-    platform: string;
-    guildId: string;
-}
-export interface PendingInvite {
-    platform: string;
-    groupId: string;
-    userId: string;
-    userName: string;
-    groupName: string;
-    time: number;
-    flag: string;
-}
-export interface PendingFriendRequest {
-    platform: string;
-    userId: string;
-    nickname: string;
-    comment: string;
-    flag: string;
-    time: number;
-}
-declare module 'koishi' {
-    interface Tables {
-        blacklisted_guild: BlacklistedGuild;
-        command_frequency_record: CommandFrequencyRecord;
-        group_bot_status: GroupBotStatus;
-        small_group_whitelist: SmallGroupWhitelist;
-        pending_invite: PendingInvite;
-        pending_friend_request: PendingFriendRequest;
-    }
-}
-export declare const name = "group-control-database";
-export declare function apply(ctx: Context): void;
-export declare const BLACKLIST_PLATFORM = "onebot";
-export declare function getBlacklistedGuild(ctx: Context, guildId: string): Promise<BlacklistedGuild[]>;
-export declare function removeBlacklistedGuild(ctx: Context, guildId: string): Promise<import("minato").Driver.WriteResult>;
-export declare function createBlacklistedGuild(ctx: Context, guildId: string, reason: string): Promise<import("minato").Driver.WriteResult>;
-export declare function getAllBlacklistedGuilds(ctx: Context): Promise<BlacklistedGuild[]>;
-export declare function clearBlacklistedGuilds(ctx: Context): Promise<import("minato").Driver.WriteResult>;
-export declare function getCommandFrequencyRecord(ctx: Context, platform: string, guildId: string): Promise<CommandFrequencyRecord>;
-export declare function updateCommandFrequencyRecord(ctx: Context, platform: string, guildId: string, data: Partial<CommandFrequencyRecord>): Promise<void>;
-export declare function getGroupBotStatus(ctx: Context, platform: string, guildId: string): Promise<GroupBotStatus | null>;
-export declare function setGroupBotStatus(ctx: Context, platform: string, guildId: string, botEnabled: boolean): Promise<void>;
-export declare function isInSmallGroupWhitelist(ctx: Context, guildId: string): Promise<boolean>;
-export declare function addToSmallGroupWhitelist(ctx: Context, guildId: string): Promise<void>;
-export declare function removeFromSmallGroupWhitelist(ctx: Context, guildId: string): Promise<void>;
-export declare function getAllSmallGroupWhitelist(ctx: Context): Promise<SmallGroupWhitelist[]>;
-export declare function getPendingInvite(ctx: Context, groupId: string): Promise<PendingInvite>;
-export declare function addPendingInvite(ctx: Context, inviteUser: Omit<PendingInvite, 'platform'>): Promise<void>;
-export declare function removePendingInvite(ctx: Context, groupId: string): Promise<void>;
-export declare function getAllPendingInvites(ctx: Context): Promise<PendingInvite[]>;
-export declare function clearExpiredPendingInvites(ctx: Context, expireTimeMs: number): Promise<number>;
-export declare function getPendingFriendRequest(ctx: Context, platform: string, userId: string): Promise<PendingFriendRequest>;
-export declare function addPendingFriendRequest(ctx: Context, platform: string, data: Omit<PendingFriendRequest, 'platform'>): Promise<void>;
-export declare function removePendingFriendRequest(ctx: Context, platform: string, userId: string): Promise<void>;
-export declare function getAllPendingFriendRequests(ctx: Context, platform: string): Promise<PendingFriendRequest[]>;
-export declare function clearExpiredPendingFriendRequests(ctx: Context, platform: string, expireTimeMs: number): Promise<number>;
+import { Context } from 'koishi';
+export interface BlacklistedGuild {
+    platform: string;
+    guildId: string;
+    timestamp: number;
+    reason: string;
+}
+export interface CommandFrequencyRecord {
+    platform: string;
+    guildId: string;
+    commandCount: number;
+    lastCommandTime: number;
+    warningSent: boolean;
+    blockExpiryTime: number;
+    firstWarningTime: number;
+    blockCount: number;
+    lastBlockNotifyTime: number;
+}
+export interface GroupBotStatus {
+    platform: string;
+    guildId: string;
+    botEnabled: boolean;
+}
+export interface SmallGroupWhitelist {
+    platform: string;
+    guildId: string;
+}
+export interface SelfLeftGuild {
+    platform: string;
+    guildId: string;
+    timestamp: number;
+}
+export interface PendingInvite {
+    platform: string;
+    groupId: string;
+    userId: string;
+    userName: string;
+    groupName: string;
+    time: number;
+    flag: string;
+}
+export interface PendingFriendRequest {
+    platform: string;
+    userId: string;
+    nickname: string;
+    comment: string;
+    flag: string;
+    time: number;
+}
+declare module 'koishi' {
+    interface Tables {
+        blacklisted_guild: BlacklistedGuild;
+        command_frequency_record: CommandFrequencyRecord;
+        group_bot_status: GroupBotStatus;
+        small_group_whitelist: SmallGroupWhitelist;
+        self_left_guild: SelfLeftGuild;
+        pending_invite: PendingInvite;
+        pending_friend_request: PendingFriendRequest;
+    }
+}
+export declare const name = "group-control-database";
+export declare function apply(ctx: Context): void;
+export declare const BLACKLIST_PLATFORM = "onebot";
+export declare function getBlacklistedGuild(ctx: Context, guildId: string): Promise<BlacklistedGuild[]>;
+export declare function removeBlacklistedGuild(ctx: Context, guildId: string): Promise<import("minato").Driver.WriteResult>;
+export declare function createBlacklistedGuild(ctx: Context, guildId: string, reason: string): Promise<import("minato").Driver.WriteResult>;
+export declare function getAllBlacklistedGuilds(ctx: Context): Promise<BlacklistedGuild[]>;
+export declare function clearBlacklistedGuilds(ctx: Context): Promise<import("minato").Driver.WriteResult>;
+/** 统一写入被踢黑名单行，保证 platform = BLACKLIST_PLATFORM */
+export declare function blacklistKicked(ctx: Context, guildId: string): Promise<import("minato").Driver.WriteResult>;
+/** 在主动退群前写入标记，让 guild-removed 能区分「自己退的」和「被踢的」*/
+export declare function markSelfLeft(ctx: Context, guildId: string): Promise<void>;
+/** 消费标记（单次读取后删除），返回是否在 maxAgeSec 内。用于 guild-removed 判断是自己退的 */
+export declare function consumeSelfLeft(ctx: Context, guildId: string, maxAgeSec?: number): Promise<boolean>;
+/** 清理标记（退群失败时回滚，或 unban 时清理）*/
+export declare function clearSelfLeft(ctx: Context, guildId: string): Promise<void>;
+/** 定期清理过期的主动退群标记（超过 maxAgeSec 秒未消费的）*/
+export declare function clearExpiredSelfLeft(ctx: Context, maxAgeSec?: number): Promise<number>;
+export declare function getCommandFrequencyRecord(ctx: Context, platform: string, guildId: string): Promise<CommandFrequencyRecord>;
+export declare function updateCommandFrequencyRecord(ctx: Context, platform: string, guildId: string, data: Partial<CommandFrequencyRecord>): Promise<void>;
+export declare function getGroupBotStatus(ctx: Context, platform: string, guildId: string): Promise<GroupBotStatus | null>;
+export declare function setGroupBotStatus(ctx: Context, platform: string, guildId: string, botEnabled: boolean): Promise<void>;
+export declare function isInSmallGroupWhitelist(ctx: Context, guildId: string): Promise<boolean>;
+export declare function addToSmallGroupWhitelist(ctx: Context, guildId: string): Promise<void>;
+export declare function removeFromSmallGroupWhitelist(ctx: Context, guildId: string): Promise<void>;
+export declare function getAllSmallGroupWhitelist(ctx: Context): Promise<SmallGroupWhitelist[]>;
+export declare function getPendingInvite(ctx: Context, groupId: string): Promise<PendingInvite>;
+export declare function addPendingInvite(ctx: Context, inviteUser: Omit<PendingInvite, 'platform'>): Promise<void>;
+export declare function removePendingInvite(ctx: Context, groupId: string): Promise<void>;
+export declare function getAllPendingInvites(ctx: Context): Promise<PendingInvite[]>;
+export declare function clearExpiredPendingInvites(ctx: Context, expireTimeMs: number): Promise<number>;
+export declare function getPendingFriendRequest(ctx: Context, platform: string, userId: string): Promise<PendingFriendRequest>;
+export declare function addPendingFriendRequest(ctx: Context, platform: string, data: Omit<PendingFriendRequest, 'platform'>): Promise<void>;
+export declare function removePendingFriendRequest(ctx: Context, platform: string, userId: string): Promise<void>;
+export declare function getAllPendingFriendRequests(ctx: Context, platform: string): Promise<PendingFriendRequest[]>;
+export declare function clearExpiredPendingFriendRequests(ctx: Context, platform: string, expireTimeMs: number): Promise<number>;

package/lib/index.d.ts

@@ -1,5 +1,5 @@
-import { Context } from 'koishi';
-import { Config } from './config';
-export * from './config';
-export declare const name = "group-control";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from './config';
+export * from './config';
+export declare const name = "group-control";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -34,9 +34,13 @@ __export(database_exports, {
   addPendingInvite: () => addPendingInvite,
   addToSmallGroupWhitelist: () => addToSmallGroupWhitelist,
   apply: () => apply,
+  blacklistKicked: () => blacklistKicked,
   clearBlacklistedGuilds: () => clearBlacklistedGuilds,
   clearExpiredPendingFriendRequests: () => clearExpiredPendingFriendRequests,
   clearExpiredPendingInvites: () => clearExpiredPendingInvites,
+  clearExpiredSelfLeft: () => clearExpiredSelfLeft,
+  clearSelfLeft: () => clearSelfLeft,
+  consumeSelfLeft: () => consumeSelfLeft,
   createBlacklistedGuild: () => createBlacklistedGuild,
   getAllBlacklistedGuilds: () => getAllBlacklistedGuilds,
   getAllPendingFriendRequests: () => getAllPendingFriendRequests,
@@ -48,6 +52,7 @@ __export(database_exports, {
   getPendingFriendRequest: () => getPendingFriendRequest,
   getPendingInvite: () => getPendingInvite,
   isInSmallGroupWhitelist: () => isInSmallGroupWhitelist,
+  markSelfLeft: () => markSelfLeft,
   name: () => name,
   removeBlacklistedGuild: () => removeBlacklistedGuild,
   removeFromSmallGroupWhitelist: () => removeFromSmallGroupWhitelist,
@@ -84,6 +89,11 @@ function apply(ctx) {
     platform: "string",
     guildId: "string"
   }, { primary: ["platform", "guildId"] });
+  ctx.model.extend("self_left_guild", {
+    platform: "string",
+    guildId: "string",
+    timestamp: "integer"
+  }, { primary: ["platform", "guildId"] });
   ctx.model.extend("pending_invite", {
     platform: "string",
     groupId: "string",
@@ -129,6 +139,44 @@ async function clearBlacklistedGuilds(ctx) {
   return await ctx.model.remove("blacklisted_guild", { platform: BLACKLIST_PLATFORM });
 }
 __name(clearBlacklistedGuilds, "clearBlacklistedGuilds");
+async function blacklistKicked(ctx, guildId) {
+  return await ctx.model.upsert("blacklisted_guild", [{
+    platform: BLACKLIST_PLATFORM,
+    guildId,
+    timestamp: Math.floor(Date.now() / 1e3),
+    reason: "kicked"
+  }]);
+}
+__name(blacklistKicked, "blacklistKicked");
+async function markSelfLeft(ctx, guildId) {
+  await ctx.model.upsert("self_left_guild", [{
+    platform: BLACKLIST_PLATFORM,
+    guildId,
+    timestamp: Math.floor(Date.now() / 1e3)
+  }]);
+}
+__name(markSelfLeft, "markSelfLeft");
+async function consumeSelfLeft(ctx, guildId, maxAgeSec = 120) {
+  const [row] = await ctx.model.get("self_left_guild", { platform: BLACKLIST_PLATFORM, guildId });
+  if (!row) return false;
+  await ctx.model.remove("self_left_guild", { platform: BLACKLIST_PLATFORM, guildId });
+  return Math.floor(Date.now() / 1e3) - row.timestamp <= maxAgeSec;
+}
+__name(consumeSelfLeft, "consumeSelfLeft");
+async function clearSelfLeft(ctx, guildId) {
+  await ctx.model.remove("self_left_guild", { platform: BLACKLIST_PLATFORM, guildId });
+}
+__name(clearSelfLeft, "clearSelfLeft");
+async function clearExpiredSelfLeft(ctx, maxAgeSec = 300) {
+  const cutoff = Math.floor(Date.now() / 1e3) - maxAgeSec;
+  const all = await ctx.model.get("self_left_guild", { platform: BLACKLIST_PLATFORM });
+  const expired = all.filter((r) => r.timestamp < cutoff);
+  for (const record of expired) {
+    await ctx.model.remove("self_left_guild", { platform: BLACKLIST_PLATFORM, guildId: record.guildId });
+  }
+  return expired.length;
+}
+__name(clearExpiredSelfLeft, "clearExpiredSelfLeft");
 async function getCommandFrequencyRecord(ctx, platform, guildId) {
   const records = await ctx.model.get("command_frequency_record", { platform, guildId });
   return records.length > 0 ? records[0] : null;
@@ -142,13 +190,20 @@ async function updateCommandFrequencyRecord(ctx, platform, guildId, data) {
   }]);
 }
 __name(updateCommandFrequencyRecord, "updateCommandFrequencyRecord");
+var groupBotStatusCache = /* @__PURE__ */ new Map();
+var groupBotStatusCacheKey = /* @__PURE__ */ __name((platform, guildId) => `${platform}:${guildId}`, "groupBotStatusCacheKey");
 async function getGroupBotStatus(ctx, platform, guildId) {
+  const key = groupBotStatusCacheKey(platform, guildId);
+  if (groupBotStatusCache.has(key)) return groupBotStatusCache.get(key);
   const records = await ctx.model.get("group_bot_status", { platform, guildId });
-  return records.length > 0 ? records[0] : null;
+  const status = records.length > 0 ? records[0] : null;
+  groupBotStatusCache.set(key, status);
+  return status;
 }
 __name(getGroupBotStatus, "getGroupBotStatus");
 async function setGroupBotStatus(ctx, platform, guildId, botEnabled) {
   await ctx.model.upsert("group_bot_status", [{ platform, guildId, botEnabled }]);
+  groupBotStatusCache.set(groupBotStatusCacheKey(platform, guildId), { platform, guildId, botEnabled });
 }
 __name(setGroupBotStatus, "setGroupBotStatus");
 async function isInSmallGroupWhitelist(ctx, guildId) {
@@ -360,17 +415,24 @@ function apply2(ctx, config) {
       if (now - time > KICK_DEDUP_MS) processedKicks.delete(key);
     }
   }, 30 * 1e3);
+  setInterval(async () => {
+    try {
+      await clearExpiredSelfLeft(ctx);
+    } catch {
+    }
+  }, 5 * 60 * 1e3);
   ctx.on("guild-added", async (session) => {
     const { guildId, platform } = session;
     ctx.logger("group-control-basic").info(`[guild-added] 触发！guildId=${guildId}, platform=${platform}`);
     if (config.basic.enableBlacklist) {
-      const [blacklisted] = await ctx.model.get("blacklisted_guild", { platform, guildId });
+      const [blacklisted] = await ctx.model.get("blacklisted_guild", { platform: BLACKLIST_PLATFORM, guildId });
       if (blacklisted) {
         try {
           await session.bot.sendMessage(guildId, config.basic.blacklistMessage, platform);
         } catch (e) {
         }
-        quittingGuilds.set(`${platform}:${guildId}`, Date.now());
+        quittingGuilds.set(`${BLACKLIST_PLATFORM}:${guildId}`, Date.now());
+        await markSelfLeft(ctx, guildId);
         try {
           await session.bot.internal.setGroupLeave(parseInt(guildId));
         } catch (e) {
@@ -430,12 +492,14 @@ function apply2(ctx, config) {
 机器人已自动退出该群。`;
                 await notifyAdmins(session.bot, config, adminMsg);
               }
-              quittingGuilds.set(`${platform}:${guildId}`, Date.now());
+              quittingGuilds.set(`${BLACKLIST_PLATFORM}:${guildId}`, Date.now());
+              await markSelfLeft(ctx, guildId);
               try {
                 await session.bot.internal.setGroupLeave(parseInt(guildId));
               } catch (e) {
                 console.error(`小群自动退群失败 (群号: ${guildId}):`, e);
-                quittingGuilds.delete(`${platform}:${guildId}`);
+                quittingGuilds.delete(`${BLACKLIST_PLATFORM}:${guildId}`);
+                await clearSelfLeft(ctx, guildId);
               }
             } else if (memberCount > config.basic.smallGroupThreshold) {
               if (config.basic.smallGroupQualifiedNotifyAdmin) {
@@ -457,25 +521,37 @@ function apply2(ctx, config) {
     }
   });
   ctx.on("guild-removed", async (session) => {
-    const { guildId, platform } = session;
-    const quittingKey = `${platform}:${guildId}`;
-    if (quittingGuilds.has(quittingKey)) {
+    const { guildId } = session;
+    const platform = BLACKLIST_PLATFORM;
+    const dedupKey = `${platform}:${guildId}`;
+    if (quittingGuilds.has(dedupKey)) {
+      try {
+        await clearSelfLeft(ctx, guildId);
+      } catch {
+      }
       return;
     }
-    if (processedKicks.has(quittingKey)) {
-      return;
+    const isSelfLeft = await consumeSelfLeft(ctx, guildId);
+    if (isSelfLeft) return;
+    const raw = session.event?._data || session.original || session.onebot || {};
+    const subType = String(raw.sub_type ?? session.subtype ?? "");
+    const eventTs = typeof raw.time === "number" ? raw.time : Math.floor(Date.now() / 1e3);
+    const ageSec = Math.floor(Date.now() / 1e3) - eventTs;
+    if (subType === "leave") return;
+    if (!subType && ageSec > 60) return;
+    if (processedKicks.has(dedupKey)) return;
+    processedKicks.set(dedupKey, Date.now());
+    if (config.basic.enableBlacklist || config.basic.notifyAdminOnKick) {
+      const [existing] = await ctx.model.get("blacklisted_guild", { platform, guildId });
+      if (existing && existing.reason === "kicked") {
+        return;
+      }
     }
-    processedKicks.set(quittingKey, Date.now());
-    const groupName = await getGroupName(session.bot, guildId);
     if (config.basic.enableBlacklist) {
-      await ctx.model.upsert("blacklisted_guild", [{
-        platform,
-        guildId,
-        timestamp: Math.floor(Date.now() / 1e3),
-        reason: "kicked"
-      }]);
+      await blacklistKicked(ctx, guildId);
     }
     if (config.basic.notifyAdminOnKick) {
+      const groupName = await getGroupName(session.bot, guildId);
       const kickMsg = config.basic.kickNotificationMessage.replaceAll("{groupId}", guildId).replaceAll("{groupName}", groupName);
       await notifyAdmins(session.bot, config, kickMsg);
     }
@@ -509,7 +585,8 @@ function apply2(ctx, config) {
 群名称：${groupName}
 群号：${guildId}`;
       await notifyAdmins(session.bot, config, adminMsg);
-      quittingGuilds.set(`${platform}:${guildId}`, Date.now());
+      quittingGuilds.set(`${BLACKLIST_PLATFORM}:${guildId}`, Date.now());
+      await markSelfLeft(ctx, guildId);
       try {
         await session.bot.sendMessage(session.guildId, config.basic.quitMessage.replace("{userId}", userId), platform);
       } catch (e) {
@@ -517,7 +594,8 @@ function apply2(ctx, config) {
       try {
         await session.bot.internal.setGroupLeave(parseInt(guildId));
       } catch (e) {
-        quittingGuilds.delete(`${platform}:${guildId}`);
+        quittingGuilds.delete(`${BLACKLIST_PLATFORM}:${guildId}`);
+        await clearSelfLeft(ctx, guildId);
         return `退出失败: ${e.message}`;
       }
       return "";
@@ -555,6 +633,33 @@ function apply3(ctx, config) {
     const rawUserId = raw.user_id ? String(raw.user_id) : session.userId;
     const rawGroupId = raw.group_id ? String(raw.group_id) : session.guildId;
     const { platform } = session;
+    if (config.basic.enableBlacklist && rawGroupId && /^\d+$/.test(String(rawGroupId))) {
+      const bl = await getBlacklistedGuild(ctx, String(rawGroupId));
+      if (bl.length > 0) {
+        try {
+          await session.bot.internal.setGroupAddRequest(flag, "invite", false, "该群已被机器人拉黑");
+        } catch (e) {
+          ctx.logger("group-control-invite").warn("拒绝黑名单群邀请失败 (flag 可能已失效):", e);
+        }
+        const rejectNotify = `已自动拒绝黑名单群邀请
+群号：${rawGroupId}
+邀请者 QQ：${rawUserId}
+如需放行请先执行 gc.unban ${rawGroupId} 再让对方重新邀请。`;
+        try {
+          await notifyAdmins(session.bot, config, rejectNotify);
+        } catch (e) {
+        }
+        try {
+          const rejectMsg = `您邀请加入的群 ${rawGroupId} 已被机器人拉黑，邀请已被自动拒绝。如有疑问请联系机器人管理员。`;
+          await session.bot.sendPrivateMessage(rawUserId, rejectMsg);
+        } catch (e) {
+        }
+        if (config.invite.showDetailedLog) {
+          console.log(`已自动拒绝黑名单群邀请: 群号 ${rawGroupId}, 邀请者 ${rawUserId}`);
+        }
+        return;
+      }
+    }
     if (!flag && config.invite.showDetailedLog) {
       console.warn("未能提取到邀请 flag，可能导致无法处理邀请。Raw event:", JSON.stringify(raw));
     }
@@ -648,6 +753,12 @@ function apply3(ctx, config) {
   ctx.command("gc.approve <groupId:string>", "同意群聊邀请").action(async ({ session }, groupId) => {
     if (!groupId) return "请指定群号。用法：gc.approve <群号>";
     if (!hasGlobalPermission(session, config)) return "权限不足，只有管理员可以审核邀请。";
+    if (config.basic.enableBlacklist) {
+      const bl = await getBlacklistedGuild(ctx, groupId);
+      if (bl.length > 0) {
+        return `群 ${groupId} 在黑名单中，无法通过审核。如需放行请先执行 gc.unban ${groupId}。`;
+      }
+    }
     const inviteData = await getPendingInvite(ctx, groupId);
     if (!inviteData) {
       const allInvites = await getAllPendingInvites(ctx);
@@ -933,6 +1044,7 @@ function apply5(ctx, config) {
     const guildId = parseGuildId(input);
     if (!guildId) return `输入格式错误。`;
     const removed = await removeBlacklistedGuild(ctx, guildId);
+    await clearSelfLeft(ctx, guildId);
     return removed ? `已移除群聊 ${guildId}` : `群聊 ${guildId} 不在黑名单中。`;
   });
   ctx.command("gc.banlist", "查看黑名单").action(async ({ session }) => {
@@ -1050,7 +1162,9 @@ function apply6(ctx, config) {
     if (isBotEnabled) {
       return next();
     }
-    if (ADMIN_COMMANDS.has(session["event"]["_data"]["message"])) {
+    const content = session.stripped?.content ?? session.content ?? "";
+    const firstWord = content.match(/^\s*[/.!！。]*(\S+)/)?.[1];
+    if (firstWord && ADMIN_COMMANDS.has(firstWord)) {
       return next();
     }
     const isMentioned = session.elements?.some((e) => e.type === "at" && e.attrs.id === session.bot.userId);

package/lib/modules/basic.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-basic";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-basic";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/modules/commands.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-commands";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-commands";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/modules/frequency.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-frequency";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-frequency";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/modules/friend.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-friend";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-friend";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/modules/invite.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-invite";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-invite";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/modules/switch.d.ts

@@ -1,4 +1,4 @@
-import { Context } from 'koishi';
-import { Config } from '../config';
-export declare const name = "group-control-switch";
-export declare function apply(ctx: Context, config: Config): void;
+import { Context } from 'koishi';
+import { Config } from '../config';
+export declare const name = "group-control-switch";
+export declare function apply(ctx: Context, config: Config): void;

package/lib/state.d.ts

@@ -1,6 +1,6 @@
-/**
- * 跨模块共享状态
- * 用于在 invite 和 basic 等模块间传递信息
- */
-/** 管理员已审核通过的群号集合（approve 指令通过后添加） */
-export declare const approvedGroups: Set<string>;
+/**
+ * 跨模块共享状态
+ * 用于在 invite 和 basic 等模块间传递信息
+ */
+/** 管理员已审核通过的群号集合（approve 指令通过后添加） */
+export declare const approvedGroups: Set<string>;

package/lib/utils.d.ts

@@ -1,17 +1,17 @@
-import { Session } from 'koishi';
-import { Config } from './config';
-export declare function isBlacklistEnabled(config: Config['basic']): string | null;
-export declare function parseGuildId(input: string): string | null;
-export declare function formatDate(timestamp: number): string;
-export declare function notifyAdmins(bot: any, config: Config, message: string): Promise<void>;
-/** 是否为全局管理员（填在 adminQQs 里的） */
-export declare function isGlobalAdmin(session: Session, config: Config): boolean;
-/**
- * 检查群级权限（bot-on/off、quit、protectedCommands）
- * builtin 模式：群管理员或全局管理员均可
- * koishi 模式：由 authority 决定
- */
-export declare function hasGuildPermission(session: Session, config: Config): Promise<boolean>;
-export declare function hasGlobalPermission(session: Session, config: Config): boolean;
-/** 管理指令列表 - 这些指令始终不受 bot-off 影响 */
-export declare const ADMIN_COMMANDS: Set<string>;
+import { Session } from 'koishi';
+import { Config } from './config';
+export declare function isBlacklistEnabled(config: Config['basic']): string | null;
+export declare function parseGuildId(input: string): string | null;
+export declare function formatDate(timestamp: number): string;
+export declare function notifyAdmins(bot: any, config: Config, message: string): Promise<void>;
+/** 是否为全局管理员（填在 adminQQs 里的） */
+export declare function isGlobalAdmin(session: Session, config: Config): boolean;
+/**
+ * 检查群级权限（bot-on/off、quit、protectedCommands）
+ * builtin 模式：群管理员或全局管理员均可
+ * koishi 模式：由 authority 决定
+ */
+export declare function hasGuildPermission(session: Session, config: Config): Promise<boolean>;
+export declare function hasGlobalPermission(session: Session, config: Config): boolean;
+/** 管理指令列表 - 这些指令始终不受 bot-off 影响 */
+export declare const ADMIN_COMMANDS: Set<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-group-control",
   "description": "Koishi 插件，一个多功能的群聊自管理工具。支持被踢出自动拉黑、刷屏自动屏蔽、开关控制等功能。(仅支持 OneBot 适配器)",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -1,199 +1,199 @@
-# koishi-plugin-group-control
-
-[![npm](https://img.shields.io/npm/v/koishi-plugin-group-control?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-group-control)
-
-Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
-
-> 使用 Qwen3-Coder & Gemini-3.1-Pro-Preview & Claude Sonnet/Opus 4.6 协助完成
-
----
-
-## 功能概览
-
-- **黑名单管理**：被踢出群后自动拉黑，下次被邀请时自动退出
-- **小群自动退群**：加入人数不足的群时自动退出并通知管理员
-- **合格小群通知**：未经审核被拉入人数达标的群时，通知管理员确认
-- **群聊邀请审核**：收到邀请时暂缓加入，等待管理员审核
-- **好友申请管理**：收到好友申请时通知管理员，或自动通过
-- **频率控制**：限制群聊/私聊的指令及对话频率，支持指数增长屏蔽时长
-- **Bot 开关**：按群独立开关 bot，关闭后屏蔽所有响应
-- **被禁言通知**：bot 被禁言时可选通知管理员
-- **权限管理**：支持 Koishi authority 或内置群管理员两种权限模式
-
----
-
-## 配置说明
-
-### 管理员配置
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `admin.adminQQs` | `[]` | 管理员QQ号列表（权限验证及通知） |
-| `admin.notificationGroupId` | *(空)* | 通知群号（填写后发到此群，否则私聊管理员） |
-
-### 权限管理
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `mode` | `builtin` | `builtin`：使用群管理员/群主权限；`koishi`：使用 Koishi authority |
-| `koishiAuthority` | `3` | Koishi 模式下管理指令所需的最低权限等级 |
-| `protectedCommands` | `[]` | 需要群管理员权限才能使用的自定义指令名列表 |
-
-### 基础群组管理
-
-**欢迎 & 退群**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `welcomeMessage` | `你好，我是机器人。` | 加入群聊时发送的欢迎消息 |
-| `quitMessage` | `收到来自{userId}的指令，即将退出群聊。` | quit 指令触发后的群内提示，支持 `{userId}` |
-| `quitCommandEnabled` | `true` | 是否启用 quit 指令 |
-
-**黑名单**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enableBlacklist` | `true` | 启用被踢出自动拉黑 |
-| `blacklistMessage` | *(见配置)* | 被拉入黑名单群后的提示 |
-
-**踢出通知**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `notifyAdminOnKick` | `true` | 被踢出时通知管理员 |
-| `kickNotificationMessage` | *(见配置)* | 通知消息模板，支持 `{groupId}`, `{groupName}` |
-
-**小群自动退群**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `smallGroupAutoQuit` | `false` | 启用小群自动退群 |
-| `smallGroupThreshold` | `30` | 人数阈值，低于等于此值时自动退出 |
-| `smallGroupQuitMessage` | *(见配置)* | 退群提示，支持 `{memberCount}`, `{threshold}`, `{groupName}`, `{groupId}` |
-| `smallGroupNotifyAdmin` | `true` | 自动退群时通知管理员 |
-| `smallGroupCheckDelay` | `3000` | 加入后延迟检测的时间（毫秒） |
-
-**合格小群通知**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `smallGroupQualifiedNotifyAdmin` | `true` | 未经审核被拉入人数达标的群时通知管理员 |
-| `smallGroupQualifiedMessage` | *(见配置)* | 通知消息模板，支持 `{groupName}`, `{groupId}`, `{memberCount}`, `{threshold}` |
-
-**被禁言通知**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `notifyAdminOnMute` | `false` | bot 被禁言时通知管理员 |
-| `muteNotificationMessage` | *(见配置)* | 通知消息模板，支持 `{groupId}`, `{groupName}`, `{operatorId}`, `{duration}` |
-
-### 频率控制
-
-**群聊**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `false` | 启用群聊频率控制（指令及 @ 对话均受限） |
-| `limit` | `5` | 时间窗口内允许的最大触发次数 |
-| `window` | `60` | 时间窗口（秒） |
-| `warnDelay` | `30` | 警告后再次触发的时间阈值（秒），超出则进入屏蔽 |
-| `blockDur` | `300` | 首次屏蔽的基础时长（秒） |
-| `whitelist` | `[]` | 不受频率限制的群号列表 |
-
-**私聊**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `privateEnabled` | `false` | 启用私聊频率控制 |
-| `privateLimit` | `10` | 私聊时间窗口内允许的最大触发次数 |
-| `privateWindow` | `60` | 私聊时间窗口（秒） |
-| `privateWarnDelay` | `30` | 私聊警告后再次触发的时间阈值（秒） |
-| `privateBlockDur` | `300` | 私聊首次屏蔽的基础时长（秒） |
-| `privateWhitelist` | `[]` | 不受私聊频率限制的用户ID列表 |
-
-**指数增长（群聊和私聊共用）**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `blockExpBase` | `2` | 指数增长底数，每次屏蔽时长 = `blockDur × base^(次数-1)`，设为 `1` 禁用 |
-| `blockExpWindow` | `3600` | 指数增长重置窗口（秒），从最后一次屏蔽结束计算，超出则重置屏蔽次数 |
-
-**提示消息**
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `blockNotifyCooldown` | `60` | 屏蔽期间重复触发时提示消息的冷却时间（秒），避免刷屏 |
-| `warnMsg` | `发言频率过高，请慢一点~` | 首次超限警告消息 |
-| `blockMsg` | `发言频率过高，已被禁用 {duration} 秒。` | 进入屏蔽时的通知，支持 `{duration}` |
-| `blockedMsg` | `暂时被禁用，还有 {time} 秒解禁。` | 屏蔽期间再次触发时的提示，支持 `{time}` |
-
-### 好友申请管理
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `false` | 启用好友申请管理 |
-| `autoApprove` | `false` | 自动通过好友申请，否则通知管理员手动处理 |
-| `notifyAdminOnApprove` | `true` | 自动通过时是否仍通知管理员 |
-| `requestExpireDays` | `7` | 待处理申请的过期天数 |
-| `requestMessage` | *(见配置)* | 通知管理员的消息模板，支持 `{userId}`, `{nickname}`, `{comment}` |
-| `approveNotificationMessage` | *(见配置)* | 自动通过时的通知消息模板，支持 `{userId}`, `{nickname}`, `{comment}` |
-
-### 群聊邀请审核
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `false` | 启用邀请审核 |
-| `inviteWaitMessage` | *(见配置)* | 发给邀请者的等待提示 |
-| `inviteRequestMessage` | *(见配置)* | 发给管理员的请求消息，支持 `{groupName}`, `{groupId}`, `{userName}`, `{userId}` |
-| `autoApprove` | `false` | 未配置管理员时自动同意邀请 |
-| `showDetailedLog` | `false` | 显示详细日志 |
-| `inviteExpireDays` | `3` | 邀请记录过期天数 |
-
-### 机器人开关
-
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `enabled` | `true` | 启用群聊 bot 开关功能 |
-| `defaultState` | `true` | 默认开启状态 |
-| `disabledMessage` | *(见配置)* | 关闭状态下被 @ 时的提示 |
-
----
-
-## 指令列表
-
-所有管理员指令统一收纳在 `gc` 主指令下，输入 `gc` 可查看子指令列表。
-
-### 管理员指令（gc 子指令，需全局管理员）
-
-| 指令 | 说明 |
-|------|------|
-| `gc.banlist` | 查看黑名单列表 |
-| `gc.ban <群号>` | 添加群到黑名单 |
-| `gc.unban <群号>` | 从黑名单移除群 |
-| `gc.clearban` | 清空黑名单 |
-| `gc.sg-add <群号>` | 将群加入小群白名单，不受人数限制 |
-| `gc.sg-rm <群号>` | 从小群白名单移除群 |
-| `gc.sg-list` | 查看小群白名单 |
-| `gc.approve <群号>` | 同意加入指定群 |
-| `gc.reject <群号>` | 拒绝加入指定群 |
-| `gc.pending` | 查看待处理的群聊邀请列表 |
-| `gc.fa <QQ号>` | 同意好友申请 |
-| `gc.fr <QQ号>` | 拒绝好友申请 |
-| `gc.fp` | 查看待处理的好友申请列表 |
-
-### 群聊管理
-
-| 指令 | 说明 | 权限 |
-|------|------|------|
-| `quit` | 让 bot 退出当前群聊 | 群管理员 |
-| `bot-on` | 开启当前群的 bot | 群管理员 |
-| `bot-off` | 关闭当前群的 bot | 群管理员 |
-
----
-
-## 注意事项
-
-- 本插件仅支持 **OneBot 适配器**（如 go-cqhttp、LLOneBot 等）
-- 管理员通知依赖 `admin.adminQQs` 或 `admin.notificationGroupId` 的配置，未配置则无法收到通知
-- 频率控制的非指令拦截（@ 对话、私聊）不影响入群欢迎等系统事件
-- 小群合格通知仅在启用了 `smallGroupAutoQuit` 且未经 `gc.approve` 审核通过的情况下触发
+# koishi-plugin-group-control
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-group-control?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-group-control)
+
+Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
+
+> 使用 Qwen3-Coder & Gemini-3.1-Pro-Preview & Claude Sonnet/Opus 4.6 协助完成
+
+---
+
+## 功能概览
+
+- **黑名单管理**：被踢出群后自动拉黑，下次被邀请时自动退出
+- **小群自动退群**：加入人数不足的群时自动退出并通知管理员
+- **合格小群通知**：未经审核被拉入人数达标的群时，通知管理员确认
+- **群聊邀请审核**：收到邀请时暂缓加入，等待管理员审核
+- **好友申请管理**：收到好友申请时通知管理员，或自动通过
+- **频率控制**：限制群聊/私聊的指令及对话频率，支持指数增长屏蔽时长
+- **Bot 开关**：按群独立开关 bot，关闭后屏蔽所有响应
+- **被禁言通知**：bot 被禁言时可选通知管理员
+- **权限管理**：支持 Koishi authority 或内置群管理员两种权限模式
+
+---
+
+## 配置说明
+
+### 管理员配置
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `admin.adminQQs` | `[]` | 管理员QQ号列表（权限验证及通知） |
+| `admin.notificationGroupId` | *(空)* | 通知群号（填写后发到此群，否则私聊管理员） |
+
+### 权限管理
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `mode` | `builtin` | `builtin`：使用群管理员/群主权限；`koishi`：使用 Koishi authority |
+| `koishiAuthority` | `3` | Koishi 模式下管理指令所需的最低权限等级 |
+| `protectedCommands` | `[]` | 需要群管理员权限才能使用的自定义指令名列表 |
+
+### 基础群组管理
+
+**欢迎 & 退群**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `welcomeMessage` | `你好，我是机器人。` | 加入群聊时发送的欢迎消息 |
+| `quitMessage` | `收到来自{userId}的指令，即将退出群聊。` | quit 指令触发后的群内提示，支持 `{userId}` |
+| `quitCommandEnabled` | `true` | 是否启用 quit 指令 |
+
+**黑名单**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enableBlacklist` | `true` | 启用被踢出自动拉黑 |
+| `blacklistMessage` | *(见配置)* | 被拉入黑名单群后的提示 |
+
+**踢出通知**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `notifyAdminOnKick` | `true` | 被踢出时通知管理员 |
+| `kickNotificationMessage` | *(见配置)* | 通知消息模板，支持 `{groupId}`, `{groupName}` |
+
+**小群自动退群**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `smallGroupAutoQuit` | `false` | 启用小群自动退群 |
+| `smallGroupThreshold` | `30` | 人数阈值，低于等于此值时自动退出 |
+| `smallGroupQuitMessage` | *(见配置)* | 退群提示，支持 `{memberCount}`, `{threshold}`, `{groupName}`, `{groupId}` |
+| `smallGroupNotifyAdmin` | `true` | 自动退群时通知管理员 |
+| `smallGroupCheckDelay` | `3000` | 加入后延迟检测的时间（毫秒） |
+
+**合格小群通知**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `smallGroupQualifiedNotifyAdmin` | `true` | 未经审核被拉入人数达标的群时通知管理员 |
+| `smallGroupQualifiedMessage` | *(见配置)* | 通知消息模板，支持 `{groupName}`, `{groupId}`, `{memberCount}`, `{threshold}` |
+
+**被禁言通知**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `notifyAdminOnMute` | `false` | bot 被禁言时通知管理员 |
+| `muteNotificationMessage` | *(见配置)* | 通知消息模板，支持 `{groupId}`, `{groupName}`, `{operatorId}`, `{duration}` |
+
+### 频率控制
+
+**群聊**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `false` | 启用群聊频率控制（指令及 @ 对话均受限） |
+| `limit` | `5` | 时间窗口内允许的最大触发次数 |
+| `window` | `60` | 时间窗口（秒） |
+| `warnDelay` | `30` | 警告后再次触发的时间阈值（秒），超出则进入屏蔽 |
+| `blockDur` | `300` | 首次屏蔽的基础时长（秒） |
+| `whitelist` | `[]` | 不受频率限制的群号列表 |
+
+**私聊**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `privateEnabled` | `false` | 启用私聊频率控制 |
+| `privateLimit` | `10` | 私聊时间窗口内允许的最大触发次数 |
+| `privateWindow` | `60` | 私聊时间窗口（秒） |
+| `privateWarnDelay` | `30` | 私聊警告后再次触发的时间阈值（秒） |
+| `privateBlockDur` | `300` | 私聊首次屏蔽的基础时长（秒） |
+| `privateWhitelist` | `[]` | 不受私聊频率限制的用户ID列表 |
+
+**指数增长（群聊和私聊共用）**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `blockExpBase` | `2` | 指数增长底数，每次屏蔽时长 = `blockDur × base^(次数-1)`，设为 `1` 禁用 |
+| `blockExpWindow` | `3600` | 指数增长重置窗口（秒），从最后一次屏蔽结束计算，超出则重置屏蔽次数 |
+
+**提示消息**
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `blockNotifyCooldown` | `60` | 屏蔽期间重复触发时提示消息的冷却时间（秒），避免刷屏 |
+| `warnMsg` | `发言频率过高，请慢一点~` | 首次超限警告消息 |
+| `blockMsg` | `发言频率过高，已被禁用 {duration} 秒。` | 进入屏蔽时的通知，支持 `{duration}` |
+| `blockedMsg` | `暂时被禁用，还有 {time} 秒解禁。` | 屏蔽期间再次触发时的提示，支持 `{time}` |
+
+### 好友申请管理
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `false` | 启用好友申请管理 |
+| `autoApprove` | `false` | 自动通过好友申请，否则通知管理员手动处理 |
+| `notifyAdminOnApprove` | `true` | 自动通过时是否仍通知管理员 |
+| `requestExpireDays` | `7` | 待处理申请的过期天数 |
+| `requestMessage` | *(见配置)* | 通知管理员的消息模板，支持 `{userId}`, `{nickname}`, `{comment}` |
+| `approveNotificationMessage` | *(见配置)* | 自动通过时的通知消息模板，支持 `{userId}`, `{nickname}`, `{comment}` |
+
+### 群聊邀请审核
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `false` | 启用邀请审核 |
+| `inviteWaitMessage` | *(见配置)* | 发给邀请者的等待提示 |
+| `inviteRequestMessage` | *(见配置)* | 发给管理员的请求消息，支持 `{groupName}`, `{groupId}`, `{userName}`, `{userId}` |
+| `autoApprove` | `false` | 未配置管理员时自动同意邀请 |
+| `showDetailedLog` | `false` | 显示详细日志 |
+| `inviteExpireDays` | `3` | 邀请记录过期天数 |
+
+### 机器人开关
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `true` | 启用群聊 bot 开关功能 |
+| `defaultState` | `true` | 默认开启状态 |
+| `disabledMessage` | *(见配置)* | 关闭状态下被 @ 时的提示 |
+
+---
+
+## 指令列表
+
+所有管理员指令统一收纳在 `gc` 主指令下，输入 `gc` 可查看子指令列表。
+
+### 管理员指令（gc 子指令，需全局管理员）
+
+| 指令 | 说明 |
+|------|------|
+| `gc.banlist` | 查看黑名单列表 |
+| `gc.ban <群号>` | 添加群到黑名单 |
+| `gc.unban <群号>` | 从黑名单移除群 |
+| `gc.clearban` | 清空黑名单 |
+| `gc.sg-add <群号>` | 将群加入小群白名单，不受人数限制 |
+| `gc.sg-rm <群号>` | 从小群白名单移除群 |
+| `gc.sg-list` | 查看小群白名单 |
+| `gc.approve <群号>` | 同意加入指定群 |
+| `gc.reject <群号>` | 拒绝加入指定群 |
+| `gc.pending` | 查看待处理的群聊邀请列表 |
+| `gc.fa <QQ号>` | 同意好友申请 |
+| `gc.fr <QQ号>` | 拒绝好友申请 |
+| `gc.fp` | 查看待处理的好友申请列表 |
+
+### 群聊管理
+
+| 指令 | 说明 | 权限 |
+|------|------|------|
+| `quit` | 让 bot 退出当前群聊 | 群管理员 |
+| `bot-on` | 开启当前群的 bot | 群管理员 |
+| `bot-off` | 关闭当前群的 bot | 群管理员 |
+
+---
+
+## 注意事项
+
+- 本插件仅支持 **OneBot 适配器**（如 go-cqhttp、LLOneBot 等）
+- 管理员通知依赖 `admin.adminQQs` 或 `admin.notificationGroupId` 的配置，未配置则无法收到通知
+- 频率控制的非指令拦截（@ 对话、私聊）不影响入群欢迎等系统事件
+- 小群合格通知仅在启用了 `smallGroupAutoQuit` 且未经 `gc.approve` 审核通过的情况下触发