# @cherrystudio/web-search 中文文档

规范地址：https://npmcn.com/package/%40cherrystudio/web-search/

版本：0\.5\.0
npm 元数据更新时间：2026-10-29T08:18:27.022Z
中文译文更新时间：2026-11-09T22:24:17.661Z
软件包许可：AGPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cherrystudio/web-search
原文对照：https://npmcn.com/package/%40cherrystudio/web-search/?lang=original
源码仓库：https://github.com/CherryHQ/cherry-studio

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：190 kB，95 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-17T08:35:00.273Z
- 最新版本发布：2026-10-29T08:18:26.784Z
- 近 30 天下载量：1706（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

具有主机拥有的运输和政策的便携式网络搜索提供者协议

## 安装

```sh
npm install @cherrystudio/web-search
```

也可以使用：`pnpm add @cherrystudio/web-search`、`yarn add @cherrystudio/web-search`、`bun add @cherrystudio/web-search`

## README

# @cherrystudio/网络搜索

现有樱桃工作室网络搜索提供者的可移植协议. 注入应用程序 联网和明确选择提供者能力;它们保持设置、证书存储、, 密钥旋转、区域检测、再试、回落、本地页面提取和生命周期所有权.

```ts
import { createWebSearchClient } from '@cherrystudio/web-search'
import { tavily } from '@cherrystudio/web-search/providers/tavily'

const client = createWebSearchClient({
  transport: hostTransport,
  providers: [{ provider: tavily, capabilities: ['searchKeywords'] }]
})

const response = await client.execute({
  providerId: 'tavily',
  capability: 'searchKeywords',
  input: 'Cherry Studio',
  config: { maxResults: 5 },
  credentials: { apiKey: selectedApiKey },
  signal,
  timeoutMs: 30_000
})
```

`hostTransport`, (中文(简体) ), `selectedApiKey`,以及 `signal` 属于应用程序。 每个调用执行一个 输入对一个提供者,不隐含重复。 结果包含 `providerId`, (中文(简体) ), `capability`, (中文(简体) ), `input`,以及 `results` 与 `title`, (中文(简体) ), `url`, (中文(简体) ), `content`, (中文(简体) ), `sourceInput`选择 `truncated`。 。 。 .

## 条目

| 条目 | 目录 |
| --- | --- |
| 根号 | 客户端、验证、错误、提供者词汇和公共类型 |
| `/catalog` | 无法移动的远程提供者元数据和人均能力公共终点 |
| `/providers/<id>` | 一个协议模块: zhipu, tavily, searxng, exa, exa-mcp, bocha, querit, jina, firecrawl, craw4ai, 平行, serply, 人民币, deepseek, searchapi, desearch |
| `/tools/config` | 纯端点覆盖合并; 明确的空覆盖保留为空 |
| `/tools/url-filter` | 可选的带诊断器的 URL 规则过滤返回呼叫者 |
| `/tools/content` | 可选符号/特征切分;应用程序分配总预算 |

提供商的入境出口使用其身份证作为指定出口,但 `exa-mcp`,用于出口 `exaMcp`。 。 。 . 额外出口 `discoverSearxngEngines`; Jina 输出 `getJinaHostCandidates` 财务报告和审定财务报表 `JINA_MIRROR_HOSTS`。导入根不会导入所有协议模块或内容切换.

SearXNG的发现是明确的,并使用了与下列内容相同的错误、取消和超时合同: 搜索。 搜索。 它的错误使用 `searxng/searchKeywords` 上下文。 搜索返回片段, 永远不要 自动下载结果页面。 Jina 候选人的选择是纯的; 软件包没有 检测区域或重试另一个终点.

`apiHost: undefined` 使用公共默认值, Crawl4AI 是 Cloud 主机 `https://api.crawl4ai.com`。明确的空地址失败验证。 SearXNG没有默认部署. 当地 `fetch` 桌面DuckDuckGo仍然为主机所有.

Querit 接受 API 主机是否使用 `/v1` 和数字字符串响应代码。 Crawl4AI 应用 云层 `/scrape` 协议 `crawl4ai.com` 及其子域,需要 API 密钥。 其它 主机保留自动托管 `/md` 带有可选符号的协议.

元宝弹 `maxResults` 到下一个被支持 `Cnt` 值(10-50),然后适用 请求的本地限制. `excludeDomains` 通过 `Site`; 无效域项被省略. 主机保留完整的 URL 规则过滤 。 只有元宝 `useDefaultResultCount: true` 省略 `Cnt` 升级兼容性,但不能损坏 `Site` 或本地限制。 协议本身从不重复.

## 运输和错误

执行 `WebSearchTransport.request` 与主机网络堆栈。 请求载有完整的 URL,信头,一个已经序列化的可选体, `signal`选择 `timeoutMs`全部返回 HTTP 状态、 小写响应头和 `bodyText`; 不要剖析 JSON 或者编码身体 再来一次 保持 URL 路径和查询编码完整 .

运输公司拥有从发送到消耗身体的超时执行权,向前 根据实际请求取消,并释放计时器/听众。 选择 `timeoutMs` 保留 主机默认值 。 掷出 `WebSearchTransportError` 报告网络、超时、取消、读取, 或未分类的失败。 没有中止的呼叫器信号的中止不是全局取消.

`execute` 掷出 `WebSearchError`。 。 `kind` 区分配置、网络、超时、, 取消, HTTP, 提供者失败, 响应无效, 未知失败 . `code`, (中文(简体) ), `status`, (中文(简体) ), `providerCode`, (中文(简体) ), `retryAfter`,以及 `requestId` 支持应用政策. `toJSON()` 忽略原因, 原始答复、信头和证书。 取消保留 `AbortError` 名称; 超时 保留 `TimeoutError`应用程序信息发布和重试决定仍为主机所有.

MCP模块支持有限的JSON/SSE响应和现有的Exa搜索文本/要点 页面文本格式。 成功 `result.content: []` 或上游消息 `No search results found. Please try a different query.` 意味着零搜索点击. 空白或未确认的答复是错误, 而空页内容总是错误。 它不管理 MCP 连接、会话或 流传订阅.

## 分销与发展

所有公共条目船舶无害环境管理/CJS和匹配申报,包括a `react-native` 导出 条件。 源有Node,Electron,React Introduct,Expo,或应用程序导入. 导入 分辨率检查不能取代消费应用平台的接受。 产出目标ES2020和 使用标准 `URL`编号 :`URLSearchParams` 和主机取消信号; 网络继续注入.

桌面消耗 `workspace:*` 作为发展依赖,通过源别名,所以便携式 执行与应用程序捆绑在一起。 它明确的能力配置过滤共享元数据. Mobile必须安装准确的已发布版本并输入其锁文件. 初始工作空间版本 `0.0.0` 是占位符; 未成年人 更改集准备 `0.1.0`。在 0.x 期间,打破 API 更改需要小放出;相容 修正使用补丁释放。 主机许可列表可以防止新能力被隐含地启用.

发布工作流程明确构建并检查了这个软件包. `test:package` 检查已建 工作空间外的柏油球、模块格式、声明和便携式导入分辨率.

```sh
pnpm --filter @cherrystudio/web-search test -- src/__tests__/protocols.test.ts
pnpm --filter @cherrystudio/web-search test:package
```

这些是选入开发命令. `test:package` 包括汇编和网络支持 安装。 在运行任一命令之前遵循当前任务的授权规则 .

许可证:AGPL-3.0-只,保留源寄存许可证. 确认许可和维护者 在首次公开发布前.

## 常见问题

### @cherrystudio/web-search 是什么？

具有主机拥有的运输和政策的便携式网络搜索提供者协议

### 如何安装 @cherrystudio/web-search？

在项目目录运行 npm install @cherrystudio/web-search，或使用 pnpm add / yarn add / bun add。

### @cherrystudio/web-search 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cherrystudio/web-search 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cherrystudio/web-search 可以商用吗？

@cherrystudio/web-search 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @cherrystudio/web-search 的下载量有多少？

根据 npm 官方下载统计，@cherrystudio/web-search 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,706 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cherrystudio/web-search 还在维护吗？

最新版本 0\.5\.0 发布于 2026/10/29（11 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/10/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。