企业官网建设流程全解析

Corsair × BoloForms 插件接入指南：以 API Key 认证实现文档列表查询与本地数据同步

【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair

BoloForms（BoloForms Signature）是一款在线表单/电子签名平台，支持调查问卷、申请表、潜在客户收集等带工作流能力的业务场景。本文以 packages/boloforms/README.md 为核心骨架，结合packages/boloforms/源码与docs/plugins/boloforms/文档，讲解如何在 Corsair 中接入 BoloForms 插件、完成租户 API Key 认证、调用documents.list查询工作区文档，并利用同步实体在本地数据库进行检索。读完本文你将掌握从安装、配置、连接租户到真实调用与排错的完整链路。

插件速览

@corsair-dev/boloforms是 Corsair 的 BoloForms 插件包，遵循 Corsair 统一的插件模型：一个插件 = 认证配置（authConfig）+ 本地数据库 Schema（schema）+ 一组类型安全的端点（endpoints）+ 错误处理策略。

从 packages/boloforms/index.ts 可以看到插件核心定义：

export type BoloformsPluginOptions = { /** Authentication method. BoloForms Signature only supports API keys. */ authType?: PickAuth<'api_key'>; /** * BoloForms API key, sent as the `x-api-key` header. When omitted the key * is resolved from the account key manager instead. */ key?: string; hooks?: InternalBoloformsPlugin['hooks']; errorHandlers?: CorsairErrorHandler; permissions?: PluginPermissionsConfig<typeof boloformsEndpointsNested>; };

当前版本提供1 个类型化 API 操作与1 个同步实体：

认证方式

BoloForms 仅支持API Key认证（对应 HTTP 层为x-api-key请求头）。packages/boloforms/README.md中明确说明：

Auth: API key. Corsair prompts your tenant for credentials on first use.

即 Corsair 会在租户首次调用时引导其录入凭据，无需你在插件初始化阶段手动配置密钥。底层认证配置在 index.ts：

export const boloformsAuthConfig = { api_key: { account: ['tenant_external_id'] as const, }, } as const satisfies PluginAuthConfig;

Webhooks

当前插件不提供任何 Webhook，插件对象中的webhooks: {}与pluginWebhookMatcher: undefined表明未接入推送事件（参见 index.ts）。

许可证

@corsair-dev/boloforms以Apache-2.0许可证发布。

安装插件

使用 pnpm 安装：

pnpm add @corsair-dev/boloforms

也可以使用 npm、yarn 或 bun（与 Corsair 本体一并安装）：

npm install corsair @corsair-dev/boloforms

yarn add corsair @corsair-dev/boloforms

bun add corsair @corsair-dev/boloforms

插件包由 tsup 构建（见 tsup.config.ts），构建产物通过包的exports字段暴露，可直接在 Node.js 与打包器环境中使用。

在 Corsair 应用中注册插件

参照 docs/plugins/boloforms/overview.mdx 的 Setup 步骤，创建一个corsair.ts：

import Database from 'better-sqlite3'; import { createCorsair } from 'corsair'; import { boloforms } from '@corsair-dev/boloforms'; export const corsair = createCorsair({ plugins: [ boloforms(), ], database: new Database('corsair.db'), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });

要点说明：

• database：使用better-sqlite3创建的本地数据库文件（如corsair.db），插件同步的documents实体将持久化于此；
• kek：Corsair 的密钥加密密钥（Key Encryption Key），用于加密租户凭据，务必从环境变量注入而非硬编码；
• hub：projectApiKey与signingSecret用于连接 Corsair Hub（托管连接页、投递凭据结果），完整说明见 docs/quick-start.mdx；
• 多租户是默认行为：通过corsair.withTenant(id)限定调用范围，租户间数据与凭据相互隔离，详见 docs/concepts/multi-tenancy.mdx。

选择认证方式

BoloForms 目前仅支持 API Key，无需在初始化时做任何配置：

boloforms()

当你（作为租户）发起第一次请求时，Corsair 会自动提示录入 API Key。相关概念见 docs/concepts/api-key.mdx。

当然，如果希望由服务端统一管理密钥（而非由租户各自录入），也可以在插件选项中显式传入：

boloforms({ key: process.env.BOLOFORMS_API_KEY! })

从 index.ts 的keyBuilder实现可见其优先级：当调用来源为endpoint且显式传入了options.key时直接返回；否则走ctx.keys?.get_api_key()从 Corsair 的账户密钥管理器读取；两者都取不到时抛出AuthMissingError('boloforms', 'api_key')。这也印证了 README 中“Corsair prompts your tenant for credentials on first use”的行为。

连接租户

插件注册完成后，为租户生成一个连接链接（Connect Link），将租户引导至 Corsair Hub 页面完成凭据录入，Hub 再通过回调把结果投递回你的应用：

const { connectUrl } = await corsair.manage.connect.createLink({ plugin: 'boloforms', tenantId: 'acme', }); // redirect the user's browser to connectUrl

租户连接后，corsair.withTenant('acme')即可使用该租户的凭据调用 BoloForms API。连接流程的详细说明见 docs/management/connect.mdx。

调用 documents.list 查询文档

端点与底层映射

documents.list是当前插件唯一暴露的端点，其 Operation ID 为boloforms.api.documents.list，风险等级为read（只读操作，无写副作用），描述为 “Retrieve a list of documents from a Boloforms workspace, with optional filtering and pagination”。

端点在 index.ts 中注册：

const boloformsEndpointsNested = { documents: { list: Documents.list, }, } as const; export const boloformsEndpointSchemas = { 'documents.list': { input: BoloformsEndpointInputSchemas.getDocumentsList, output: BoloformsEndpointOutputSchemas.getDocumentsList, }, } as const; const boloformsEndpointMeta = { 'documents.list': { riskLevel: 'read', description: 'Retrieve a list of documents from a Boloforms workspace, with optional filtering and pagination', }, } as const;

其底层调用的是 BoloForms Signature 的GET /signature/get-documents接口（见 endpoints/documents.ts），请求头同时携带x-api-key与workspaceid。

调用示例

const tenant = corsair.withTenant('acme'); await tenant.boloforms.api.documents.list({});

传入查询参数时（如分页）：

await tenant.boloforms.api.documents.list({ workspaceId: 'ws-xxx', page: '1', limit: '10', });

注意：workspaceId是必填的输入字段，其余参数均为可选。

输入参数详解

以下参数表来自 docs/plugins/boloforms/api.mdx，与 endpoints/types.ts 中的 Zod Schema 完全一致：

注意：除workspaceId外的分页/过滤参数均为string类型，符合 BoloForms OpenAPI 的 query 传参约定。

输出结构

documents.list的返回结构（同样经 Zod 校验，见 endpoints/types.ts）：

documents[]中单个文档的完整类型（见 schema/database.ts）：

{ documentId: string, name?: string, documentName?: string, status?: string, signingType?: string, createdAt?: string, updatedAt?: string }[]

pagination的完整类型：

{ currentPage?: number, totalPages?: number, totalDocuments?: number }

值得注意的是，响应 Schema 通过.passthrough()保留了未声明的额外字段；同时源码注释表明，真实GET /signature/get-documents响应中常常省略pagination块，而是改用documentsCount/formCount表达数量信息——BoloformsDocumentsPagination是对官方 OpenAPI 分页结构的兼容性定义。

字段细节：name 与 documentName

BoloformsDocument同时声明了name与documentName两个可选字段：官方 OpenAPI 的DocumentsResponse.documents[]只声明documentId, name, createdAt, status，而真实接口返回中还包含documentName；signingType则是发送签署的类型判别字段（FORM_TEMPLATE或PDF_TEMPLATE）。这些兼容性处理使得 Schema 既能通过官方文档校验，也能接受线上真实响应。

底层请求实现与错误处理

HTTP 客户端

所有 BoloForms 请求都经由 client.ts 的makeBoloformsRequest发出，它基于corsair/http的request构建 OpenAPI 配置：

• 基础地址：https://sapi.boloforms.com（对应 OpenAPI Server URLhttps://sapi.boloforms.com/signature）；
• 请求头：Content-Type: application/json、Accept: application/json、x-api-key: <apiKey>、workspaceid: <workspaceId>；
• GET 请求将query参数附加到 URL，POST/PUT/PATCH 请求将body以 JSON 发送；
• 内置限流重试配置：enabled: true、maxRetries: 3、initialRetryDelay: 1000（毫秒）、backoffMultiplier: 2（指数退避）、retryAfter: 'Retry-After'响应头识别。

任何ApiError都会被包装为BoloformsAPIError（携带status、statusText、body、retryAfter），便于上层统一识别。

错误处理策略

error-handlers.ts 定义了三类错误处理：

• RATE_LIMIT_ERROR：命中 429 或消息含rate_limited/429时触发，最多重试5 次，并优先采用服务端Retry-After头指定等待时间；
• AUTH_ERROR：命中 401/403 或消息含unauthorized/forbidden/invalid_auth时触发，不重试（注意：BoloForms 真实接口对无效密钥返回的是 403 而非 401）；
• DEFAULT：兜底策略，不重试。

这些内置错误处理可通过插件选项errorHandlers覆盖或扩展：

boloforms({ errorHandlers: { // 自定义错误处理器 }, });

本地数据库同步与查询

插件将documents实体同步到 Corsair 本地数据库（Schema 见 schema/index.ts）：

export const BoloformsSchema = { version: '1.0.0', entities: { documents: BoloformsDocument, }, } as const;

同步后即可对本地数据执行快速查询：

const tenant = corsair.withTenant('acme'); // 搜索 await tenant.boloforms.db.documents.search({ /* 过滤条件 */ }); // 列表 await tenant.boloforms.db.documents.list({ /* 过滤条件 */ });

documents实体的字段、过滤条件与操作符说明详见 docs/plugins/boloforms/database.mdx。

测试验证与行为佐证

插件行为由 api.test.ts 与 schema.test.ts 双重保障，测试覆盖了：

• Schema 校验：BoloformsSchema.version符合 semver；documents实体可从官方文档结构解析出documentId；
• 请求构造：documents.list会以('signature/get-documents', KEY, WORKSPACE, { method: 'GET', query: {...} })的形式调用makeBoloformsRequest，并记录事件boloforms.documents.list（状态completed）；
• 分页兼容：响应含 OpenAPIpagination块时也能正确解析；
• 错误传播：客户端错误会原样向上抛出；
• 认证解析：keyBuilder在显式传入options.key时直接返回；从密钥管理器读取到 API Key 时正常返回；读取为空时抛出AuthMissingError。

此外 docs/plugins/boloforms/api.mdx 提供了完整的参数与类型参考，docs/plugins/boloforms/overview.mdx 给出了从安装到查询的端到端指引。

在 Agent 中暴露插件能力

插件注册后，其操作可通过 MCP 适配层暴露为 MCP 工具供 Agent（如 Claude、Cursor 等）调用。相关接入方法见 docs/mcp-adapters/mcp-adapters.mdx 及各框架适配器文档：

• LangChain 适配器
• LlamaIndex 适配器
• Mastra 适配器

以及 docs/getting-started/set-up-with-your-agent.mdx 的 Agent 接入快速上手。

小结

通过 Corsair 接入 BoloForms，你可以用统一、类型安全的方式完成以下工作：

1. 用pnpm add @corsair-dev/boloforms安装插件，并在createCorsair中注册boloforms()；
2. 租户首次调用时录入 API Key，Corsair 负责密钥的安全存储与管理（x-api-key+workspaceid请求头由 client.ts 自动构造）；
3. 调用tenant.boloforms.api.documents.list({ workspaceId, ... })查询工作区文档，支持关键词、日期、分页、排序等过滤；
4. 通过本地同步的documents实体执行.search()/.list()离线快速检索；
5. 内置限流退避重试与认证错误处理，异常情况由BoloformsAPIError统一承载。

当前插件仅提供只读的文档列表能力且无 Webhook，若需要写入或推送事件能力，可关注后续版本或结合 docs/plugins/boloforms/api.mdx 中的操作列表评估其他端点。

【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair