2026/9/16 21:51:55
FEATURED · 精选文章 
Corsair Veriphone 插件实战在 AI Agent 中接入电话号码校验与积分查询【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/veriphone是 Corsair 生态中封装 Veriphone 电话号码校验 API 的官方插件它把号码是否有效、属于哪个国家、由哪家运营商承载这类能力变成 AI Agent 可以直接调用的四个工具端点。读完本文你将掌握该插件的安装方式、API Key 认证机制、四个端点的参数与响应结构、错误重试策略并能通过源码理解其在 Corsair 插件体系中的实现原理直接在自己的 Agent 工程中落地。插件定位拉取式的号码校验能力Veriphone 是一个基于 REST 的号码校验服务本身不推送任何事件属于典型的拉取式pull-basedAPI。Corsair 将其封装为插件后端点以工具tool的形式暴露给 AgentAgent 可以在对话中直接触发验证这个号码查一下余额美国有哪些运营商覆盖等操作。从插件声明看其核心配置集中在 packages/veriphone/index.ts插件 ID 为veriphone只支持api_key一种认证方式且不注册任何 Webhook源码注释明确说明 Veriphone 只有 REST 端点、无事件投递。同时它在 packages/veriphone/schema/database.ts 中声明了一个空实体集VeriphoneEntities z.object({})说明该插件不向本地数据库写入任何实体所有数据校验结果、余额、覆盖范围均实时读取这与纯拉取型 API的定位完全一致。安装插件已发布到 npm包名为corsair-dev/veriphone。它声明了corsair 0.1.0与zod ^4.1.13两个 peer 依赖安装时需确保工程中已就绪详见 packages/veriphone/package.jsonpnpm add corsair-dev/veriphone快速接入在 Corsair 中注册插件插件的入口是一个同名的veriphone()工厂函数传入VeriphonePluginOptions即可获得完整的插件实例import { veriphone } from corsair-dev/veriphone; import { corsair } from corsair/core; const app corsair({ plugins: [ veriphone({ // 可选直接把 API Key 写死在代码/环境变量中 key: process.env.VERIPHONE_API_KEY, // 可选自定义错误处理器会与默认处理器合并 errorHandlers: { // ...你的自定义 handler }, }), ], });可配置项定义在 packages/veriphone/index.ts#L34-L53 的VeriphonePluginOptions中完整清单如下选项类型说明authTypeapi_key认证方式目前仅支持api_key缺省时自动取默认值keystringVeriphone API Key来自 Veriphone 控制台每次请求以Authorization: Bearer key发送hooksInternalVeriphonePlugin[hooks]可选端点的生命周期钩子errorHandlersCorsairErrorHandler可选自定义错误处理器与内置默认处理器合并permissionsPluginPermissionsConfig...可选权限配置见下文风险分级认证机制API Key 的三种获取路径README 指出Auth: API key. Corsair prompts your tenant for credentials on first use即首次使用时 Corsair 会向你的租户tenant索要凭据。这一行为由 packages/veriphone/index.ts#L195-L209 的keyBuilder实现其优先级如下若插件配置了options.key且来源为endpoint直接使用它否则调用ctx.keys.get_api_key()从账号密钥管理器读取已存储的 Key两处都没有时抛出AuthMissingError(veriphone, api_key)提示租户补充凭据。值得注意的一个细节tryGetStoredKey见 packages/veriphone/client.ts#L66-L78会捕获密钥管理器抛出的 no dek found 错误并将其视为无已存储 Key而非中断请求——因为完全通过插件选项配置 Key、从未碰过密钥管理器的账号本就没有 DEK数据加密密钥这是合法状态。请求发送统一走 packages/veriphone/client.ts#L92-L134 的makeVeriphoneRequest基于https://api.veriphone.ioAPI 版本3所有端点以 GET query 参数调用认证头为Authorization: Bearer key。源码特意注释说明不用?key或 Cookie 方式传 Key是为了避免 Key 出现在日志中。端点总览README 中的端点表格与本仓库 packages/veriphone/endpoints 目录下的四个实现一一对应操作Operation ID风险级别底层端点描述coverageveriphone.api.coveragereadGET /v3/coverage/current列出支持 Currentmodecurrent查询的国家creditsveriphone.api.creditsreadGET /v3/credits获取账户余额与按查询模式拆分的用量getExamplePhoneNumberveriphone.api.getExamplePhoneNumberreadGET /v2/example获取指定国家与线路类型的示例号码verifyPhoneNumberveriphone.api.verifyPhoneNumberwriteGET /v3/verify校验号码有效性返回格式、区域与运营商信息端点元数据风险级别与描述定义在 packages/veriphone/index.ts#L117-L141 的veriphoneEndpointMeta中。风险分级决定了权限默认值三个只读端点默认open而verifyPhoneNumber默认allow——因为其record: true会在服务端侧写入校验历史属于写操作见 packages/veriphone/index.ts#L48-L52 注释。1. verifyPhoneNumber号码校验write对应实现见 packages/veriphone/endpoints/verify-phone-number.ts。该端点封装了GET /v3/verify输入参数由 packages/veriphone/endpoints/types.ts#L40-L69 的VerifyPhoneNumberInputSchema定义参数类型默认值说明phonestring必填待校验号码建议使用 E.164 国际格式长度 4–25 字符且含 4–20 位数字default_countrystring可选ISO 3166-1 alpha-2 国家码如US当号码无国际前缀时使用modestatic \| currentstaticstatic消耗 1 积分current为实时注册库查询消耗 10 积分recordboolean可选为true时把结果保存到账户校验历史校验响应结构非常丰富VerifyPhoneNumberResponseSchematypes.ts#L75-L113核心字段是statussuccess/error/syntax-error与phone_valid失败时reason会给出too_short、too_long、invalid_length、invalid_country_code、unrecognized_range、not_a_number等具体原因。成功时则返回phone_type共 10 种mobile、fixed_line、fixed_line_or_mobile、toll_free、premium_rate、shared_cost、voip、short_code、emergency、unknown、carrier、country、country_code、country_prefix、international_number、local_number、e164、timezone等字段在modecurrent下还包含original_carrier、current_carrier、ported是否携号转网、current_lookup、carrier_data_source等实时比对信息。实现上有一个值得借鉴的点verify-phone-number.ts#L35-L37请求发出前先用 Zod Schema 校验输入因为一次校验会消耗积分格式错误的号码绝不应打到上游 API。调用成功后还会通过logEventFromContext记录veriphone.verifyPhoneNumber事件便于审计与追踪。2. getExamplePhoneNumber获取示例号码read对应 packages/veriphone/endpoints/get-example-phone-number.ts封装GET /v2/example。输入只有两个字段参数类型说明country_codestringISO 3166-1 alpha-2 国家码如US调用前务必先确认国家码typestring线路类型可选mobile、fixed_line、toll_free、premium_rate、shared_cost、voip缺省为mobile响应包含phone_type、country_code、country_prefix、international_number、local_number、e164等字段。源码注释types.ts#L151-L166记录了真实的兼容性处理/v2/example实测返回大写的线路类型如MOBILE因此响应 Schema 先toLowerCase()再校验部分镜像会把e164键写成大写E164Schema 对两种键都做了兼容。这是给 Agent 使用时的实用提示该端点在官方 v2/v3 参考文档中并未收录仅见于第三方镜像文档使用时需以实际响应为准。3. credits余额与用量查询read对应 packages/veriphone/endpoints/credits.ts封装GET /v3/credits无输入参数。响应CreditsResponseSchematypes.ts#L183-L200包含email账户邮箱counter当前已用积分计数数值active账户是否激活payg按量付费额度limit积分上限plan套餐名renew续费周期last_reset上次重置时间v3 中为{ seconds, nanos }对象v2 中为字符串Schema 做了联合兼容usage按static/current两种模式拆分的{ count, credits }用量4. coverage覆盖国家列表read对应 packages/veriphone/endpoints/coverage.ts封装GET /v3/coverage/current无输入参数。响应types.ts#L214-L226为{ countries: [{ iso, covered }], updatedAt }——iso是国家码covered表示该国家是否支持 Current 模式实时查询。错误处理与重试策略插件的错误处理逻辑集中在 packages/veriphone/error-handlers.ts与 Veriphone v3 文档的错误码表一一对应错误码含义处理器行为429限流RATE_LIMIT_ERROR最多重试5 次并遵循Retry-After头headersRetryAfterMs等待后重试401API Key 缺失或无效AUTH_ERROR打印告警日志maxRetries: 0不重试402积分不足PAYMENT_REQUIRED_ERROR打印告警并提示充值或降低查询量不重试404资源不存在NOT_FOUND_ERROR不重试5xx服务端错误SERVER_ERROR不重试其他兜底DEFAULT打印错误信息不重试限流处理有一个精妙的细节error-handlers.ts#L39-L47注释指出maxRetries必须大于 0headersRetryAfterMs才会生效——因为绑定器只在真正发生重试时才会等待该时间。每个匹配器都优先取错误对象上的结构化status字段同时用消息文本匹配做兜底。底层错误对象是 packages/veriphone/client.ts#L12-L42 定义的VeriphoneAPIError它从corsair/http的ApiError中透传status、statusText、body、retryAfter以及rateLimitLimit/rateLimitRemaining/rateLimitReset三个限流头字段供上述处理器直接检查无需重新发请求。测试与验证仓库提供了两层测试packages/veriphone/api.test.ts、packages/veriphone/endpoints.test.ts 等Schema 与端点单元测试验证 Zod Schema 的输入输出解析、错误处理器匹配逻辑真实 API 冒烟测试api.test.ts中标注了VERIPHONE_API_KEY环境变量未设置时自动跳过describe.skip设置后会真实调用 Veriphone API 并断言响应形状。例如测试用14169670000校验断言status success、phone_valid true、country_code CA用country_code: US, type: mobile获取示例号码等。这意味着如果你要自测可以这样运行VERIPHONE_API_KEY你的密钥 pnpm test小结corsair-dev/veriphone是一个小而精的拉取式集成插件四个端点完整覆盖了号码校验、示例号码、余额查询与覆盖查询四类场景API Key 认证支持配置项直传与租户级密钥管理两种方式内置的按错误码分类的重试策略与VeriphoneAPIError结构化错误让 Agent 能够优雅处理限流、积分不足等业务异常而无 Webhook、无本地持久化的极简设计使其非常适合作为对话式 AI 中按需触发的号码工具。若需在应用层补充权限控制可直接利用其permissions选项——只读端点默认开放verifyPhoneNumber作为写操作默认受控开箱即用的分级策略为生产环境的多租户接入提供了安全保障。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Corsair Veriphone 插件实战：在 AI Agent 中接入电话号码校验与积分查询
Corsair Veriphone 插件实战在 AI Agent 中接入电话号码校验与积分查询【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/veriphone是 Corsair 生态中封装 Veriphone 电话号码校验 API 的官方插件它把号码是否有效、属于哪个国家、由哪家运营商承载这类能力变成 AI Agent 可以直接调用的四个工具端点。读完本文你将掌握该插件的安装方式、API Key 认证机制、四个端点的参数与响应结构、错误重试策略并能通过源码理解其在 Corsair 插件体系中的实现原理直接在自己的 Agent 工程中落地。插件定位拉取式的号码校验能力Veriphone 是一个基于 REST 的号码校验服务本身不推送任何事件属于典型的拉取式pull-basedAPI。Corsair 将其封装为插件后端点以工具tool的形式暴露给 AgentAgent 可以在对话中直接触发验证这个号码查一下余额美国有哪些运营商覆盖等操作。从插件声明看其核心配置集中在 packages/veriphone/index.ts插件 ID 为veriphone只支持api_key一种认证方式且不注册任何 Webhook源码注释明确说明 Veriphone 只有 REST 端点、无事件投递。同时它在 packages/veriphone/schema/database.ts 中声明了一个空实体集VeriphoneEntities z.object({})说明该插件不向本地数据库写入任何实体所有数据校验结果、余额、覆盖范围均实时读取这与纯拉取型 API的定位完全一致。安装插件已发布到 npm包名为corsair-dev/veriphone。它声明了corsair 0.1.0与zod ^4.1.13两个 peer 依赖安装时需确保工程中已就绪详见 packages/veriphone/package.jsonpnpm add corsair-dev/veriphone快速接入在 Corsair 中注册插件插件的入口是一个同名的veriphone()工厂函数传入VeriphonePluginOptions即可获得完整的插件实例import { veriphone } from corsair-dev/veriphone; import { corsair } from corsair/core; const app corsair({ plugins: [ veriphone({ // 可选直接把 API Key 写死在代码/环境变量中 key: process.env.VERIPHONE_API_KEY, // 可选自定义错误处理器会与默认处理器合并 errorHandlers: { // ...你的自定义 handler }, }), ], });可配置项定义在 packages/veriphone/index.ts#L34-L53 的VeriphonePluginOptions中完整清单如下选项类型说明authTypeapi_key认证方式目前仅支持api_key缺省时自动取默认值keystringVeriphone API Key来自 Veriphone 控制台每次请求以Authorization: Bearer key发送hooksInternalVeriphonePlugin[hooks]可选端点的生命周期钩子errorHandlersCorsairErrorHandler可选自定义错误处理器与内置默认处理器合并permissionsPluginPermissionsConfig...可选权限配置见下文风险分级认证机制API Key 的三种获取路径README 指出Auth: API key. Corsair prompts your tenant for credentials on first use即首次使用时 Corsair 会向你的租户tenant索要凭据。这一行为由 packages/veriphone/index.ts#L195-L209 的keyBuilder实现其优先级如下若插件配置了options.key且来源为endpoint直接使用它否则调用ctx.keys.get_api_key()从账号密钥管理器读取已存储的 Key两处都没有时抛出AuthMissingError(veriphone, api_key)提示租户补充凭据。值得注意的一个细节tryGetStoredKey见 packages/veriphone/client.ts#L66-L78会捕获密钥管理器抛出的 no dek found 错误并将其视为无已存储 Key而非中断请求——因为完全通过插件选项配置 Key、从未碰过密钥管理器的账号本就没有 DEK数据加密密钥这是合法状态。请求发送统一走 packages/veriphone/client.ts#L92-L134 的makeVeriphoneRequest基于https://api.veriphone.ioAPI 版本3所有端点以 GET query 参数调用认证头为Authorization: Bearer key。源码特意注释说明不用?key或 Cookie 方式传 Key是为了避免 Key 出现在日志中。端点总览README 中的端点表格与本仓库 packages/veriphone/endpoints 目录下的四个实现一一对应操作Operation ID风险级别底层端点描述coverageveriphone.api.coveragereadGET /v3/coverage/current列出支持 Currentmodecurrent查询的国家creditsveriphone.api.creditsreadGET /v3/credits获取账户余额与按查询模式拆分的用量getExamplePhoneNumberveriphone.api.getExamplePhoneNumberreadGET /v2/example获取指定国家与线路类型的示例号码verifyPhoneNumberveriphone.api.verifyPhoneNumberwriteGET /v3/verify校验号码有效性返回格式、区域与运营商信息端点元数据风险级别与描述定义在 packages/veriphone/index.ts#L117-L141 的veriphoneEndpointMeta中。风险分级决定了权限默认值三个只读端点默认open而verifyPhoneNumber默认allow——因为其record: true会在服务端侧写入校验历史属于写操作见 packages/veriphone/index.ts#L48-L52 注释。1. verifyPhoneNumber号码校验write对应实现见 packages/veriphone/endpoints/verify-phone-number.ts。该端点封装了GET /v3/verify输入参数由 packages/veriphone/endpoints/types.ts#L40-L69 的VerifyPhoneNumberInputSchema定义参数类型默认值说明phonestring必填待校验号码建议使用 E.164 国际格式长度 4–25 字符且含 4–20 位数字default_countrystring可选ISO 3166-1 alpha-2 国家码如US当号码无国际前缀时使用modestatic \| currentstaticstatic消耗 1 积分current为实时注册库查询消耗 10 积分recordboolean可选为true时把结果保存到账户校验历史校验响应结构非常丰富VerifyPhoneNumberResponseSchematypes.ts#L75-L113核心字段是statussuccess/error/syntax-error与phone_valid失败时reason会给出too_short、too_long、invalid_length、invalid_country_code、unrecognized_range、not_a_number等具体原因。成功时则返回phone_type共 10 种mobile、fixed_line、fixed_line_or_mobile、toll_free、premium_rate、shared_cost、voip、short_code、emergency、unknown、carrier、country、country_code、country_prefix、international_number、local_number、e164、timezone等字段在modecurrent下还包含original_carrier、current_carrier、ported是否携号转网、current_lookup、carrier_data_source等实时比对信息。实现上有一个值得借鉴的点verify-phone-number.ts#L35-L37请求发出前先用 Zod Schema 校验输入因为一次校验会消耗积分格式错误的号码绝不应打到上游 API。调用成功后还会通过logEventFromContext记录veriphone.verifyPhoneNumber事件便于审计与追踪。2. getExamplePhoneNumber获取示例号码read对应 packages/veriphone/endpoints/get-example-phone-number.ts封装GET /v2/example。输入只有两个字段参数类型说明country_codestringISO 3166-1 alpha-2 国家码如US调用前务必先确认国家码typestring线路类型可选mobile、fixed_line、toll_free、premium_rate、shared_cost、voip缺省为mobile响应包含phone_type、country_code、country_prefix、international_number、local_number、e164等字段。源码注释types.ts#L151-L166记录了真实的兼容性处理/v2/example实测返回大写的线路类型如MOBILE因此响应 Schema 先toLowerCase()再校验部分镜像会把e164键写成大写E164Schema 对两种键都做了兼容。这是给 Agent 使用时的实用提示该端点在官方 v2/v3 参考文档中并未收录仅见于第三方镜像文档使用时需以实际响应为准。3. credits余额与用量查询read对应 packages/veriphone/endpoints/credits.ts封装GET /v3/credits无输入参数。响应CreditsResponseSchematypes.ts#L183-L200包含email账户邮箱counter当前已用积分计数数值active账户是否激活payg按量付费额度limit积分上限plan套餐名renew续费周期last_reset上次重置时间v3 中为{ seconds, nanos }对象v2 中为字符串Schema 做了联合兼容usage按static/current两种模式拆分的{ count, credits }用量4. coverage覆盖国家列表read对应 packages/veriphone/endpoints/coverage.ts封装GET /v3/coverage/current无输入参数。响应types.ts#L214-L226为{ countries: [{ iso, covered }], updatedAt }——iso是国家码covered表示该国家是否支持 Current 模式实时查询。错误处理与重试策略插件的错误处理逻辑集中在 packages/veriphone/error-handlers.ts与 Veriphone v3 文档的错误码表一一对应错误码含义处理器行为429限流RATE_LIMIT_ERROR最多重试5 次并遵循Retry-After头headersRetryAfterMs等待后重试401API Key 缺失或无效AUTH_ERROR打印告警日志maxRetries: 0不重试402积分不足PAYMENT_REQUIRED_ERROR打印告警并提示充值或降低查询量不重试404资源不存在NOT_FOUND_ERROR不重试5xx服务端错误SERVER_ERROR不重试其他兜底DEFAULT打印错误信息不重试限流处理有一个精妙的细节error-handlers.ts#L39-L47注释指出maxRetries必须大于 0headersRetryAfterMs才会生效——因为绑定器只在真正发生重试时才会等待该时间。每个匹配器都优先取错误对象上的结构化status字段同时用消息文本匹配做兜底。底层错误对象是 packages/veriphone/client.ts#L12-L42 定义的VeriphoneAPIError它从corsair/http的ApiError中透传status、statusText、body、retryAfter以及rateLimitLimit/rateLimitRemaining/rateLimitReset三个限流头字段供上述处理器直接检查无需重新发请求。测试与验证仓库提供了两层测试packages/veriphone/api.test.ts、packages/veriphone/endpoints.test.ts 等Schema 与端点单元测试验证 Zod Schema 的输入输出解析、错误处理器匹配逻辑真实 API 冒烟测试api.test.ts中标注了VERIPHONE_API_KEY环境变量未设置时自动跳过describe.skip设置后会真实调用 Veriphone API 并断言响应形状。例如测试用14169670000校验断言status success、phone_valid true、country_code CA用country_code: US, type: mobile获取示例号码等。这意味着如果你要自测可以这样运行VERIPHONE_API_KEY你的密钥 pnpm test小结corsair-dev/veriphone是一个小而精的拉取式集成插件四个端点完整覆盖了号码校验、示例号码、余额查询与覆盖查询四类场景API Key 认证支持配置项直传与租户级密钥管理两种方式内置的按错误码分类的重试策略与VeriphoneAPIError结构化错误让 Agent 能够优雅处理限流、积分不足等业务异常而无 Webhook、无本地持久化的极简设计使其非常适合作为对话式 AI 中按需触发的号码工具。若需在应用层补充权限控制可直接利用其permissions选项——只读端点默认开放verifyPhoneNumber作为写操作默认受控开箱即用的分级策略为生产环境的多租户接入提供了安全保障。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
