方案简介

本方案基于 Botpress 官方仓库提供的集成开发工具链，使用 @botpress/cli（Botpress CLI）与 @botpress/sdk 配合 TypeScript，构建可发布到 Botpress Hub 的聊天机器人集成（Integration）。Botpress 是构建由 OpenAI 驱动的下一代聊天机器人与助手的平台，而本仓库集中托管了其全部公开集成、开发工具（CLI、SDK、API Client）以及纯代码方式构建的示例机器人。

对于希望在 Botpress 平台上扩展新能力（如接入外部服务）的开发者，这套组合提供了从脚手架生成、定义编写、实现开发到一键部署工作区乃至公开发布的完整流程。整个过程可在任意目录和任意 git 仓库中进行，无需 fork 官方仓库。适合熟悉 Node.js/TypeScript 的开发者快速参与 Botpress 生态集成开发。

亮点与能力

• 一条命令 bp init 从模板生成集成脚手架
• 集成的定义与实现分离：integration.definition.ts 定义接口，src/index.ts 实现逻辑
• bp deploy 将当前版本部署到自己工作区并供所有机器人使用
• 已部署版本可被更新，未部署过则创建新版本
• 支持 --visibility public 将集成公开发布到 Botpress Hub 供全社区使用
• 所有开发工具开源且基于 MIT 许可证
• 提供类型安全的 API 客户端 @botpress/client 消费 Botpress API

组成与分工

• Botpress CLI (@botpress/cli)：构建、部署和管理机器人、集成与插件的核心命令行工具，负责 bp init 生成脚手架与 bp deploy 部署发布。
• @botpress/sdk：用于构建集成的 SDK，编写集成的定义与实现时使用。
• @botpress/client：类型安全的客户端，用于消费 Botpress API。
• TypeScript：集成定义与实现文件（integration.definition.ts、src/index.ts）均为 TypeScript 文件。
• Node.js：JavaScript 运行时，本地开发的前置工具之一。
• pnpm：仓库开发环境使用的快速、磁盘高效的包管理器。

前置要求

开发环境需要安装以下工具：

• git：免费开源的分布式版本控制系统。
• node：基于 Chrome V8 引擎的 JavaScript 运行时。
• pnpm：快速、节省磁盘空间的包管理器。

Windows 系统额外需要：

• Microsoft Visual C++ Redistributable for Visual Studio 2015-2022

实施步骤

1. 安装 Botpress CLI

根据所用包管理器选择安装命令：

sh
npm install -g @botpress/cli # for npm
yarn global add @botpress/cli # for yarn
pnpm install -g @botpress/cli # for pnpm

2. 生成集成脚手架

在你选择的目录中执行：

sh
bp init

该命令会基于提供的模板生成一个集成。此步骤可在任意目录和任意 git 仓库中执行，无需 fork 本仓库。

3. 编写定义与实现

修改生成的两个文件：integration.definition.ts（集成定义）与 src/index.ts（集成实现）。

4. 部署到工作区

sh
bp deploy

部署后集成对该工作区内的所有机器人可用；若该版本已部署过则更新，否则创建新版本。

5. （可选）公开发布

sh
bp deploy --visibility public

发布后集成对所有 Botpress 用户在 Botpress Hub 上可用。

如需从源码构建本仓库：

sh

Clone the repository

git clone https://github.com/botpress/botpress.git
cd botpress

Install dependencies

pnpm install

Build all packages

pnpm run build

Run Checks

pnpm run check

使用与配置要点

• 日常迭代中反复运行 bp deploy 即可更新工作区内的集成版本。
• 版本一旦以 public 可见性发布到 Botpress Hub，就不能再更新，发布前需确认内容稳定。
• 默认情况下所有集成仅对部署它的工作区私有，适合先内部测试再公开发布。
• 集成开发的更多细节可参考官方文档：https://botpress.com/docs/for-developers/sdk/integration/getting-started 。
• CLI 的命令参考文档见 https://www.botpress.com/docs/for-developers/sdk/cli-reference 。
• 遇到 Bug 或需要新功能，可在本仓库创建 issue，但通过 Discord 社区能获得更快响应。

注意事项与常见问题

• 公开发布的限制：集成某个版本一旦设为 public 并发布到 Botpress Hub，就再也无法更新，需谨慎发布。
• 纯代码方式（SDK+CLI）构建机器人并非官方推荐做法，不能替代 Botpress Studio，仅适合希望以更程序化方式构建机器人的有经验开发者；官方团队内部也在使用，因为 Studio 与 SDK 共用相同的底层原语。
• Windows 开发者需额外安装 Visual C++ Redistributable 2015-2022。
• 与 Botpress v12（本地部署版）相关的问题请移步 v12 仓库，与本仓库无关。

优缺点

• ✓ 开源MIT许可
• ✓ 命令行一键部署
• ✕ 公开版本发布后不可再更新
• ✕ 默认私有仅工作区可用

出处

本方案挖掘自开源项目 botpress/botpress，方案内容与实施命令均来自其 README 原文。