核心概念

这一页先解释 iamai 的词汇。理解这些概念后，再读教程和 API 会更顺。

Runtime —

Runtime 是运行时容器。它负责读取配置、创建适配器、加载插件、管理状态、调度事件、 处理热重载，并向插件提供依赖注入。

Adapter

Adapter 是协议边界。它把外部系统的消息转换成统一的 Event，也负责把 Message 发回外部系统。

适配器应该处理网络、鉴权、协议格式和限流等边界问题；业务逻辑不应该依赖某个平台的 原始 payload。

Event

Event 是框架内部的统一事件模型。插件通常读取这些字段：

• event.type

• event.detail_type

• event.user_id

• event.channel_id

• event.text

• event.raw

raw 仍然保留平台原始数据，但应当作为补充信息，而不是插件的主要依赖。

Message

Message 是协议无关的消息链容器。插件可以从纯文本开始，也可以构造更复杂的 segment。 适配器在发送时再转换成目标协议格式。

Plugin

Plugin 是业务模块。一个插件可以声明：

• 命令 handler；

• 普通消息 handler；

• 事件 handler；

• middleware；

• Pydantic 配置模型；

• 持久化状态。

Context

Context 是一次 handler 执行的上下文。它把 runtime、adapter、plugin、 event、匹配结果和快捷方法放在一起。

Rule 与 Permission

Rule 负责判断事件是否应该进入某个 handler。Permission 负责判断调用者是否有资格 执行该 handler。

Rule 可以组合文本规则、事件字段规则、原始 payload 字段规则和命名 Ruleset。规则成功时 可以返回 payload，这些值会进入 ctx.matches 并参与依赖注入。Permission 只看“谁能做”， 不要和消息形态判断混在一起。

把这两层拆开会让业务代码更清晰，也让管理命令、群聊权限和平台限制更容易审计。规则细节见 规则参考。

State 与 Session

state 用于保存插件状态。SessionManager 用于等待同一会话里的下一条消息。 当前 session key 默认由 adapter:channel:user 组成，避免群聊中不同用户互相串会话。