架构总览¶
普通用户不需要读懂所有细节。如果你想理解"为什么机器人有时候不回复"或"为什么改完配置要重启"，这里给你一个大概印象。
消息处理流程¶
一条消息进入机器人后经过这几步：
- 频道白名单：是否允许接收此频道消息。
- Assignee 检查：群聊频道是否把 Bot 设为负责人。
- 格式转换：平台消息经 Translator 转成内部记录。
- Will 判断：决定"先观察"还是"触发回复"。
- 模型调用：如果触发，调用模型、执行工具、生成回复。
- 分段投递：结果按节奏发回群里。
平台消息
→ Messenger 接收
→ 白名单 + assignee 检查
→ Translator 格式转换
→ ChannelRuntime 入队
→ Will 判断
→ Agent Runtime（模型 + 工具）
→ 分段投递回平台
关键组件¶
Messenger：消息入口与出口¶
Messenger 注册 Koishi 中间件，接收平台 Session。它负责：
- 检查频道白名单和 assignee
- 选择 Translator 转换消息格式
- 投递回复，按字符速度 pacing 分段发送
- 失败时通知 Runtime
Channels：频道存储¶
每个频道有独立数据目录，保存会话文件、收到的图片、工具生成的文件。Channels 负责创建和管理这些目录。
RuntimeManager：频道运行管理¶
每个频道有一个 ChannelRuntime。RuntimeManager 按需创建、缓存和销毁它们，保证同一频道不会出现多个互相干扰的回复流程。
ChannelRuntime：消息队列¶
同一频道的消息按顺序处理。如果机器人正在回复，新消息进入同一对话流程排队，不会开新线程抢回复。
Agent Runtime：模型和工具执行¶
真正调用模型、执行工具、生成回复的通用运行时。它不关心 Koishi 或具体平台，只处理消息、工具和模型之间的交互。位于 @yesimbot/agent-runtime 包中。
为什么改配置要重启¶
频道开始时会固定当时的模型、工具和插件设置（Runtime Snapshot）。避免一边聊一边切换底层配置造成混乱，新配置通常等重启后完整生效。
投递失败会怎样¶
如果回复发送失败，Messenger 会把失败通知同一频道的 ChannelRuntime，让对话流程知道发送未成功。这比假装已发出要好，方便排查问题。