尧图网页设计 
AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载导读botpress/chat是 Botpress 官方发布的 TypeScript 客户端库用于以代码方式与 Botpress Chat API 交互覆盖用户、会话、消息、事件四大实体并内置基于 SSE / WebSocket 的实时事件监听能力。本文以仓库 packages/chat-client/readme.md 为主体结合 packages/chat-client/src 的源码实现与 packages/chat-client/e2e 的端到端测试系统讲解安装、认证连接、消息收发、实时监听与断线重连的完整实战方案读完即可在 Node.js 或浏览器中搭建自己的 LLM Agent 对话客户端。一、安装与运行环境botpress/chat以 npm 包形式发布当前仓库版本为 1.1.0见 package.json支持 npm、yarn、pnpm 三种包管理器npm install botpress/chat # for npm yarn add botpress/chat # for yarn pnpm add botpress/chat # for pnpm从源码看包同时提供 CJSdist/index.cjs与 ESMdist/index.mjs产物types指向dist/index.d.ts因此既有 TypeScript 类型提示也兼容require与import两种模块风格。运行时对 Node.js 版本有明确要求^20.19.0 || ^22.12.0 || 23.0.0engines 字段。注意若使用加密密钥签名用户 Key需要 WebCrypto APINode.js 20 或浏览器安全上下文这一点在 jwt.ts 的错误提示中有明确说明。该库的依赖包括 axiosHTTP 请求、zod事件信号解析、joseJWT 签名、eventsource / event-source-polyfillSSE 事件源等说明其核心职责就是封装 HTTP 调用 实时事件流两层能力。二、快速开始完整的 API 调用示例官方 readme 提供了一个从零到拿到机器人回复的完整示例。核心入口是包导出的Client类其构造方式是通过chat.Client.connect({ webhookId })完成连接并创建用户import _ from lodash import * as chat from botpress/chat const main async () { /** * You can find your webhook id in the the Botpress Dashboard. * Navigate to your bots Chat Integration configuration. Look for: * https://webhook.botpress.cloud/$YOUR_WEBHOOK_ID */ const webhookId process.env.WEBHOOK_ID if (!webhookId) { throw new Error(WEBHOOK_ID is required) } // 0. connect and create a user const client await chat.Client.connect({ webhookId }) // 1. create a conversation const { conversation } await client.createConversation({}) // 2. send a message await client.createMessage({ conversationId: conversation.id, payload: { type: text, text: hello world, }, }) // 3. sleep for a bit await new Promise((resolve) setTimeout(resolve, 2000)) // 4. list messages const { messages } await client .listMessages({ conversationId: conversation.id, }) .then(({ messages }) ({ messages: _.sortBy(messages, (m) new Date(m.createdAt).getTime()), })) const botResponse messages[1] console.log(Bots response:, botResponse.payload) } void main() .then(() { console.log(done) process.exit(0) }) .catch((err) { console.error(err) process.exit(1) })这段示例展示了五个关键步骤连接并创建用户 → 创建会话 → 发送文本消息 → 等待响应 → 拉取消息列表。其中webhookId 从哪来登录 Botpress Dashboard进入机器人Bot的 Chat Integration 配置页面找到形如https://webhook.botpress.cloud/$YOUR_WEBHOOK_ID的地址$YOUR_WEBHOOK_ID即为所需值建议通过process.env.WEBHOOK_ID注入避免硬编码。为什么要 sleep 2 秒消息发送是异步的机器人响应由服务端处理轮询前留出时间窗口更优雅的替代方案是下文介绍的事件监听listenConversation。为什么取messages[1]listMessages默认返回的消息顺序并不保证按时间排列示例用 lodash 的sortBy按createdAt升序排列后索引 0 是自己发送的消息索引 1 才是机器人的回复。从源码层面看Client.connect的核心逻辑在 client.ts它先用传入的配置构造底层Client并调用_testConnection()探测GET {apiUrl}/hello端点确保连接可用然后根据是否提供userKey/encryptionKey走不同认证分支最后返回一个AuthenticatedClient见下文第三节。三、连接与认证webhookId、三种用户认证方式与 apiUrlClient.connect接受的配置ConnectProps见 types.ts由两部分组成1. 服务端地址二选一webhookId: string从 Dashboard 获取的 Webhook ID客户端会自动拼接为${baseApiUrl}/${webhookId}apiUrl: string直接指定完整 API 地址如自建部署优先级高于 webhookId 组合。其中baseApiUrl可省略默认值为https://chat.botpress.cloud见 consts.ts。2. 通用项CommonClientPropstimeout?: numberHTTP 请求超时时间毫秒源码默认60_00060 秒headers?: Recordstring, string附加请求头debug?: boolean开启后SignalListener会输出信号解析调试日志。3. 用户身份ConnectProps独有三种方式对应 client.ts 的三个分支方式传参行为匿名自动创建不传任何身份参数调用createUser({ id: userId })服务端生成用户及其 key服务端签发 KeyuserKey: string调用getOrCreateUser({ x-user-key: userKey })实现同一 Key 映射同一用户自签加密 KeyuserId: stringencryptionKey: string用 HS256 签名 JWT 作为 userKey再走getOrCreateUser第三种方式适合跨端共享用户身份在服务端用同一把encryptionKey为任意userId签名 JWT客户端拿到的就是与平台绑定的用户凭证。签名逻辑在 jwt.tsSignJWT HS256 setIssuedAt()任何具备该密钥的一方都能独立生成合法 userKey。注意使用encryptionKey时必须同时提供userId否则抛出ChatConfigError提示选择一个未被占用的 userId。connect 成功后返回AuthenticatedClient它内部持有user含id、key对象并在每次请求中自动注入x-user-key: this.user.key请求头见 client.ts。因此后续所有调用createConversation、createMessage、listMessages等都不需要再手动传用户凭证。四、核心 API 操作一览Client/AuthenticatedClient暴露的操作由 OpenAPI 定义自动生成生成脚本见 openapi.ts调用botpress/chat-api导出 client 与 signals 类型从 client.ts 可以看到完整操作面会话createConversation、getConversation、getOrCreateConversation、deleteConversation、listConversations消息createMessage、getMessage、deleteMessage、listMessages用户createUser、getUser、getOrCreateUser、updateUser、deleteUser参与者addParticipant、removeParticipant、getParticipant、listParticipants事件createEvent、getEvent实时listenConversation值得注意的实现细节list属性client.ts为三类列表查询封装了基于nextToken的分页迭代器AsyncCollectionlisting.ts支持for await...of遍历所有分页数据也支持collect({ limit })一次性收集到数组// 遍历某会话的全部消息自动翻页 for await (const message of client.list.messages({ conversationId })) { console.log(message.payload) } // 最多取 100 条 const messages await client.list.messages({ conversationId }).collect({ limit: 100 })另外每次请求前_call都会先做一次_testConnection探测只执行一次并缓存结果并解析响应 payload——由于 Chat API 经由桥接 Webhook 转发服务端可能返回 2xx 状态码但 payload 内嵌错误码_checkPayloadForError会识别 400–599 的code字段并抛出ChatHTTPError见 client.ts。所有异常最终统一映射为ChatClientError/ChatHTTPError/ChatConfigErrorerrors.ts并保留 Axios 响应细节状态码、请求方法、路径、服务端 message便于排查。五、Realtime Events实时接收机器人消息轮询之外客户端还提供实时事件监听。readme 示例通过listenConversation订阅会话事件并用message_created信号等待机器人的回复// ... const listener await client.listenConversation({ id: conversation.id, }) const botResponse await new Promisechat.Message((resolve) { const onMessage (ev: chat.Signals[message_created]) { if (ev.userId client.user.id) { // message created by my current user, ignoring... return } listener.off(message_created, onMessage) resolve(ev) } listener.on(message_created, onMessage) }) console.log(Bots response:, botResponse.payload)事件机制与类型定义listener是SignalListenersignal-listener.ts本质是一个类型安全的事件发射器事件名即信号名如message_created事件负载由 zod schema 校验解析无法识别的负载会落入unknown信号不会导致监听崩溃。chat.Signals[message_created]是Signals索引类型源码由 signals schema 生成见 openapi.ts保证事件回调的负载有完整类型提示。除message_created外可推断会话相关的其他信号如message_deleted、conversation_*、event_created等都会以同名事件在 listener 上派发e2e 测试中即同时用到了message_created与message_deleted见 message.test.ts。SignalListener的状态机包含disconnected/connecting/connected三种状态并提供connect()/disconnect()方法listenConversation返回时已处于connected。事件发射器底层event-emitter.ts除常规on/off外还提供once只监听一次与onceOrMore回调返回stop-listening时停止监听否则持续监听后者被 e2e 测试用来跳过自己发出的消息、只捕获机器人回复。六、实时协议SSE 与 WebSocketlistenConversation支持通过protocol参数选择底层传输协议ServerEventsProtocol websocket | sse见 eventsource.ts默认sseconst listener await client.listenConversation({ id: conversation.id, protocol: websocket, // 或 sse })两种协议的实现差异SSE在浏览器端使用event-source-polyfill在 Node.js 端使用eventsource包请求头中携带x-user-key通过 polyfill 的headers选项或 Node 模块的 headers 选项注入WebSocket将http(s)前缀替换为ws(s)后建立原生WebSocket连接由于浏览器 WebSocket 无法自定义请求头x-user-key会被自动编码为 URL 查询参数?x-user-key...附带在连接地址上。无论哪种协议listenEventSource都会等待open事件确认连接建立后才 resolve并监听error/close事件向调用方派发对应事件。e2e 测试对sse与websocket两种协议都做了消息收发验证message.test.ts可据此确认两种协议在功能上等价。此外SignalListener内部有一个看门狗watchdog.ts连接建立后启动 60 秒CONNECTION_TIMEOUT计时器每收到一条消息watchdog.reset()就重置计时若超过 60 秒无消息看门狗会触发Client connection timed out错误并通过error事件通知应用用于及时发现静默断连。七、断线重连把连接生命周期握在自己手里readme 明确指出Client不会自动重连。这是刻意设计——把重连策略交给应用以便与业务状态如消息列表、UI 状态协调。官方给出的模式是监听error事件在断开后重连并同步状态const state { messages } // your application state const onDisconnection async () { try { await listener.connect() const { messages } await client.listMessages({ conversationId: conversation.id }) state.messages messages } catch (thrown) { console.error(failed to reconnect, retrying..., thrown) setTimeout(onDisconnection, 1000) // consider using a backoff strategy } } listener.on(error, (err) { console.error(connection lost, err) void onDisconnection() })要点拆解listener.on(error, ...)注册断线回调。连接异常、看门狗超时都会触发error事件见 signal-listener.ts触发后监听器内部已切换回disconnected状态listener.connect()是幂等且可重入的若已连接则直接返回若正在连接则等待既有连接完成signal-listener.ts因此重连调用是安全的重连成功后通过listener.listMessages拉取最新消息把补发的消息同步进应用状态避免重连窗口期的消息丢失重连失败不要无限重试注释建议实现指数退避backoff策略setTimeout(onDisconnection, 1000)是最简的固定间隔重试。从事件流角度理解一次断线 →error事件 → 应用主动connect()→open事件 → 服务端可能重新推送历史信号或应用自行listMessages补齐 → 状态收敛。这套应用掌控重连的模型与常见自动重连 SDK 相比把补偿逻辑补消息、刷新状态显式交给了业务层更适合 Chat 类产品对一致性的要求。八、e2e 测试验证从源码确认行为边界packages/chat-client/e2e 下的端到端测试可以作为本库行为的权威佐证运行需设置API_URL与ENCRYPTION_KEY环境变量见 config.ts消息收发message.test.ts验证了两种协议下基于 Botpress ID 与外部 IDfid的消息收发、删除消息后getMessage抛ResourceNotFoundError、metadata随消息透传但不进入 payload、bloc复合消息文本 图片的收发用户与身份user.test.ts验证了非法 fid含非法字符、超长会抛InvalidPayloadError、重复创建同 fid 用户会抛AlreadyExistsError、getOrCreateUser的幂等性多次调用返回同一用户连接失败webhook.test.ts验证了错误的 apiUrl 会使createUser抛出ChatClientError印证_testConnection与统一错误映射的链路。这些测试同时展示了waitFor/onceOrMore/Signals等事件 API 的典型用法utils.ts是阅读事件监听能力的极佳范例。九、总结何时选择 botpress/chatbotpress/chat定位清晰面向用代码直接驱动 Botpress 机器人对话的场景与在 Dashboard 中使用 Chat Widget 互补。适用场景包括需要自定义前端 UI、以 Webhook ID 接入 Botpress Chat API 的应用需要在 Node.js 服务端代理/编排对话创建会话、发消息、批量拉取历史需要实时订阅消息与事件、并对断线重连有明确业务策略的产品。核心取舍简单性一个类搞定认证、请求与事件流类型齐全与可控性不自动重连把连接生命周期交给应用。上手路径建议按 readme 顺序先跑通 API Queries 示例拿到首条机器人回复再替换为listenConversation实时接收最后在生产环境补充基于error事件的退避重连与状态补偿逻辑。延伸阅读官方使用文档主体packages/chat-client/readme.md客户端核心实现packages/chat-client/src/client.tsconnect 认证分支、请求封装、错误解析实时事件监听packages/chat-client/src/signal-listener.ts 与 packages/chat-client/src/eventsource.tsSSE / WebSocket 双协议类型与配置定义packages/chat-client/src/types.ts端到端测试packages/chat-client/e2e/message.test.ts、packages/chat-client/e2e/user.test.ts赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Botpress CLI 实战指南使用 bp 命令完成 GPT/LLM Agent 的构建、部署与云端管理Botpress CLI 实战指南使用 bp 命令完成 GPT/LLM Agent 的构建、部署与云端管理 Botpress CLI botpress/cAI 应用后端Botpress LLMz Chat Exits 实战用类型安全的 Exit 机制实现对话退出与人机移交Botpress LLMz Chat Exits 实战用类型安全的 Exit 机制实现对话退出与人机移交 LLMz packages/llmz 是 BotAI 应用后端Botpress BambooHR 集成实战让 GPT/LLM Agent 读取与管理员工数据Botpress BambooHR 集成实战让 GPT/LLM Agent 读取与管理员工数据 导读 本文围绕 Botpress 开源仓库中 BambooHRAI 应用后端上一篇Trigger.dev任务取消机制灵活控制任务生命周期的终极指南下一篇Modern C Template 单元测试完整教程GoogleTest与Catch2深度对比 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Botpress Chat Client 完全指南：用 @botpress/chat 构建 GPT/LLM Agent 的对话客户端
AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载导读botpress/chat是 Botpress 官方发布的 TypeScript 客户端库用于以代码方式与 Botpress Chat API 交互覆盖用户、会话、消息、事件四大实体并内置基于 SSE / WebSocket 的实时事件监听能力。本文以仓库 packages/chat-client/readme.md 为主体结合 packages/chat-client/src 的源码实现与 packages/chat-client/e2e 的端到端测试系统讲解安装、认证连接、消息收发、实时监听与断线重连的完整实战方案读完即可在 Node.js 或浏览器中搭建自己的 LLM Agent 对话客户端。一、安装与运行环境botpress/chat以 npm 包形式发布当前仓库版本为 1.1.0见 package.json支持 npm、yarn、pnpm 三种包管理器npm install botpress/chat # for npm yarn add botpress/chat # for yarn pnpm add botpress/chat # for pnpm从源码看包同时提供 CJSdist/index.cjs与 ESMdist/index.mjs产物types指向dist/index.d.ts因此既有 TypeScript 类型提示也兼容require与import两种模块风格。运行时对 Node.js 版本有明确要求^20.19.0 || ^22.12.0 || 23.0.0engines 字段。注意若使用加密密钥签名用户 Key需要 WebCrypto APINode.js 20 或浏览器安全上下文这一点在 jwt.ts 的错误提示中有明确说明。该库的依赖包括 axiosHTTP 请求、zod事件信号解析、joseJWT 签名、eventsource / event-source-polyfillSSE 事件源等说明其核心职责就是封装 HTTP 调用 实时事件流两层能力。二、快速开始完整的 API 调用示例官方 readme 提供了一个从零到拿到机器人回复的完整示例。核心入口是包导出的Client类其构造方式是通过chat.Client.connect({ webhookId })完成连接并创建用户import _ from lodash import * as chat from botpress/chat const main async () { /** * You can find your webhook id in the the Botpress Dashboard. * Navigate to your bots Chat Integration configuration. Look for: * https://webhook.botpress.cloud/$YOUR_WEBHOOK_ID */ const webhookId process.env.WEBHOOK_ID if (!webhookId) { throw new Error(WEBHOOK_ID is required) } // 0. connect and create a user const client await chat.Client.connect({ webhookId }) // 1. create a conversation const { conversation } await client.createConversation({}) // 2. send a message await client.createMessage({ conversationId: conversation.id, payload: { type: text, text: hello world, }, }) // 3. sleep for a bit await new Promise((resolve) setTimeout(resolve, 2000)) // 4. list messages const { messages } await client .listMessages({ conversationId: conversation.id, }) .then(({ messages }) ({ messages: _.sortBy(messages, (m) new Date(m.createdAt).getTime()), })) const botResponse messages[1] console.log(Bots response:, botResponse.payload) } void main() .then(() { console.log(done) process.exit(0) }) .catch((err) { console.error(err) process.exit(1) })这段示例展示了五个关键步骤连接并创建用户 → 创建会话 → 发送文本消息 → 等待响应 → 拉取消息列表。其中webhookId 从哪来登录 Botpress Dashboard进入机器人Bot的 Chat Integration 配置页面找到形如https://webhook.botpress.cloud/$YOUR_WEBHOOK_ID的地址$YOUR_WEBHOOK_ID即为所需值建议通过process.env.WEBHOOK_ID注入避免硬编码。为什么要 sleep 2 秒消息发送是异步的机器人响应由服务端处理轮询前留出时间窗口更优雅的替代方案是下文介绍的事件监听listenConversation。为什么取messages[1]listMessages默认返回的消息顺序并不保证按时间排列示例用 lodash 的sortBy按createdAt升序排列后索引 0 是自己发送的消息索引 1 才是机器人的回复。从源码层面看Client.connect的核心逻辑在 client.ts它先用传入的配置构造底层Client并调用_testConnection()探测GET {apiUrl}/hello端点确保连接可用然后根据是否提供userKey/encryptionKey走不同认证分支最后返回一个AuthenticatedClient见下文第三节。三、连接与认证webhookId、三种用户认证方式与 apiUrlClient.connect接受的配置ConnectProps见 types.ts由两部分组成1. 服务端地址二选一webhookId: string从 Dashboard 获取的 Webhook ID客户端会自动拼接为${baseApiUrl}/${webhookId}apiUrl: string直接指定完整 API 地址如自建部署优先级高于 webhookId 组合。其中baseApiUrl可省略默认值为https://chat.botpress.cloud见 consts.ts。2. 通用项CommonClientPropstimeout?: numberHTTP 请求超时时间毫秒源码默认60_00060 秒headers?: Recordstring, string附加请求头debug?: boolean开启后SignalListener会输出信号解析调试日志。3. 用户身份ConnectProps独有三种方式对应 client.ts 的三个分支方式传参行为匿名自动创建不传任何身份参数调用createUser({ id: userId })服务端生成用户及其 key服务端签发 KeyuserKey: string调用getOrCreateUser({ x-user-key: userKey })实现同一 Key 映射同一用户自签加密 KeyuserId: stringencryptionKey: string用 HS256 签名 JWT 作为 userKey再走getOrCreateUser第三种方式适合跨端共享用户身份在服务端用同一把encryptionKey为任意userId签名 JWT客户端拿到的就是与平台绑定的用户凭证。签名逻辑在 jwt.tsSignJWT HS256 setIssuedAt()任何具备该密钥的一方都能独立生成合法 userKey。注意使用encryptionKey时必须同时提供userId否则抛出ChatConfigError提示选择一个未被占用的 userId。connect 成功后返回AuthenticatedClient它内部持有user含id、key对象并在每次请求中自动注入x-user-key: this.user.key请求头见 client.ts。因此后续所有调用createConversation、createMessage、listMessages等都不需要再手动传用户凭证。四、核心 API 操作一览Client/AuthenticatedClient暴露的操作由 OpenAPI 定义自动生成生成脚本见 openapi.ts调用botpress/chat-api导出 client 与 signals 类型从 client.ts 可以看到完整操作面会话createConversation、getConversation、getOrCreateConversation、deleteConversation、listConversations消息createMessage、getMessage、deleteMessage、listMessages用户createUser、getUser、getOrCreateUser、updateUser、deleteUser参与者addParticipant、removeParticipant、getParticipant、listParticipants事件createEvent、getEvent实时listenConversation值得注意的实现细节list属性client.ts为三类列表查询封装了基于nextToken的分页迭代器AsyncCollectionlisting.ts支持for await...of遍历所有分页数据也支持collect({ limit })一次性收集到数组// 遍历某会话的全部消息自动翻页 for await (const message of client.list.messages({ conversationId })) { console.log(message.payload) } // 最多取 100 条 const messages await client.list.messages({ conversationId }).collect({ limit: 100 })另外每次请求前_call都会先做一次_testConnection探测只执行一次并缓存结果并解析响应 payload——由于 Chat API 经由桥接 Webhook 转发服务端可能返回 2xx 状态码但 payload 内嵌错误码_checkPayloadForError会识别 400–599 的code字段并抛出ChatHTTPError见 client.ts。所有异常最终统一映射为ChatClientError/ChatHTTPError/ChatConfigErrorerrors.ts并保留 Axios 响应细节状态码、请求方法、路径、服务端 message便于排查。五、Realtime Events实时接收机器人消息轮询之外客户端还提供实时事件监听。readme 示例通过listenConversation订阅会话事件并用message_created信号等待机器人的回复// ... const listener await client.listenConversation({ id: conversation.id, }) const botResponse await new Promisechat.Message((resolve) { const onMessage (ev: chat.Signals[message_created]) { if (ev.userId client.user.id) { // message created by my current user, ignoring... return } listener.off(message_created, onMessage) resolve(ev) } listener.on(message_created, onMessage) }) console.log(Bots response:, botResponse.payload)事件机制与类型定义listener是SignalListenersignal-listener.ts本质是一个类型安全的事件发射器事件名即信号名如message_created事件负载由 zod schema 校验解析无法识别的负载会落入unknown信号不会导致监听崩溃。chat.Signals[message_created]是Signals索引类型源码由 signals schema 生成见 openapi.ts保证事件回调的负载有完整类型提示。除message_created外可推断会话相关的其他信号如message_deleted、conversation_*、event_created等都会以同名事件在 listener 上派发e2e 测试中即同时用到了message_created与message_deleted见 message.test.ts。SignalListener的状态机包含disconnected/connecting/connected三种状态并提供connect()/disconnect()方法listenConversation返回时已处于connected。事件发射器底层event-emitter.ts除常规on/off外还提供once只监听一次与onceOrMore回调返回stop-listening时停止监听否则持续监听后者被 e2e 测试用来跳过自己发出的消息、只捕获机器人回复。六、实时协议SSE 与 WebSocketlistenConversation支持通过protocol参数选择底层传输协议ServerEventsProtocol websocket | sse见 eventsource.ts默认sseconst listener await client.listenConversation({ id: conversation.id, protocol: websocket, // 或 sse })两种协议的实现差异SSE在浏览器端使用event-source-polyfill在 Node.js 端使用eventsource包请求头中携带x-user-key通过 polyfill 的headers选项或 Node 模块的 headers 选项注入WebSocket将http(s)前缀替换为ws(s)后建立原生WebSocket连接由于浏览器 WebSocket 无法自定义请求头x-user-key会被自动编码为 URL 查询参数?x-user-key...附带在连接地址上。无论哪种协议listenEventSource都会等待open事件确认连接建立后才 resolve并监听error/close事件向调用方派发对应事件。e2e 测试对sse与websocket两种协议都做了消息收发验证message.test.ts可据此确认两种协议在功能上等价。此外SignalListener内部有一个看门狗watchdog.ts连接建立后启动 60 秒CONNECTION_TIMEOUT计时器每收到一条消息watchdog.reset()就重置计时若超过 60 秒无消息看门狗会触发Client connection timed out错误并通过error事件通知应用用于及时发现静默断连。七、断线重连把连接生命周期握在自己手里readme 明确指出Client不会自动重连。这是刻意设计——把重连策略交给应用以便与业务状态如消息列表、UI 状态协调。官方给出的模式是监听error事件在断开后重连并同步状态const state { messages } // your application state const onDisconnection async () { try { await listener.connect() const { messages } await client.listMessages({ conversationId: conversation.id }) state.messages messages } catch (thrown) { console.error(failed to reconnect, retrying..., thrown) setTimeout(onDisconnection, 1000) // consider using a backoff strategy } } listener.on(error, (err) { console.error(connection lost, err) void onDisconnection() })要点拆解listener.on(error, ...)注册断线回调。连接异常、看门狗超时都会触发error事件见 signal-listener.ts触发后监听器内部已切换回disconnected状态listener.connect()是幂等且可重入的若已连接则直接返回若正在连接则等待既有连接完成signal-listener.ts因此重连调用是安全的重连成功后通过listener.listMessages拉取最新消息把补发的消息同步进应用状态避免重连窗口期的消息丢失重连失败不要无限重试注释建议实现指数退避backoff策略setTimeout(onDisconnection, 1000)是最简的固定间隔重试。从事件流角度理解一次断线 →error事件 → 应用主动connect()→open事件 → 服务端可能重新推送历史信号或应用自行listMessages补齐 → 状态收敛。这套应用掌控重连的模型与常见自动重连 SDK 相比把补偿逻辑补消息、刷新状态显式交给了业务层更适合 Chat 类产品对一致性的要求。八、e2e 测试验证从源码确认行为边界packages/chat-client/e2e 下的端到端测试可以作为本库行为的权威佐证运行需设置API_URL与ENCRYPTION_KEY环境变量见 config.ts消息收发message.test.ts验证了两种协议下基于 Botpress ID 与外部 IDfid的消息收发、删除消息后getMessage抛ResourceNotFoundError、metadata随消息透传但不进入 payload、bloc复合消息文本 图片的收发用户与身份user.test.ts验证了非法 fid含非法字符、超长会抛InvalidPayloadError、重复创建同 fid 用户会抛AlreadyExistsError、getOrCreateUser的幂等性多次调用返回同一用户连接失败webhook.test.ts验证了错误的 apiUrl 会使createUser抛出ChatClientError印证_testConnection与统一错误映射的链路。这些测试同时展示了waitFor/onceOrMore/Signals等事件 API 的典型用法utils.ts是阅读事件监听能力的极佳范例。九、总结何时选择 botpress/chatbotpress/chat定位清晰面向用代码直接驱动 Botpress 机器人对话的场景与在 Dashboard 中使用 Chat Widget 互补。适用场景包括需要自定义前端 UI、以 Webhook ID 接入 Botpress Chat API 的应用需要在 Node.js 服务端代理/编排对话创建会话、发消息、批量拉取历史需要实时订阅消息与事件、并对断线重连有明确业务策略的产品。核心取舍简单性一个类搞定认证、请求与事件流类型齐全与可控性不自动重连把连接生命周期交给应用。上手路径建议按 readme 顺序先跑通 API Queries 示例拿到首条机器人回复再替换为listenConversation实时接收最后在生产环境补充基于error事件的退避重连与状态补偿逻辑。延伸阅读官方使用文档主体packages/chat-client/readme.md客户端核心实现packages/chat-client/src/client.tsconnect 认证分支、请求封装、错误解析实时事件监听packages/chat-client/src/signal-listener.ts 与 packages/chat-client/src/eventsource.tsSSE / WebSocket 双协议类型与配置定义packages/chat-client/src/types.ts端到端测试packages/chat-client/e2e/message.test.ts、packages/chat-client/e2e/user.test.ts赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Botpress CLI 实战指南使用 bp 命令完成 GPT/LLM Agent 的构建、部署与云端管理Botpress CLI 实战指南使用 bp 命令完成 GPT/LLM Agent 的构建、部署与云端管理 Botpress CLI botpress/cAI 应用后端Botpress LLMz Chat Exits 实战用类型安全的 Exit 机制实现对话退出与人机移交Botpress LLMz Chat Exits 实战用类型安全的 Exit 机制实现对话退出与人机移交 LLMz packages/llmz 是 BotAI 应用后端Botpress BambooHR 集成实战让 GPT/LLM Agent 读取与管理员工数据Botpress BambooHR 集成实战让 GPT/LLM Agent 读取与管理员工数据 导读 本文围绕 Botpress 开源仓库中 BambooHRAI 应用后端上一篇Trigger.dev任务取消机制灵活控制任务生命周期的终极指南下一篇Modern C Template 单元测试完整教程GoogleTest与Catch2深度对比 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考