chat-sdk

Chat SDK

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

重要：阅读随附文档

chat 包附带完整文档，位于 node_modules/chat/docs/，并包含 TypeScript 源类型。编写代码前务必先阅读这些文档：

node_modules/chat/docs/           # Full documentation (MDX files)
node_modules/chat/dist/           # Built types (.d.ts files)

根据任务需要阅读的关键文档：

• docs/getting-started.mdx — 设置指南
• docs/usage.mdx — 事件处理程序、线程、消息、频道
• docs/streaming.mdx — 使用 AI SDK 进行 AI 流式传输
• docs/cards.mdx — JSX 交互卡片
• docs/actions.mdx — 按钮/下拉菜单处理程序
• docs/modals.mdx — 表单对话框（仅限 Slack）
• docs/adapters.mdx、docs/platform-adapters.mdx — 适配器概览和平台专属设置
• docs/state-adapters.mdx — 状态适配器配置（Redis、ioredis、内存）

还要阅读 node_modules/chat/dist/ 中的 TypeScript 类型，以了解完整的 API 范围。

快速开始

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({
      botToken: process.env.SLACK_BOT_TOKEN!,
      signingSecret: process.env.SLACK_SIGNING_SECRET!,
    }),
  },
  state: createRedisState({ url: process.env.REDIS_URL! }),
});

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、GChat、Discord、GitHub、Linear）
• State — 可插拔的持久化存储（生产环境使用 Redis，开发环境使用内存）
• Thread — 对话线程，提供 post()、subscribe()、startTyping()
• Message — 规范化格式，包含 text、formatted（mdast AST）、raw
• Channel — 线程容器，支持列出线程和发布消息

事件处理程序

处理程序	触发条件
onNewMention	机器人在未订阅的线程中被 @ 提及
onSubscribedMessage	已订阅线程中的任意消息
onNewMessage(regex)	未订阅线程中符合模式的消息
onSlashCommand("/cmd")	斜杠命令调用
onReaction(emojis)	添加或移除表情符号回应
onAction(actionId)	点击按钮或选择下拉菜单项
onAssistantThreadStarted	Slack Assistants API 线程已打开
onAppHomeOpened	Slack App Home 标签页已打开

流式传输

将任意 AsyncIterable<string> 传递给 thread.post()。可与 AI SDK 的 textStream 配合使用：

import { ToolLoopAgent } from 'ai';
const agent = new ToolLoopAgent({ model: 'anthropic/claude-sonnet-5' });

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

卡片（JSX）

在 tsconfig 中设置 jsxImportSource: "chat"。组件：Card、CardText、Button、Actions、Fields、Field、Select、SelectOption、Image、Divider、LinkButton、Section、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>,
);

Packages

chat 和 @chat-adapter/* 包是本仓库使用的外部 SDK（通过 package.json 中的 semver 范围锁定），并非在此处构建或进行版本管理的内容——无需为它们记录 Changesets/发布流程。

Package	Purpose
chat	核心 SDK
@chat-adapter/discord	Discord
@chat-adapter/slack	Slack
@chat-adapter/telegram	Telegram
@chat-adapter/state-ioredis	ioredis 状态
@lobechat/chat-adapter-feishu	Lark/Feishu — 在仓库内构建（packages/chat-adapter-feishu），并非来自 @chat-adapter/
@lobechat/chat-adapter-imessage	通过 BlueBubbles 接入 iMessage — 在仓库内构建
@lobechat/chat-adapter-line	LINE Messaging API — 在仓库内构建
@lobechat/chat-adapter-qq	QQ Bot — 在仓库内构建
@lobechat/chat-adapter-wechat	WeChat（iLink）— 在仓库内构建

Webhook setup

每个适配器都通过 bot.webhooks.{platform} 提供 webhook 处理程序。请将其连接到 HTTP 框架的路由（例如 Next.js API 路由、Hono、Express）。