AstrBot 群聊多机器人共存控制

astrbot_plugin_multi_bot_control 用于限制同一 QQ 群里多个机器人互相唤醒、循环调用 LLM 的情况。插件通过 QQ 号精确识别机器人，把可由当前 AstrBot 实例控制的机器人放入“受控机器人”名单，把外部未知机器人放入“不受控机器人”名单，然后按群聊独立统计对话次数、冷却和频率。

当前版本：v0.2.2

本插件不会主动唤醒机器人。所有机器人仍然遵循 AstrBot 原有唤醒规则；只有某条机器人消息本来已经命中 @、引用回复、唤醒前缀等唤醒条件时，本插件才会介入限流、提示词注入和计数。

适用范围

• 推荐平台：OneBot v11 / aiocqhttp。该平台事件中的 sender_id、self_id、group_id 均是 QQ 号/群号，可以与配置中的 QQ 号匹配。
• QQ 官方 API：AstrBot 当前适配器通常只暴露 openid，不是 QQ 号。由于本插件按 QQ 号精确匹配，无法可靠识别 QQ 官方 API 的机器人身份。
• 名单中的昵称和称呼只用于提示词显示，不参与身份识别。

名单配置

在 WebUI 的插件配置中填写：

• 由本 AstrBot 创建的受控机器人：当前 AstrBot 实例实际控制、会代表其调用 LLM 回复的机器人 QQ 号。当前运行实例的 QQ 号必须命中该名单，否则插件不会代它处理机器人对话。
• 来源未知的不受控机器人：同群内外部机器人 QQ 号。它们不会被本插件控制，但其发言会被识别、限流和注入机器人交流提示词。

全局名单可复用于多个群。统计状态按 平台实例 + 群聊 + 当前受控机器人 + 对端机器人 隔离，因此同一对机器人在群 1 触发冷却，不会影响群 2。

控制策略

插件支持以下限制：

• 单对机器人会话最大连续轮次
• 达到限制后的冷却时间
• 同一对端机器人最小请求间隔
• 同群时间窗口内机器人回复总量
• 无人类介入时的连续机器人对话限制
• 同一会话重复消息限制
• 多个受控机器人被同时 @ 时按稳定优先级排队回复

轮次、群窗口、无人类连续对话和重复消息统计只在当前受控机器人实际成功发出回复后提交。其他机器人发起调用但当前受控机器人没有成功发送回复时，不会消耗回复轮次。

人类成员在群内发言会重置当前群的“无人类介入”统计，但不会清除已经触发的单对机器人冷却。

目标识别

require_explicit_target 默认关闭。关闭时，只要消息来源命中机器人名单且该消息本来已经唤醒当前 AstrBot，就会进入限流逻辑；如果消息明确 @ 或引用回复了其他受控机器人，当前受控机器人会静默拦截，避免抢答。

开启 require_explicit_target 后，在原本已唤醒的前提下，名单内机器人还必须明确指向当前受控机器人，才允许当前受控机器人回复。明确目标包括：

• @ 当前受控机器人的 QQ 号
• 引用回复当前受控机器人的消息
• 开启 treat_at_all_as_target 后的 @全体成员
• 开启 treat_wake_prefix_as_target 后，仅使用 AstrBot 唤醒前缀且未 @/引用其他人的消息

群主命令

群主可以为当前群维护本地“不受控机器人”名单：

/mbot add <QQ号> [昵称] [称呼]
/mbot remove <QQ号>
/mbot list
/mbot clear
/mbot help

本地名单只影响当前群，不修改 WebUI 全局配置。若本地名单与全局受控机器人 QQ 号重复，全局受控机器人优先，避免误把当前 AstrBot 控制的机器人降级为不受控机器人。

数据文件

插件运行数据保存在 AstrBot 插件数据目录：

• group_bots.json：群主命令维护的当前群本地名单
• controlled_priorities.json：受控机器人的稳定优先级

调试建议

如果限制不生效，优先检查：

1. 当前 AstrBot 实例的机器人 QQ 号是否已填写到“受控机器人”名单。
2. 外部机器人的 QQ 号是否填写到“不受控机器人”名单。
3. 当前平台是否是 OneBot v11 / aiocqhttp，而不是只提供 openid 的 QQ 官方 API。
4. 开启 require_explicit_target 后，外部机器人是否真的 @ 或引用回复了当前受控机器人。