astrbotpluginmatrixrulereact

独立的 Matrix 条件 Reaction 插件。它承接原先位于 astrbot_plugin_matrix_adapter 中的预回应逻辑，让适配器只负责 Matrix 事件转换与 Reaction 发送能力。

依赖与安装

• AstrBot >=4.16.0
• 已安装并启用 astrbot_plugin_matrix_adapter
• 仅处理 matrix 平台的群聊与私聊消息

将本目录作为 AstrBot 插件安装后，必须先在插件配置页填写一个或多个「机器人名称」，再按需 开启「启用唤醒条件 Reaction」和/或「启用动态 Reaction 规则」。两个开关相互独立且 默认均关闭。「机器人名称」列表为空或与当前消息所属机器人不匹配时，插件完全不运行。

代码结构

• main.py：插件入口与 AstrBot 消息/指令装饰器绑定；
• message_handler.py：消息校验、唤醒回退与 Reaction 发送流程；
• rule_commands.py：管理员规则增删查及配置持久化；
• rules.py：条件数组解析、AND/OR 规则匹配、旧规则兼容和动态 Reaction 选择；
• trigger_filter.py：原有 @机器人 / wake_prefix 唤醒条件过滤。

触发规则

插件首先将配置的 bot_name 列表与 event.get_platform_id() 比较。该 ID 就是 AstrBot WebUI 「机器人」列表中显示的「机器人名称」，不是 Matrix 用户 ID、昵称或设备名。列表为空或 当前机器人名称不在列表中时，Reaction 检测和管理指令都不执行。

「启用唤醒条件 Reaction」只控制 @bot / wake_prefix 触发；「启用动态 Reaction 规则」只控制下方规则列表。因此即使关闭前者，只要后者开启，普通 Matrix 消息仍会进行动态规则匹配。

动态规则按配置顺序匹配，首个命中的规则生效，每条消息最多发送一个 Reaction。同一规则的条件可以使用 AND（全部命中）或 OR（任一命中）组合， 每个 A / B / C 条件都可以独立选择下列匹配类型：

• keyword：原始消息文本包含指定关键字（区分大小写）；
• regex：正则表达式在原始消息文本中匹配；
• user_id：发件人完整 Matrix ID 与配置值相同；
• bot_id：当前 Matrix 机器人 ID 与配置值相同；
• group_id：群聊的完整 Matrix room ID 与配置值相同；
• message_type：匹配 group / private 等 AstrBot 消息类型，也可以匹配 Matrix 原始 msgtype（例如 m.text）。

规则可以使用 fixed 固定 Reaction，或使用 random 从规则的 Reaction 列表中随机选取。动态检测通过工作线程异步执行，避免大量规则或正则匹配阻塞 AstrBot 事件循环。当两个开关同时开启时，动态规则优先；如果没有命中，再使用唤醒 规则从全局 emojis 列表随机选择：

• 消息链明确 @ 当前 Matrix 机器人；
• 原始消息以当前会话使用的 AstrBot 全局 wake_prefix 开头，并且 AstrBot 已将它识别为 有效唤醒消息。

插件使用适配器提供的标准 event.react() 接口，不访问适配器私有配置。不匹配动态规则且未 显式唤醒的普通消息、机器人自身消息、缺少 Matrix event ID 的消息，以及空 Reaction 列表都不会触发。发送失败只记录日志，不中断后续消息处理。

简单规则模板

在插件配置页的「动态 Reaction 规则」中点击添加，可直接选择：

• 单条规则（Single）：一个条件命中；
• A AND B（快捷）：A 和 B 都命中；
• A OR B（快捷）：A 或 B 任一命中；
• 全部匹配（All）：可追加任意数量的条件，全部命中；
• 任一匹配（Any）：可追加任意数量的条件，任一命中。

每个模板都可设置 fixed / random、Reaction 列表，以及每个条件的匹配类型和内容。 模板缺少必需条件或条件内容为空时，该规则会被安全忽略。

管理员指令

所有动态规则指令均位于 /matrix rules react 指令组下，并且需要 AstrBot 管理员权限。

/matrix rules react add <fixed|random> <Reaction 列表> (<keyword|regex|user_id|bot_id|group_id|message_type> <匹配内容>)[]
/matrix rules react list
/matrix rules react remove <规则编号>

Reaction 列表 使用英文逗号分隔。fixed 模式必须且只能提供一项； random 模式可以提供多项。后面的条件数组至少需要一项，数量不设上限；推荐用 (...) 包住每一项，这样带空格或括号的关键字、正则也可以被准确解析。不写括号的 keyword 部署完成 group_id !room:example.org 形式也受支持；如果匹配内容本身包含一个 完整的条件类型单词，请用括号或引号避免歧义。 指令添加的高级多条件规则默认使用 AND；在配置页展开该规则后，也可将「条件关系」改为 OR。

/matrix rules react add fixed 👍 (keyword 部署完成)
/matrix rules react add random 👍,🎉 (regex ^build\s+(passed|success)$) (group_id !ci:example.org)
/matrix rules react add fixed 👋 (user_id @alice:example.org) (bot_id @helper:example.org) (message_type group)
/matrix rules react list
/matrix rules react remove 2

指令会立即更新并持久化插件配置。动态规则只受 matrix_rule_react.dynamic_rules_enable 控制；如果该开关未启用，add 的返回消息会明确提示。

配置

{
  "matrix_rule_react": {
    "bot_name": ["bot", "matrix-bot"],
    "enable": false,
    "dynamic_rules_enable": true,
    "emojis": ["🤗", "🐟", "🍞", "mxc://example.org/media-id"],
    "rules": [
      {
        "__template_key": "a_and_b",
        "selection": "fixed",
        "reactions": ["👍"],
        "match_mode": "all",
        "condition_a": {"match_type": "keyword", "negated": false, "patterns": ["部署完成"]},
        "condition_b": {"match_type": "group_id", "negated": false, "patterns": ["!ci:example.org"]}
      },
      {
        "__template_key": "a_or_b",
        "selection": "random",
        "reactions": ["👍", "🎉"],
        "match_mode": "any",
        "condition_a": {"match_type": "keyword", "negated": false, "patterns": ["build passed"]},
        "condition_b": {"match_type": "user_id", "negated": false, "patterns": ["@ci:example.org"]}
      },
      {
        "__template_key": "all_rule",
        "selection": "fixed",
        "reactions": ["🚀"],
        "match_mode": "all",
        "conditions": [
          {"match_type": "regex", "negated": false, "patterns": ["^build\\s+(passed|success)$"]},
          {"match_type": "message_type", "negated": false, "patterns": ["group"]}
        ]
      }
    ]
  }
}

bot_name 是必填的目标机器人名称列表，区分大小写。比如 WebUI 中对应 Matrix 机器人的 「机器人名称」为 bot 和 matrix-bot，这里就可以填写 ["bot", "matrix-bot"]。 旧版单字符串配置仍会被识别为只包含该名称的列表。

emojis 只供唤醒条件 Reaction 使用，同时支持普通 Unicode 表情和 Matrix 客户端支持的 自定义 Reaction key。运行时 会去除首尾空白、忽略空值并去重。旧版单条件规则中的 match_type / pattern 仍可继续运行；新指令统一写入 conditions 数组和 match_mode: "all"。

从 Matrix 适配器迁移

适配器原配置项 matrix_pre_ack_emoji 已移除。升级后请在本插件配置中将：

• matrix_pre_ack_emoji.enable 迁移为 matrix_rule_react.enable；
• matrix_pre_ack_emoji.emojis 迁移为 matrix_rule_react.emojis。

从本插件 0.6.x 或更早版本升级时，如果需要继续运行已有动态规则，还需显式开启 matrix_rule_react.dynamic_rules_enable。新开关默认关闭，避免升级后未经确认就对普通消息 发送 Reaction。 从 0.7.x 升级到 0.8.0 后，还必须填写 matrix_rule_react.bot_name，否则插件不运行。 从 0.8.x 起，bot_name 支持名称列表；旧版字符串配置会自动按单元素列表处理。

不要在两个插件中重复配置；Reaction 的条件判断与随机选择现只由本插件负责。