lobehub/docs/development/basic/add-new-bot-platform.zh-CN.mdx

---
title: 添加新的 Bot 平台
description: >-
  了解如何向 LobeHub 的渠道系统添加新的 Bot 平台（如 Slack、WhatsApp），包括 Schema 定义、客户端实现和平台注册。
tags:
  - Bot 平台
  - 消息渠道
  - 集成
  - 开发指南
---

# 添加新的 Bot 平台

本指南介绍如何向 LobeHub 的渠道系统添加新的 Bot 平台。平台架构是模块化的 —— 每个平台是 `src/server/services/bot/platforms/` 下的一个独立目录。

## 架构概览

```
src/server/services/bot/platforms/
├── types.ts            # 核心接口（FieldSchema、PlatformClient、ClientFactory 等）
├── registry.ts         # PlatformRegistry 类
├── index.ts            # 单例注册表 + 平台注册
├── utils.ts            # 共享工具函数
├── discord/            # 示例：Discord 平台
│   ├── definition.ts   # PlatformDefinition 导出
│   ├── schema.ts       # 凭据和设置的 FieldSchema[]
│   ├── client.ts       # ClientFactory + PlatformClient 实现
│   └── api.ts          # 平台 API 辅助类
└── <your-platform>/    # 你的新平台
```

**核心概念：**

- **FieldSchema** — 声明式 Schema，同时驱动服务端校验和前端表单自动生成
- **PlatformClient** — 与平台交互的运行时接口（消息收发、生命周期管理）
- **ClientFactory** — 创建 PlatformClient 实例并验证凭据
- **PlatformDefinition** — 元数据 + Schema + 工厂，注册到全局注册表
- **Chat SDK Adapter** — 将平台的 Webhook / 事件桥接到统一的 Chat SDK

## 前置条件：Chat SDK Adapter

每个平台都需要一个 **Chat SDK Adapter**，用于将平台的 Webhook 事件桥接到统一的 [Vercel Chat SDK](https://github.com/vercel/chat)（`chat` npm 包）。在实现平台之前，需要确定使用哪个 Adapter：

### 方案 A：使用已有的 npm Adapter

部分平台已有官方 Adapter 发布在 `@chat-adapter/*` 下：

- `@chat-adapter/discord` — Discord
- `@chat-adapter/slack` — Slack
- `@chat-adapter/telegram` — Telegram

可以通过 `npm view @chat-adapter/<platform>` 检查是否存在。

### 方案 B：在 `packages/` 中开发自定义 Adapter

如果没有现成的 npm Adapter，你需要在工作区中创建一个 Adapter 包。可参考现有实现：

- `packages/chat-adapter-feishu` — 飞书 / Lark Adapter（`@lobechat/chat-adapter-feishu`）
- `packages/chat-adapter-qq` — QQ Adapter（`@lobechat/chat-adapter-qq`）

每个 Adapter 包遵循以下结构：

```
packages/chat-adapter-<platform>/
├── package.json        # name: @lobechat/chat-adapter-<platform>
├── tsconfig.json
├── tsup.config.ts
└── src/
    ├── index.ts            # 公共导出：createXxxAdapter、XxxApiClient 等
    ├── adapter.ts          # 实现 chat SDK 的 Adapter 接口的适配器类
    ├── api.ts              # 平台 API 客户端（Webhook 验证、消息解析）
    ├── crypto.ts           # 请求签名验证
    ├── format-converter.ts # 消息格式转换（平台格式 ↔ Chat SDK AST）
    └── types.ts            # 平台特定的类型定义
```

开发自定义 Adapter 的要点：

- Adapter 必须实现 `chat` 包中的 `Adapter` 接口
- 需要处理 Webhook 请求验证、事件解析和消息格式转换
- `createXxxAdapter(config)` 工厂函数是 `PlatformClient.createAdapter()` 调用的入口
- 在 `package.json` 中添加 `"chat": "^4.14.0"` 作为依赖

## 第一步：创建平台目录

```bash
mkdir src/server/services/bot/platforms/<platform-name>
```

需要创建四个文件：

| 文件              | 用途                                    |
| --------------- | ------------------------------------- |
| `schema.ts`     | 凭据和设置的字段定义                            |
| `api.ts`        | 用于出站消息的轻量 API 客户端                     |
| `client.ts`     | `ClientFactory` + `PlatformClient` 实现 |
| `definition.ts` | `PlatformDefinition` 导出               |

## 第二步：定义 Schema（`schema.ts`）

Schema 是一个 `FieldSchema` 对象数组，包含两个顶层部分：`credentials`（凭据）和 `settings`（设置）。

```ts
import type { FieldSchema } from '../types';

export const schema: FieldSchema[] = [
  {
    key: 'credentials',
    label: 'channel.credentials',
    properties: [
      {
        key: 'applicationId',
        description: 'channel.applicationIdHint',
        label: 'channel.applicationId',
        required: true,
        type: 'string',
      },
      {
        key: 'botToken',
        description: 'channel.botTokenEncryptedHint',
        label: 'channel.botToken',
        required: true,
        type: 'password', // 存储时加密，UI 中遮蔽显示
      },
    ],
    type: 'object',
  },
  {
    key: 'settings',
    label: 'channel.settings',
    properties: [
      {
        key: 'charLimit',
        default: 4000,
        description: 'channel.charLimitHint',
        label: 'channel.charLimit',
        minimum: 100,
        type: 'number',
      },
      // 添加平台特定设置...
    ],
    type: 'object',
  },
];
```

**Schema 约定：**

- `type: 'password'` 字段会被加密存储，在表单中以密码形式显示
- 共享字段使用已有的 i18n 键（如 `channel.botToken`、`channel.charLimit`）
- 平台特有字段使用 `channel.<platform>.<key>` 命名
- `devOnly: true` 的字段仅在 `NODE_ENV === 'development'` 时显示
- 凭据中必须包含一个能解析为 `applicationId` 的字段 —— 可以是显式的 `applicationId` 字段、`appId` 字段，或从 `botToken` 中提取（参见渠道详情页的 `resolveApplicationId`）

## 第三步：创建 API 客户端（`api.ts`）

用于回调服务（Chat SDK Adapter 之外）的出站消息操作的轻量类：

```ts
import debug from 'debug';

const log = debug('bot-platform:<platform>:client');

export const API_BASE = 'https://api.example.com';

export class PlatformApi {
  private readonly token: string;

  constructor(token: string) {
    this.token = token;
  }

  async sendMessage(channelId: string, text: string): Promise<{ id: string }> {
    log('sendMessage: channel=%s', channelId);
    return this.call('messages.send', { channel: channelId, text });
  }

  async editMessage(channelId: string, messageId: string, text: string): Promise<void> {
    log('editMessage: channel=%s, message=%s', channelId, messageId);
    await this.call('messages.update', { channel: channelId, id: messageId, text });
  }

  // ... 其他操作（输入指示器、表情回应等）

  private async call(method: string, body: Record<string, unknown>): Promise<any> {
    const response = await fetch(`${API_BASE}/${method}`, {
      body: JSON.stringify(body),
      headers: {
        Authorization: `Bearer ${this.token}`,
        'Content-Type': 'application/json',
      },
      method: 'POST',
    });

    if (!response.ok) {
      const text = await response.text();
      log('API error: method=%s, status=%d, body=%s', method, response.status, text);
      throw new Error(`API ${method} failed: ${response.status} ${text}`);
    }

    return response.json();
  }
}
```

## 第四步：实现客户端（`client.ts`）

实现 `PlatformClient` 并继承 `ClientFactory`：

```ts
import { createPlatformAdapter } from '@chat-adapter/<platform>';
import debug from 'debug';

import {
  type BotPlatformRuntimeContext,
  type BotProviderConfig,
  ClientFactory,
  type PlatformClient,
  type PlatformMessenger,
  type ValidationResult,
} from '../types';
import { PlatformApi } from './api';

const log = debug('bot-platform:<platform>:bot');

class MyPlatformClient implements PlatformClient {
  readonly id = '<platform>';
  readonly applicationId: string;

  private config: BotProviderConfig;
  private context: BotPlatformRuntimeContext;

  constructor(config: BotProviderConfig, context: BotPlatformRuntimeContext) {
    this.config = config;
    this.context = context;
    this.applicationId = config.applicationId;
  }

  // --- 生命周期 ---

  async start(): Promise<void> {
    // 注册 webhook 或开始监听
    // Webhook 平台：通过平台 API 配置 webhook URL
    // 网关平台：打开持久连接
  }

  async stop(): Promise<void> {
    // 清理：移除 webhook 注册或关闭连接
  }

  // --- 运行时操作 ---

  createAdapter(): Record<string, any> {
    // 返回 Chat SDK adapter 实例用于入站消息处理
    return {
      '<platform>': createPlatformAdapter({
        botToken: this.config.credentials.botToken,
        // ... adapter 特定配置
      }),
    };
  }

  getMessenger(platformThreadId: string): PlatformMessenger {
    const api = new PlatformApi(this.config.credentials.botToken);
    const channelId = platformThreadId.split(':')[1];

    return {
      createMessage: (content) => api.sendMessage(channelId, content).then(() => {}),
      editMessage: (messageId, content) => api.editMessage(channelId, messageId, content),
      removeReaction: (messageId, emoji) => api.removeReaction(channelId, messageId, emoji),
      triggerTyping: () => Promise.resolve(),
    };
  }

  extractChatId(platformThreadId: string): string {
    return platformThreadId.split(':')[1];
  }

  parseMessageId(compositeId: string): string {
    return compositeId;
  }

  // --- 可选方法 ---

  // sanitizeUserInput(text: string): string { ... }
  // shouldSubscribe(threadId: string): boolean { ... }
  // formatReply(body: string, stats?: UsageStats): string { ... }
}

export class MyPlatformClientFactory extends ClientFactory {
  createClient(config: BotProviderConfig, context: BotPlatformRuntimeContext): PlatformClient {
    return new MyPlatformClient(config, context);
  }

  async validateCredentials(credentials: Record<string, string>): Promise<ValidationResult> {
    // 调用平台 API 验证凭据有效性
    try {
      const res = await fetch('https://api.example.com/auth.test', {
        headers: { Authorization: `Bearer ${credentials.botToken}` },
        method: 'POST',
      });
      if (!res.ok) throw new Error(`HTTP ${res.status}`);
      return { valid: true };
    } catch {
      return {
        errors: [{ field: 'botToken', message: 'Failed to authenticate' }],
        valid: false,
      };
    }
  }
}
```

**需要实现的关键接口：**

| 方法                    | 用途                           |
| --------------------- | ---------------------------- |
| `start()`             | 注册 webhook 或启动网关监听           |
| `stop()`              | 关闭时清理资源                      |
| `createAdapter()`     | 返回 Chat SDK adapter 用于入站事件处理 |
| `getMessenger()`      | 返回指定会话的出站消息接口                |
| `extractChatId()`     | 从复合会话 ID 中解析平台频道 ID          |
| `parseMessageId()`    | 将复合消息 ID 转换为平台原生格式           |
| `sanitizeUserInput()` | \*（可选）\* 去除用户输入中的 Bot 提及标记   |
| `shouldSubscribe()`   | \*（可选）\* 控制会话自动订阅行为          |
| `formatReply()`       | \*（可选）\* 在回复中追加平台特定的格式化内容    |

## 第五步：导出定义（`definition.ts`）

```ts
import type { PlatformDefinition } from '../types';
import { MyPlatformClientFactory } from './client';
import { schema } from './schema';

export const myPlatform: PlatformDefinition = {
  id: '<platform>',
  name: 'Platform Name',
  description: 'Connect a Platform bot',
  documentation: {
    portalUrl: 'https://developers.example.com',
    setupGuideUrl: 'https://lobehub.com/docs/usage/channels/<platform>',
  },
  schema,
  showWebhookUrl: true, // 如果用户需要手动复制 webhook URL 则设为 true
  clientFactory: new MyPlatformClientFactory(),
};
```

**`showWebhookUrl`：** 对于需要用户手动粘贴 webhook URL 的平台（如 Slack、飞书）设为 `true`。对于通过 API 自动注册 webhook 的平台（如 Telegram）设为 `false` 或省略。

## 第六步：注册平台

编辑 `src/server/services/bot/platforms/index.ts`：

```ts
import { myPlatform } from './<platform>/definition';

// 添加到导出
export { myPlatform } from './<platform>/definition';

// 注册
platformRegistry.register(myPlatform);
```

## 第七步：添加 i18n 键

### 默认键（`src/locales/default/agent.ts`）

添加平台特有键。尽量复用通用键：

```ts
// 可复用（已存在）：
// 'channel.botToken'、'channel.applicationId'、'channel.charLimit' 等

// 平台特有：
'channel.<platform>.description': 'Connect this assistant to Platform for ...',
'channel.<platform>.someFieldHint': 'Description of this field.',
```

### 翻译文件（`locales/zh-CN/agent.json`、`locales/en-US/agent.json`）

在两个语言文件中添加所有新键的对应翻译。

## 第八步：添加用户文档

在 `docs/usage/channels/` 下创建配置教程：

- `<platform>.mdx` — 英文教程
- `<platform>.zh-CN.mdx` — 中文教程

参考现有文档的结构（如 `discord.mdx`）：前置条件 → 创建应用 → 在 LobeHub 中配置 → 配置 Webhook → 测试连接 → 配置参考 → 故障排除。

## 前端：自动 UI 生成

前端会根据 Schema 自动生成配置表单，无需修改前端代码（除非你的平台需要自定义图标）。图标解析通过将平台 `name` 与 `@lobehub/ui/icons` 中的已知图标匹配来实现：

```
// src/routes/(main)/agent/channel/const.ts
const ICON_NAMES = ['Discord', 'GoogleChat', 'Lark', 'Slack', 'Telegram', ...];
```

如果你的平台 `name` 与图标名称匹配（不区分大小写），图标会自动使用。否则需要在 `ICON_ALIASES` 中添加别名。

## Webhook URL 模式

所有平台共享同一个 Webhook 路由：

```
POST /api/agent/webhooks/[platform]/[appId]
```

`BotMessageRouter` 会自动处理路由分发、按需加载 Bot 和 Chat SDK 集成。

## 检查清单

- [ ] 确保 Chat SDK Adapter 可用（npm 上的 `@chat-adapter/*` 或自定义的 `packages/chat-adapter-<platform>`）
- [ ] 创建 `src/server/services/bot/platforms/<platform>/`
  - [ ] `schema.ts` — 凭据和设置的字段定义
  - [ ] `api.ts` — 出站 API 客户端
  - [ ] `client.ts` — `ClientFactory` + `PlatformClient`
  - [ ] `definition.ts` — `PlatformDefinition` 导出
- [ ] 在 `src/server/services/bot/platforms/index.ts` 中注册
- [ ] 在 `src/locales/default/agent.ts` 中添加 i18n 键
- [ ] 在 `locales/zh-CN/agent.json` 和 `locales/en-US/agent.json` 中添加翻译
- [ ] 在 `docs/usage/channels/<platform>.mdx` 中添加配置教程（中英文）
- [ ] 验证图标在 `const.ts` 中能正确解析（或添加别名）