Multi-bot response controller - manages the response behavior of multiple bots in the same channel by automatically adjusting the assignee field in the channel table, supporting keyword and command-based filtering rules
npm install koishi-plugin-multi-bot-controller
Multi-bot response controller for Koishi. Manage which bot should respond to messages in multi-bot scenarios.
- 独立过滤配置
- 指令过滤:控制响应哪些指令
- 来源过滤:按群号、用户 ID、频道 ID、私聊进行过滤
- 关键词过滤:控制响应哪些非指令消息
- 艾特优先
- 当消息艾特了某个 Bot 时,只有被艾特的 Bot 会响应
- 此逻辑优先级最高,通用于任何配置
- 动态指令监听
- 自动监听当前实例的所有可用指令
- 指令列表会随着插件加载/卸载自动更新
- 辅助命令
- mc.bots - 查看可用的 Bot 列表
- mc.commands - 查看可用的指令列表
- mc.copy-commands - 获取所有指令名称(方便配置时使用)
- mc.config - 查看当前插件配置
``bash使用 npm
npm install koishi-plugin-multi-bot-controller
配置
$3
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
|
debug | boolean | false | 是否启用调试日志 |
| bots | BotConfig[] | [] | Bot 配置列表 |$3
#### 基础配置
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
|
platform | string | 必需 | 平台名称(如 onebot, qq, discord) |
| selfId | string | 必需 | Bot 账号 ID |
| enabled | boolean | true | 是否启用此 bot 的响应控制 |#### 指令过滤
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
|
enableCommandFilter | boolean | false | 是否启用指令过滤 |
| commands | string[] | [] | 允许响应的指令列表 |说明:启用后,只有列表中的指令会被响应。列表为空时不响应任何指令。
#### 来源过滤
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
|
enableSourceFilter | boolean | false | 是否启用来源过滤 |
| sourceFilters | SourceFilter[] | [] | 来源过滤规则列表 |
| sourceFilterMode | FilterMode | whitelist | 来源过滤模式:blacklist / whitelist |来源过滤规则 (SourceFilter):
-
type: 'guild' - 按群号过滤,value 为群号
- type: 'user' - 按用户 ID 过滤,value 为用户 ID
- type: 'channel' - 按频道 ID 过滤,value 为频道 ID
- type: 'private' - 私聊过滤,value 为 true 或 false#### 关键词过滤
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
|
enableKeywordFilter | boolean | false | 是否启用关键词过滤 |
| keywords | string[] | [] | 触发词列表 |
| keywordFilterMode | FilterMode | whitelist | 关键词过滤模式 |说明:仅对非指令消息生效。
$3
| 模式 | 关键词过滤 | 来源过滤 |
|------|-----------|----------|
|
whitelist | 白名单 | 白名单 |
| blacklist | 黑名单 | 黑名单 |使用场景
$3
`yaml
bots:
# 简单问答 Bot(只响应特定关键词)
- platform: qq
selfId: "111"
enabled: true
enableKeywordFilter: true
keywords: ["天气", "时间", "查询"]
keywordFilterMode: whitelist # 白名单:只响应包含这些关键词的消息 # LLM 智能对话 Bot(响应所有消息)
- platform: qq
selfId: "222"
enabled: true
# 不配置任何过滤,响应所有消息
`$3
`yaml
bots:
# 管理员专用 Bot(仅特定群和用户的管理指令)
- platform: qq
selfId: "111"
enabled: true
enableSourceFilter: true
sourceFilters:
- type: guild
value: "987654321" # 管理员群
- type: user
value: "123456789" # 超级用户
sourceFilterMode: whitelist # 白名单:只允许这些来源
enableCommandFilter: true
commands: ["ban", "kick", "mute"] # 只响应这些指令 # 娱乐类指令 Bot
- platform: qq
selfId: "222"
enabled: true
enableCommandFilter: true
commands: ["roll", "draw", "guess"] # 只响应这些指令
# LLM 通用 Bot
- platform: qq
selfId: "333"
enabled: true
# 不配置过滤,响应所有消息
`$3
`yaml
bots:
# QQ Bot - 处理指令和关键词
- platform: onebot
selfId: "111"
enabled: true
enableKeywordFilter: true
keywords: ["帮助", "查询"]
keywordFilterMode: whitelist # 白名单:只响应包含这些关键词的消息 # Discord Bot - 全部响应
- platform: discord
selfId: "222"
enabled: true
`$3
`yaml
bots:
- platform: qq
selfId: "111"
enabled: true
enableKeywordFilter: true
keywords: ["广告", "推广", "加群"]
keywordFilterMode: blacklist # 黑名单:屏蔽包含这些关键词的消息
`命令
| 命令 | 别名 | 说明 |
|------|------|------|
|
mc.bots | mbc.bots | 查看可用的 Bot 列表 |
| mc.commands | mbc.commands | 查看可用的指令列表 |
| mc.copy-commands | mbc.copy-commands | 获取所有指令名称(方便配置时使用) |
| mc.config | mbc.config | 查看当前插件配置 |工作原理
$3
在 Koishi 中,当多个 Bot 加入同一个频道时,系统使用 Channel Table(频道表) 来管理哪个 Bot 应该响应消息。每个频道记录都有一个
assignee 字段,表示被指定处理消息的 Bot ID。消息处理流程如下:
1. 用户发送消息到频道
2. Koishi 检查该频道的
assignee
3. 如果 assignee 为空,所有 Bot 都可能响应
4. 如果 assignee 有值,只有被指定的 Bot 会响应$3
本插件通过监听 Koishi 的
attach-channel 事件,在消息处理的最早阶段介入,动态控制 assignee 字段来实现多 Bot 的自动分配。`
用户消息
│
▼
┌─────────────────────────────────────┐
│ attach-channel 事件触发 │
│ (消息进入处理管道的第一步) │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 检查是否有艾特 │
│ - 有艾特:只有被艾特的 Bot 响应 │
│ - 无艾特:继续判断 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Bot 是否启用? │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 来源过滤检查 │
│ - 未启用 → 通过 │
│ - 黑名单模式 → 匹配则阻止 │
│ - 白名单模式 → 匹配则通过 │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 判断消息类型 │
│ - 指令消息 → 检查指令权限 │
│ - 非指令消息 → 检查关键词匹配 │
└─────────────────────────────────────┘
│
├─────────────────┬─────────────────┐
▼ ▼
应该响应 不应该响应
│ │
▼ ▼
设置 assignee 清空 assignee
为当前 Bot ID (让其他 Bot 处理)
│ │
└─────────────────┴─────────────────┘
│
▼
后续插件处理消息
(指令、LLM、其他功能)
`$3
`
shouldBotRespond(session, botConfig)
│
▼
┌─────────────────────────────────────┐
│ Bot 是否启用? │
└─────────────────────────────────────┘
│
├─ 否 ─→ 返回 false (不响应)
│
▼ 是
┌─────────────────────────────────────┐
│ 来源过滤检查 │
│ - 未启用 → 通过 │
│ - 黑名单模式 → 匹配则阻止 │
│ - 白名单模式 → 匹配则通过 │
└─────────────────────────────────────┘
│
▼ 通过
┌─────────────────────────────────────┐
│ 是指令消息? │
└─────────────────────────────────────┘
│
├─ 是 ─→ 检查指令权限
│ - 未启用过滤 → 放行
│ - 列表为空 → 不响应
│ - 在列表中 → 响应
│ - 不在列表中 → 不响应
│
▼ 否
┌─────────────────────────────────────┐
│ 关键词过滤检查 │
│ - 未启用 → 不响应 │
│ - 白名单(默认):匹配则响应 │
│ - 黑名单:不匹配则响应 │
└─────────────────────────────────────┘
`$3
当消息中包含艾特(@提及)时:
1. 被艾特的 Bot:直接接管消息处理,设置
assignee 为自己
2. 未被艾特的 Bot:放弃处理,清空 assignee(如果之前持有)此逻辑优先级最高,会跳过所有其他过滤判断。
$3
Koishi 的事件触发顺序:
`
1. attach-channel ← 本插件在此拦截 (最早)
2. before-attach
3. attach
4. before-command
5. command
6. middleware (中间件)
`选择
attach-channel 的原因:
- 最早介入:在任何插件处理消息之前就能控制 assignee
- 精确控制:可以直接修改频道表的 assignee 字段
- 无副作用:不会影响其他插件的事件监听$3
启用
debug: true 后,插件会输出详细的决策日志:`
[DEBUG] [qq:123456] 频道 987654, 用户 111222: 来源过滤:匹配,whitelist 模式 → 通过
[DEBUG] [qq:123456] 频道 987654, 用户 111222: 指令 "help":在列表中 → true
[DEBUG] [qq:123456] 被艾特,接管消息处理
[DEBUG] [qq:123456] 频道 987654, 用户 111222: 非指令消息:关键词匹配结果 = true
``MIT