koishi-plugin-group-control 1.0.4 → 1.1.0-alpha.0

package/package.json

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

package/readme.md

@@ -4,20 +4,22 @@
 
 Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
 
-> 使用 Qwen3-Coder & Gemini-3.1-Pro-Preview & Claude Sonnet/Opus 4.6 协助完成
+> 使用 AI Agent 协助完成
 
 ---
 
 ## 功能概览
 
 - **黑名单管理**：被踢出群后自动拉黑，下次被邀请时自动退出
-- **小群自动退群**：加入人数不足的群时自动退出并通知管理员
+- **小群自动退群**：加入人数不足的群时自动退出并通知管理员，统计人数时自动排除 QQ 官方机器人（仅计真人）
+- **实时小群监控**：监听成员退群事件，群缩水到阈值以下时自动退出（仅针对未经审核拉入的群）
 - **合格小群通知**：未经审核被拉入人数达标的群时，通知管理员确认
 - **群聊邀请审核**：收到邀请时暂缓加入，等待管理员审核
 - **好友申请管理**：收到好友申请时通知管理员，或自动通过
 - **频率控制**：限制群聊/私聊的指令及对话频率，支持指数增长屏蔽时长
 - **Bot 开关**：按群独立开关 bot，关闭后屏蔽所有响应
-- **被禁言通知**：bot 被禁言时可选通知管理员
+- **好友/群管理**：指令列出好友（合并转发）、删除好友、列出所在群、远程退出指定群
+- **被禁言通知**：bot 被禁言时可选通知管理员；被禁言时长达到阈值时可自动退群并拉黑
 - **权限管理**：支持 Koishi authority 或内置群管理员两种权限模式
 
 ---
@@ -69,6 +71,9 @@ Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
 |--------|--------|------|
 | `smallGroupAutoQuit` | `false` | 启用小群自动退群 |
 | `smallGroupThreshold` | `30` | 人数阈值，低于等于此值时自动退出 |
+| `smallGroupExcludeOfficialBots` | `true` | 统计群人数时排除 QQ 官方机器人（`is_robot`）及机器人自身，仅统计真人成员 |
+| `smallGroupRealtimeMonitor` | `true` | 实时监控群人数：监听成员退群事件，群缩小到阈值以下时自动退群（仅监控未经审核拉入的群） |
+| `smallGroupRecheckCooldown` | `60` | 实时监控时同一群两次复检的最小间隔（秒），避免成员批量退群时频繁调用接口 |
 | `smallGroupQuitMessage` | *(见配置)* | 退群提示，支持 `{memberCount}`, `{threshold}`, `{groupName}`, `{groupId}` |
 | `smallGroupNotifyAdmin` | `true` | 自动退群时通知管理员 |
 | `smallGroupCheckDelay` | `3000` | 加入后延迟检测的时间（毫秒） |
@@ -86,6 +91,9 @@ Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
 |--------|--------|------|
 | `notifyAdminOnMute` | `false` | bot 被禁言时通知管理员 |
 | `muteNotificationMessage` | *(见配置)* | 通知消息模板，支持 `{groupId}`, `{groupName}`, `{operatorId}`, `{duration}` |
+| `muteAutoQuit` | `false` | bot 被禁言达到阈值时自动退群并拉黑 |
+| `muteAutoQuitThreshold` | `600` | 触发自动退群的禁言时长阈值（秒），被禁言时长 ≥ 此值即退群并拉黑 |
+| `muteQuitNotificationMessage` | *(见配置)* | 自动退群时发给管理员的通知模板，支持 `{groupId}`, `{groupName}`, `{operatorId}`, `{duration}` |
 
 ### 频率控制
 
@@ -174,12 +182,16 @@ Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
 | `gc.sg-add <群号>` | 将群加入小群白名单，不受人数限制 |
 | `gc.sg-rm <群号>` | 从小群白名单移除群 |
 | `gc.sg-list` | 查看小群白名单 |
+| `gc.friends` | 列出机器人的好友（合并转发形式发送） |
+| `gc.delfriend <QQ号>` | 删除指定好友 |
+| `gc.groups` | 列出机器人所在的群（合并转发形式发送） |
+| `gc.leave <群号>` | 让机器人退出指定群 |
 | `gc.approve <群号>` | 同意加入指定群 |
 | `gc.reject <群号>` | 拒绝加入指定群 |
 | `gc.pending` | 查看待处理的群聊邀请列表 |
-| `gc.fa <QQ号>` | 同意好友申请 |
-| `gc.fr <QQ号>` | 拒绝好友申请 |
-| `gc.fp` | 查看待处理的好友申请列表 |
+| `gc.friend-approve <QQ号>` | 同意好友申请（兼容别名：`gc.fa`） |
+| `gc.friend-reject <QQ号>` | 拒绝好友申请（兼容别名：`gc.fr`） |
+| `gc.friend-pending` | 查看待处理的好友申请列表（兼容别名：`gc.fp`） |
 
 ### 群聊管理
 
@@ -197,3 +209,5 @@ Koishi 插件，多功能群聊自管理工具。仅支持 OneBot 适配器。
 - 管理员通知依赖 `admin.adminQQs` 或 `admin.notificationGroupId` 的配置，未配置则无法收到通知
 - 频率控制的非指令拦截（@ 对话、私聊）不影响入群欢迎等系统事件
 - 小群合格通知仅在启用了 `smallGroupAutoQuit` 且未经 `gc.approve` 审核通过的情况下触发
+- **小群人数统计**：开启 `smallGroupExcludeOfficialBots` 后只计真人成员（排除 `is_robot` 机器人与自身）。检测做了分级短路以减少接口调用——原始人数 ≤ 阈值直接退群、原始人数 > 阈值 + 20（单群机器人上限）直接保留，仅当人数处于中间区间时才拉取一次成员列表，且统计到足够机器人即提前结束遍历
+- **实时小群监控**：纯事件驱动（仅监听成员退群），不做轮询，配合 per-群冷却限流，几乎不增加接口压力。**经 `gc.approve` 审核通过或在小群白名单中的群永久豁免**，仅监控未经审核被拉入的群；机器人退出某群后其审核标记自动清除，若日后被未经审核地重新拉入会重新接受检测

package/lib/config.d.ts

@@ -1,82 +0,0 @@
-import { Schema } from 'koishi';
-export interface GroupConfig {
-    welcomeMessage: string;
-    quitMessage: string;
-    quitCommandEnabled: boolean;
-    enableBlacklist: boolean;
-    blacklistMessage: string;
-    notifyAdminOnKick: boolean;
-    kickNotificationMessage: string;
-    smallGroupAutoQuit: boolean;
-    smallGroupThreshold: number;
-    smallGroupQuitMessage: string;
-    smallGroupNotifyAdmin: boolean;
-    smallGroupCheckDelay: number;
-    smallGroupQualifiedNotifyAdmin: boolean;
-    smallGroupQualifiedMessage: string;
-    notifyAdminOnMute: boolean;
-    muteNotificationMessage: string;
-}
-export interface AdminConfig {
-    adminQQs: string[];
-    notificationGroupId: string;
-}
-export interface GroupInviteConfig {
-    enabled: boolean;
-    inviteWaitMessage: string;
-    inviteRequestMessage: string;
-    autoApprove: boolean;
-    notifyAdminOnApprove: boolean;
-    inviteApproveMessage: string;
-    inviteApproveNotificationMessage: string;
-    showDetailedLog: boolean;
-    inviteExpireDays: number;
-}
-export interface FrequencyConfig {
-    enabled: boolean;
-    limit: number;
-    window: number;
-    warnDelay: number;
-    blockDur: number;
-    whitelist: string[];
-    privateEnabled: boolean;
-    privateLimit: number;
-    privateWindow: number;
-    privateWarnDelay: number;
-    privateBlockDur: number;
-    privateWhitelist: string[];
-    blockExpBase: number;
-    blockExpWindow: number;
-    blockNotifyCooldown: number;
-    warnMsg: string;
-    blockMsg: string;
-    blockedMsg: string;
-}
-export interface FriendConfig {
-    enabled: boolean;
-    autoApprove: boolean;
-    notifyAdminOnApprove: boolean;
-    requestExpireDays: number;
-    requestMessage: string;
-    approveNotificationMessage: string;
-}
-export interface BotSwitchConfig {
-    enabled: boolean;
-    defaultState: boolean;
-    disabledMessage: string;
-}
-export interface PermissionConfig {
-    mode: 'koishi' | 'builtin';
-    koishiAuthority: number;
-    protectedCommands: string[];
-}
-export interface Config {
-    admin: AdminConfig;
-    permission: PermissionConfig;
-    basic: GroupConfig;
-    invite: GroupInviteConfig;
-    friend: FriendConfig;
-    frequency: FrequencyConfig;
-    botSwitch: BotSwitchConfig;
-}
-export declare const Config: Schema<Config>;

package/lib/database.d.ts

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