尧图网页设计 
Corsair You.com 插件解析把 LLM 就绪的网页搜索接入你的 AI 应用【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairCorsair 是一个帮助用户接入其第三方应用的 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选项类型说明authTypePickAuthapi_key可选缺省为api_keykeystring静态 API Key作为 endpoint 调用时的兜底hooks插件 hooks生命周期钩子errorHandlersCorsairErrorHandler覆盖默认错误处理器permissionsPluginPermissionsConfig按 endpoint 配置租户权限唯一操作yousearch.youSearchREADME 与插件元数据一致地声明插件只有一个操作OperationOperation IDRiskDescriptionyousearch.youSearchyoucom.api.yousearch.youSearchread使用 You.com 搜索 API 搜索网页返回 LLM 就绪的网页结果与新闻文章风险等级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 给出了完整参数表。结合源码中的校验规则各参数的取值范围与默认值如下NameType必填取值范围 / 默认值说明querystring是至少 1 个字符搜索关键词countnumber否整数1–100默认10返回结果数量freshnessday \| week \| month \| year \| string否枚举值或YYYY-MM-DDtoYYYY-MM-DD格式日期区间正则/^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/结果新鲜度过滤offsetnumber否整数0–9默认0分页偏移country枚举否AR AU AT BE BR CA CL DK FI FR DE HK IN ID IT JP KR MY MX NL NZ NO CN PL PT PH RU SA ZA ES SE CH TW TR GB US按国家/地区限定结果language枚举否AR EU BN BG CA ZH-HANS ZH-HANT HR CS DA NL EN EN-GB ET FI FR GL DE EL GU HE HI HU IS IT JA KN KO LV LT MS ML MR NB PL PT-BR PT-PT PA RO RU SR SK SL ES SV TA TE TH TR UK VI默认EN结果语言safesearchoff \| moderate \| strict否默认moderate安全搜索等级livecrawlweb \| news \| all否—开启实时爬取网页/新闻正文livecrawl_formatshtml \| markdown数组否默认[html]正文内容格式include_domainsstring[]否最多 500 个域名仅搜索指定域名exclude_domainsstring[]否最多 500 个域名排除指定域名boost_domainsstring[]否最多 500 个域名提升指定域名权重crawl_timeoutnumber否整数1–60默认10秒实时爬取超时所有字段都经过 Zod 校验非法枚举值如country: XX会在到达上游 API 之前就被拒绝。请求实现GET/POST 自动路由与限流策略真正发请求的逻辑在 client.ts。几个值得注意的实现细节1. GET 与 POST 的选择是自动的。makeYoucomSearchRequest先调用shouldUsePostclient.ts#L43-L49只要include_domains、exclude_domains、boost_domains三者中任意一个非空就改用POST /v1/search并带 JSON body否则走GET /v1/search把参数拼进 query stringbuildGetQuery不携带域名类参数。上游 API 基地址为https://ydc-index.io鉴权头为X-API-Keyclient.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 定义了四类处理器处理器匹配条件行为RATE_LIMIT_ERRORHTTP 429或错误信息含rate_limited/429最多重试 5 次并遵循retryAfterMs头AUTH_ERRORHTTP 401或含unauthorized/invalid_auth不重试maxRetries: 0PERMISSION_ERRORHTTP 403或含forbidden/access_denied不重试DEFAULT其他一切不重试这种“限流可重试、鉴权/权限错误快速失败”的策略是搜索类插件的合理默认限流是暂时性故障而 401/403 重试没有意义。宿主也可以在youcom({ errorHandlers })中覆盖这些行为。认证API Key 解析链路README 声明Auth 方式为 API keyCorsair 会在首次使用时向租户tenant提示提供凭证。插件没有 Webhookwebhooks: {}且pluginWebhookMatcher恒返回false见 index.ts#L114-L118。密钥解析逻辑在keyBuilderindex.ts#L124-L135中endpoint 调用时的优先级是若显式配置了key选项直接返回它否则走api_key认证类型从租户存储的凭证中读取ctx.keys.get_api_key()两者都没有则抛出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在返回结果前还做两件事结果落库逐条把web和news结果 upsert 到插件 schema 的searchResults实体中entity ID 由query:resultType:url拼接searchResultEntityId并附加resultType、query、searchedAt字段。落库 schema 定义在 schema/database.ts注册于 schema/index.tsversion: 1.0.0。每条落库失败仅console.warn不会中断搜索调用——存储是尽力而为的旁路行为。这意味着你可以通过 Corsair 的数据库访问能力查询“某租户搜索过哪些结果”用于审计或缓存。事件打点调用logEventFromContext记录youcom.yousearch.youSearch事件payload 含query、webResultCount、newsResultCount状态completed。测试用例中的典型用法api.test.ts 提供了可直接参照的调用示例需要环境变量YOUCOM_API_KEY或YDC_API_KEY否则整组跳过// 基础搜索 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: latest AI research developments, count: 5, }); // 新鲜度过滤 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: technology news, count: 3, freshness: week, }); // 国家 语言 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: local news headlines, count: 3, country: US, language: EN, }); // 安全搜索 分页 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: open source software releases, count: 2, offset: 0, safesearch: moderate, });测试还验证了exclude_domains触发 POST 路径、以及每次响应都能通过YoucomEndpointOutputSchemas.youSearch.parse的类型校验——即插件保证“进与出”都经过 Zod宿主代码拿到的永远是类型安全的数据。小结与适用边界corsair-dev/youcom是一个单操作yousearch.youSearchread风险插件专为给 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Corsair You.com 插件解析：把 LLM 就绪的网页搜索接入你的 AI 应用
Corsair You.com 插件解析把 LLM 就绪的网页搜索接入你的 AI 应用【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsairCorsair 是一个帮助用户接入其第三方应用的 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选项类型说明authTypePickAuthapi_key可选缺省为api_keykeystring静态 API Key作为 endpoint 调用时的兜底hooks插件 hooks生命周期钩子errorHandlersCorsairErrorHandler覆盖默认错误处理器permissionsPluginPermissionsConfig按 endpoint 配置租户权限唯一操作yousearch.youSearchREADME 与插件元数据一致地声明插件只有一个操作OperationOperation IDRiskDescriptionyousearch.youSearchyoucom.api.yousearch.youSearchread使用 You.com 搜索 API 搜索网页返回 LLM 就绪的网页结果与新闻文章风险等级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 给出了完整参数表。结合源码中的校验规则各参数的取值范围与默认值如下NameType必填取值范围 / 默认值说明querystring是至少 1 个字符搜索关键词countnumber否整数1–100默认10返回结果数量freshnessday \| week \| month \| year \| string否枚举值或YYYY-MM-DDtoYYYY-MM-DD格式日期区间正则/^\d{4}-\d{2}-\d{2}to\d{4}-\d{2}-\d{2}$/结果新鲜度过滤offsetnumber否整数0–9默认0分页偏移country枚举否AR AU AT BE BR CA CL DK FI FR DE HK IN ID IT JP KR MY MX NL NZ NO CN PL PT PH RU SA ZA ES SE CH TW TR GB US按国家/地区限定结果language枚举否AR EU BN BG CA ZH-HANS ZH-HANT HR CS DA NL EN EN-GB ET FI FR GL DE EL GU HE HI HU IS IT JA KN KO LV LT MS ML MR NB PL PT-BR PT-PT PA RO RU SR SK SL ES SV TA TE TH TR UK VI默认EN结果语言safesearchoff \| moderate \| strict否默认moderate安全搜索等级livecrawlweb \| news \| all否—开启实时爬取网页/新闻正文livecrawl_formatshtml \| markdown数组否默认[html]正文内容格式include_domainsstring[]否最多 500 个域名仅搜索指定域名exclude_domainsstring[]否最多 500 个域名排除指定域名boost_domainsstring[]否最多 500 个域名提升指定域名权重crawl_timeoutnumber否整数1–60默认10秒实时爬取超时所有字段都经过 Zod 校验非法枚举值如country: XX会在到达上游 API 之前就被拒绝。请求实现GET/POST 自动路由与限流策略真正发请求的逻辑在 client.ts。几个值得注意的实现细节1. GET 与 POST 的选择是自动的。makeYoucomSearchRequest先调用shouldUsePostclient.ts#L43-L49只要include_domains、exclude_domains、boost_domains三者中任意一个非空就改用POST /v1/search并带 JSON body否则走GET /v1/search把参数拼进 query stringbuildGetQuery不携带域名类参数。上游 API 基地址为https://ydc-index.io鉴权头为X-API-Keyclient.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 定义了四类处理器处理器匹配条件行为RATE_LIMIT_ERRORHTTP 429或错误信息含rate_limited/429最多重试 5 次并遵循retryAfterMs头AUTH_ERRORHTTP 401或含unauthorized/invalid_auth不重试maxRetries: 0PERMISSION_ERRORHTTP 403或含forbidden/access_denied不重试DEFAULT其他一切不重试这种“限流可重试、鉴权/权限错误快速失败”的策略是搜索类插件的合理默认限流是暂时性故障而 401/403 重试没有意义。宿主也可以在youcom({ errorHandlers })中覆盖这些行为。认证API Key 解析链路README 声明Auth 方式为 API keyCorsair 会在首次使用时向租户tenant提示提供凭证。插件没有 Webhookwebhooks: {}且pluginWebhookMatcher恒返回false见 index.ts#L114-L118。密钥解析逻辑在keyBuilderindex.ts#L124-L135中endpoint 调用时的优先级是若显式配置了key选项直接返回它否则走api_key认证类型从租户存储的凭证中读取ctx.keys.get_api_key()两者都没有则抛出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在返回结果前还做两件事结果落库逐条把web和news结果 upsert 到插件 schema 的searchResults实体中entity ID 由query:resultType:url拼接searchResultEntityId并附加resultType、query、searchedAt字段。落库 schema 定义在 schema/database.ts注册于 schema/index.tsversion: 1.0.0。每条落库失败仅console.warn不会中断搜索调用——存储是尽力而为的旁路行为。这意味着你可以通过 Corsair 的数据库访问能力查询“某租户搜索过哪些结果”用于审计或缓存。事件打点调用logEventFromContext记录youcom.yousearch.youSearch事件payload 含query、webResultCount、newsResultCount状态completed。测试用例中的典型用法api.test.ts 提供了可直接参照的调用示例需要环境变量YOUCOM_API_KEY或YDC_API_KEY否则整组跳过// 基础搜索 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: latest AI research developments, count: 5, }); // 新鲜度过滤 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: technology news, count: 3, freshness: week, }); // 国家 语言 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: local news headlines, count: 3, country: US, language: EN, }); // 安全搜索 分页 await makeYoucomSearchRequestYouSearchResponse(KEY, { query: open source software releases, count: 2, offset: 0, safesearch: moderate, });测试还验证了exclude_domains触发 POST 路径、以及每次响应都能通过YoucomEndpointOutputSchemas.youSearch.parse的类型校验——即插件保证“进与出”都经过 Zod宿主代码拿到的永远是类型安全的数据。小结与适用边界corsair-dev/youcom是一个单操作yousearch.youSearchread风险插件专为给 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考