跳到主要内容

Photon iMessage

通过 Photon 将 Kopi Agent 接入 iMessage。Photon 是一项托管服务,负责处理 Apple 线路分配和滥用防护层,因此你无需自己运行 Mac 中继。

免费层使用 Photon 的共享 iMessage 线路池——不同收件人可能会看到不同的发送号码,但每个会话保持稳定。付费的 Business 层为每个用户提供固定的专属号码;插件同时支持两者,推荐从免费层开始使用。

免费起步

Photon 的共享线路池是免费的。从 Kopi Agent 发送第一条 iMessage 无需订阅——只需提供一个可绑定到你账户的电话号码。

架构​

Photon 是一个持久连接频道,与 Discord 或 Slack 类似——无需 webhook、无需公开 URL、无需管理签名密钥。

spectrum-ts SDK 通过双向长驻 gRPC 流与 Photon 通信。由于该 SDK 仅支持 TypeScript,Kopi Agent 会在一个受监管的小型 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 注册
  • PATH 中安装 Node.js 18.17 或更新版本(node --version)
  • 一个可接收 iMessage 的电话号码(用于绑定你的账户)

就这些——无需设置公开 URL 或隧道。

首次设置​

可以运行统一的网关向导并选择 Photon iMessage:

kopi gateway setup

…也可以直接运行 Photon 设置流程(向导调用的是同一个流程):

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

设置流程按顺序进行:

  1. 设备登录(client_id=photon-cli)——打开 https://app.photon.codes/ 进行授权,并存储 bearer token。
  2. 查找或创建你账户下的 KOPI AI AGENT 项目。
  3. 启用 Spectrum,读取该项目的 Spectrum id,并轮换项目密钥。
  4. 注册你的电话号码为 Spectrum 用户——如果该号码对应的用户已存在则跳过,因此重复运行是安全的。
  5. 打印分配给你的 iMessage 线路——即你用来联系 agent 的号码。
  6. 在插件的 sidecar 目录中运行 npm install。

运行时凭据会写入 ~/.kopi/.env(PHOTON_PROJECT_ID = Spectrum 项目 id,PHOTON_PROJECT_SECRET),其他所有频道也将 token 保存在同一位置。管理元数据(设备 token、dashboard 项目 id)保存在 ~/.kopi/auth.json 下的 credential_pool.photon / credential_pool.photon_project 中。

授权用户​

Photon 使用与 Kopi Agent 其他所有频道相同的授权模型。选择一种方式:

DM 配对(默认)。 当未知号码向你的 Photon 线路发送消息时,Kopi Agent 会回复一个配对码。使用以下命令批准:

kopi pairing approve photon <CODE>

使用 kopi pairing list 查看待处理的配对码和已批准的用户。

预授权特定号码(在 ~/.kopi/.env 中):

PHOTON_ALLOWED_USERS=+15551234567,+15559876543

开放访问(仅限开发环境,在 ~/.kopi/.env 中):

PHOTON_ALLOW_ALL_USERS=true

当设置了 PHOTON_ALLOWED_USERS 时,未知发送者会被静默忽略,而不会收到配对码(因为白名单表明你已主动限制了访问权限)。

在群聊中要求 @ 提及​

默认情况下,Kopi Agent 会响应每条来自已授权用户的 DM 和群消息。若要让群聊采用选择加入模式,请启用提及门控(DM 始终有效):

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

启用 require_mention: true 后,群聊消息除非匹配唤醒词模式,否则会被忽略。默认模式匹配 Kopi Agent 和 @Kopi Agent 变体。若使用自定义 agent 名称,请设置正则表达式模式:

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

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

启动网关​

kopi gateway start

你会看到类似如下内容:

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

向分配给你的号码发送 iMessage,Kopi Agent 就会回复。

状态与故障排查​

kopi photon status

打印已保存的凭据、sidecar 健康状态、你注册的号码,以及 Kopi Agent 使用的已分配 iMessage 线路。当 Photon token 和 dashboard 项目可用时,status 会从 dashboard 刷新缺失的号码行,而不会配置新线路。

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 kopi photon install-sidecar — Node 已安装但未安装 spectrum-ts。请运行提示的命令。
  • device token : ✗ missing — 运行 kopi photon setup 进行登录。
  • No iMessage line assigned yet — Spectrum 已启用但尚未配置线路;请重新运行 kopi photon setup 或查看 dashboard。
  • Sidecar 无法启动 — 确认 node --version 版本为 18.17 以上,并且 kopi photon install-sidecar 在无错误的情况下完成。

当前的限制​

  • 入站附件仅包含元数据。 入站事件携带文件名 + MIME 类型;agent 可以看到标记,但尚无法读取实际字节内容。SDK 通过 content.read() 暴露附件字节,因此这属于 sidecar 的后续改进项。
  • 支持出站附件。 Kopi Agent 通过 sidecar 的 /send-attachment 端点,使用 spectrum-ts 的 attachment() / voice() 内容构建器发送图片、语音消息、视频和文档。说明文字会在媒体之后以单独的 iMessage 气泡发送。
  • Photon 的免费配额: 每个服务器每天 5,000 条消息,每条共享线路每天 50 次新会话发起。如需提升配额,请发送邮件至 help@photon.codes。

环境变量​

变量默认值说明
PHOTON_PROJECT_IDfrom .envSpectrum 项目 id(即 SDK 的 projectId);由 setup 设置
PHOTON_PROJECT_SECRETfrom .env项目密钥;由 setup 设置
PHOTON_SIDECAR_PORT8789sidecar 控制通道 + 入站通道的回环端口
PHOTON_SIDECAR_AUTOSTARTtrue适配器是否生成 sidecar
PHOTON_NODE_BINwhich node覆盖 Node 二进制文件路径
PHOTON_HOME_CHANNEL(unset)cron / 通知使用的默认 space id
PHOTON_HOME_CHANNEL_NAME(unset)主频道的人类可读标签
PHOTON_ALLOWED_USERS(unset)逗号分隔的 E.164 允许列表
PHOTON_ALLOW_ALL_USERSfalse仅限开发环境 — 接受任意发送者
PHOTON_REQUIRE_MENTIONfalse在群组中响应前需要唤醒词
PHOTON_MENTION_PATTERNSKopi Agent 唤醒词群组提及时使用的 JSON 列表 / 逗号分隔 / 换行分隔的正则表达式模式
PHOTON_DASHBOARD_HOSTapp.photon.codes覆盖仪表板 / 设备登录主机
PHOTON_SPECTRUM_HOSTspectrum.photon.codes覆盖 Spectrum API 主机