koishi-plugin-group-control 0.2.11 → 1.0.0-alpha.0

package/lib/config.d.ts

@@ -21,6 +21,7 @@ export interface GroupInviteConfig {
     inviteRequestMessage: string;
     autoApprove: boolean;
     showDetailedLog: boolean;
+    inviteExpireDays: number;
 }
 export interface FrequencyConfig {
     enabled: boolean;

package/lib/database.d.ts

@@ -23,12 +23,22 @@ export interface SmallGroupWhitelist {
     platform: string;
     guildId: string;
 }
+export interface PendingInvite {
+    platform: string;
+    groupId: string;
+    userId: string;
+    userName: string;
+    groupName: string;
+    time: number;
+    flag: string;
+}
 declare module 'koishi' {
     interface Tables {
         blacklisted_guild: BlacklistedGuild;
         command_frequency_record: CommandFrequencyRecord;
         group_bot_status: GroupBotStatus;
         small_group_whitelist: SmallGroupWhitelist;
+        pending_invite: PendingInvite;
     }
 }
 export declare const name = "group-control-database";
@@ -47,3 +57,8 @@ export declare function isInSmallGroupWhitelist(ctx: Context, guildId: string):
 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>;

package/lib/index.js

@@ -30,19 +30,24 @@ module.exports = __toCommonJS(src_exports);
 var database_exports = {};
 __export(database_exports, {
   BLACKLIST_PLATFORM: () => BLACKLIST_PLATFORM,
+  addPendingInvite: () => addPendingInvite,
   addToSmallGroupWhitelist: () => addToSmallGroupWhitelist,
   apply: () => apply,
   clearBlacklistedGuilds: () => clearBlacklistedGuilds,
+  clearExpiredPendingInvites: () => clearExpiredPendingInvites,
   createBlacklistedGuild: () => createBlacklistedGuild,
   getAllBlacklistedGuilds: () => getAllBlacklistedGuilds,
+  getAllPendingInvites: () => getAllPendingInvites,
   getAllSmallGroupWhitelist: () => getAllSmallGroupWhitelist,
   getBlacklistedGuild: () => getBlacklistedGuild,
   getCommandFrequencyRecord: () => getCommandFrequencyRecord,
   getGroupBotStatus: () => getGroupBotStatus,
+  getPendingInvite: () => getPendingInvite,
   isInSmallGroupWhitelist: () => isInSmallGroupWhitelist,
   name: () => name,
   removeBlacklistedGuild: () => removeBlacklistedGuild,
   removeFromSmallGroupWhitelist: () => removeFromSmallGroupWhitelist,
+  removePendingInvite: () => removePendingInvite,
   setGroupBotStatus: () => setGroupBotStatus,
   updateCommandFrequencyRecord: () => updateCommandFrequencyRecord
 });
@@ -72,6 +77,15 @@ function apply(ctx) {
     platform: "string",
     guildId: "string"
   }, { primary: ["platform", "guildId"] });
+  ctx.model.extend("pending_invite", {
+    platform: "string",
+    groupId: "string",
+    userId: "string",
+    userName: "string",
+    groupName: "string",
+    time: "integer",
+    flag: "string"
+  }, { primary: ["platform", "groupId"] });
 }
 __name(apply, "apply");
 var BLACKLIST_PLATFORM = "onebot";
@@ -139,6 +153,33 @@ async function getAllSmallGroupWhitelist(ctx) {
   return await ctx.model.get("small_group_whitelist", { platform: BLACKLIST_PLATFORM });
 }
 __name(getAllSmallGroupWhitelist, "getAllSmallGroupWhitelist");
+async function getPendingInvite(ctx, groupId) {
+  const records = await ctx.model.get("pending_invite", { platform: BLACKLIST_PLATFORM, groupId });
+  return records.length > 0 ? records[0] : null;
+}
+__name(getPendingInvite, "getPendingInvite");
+async function addPendingInvite(ctx, inviteUser) {
+  await ctx.model.upsert("pending_invite", [{ platform: BLACKLIST_PLATFORM, ...inviteUser }]);
+}
+__name(addPendingInvite, "addPendingInvite");
+async function removePendingInvite(ctx, groupId) {
+  await ctx.model.remove("pending_invite", { platform: BLACKLIST_PLATFORM, groupId });
+}
+__name(removePendingInvite, "removePendingInvite");
+async function getAllPendingInvites(ctx) {
+  return await ctx.model.get("pending_invite", { platform: BLACKLIST_PLATFORM });
+}
+__name(getAllPendingInvites, "getAllPendingInvites");
+async function clearExpiredPendingInvites(ctx, expireTimeMs) {
+  const cutoff = Date.now() - expireTimeMs;
+  const all = await ctx.model.get("pending_invite", { platform: BLACKLIST_PLATFORM });
+  const expired = all.filter((r) => r.time < cutoff);
+  for (const record of expired) {
+    await ctx.model.remove("pending_invite", { platform: BLACKLIST_PLATFORM, groupId: record.groupId });
+  }
+  return expired.length;
+}
+__name(clearExpiredPendingInvites, "clearExpiredPendingInvites");
 
 // src/modules/basic.ts
 var basic_exports = {};
@@ -183,6 +224,9 @@ async function notifyAdmins(bot, config, message) {
 }
 __name(notifyAdmins, "notifyAdmins");
 async function hasPermission(session, config) {
+  if (config.invite.adminQQs?.includes(session.userId)) {
+    return true;
+  }
   if (config.permission.mode === "koishi") {
     try {
       const user = session.user;
@@ -194,9 +238,6 @@ async function hasPermission(session, config) {
     return false;
   }
   const userId = session.userId;
-  if (config.invite.adminQQs?.includes(userId)) {
-    return true;
-  }
   try {
     const member = await session.bot.getGuildMember(session.guildId, userId);
     const roles = member?.roles || member?.role;
@@ -223,20 +264,31 @@ async function hasPermission(session, config) {
   return false;
 }
 __name(hasPermission, "hasPermission");
+function isGlobalAdmin(session, config) {
+  if (config.invite.adminQQs?.includes(session.userId)) {
+    return true;
+  }
+  const user = session.user;
+  if (config.permission.mode === "koishi" && user && typeof user.authority === "number") {
+    return user.authority >= 4;
+  }
+  return false;
+}
+__name(isGlobalAdmin, "isGlobalAdmin");
 var ADMIN_COMMANDS = /* @__PURE__ */ new Set([
   "bot-on",
   "bot-off",
   "quit",
-  "view-blacklist",
-  "remove-from-blacklist",
-  "add-to-blacklist",
-  "clear-blacklist",
+  "banlist",
+  "unban",
+  "ban",
+  "clearban",
   "approve",
   "reject",
-  "pending-invites",
-  "allow-small-group",
-  "disallow-small-group",
-  "view-small-group-whitelist"
+  "pending",
+  "sg-add",
+  "sg-rm",
+  "sg-list"
 ]);
 
 // src/state.ts
@@ -427,19 +479,17 @@ __export(invite_exports, {
 var name3 = "group-control-invite";
 function apply3(ctx, config) {
   if (!config.invite.enabled) return;
-  const pendingInvites = /* @__PURE__ */ new Map();
-  const INVITE_TIMEOUT = 10 * 60 * 1e3;
-  setInterval(() => {
-    const now = Date.now();
-    for (const [key, invite] of pendingInvites) {
-      if (now - invite.time > INVITE_TIMEOUT) {
-        pendingInvites.delete(key);
-        if (config.invite.showDetailedLog) {
-          console.log(`邀请超时已清理: 群号=${invite.groupId}, 邀请者=${invite.userId}`);
-        }
+  setInterval(async () => {
+    const expireMs = config.invite.inviteExpireDays * 24 * 60 * 60 * 1e3;
+    try {
+      const count = await clearExpiredPendingInvites(ctx, expireMs);
+      if (count > 0 && config.invite.showDetailedLog) {
+        console.log(`已自动清理 ${count} 个过期邀请`);
       }
+    } catch (error) {
+      console.error("清理过期邀请失败:", error);
     }
-  }, 60 * 1e3);
+  }, 60 * 60 * 1e3);
   ctx.on("guild-request", async (session) => {
     const raw = session.original || session.raw || session.event?._data || {};
     const flag = raw.flag || session.flag || session.messageId;
@@ -486,7 +536,7 @@ function apply3(ctx, config) {
       }
       return;
     }
-    pendingInvites.set(rawGroupId, {
+    await addPendingInvite(ctx, {
       groupId: rawGroupId,
       userId: rawUserId,
       userName,
@@ -524,14 +574,15 @@ function apply3(ctx, config) {
       console.warn("群邀请请求发送失败：未配置通知群且管理员私聊发送失败");
     }
   });
-  ctx.command("approve <groupId:string>", "同意群聊邀请", { authority: 4 }).action(async ({ session }, groupId) => {
+  ctx.command("approve <groupId:string>", "同意群聊邀请").action(async ({ session }, groupId) => {
     if (!groupId) return "请指定群号。用法：approve <群号>";
     if (!config.invite.adminQQs.includes(session.userId)) {
       return "权限不足，只有管理员可以审核邀请。";
     }
-    const inviteData = pendingInvites.get(groupId);
+    const inviteData = await getPendingInvite(ctx, groupId);
     if (!inviteData) {
-      return `未找到群号 ${groupId} 的待处理邀请。当前待处理邀请：${pendingInvites.size > 0 ? Array.from(pendingInvites.values()).map((i) => `${i.groupId}(${i.groupName})`).join(", ") : "无"}`;
+      const allInvites = await getAllPendingInvites(ctx);
+      return `未找到群号 ${groupId} 的待处理邀请。当前待处理邀请：${allInvites.length > 0 ? allInvites.map((i) => `${i.groupId}(${i.groupName})`).join(", ") : "无"}`;
     }
     try {
       await session.bot.internal.setGroupAddRequest(inviteData.flag, "invite", true, "");
@@ -541,21 +592,22 @@ function apply3(ctx, config) {
       } catch (error) {
         console.error("通知邀请者失败:", error);
       }
-      pendingInvites.delete(groupId);
+      await removePendingInvite(ctx, groupId);
       return `已同意加入群 ${groupId}（${inviteData.groupName}），邀请者：${inviteData.userName}`;
     } catch (error) {
       console.error("处理同意邀请失败:", error);
       return `处理同意邀请失败: ${error.message}`;
     }
   });
-  ctx.command("reject <groupId:string>", "拒绝群聊邀请", { authority: 4 }).action(async ({ session }, groupId) => {
+  ctx.command("reject <groupId:string>", "拒绝群聊邀请").action(async ({ session }, groupId) => {
     if (!groupId) return "请指定群号。用法：reject <群号>";
     if (!config.invite.adminQQs.includes(session.userId)) {
       return "权限不足，只有管理员可以审核邀请。";
     }
-    const inviteData = pendingInvites.get(groupId);
+    const inviteData = await getPendingInvite(ctx, groupId);
     if (!inviteData) {
-      return `未找到群号 ${groupId} 的待处理邀请。当前待处理邀请：${pendingInvites.size > 0 ? Array.from(pendingInvites.values()).map((i) => `${i.groupId}(${i.groupName})`).join(", ") : "无"}`;
+      const allInvites = await getAllPendingInvites(ctx);
+      return `未找到群号 ${groupId} 的待处理邀请。当前待处理邀请：${allInvites.length > 0 ? allInvites.map((i) => `${i.groupId}(${i.groupName})`).join(", ") : "无"}`;
     }
     try {
       await session.bot.internal.setGroupAddRequest(inviteData.flag, "invite", false, "已拒绝");
@@ -564,22 +616,23 @@ function apply3(ctx, config) {
       } catch (error) {
         console.error("通知邀请者失败:", error);
       }
-      pendingInvites.delete(groupId);
+      await removePendingInvite(ctx, groupId);
       return `已拒绝加入群 ${groupId}（${inviteData.groupName}），邀请者：${inviteData.userName}`;
     } catch (error) {
       console.error("处理拒绝邀请失败:", error);
       return `处理拒绝邀请失败: ${error.message}`;
     }
   });
-  ctx.command("pending-invites", "查看待处理的群聊邀请", { authority: 4 }).action(async ({ session }) => {
+  ctx.command("pending", "查看待处理的群聊邀请").action(async ({ session }) => {
     if (!config.invite.adminQQs.includes(session.userId)) {
       return "权限不足，只有管理员可以查看待处理邀请。";
     }
-    if (pendingInvites.size === 0) {
+    const allInvites = await getAllPendingInvites(ctx);
+    if (allInvites.length === 0) {
       return "当前没有待处理的群聊邀请。";
     }
     const lines = ["待处理的群聊邀请列表："];
-    for (const [, invite] of pendingInvites) {
+    for (const invite of allInvites) {
       const elapsed = Math.floor((Date.now() - invite.time) / 1e3 / 60);
       lines.push(`- 群：${invite.groupName}（${invite.groupId}）`);
       lines.push(`  邀请者：${invite.userName}（${invite.userId}）`);
@@ -673,7 +726,8 @@ __export(commands_exports, {
 });
 var name5 = "group-control-commands";
 function apply5(ctx, config) {
-  async function viewBlacklist() {
+  async function viewBlacklist({ session }) {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const errorMsg = isBlacklistEnabled(config.basic);
     if (errorMsg) return errorMsg;
     const records = await getAllBlacklistedGuilds(ctx);
@@ -681,8 +735,9 @@ function apply5(ctx, config) {
     return "黑名单列表：\n" + records.map((r) => `- ${r.guildId} (时间: ${formatDate(r.timestamp)})`).join("\n");
   }
   __name(viewBlacklist, "viewBlacklist");
-  ctx.command("view-blacklist", "查看被拉黑的群聊列表", { authority: 4 }).action(viewBlacklist);
-  async function removeFromBlacklist({}, input) {
+  ctx.command("banlist", "查看被拉黑的群聊列表").action(viewBlacklist);
+  async function removeFromBlacklist({ session }, input) {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const errorMsg = isBlacklistEnabled(config.basic);
     if (errorMsg) return errorMsg;
     const guildId = parseGuildId(input);
@@ -691,8 +746,9 @@ function apply5(ctx, config) {
     return removed ? `已移除群聊 ${guildId}` : `群聊 ${guildId} 不在黑名单中。`;
   }
   __name(removeFromBlacklist, "removeFromBlacklist");
-  ctx.command("remove-from-blacklist <groupId:text>", "从黑名单移除指定群聊", { authority: 4 }).action(removeFromBlacklist);
-  async function addToBlacklist({}, input) {
+  ctx.command("unban <groupId:text>", "从黑名单移除指定群聊").action(removeFromBlacklist);
+  async function addToBlacklist({ session }, input) {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const errorMsg = isBlacklistEnabled(config.basic);
     if (errorMsg) return errorMsg;
     const guildId = parseGuildId(input);
@@ -703,8 +759,9 @@ function apply5(ctx, config) {
     return `已添加群聊 ${guildId} 到黑名单。`;
   }
   __name(addToBlacklist, "addToBlacklist");
-  ctx.command("add-to-blacklist <groupId:text>", "手动添加群聊到黑名单", { authority: 4 }).action(addToBlacklist);
-  async function clearBlacklist() {
+  ctx.command("ban <groupId:text>", "手动添加群聊到黑名单").action(addToBlacklist);
+  async function clearBlacklist({ session }) {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const errorMsg = isBlacklistEnabled(config.basic);
     if (errorMsg) return errorMsg;
     const records = await getAllBlacklistedGuilds(ctx);
@@ -713,8 +770,9 @@ function apply5(ctx, config) {
     return `已清空黑名单，共移除 ${records.length} 个群聊。`;
   }
   __name(clearBlacklist, "clearBlacklist");
-  ctx.command("clear-blacklist", "清空黑名单", { authority: 4 }).action(clearBlacklist);
-  ctx.command("allow-small-group <groupId:text>", "解除指定群聊的小群人数限制", { authority: 4 }).action(async ({}, input) => {
+  ctx.command("clearban", "清空黑名单").action(clearBlacklist);
+  ctx.command("sg-add <groupId:text>", "解除指定群聊的小群人数限制").action(async ({ session }, input) => {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const guildId = parseGuildId(input);
     if (!guildId) return "输入格式错误，请输入群号。";
     const exists = await isInSmallGroupWhitelist(ctx, guildId);
@@ -722,7 +780,8 @@ function apply5(ctx, config) {
     await addToSmallGroupWhitelist(ctx, guildId);
     return `已将群聊 ${guildId} 加入小群白名单，该群不再受小群人数限制。`;
   });
-  ctx.command("disallow-small-group <groupId:text>", "恢复指定群聊的小群人数限制", { authority: 4 }).action(async ({}, input) => {
+  ctx.command("sg-rm <groupId:text>", "恢复指定群聊的小群人数限制").action(async ({ session }, input) => {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const guildId = parseGuildId(input);
     if (!guildId) return "输入格式错误，请输入群号。";
     const exists = await isInSmallGroupWhitelist(ctx, guildId);
@@ -730,7 +789,8 @@ function apply5(ctx, config) {
     await removeFromSmallGroupWhitelist(ctx, guildId);
     return `已将群聊 ${guildId} 从小群白名单移除，该群将恢复小群人数限制。`;
   });
-  ctx.command("view-small-group-whitelist", "查看小群白名单", { authority: 4 }).action(async () => {
+  ctx.command("sg-list", "查看小群白名单").action(async ({ session }) => {
+    if (!isGlobalAdmin(session, config)) return "权限不足，只有全局管理员可以执行此操作。";
     const records = await getAllSmallGroupWhitelist(ctx);
     if (records.length === 0) return "小群白名单为空。";
     return "小群白名单列表（以下群不受小群人数限制）：\n" + records.map((r) => `- ${r.guildId}`).join("\n");
@@ -871,7 +931,8 @@ var Config = import_koishi.Schema.intersect([
       inviteWaitMessage: import_koishi.Schema.string().default("已收到您的群聊邀请，正在等待管理员审核，请耐心等待。").description("发送给邀请者的等待审核提示消息"),
       inviteRequestMessage: import_koishi.Schema.string().default("收到新的群聊邀请请求：\n群名称：{groupName}\n群号：{groupId}\n邀请者：{userName} (QQ: {userId})\n\n请管理员使用指令 approve {groupId} 同意或 reject {groupId} 拒绝。").description("发送给管理员的邀请请求消息模板，支持变量{groupName}, {groupId}, {userName}, {userId}"),
       autoApprove: import_koishi.Schema.boolean().default(false).description("是否自动同意邀请（仅在没有指定管理员时）"),
-      showDetailedLog: import_koishi.Schema.boolean().default(false).description("是否显示详细日志")
+      showDetailedLog: import_koishi.Schema.boolean().default(false).description("是否显示详细日志"),
+      inviteExpireDays: import_koishi.Schema.number().default(3).description("邀请记录过期时间（天），超过此时间未处理的邀请将被自动清理")
     }).description("群聊邀请审核")
   }),
   import_koishi.Schema.object({

package/lib/utils.d.ts

@@ -10,5 +10,10 @@ export declare function notifyAdmins(bot: any, config: Config, message: string):
  * - builtin 模式: 检查用户是否为群管理员/群主，或在管理员QQ列表中
  */
 export declare function hasPermission(session: Session, config: Config): Promise<boolean>;
+/**
+ * 检查当前用户是否拥有全局管理权限
+ * （供独立于群聊的全局指令（如黑名单、白名单）使用）
+ */
+export declare function isGlobalAdmin(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": "0.2.11",
+  "version": "1.0.0-alpha.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -0,0 +1,208 @@
+# 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 4.6 协助完成
+
+---
+
+## 功能概览
+
+- **黑名单管理**：被踢出群后自动拉黑，下次被邀请时自动退出
+- **小群自动退群**：加入人数不足的群时自动退出并通知管理员
+- **合格小群通知**：未经审核被拉入人数达标的群时，通知管理员确认
+- **群聊邀请审核**：收到邀请时暂缓加入，等待管理员 approve/reject
+- **好友申请管理**：收到好友申请时通知管理员，或自动通过
+- **频率控制**：限制群聊/私聊的指令及对话频率，支持指数增长屏蔽时长
+- **Bot 开关**：按群独立开关 bot，关闭后屏蔽所有响应
+- **被禁言通知**：bot 被禁言时可选通知管理员
+- **权限管理**：支持 Koishi authority 或内置群管理员两种权限模式
+
+---
+
+## 配置说明
+
+### 权限管理
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `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}` |
+| `approvedUserMessage` | `你的好友申请已通过审核。` | 同意申请后发给对方的消息 |
+
+### 群聊邀请审核
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `false` | 启用邀请审核 |
+| `adminQQs` | `[]` | 管理员QQ号列表，用于权限验证及私聊通知 |
+| `notificationGroupId` | *(空)* | 通知群号，填写后邀请请求发到此群，否则私聊管理员 |
+| `inviteWaitMessage` | *(见配置)* | 发给邀请者的等待提示 |
+| `inviteRequestMessage` | *(见配置)* | 发给管理员的请求消息，支持 `{groupName}`, `{groupId}`, `{userName}`, `{userId}` |
+| `autoApprove` | `false` | 未配置管理员时自动同意邀请 |
+| `showDetailedLog` | `false` | 显示详细日志 |
+| `inviteExpireDays` | `3` | 邀请记录过期天数 |
+
+### 机器人开关
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `true` | 启用群聊 bot 开关功能 |
+| `defaultState` | `true` | 默认开启状态 |
+| `disabledMessage` | *(见配置)* | 关闭状态下被 @ 时的提示 |
+
+---
+
+## 指令列表
+
+### 黑名单管理（需全局管理员）
+
+| 指令 | 说明 |
+|------|------|
+| `banlist` | 查看黑名单列表 |
+| `ban <群号>` | 手动添加群到黑名单 |
+| `unban <群号>` | 从黑名单移除群 |
+| `clearban` | 清空黑名单 |
+
+### 小群白名单（需全局管理员）
+
+| 指令 | 说明 |
+|------|------|
+| `sg-add <群号>` | 将群加入小群白名单，不受人数限制 |
+| `sg-rm <群号>` | 从小群白名单移除群 |
+| `sg-list` | 查看小群白名单 |
+
+### 好友申请管理（需在 adminQQs 中）
+
+| 指令 | 说明 |
+|------|------|
+| `friend-pending` | 查看待处理的好友申请列表 |
+| `friend-approve <QQ号>` | 同意指定用户的好友申请 |
+| `friend-reject <QQ号>` | 拒绝指定用户的好友申请 |
+
+### 邀请审核（需在 adminQQs 中）
+
+| 指令 | 说明 |
+|------|------|
+| `pending` | 查看待处理的邀请列表 |
+| `approve <群号>` | 同意加入指定群 |
+| `reject <群号>` | 拒绝加入指定群 |
+
+### 群聊管理
+
+| 指令 | 说明 | 权限 |
+|------|------|------|
+| `quit` | 让 bot 退出当前群聊 | 群管理员 |
+| `bot-on` | 开启当前群的 bot | 群管理员 |
+| `bot-off` | 关闭当前群的 bot | 群管理员 |
+
+---
+
+## 注意事项
+
+- 本插件仅支持 **OneBot 适配器**（如 go-cqhttp、LLOneBot 等）
+- 管理员通知依赖 `invite.adminQQs` 或 `invite.notificationGroupId` 的配置，未配置则无法收到通知
+- 频率控制的非指令拦截（@ 对话、私聊）不影响入群欢迎等系统事件
+- 小群合格通知仅在启用了 `smallGroupAutoQuit` 且未经 `approve` 审核通过的情况下触发

package/README.md

@@ -1,9 +0,0 @@
-# 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 适配器)
-
-#### 仅支持 OneBot 协议
-
-> 使用 Qwen3-Coder & Gemini-3.1-Pro-Preview 协助完成