Corsair Xquik 插件corsair-dev/xquik搜索推文、执行 X 操作与 Webhook 监控的完整接入指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本篇指南基于 Xquik 插件文档 与其源码实现系统讲解如何在 Corsair 中接入corsair-dev/xquik插件覆盖安装方式、全部 25 个端点的操作清单与风险分级、API Key 认证与凭据存储、关键输入参数的取值约束、写操作的两阶段确认机制、Webhook 事件签名校验原理以及内置的错误重试策略。读完后可直接在自己的 Agent 应用中让用户的 AI 助手搜索推文、发推、点赞、关注用户并接收实时事件通知。一、插件定位与安装Xquik 插件面向 X原 Twitter场景官方描述为“Search tweets, inspect users, manage Xquik webhooks, upload media, and run X actions from Corsair”——即从 Corsair 中搜索推文、查看用户、管理 Webhook、上传媒体并执行 X 写操作。安装命令来自插件 README 与 package.jsonpnpm add corsair-dev/xquik该包当前版本为0.1.2peerDependencies要求corsair 0.1.0与zod ^4.1.13说明插件的输入/输出校验完全构建在 Zod 之上可直接与 TypeScript 类型系统联动。在代码中通过工厂函数xquik()创建插件实例其配置项定义见 XquikPluginOptions选项类型作用authTypePickAuthapi_key认证方式默认api_keybaseUrlstring覆盖默认 API 基址不传则走内置默认值keystring直接内联提供 Xquik API KeywebhookSecretstring直接内联提供 Webhook HMAC 签名密钥errorHandlersCorsairErrorHandler覆盖/补充内置错误处理与重试策略permissionsPluginPermissionsConfig按端点声明式限制可用的操作面hooks/webhookHooks-注入自定义生命周期钩子二、完整端点清单与风险分级插件 README 的 Endpoints 表格完整列出了 25 个操作。该清单与源码中 xquikEndpointsNested 的注册结构一一对应tweets.delete映射到实现函数Tweets.deleteTweet且每个操作的description与riskLevel均在 xquikEndpointMeta 中声明供 Corsair 的权限系统与审计系统消费。操作Operation ID风险级别说明media.downloadxquik.api.media.downloadread从一条或多条推文下载图片与视频media.uploadFromUrlxquik.api.media.uploadFromUrlwrite上传公开媒体 URL供创建推文时使用trends.getxquik.api.trends.getread按 WOEID 区域获取 X 热门话题tweets.batchxquik.api.tweets.batchread按 ID 批量获取最多 100 条推文tweets.createxquik.api.tweets.createwrite用已连接 X 账号发推或回复tweets.deletexquik.api.tweets.deletedestructive删除已连接 X 账号的推文tweets.getxquik.api.tweets.getread获取推文全文、作者、指标与媒体tweets.likexquik.api.tweets.likewrite用已连接账号点赞推文tweets.retweetxquik.api.tweets.retweetwrite用已连接账号转推tweets.searchxquik.api.tweets.searchread使用 X 查询运算符与分页搜索推文tweets.unlikexquik.api.tweets.unlikewrite用已连接账号取消点赞users.batchxquik.api.users.batchread按 ID 查找最多 100 个 X 用户users.followxquik.api.users.followwrite用已连接账号关注用户users.followersxquik.api.users.followersread列出某用户的粉丝users.followingxquik.api.users.followingread列出某用户关注的账号users.getxquik.api.users.getread按用户名或用户 ID 获取资料users.searchxquik.api.users.searchread按姓名或用户名搜索用户users.tweetsxquik.api.users.tweetsread列出某用户最近发布的推文users.unfollowxquik.api.users.unfollowwrite用已连接账号取关webhooks.createxquik.api.webhooks.createwrite创建 Xquik Webhook 端点订阅webhooks.deactivatexquik.api.webhooks.deactivatewrite停用 Webhook 端点webhooks.deliveriesxquik.api.webhooks.deliveriesread列出某 Webhook 端点的投递记录webhooks.listxquik.api.webhooks.listread列出已配置的 Webhook 端点webhooks.testxquik.api.webhooks.testwrite向 Webhook 端点发送测试投递webhooks.updatexquik.api.webhooks.updatewrite更新 Webhook 的 URL、事件类型或激活状态writeActions.getxquik.api.writeActions.getread查询挂起的 Xquik 写操作状态其中tweets.delete是唯一标注destructive且irreversible: true的操作见 endpoint meta 中 tweets.delete 声明在 Agent 自动化场景下应特别注意权限管控。从各端点实现看HTTP 路径映射关系为以 tweets.ts、media.ts、webhooks.ts 为准搜索GET /x/tweets/search筛选条件、cursor、limit、q、queryType、sinceTime、untilTime全部走 query 参数批量GET /x/tweets?ids...多个 ID 以逗号拼接idsQuery发推POST /x/tweets点赞/取消点赞POST/DELETE /x/tweets/{id}/like转推POST /x/tweets/{id}/retweet媒体上传POST /x/media下载POST /x/media/downloadWebhook 管理GET/POST /webhooks更新PATCH /webhooks/{id}停用DELETE /webhooks/{id}投递记录GET /webhooks/{id}/deliveries测试POST /webhooks/{id}/test三、认证API Key 与凭据解析README 声明认证方式为 “Auth: API key. Corsair prompts your tenant for credentials on first use.”。从源码看凭据解析逻辑集中在 keyBuilder按调用来源分四条路径Webhook 来源 提供了webhookSecret直接使用options.webhookSecret用于 HMAC 验签而非 API 调用Webhook 来源 未提供webhookSecret回退到数据库读取ctx.keys.get_webhook_signature()端点调用 提供了key直接使用内联 key端点调用 authType api_key从数据库读取ctx.keys.get_api_key()以上都不满足则抛出AuthMissingError(xquik, api_key)。凭据有两种注入方式。方式一使用 Corsair CLI 将凭据写入多租户模式下由 Corsair 在首次使用时向租户提示pnpm corsair setup --pluginxquik api_keyyour-xquik-api-key方式二在代码中直接内联xquik({ key: process.env.XQUIK_API_KEY, })API Key 最终通过x-api-key请求头随每个请求发送这一点在 client.ts 中可以看到客户端还固定附带xquik-api-contract契约版本头当前为2026-04-29与Content-Type: application/json默认基址为https://xquik.com/api/v1并显式声明CREDENTIALS: omit不携带浏览器 Cookie。所有 API 调用统一经由 makeXquikRequest 发出任何底层ApiError都会被包装为携带status、body、retryAfter与速率限制信息的XquikAPIError。四、关键输入参数详解Zod 校验层插件的全部输入约束以 Zod Schema 形式定义在 endpoints/types.ts这部分信息 README 未展开但对实际调用非常关键。4.1 推文搜索tweets.searchTweetSearchInputSchema由TweetFilterSchema合并分页字段扩展而来定义见 types.ts必填项为qX 查询语句其余为可选参数约束说明q非空字符串X 查询运算符表达式如from:xquikcom since:2026-01-01limit整数1–200每页条数cursor字符串分页游标queryTypeLatest|Top排序类型sinceTime/untilTimeISO 时间字符串时间窗过滤mediaTypegifs/images/links/media/none/videos媒体类型过滤minFaves/minQuotes/minReplies/minRetweets非负整数指标下限quotes/replies/retweetsexclude/include/only引用/回复/转推的纳入模式sinceDate/untilDateYYYY-MM-DD正则日期过滤其他anyWords、exactPhrase、excludeWords、fromUser、toUser、hashtags、cashtags、conversationId、inReplyToTweetId、quotesOfTweetId、retweetsOfTweetId、language、mentioning、url、verifiedOnly细粒度筛选这些筛选项在运行时被 tweetFilterQuery 逐字段映射为 Xquik 的 query 参数。搜索结果为PaginatedTweets{ has_next_page, next_cursor, tweets[] }每条SearchTweet含id、text、作者信息、likeCount/retweetCount/viewCount等指标与媒体数组。4.2 发推tweets.createTweetCreateInputSchema定义见 types.ts必填account已连接的 X 账号标识text与media最多 4 个 URL二者至少提供一个Schema 中有显式refine校验错误信息为 Provide text, media, or both.可选reply_to_tweet_id回复、attachment_url、community_id、is_note_tweet。响应是联合类型CreateTweetResponse要么{ success: true, tweetId }立即成功要么进入挂起确认状态见下节。4.3 其他端点约束速览批量操作tweets.batch与users.batch的ids均为 1–100 个元素用户时间线users.tweets在id之上可加pageSize20–200、includeReplies、includeParentTweet及完整TweetFilter热门话题trends.getwoeid区域编号与count1–50均可选媒体下载media.downloadtweetInput/tweetId/tweetUrl/tweetIds最多 50 个至少提供一个同样有refine强制Webhook 创建webhooks.createurl必须为合法 URLeventTypes为至少 1 个事件类型的数组Webhook 更新webhooks.updateeventTypes/isActive/url至少更新一个字段。五、写操作的两阶段确认机制Xquik 的部分写操作可能不立即生效而是返回“待确认”状态。输出类型中定义了PendingWriteResponsetypes.ts{ charged: boolean; // 是否已计费 error: x_write_unconfirmed; // 固定错误码 retryable: false; status: pending_confirmation; writeActionId: string; // 用于后续轮询的写操作 ID message?: string; }tweets.create的实现会检测response.status pending_confirmation并写入审计日志tweets.ts create。拿到writeActionId后可调用writeActions.get轮询其状态WriteActionStatus包含status: failed | pending_confirmation | success、charged、confirmationAttempts、confirmedAt、tweetId等字段定义见 types.ts。从这套类型结构看插件为 Agent 侧设计了“发推 → 拿到 writeActionId → 轮询确认”的完整闭环避免在计费/确认前就误判操作成败。六、Webhooks两类投递事件与 HMAC 签名校验README 的 Webhooks 一节指出插件“处理 2 类 webhook 事件”。从 index.ts 看这两个事件是events.monitormonitorEvent匹配除webhook.test外的所有已签名监控事件投递对应 4 种监控事件类型tweet.new、tweet.quote、tweet.reply、tweet.retweetEventTypeSchemaevents.testtest匹配eventType webhook.test的测试投递。两者的 handler 见 webhooks/events.ts逻辑完全一致先验签失败返回 401 与具体错误信息验签通过后打审计日志返回{ data: event, success: true }。6.1 事件载荷结构EventPayloadSchematypes.tseventType4 种 tweet 事件之一或webhook.testdata事件类型特定的开放对象provider-defined透传元数据deliveryId、streamEventId、occurredAt、query、schemaVersion、timestamp、username。6.2 签名算法与新鲜度窗口验签实现位于 verifyXquikWebhookSignature步骤为校验三个请求头x-xquik-signature、x-xquik-timestamp、x-xquik-nonce任一缺失即拒绝新鲜度检查timestamp与当前时间差超过5 分钟DEFAULT_MAX_AGE_MS 5 * 60 * 1000判定为过期Stale Xquik webhook timestamp防止重放攻击用HMAC-SHA256(secret, {timestamp}.{nonce}.{rawBody})计算期望签名格式为sha256前缀加十六进制摘要长度预检后用crypto.timingSafeEqual做时序安全比较防止时序侧信道攻击。插件通过 hasXquikSignature检测签名头存在性作为路由匹配器把带签名的请求识别为 Xquik Webhook多租户场景下另有matchXquikTenantWebhook做租户匹配。6.3 Webhook Secret 的配置创建 Xquik Webhook 端点时webhooks.create响应会一次性返回 HMAC 签名密钥——输出类型为Webhook { secret: string }types.ts。需要把它存入 Corsair否则无法验证后续投递。两种方式pnpm corsair setup --pluginxquik webhook_signatureyour-xquik-webhook-secretxquik({ webhookSecret: process.env.XQUIK_WEBHOOK_SECRET, })凭据汇总如下凭据用途获取位置API Key全部 API 调用Xquik 控制台的 API keys 区域Webhook Secret入站 Webhook 验签创建 Xquik Webhook 端点时的响应仅一次6.4 用webhooks.test验证链路配好后无需等真实事件调用webhooks.testPOST /webhooks/{id}/test触发一次测试投递响应为TestWebhookResponse{ success, statusCode, error? }便于快速确认“签名密钥一致、路由可达”。七、错误处理与重试策略插件内置一套 errorHandlers按 HTTP 状态码与错误消息模式分类返回给 Corsair 核心的重试策略分类匹配条件重试策略AUTH_ERROR401 / 消息含unauthorized、invalid api key0 次PAYMENT_REQUIRED402 / 消息含insufficient_credits0 次PERMISSION_ERROR403 / 消息含account_needs_reauth、account_restricted0 次RATE_LIMIT_ERROR429 / 消息含rate_limited、too many requests5 次优先采用响应头的 retry-afterSERVER_ERROR424 / 502 / 5033 次同样优先响应头 retry-afterVALIDATION_ERROR400 / 4220 次DEFAULT兜底0 次XquikAPIError会透传rateLimitLimit、rateLimitRemaining、rateLimitReset、retryAfterclient.ts因此限流重试能拿到精确的退避时长。业务侧也可通过xquik({ errorHandlers: {...} })覆盖或补充这些策略。八、源码结构与测试佐证插件目录结构相对仓库根目录packages/xquik/index.ts插件工厂xquik()、端点/Webhook 注册表、Schema 与元数据聚合、keyBuilder凭据解析packages/xquik/client.tsHTTP 客户端封装、请求头与契约版本、XquikAPIErrorpackages/xquik/endpoints/tweets、users、webhooks、media、trends、write-actions六个端点模块 types.ts 全量 Zod 校验层packages/xquik/webhooks/事件匹配器、HMAC 验签、租户匹配器packages/xquik/schema/database.ts插件在 Corsair 数据库中的表结构存储 API Key 等凭据。测试 api.test.ts 覆盖了三个核心面可作接入前的行为基准搜索输入校验q: from:xquikcom since:2026-01-01、limit: 50、mediaType: images的请求可被 Schema 接受分页输出容错末页响应允许next_cursor: null或字段缺省签名校验闭环用HMAC-SHA256按timestamp.nonce.rawBody构造签名可验签通过密钥为空时返回{ error: Missing Xquik webhook secret, valid: false }。九、快速上手清单pnpm add corsair-dev/xquik安装插件在 Xquik 控制台创建 API Key通过pnpm corsair setup --pluginxquik api_key...或xquik({ key })存入在 Agent 工具集中暴露需要的端点如tweets.search、tweets.create、users.get必要时用permissions收窄权限面若需实时感知新推文/引用/回复/转推调用webhooks.create订阅tweet.*事件将响应中的secret存入webhook_signature再用webhooks.test打通链路对可能进入pending_confirmation的写操作记录writeActionId并用writeActions.get轮询最终状态。完整文档、类型与更多示例可参考插件文档目录 docs/plugins/xquik含凭据获取、Webhook、API 参考等页面。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考