# @framers/agentos-ext-web-search 中文文档

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

版本：1\.4\.0
npm 元数据更新时间：2026-11-11T09:17:37.623Z
中文译文更新时间：2026-11-15T12:08:06.567Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-web-search
原文对照：https://npmcn.com/package/%40framers/agentos-ext-web-search/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/research/web-search#readme
源码仓库：https://github.com/framerslab/agentos-extensions

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

- 包体积（解压后）：176 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- peer 依赖：@framers/agentos \>=0\.10\.40
- 首次发布：2026-02-06T12:51:22.908Z
- 最新版本发布：2026-11-11T09:17:37.202Z
- 近 30 天下载量：20861（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

AgentOS的网络搜索、研究汇总和事实检查工具

## 安装

```sh
npm install @framers/agentos-ext-web-search
```

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

## README

# AgentOS 网络搜索扩展

专业的网络搜索,研究汇总,以及AgentOS代理的实况调查.

支持Serper.dev,Tavily,Brave,SerpAPI,Firecrawl和SearXNG等. 搜索按此顺序询问被配置的提供者,并用第一个没有出错返回的提供者来回答,即使它没有返回任何结果(Tavily或Firecrawl要求出局时不返回结果). 它只有在一个投出出出错或超过其速率限制时才会移动到下一个提供商,而返回到DuckDuckGo,它不需要API密钥,而每个配置的提供商都这样做了. 英文维基百科不需要密钥,它回答一个搜索 锁定它和 `multiSearch` 一旦一个主机允许它(见 [选项](https://npmcn.com/package/%40framers/agentos-ext-web-search/#readme-options)) (中文(简体) ).

## 安装

```bash
npm install @framers/agentos-ext-web-search
```

## 快速启动

```ts
import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-web-search',
        options: {
          // Any one of these is enough; configured providers are tried in the order above.
          serperApiKey: process.env.SERPER_API_KEY,
          tavilyApiKey: process.env.TAVILY_API_KEY,
          braveApiKey: process.env.BRAVE_API_KEY,
          serpApiKey: process.env.SERPAPI_API_KEY,
          firecrawlApiKey: process.env.FIRECRAWL_API_KEY,
          searxngUrl: process.env.SEARXNG_URL,
        },
      },
    ],
  },
});
```

## 环境变量

-   `SERPER_API_KEY` (可选)
-   `SERPAPI_API_KEY` (可选)
-   `BRAVE_API_KEY` (可选)
-   `TAVILY_API_KEY` (可选)
-   `FIRECRAWL_API_KEY` (可选)
-   `SEARXNG_URL` (可选, 一个 SearXNG 实例 URL)

如果没有设置,扩展将返回 DuckDuckGo 。 维基百科不需要键和变量: `wikipedia` 选项允许它.

## 选项

除了上面的键,包选项和 `SearchProviderService`配置 :

| 选项 | 它会做什么 | 当被忽略时 |
| --- | --- | --- |
| `wikipedia` | `{ enabled, client, limiter?, origin?, timeoutMs? }`:英语维基百科的REST搜索通过 [`@framers/agentos-ext-public-sources`](https://www.npmjs.com/package/@framers/agentos-ext-public-sources)' `WikipediaSourceProvider`不需要钥匙. `client` (单位:千美元)`{ name, version, contact }`)作为Wikimedia用户代理的政策要求发送. `limiter` 是一个过程 `SourceLimiter` 维基百科中的相关条目: 向每个服务单位和每个调用它的读者传递相同的一个,因为维基媒体计算每个客户端的极限. `origin` 将提供者指向另一个维基或站点; `timeoutMs` 是每个请求的最后期限. | 关. 一旦启用:一个新的 `SourceLimiter`, (中文(简体) ), `https://en.wikipedia.org`3000ms (英语). |
| `serperUrl` | 塞尔珀的搜索端点,例如主机测试中的站站. | `https://google.serper.dev/search` |
| `tavilyUrl` | 塔维利的搜索终点. | `https://api.tavily.com/search` |
| `firecrawlUrl` | Firecrawl的搜索终点. | `https://api.firecrawl.dev/v1/search` |
| `tavily` | `{ searchDepth: 'basic' | 'advanced' }`,则 `search_depth` 塔维利被派来. `include_answer` 财务报告和审定财务报表 `include_raw_content` 任何深度都是虚假的. | `advanced` |

这个 `wikipedia` 提供者在所有其他配置提供者之后列出。 A 类 `search` 没有 `provider` 从不问:它只回答文章标题,所以一般查询会到按键提供者,然后到 DuckDuckGo. 把它绑起来 `provider: 'wikipedia'`,或使用 `multiSearch`,它问它与其他人。 每个被击中的答案是 `{ title, url, snippet: '', position }`,则 `url` 由公共来源建造 `articleUrl`这样 `decodeURIComponent` 路径 `/wiki/` 将文章的密钥送回读取 `WikipediaSourceProvider.read`。 。 。 .

## 从代码搜索

```ts
import { SourceLimiter } from '@framers/agentos-ext-public-sources';
import { LimiterRefused, SearchFailed, SearchProviderService } from '@framers/agentos-ext-web-search';

// One limiter for the wiki in the process, shared with every other caller of it.
const wikiLimiter = new SourceLimiter();

const search = new SearchProviderService({
  tavilyApiKey: process.env.TAVILY_API_KEY,
  tavily: { searchDepth: 'basic' },
  wikipedia: {
    enabled: true,
    client: { name: 'MyApp', version: '1.2.0', contact: 'https://example.org/contact' },
    limiter: wikiLimiter,
  },
});

let sent = 0;
const controller = new AbortController();
try {
  const response = await search.search('Treaty of Versailles', {
    provider: 'wikipedia',
    maxResults: 2,
    signal: controller.signal,
    onSend: () => {
      sent += 1;
    },
  });
  // response.results[0]: { title: 'Treaty of Versailles', url: 'https://en.wikipedia.org/wiki/Treaty_of_Versailles', snippet: '', position: 1 }
} catch (error) {
  if (error instanceof LimiterRefused) {
    // Nothing was sent: error.reason is 'blocked', 'minute', 'wait' or 'caller'.
  } else if (error instanceof SearchFailed) {
    // error.provider is 'wikipedia'; error.status is the HTTP status, or null when none came.
  }
}
```

`search(query, { maxResults, provider, category, signal, onSend })`数字 :

-   `provider` 针入一个提供者:没有其他提供者被尝试过,没有任何东西回到DuckDuckGo. 解答错误状态的被绑定的密钥提供者抛出自己的 `Error`被钉住 `wikipedia` 搜索限制器拒绝丢出公共来源 `LimiterRefused`,这个包的再出口, 一个失败扔 `SearchFailed`。拒绝是宿主的限制器投掷的,理由和所有,甚至来自另一份公共来源的限制器。 一个搜索锁定在 `wikipedia` 在一个服务 它不能扔和发送什么.
-   `signal` 结束搜索的每一个提供者请求,搜索则以信号的理由拒绝. Tavily和Firecrawl自己的15秒计时器在旁边跑,他们自己的计时器没有结果. 无 `provider`中,中止结束搜索:没有询问下一个提供者, DuckDuckGo 则不是.
-   `onSend` 在每个提供者被问到之前,等待其请求。 投出后,一无所寄;再无所求;而取出所投之物而拒之. 对于 `wikipedia` 一旦限制器批准请求,它就会运行,所以限制器拒绝运行。 搜索会被拒绝 `onSend` 当一个429或一个503 屏蔽了限制器时, 或间距会经过限制器时 `waitMs`。 。 。 .

一个没有的搜索 `signal` 也没有 `onSend` 在这些选项存在前发送请求 .

## 工具

### `web_search`

腾讯网. `provider` 针头之一 `serper`, (中文(简体) ), `serpapi`, (中文(简体) ), `brave`, (中文(简体) ), `tavily`, (中文(简体) ), `firecrawl`, (中文(简体) ), `searxng` 或者说 `duckduckgo`,以及 `wikipedia` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}我为它提供了服务 该工具在构建时读取服务供应商: 在没有服务的情况下 `wikipedia`它的图谋 `provider` enum及其描述将维基百科排除在外 `validateArgs` 拒绝 `provider: 'wikipedia'` 作为无效的提供者.

### `research_aggregate`

运行多个搜索和汇总结果 .

### `fact_check`

交叉核对各种来源的索赔.

## 排名

与 `multiSearch: true` (工具输入或包选项) `defaultMultiSearch: true` ),每个已配置的提供者都会有一个查询 `wikipedia` 当它被启用时,在其中提供)和 DuckDuckGo 并行进行。 结果通过规范化的URL合并,并根据从有多少供应商返回URL以及每个供应商将其放在哪里而建立的信任分数来命令. 包头运行没有再排队模式,并将结果发送到没有再排队服役.

### 与代理服务器重排

AgentOS 重排一个 `RerankerService` (单位:千美元)`@framers/agentos/cognition/rag/reranking`) (中文(简体) ). 重新排序是提供者不可知的:您要注册提供者,以及 `rerankChain(query, chunks, chain)` 按顺序运行链的相位,每个相位指定一个提供者 id, a `topK` 也可以选个模特儿 提供商未注册或无法提供的舞台被跳过,而扔出之前的顺序的舞台被丢出.

网络搜索有两种使用方式:

-   **这包的结果.** 包的工具不叫重排机。 重新排序什么 `web_search` 返回,将结果传递给 `rerankChain` 自己,每个块与一个 `id`,一个 `originalDocumentId` (例如URL)及其片段为 `content`。 。 。 .
-   **AgentOS自己的搜索.** `WebSearchService` (单位:千美元)`@framers/agentos/cognition/web-search`)是与其自己的提供商进行单独搜索(`FirecrawlProvider`, (中文(简体) ), `TavilyProvider`, (中文(简体) ), `SerperProvider` 财务报告和审定财务报表 `BraveProvider`,随 `registerProvider`不是这个包 鉴于a `reranker` 联合国 `RerankerService`)和a 数据 `rerankChain`,它会重新排序其被熔化的结果,发送每个结果的页面内容,或者当它没有时它的片段. 如果重排失败, 它会返回未重排的导出结果 .

AgentOS 飞船 3个重排供应商,全部从 `@framers/agentos/cognition/rag/reranking`。该表描述了执行中的代理操作系统 [`c46ff75`](https://github.com/framerslab/agentos/tree/c46ff754e8df1ccb54f31aa24fc8fd8df5952776);其他版本可能有所不同(在v0.10.40,这个包申报的最古老的AgentOS, `LlmJudgeReranker` 接受一个 `timeoutMs` (但不适用).

| 编号 | 类 | 如何得分 | 剩下的过程 | 默认 | 失败时 |
| --- | --- | --- | --- | --- | --- |
| `local` | [`LocalCrossEncoderReranker`](https://github.com/framerslab/agentos/blob/c46ff754e8df1ccb54f31aa24fc8fd8df5952776/src/cognition/rag/reranking/providers/LocalCrossEncoderReranker.ts) | 交叉编码器通过 Transformers.js 给每个查询和文档配对进行中评分(`@huggingface/transformers`,则 `@xenova/transformers`,由主机安装). | 没有查询或文档。 该模型被下载在先使用后被缓存. | 型号 `cross-encoder/ms-marco-MiniLM-L-6-v2`,设备 `cpu`, (中文(简体) ), `maxSequenceLength` 512号, `batchSize` 32. 国家. | 当两个变形器.js软件包都没有安装时不可用 。 无法装入抛出物的模型 。 一份得分为0的文档. |
| `cohere` | [`CohereReranker`](https://github.com/framerslab/agentos/blob/c46ff754e8df1ccb54f31aa24fc8fd8df5952776/src/cognition/rag/reranking/providers/CohereReranker.ts) | Cohere是Rerank API对文件的评分. | 查询和每个文件的全部内容,发送到 `<baseUrl>/v1/rerank` 与 `apiKey`。 。 。 . | 型号 `rerank-v3.5`, (中文(简体) ), `baseUrl` `https://api.cohere.ai`超时3000毫秒. | 未提供 `apiKey`. 非-2xx 答案或超时抛出. |
| `llm-judge` | [`LlmJudgeReranker`](https://github.com/framerslab/agentos/blob/c46ff754e8df1ccb54f31aa24fc8fd8df5952776/src/cognition/rag/reranking/providers/LlmJudgeReranker.ts) | 一个语言模型,通过主机调用 `llmCallFn(system, user, model?)`评分 `maxPointwiseDocuments` 文档分为批次为0至10个,然后在一次呼叫中将得分最高者排在首位。 过去的文件 `maxPointwiseDocuments` 没有答案. | 查询和每个文档的前200个字符, 发送到主机所在的地方 `llmCallFn` 派他们来. | 没有自己的模式 : `scoringModel` 财务报告和审定财务报表 `rankingModel` 转至 `llmCallFn` 现予印发. `maxPointwiseDocuments` 一百块, `batchSize` 10号, `pointwiseTopK` 20,超时3000分的电话. | 拨打失败,出局或不分析得分的批次 排名失败的调用将顺序留给分数. |

见特工OS [重新排队](https://github.com/framerslab/agentos/blob/c46ff754e8df1ccb54f31aa24fc8fd8df5952776/docs/text/RERANKING.md) 页 次 [`WebSearchService.ts`](https://github.com/framerslab/agentos/blob/c46ff754e8df1ccb54f31aa24fc8fd8df5952776/src/cognition/web-search/WebSearchService.ts)。 。 。 .

## 页:1

-   工具只读(无副作用).
-   提供者选择是自动的,基于哪个密钥配置以及是否 `wikipedia` 已启用.

## 许可证

Apache-2.0 框架.dev

## 常见问题

### @framers/agentos-ext-web-search 是什么？

AgentOS的网络搜索、研究汇总和事实检查工具

### 如何安装 @framers/agentos-ext-web-search？

在项目目录运行 npm install @framers/agentos-ext-web-search，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.10\.40）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-web-search 支持 TypeScript 吗？

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

### @framers/agentos-ext-web-search 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @framers/agentos-ext-web-search 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @framers/agentos-ext-web-search 可以商用吗？

@framers/agentos-ext-web-search 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @framers/agentos-ext-web-search 的下载量有多少？

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

### @framers/agentos-ext-web-search 还在维护吗？

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