Typebot插件开发指南：5步扩展聊天机器人功能

你是否曾因Typebot内置功能无法满足特定业务需求而苦恼？客户需要与私有CRM系统对接？想实现自定义数据分析追踪？本文将通过5个清晰步骤，带你掌握Typebot插件开发全流程，从环境搭建到功能部署，让你的聊天机器人轻松扩展无限可能。

插件开发准备工作

在开始编写插件前，需要准备基础开发环境。首先克隆官方仓库并安装依赖：

git clone https://gitcode.com/GitHub_Trending/ty/typebot.io
cd typebot.io
bun install

Typebot插件开发基于Forge SDK，核心代码位于packages/forge/目录。该SDK提供了完整的插件开发框架，包括认证管理、动作定义和数据流处理等模块。开发工具链已内置插件脚手架，可通过CLI快速生成项目结构。

第1步：创建插件项目

使用Forge CLI创建新插件项目，支持交互式配置或命令行参数直接生成：

cd packages/forge/cli
bun create-new-block --name "客户管理" --id "customer-management" --auth "apiKey"

命令执行后将自动生成标准插件目录结构：

customer-management/
├── src/
│   ├── index.ts        # 插件入口
│   ├── auth.ts         # 认证配置
│   ├── logo.tsx        # 图标组件
│   └── schemas.ts      # 类型定义
├── package.json
└── tsconfig.json

脚手架已预置基础代码框架，例如src/index.ts中自动生成的插件注册代码：

export const customerManagementBlock = createBlock({
  id: 'customer-management',
  name: '客户管理',
  tags: ['crm', 'database'],
  LightLogo: CustomerManagementLogo,
  auth,
  actions: [],
})

第2步：定义认证机制

根据插件需求选择合适的认证方式，Typebot支持API Key、OAuth和自定义加密数据三种认证模式。以API Key认证为例，编辑src/auth.ts文件：

export const auth = {
  type: 'encryptedCredentials',
  name: '客户管理系统账号',
  schema: option.object({
    apiKey: option.string.layout({
      label: 'API密钥',
      isRequired: true,
      inputType: 'password',
      helperText: '从客户管理系统控制台获取API密钥',
      withVariableButton: false
    })
  })
}

认证配置将在Typebot编辑器中生成可视化配置界面，用户可安全存储敏感信息。

第3步：实现核心功能

插件功能通过Action定义实现，每个Action对应一个具体业务操作。例如创建"添加客户"功能：

actions: [
  {
    name: '添加客户',
    options: option.object({
      name: option.string.layout({ label: '客户姓名' }),
      email: option.string.layout({ label: '电子邮箱' })
    }),
    run: {
      server: async ({ credentials, options, variables, logs }) => {
        const response = await fetch('https://api.example.com/customers', {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${credentials.apiKey}` },
          body: JSON.stringify({
            name: options.name,
            email: options.email
          })
        })
        if (!response.ok) throw new Error('添加客户失败')
        logs.add('客户添加成功')
      }
    }
  }
]

Action支持三种执行环境：server端运行、web端渲染和流式响应，满足不同场景需求。

第4步：本地测试与调试

开发完成后通过Typebot开发服务器测试插件功能：

bun dev:builder

在编辑器中创建测试机器人，添加自定义插件节点并配置参数。可通过packages/playwright/提供的测试工具进行自动化测试，确保功能稳定性。

第5步：打包与部署

插件测试通过后，执行打包命令生成发布文件：

bun run build:forge

打包产物位于dist目录，可通过两种方式部署：

• 本地部署：复制到Typebot安装目录的plugins文件夹
• 社区贡献：提交PR到官方仓库packages/forge/blocks/

插件开发最佳实践

代码组织规范

• 复杂逻辑拆分到services目录
• 使用packages/forge/core/src/types.ts定义的类型确保类型安全
• 图标使用24x24 SVG格式，参考logo.tsx模板

性能优化建议

• 避免在run函数中执行耗时操作
• 合理使用缓存机制减少API调用
• 大文件处理采用流式传输

常见问题排查

• 认证失败：检查auth.ts中的schema定义
• 变量不生效：确保在actions中正确声明getSetVariableIds
• 编辑器不显示：检查插件ID是否符合slug格式

示例插件参考

官方提供多个插件示例可供参考：

• Cal.com预约插件
• OpenAI集成插件
• HTTP请求插件

这些示例包含完整的认证处理、复杂选项配置和多环境支持，是学习插件开发的绝佳资源。

通过插件开发，你可以将Typebot与任何系统无缝连接，打造真正符合业务需求的聊天机器人。立即开始探索Typebot的无限可能，构建属于你的专属插件生态！

官方文档：apps/docs/
API参考：packages/forge/core/src/
贡献指南：CONTRIBUTING.md