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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-group-control",
   "description": "Koishi 插件，一个多功能的群聊自管理工具。支持被踢出自动拉黑、刷屏自动屏蔽、开关控制等功能。(仅支持 OneBot 适配器)",
-  "version": "0.2.12",
+  "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 协助完成