koishi-plugin-group-control 1.0.0-alpha.7 → 1.0.1

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/config.d.ts

@@ -26,6 +26,9 @@ export interface GroupInviteConfig {
     inviteWaitMessage: string;
     inviteRequestMessage: string;
     autoApprove: boolean;
+    notifyAdminOnApprove: boolean;
+    inviteApproveMessage: string;
+    inviteApproveNotificationMessage: string;
     showDetailedLog: boolean;
     inviteExpireDays: number;
 }

package/lib/database.d.ts

@@ -1,80 +1,80 @@
-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 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>;

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

@@ -349,8 +349,8 @@ __name(getGroupName, "getGroupName");
 function apply2(ctx, config) {
   const quittingGuilds = /* @__PURE__ */ new Map();
   const processedKicks = /* @__PURE__ */ new Map();
-  const QUITTING_EXPIRE_MS = 5 * 60 * 1e3;
-  const KICK_DEDUP_MS = 5 * 60 * 1e3;
+  const QUITTING_EXPIRE_MS = 60 * 1e3;
+  const KICK_DEDUP_MS = 60 * 1e3;
   setInterval(() => {
     const now = Date.now();
     for (const [key, time] of quittingGuilds) {
@@ -459,7 +459,6 @@ function apply2(ctx, config) {
   ctx.on("guild-removed", async (session) => {
     const { guildId, platform } = session;
     const quittingKey = `${platform}:${guildId}`;
-    ctx.logger("group-control-basic").info(`[guild-removed] 触发！guildId=${guildId}, platform=${platform}, isQuitting=${quittingGuilds.has(quittingKey)}, isProcessed=${processedKicks.has(quittingKey)}`);
     if (quittingGuilds.has(quittingKey)) {
       return;
     }
@@ -576,6 +575,29 @@ function apply3(ctx, config) {
     } catch (error) {
       console.error("获取群信息失败:", error);
     }
+    if (config.invite.autoApprove) {
+      try {
+        await session.bot.internal.setGroupAddRequest(flag, "invite", true, "");
+        approvedGroups.add(rawGroupId);
+        if (config.invite.showDetailedLog) {
+          console.log(`自动同意群聊邀请: 群号 ${rawGroupId}, 邀请者 ${rawUserId}`);
+        }
+      } catch (error) {
+        console.error("自动同意群聊邀请失败:", error);
+        return;
+      }
+      try {
+        const approveMessage = config.invite.inviteApproveMessage.replaceAll("{groupName}", groupName).replaceAll("{groupId}", rawGroupId).replaceAll("{userName}", userName).replaceAll("{userId}", rawUserId);
+        await session.bot.sendPrivateMessage(rawUserId, approveMessage);
+      } catch (error) {
+        console.error(`发送自动通过提示给 ${rawUserId} 失败:`, error);
+      }
+      if (config.invite.notifyAdminOnApprove) {
+        const notifyMessage = config.invite.inviteApproveNotificationMessage.replaceAll("{groupName}", groupName).replaceAll("{groupId}", rawGroupId).replaceAll("{userName}", userName).replaceAll("{userId}", rawUserId);
+        await notifyAdmins(session.bot, config, notifyMessage);
+      }
+      return;
+    }
     try {
       const waitMessage = config.invite.inviteWaitMessage.replaceAll("{groupName}", groupName).replaceAll("{groupId}", rawGroupId).replaceAll("{userName}", userName).replaceAll("{userId}", rawUserId);
       await session.bot.sendPrivateMessage(rawUserId, waitMessage);
@@ -583,17 +605,6 @@ function apply3(ctx, config) {
       console.error(`发送等待审核提示给 ${rawUserId} 失败:`, error);
     }
     if (!config.admin.adminQQs || config.admin.adminQQs.length === 0) {
-      if (config.invite.autoApprove) {
-        try {
-          await session.bot.internal.setGroupAddRequest(flag, "invite", true, "");
-          approvedGroups.add(rawGroupId);
-          if (config.invite.showDetailedLog) {
-            console.log(`自动同意群聊邀请: 群号 ${rawGroupId}, 邀请者 ${rawUserId}`);
-          }
-        } catch (error) {
-          console.error("自动同意群聊邀请失败:", error);
-        }
-      }
       return;
     }
     await addPendingInvite(ctx, {
@@ -921,12 +932,8 @@ function apply5(ctx, config) {
     if (errorMsg) return errorMsg;
     const guildId = parseGuildId(input);
     if (!guildId) return `输入格式错误。`;
-    const existing = await getBlacklistedGuild(ctx, guildId);
-    if (existing.length === 0) return `群聊 ${guildId} 不在黑名单中。`;
-    await removeBlacklistedGuild(ctx, guildId);
-    const check = await getBlacklistedGuild(ctx, guildId);
-    if (check.length > 0) return `群聊 ${guildId} 移除失败，请重试。`;
-    return `已移除群聊 ${guildId}，当前黑名单中已不存在该群。`;
+    const removed = await removeBlacklistedGuild(ctx, guildId);
+    return removed ? `已移除群聊 ${guildId}` : `群聊 ${guildId} 不在黑名单中。`;
   });
   ctx.command("gc.banlist", "查看黑名单").action(async ({ session }) => {
     if (!hasGlobalPermission(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
@@ -1187,9 +1194,12 @@ var Config = import_koishi.Schema.intersect([
   import_koishi.Schema.object({
     invite: import_koishi.Schema.object({
       enabled: import_koishi.Schema.boolean().default(false).description("启用群聊邀请审核"),
-      autoApprove: import_koishi.Schema.boolean().default(false).description("自动同意邀请（仅在未指定管理员时生效）"),
+      autoApprove: import_koishi.Schema.boolean().default(false).description("自动同意邀请"),
+      notifyAdminOnApprove: import_koishi.Schema.boolean().default(true).description("自动同意时是否仍通知管理员"),
       inviteWaitMessage: import_koishi.Schema.string().default("已收到您的群聊邀请，正在等待管理员审核，请耐心等待。").description("发给邀请者的等待提示"),
+      inviteApproveMessage: import_koishi.Schema.string().default("已自动通过您的群聊邀请，机器人正在加入群聊。").description("自动同意时发给邀请者的提示，支持变量 {groupName}, {groupId}, {userName}, {userId}"),
       inviteRequestMessage: import_koishi.Schema.string().default("收到新的群聊邀请请求：\n群名称：{groupName}\n群号：{groupId}\n邀请者：{userName} (QQ: {userId})\n\n请使用指令 gc.approve {groupId} 同意或 gc.reject {groupId} 拒绝。").description("发给管理员的请求消息模板，支持变量 {groupName}, {groupId}, {userName}, {userId}"),
+      inviteApproveNotificationMessage: import_koishi.Schema.string().default("已自动通过群聊邀请\n群名称：{groupName}\n群号：{groupId}\n邀请者：{userName} (QQ: {userId})").description("自动同意时发给管理员的通知模板，支持变量 {groupName}, {groupId}, {userName}, {userId}"),
       inviteExpireDays: import_koishi.Schema.number().default(3).description("邀请记录过期天数"),
       showDetailedLog: import_koishi.Schema.boolean().default(false).description("显示详细日志")
     }).description("群聊邀请审核")

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.0-alpha.7",
+  "version": "1.0.1",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -22,8 +22,5 @@
   ],
   "peerDependencies": {
     "koishi": "^4.18.7"
-  },
-  "devDependencies": {
-    "@types/node": "^22.19.7"
   }
 }

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` 审核通过的情况下触发