Photon iMessage

通過 Photon 將 Hermes 連接到 iMessage。Photon 是一項託管服務，負責處理 Apple 線路分配和防濫用層，因此你無需運行自己的 Mac 中繼。

免費層級使用 Photon 的共享 iMessage 線路池——不同的收件人可能會看到不同的發送號碼，但每個對話保持穩定。付費的 Business 層級為每個用戶提供相同的專用號碼；該插件同時支持這兩種模式，建議從免費層級開始。

免費起步

Photon 的共享線路池是免費的。從 Hermes 發送第一條 iMessage 不需要訂閱——只需要一個我們可以綁定到你賬戶的電話號碼。

架構

Photon 是一個持久連接通道，類似於 Discord 或 Slack——無需 webhook、無需公共 URL、無需管理簽名密鑰。

spectrum-ts SDK 與 Photon 之間保持一個雙向的長生命週期 gRPC 流。由於該 SDK 僅支持 TypeScript，Hermes 在一個小型受監督的 Node 邊車（sidecar） 中運行它，並通過環回接口與其通信：

入站（Inbound）——邊車消費 SDK 的 app.messages gRPC 流，並通過環回 GET /inbound（NDJSON格式）將每條消息轉發給 Python 適配器。適配器對消息進行去重並分發給 agent，如果流斷開則自動重新連接。
出站（Outbound）——回覆通過環回 POST 請求發送給邊車，邊車調用 SDK 上的 space.send(...)。

Python 插件會自動啟動、監督並關閉邊車。

前置條件

一個 Photon 賬戶——在 app.photon.codes 註冊
PATH 中存在 Node.js 18.17 或更高版本（node --version）
一個可以接收 iMessage 的電話號碼（用於綁定你的賬戶）

僅此而已——無需設置公共 URL 或隧道。

首次設置

運行統一網關嚮導並選擇 Photon iMessage：

hermes gateway setup

……或者直接運行 Photon 設置（嚮導調用的是相同的流程）：

# Device-code login + project + user + sidecar deps, all in one
hermes photon setup --phone +15551234567

設置步驟如下：

設備登錄（client_id=photon-cli）——打開 https://app.photon.codes/ 進行授權並存儲 bearer token。
查找或創建你賬戶下的 Hermes Agent 項目。
啟用 Spectrum，讀取項目的 Spectrum id，並輪換項目密鑰。
註冊你的電話號碼作為 Spectrum 用戶——如果已存在具有該號碼的用戶，則跳過此步驟，因此重複運行是安全的。
打印分配給你的 iMessage 線路——即你用來聯繫 agent 的短信號碼。
在插件的邊車目錄中運行 npm install。

運行時憑證寫入 ~/.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 時，未知發送者將被靜默忽略，而不是提供配對碼（允許列表表明你有意限制了訪問權限）。

在群聊中要求提及（Mention）

默認情況下，Hermes 會響應每個已授權的 DM 和群消息。要使群聊變為選擇加入模式，請啟用提及 gating（DM 仍然始終有效）：

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 通道使用的提及 gating 模型相同。

啟動網關

hermes gateway start

你將看到類似以下內容：

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

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

狀態與故障排除

hermes photon status

打印保存的憑證、邊車健康狀態、你註冊的號碼以及 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 或檢查 dashboard。
Sidecar 無法啟動 — 確認 node --version 為 18.17+，且 hermes photon install-sidecar 已完成且無錯誤。

當前限制

入站附件僅包含元數據。 入站事件攜帶文件名 + MIME 類型；代理可以看到標記，但尚無法讀取字節。SDK 通過 content.read() 暴露附件字節，因此這是 sidecar 的後續跟進事項。
支持出站附件。 Hermes 通過 sidecar 的 /send-attachment 端點，利用 spectrum-ts 的 attachment() / voice() 內容構建器發送圖片、語音筆記、視頻和文檔。標題作為單獨的 iMessage 氣泡在媒體之後到達。
Photon 的免費配額： 每臺服務器每天 5,000 條消息，每條共享線路每天 50 次新對話發起。如需增加配額，請發送郵件至 help@photon.codes。

環境變量

變量	默認值	說明
`PHOTON_PROJECT_ID`	來自 `.env`	Spectrum 項目 ID（SDK 的 `projectId`）；由 setup 設置
`PHOTON_PROJECT_SECRET`	來自 `.env`	項目密鑰；由 setup 設置
`PHOTON_SIDECAR_PORT`	`8789`	Sidecar 控制 + 入站通道的環回端口
`PHOTON_SIDECAR_AUTOSTART`	`true`	適配器是否生成 sidecar
`PHOTON_NODE_BIN`	`which node`	覆蓋 Node 二進制文件路徑
`PHOTON_HOME_CHANNEL`	(未設置)	Cron / 通知的默認空間 ID
`PHOTON_HOME_CHANNEL_NAME`	(未設置)	Home 通道的人類可讀標籤
`PHOTON_ALLOWED_USERS`	(未設置)	逗號分隔的 E.164 允許列表
`PHOTON_ALLOW_ALL_USERS`	`false`	僅限開發環境 — 接受任何發送者
`PHOTON_REQUIRE_MENTION`	`false`	在群組中響應前需要喚醒詞
`PHOTON_MENTION_PATTERNS`	Hermes 喚醒詞	用於群組提及的 JSON 列表 / 逗號 / 換行正則表達式模式
`PHOTON_DASHBOARD_HOST`	`app.photon.codes`	覆蓋 dashboard / 設備登錄主機
`PHOTON_SPECTRUM_HOST`	`spectrum.photon.codes`	覆蓋 Spectrum API 主機

架構​

前置條件​

首次設置​

授權用戶​

在群聊中要求提及（Mention）​

啟動網關​

狀態與故障排除​

當前限制​

環境變量​

架構