@hambur/koishi-plugin-auto-kick/readme.md

自动踢出黑名单用户的群管理插件

# Auto-kick - 智能群管理插件

![Koishi](https://img.shields.io/badge/Koishi-v4+-blue.svg)
![Node.js](https://img.shields.io/badge/Node.js-16+-green.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-4.7+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)

一个智能的 Koishi 群管理插件，支持自动踢出黑名单用户，特别针对用户进群后改名违规的行为进行检测。

## ✨ 主要特性

### 🎯 双重黑名单机制
- **QQ号黑名单**：直接通过QQ号识别和踢出指定用户
- **昵称关键词黑名单**：通过昵称关键词防止用户冒充群主、管理员等

### ⏰ 智能延迟检查
- **进群后昵称检查**：新用户进群5分钟后自动检查昵称是否变更
- **防改名违规**：有效防止用户进群后修改昵称为违规内容
- **单次检查机制**：每个用户只检查一次，避免重复处理

### ⚡ 高性能设计
- **O(1)查找算法**：使用Set数据结构，确保大规模黑名单下的高效查找
- **批量处理**：支持批量扫描群成员，适用于大群管理
- **并发控制**：智能并发控制，避免API调用过于频繁
- **错误重试**：自动重试机制，提高操作成功率

### 🛡️ 可靠性保障
- **踢人结果验证**：踢人后自动验证用户是否真的被踢出
- **权限检测**：自动检测机器人权限，提醒权限不足
- **详细日志**：提供清晰的操作日志，便于问题排查

## 📦 安装方法

### 方法一：通过 npm 安装（推荐）
```bash
npm install koishi-plugin-auto-kick
```

### 方法二：通过 Koishi 控制台安装
1. 进入 Koishi 控制台
2. 在插件市场搜索 "auto-kick"
3. 点击安装并启用

### 方法三：手动安装
1. 下载插件源码到 `external/auto-kick` 目录
2. 在控制台中启用插件

## ⚙️ 配置说明

### 基础配置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `blacklist` | `string[]` | `[]` | QQ号黑名单列表 |
| `nicknameBlacklist` | `string[]` | `[]` | 昵称关键词黑名单列表 |
| `enableJoinScan` | `boolean` | `true` | 机器人进群时扫描现有成员 |
| `enableMemberJoin` | `boolean` | `true` | 监听新成员加入事件 |
| `enableDelayedNicknameCheck` | `boolean` | `true` | 新成员加入后延迟检查昵称变更 |
| `delayedCheckTime` | `number` | `300000` | 延迟检查时间(毫秒) |
| `notifyAdmins` | `boolean` | `false` | 是否通知管理员 |
| `logLevel` | `string` | `'info'` | 日志级别 |

### 性能优化配置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `scanDelay` | `number` | `5000` | 机器人进群后延迟扫描时间(ms) |
| `batchSize` | `number` | `50` | 批量处理成员数量 |
| `maxConcurrent` | `number` | `3` | 最大并发踢人数量 |
| `kickDelay` | `number` | `2000` | 踢人操作间隔(ms) |
| `retryAttempts` | `number` | `3` | 失败重试次数 |

### 高级功能配置

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `verifyKickResult` | `boolean` | `true` | 验证踢人结果 |
| `verifyDelay` | `number` | `2000` | 踢人后验证延迟(ms) |
| `verifyTimeout` | `number` | `10000` | 验证超时时间(ms) |
| `nicknameMatchMode` | `string` | `'contains'` | 昵称匹配模式 |
| `skipBotMembers` | `boolean` | `true` | 跳过机器人成员 |

## 🚀 使用方法

### 1. 基础防护配置

```yaml
plugins:
  auto-kick:
    # QQ号黑名单
    blacklist:
      - "123456789"
      - "987654321"

    # 昵称关键词黑名单
    nicknameBlacklist:
      - "群主"
      - "管理员"
      - "群管"

    # 启用延迟检查（防改名）
    enableDelayedNicknameCheck: true
    delayedCheckTime: 300000  # 5分钟

    # 启用踢人验证
    verifyKickResult: true
```

### 2. 群组过滤器设置

```yaml
plugins:
  auto-kick:
    # 插件配置...
    filter:
      guild:
        - "876886091"  # 要监控的群号
        - "123456789"  # 可以添加多个群
```

### 3. 昵称匹配模式

#### 包含匹配模式（推荐）
```yaml
nicknameMatchMode: "contains"
nicknameBlacklist:
  - "群主"      # 匹配包含"群主"的昵称
  - "管理员"    # 匹配包含"管理员"的昵称
```

#### 正则表达式模式
```yaml
nicknameMatchMode: "regex"
nicknameBlacklist:
  - "^群主.*$"    # 匹配以"群主"开头的昵称
  - ".*管理.*"    # 匹配包含"管理"的昵称
```

## 📋 配置示例

### 示例1：基础防冒充配置
```yaml
plugins:
  auto-kick:
    # 防止冒充群主和管理员
    nicknameBlacklist:
      - "群主"
      - "管理员"
      - "群管"

    # 启用延迟检查
    enableDelayedNicknameCheck: true
    delayedCheckTime: 300000  # 5分钟

    # 基础设置
    enableJoinScan: true
    enableMemberJoin: true
    verifyKickResult: true

    # 群组过滤
    filter:
      guild:
        - "876886091"
```

### 示例2：大群高性能配置
```yaml
plugins:
  auto-kick:
    # 黑名单配置
    blacklist:
      - "123456789"
    nicknameBlacklist:
      - "群主"
      - "管理员"

    # 延迟检查设置
    enableDelayedNicknameCheck: true
    delayedCheckTime: 600000  # 10分钟（给大群更多时间）

    # 性能优化（适用于大群）
    batchSize: 100
    maxConcurrent: 5
    kickDelay: 1000
    scanDelay: 3000

    # 启用验证
    verifyKickResult: true
    verifyDelay: 3000

    # 通知设置
    notifyAdmins: true
    adminNotifyMessage: "⚠️ 检测到黑名单用户 {user}，原因：{reason}"
```

### 示例3：正则表达式高级配置
```yaml
plugins:
  auto-kick:
    # 正则表达式匹配
    nicknameMatchMode: "regex"
    nicknameBlacklist:
      - "^群主.*$"        # 以"群主"开头
      - ".*管理.*"        # 包含"管理"
      - "^[0-9]+$"        # 纯数字昵称
      - "[ღ♥♡❤]"         # 特殊符号

    # 延迟检查
    enableDelayedNicknameCheck: true
    delayedCheckTime: 180000  # 3分钟

    # 验证设置
    verifyKickResult: true
    retryAttempts: 5
```

## 🔧 工作原理

### 核心检测流程

```
新用户进群
    ↓
立即检查当前昵称
    ├─ 违规 → 立即踢出
    └─ 正常 → 缓存昵称，设置延迟检查
              ↓
          等待5分钟
              ↓
          重新获取昵称
              ↓
          对比昵称变化
              ├─ 未变化 → 结束检查
              └─ 变化且违规 → 踢出用户
```

### 延迟检查机制详解

1. **缓存机制**：
   - 用户进群时缓存初始昵称
   - 设置定时器在指定时间后检查
   - 自动清理过期缓存

2. **昵称对比**：
   - 获取用户当前昵称
   - 与缓存的初始昵称对比
   - 检测到变化时进行黑名单匹配

3. **智能处理**：
   - 每个用户只检查一次
   - 用户离群自动清理缓存
   - 插件重启不影响已设置的检查

### 批量扫描机制

- **机器人进群时**：延迟扫描避免冲突
- **分批处理**：避免一次性处理大量用户
- **并发控制**：限制同时进行的踢人操作
- **性能统计**：记录扫描效率和结果

## 🛠️ 权限要求

### 机器人权限
- **群管理员权限** 或 **踢人权限**
- 建议将机器人设置为管理员以确保功能正常

### 权限检查
插件会在运行时自动检查权限状态：
- ✅ 权限充足：正常运行
- ⚠️ 权限不足：会在群聊中发送提醒

## 📊 日志说明

### 正常运行日志
```
🚀 Auto-kick 插件启动成功
📋 QQ号黑名单: 2 个
👤 昵称关键词: 3 个 [群主, 管理员, 群管]
⚙️ 匹配模式: contains, 验证踢人: ✅
⏰ 延迟昵称检查: ✅ 300秒

👤 新成员加入: 123456
👤 新成员: 张三 (123456)
⏰ 设置用户 123456 延迟昵称检查 (300秒)
```

### 延迟检查日志
```
🔄 检测到用户昵称变更: 123456 "张三" -> "群主"
🎯 变更后的昵称 "群主" 违规 (匹配: 群主)
🎯 发现黑名单用户: 群主 (123456) - 昵称黑名单 (匹配: 群主)
✅ 成功踢出: 群主 (123456) - 昵称黑名单 (匹配: 群主)
```

### 批量扫描日志
```
🔍 开始扫描群 876886091
📊 扫描完成: 检查 156 人, 发现黑名单 1 人, 成功踢出 1 人, 失败 0 人, 耗时 2345ms
```

## ❓ 常见问题

### Q: 为什么要等5分钟才检查昵称变更？
**A:** 原因分析：
- QQ不会主动推送用户昵称变更事件
- 需要通过定时检查来发现昵称变化
- 5分钟是平衡检测效果和性能的最佳时间
- 可以通过 `delayedCheckTime` 配置调整检查间隔

### Q: 延迟检查会影响性能吗？
**A:** 性能影响很小：
- 只对新加入的用户设置检查
- 每个用户只检查一次
- 自动清理过期缓存
- 可以根据群规模调整检查时间

### Q: 如果用户在检查前就离群了怎么办？
**A:** 插件有完善的处理机制：
- 检查时会先验证用户是否还在群里
- 用户离群会自动清理相关缓存
- 不会对已离群的用户进行无效操作

### Q: 可以检测群名片变更吗？
**A:** 当前版本专注于QQ昵称检测：
- 延迟检查针对的是用户QQ昵称变更
- 群名片变更需要依赖特定的事件支持
- 如需群名片检测，可以考虑后续版本添加

### Q: 如何防止误踢正常用户？
**A:** 建议措施：
- 仔细配置昵称关键词，避免过于宽泛
- 使用正则表达式进行精确匹配
- 启用管理员通知功能
- 定期检查和调整黑名单配置
- 测试关键词匹配效果

### Q: 延迟检查时间可以设置多长？
**A:** 时间配置建议：
- **最短建议**：180秒（3分钟）
- **默认设置**：300秒（5分钟）
- **大群建议**：600秒（10分钟）
- **最长建议**：不超过1800秒（30分钟）

## 🔧 技术细节

### 架构设计
```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Koishi Core   │ → │   Auto-kick      │ → │  BlacklistMgr   │
│                 │    │   Plugin         │    │                 │
│ Event System    │    │                  │    │ O(1) Lookup     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ guild-member    │    │ Nickname Cache   │    │ Delayed Check   │
│ -added Event    │    │ Management       │    │ Timer System    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

### 核心算法
- **黑名单查找**：使用 `Set<string>` 实现 O(1) 时间复杂度
- **昵称匹配**：支持字符串包含和正则表达式两种模式
- **缓存管理**：使用 `Map` 结构管理用户昵称缓存
- **并发控制**：队列机制控制踢人操作并发数

### 性能优化
- **智能批处理**：避免一次性处理大量成员
- **延迟机制**：防止API调用过于频繁
- **内存管理**：自动清理过期缓存和无用数据
- **错误恢复**：完善的重试和异常处理机制

## 📈 版本历史

### v1.1.0 (最新)
- ✅ 新增延迟昵称检查功能
- ✅ 优化昵称获取机制
- ✅ 简化配置和代码结构
- ✅ 移除不必要的成员更新事件监听
- ✅ 提升性能和稳定性

### v1.0.0
- ✅ 基础的QQ号和昵称黑名单功能
- ✅ 高性能批量处理机制
- ✅ 踢人结果验证功能
- ✅ 完善的错误处理和重试

## 🤝 贡献指南

欢迎提交Issue和Pull Request来帮助改进插件！

### 开发环境设置
```bash
# 克隆仓库
git clone <repository-url>

# 安装依赖
npm install

# 构建插件
npm run build

# 运行测试
npm test
```

### 提交规范
- 遵循 [Conventional Commits](https://conventionalcommits.org/) 规范
- 提供详细的测试用例
- 更新相关文档

## 📄 许可证

本项目采用 [MIT License](LICENSE) 许可证。

## 📞 支持与反馈

如果您在使用过程中遇到问题或有建议，请：

1. 查看本文档的常见问题部分
2. 在 GitHub 上提交 Issue
3. 加入 Koishi 官方群组寻求帮助

---

**Auto-kick v2.0** - 智能防护，让群管理更轻松！ 🚀

### 🎯 核心亮点

- **🔍 智能检测**：新用户进群后自动延迟检查昵称变更
- **⚡ 高性能**：针对大群优化，支持批量处理和并发控制
- **🛡️ 可靠性**：踢人验证机制，确保操作真正生效
- **🎛️ 灵活配置**：丰富的配置选项，适应不同群组需求
- **📊 详细日志**：清晰的日志输出，便于监控和调试

让群管理变得更智能、更高效！