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）​

启动网关​

状态与故障排除​

当前限制​

环境变量​

架构