chat-adapter-imessage

Vercel AI SDK：iMessage 适配器技能

本技能提供了使用 chat-adapter-imessage 的完整参考。它是 Photon 官方适配器，可将 Vercel AI SDK (Chat SDK) 连接到 iMessage。

概览

该适配器充当桥梁，让你能够使用 Vercel AI SDK 构建 AI Agent 和助手，并通过 iMessage 与用户交流。它在底层使用 @photon-ai/imessage-kit（可自托管）和 @photon-ai/advanced-imessage-kit（由 Photon 提供的生产基础设施）。

主要功能

• 两种模式： 开发时可在任意 Mac 上以本地模式运行，也可连接到 Photon 的生产级 iMessage 基础设施，以远程模式运行。
• 统一接口： 无论底层使用哪种模式，都提供一致的消息收发 API。
• Vercel AI SDK 集成： 实现 chat 包中的 Adapter 接口，可直接作为即插即用的解决方案。
• Markdown 转换： 自动将 AI SDK 中的 Markdown 转换为兼容 iMessage 的纯文本。

---

设置与初始化

安装

pnpm install chat-adapter-imessage @photon-ai/imessage-kit
# For remote mode, also install the advanced kit
pnpm install @photon-ai/advanced-imessage-kit

createiMessageAdapter(config)

这是主要入口点，用于创建并配置 iMessageAdapter 实例。

import { createiMessageAdapter } from 'chat-adapter-imessage';

// Local Mode: Runs on your Mac, uses your iMessage
const localAdapter = createiMessageAdapter({ local: true });

// Remote Mode: Connects to Photon's production servers
const remoteAdapter = createiMessageAdapter({
  local: false,
  serverUrl: process.env.IMESSAGE_SERVER_URL, // Provided by Photon
  apiKey: process.env.IMESSAGE_API_KEY      // Provided by Photon
});

配置（iMessageAdapterConfig）

模式	local	serverUrl	apiKey	说明
本地	true	可选	可选	在 macOS 上使用 @photon-ai/imessage-kit 运行。serverUrl 和 apiKey 会被忽略。
远程	false	必填	必填	使用 @photon-ai/advanced-imessage-kit 连接到 Photon 的基础设施。

与 Chat 集成

创建适配器后，将其传入 Vercel AI SDK 的 Chat 构造函数。

import { Chat } from 'chat';
import { createiMessageAdapter } from 'chat-adapter-imessage';

const adapter = createiMessageAdapter({ local: true });

const chat = new Chat({
  adapter,
  // ... your other Chat config
});

---

核心适配器方法

adapter.initialize(chat)

由 Chat 实例调用，用于关联适配器。在远程模式下，此方法还会建立与 Photon 服务的 WebSocket 连接。

adapter.postMessage(threadId, message)

向指定的 iMessage 话题发送消息。

• threadId：编码后的话题标识符，即 chatGuid（例如 iMessage;-;+15551234567）。
• message：AdapterPostableMessage 对象，可以是简单字符串，也可以是包含 Markdown 的 FormattedContent 对象。

const threadId = 'iMessage;-;+15551234567'; // A direct message thread

// Send a simple text message
await adapter.postMessage(threadId, 'Hello from the adapter!');

// Send a message with markdown (will be converted to plain text)
await adapter.postMessage(threadId, {
  markdown: 'Here are the results:\n\n- **Item 1**\n- *Item 2*'
});

adapter.editMessage(threadId, messageId, message)

编辑已发送的消息。仅支持远程模式。

await adapter.editMessage(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-EDIT',
  'This is the corrected text.'
);

adapter.deleteMessage(threadId, messageId)

撤回或删除已发送的消息。仅支持远程模式。

await adapter.deleteMessage(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-DELETE'
);

adapter.react(threadId, messageId, emoji)

为消息添加 Tapback 表情回应。仅支持远程模式。

• emoji：标准表情符号字符，或 heart、like、laugh 之类的名称。

await adapter.react(
  'iMessage;-;+15551234567',
  'p:0/GUID-OF-MESSAGE-TO-REACT-TO',
  '❤️'
);

adapter.startGatewayListener(options)

这是接收消息的主要方法。它会启动一个监听器，从本地和远程 SDK 接收消息，并将消息转发给 Chat 实例。

// In your main application file

const adapter = createiMessageAdapter({ local: true });
const chat = new Chat({ adapter });

// Start listening for incoming iMessages
adapter.startGatewayListener();

// Now, messages sent to your iMessage will be processed by the Chat SDK
chat.on('message', (message) => {
  console.log(`[${message.author.userName}]: ${message.text}`);
  // Your AI logic here...
});

adapter.handleWebhook(request)

**此方法不受支持。**该适配器不使用传统 Webhook 接收消息。你必须改用 startGatewayListener()。

---

类型参考

iMessageThreadId

解码后的 threadId 对象。

interface iMessageThreadId {
  chatGuid: string; // e.g., "iMessage;-;+1234567890"
}

iMessageGatewayMessageData

适配器内部使用的标准化消息对象。

interface iMessageGatewayMessageData {
  guid: string;
  text: string | null;
  sender: string;
  senderName: string | null;
  chatId: string;
  isGroupChat: boolean;
  isFromMe: boolean;
  date: string; // ISO 8601
  attachments: iMessageAttachment[];
  source: 'local' | 'remote';
  raw?: unknown; // Original message object from the underlying SDK
}

NativeWebhookPayload

如果使用 Self-Hosted Kit 的原生 Webhook 功能，这就是发送到你的端点的 JSON 负载结构。适配器可以处理此负载。

interface NativeWebhookPayload {
  guid: string;
  text: string | null;
  sender: string;
  chatId: string;
  // ... and other fields from the Basic Kit Message object
}

---

参考资料

1. Vercel AI SDK (Chat)
2. npm 上的 chat-adapter-imessage
3. Photon