Raft 接入——轻量组网协议

這篇教學帶你用 Raft 把 AI 智慧體接入聊天平台，全程只需設定一個環境變數，其他交給 Hermes 自動搞定。

---

先打個比方

把 Raft 想像成 社區管理員，你的 AI 智慧體是 住戶，Hermes 是 警衛。

• 管理員（Raft 伺服器） 負責通知住戶「有快遞來了」，但不直接送快遞。
• 警衛（Hermes 轉接器） 只負責轉達「有快遞」這個提示，不碰快遞箱。
• 住戶（智慧體） 聽到提示後，自己下樓取件（raft message check）和回信（raft message send）。

整個過程中，Hermes 不接觸訊息內容，也不持有 Raft 的登入憑證——它只用一個臨時令牌，確認「這是管理員派來的」就夠了。

---

第 1 步：準備 Raft 工作區

1. 開啟 Raft，進入你的工作區。
2. 在 Agents 選單裡，建立一個 External Agent（外部智慧體）。
3. 依照頁面提示，安裝 Raft CLI 並登入該智慧體的帳號。

建立完成後，Raft 會顯示一個 Hermes 接入指南，裡面需要的設定其實就一個。

---

第 2 步：設定環境變數

在 ~/.hermes/.env 檔案裡，加上這一行：

RAFT_PROFILE=你的智慧體帳號名

就這一行，完事了。 不用手動啟動任何服務。

---

第 3 步：啟動 Hermes 閘道

正常啟動 Hermes 閘道（比如 hermes gateway）。轉接器會自動完成以下事情：

• 產生一個臨時橋接令牌（僅本次工作階段有效）
• 挑選一個空閒的本機連接埠
• 自動啟動一個 橋接子程序，負責與 Raft 伺服器保持連線

閘道關閉時，橋接程序也會自動結束，不用你操心清理。

---

它內部是怎麼跑的？

Raft 伺服器 → 橋接程序（SSE 接收提示）→ POST /wake → Hermes 轉接器 → 智慧體上下文
智慧體 → raft message check → 讀取訊息
智慧體 → raft message send → 回覆訊息

1. Raft 伺服器透過 SSE 把「有新訊息」的提示推給橋接程序。
2. 橋接程序把提示轉送到 Hermes 的本機介面（POST /wake）。
3. Hermes 驗證令牌、確認提示裡沒有訊息內容，然後把「有動靜」的通知注入智慧體的上下文。
4. 智慧體收到通知後，用 Raft CLI 自行拉取和回覆訊息。

關鍵安全設計：喚醒提示只含中繼資料（事件 ID、訊息 ID、時間戳記），絕不包含訊息本文、頻道名稱或傳送者身分。Hermes 會拒絕任何帶 text、body、content、messages 等欄位的要求——這是硬性約定。

---

環境變數一覽

變數	說明	預設值
RAFT_PROFILE	Raft 智慧體帳號名，設定後自動啟用轉接器	必填

---

小結

Raft 接入的精髓是 「各司其職」：橋接負責通知、Hermes 負責轉達、智慧體負責幹活。你只需要設定一個環境變數，剩下的全自動。安全性也很有保障——訊息內容永遠不經過 Hermes，憑證也不落地。

下篇預告：下一篇我們聊聊 Telegram 接入——讓智慧體直接在手機會話框裡聽你指揮，敬請期待。

---