<!-- Source: https://hermesbible.com/docs/user-guide/messaging/photon -->

章節：訊息平台 · 網址：https://hermesbible.com/docs/user-guide/messaging/photon

Photon iMessage

透過 Photon 將 Hermes 連接到 iMessage，這是一項託管服務，負責處理 Apple 路線分配與濫用防護機制，讓你無需自行架設 Mac 中繼器。

免費方案使用 Photon 的共享 iMessage 路線池 — 不同收件者可能會看到不同的發送號碼，但每個對話都會保持穩定。付費的 Business 方案則為每位使用者提供專屬的固定號碼；此插件支援兩種方案，建議從免費方案開始使用。

免費即可開始

Photon 的共享路線池免費提供。無需訂閱即可透過 Hermes 發送第一則 iMessage — 只需提供一個可綁定的電話號碼。

架構

Photon 是一個持久連線的頻道，類似 Discord 或 Slack — 無需設定 webhook、公開網址或簽章密鑰。

spectrum-ts SDK 與 Photon 之間維持一個長期的 gRPC 串流，負責雙向通訊。由於 SDK 僅支援 TypeScript，Hermes 透過一個小型的監督式 Node sidecar 來運行它，並透過 loopback 進行通訊：

• 接收 — sidecar 讀取 SDK 的 app.messages gRPC 串流，並將每則訊息透過 loopback 的 GET /inbound（NDJSON）轉送給 Python 適配器。適配器進行去重後將訊息分派給 agent，若串流失敗則自動重連。
• 傳送 — 回覆透過 loopback POST 發送到 sidecar，由 sidecar 呼叫 SDK 的 space.send(...)。

Python 插件會自動啟動、監控並關閉 sidecar。

先決條件

• 一個 Photon 帳號 — 在 app.photon.codes 註冊
• Node.js 18.17 或更新版本（需在 PATH 中，執行 node --version 確認）
• 一個可以接收 iMessage 的電話號碼（用於綁定帳號）

就這樣 — 不需要設定任何公開網址或隧道。

首次設定

執行統一的閘道器設定精靈並選擇 Photon iMessage：

hermes gateway setup

…或直接執行 Photon 設定（精靈呼叫的是相同的流程）：

# Device-code 登入 + 專案 + 使用者 + sidecar 依賴，一步完成
hermes photon setup --phone +15551234567

設定流程依序為：

1. 裝置登入（client_id=photon-cli）— 開啟 https://app.photon.codes/ 進行授權，並儲存 bearer token。
2. 尋找或建立 帳號中的 Hermes Agent 專案。
3. 啟用 Spectrum，讀取專案的 Spectrum id，並輪替專案密鑰。
4. 註冊你的電話號碼 為 Spectrum 使用者 — 若該號碼已有使用者，則會跳過此步驟，因此重複執行是安全的。
5. 顯示分配給你的 iMessage 號碼 — 用來與 agent 通訊的號碼。
6. 執行 npm install 在插件的 sidecar 目錄中。

運行時的認證資訊寫入 ~/.hermes/.env（PHOTON_PROJECT_ID = Spectrum 專案 id，PHOTON_PROJECT_SECRET），與其他頻道儲存 token 的位置相同。管理中繼資料（裝置 token、儀表板專案 id）則儲存在 ~/.hermes/auth.json 的 credential_pool.photon / credential_pool.photon_project 下。

授權使用者

Photon 使用與其他所有 Hermes 頻道相同的授權模型。擇一使用：

DM 配對（預設）。 當未知號碼向你的 Photon 號碼發送訊息時，Hermes 會回覆一組配對碼。執行以下指令進行核准：

hermes pairing approve photon <CODE>

使用 hermes pairing list 查看待處理的配對碼和已核准的使用者。

預先授權特定號碼（在 ~/.hermes/.env 中設定）：

PHOTON_ALLOWED_USERS=+15551234567,+15559876543

開放存取（僅限開發用途，在 ~/.hermes/.env 中設定）：

PHOTON_ALLOW_ALL_USERS=true

當設定 PHOTON_ALLOWED_USERS 時，未知的發送者會被靜默忽略，而不會收到配對碼邀請（允許清單表示你有意限制存取）。

群組聊天室要求提及

預設情況下，Hermes 會回應所有已授權的私人訊息和群組訊息。若要讓群組聊天室成為選擇性參與，請啟用提及觸發功能（私人訊息仍會正常運作）：

gateway:
  platforms:
    photon:
      enabled: true
      require_mention: true

設定 require_mention: true 後，群組訊息會被忽略，除非它們符合喚醒詞模式。預設的喚醒詞匹配 Hermes 和 @Hermes agent 的變體。若要使用自訂的 agent 名稱，請設定正則表達式模式：

gateway:
  platforms:
    photon:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

這兩個設定也支援環境變數（PHOTON_REQUIRE_MENTION、PHOTON_MENTION_PATTERNS）。這與 BlueBubbles iMessage 頻道使用的提及觸發模式相同。

啟動閘道器

hermes gateway start

你會看到類似以下的輸出：

[photon] connected — sidecar on 127.0.0.1:8789, streaming inbound over gRPC

向你分配的號碼發送 iMessage，Hermes 就會回覆。

狀態與問題排除

hermes photon status

顯示已儲存的認證資訊、sidecar 健康狀態、你註冊的號碼，以及 Hermes 使用的 iMessage 分配號碼。當 Photon token 和儀表板專案可用時，status 會從儀表板刷新缺少的號碼資訊，而無需重新配置新的號碼。

Photon iMessage status
──────────────────────
  device token        : ✓ stored
  dashboard project   : 3c90c3cc-0d44-4b50-...
  spectrum project id : sp-...
  project secret      : ✓ stored
  my number           : +15551234567
  assigned number     : +16282679185
  node binary         : /usr/bin/node
  sidecar deps        : ✓ installed

常見問題：

• sidecar deps : ✗ run hermes photon install-sidecar — Node 已安裝但 spectrum-ts 尚未安裝。執行提示的指令即可。
• device token : ✗ missing — 執行 hermes photon setup 進行登入。
• No iMessage line assigned yet — Spectrum 已啟用但尚未配置號碼；重新執行 hermes photon setup 或到儀表板確認。
• Sidecar 無法啟動 — 確認 node --version 為 18.17 以上，且 hermes photon install-sidecar 已成功完成。

目前的限制

• 接收的附件僅支援中繼資料。 接收的事件僅包含檔名和 MIME 類型；agent 能看到標記但目前無法讀取實際內容。SDK 已透過 content.read() 暴露附件內容，因此這是後續可補充的功能。
• 支援傳送附件。 Hermes 可透過 spectrum-ts 的 attachment() / voice() 內容建構器，透過 sidecar 的 /send-attachment 端點傳送圖片、語音訊息、影片和文件。說明文字會在媒體之後以獨立的 iMessage 訊息泡送出。
• Photon 免費額度： 每個伺服器每天 5,000 則訊息，每條共享路線每天 50 個新對話。可申請提高額度 — 來信至 help@photon.codes。

環境變數

---

---

QQ Bot