MaiBot-iMessage-Adapter使用教程(详细版)
MaiBot-iMessage-Adapter使用教程(详细版)
彩咖工作室MaiBot-iMessage-Adapter 使用教程
本教程将引导你完成 MaiBot iMessage 适配器的配置，包括 Photon Spectrum 平台注册、插件安装与配置。
第一部分：Photon Spectrum 平台注册与配置
1. 什么是 Photon Spectrum
Photon Spectrum 是一个云端消息平台，通过在云端运行 macOS 虚拟机来桥接 Apple iMessage 服务。它提供了官方的 spectrum-ts SDK，MaiBot iMessage 适配器正是基于此 SDK 实现了与 iMessage 的双向消息收发。
简单来说，数据流是这样的：
1 | 你的 iPhone/iMessage 好友 ←→ Apple iMessage 服务器 ←→ Photon 云端 Mac ←→ spectrum-ts SDK ←→ 本插件 ←→ MaiBot |
费用说明：Photon 提供免费计划（Free Plan），适合个人使用和测试。免费计划有一定限制（如不支持电子邮件地址的 iMessage、不支持主动发起会话）。
2. 注册 Photon 账号
2.1 访问 Photon 官网
在浏览器中打开 https://app.photon.codes。
2.2 创建账号
点击页面上的 “Sign Up” 或 “Get Started” 按钮，进入注册页面。
填写以下信息：
- Email：你的邮箱地址
- Password：设置密码
点击 “Create Account” 完成注册。
在注册时需要绑定手机号码
2.3 验证邮箱
注册后，Photon 会向你的邮箱发送一封带有验证码的邮件。
打开邮件，使用验证码注册你的 Photon 账号。
2.4 登录
回到 https://app.photon.codes，使用刚才注册的邮箱和密码登录。
登录成功后，你将看到 Photon 控制台（Dashboard）。
因为我已经创建过了，第一次应该是什么都没有的 =)
3. 创建项目
3.1 进入项目创建页面
在控制台首页，点击 “New Project” 按钮。
3.2 填写项目信息
填写以下内容：
- Project Picture: 可以自己上传一张
- Project Name：项目名称，你想写啥就写啥
- LOCATION: United Status就行，因为没别的选项 :3
3.3 选择平台
Photon 提供多种平台SDK（Platforms)，对于我们这个插件，选择 iMessage/RCS 即可。
3.4 完成创建
点击 “Create Project” 确认创建。创建成功后，你会被自动导航到项目详情页面。
4. 获取项目凭证
项目创建完成后，你需要获取两个关键凭证：Project ID 和 Project Secret。这两个凭证是插件连接 Photon 的身份认证凭据。
4.1 找到凭证位置
在项目详情页面，找到 “Set it up manually” 区域，将它展开。
在 “Add your credentials” 标题下方可以看到你的 Project ID 和 Project Secret。
4.2 复制密钥
Project ID 是一个公开标识符，用于标识你的项目。它通常是一串字母数字组合。
点击 Project ID 旁边的复制按钮，将其保存下来。
Project Secret 是机密凭证，用于认证你的项目身份。请妥善保管，不要泄露给他人。
⚠️ 重要：Secret如果泄露，可以根据下面的指示生成新的。
点击复制按钮，将 Secret 保存下来。
5. 配置项目使用的号码
5.1 查看号码
在项目详情页面下翻，可以看到 “Run it and text your line” 标题，下面有一个肥肠醒目的号码 “ +1(xxx)xxx-xxxx”。
这个号码就是你的 MaiBot 在 iMessage 中的身份。
记下这个号码：格式为
+1xxxxxxxxxx，后续需要在 MaiBot 中配置。
5.2 (可选) 配置多用户
如果你需要使用多个号码与这个项目联系，你可以配置多用户，为每一个用户分配一个号码
点击左侧Spectrum下的Users，进入配置页面。你可以看到你注册时添加的电话号码，点击 “Add user” 按钮。
然后在Phone的那一栏选择 “+86” ，后面填入你的 “已经开启iMessage功能” 的手机号码。
你也可以填写邮箱，使用邮箱在Free订阅不可用哦.
6. 填入 MaiBot 插件配置
6.1 打开插件配置页面
在 MaiBot WebUI 中，进入 插件管理 → iMessage 连接器 / iMessage Adapter
→ 配置。
6.2 填写 Photon 云端配置
在 “Photon 云端” 配置区域：
| 字段 | 填入内容 |
|---|---|
| 项目 ID | 第 4.2 步中复制的 Project ID |
| 项目密钥 | 第 4.2 步中复制的 Project Secret |
在 “插件设置” 区域，将 “启用适配器” 开关打开。
6.3 配置 MaiBot 平台账号
你还需要在 MaiBot 的 bot_config.toml 添加 iMessage 平台账号，或者通过 WebUI 设置：
WebUI 方式：麦麦设置 → 基础 → 平台账号 → 点击加号 → 平台填写 "imessage" → 账号填写 Photon 分配的电话号码（如 +10000000000）
注意： 如果你在5.2步配置了多用户，那么每个用户都会被分配一个不同的号码，应该都需要填写。
新建多个 “imessage” 平台，填上分配的号码。
手动配置方式（bot_config.toml）：
1 | [bot] |
6.4 保存并重载
点击 “保存” 按钮，然后重载插件使配置生效，注意观察日志哦 :3
7. 首次使用注意事项
7.1 ⚠️ 必须先由对方发起首条消息
这是最容易踩坑的一点. Photon 免费计划不支持主动发起 iMessage 会话。
为什么? emmmm,去自己看官网 =)，直通车—-> 链接
你需要先用你的手机（或其他 iMessage 设备）向 Photon 分配的电话号码发送一条消息，之后 MaiBot 才能回复你。
如果不这样做，插件日志会出现
AuthenticationError: [spectrum-imessage] Target not allowed for this project错误。
7.2 免费计划的其他限制
| 限制项 | 说明 |
|---|---|
| 不支持电子邮件 iMessage | 只能使用手机号码的 iMessage |
| 不支持主动发起会话 | 必须用户先发消息 |
7.3 验证连接
在iMessage对话中发送 /imessage_status 命令，确认可以收到回复。
8. 常见问题
Q: 注册时收不到验证邮件？
检查垃圾邮件文件夹。如果仍未收到，可以尝试重新发送验证邮件，或更换邮箱注册。
Q: Project Secret 丢失了怎么办？
在 Photon 控制台的项目凭证页面，可以重新生成新的 Secret（旧 Secret 会立即失效）。生成后记得更新 MaiBot 插件配置。
Q: 提示 “Target not allowed for this project”？
这说明你还没有通过 iMessage 向 Photon 号码发送首条消息。
如果是多用户，都要这样操作。
注意： 不同的用户会被分配不同的号码哦，发送的时候注意下.
Q: 免费计划可以升级吗？
可以。在 Photon 控制台的 Billing 页面可以升级到付费计划。付费计划支持更多功能和更高的消息限额。
很贵喵
9. 目前缺陷
目前已知有几个功能缺陷，我在努力修了
1. iMessage 消息不支持语音和实况图片。(因为语音消息是苹果专用的格式,麦麦无法识别，实况图片的
HEIC麦麦同样无法识别. )
2. 待收集使用反馈，欢迎提Issue Issue链接
鸣谢：
我自己
我的电脑
VS Code
开源社区
许可证:
本项目基于 GPL-3.0 许可证开源。
