chat-sdk

Chat SDK

用于在 Slack、Teams、Google Chat、Discord、Telegram、GitHub、Linear 和 WhatsApp 上构建聊天机器人的统一 TypeScript SDK。只需编写一次机器人逻辑，即可部署到所有平台。

从已发布的源文件开始

在用户项目中安装 Chat SDK 后，请检查随包发布在 node_modules 中的文件：

node_modules/chat/docs/                    # bundled docs
node_modules/chat/dist/index.d.ts          # core API types
node_modules/chat/dist/jsx-runtime.d.ts    # JSX runtime types
node_modules/chat/docs/contributing/       # adapter-authoring docs
node_modules/chat/docs/guides/             # framework/platform guides

如果以下路径中有任何一个不存在，说明项目中尚未安装对应的包。

编写代码前，请先阅读：

• node_modules/chat/docs/getting-started.mdx — 安装和设置
• node_modules/chat/docs/usage.mdx — Chat 配置和生命周期
• node_modules/chat/docs/handling-events.mdx — 事件路由和处理程序
• node_modules/chat/docs/threads-messages-channels.mdx — 线程／频道／消息模型
• node_modules/chat/docs/posting-messages.mdx — 发布、编辑、删除和定时发送消息
• node_modules/chat/docs/streaming.mdx — AI SDK 集成和流式传输语义
• node_modules/chat/docs/cards.mdx — JSX 卡片
• node_modules/chat/docs/actions.mdx — 按钮／选择交互
• node_modules/chat/docs/modals.mdx — 模态框提交／关闭流程
• node_modules/chat/docs/slash-commands.mdx — 斜杠命令路由
• node_modules/chat/docs/direct-messages.mdx — 私信行为和 openDM()
• node_modules/chat/docs/files.mdx — 附件／上传
• node_modules/chat/docs/state.mdx — 持久化、锁定、去重
• node_modules/chat/docs/adapters.mdx — 跨平台功能矩阵
• node_modules/chat/docs/api/chat.mdx — 完整的 Chat API
• node_modules/chat/docs/api/thread.mdx — 完整的 Thread API
• node_modules/chat/docs/api/message.mdx — 完整的 Message API
• node_modules/chat/docs/api/modals.mdx — 模态框元素和事件详情

对于你要使用的特定适配器或状态包，请检查 node_modules 中该已安装包的 dist/index.d.ts 导出内容。

快速开始

import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createRedisState } from "@chat-adapter/state-redis";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    slack: createSlackAdapter(),
  },
  state: createRedisState(),
  dedupeTtlMs: 600_000,
});

bot.onNewMention(async (thread) => {
  await thread.subscribe();
  await thread.post("Hello! I'm listening to this thread.");
});

bot.onSubscribedMessage(async (thread, message) => {
  await thread.post(`You said: ${message.text}`);
});

核心概念

• Chat — 主入口；负责协调适配器、路由、锁和状态
• Adapters — 针对 Slack、Teams、Google Chat、Discord、Telegram、GitHub、Linear 和 WhatsApp 的平台专属集成
• State adapters — 用于持久化订阅、锁、去重数据和线程状态
• Thread — 对话上下文，包含 post()、stream()、subscribe()、setState()、startTyping()
• Message — 规范化内容，包含 text、formatted、附件、作者信息和平台 raw
• Channel — 用于容纳线程和顶层帖子的容器

事件处理程序

处理程序	触发条件
onNewMention	机器人在未订阅的线程中被 @提及
onDirectMessage	在未订阅的私信线程中收到新私信
onSubscribedMessage	收到已订阅线程中的任何消息
onNewMessage(regex)	在未订阅的线程中匹配正则表达式
onReaction(emojis?)	添加或移除表情符号
onAction(actionIds?)	点击按钮以及选择／单选交互
onModalSubmit(callbackId?)	提交模态框表单
onModalClose(callbackId?)	关闭／取消模态框
onSlashCommand(commands?)	调用斜杠命令
onAssistantThreadStarted	打开 Slack 助手线程
onAssistantContextChanged	Slack 助手上下文已更改
onAppHomeOpened	打开 Slack App Home
onMemberJoinedChannel	Slack 成员加入频道事件

在接入处理程序前，请先阅读 node_modules/chat/docs/handling-events.mdx、node_modules/chat/docs/actions.mdx、node_modules/chat/docs/modals.mdx 和 node_modules/chat/docs/slash-commands.mdx。onDirectMessage 的行为记录在 node_modules/chat/docs/direct-messages.mdx 中。

流式传输

将任意 AsyncIterable<string> 传递给 thread.post() 或 thread.stream()。对于 AI SDK，如果可用，优先使用 result.fullStream 而不是 result.textStream，以保留步骤边界。

import { ToolLoopAgent } from "ai";

const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" });

bot.onNewMention(async (thread, message) => {
  const result = await agent.stream({ prompt: message.text });
  await thread.post(result.fullStream);
});

关键细节：

• streamingUpdateIntervalMs 控制「发布 + 编辑」回退频率
• fallbackStreamingPlaceholderText 默认为 "..."；设置为 null 可禁用
• 结构化 StreamChunk 支持仅限 Slack；其他适配器会忽略非文本块

卡片和模态框（JSX）

在 tsconfig.json 中设置 jsxImportSource: "chat"。

卡片组件：

• Card、CardText、Section、Fields、Field、Button、CardLink、LinkButton、Actions、Select、SelectOption、RadioSelect、Table、Image、Divider

模态框组件：

• Modal、TextInput、Select、SelectOption、RadioSelect

await thread.post(
  <Card title="Order #1234">
    <CardText>Your order has been received.</CardText>
    <Actions>
      <Button id="approve" style="primary">Approve</Button>
      <Button id="reject" style="danger">Reject</Button>
    </Actions>
  </Card>
);

适配器列表

官方平台适配器

平台	包	工厂
Slack	@chat-adapter/slack	createSlackAdapter
Microsoft Teams	@chat-adapter/teams	createTeamsAdapter
Google Chat	@chat-adapter/gchat	createGoogleChatAdapter
Discord	@chat-adapter/discord	createDiscordAdapter
GitHub	@chat-adapter/github	createGitHubAdapter
Linear	@chat-adapter/linear	createLinearAdapter
Telegram	@chat-adapter/telegram	createTelegramAdapter
WhatsApp Business Cloud	@chat-adapter/whatsapp	createWhatsAppAdapter

官方状态适配器

状态后端	包	工厂
Redis	@chat-adapter/state-redis	createRedisState
ioredis	@chat-adapter/state-ioredis	createIoRedisState
PostgreSQL	@chat-adapter/state-pg	createPostgresState
Memory	@chat-adapter/state-memory	createMemoryState

社区适配器

• chat-state-cloudflare-do
• @beeper/chat-adapter-matrix
• chat-adapter-imessage
• @bitbasti/chat-adapter-webex
• @resend/chat-sdk-adapter
• chat-adapter-baileys

即将推出的平台条目

• Instagram
• Signal
• X
• Messenger

构建自定义适配器

请先阅读以下已发布的文档：

• node_modules/chat/docs/contributing/building.mdx
• node_modules/chat/docs/contributing/testing.mdx
• node_modules/chat/docs/contributing/publishing.mdx

另请检查：

• node_modules/chat/dist/index.d.ts — Adapter 和相关接口
• node_modules/@chat-adapter/shared/dist/index.d.ts — 共享错误和实用工具
• 已安装的官方适配器 dist/index.d.ts 文件 — 配置和 API 的参考实现

自定义适配器需要实现请求验证、Webhook 解析、消息／线程／频道操作、ID 编码／解码以及格式转换器。使用 chat 中的 BaseFormatConverter，以及 @chat-adapter/shared 中的共享实用工具。

Webhook 设置

每个已注册的适配器都会公开 bot.webhooks.<name>。将它们直接接入 HTTP 框架的路由。有关特定框架的路由模式，请参阅 node_modules/chat/docs/guides/slack-nextjs.mdx 和 node_modules/chat/docs/guides/discord-nuxt.mdx。