Messages

本页串起 Moltbot 如何处理入站消息、sessions、queueing、streaming，以及 reasoning 可见性。

Message flow（高层）

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

关键开关位于配置中：

• messages.*：用于 prefixes、queueing 与群聊行为。
• agents.defaults.*：用于 block streaming 与 chunking 的默认值。
• 渠道覆盖（channels.whatsapp.*、channels.telegram.* 等）：用于 caps 与 streaming 开关。

完整 schema 参见 Configuration。

入站去重（Inbound dedupe）

渠道在重连后可能会重复投递同一条消息。Moltbot 会维护一个短生命周期 cache（按 channel/account/peer/session/message id 作为 key），以保证重复投递不会触发新的 agent run。

入站防抖（Inbound debouncing）

来自同一发送者的快速连续消息可以通过 messages.inbound 被批处理成单个 agent 回合。防抖按 channel + conversation 作用域生效，并使用最新一条消息作为 reply threading/IDs。

配置（全局默认 + 按渠道覆盖）：

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}

备注：

• 防抖只对纯文本消息生效；media/attachments 会立即 flush。
• 控制命令会绕过防抖，以保持其独立消息语义。

Sessions 与设备

Sessions 由 gateway 持有，而不是 clients。

• 私聊会折叠到 agent main session key。
• 群聊/频道拥有各自的 session keys。
• session store 与 transcripts 位于 gateway host。

多个设备/渠道可以映射到同一个 session，但历史不会完全同步回每个 client。建议：长对话尽量使用一个主设备，以避免上下文分叉。Control UI 与 TUI 始终展示 gateway-backed 的 session transcript，因此它们是唯一事实来源。

细节参见 Session management。

入站 body 与历史上下文

Moltbot 会把prompt body与command body分开：

• Body：发送给 agent 的 prompt 文本。可能包含 channel envelopes 与可选的历史包装。
• CommandBody：用于 directive/command 解析的原始用户文本。
• RawBody：CommandBody 的 legacy alias（保留以兼容）。

当渠道提供历史时，会使用统一的 wrapper：

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

对非私聊（groups/channels/rooms），当前消息 body 会带上发送者 label 前缀（与历史条目的风格一致）。这让实时消息与队列/历史消息在 agent prompt 中保持一致。

历史 buffer 是 pending-only：它包含那些未触发 run 的群消息（例如需要 mention 才触发的消息），并且排除已写入 session transcript 的消息。

directive stripping 只作用于当前消息区块，以保证历史不被改写。包装历史的渠道应将 CommandBody（或 RawBody）设置为原始消息文本，并将 Body 作为合并后的 prompt。历史 buffer 可通过 messages.groupChat.historyLimit（全局默认）与按渠道覆盖（如 channels.slack.historyLimit 或 channels.telegram.accounts.<id>.historyLimit）配置（设为 0 可禁用）。

Queueing 与 followups

当已有 run 处于 active 状态时，入站消息可以排队、steer 进当前 run，或被 collect 为 followup 回合。

• 通过 messages.queue（以及 messages.queue.byChannel）配置。
• Modes：interrupt、steer、followup、collect，以及 backlog 变体。

细节参见 Queueing。

Streaming、chunking 与 batching

Block streaming 会在模型产生文本 blocks 时发送部分回复。 chunking 会遵守渠道文本长度限制，并避免拆分 fenced code。

关键配置：

• agents.defaults.blockStreamingDefault（on|off，默认 off）
• agents.defaults.blockStreamingBreak（text_end|message_end）
• agents.defaults.blockStreamingChunk（minChars|maxChars|breakPreference）
• agents.defaults.blockStreamingCoalesce（基于 idle 的 batching）
• agents.defaults.humanDelay（block replies 之间更像人的停顿）
• 渠道覆盖：*.blockStreaming 与 *.blockStreamingCoalesce（非 Telegram 渠道需要显式 *.blockStreaming: true）

细节参见 Streaming + chunking。

Reasoning 可见性与 tokens

Moltbot 可以暴露或隐藏模型 reasoning：

• /reasoning on|off|stream 控制可见性。
• reasoning 一旦由模型产出，仍会计入 token 用量。
• Telegram 支持把 reasoning stream 到 draft bubble。

细节参见 Thinking + reasoning directives 与 Token use。

Prefixes、threading 与 replies

出站消息格式化集中在 messages：

• messages.responsePrefix（出站前缀）与 channels.whatsapp.messagePrefix（WhatsApp 入站前缀）
• 通过 replyToMode 与各渠道默认值实现回复线程（reply threading）

细节参见 Configuration 与各渠道文档。