企业官网建设流程全解析

Corsair You.com 插件解析：把 LLM 就绪的网页搜索接入你的 AI 应用

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

Corsair 是一个帮助用户接入其第三方应用的 TypeScript 授权/插件框架，@corsair-dev/youcom是官方插件之一：它把 You.com 的 Web Search API 封装成单一的yousearch.youSearch操作，让 AI Agent 可以以 API Key 鉴权方式执行搜索，并拿到结构化、LLM 就绪的网页结果与新闻文章。读完本篇，你将掌握该插件的安装方式、完整搜索参数（freshness、livecrawl、include_domains等）的取值与默认值、GET/POST 请求路由策略、API Key 解析链路、搜索结果落库行为以及内置的限流/鉴权错误重试策略。

安装与包结构

安装命令：

pnpm add @corsair-dev/youcom

该插件位于 packages/youcom，当前版本为0.1.1（见 package.json），以 Apache-2.0 协议发布。它的运行时 peer 依赖是corsair >= 0.1.0与zod ^4.1.13，说明插件的输入/输出类型校验完全建立在你项目中的 Zod 之上。

插件入口是 index.ts，它导出了youcom()工厂函数以及YouSearchRequest、YouSearchResponse、YoucomWebResult、YoucomNewsResult、YoucomSearchMetadata等类型，供宿主项目做类型推断。插件元数据在 plugin-docs.yaml 中声明为 “AI search engine API for web answers, citations, and research-oriented query results”，即定位是面向回答、引用和研究型查询的搜索后端。

插件注册选项

youcom()接受如下选项（见 index.ts）：

唯一操作：yousearch.youSearch

README 与插件元数据一致地声明，插件只有一个操作：

风险等级read在 index.ts 的youcomEndpointMeta中硬编码。调用方式：

await corsair.youcom.api.yousearch.youSearch({ query: 'latest AI research developments' });

请求参数全表

请求体由 endpoints/types.ts 中的YouSearchRequestSchema定义，官方 API 参考文档 docs/plugins/youcom/api.mdx 给出了完整参数表。结合源码中的校验规则，各参数的取值范围与默认值如下：

所有字段都经过 Zod 校验，非法枚举值（如country: 'XX'）会在到达上游 API 之前就被拒绝。

请求实现：GET/POST 自动路由与限流策略

真正发请求的逻辑在 client.ts。几个值得注意的实现细节：

1. GET 与 POST 的选择是自动的。makeYoucomSearchRequest先调用shouldUsePost（client.ts#L43-L49）：只要include_domains、exclude_domains、boost_domains三者中任意一个非空，就改用POST /v1/search并带 JSON body；否则走GET /v1/search，把参数拼进 query string（buildGetQuery不携带域名类参数）。上游 API 基地址为https://ydc-index.io，鉴权头为X-API-Key（client.ts#L28）。

2. 传输层不重试。插件配置了YOUCOM_NO_TRANSPORT_RETRIES速率限制策略（maxRetries: 0），并通过retry-after、x-ratelimit-reset、x-ratelimit-remaining、x-ratelimit-limit头解析上游限流状态。也就是说：429 的重试完全交给 Corsair 的应用层错误处理器（下一节），而不是 HTTP 客户端层盲目重发，避免在上游限流期间加剧压力。

3. 错误统一包装。底层ApiError会被包装为YoucomAPIError，携带status、retryAfter、code字段，供错误处理器匹配（见 client.ts#L9-L26）。

错误与重试策略

error-handlers.ts 定义了四类处理器：

这种“限流可重试、鉴权/权限错误快速失败”的策略是搜索类插件的合理默认：限流是暂时性故障，而 401/403 重试没有意义。宿主也可以在youcom({ errorHandlers })中覆盖这些行为。

认证：API Key 解析链路

README 声明：Auth 方式为 API key，Corsair 会在首次使用时向租户（tenant）提示提供凭证。插件没有 Webhook（webhooks: {}，且pluginWebhookMatcher恒返回false，见 index.ts#L114-L118）。

密钥解析逻辑在keyBuilder（index.ts#L124-L135）中，endpoint 调用时的优先级是：

1. 若显式配置了key选项，直接返回它；
2. 否则走api_key认证类型，从租户存储的凭证中读取（ctx.keys.get_api_key()）；
3. 两者都没有则抛出AuthMissingError('youcom', 'api_key')。

youcomAuthConfig声明 API key 以tenant_external_id为粒度存储（index.ts#L80-L84），即同一租户下多用户共享一个 You.com 密钥。

返回结构与搜索结果落库

响应由YouSearchResponseSchema校验（endpoints/types.ts#L187-L192），结构为{ results, metadata }：

{ web?: { url: string, title: string, description?: string, snippets?: string[], thumbnail_url?: string, page_age?: string, contents?: { html?: string, markdown?: string }, // livecrawl 时返回正文 favicon_url?: string }[], news?: { title: string, description?: string, page_age?: string, thumbnail_url?: string, url: string, contents?: { html?: string, markdown?: string } }[] } // metadata { search_uuid: string, query: string, latency: number }

yousearch.youSearch端点（endpoints/yousearch.ts）在返回结果前还做两件事：

1. 结果落库：逐条把web和news结果 upsert 到插件 schema 的searchResults实体中，entity ID 由query:resultType:url拼接（searchResultEntityId），并附加resultType、query、searchedAt字段。落库 schema 定义在 schema/database.ts，注册于 schema/index.ts（version: '1.0.0'）。每条落库失败仅console.warn，不会中断搜索调用——存储是尽力而为的旁路行为。这意味着你可以通过 Corsair 的数据库访问能力查询“某租户搜索过哪些结果”，用于审计或缓存。
2. 事件打点：调用logEventFromContext记录youcom.yousearch.youSearch事件，payload 含query、webResultCount、newsResultCount，状态completed。

测试用例中的典型用法

api.test.ts 提供了可直接参照的调用示例（需要环境变量YOUCOM_API_KEY或YDC_API_KEY，否则整组跳过）：

// 基础搜索 await makeYoucomSearchRequest<YouSearchResponse>(KEY, { query: 'latest AI research developments', count: 5, }); // 新鲜度过滤 await makeYoucomSearchRequest<YouSearchResponse>(KEY, { query: 'technology news', count: 3, freshness: 'week', }); // 国家 + 语言 await makeYoucomSearchRequest<YouSearchResponse>(KEY, { query: 'local news headlines', count: 3, country: 'US', language: 'EN', }); // 安全搜索 + 分页 await makeYoucomSearchRequest<YouSearchResponse>(KEY, { query: 'open source software releases', count: 2, offset: 0, safesearch: 'moderate', });

测试还验证了exclude_domains触发 POST 路径、以及每次响应都能通过YoucomEndpointOutputSchemas.youSearch.parse的类型校验——即插件保证“进与出”都经过 Zod，宿主代码拿到的永远是类型安全的数据。

小结与适用边界

• @corsair-dev/youcom是一个单操作（yousearch.youSearch，read风险）插件，专为给 AI Agent 提供搜索工具而建；无 Webhook、无 OAuth，只支持 API Key。
• 所有参数在 endpoints/types.ts 有严格 Zod 约束（count上限 100、offset上限 9、域名数组上限 500、crawl_timeout上限 60 秒等），使用时以当前仓库版本（0.1.1）的实际 schema 为准。
• 完整 API 参考、类型与示例可参考仓库内 docs/plugins/youcom/overview.mdx、docs/plugins/youcom/api.mdx 与 docs/plugins/youcom/database.mdx，以及插件自身文档 packages/youcom/README.md。

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