koishi-plugin-auto-tata-group-name/readme.md

个人自用,自动更新群聊名称的 Koishi 插件，根据群聊成员数量变化自动更新群名

# koishi-plugin-auto-tata-group-name

一个自动更新群聊名称的 Koishi 插件，可以根据群聊成员数量变化实时更新群名。

## ✨ 功能特性

- 🔄 **自动监听** - 实时监听群聊成员加入/退出事件
- 👥 **多群支持** - 可以同时监听多个群聊
- 🎨 **自定义模板** - 每个群都有独立的名称模板，使用 `{count}` 占位符
- 📊 **人数反转** - 群名中显示的人数为实际人数的倒序（如374人显示为473）
- 🛠️ **手动操作** - 提供便捷的手动更新指令
- 📝 **详细日志** - 完整的操作日志记录

## 📦 安装

```bash
npm install koishi-plugin-auto-tata-group-name
```

## ⚙️ 配置选项

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `guildTemplates` | `GuildConfig[]` | `[]` | 群聊模板配置，配置了就表示监听该群 |
| `updateDelay` | `number` | `2000` | 成员变动后等待平台更新的延迟时间（毫秒，范围：500-10000） |

### GuildConfig 配置结构

```typescript
interface GuildConfig {
  guildId: string      // 群聊ID
  nameTemplate: string // 该群的模板，使用{count}表示人数
}
```

## 🚀 使用方法

### 基础配置

在 Koishi 配置文件中添加：

```yaml
plugins:
  auto-tata-group-name:
    guildTemplates:
      - guildId: "12345678901234567"
        nameTemplate: "({count})🦦獭家一爱相亲相"
      - guildId: "98765432109876543"
        nameTemplate: "({count})🎮游戏群-人数统计"
      - guildId: "11111111111111111"
        nameTemplate: "📚学习群({count}人)"
    updateDelay: 2000  # 等待2秒后获取成员数量
```

### 配置说明

1. **监听规则**：只有在 `guildTemplates` 中配置的群聊才会被监听
2. **模板要求**：每个模板都必须包含 `{count}` 占位符
3. **人数显示**：`{count}` 会被替换为实际人数的倒序

### 延迟时间说明

`updateDelay` 配置项用于解决成员数量获取不准确的问题：

- **问题原因**：成员加入/退出事件触发时，平台可能还没有更新成员列表
- **解决方案**：等待一段时间后再获取成员数量，确保数据准确
- **推荐设置**：
  - QQ平台：1000-2000ms
  - Discord：500-1000ms  
  - 其他平台：根据实际情况调整

### 效果演示

假设有三个群聊，各有不同人数：

**群聊A（374人）：**
- 配置：`"({count})🦦獭家一爱相亲相"`
- 更新后：`(473)🦦獭家一爱相亲相`

**群聊B（156人）：**
- 配置：`"({count})🎮游戏群-人数统计"`
- 更新后：`(651)🎮游戏群-人数统计`

**群聊C（89人）：**
- 配置：`"📚学习群({count}人)"`
- 更新后：`📚学习群(98人)`

> 注意：括号中的数字是实际人数的倒序显示

## 🎮 可用指令

### `update-group-name [群聊ID]`
手动更新群聊名称

**参数：**
- `群聊ID` (可选) - 要更新的群聊ID，不提供则使用当前群聊
- `-c, --count <数量>` - 手动指定人数，不提供则自动获取

**示例：**
```
update-group-name
update-group-name 12345678901234567
update-group-name -c 100
```

### `group-name-config`
查看当前插件配置

**示例输出：**
```
群名自动更新配置:
- 监听群聊: 12345678901234567, 98765432109876543, 11111111111111111
- 更新延迟: 2000ms
- 群聊模板:
  * 12345678901234567: ({count})🦦獭家一爱相亲相
  * 98765432109876543: ({count})🎮游戏群-人数统计
  * 11111111111111111: 📚学习群({count}人)
```

### `set-group-template <群聊ID> <模板>`
设置群聊模板

**参数：**
- `群聊ID` - 要设置模板的群聊ID
- `模板` - 新的模板内容，必须包含 `{count}` 占位符

**示例：**
```
set-group-template 12345678901234567 "({count})🦦獭家一爱相亲相"
set-group-template 98765432109876543 "({count})🎮游戏群-人数统计"
set-group-template 11111111111111111 "📚学习群({count}人)"
```

### `remove-group-template <群聊ID>`
删除群聊模板，停止监听该群

**示例：**
```
remove-group-template 12345678901234567
```

### `test-group-api [群聊ID]`
测试群聊API功能

**示例输出：**
```
群聊API测试结果:
- 群聊ID: 12345678901234567
- 当前群名: (473)🦦獭家一爱相亲相
- 成员数量: 374
- 使用模板: ({count})🦦獭家一爱相亲相
- 监听状态: 已监听
- 平台: onebot
- 可用API方法: set_group_name, OneBot.call
- 所有内部方法: set_group_name, get_group_info, send_msg...
```

### `debug-platform`
显示平台详细信息和支持的API方法

**示例输出：**
```
平台调试信息:
- 平台: onebot
- 机器人ID: 12345678
- 用户ID: 98765432
- 内部方法数量: 25
- 函数方法: set_group_name, get_group_info, get_group_member_list...
- 属性: platform, selfId, userId...
```

## 🔧 获取群聊ID

### QQ群
1. 在群聊中发送 `test-group-api` 指令
2. 或在QQ群设置中查看群号

### 微信群
1. 使用微信机器人时，群聊ID通常是一个长字符串
2. 可以通过 `test-group-api` 指令获取

### Discord
1. 开启开发者模式
2. 右键群聊 → 复制ID

## 🐛 故障排除

### 群名更新失败
1. 检查机器人是否有管理群聊的权限
2. 确认群聊ID是否正确
3. 查看日志中的具体错误信息

### 人数获取不准确
如果发现人数显示不正确：

1. **调整延迟时间**：
   ```yaml
   updateDelay: 3000  # 增加到3秒
   ```

2. **检查日志**：
   - 查看是否有 "等待平台更新成员列表" 的日志
   - 确认是否成功获取到成员数量

3. **不同平台建议**：
   - QQ平台：建议设置为 2000-3000ms
   - 网络较慢时：可以设置为 5000ms

### 平台不支持修改群名
如果看到 `当前平台不支持修改群名` 的警告：

1. **使用调试指令检查平台支持**：
   ```
   debug-platform
   test-group-api
   ```

2. **常见平台支持情况**：
   - ✅ **QQ (OneBot)**：支持 `set_group_name` 等API
   - ✅ **QQ官方Bot**：支持 `modify_group_info` 等API  
   - ❌ **微信**：大多数情况下不支持修改群名
   - ✅ **Discord**：支持 `editGuild` API
   - ❌ **Telegram**：Bot无法修改群名

3. **解决方案**：
   - 检查机器人是否有足够的权限
   - 确认使用的适配器是否支持群名修改
   - 联系适配器开发者了解API支持情况

### 无法获取成员列表
1. 某些平台可能限制获取成员列表
2. 可以使用手动指定人数的方式：`update-group-name -c 人数`

## 📋 注意事项

1. **人数显示规则**：群名中显示的人数是实际人数的倒序
   - 实际 123 人 → 显示 321
   - 实际 456 人 → 显示 654

2. **监听规则**：只有在 `guildTemplates` 中配置的群聊才会被监听和自动更新

3. **人数准确性**：插件会在成员变动后等待一段时间再获取成员数量，确保数据准确

4. **平台兼容性**：不同聊天平台的API可能有差异，如遇问题请查看日志

5. **权限要求**：机器人需要有修改群名的权限

6. **更新频率**：每次成员变动都会触发检查，但只有人数真正变化时才会更新群名

## 📄 许可证

MIT License