# @dbx-tools/appkit-web-search 中文文档

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

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:20:03.824Z
中文译文更新时间：2026-11-11T17:40:35.557Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/appkit-web-search
原文对照：https://npmcn.com/package/%40dbx-tools/appkit-web-search/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

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

- 包体积（解压后）：504 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：13 个
- 首次发布：2026-07-26T10:51:06.129Z
- 最新版本发布：2026-11-10T19:20:03.443Z
- 近 30 天下载量：8743（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：318（近 12 个月 318 个）

## 中文简介

服务器端网络搜索运行时间、 Mastra 工具和 AppKit 插件

## 安装

```sh
npm install @dbx-tools/appkit-web-search
```

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

## README

# @dbx-tools/appkit-web-搜索

添加 `web_search` 财务报告和审定财务报表 `web_fetch` 到 AppKit 或 Mastra 后端. `web_search` 运行在 [Databricks 模型服务本地网络搜索工具](https://docs.databricks.com/aws/en/machine-learning/model-serving/web-search)数字 : 模式搜索网络服务器侧并返回一个合成的答案加 它使用的源没有第三方搜索 API 密钥. `web_fetch` 读取单页 结束 [被冲动](https://www.npmjs.com/package/got-scraping)。 。 。 .

## 快开始

注册插件并将其工具交给代理 :

```ts
import { createApp, server } from "@databricks/appkit";
import { webSearch } from "@dbx-tools/appkit-web-search";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const researcher = agents.createAgent({
  instructions: "Search the web, then read the most relevant sources.",
  async tools(plugins) {
    return { ...(await plugins["web-search"].toolkit()) };
  },
});

await createApp({
  plugins: [server(), webSearch(), mastra({ agents: { researcher } })],
});
```

登记规定:

-   AppKit 插件注册可以解析并登录启动时的有效策略 .
-   两个马斯特拉工具: `web_search` (回答+引用)和 `web_fetch` (页) 作为可读文本或原始 HTML 的内容,加上与 AppKit 代理设备相同的一对 通过插件的工具 `ToolProvider`。 。 。 .
-   `web_search` 解决一个专用的网络搜索能力模型(默认情况下的Gemini, 然后GPT)独立于呼叫代理聊天模式(可能不会) 支持网页搜索)。 闲置名称( O)`"gemini"`, (中文(简体) ), `"gpt"`绒毛相接现场 通过目录 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model)。 。 。 .
-   内置提供者 - > 请求分解地图( OpenAI Response API) `{"tools":[{"type":"web_search"}]}`双子聊天完成 `{"google_search":{}}`, (中文(简体) ), 每一供应商均享有 `WEB_SEARCH_TOOLS` 设置.
-   命名的 URL 策略 (S)`allowlist` 或者说 `unrestricted`) 在一个普通的许可列表之上 发展于 [@dbx-tools/路径](https://npmcn.com/package/%40dbx-tools/path)是因为 `match` 匹配者 : `web_search` 安静 过滤器不允许引用, `web_fetch` 拒绝不允许的 URL,并且 模式在启动时记录.
-   每个工具的审批标志:每一次呼叫的门,或(用于) `web_fetch`只有电话 其 URL 匹配图案, 映射到 Mastra 的 `requireApproval`。 。 。 .
-   每一次外出通话都通过AppKit `execute()` 链(用户缓存, 以颤抖的后退、超时和遥测方式重试) `AbortSignal`。每个插件实例都将其政策和执行器分开,所以 在一个过程中的多个应用仍然被隔离.
-   页面和倒置结果 HTML 使用解析器支持的文本转换和选择器, 包括完整的 HTML 实体解码和错误的标记恢复.

## 选择网络提供者

AppKit没有第一党的网页搜索或页面图面. 当 代理商需要在打开的网页上查找一些东西,或者读取用户粘贴的URL, 政策层( 允许列表 + 可选批准 ) , 围绕它进行部署 控制哪些站点可以到达 哪些站点需要暂停 这个 网络搜索工具解决自己的网络搜索能力模型,所以是一个代理 运行在任何聊天模式上(包括一个没有网络搜索)仍然可以搜索. 这个 提供 Mastra 工具和 AppKit 插件, 如 [@dbx-tools/电子邮件](https://npmcn.com/package/%40dbx-tools/email)。 。 。 .

当支持的 GPT 或双子座端点是时, 使用本地 Databricks 网络搜索 已部署。 使用 DuckDuckGo 刮后退 只有当没有能达到的终点时 可获取和未合成的搜索结果是可以接受的。 使用 `web_fetch` (单位:千美元) 特定的公用HTTPS页面. 对于索引化的应用程序数据,使用 [@ dbx 工具/ 搜索](https://npmcn.com/package/%40dbx-tools/search) 换句话说.

## 配置 AppKit 插件

```ts
import { createApp, lakebase, server } from "@databricks/appkit";
import { webSearch } from "@dbx-tools/appkit-web-search";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const researcher = agents.createAgent({
  instructions: "Research questions using web_search, then read sources with web_fetch.",
  async tools(plugins) {
    return { ...(await plugins["web-search"].toolkit()) };
  },
});

await createApp({
  plugins: [
    server(),
    lakebase(),
    webSearch({
      model: "gemini", // defaults to Gemini, then GPT, when omitted
      allowedUrls: ["*.databricks.com", "docs.example.com"],
    }),
    mastra({ agents: researcher, storage: true }),
  ],
});
```

`plugin.webSearch()` 解析配置( 覆盖) , 编译 URL 策略,以及 提供其工具所使用的执行器。 App-Integrated Mastra 代理可以消费 上面显示的本地插件工具包,它保留了该插件的政策, OBO范围,和AppKit执行链. 启用后批准需要 Mastra 存储,所以注册 `lakebase()` 或配置 Mastra 插件中的存储.

该插件也是 AppKit `ToolProvider`,所以本地代码代理可以 没有马斯特拉 就拿两个一样的工具 把定义放在 `server/agents/researcher/agent.ts` 所以AppKit发现了它:

```ts
import { createAgent } from "@databricks/appkit/beta";

export default createAgent({
  name: "Researcher",
  default: true,
  model: "databricks-gpt-6-1-sol",
  instructions: "Research questions with web_search, then read sources with web_fetch.",
  tools: (plugins) => ({ ...plugins["web-search"].toolkit() }),
  skills: ["research-policy"],
});
```

将技能放在 `server/agents/skills/research-policy/SKILL.md`,注册本地 `agents()` 与 没有被贬值的代理映射,并构建一个编译的本地代理服务器:

```ts
import { appkitServerConfig } from "@databricks/appkit/tsdown";

export default appkitServerConfig();
```

两个工具都有说明 `effect: "read"` ,并且需要用户上下文,而不需要 是自动不可继承的:一个代理人必须要求它们,因为 `web_fetch` 达到 不管模型产生什么URL.

土著体积技能作为服务校长运作。 0.81号 `skillCredentialMode: "obo"` 选项没有带线。 保持请求范围可写 技术,远程来源,同步的Graphiti发现, Sandbox/Monty, 马斯特拉记忆 和持久的批准 `@dbx-tools/appkit-mastra`。 。 。 .

## 选择网络搜索模式

本地的网络搜索工具只运行在某些模型上,它是提供者- 具体。 此套件解决了部署的终点 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model) 并应用此命令:

1.  排名最高的网络搜索能力 **双子座**。 。 。 .
2.  没有双子座,有能力 **常规** 匹配呼叫/请求的模型.
3.  排名最高的能力 **常规**。 。 。 .
4.  任何额外的 `modelFallbacks` 搜索顺序.

当Databricks报告双子座网络搜索无法进行时,因为 跨区域处理已禁用, 插件压制双子座24小时 在此运行时间中, 透明地重试同一工具调用下一个 GPT 候选人.

`DATABRICKS_SERVING_ENDPOINT_NAME` 是 AppKit 模型的标准名称 服务装订,插件显示的就是字段,所以 `app.yaml` / 捆绑接线以其他方式到达此插件 . 请求是 `model`, 插件 `model`,并使用环境模型值 匹配双子座可用性检查后的调用. 当工具通过时 `@dbx-tools/appkit-mastra`时,主机注入 解决聊天模式, 压倒生成的任何不同模式参数 根据LLM.

模型解析度与现场工作空间目录相悖 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model),所以它只选一个终点 实际部署。 所配置的不存在的代号从不叫.

### 倒计时

首选的是本地工具 。 当工作空间没有部署时 GPT/ Gemini 端点( 所以本地网络搜索完全无法运行), 工具掉入 回到鸭子去刮去 `got-scraping` 因此它仍然返回结果 而不是错误。 设定倒计时结果 `model` 改为 `"scrape:duckduckgo"` 财务报告和审定财务报表 将物质装入 `citations` (没有模型合成一个答案, 这样 `answer` 是一个领先的结果。 默认启用 。 设定 `scrapeFallback: false` (或 `WEB_SEARCH_SCRAPE_FALLBACK=0`要求当地人 没有部署模型和出错.

插件从解析模型中选择提供者请求片段 : OpenAI GPT 使用响应 API `{"tools":[{"type":"web_search"}]}`双子座 使用顶级聊天补全字段 `{"google_search":{}}`。覆盖或扩展每个提供者的地图 页:1 `webSearchTools` 设置( env) `WEB_SEARCH_TOOLS`作为平台 进化 :

```ts
plugin.webSearch({
  model: "databricks-gemini-3-pro",
  webSearchTools: { gemini: { request: { google_search: {} } } },
});
```

## 没有代理搜索和获取

```ts
import { search, fetch, runtime, tool } from "@dbx-tools/appkit-web-search";
import { getExecutionContext } from "@databricks/appkit";

const webRuntime = runtime.createWebSearchRuntime({
  model: "gemini",
  allowedUrls: ["*.databricks.com"],
});

// web_search needs the OBO client + host from the active execution context:
const ctx = getExecutionContext();
const host = (await ctx.client.config.getHost()).toString();

const result = await search.runWebSearch(
  { query: "unity catalog lineage best practices" },
  webRuntime,
  { client: ctx.client, host },
);
// result.answer, result.citations, result.model

const page = await fetch.runWebFetch({ url: result.citations[0]!.url, format: "text" }, webRuntime);
```

使用直接的调用, 用于运行中的外观、 测试或管理流 不参与。 独立的Mastra工具厂也接受 `runtime` 或者说 `config`。它们从未发现或附加到进程-全局插件上 :

```ts
const webRuntime = runtime.createWebSearchRuntime({
  allowedUrls: ["*.databricks.com"],
});

const tools = {
  web_search: tool.webSearchTool({ runtime: webRuntime }),
  web_fetch: tool.webFetchTool({ runtime: webRuntime }),
};
```

明确传递运行时间或提供执行器给 `createWebSearchRuntime`。 。 。 .

## 限制可达到的 URL

```ts
import { allowlist } from "@dbx-tools/appkit-web-search";

const list = allowlist.toUrlAllowList(
  allowlist.parseAllowedUrls(["*.databricks.com", "docs.example.com/api/**"]),
);

list.allows("https://docs.databricks.com/aws/en/index.html"); // true
list.allows("https://evil.example.com/"); // false
```

每个条目都是由 [@dbx-tools/路径](https://npmcn.com/package/%40dbx-tools/path)是因为 `match` 选手. 主机条目( 无路径, 例如 ) `databricks.com` 或者说 `*.databricks.com`匹配 URL的主机名,而赤色主机也与其子域相匹配. 路径条目 (单位:千美元)`docs.example.com/api/**`)匹配主机+路径名. 执法不对称 设计 : `web_search` 引用被悄悄地过滤到允许的集合(即: 模型从不显示它无法取取的来源,而显式 `web_fetch` 以出错(一个可见的、可更正的错误)拒绝不允许使用的 URL . `web_fetch` 仅接受HTTPS中决心公开地址的目标 在每个重定向请求前重新应用两个检查 .

两种模式中哪一种是有效的,由 `urlPolicy`,并有效 模式在启动日志中 :

| `urlPolicy` | 效果 |
| --- | --- |
| `"allowlist"` | 仅 `allowedUrls` 可到达条目 |
| `"unrestricted"` | 任何公共 HTTPS URL 都可以达到 |

离开 `urlPolicy` 未设并随行 `allowedUrls`数字 : `"allowlist"` 当那里 是条目, `"unrestricted"` 当没有。 设定它来说明你是谁 意为. 两个矛盾在启动时失败 而不是悄悄地挑一个 边 : `"allowlist"` 没有条目,以及 `"unrestricted"` 包含条目.

```ts
// An open deployment, said out loud:
plugin.webSearch({ urlPolicy: "unrestricted" });

// A closed one:
plugin.webSearch({ urlPolicy: "allowlist", allowedUrls: ["*.databricks.com"] });
```

## 门呼叫请求批准

两个工具都默认运行,未经批准. 过 `approval` 到工具(或设置) 需要批准. `true` 每一个呼叫都关上门 一个 URL 模式(或 列表)只调用其 URL 匹配的门。 A 类 `web_fetch` 准确评价 相对于目标 URL,而 `web_search` (结果 URL 未知) 在呼叫之前)将一个图案门当作"接通每一个呼叫".

```ts
import { tool } from "@dbx-tools/appkit-web-search";

// Every fetch requires approval:
tool.webFetchTool({ approval: true });

// Only fetches of an internal domain require approval:
tool.webFetchTool({ approval: "*.internal.example.com" });

// The same thing, with the mode named:
tool.webFetchTool({ approval: { mode: "urls", patterns: ["*.internal.example.com"] } });

// Plugin toolkit default:
plugin.webSearch({ approval: ["*.internal.example.com", "*.corp.example.com"] });

// Standalone tool config:
tool.webFetchTool({ config: { approval: ["*.internal.example.com"] } });
```

每种拼写都符合三种模式之一(`{ mode: "none" }`, (中文(简体) ), `{ mode: "always" }`,或 `{ mode: "urls", patterns }`),这是什么 解析了配置载体和启动日志报告。 批准语法与 允许列表,所以两种策略读取相同.

## 配置

分辨率顺序是明确的配置,先是环境变量,再是a 内建默认值.

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `model` | `string` | 通过倒计时解决 | Web-search endpoint:一个端点名称,一个松散的名称,或者一个能力类. |
| `modelFallbacks` | `string | string[]` | 双子座,然后是GPT | 有秩序的候选人在 `model` 未设定. |
| `webSearchTools` | `Record<string, unknown>` | 内建提供者地图 | 提供者 - > 请求分解覆盖,在默认情况下合并. |
| `modelFuzzyMatch` | `boolean` | `true` | 模糊相扑松散的模型名与活盘目录相对抗. |
| `modelFuzzyThreshold` | `number` | `0.4` | Fuse.js得分,低于此分,接受模糊的比赛. |
| `maxCitations` | `number` | `10` | 从一次搜索中返回了引用的硬盖 . |
| `fetchMaxLength` | `number` | `50000` | 硬盖上 `web_fetch` 内容长度,以字符表示. |
| `timeoutMs` | `number` | `60000` | 请求网络超时 . |
| `scrapeFallback` | `boolean` | `true` | 当没有部署网络搜索能力模型时, Scrape DuckDuckGo. |
| `urlPolicy` | `"unrestricted" | "allowlist"` | 如下 `allowedUrls` | 工具可能到达的 URL . |
| `allowedUrls` | `string | string[]` | 无 | 允许列表 globs 或赤色主机 . |
| `approval` | `boolean | string | string[] | ApprovalPolicy` | `{ mode: "none" }` | 两个工具的默认批准门 . |

| 环境变量 | 设定 |
| --- | --- |
| `WEB_SEARCH_MODEL` | `model` (专用重置,胜于以下约束) |
| `DATABRICKS_SERVING_ENDPOINT_NAME` | `model` (AppKit's Model's Service bounding,作为优先处理) |
| `WEB_SEARCH_MODEL_FALLBACKS` | `modelFallbacks` (通信/空间分离) |
| `WEB_SEARCH_TOOLS` | `webSearchTools` (JSON对象. 任何其它值在启动时失败 。 ) |
| `WEB_SEARCH_FUZZY` | `modelFuzzyMatch` |
| `WEB_SEARCH_FUZZY_THRESHOLD` | `modelFuzzyThreshold` |
| `WEB_SEARCH_MAX_CITATIONS` | `maxCitations` |
| `WEB_SEARCH_FETCH_MAX_LENGTH` | `fetchMaxLength` |
| `WEB_SEARCH_TIMEOUT_MS` | `timeoutMs` |
| `WEB_SEARCH_SCRAPE_FALLBACK` | `scrapeFallback` |
| `WEB_SEARCH_URL_POLICY` | `urlPolicy` |
| `WEB_SEARCH_ALLOWED_URLS` | `allowedUrls` (通信/空间分离) |

该插件的 `maxCitations` 编号 : `fetchMaxLength` 硬盖:每一次呼叫请求 可能缩小范围,但不会超过范围.

每一次外出通话,包括服务POST,一个页面取取取,和刮取 倒置,通过插件运行 `execute()` 链,所以所有三个都缓存, 重审了紧张的后退 超时 追踪 缓存已命名空格 每个用户,所以一个半结果 从来没有交叉身份。 见 `defaults.ts` 用于TTL和重试预算以及为什么选择每个预算.

OpenAI 响应网页搜索流本地搜索、页面阅读和完成 状态通过 Mastra 工具写入器。 常用工具片片片更新 在搜索运行时。 已完成的应对有效载荷仍然是工具成果.

要求: 本地网络搜索工具运行在付费的 GPT / 双子座 为跨区域处理的终点服务。 无法使用 为外部型号或根据HIPAA/BAA规定提供的吞吐量。 见 页:1 [数据砖文件](https://docs.databricks.com/aws/en/machine-learning/model-serving/web-search)。 。 。 .

## 模块

-   `plugin` - 说吧 `WebSearchPlugin`, (中文(简体) ), `webSearch()` AppKit 插件厂,以及 应用程序 `ToolProvider` 执行.
-   `tool` - 说吧 `webSearchTool()` 编号 : `webFetchTool()` 马斯特拉的工具.
-   `defaults` - 缓存/ 重试/ 超时设置 和每一个背后的推理.
-   `search` - 说吧 `runWebSearch()` 在 Databricks 本地网络搜索工具之上.
-   `provider` - 提供者检测 + 提供者 - > 工具谱图.
-   `scrape` - 说吧 `runScrapeSearch()` Duck Duck 退后加解析器后置 `parseDdgHtml()` 对没有本地网络搜索模式的工作空间进行结果提取.
-   `fetch` - 说吧 `runWebFetch()` 被冲了过来.
-   `html-text` - 说吧 `htmlToText()` 编号 : `htmlFragmentToText()` 编号 : `decodeHtmlEntities()`共享 `fetch` 鸭子去刮倒回落.
-   `runtime` - 单独的运行时间建造和执行: `createWebSearchRuntime()`, (中文(简体) ), `createResolvedWebSearchRuntime()`, (中文(简体) ), 财务报告和审定财务报表 `executeRead()`。 。 。 .
-   `config` JSON计划, `resolveWebSearchConfig()`, URL 策略 和批准帮助者.
-   `allowlist` - URL 允许列表解析/编译 `@dbx-tools/path`。 。 。 .
-   `schema` - zod工具合同和推断类型.

给这个包配对 [@dbx-tools/appkit-mastra (英语)](https://npmcn.com/package/%40dbx-tools/appkit-mastra) 应添加 工具,并通过 [@dbx-工具/型号](https://npmcn.com/package/%40dbx-tools/model)。 。 。 . 使用 [@dbx-tools/电子邮件](https://npmcn.com/package/%40dbx-tools/email) 对兄弟批准的工具模式.

## 常见问题

### @dbx-tools/appkit-web-search 是什么？

服务器端网络搜索运行时间、 Mastra 工具和 AppKit 插件

### 如何安装 @dbx-tools/appkit-web-search？

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

### @dbx-tools/appkit-web-search 支持 TypeScript 吗？

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

### @dbx-tools/appkit-web-search 支持 ESM 还是 CommonJS？

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

### @dbx-tools/appkit-web-search 可以商用吗？

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

### @dbx-tools/appkit-web-search 的下载量有多少？

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

### @dbx-tools/appkit-web-search 还在维护吗？

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