koishi-plugin-group-control 1.0.1 → 1.0.2

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,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

@@ -142,13 +142,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) {
@@ -1050,7 +1057,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.2",
   "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` 审核通过的情况下触发