跳到主要內容

Raft 設置

Hermes 通過本地喚醒通道橋接器（wake-channel bridge）作為外部代理連接到 Raft。該適配器啟動一個環回 HTTP 端點，接收來自橋接器的無內容喚醒提示（wake hints），然後將它們注入到 Hermes 網關會話管道中。代理通過 Raft CLI 讀取和發送消息——適配器從不處理消息體或交付遊標。

職責劃分
  • 橋接器負責：喚醒提示消費、去重、退避、重連、至少一次交付以及證明日誌記錄。
  • Hermes 適配器負責：一個本地主機喚醒端點，並將簡短通知注入代理的上下文中。
  • 代理負責：拉取消息（raft message check）、回覆（raft message send）以及通過 CLI 進行的所有其他 Raft 交互。

適配器不持有任何 Raft 憑據——僅持有用於橋接器和端點之間本地主機身份驗證的每會話共享令牌。

前提條件​

  • 一個可以創建外部代理的 Raft 工作區
  • 已安裝並登錄到該外部代理配置文件的 Raft CLI
  • aiohttp — Python 包（包含在 Hermes [all] 額外依賴中）

在 Raft 中，打開 Agents（代理）菜單，創建一個 External Agent（外部代理），並按照設置卡片指引安裝 Raft CLI 並登錄代理配置文件。代理創建完成後，Raft 會顯示一個 Hermes 設置指南，其中包含啟動網關所需的環境變量和配置。

設置​

添加到 ~/.hermes/.env：

RAFT_PROFILE=your-agent-profile

就是這樣——當設置了 RAFT_PROFILE 時，適配器會自動啟用。它會生成每會話橋接令牌，選擇一個臨時端口，並在網關啟動時自動產生橋接子進程。

工作原理​

Raft Server → Bridge (wake-hints SSE) → POST /wake → Hermes Adapter → Agent context
Agent → raft message check → Raft Server (message bodies)
Agent → raft message send → Raft Server (replies)
  1. Raft 服務器通過 SSE 向橋接進程發送喚醒提示。
  2. 橋接器將每個提示作為 POST /wake 轉發到適配器的環回端點。
  3. 適配器驗證橋接令牌，確認負載無內容，並將喚醒通知注入 Hermes 會話。
  4. 代理看到喚醒通知後，使用 Raft CLI 讀取消息並回復。

根據約定，喚醒負載是無內容的——它們攜帶元數據（事件 ID、消息 ID、時間戳），但絕不包含消息體、頻道名稱或發送者身份。適配器會拒絕任何包含內容形狀字段（text、body、content、messages 等）的負載。

橋接器​

適配器自動以子進程形式產生 raft agent bridge，傳遞端點 URL 和令牌。橋接器使用配置好的配置文件連接到 Raft 服務器，並開始轉發喚醒提示。當網關關閉時，它會被終止。

環境變量​

變量描述默認值
RAFT_PROFILERaft 代理配置文件 slug —— 設置後自動啟用適配器(必填)