# chatluna-plugin-omsearch 中文文档

规范地址：https://npmcn.com/package/chatluna-plugin-omsearch/

版本：0\.1\.0
npm 元数据更新时间：2026-11-03T05:13:36.119Z
中文译文更新时间：2026-11-03T07:42:28.689Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/chatluna-plugin-omsearch
原文对照：https://npmcn.com/package/chatluna-plugin-omsearch/?lang=original

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

- 包体积（解压后）：95.2 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：cordis ^4\.0\.0-rc\.12，@chatluna/tool ^2\.0\.0-alpha\.0，@chatluna/schema ^2\.0\.0-alpha\.0，@cordisjs/plugin-http ^1\.5\.0
- 首次发布：2026-11-03T05:12:19.905Z
- 最新版本发布：2026-11-03T05:13:35.986Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

chatluna的搜索插件集成，支持大部分主流搜索服务。

## 安装

```sh
npm install chatluna-plugin-omsearch
```

也可以使用：`pnpm add chatluna-plugin-omsearch`、`yarn add chatluna-plugin-omsearch`、`bun add chatluna-plugin-omsearch`

## README

# chatluna-plugin-omsearch

chatluna的搜索插件集成，支持大部分主流搜索服务。

给模型提供一个统一的 `web_search` 工具。你在配置里按顺序添加搜索服务，搜索时依次尝试：前一个出错、超时或没有结果，就自动换下一个。

## 支持的搜索服务

| 类型 | 服务 | 需要 |
| --- | --- | --- |
| 国际 | Tavily、Brave Search、Exa、Jina Search、Firecrawl、Kagi、Serper（Google）、Perplexity Search | API Key（Firecrawl 自建实例可不填） |
| 国内 | 博查 Bocha、智谱 Web Search、秘塔 Metaso、百度千帆 AI 搜索 | API Key |
| 自托管 / 免 Key | SearXNG、DuckDuckGo | SearXNG 实例地址；DuckDuckGo 无需配置 |

## 配置

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `providers` | `[]` | 回退链。只有添加并启用的服务才会被使用，列表顺序就是尝试顺序。同一种服务可以添加多次（例如多个 API Key）。 |
| `providers[].type` | — | 搜索服务类型，决定下面出现哪些字段。 |
| `providers[].enabled` | `true` | 关闭后保留配置，但不参与搜索。 |
| `limit` | `8` | 模型没有指定数量时返回的条数（1–20）。 |
| `timeout` | `20000` | 单个服务的超时（毫秒），超时后转到下一个服务。 |

没有启用任何服务时，`web_search` 会返回明确的错误，提示去配置。

```yaml
- id: omsearch
  name: chatluna-plugin-omsearch
  config:
    providers:
      - type: bocha
        apiKey: sk-...
      - type: tavily
        apiKey: tvly-...
      - type: searxng
        endpoint: http://127.0.0.1:8080
```

## 工具

`web_search({ query, recency?, limit? })`

-   `query`：搜索词，大多数引擎支持引号短语和 `site:`。
-   `recency`：`day` / `week` / `month` / `year`。没有对应时间窗的服务会放宽到最接近的一档（SearXNG 的 week → month，百度的 day → week）；秘塔、Jina 不支持时间过滤。
-   `limit`：1–20，超出单个服务上限时按该服务上限截断。

返回编号结果（标题、链接、摘要、日期），部分服务（Tavily、Kagi、Serper、SearXNG）会附带一段简短回答，末尾注明实际返回结果的服务。

## 注意

-   智谱搜索的查询不能超过 70 个字符，超出时直接跳到下一个服务。
-   DuckDuckGo 通过抓取 HTML 页面实现，数据中心或共享出口 IP 容易被它的人机验证拦截，建议放在回退链末尾。
-   依赖宿主的 `tools`（`@chatluna/tool`）和 `http`（`@cordisjs/plugin-http`）服务。

## 许可

MIT

## 常见问题

### chatluna-plugin-omsearch 是什么？

chatluna的搜索插件集成，支持大部分主流搜索服务。

### 如何安装 chatluna-plugin-omsearch？

在项目目录运行 npm install chatluna-plugin-omsearch，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cordis（^4\.0\.0-rc\.12）、@chatluna/tool（^2\.0\.0-alpha\.0）、@chatluna/schema（^2\.0\.0-alpha\.0）、@cordisjs/plugin-http（^1\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### chatluna-plugin-omsearch 支持 TypeScript 吗？

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

### chatluna-plugin-omsearch 支持 ESM 还是 CommonJS？

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

### chatluna-plugin-omsearch 需要什么版本的 Node\.js？

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

### chatluna-plugin-omsearch 可以商用吗？

chatluna-plugin-omsearch 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### chatluna-plugin-omsearch 还在维护吗？

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