hermes教程-Photon iMessage

Photon iMessage

通过 Photon 将 Hermes 连接到 iMessage，这是一个托管服务，负责处理 Apple 线路分配和滥用防护层，因此您无需运行自己的 Mac 中继。

免费层使用 Photon 的共享 iMessage 线路池——不同的收件人可能会看到不同的发送号码，但每个对话保持稳定。付费商业层为每个用户提供相同的专用号码；插件同时支持两者，免费层是推荐的起点。

信息 — 免费开始

Photon 的共享线路池是免费的。无需订阅即可从 Hermes 发送第一条 iMessage——只需一个我们可以绑定到您账户的电话号码。

架构

Photon 是一个持久连接通道，类似于 Discord 或 Slack——无需 webhook、无需公共 URL、无需管理签名密钥。

spectrum-ts SDK 持有一个长期存在的 gRPC 流 与 Photon 进行双向通信。由于 SDK 仅支持 TypeScript，Hermes 在一个小型受监督的 Node 边车 中运行它，并通过回环进行通信：

• 入站 — 边车消费 SDK 的 app.messages gRPC 流，并通过回环 GET /inbound（NDJSON）将每条消息转发到 Python 适配器。适配器去重并将其分发给代理，如果流断开则自动重新连接。
• 出站 — 回复通过回环 POST 到边车，边车调用 SDK 的 space.send(...)。

Python 插件自动启动、监督和关闭边车。

前提条件

• 一个 Photon 账户 — 在 app.photon.codes 注册
• Node.js 18.17 或更新版本 在 PATH 中（node --version）
• 一个可以接收 iMessage 的电话号码（用于绑定您的账户）

仅此而已——无需设置公共 URL 或隧道。

首次设置

运行统一网关向导并选择 Photon iMessage：

hermes gateway setup

…或直接运行 Photon 设置（向导调用相同的流程）：

## 设备码登录 + 项目 + 用户 + 边车依赖，一步完成
hermes photon setup --phone +15551234567

设置顺序：

1. 设备登录（client_id=photon-cli）— 打开 https://app.photon.codes/ 进行授权，并存储 bearer 令牌。
2. 查找或创建 您账户上的 Hermes Agent 项目。
3. 启用 Spectrum，读取项目的 Spectrum ID，并轮换项目密钥。
4. 将您的电话号码注册 为 Spectrum 用户 — 如果已存在具有该号码的用户则跳过，因此重新运行是安全的。
5. 打印您分配的 iMessage 线路 — 您发送短信以联系代理的号码。
6. 在插件的边车目录中运行 npm install。

运行时凭据写入 ~/.hermes/.env（PHOTON_PROJECT_ID = Spectrum 项目 ID，PHOTON_PROJECT_SECRET），与其他通道存储令牌的位置相同。管理元数据（设备令牌、仪表板项目 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 响应每个授权的 DM 和群组消息。要使群聊选择加入，启用提及门控（DM 仍然始终有效）：

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

使用 require_mention: true，群聊消息会被忽略，除非它们匹配唤醒词模式。默认匹配 Hermes 和 @Hermes agent 变体。对于自定义代理名称，设置正则表达式模式：

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

两个键也接受环境变量（PHOTON_REQUIRE_MENTION、PHOTON_MENTION_PATTERNS）。这与 BlueBubbles iMessage 通道使用的提及门控模型相同。

启动网关

hermes gateway start

您会看到类似：

向您分配的号码发送一条 iMessage，Hermes 将回复。

状态与故障排除

hermes photon status

打印已保存的凭据、边车健康状态、您注册的号码以及 Hermes 使用的分配 iMessage 线路。当 Photon 令牌和仪表板项目可用时，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 或检查 仪表板。
• 边车无法启动 — 确认 node --version 为 18.17+，并且 hermes photon install-sidecar 已完成且无错误。

当前限制

• 入站附件仅包含元数据。 入站事件携带文件名 + MIME 类型；代理会看到一个标记，但尚无法读取字节。SDK 通过 content.read() 暴露附件字节，因此这是边车的后续改进。
• 出站附件受支持。 Hermes 通过 spectrum-ts 的 attachment() / voice() 内容构建器，经由边车的 /send-attachment 端点发送图片、语音笔记、视频和文档。说明文字在媒体之后作为单独的 iMessage 气泡到达。
• Photon 的免费配额： 每个服务器每天 5,000 条消息，每个共享线路每天 50 次新对话发起。可增加 — 发送邮件至 [email protected]。

环境变量