Corsair Bolt IoT 插件接入指南在 Agent 应用中读写 Bolt 云平台设备与串口【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读本文以 corsair-dev/boltiot 插件为主体讲解如何通过 Corsair 平台把 Bolt IoT 云上的硬件设备传感器、继电器、UART 串口外设以统一、带类型校验的 API 形式暴露给你的 LLM Agent。读完本文你将掌握该插件的安装方式、7 个核心端点的参数与返回值语义、API Key 认证流程、底层请求封装与错误重试机制并知道如何通过仓库内的源码与测试验证其行为。Bolt IoT 插件是什么Bolt IoT 是一个面向物联网场景的云平台用于把设备、传感器和硬件连接到云端仪表盘见 plugin-docs.yaml。corsair-dev/boltiot是 Corsair 生态中对应的官方插件它把 Bolt 云远程 API 的常用命令isOnline、analogRead、digitalWrite、digitalRead、serialRead、serialWrite、serialWR封装成结构化的device.*与serial.*端点让 Agent 可以通过自然语言任务安全地操作真实硬件。从源码结构看插件遵循 Corsair 插件的标准形态入口文件声明插件 IDboltiot、定义认证配置api_key、注册嵌套端点、提供输入/输出 Zod 校验 Schema、事件日志与错误处理器并实现了keyBuilder负责在首次调用时向租户索取 API Key。安装与依赖在 pnpm 工作区如本仓库的 monorepo 结构中安装pnpm add corsair-dev/boltiot该包以 Corsair 核心库与 Zod 作为peerDependencies见 package.jsonpeerDependencies: { corsair: 0.1.0, zod: ^4.1.13 }这意味着使用前需确保应用内已安装corsair核心包与zod^4.1.13。包版本为0.1.1采用 ESM 输出type: module构建产物位于dist目录许可证为 Apache-2.0。快速创建一个插件实例boltiot()工厂函数接收可选配置并返回 Corsair 插件对象index.tsimport { boltiot } from corsair-dev/boltiot; const plugin boltiot({ // 可选直接内联 API Key不传则由 Corsair 在首次使用时向租户提示输入 // key: YOUR_BOLT_API_KEY, // authType: api_key, // 默认即为 api_key });创建后的插件实例包含id、authConfig、schema、endpoints、webhooks、endpointMeta、endpointSchemas、errorHandlers与keyBuilder等字段。BoltIotPluginOptions还允许传入自定义hooks、errorHandlers与permissions用于在 Corsair 侧做细粒度控制。认证API Key认证方式为API Key。Corsair 会在租户首次使用插件时提示输入凭据README 中的 Corsair prompts your tenant for credentials on first use。认证配置在源码中明确声明为单账号模型export const boltIotAuthConfig { api_key: { account: [one] as const, }, } as const satisfies PluginAuthConfig;keyBuilder的取值优先级为① 若调用来源是 endpoint 且显式传入了options.key直接使用内联 Key② 否则从 Corsair 的凭据存储中读取api_key③ 两者皆无则抛出AuthMissingError(boltiot, api_key)index.ts。值得注意的实现细节Bolt 远程 API 把 API Key 放在 URL 路径中https://cloud.boltiot.com/remote/{api_key}/{command}而非Authorization请求头——这一点也被 api.test.ts 的断言expect(req.auth).toBeNull()所验证。端点总览插件共暴露 7 个端点按命名空间分为设备device与串口serial两组风险等级分为read与writeOperationOperation IDRiskDescriptiondevice.analogReadboltiot.api.device.analogReadread读取 Bolt 设备指定引脚的模拟值0-1023device.checkStatusboltiot.api.device.checkStatusread检查指定 Bolt 设备是否在线device.digitalReadboltiot.api.device.digitalReadread读取指定 Bolt 设备数字引脚的状态device.digitalWriteboltiot.api.device.digitalWritewrite将指定 Bolt 设备的数字引脚设为 HIGH 或 LOWserial.readboltiot.api.serial.readread从 Bolt 设备 UART 读取传入的串口数据serial.writeboltiot.api.serial.writewrite通过 UART 向 Bolt 设备发送 ASCII 串口数据serial.writeReadboltiot.api.serial.writeReadwrite发送串口数据并立即读取回复在源码中端点按嵌套结构注册为device.checkStatus / device.analogRead / device.digitalWrite / device.digitalRead与serial.read / serial.write / serial.writeReadindex.tsendpointMeta为每个端点声明了riskLevel与描述index.ts风险级别即 README 表格中的read/write列。Device 端点深入设备组端点定义在 endpoints/device.ts输入输出 Schema 在 endpoints/types.ts。每个端点执行成功后都会调用logEventFromContext记录事件如boltiot.device.checkStatus、boltiot.device.analogRead便于在 Corsair 侧审计。checkStatus设备在线状态输入deviceNameBolt 设备 ID/名称如BOLT1234567输出success布尔、valueonline或offline、可选time官方isOnline返回的状态变更时间戳、deviceName底层调用 Bolt 云的isOnline命令。time字段只有在响应包含时才透传如Sun 2018-05-06 08:14:43 UTC见 schema/database.ts 中的注释。实现见 device.ts。analogRead模拟引脚读取输入deviceNamepin可选默认A0z.string().default(A0)输出value数字0-1023、rawValue原始字符串、pin、deviceName底层调用analogRead命令。返回值会经过严格校验parseAnalogReading要求原始值必须为纯数字且在 0-1023 范围内否则抛出BoltIotAPIErrordevice.ts。对应测试覆盖了正常读取512与畸形数据12x两条路径api.test.ts。digitalWrite数字引脚写操作输入deviceNamepin如0~4state枚举HIGH | LOW | 1 | 0输出success、value设备响应、pin、state、deviceNameHIGH或1会被归一化为HIGH其余归一化为LOW再以stateHIGH/LOW形式发送device.ts。测试验证了 URL 中携带stateHIGHapi.test.ts。digitalRead数字引脚读操作输入deviceNamepin如0~4输出value1表示 HIGH0表示 LOW、pin、deviceNameSerial 端点深入串口组端点定义在 endpoints/serial.ts用于与接在 Bolt 模块 UART 上的外设如 AT 指令设备通信。serial.read读取串口数据输入deviceNametill可选——ASCII 字符码读到该字符为止如10表示换行符输出success、value读到的串口数据、deviceName底层调用serialRead命令测试中传入till: 10并在 URL 中携带till10api.test.ts。serial.write发送串口数据输入deviceNamedata要发送的 ASCII 字符串如AT输出success、value写操作状态响应、deviceName底层调用serialWrite命令典型场景是向 GSM/传感器模块发送指令。serial.writeRead发送并读取回复输入deviceNamedatatill可选读取回复的结束字符码输出success、value写读命令返回的回复、deviceName底层调用的是serialWR命令而非serialWriteRead这是官方远程 API 的命令名测试同样验证了 URL 中的/serialWR路径api.test.ts。底层客户端makeBoltIotRequest所有端点最终都经由 client.ts 中的makeBoltIotRequest(command, apiKey, query)发出请求其核心行为请求地址https://cloud.boltiot.com/remote/{apiKey}/{command}?{query}API Key 直接内嵌在路径中超时20 秒使用AbortSignal.timeout(REQUEST_TIMEOUT_MS)超时抛出BoltIotAPIError响应校验要求响应体为对象且包含success字段success 0或 HTTP 非 2xx 时抛出BoltIotAPIError错误信息取自value字段响应信封统一为{ success, value, time? }其中success兼容官方 Python SDK 的字符串形式1/0与线上 API 的数字形式1/0——这一点在 schema/database.ts 的BoltIotCommandSchema 中用z.union做了明确声明。限流与错误处理客户端定义了两种错误类型client.tsBoltIotAPIError通用 API 错误携带可选code与statusBoltIotRateLimitError429 限流错误携带retryAfterMs从Retry-After响应头解析支持秒数与 HTTP 日期两种格式。对应的默认错误处理器error-handlers.ts为RATE_LIMIT_ERROR命中 429/限流类错误时返回{ maxRetries: 5, headersRetryAfterMs }即最多重试 5 次并尊重服务端建议的等待时间AUTH_ERROR命中 401 /invalid api key/unauthorized等签名时返回{ maxRetries: 0 }凭据错误不重试DEFAULT其余错误不重试。数据模型与 Schema 校验插件通过 Zod 为每个端点定义了输入/输出 Schemaendpoints/types.ts并在插件层以boltIotEndpointSchemas统一注册index.ts。Corsair 会据此在运行时校验 Agent 的调用参数与返回结果保证类型安全。数据库层 Schemaschema/index.ts定义了devices与commands两个实体export const BoltIotSchema { version: 1.0.0, entities: { devices: BoltIotDevice, // { deviceName: string } commands: BoltIotCommand, // { success, value, time? } }, };测试验证仓库为该插件提供了完整的单元测试api.test.ts通过 mockfetch验证插件元数据完整id为boltiot、7 个端点全部注册未配置 Key 时keyBuilder抛出AuthMissingError每个端点生成的 URL 路径与查询参数正确如/isOnline?deviceName...、/analogRead?pinA0、/serialWR异常路径success: 0抛 API 错误、429 抛限流错误且正确解析retryAfterMs、空 JSON 体抛错模拟读数越界/畸形数据的校验逻辑。Webhooks 与扩展说明README 明确指出该插件不支持 WebhooksNo webhooks。源码中webhooks: {}与pluginWebhookMatcher: () false与之呼应index.ts即 Bolt 云事件不会主动推送到 Corsair只能通过端点轮询/命令方式获取设备状态。如果需要自定义行为BoltIotPluginOptions支持注入hooks、errorHandlers与permissions也可以在创建插件时直接传入key跳过租户凭据输入环节适合服务端直连场景。许可corsair-dev/boltiot以 Apache-2.0 协议开源package.json。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考