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.messagesgRPC 流,并通过 loopbackGET /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
设置流程按顺序进行:
- 设备登录(
client_id=photon-cli)——打开https://app.photon.codes/进行授权,并存储 bearer token。 - 查找或创建你账户下的
KOPI AI AGENT项目。 - 启用 Spectrum,读取该项目的 Spectrum id,并轮换项目密钥。
- 注册你的电话号码为 Spectrum 用户——如果该号码对应的用户已存在则跳过,因此重复运行是安全的。
- 打印分配给你的 iMessage 线路——即你用来联系 agent 的号码。
- 在插件的 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_ID | from .env | Spectrum 项目 id(即 SDK 的 projectId);由 setup 设置 |
PHOTON_PROJECT_SECRET | from .env | 项目密钥;由 setup 设置 |
PHOTON_SIDECAR_PORT | 8789 | sidecar 控制通道 + 入站通道的回环端口 |
PHOTON_SIDECAR_AUTOSTART | true | 适配器是否生成 sidecar |
PHOTON_NODE_BIN | which node | 覆盖 Node 二进制文件路径 |
PHOTON_HOME_CHANNEL | (unset) | cron / 通知使用的默认 space id |
PHOTON_HOME_CHANNEL_NAME | (unset) | 主频道的人类可读标签 |
PHOTON_ALLOWED_USERS | (unset) | 逗号分隔的 E.164 允许列表 |
PHOTON_ALLOW_ALL_USERS | false | 仅限开发环境 — 接受任意发送者 |
PHOTON_REQUIRE_MENTION | false | 在群组中响应前需要唤醒词 |
PHOTON_MENTION_PATTERNS | Kopi Agent 唤醒词 | 群组提及时使用的 JSON 列表 / 逗号分隔 / 换行分隔的正则表达式模式 |
PHOTON_DASHBOARD_HOST | app.photon.codes | 覆盖仪表板 / 设备登录主机 |
PHOTON_SPECTRUM_HOST | spectrum.photon.codes | 覆盖 Spectrum API 主机 |