Mastra × Tavily 集成全解析从 0.1.0-alpha 到 1.1.2 的演进与四个一等公民搜索工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇技术指南以mastra/tavily的 CHANGELOG 为主线完整梳理该集成包从首个 alpha 版本到 1.1.2 的演进历程并深入仓库源码逐一向你拆解search、extract、crawl、map四个一等公民 Mastra 工具的输入输出 Schema、配置解析与底层调用链以及 X-Client-Name 归属头、依赖治理、供应链安全修复等工程细节。读完本文你将掌握如何在 Mastra Agent 中一键接入 Tavily 的完整 Web 检索能力并理解该集成包每个版本号背后真实发生过的技术变更。一、包概况与演进脉络mastra/tavily是 Mastra 官方维护的 Tavily 集成包定位是为 Mastra Agent 提供 Tavily 搜索、提取、爬取和站点地图工具支持共享配置、类型化 Zod Schema 与结构化 Web 结果见 README 与 package.json 中的包描述。当前仓库中的版本为1.1.2其核心依赖为tavily/core^0.7.6对mastra/core1.0.0-0 2.0.0-0与zod3.0.0 || 4.0.0均为 peerDependency运行环境要求 Node.js22.13.0。从 CHANGELOG 的版本历史可以清晰看到一条完整的演进时间线版本类型核心变更0.1.0-alpha.0Minor初版发布createTavilySearchTool、createTavilyExtractTool、createTavilyCrawlTool、createTavilyMapTool、createTavilyTools五大工厂函数1.0.0 / 1.0.0-alpha.1Major正式发布新增一等公民工具mastracode的 Web 搜索工具迁移到本集成1.0.1Patch修复运行时ERR_MODULE_NOT_FOUND将tavily/core改为直接依赖消费者无需手动安装1.0.2Patch依赖升级tavily/core^0.7.3 → ^0.7.5同步更新 ai-sdk 依赖1.0.3Patch依赖升级tavily/core^0.7.5 → ^0.7.61.0.5Patch2026-06-17 easy-day-js 供应链事件安全修复发布干净版本并前移latestdist-tag1.1.0Minor随机版本提升Random bump1.1.1Patch修复 Tavily 请求归属改用X-Client-Name请求头1.1.2Patch更新 README 内容从 npm 分发产物中移除CHANGELOG.md减小包体积值得注意的是每个版本都随附了对mastra/core的依赖更新例如 1.1.2 对应mastra/core1.64.0、1.1.1 对应mastra/core1.52.0、1.0.1 对应mastra/core1.27.0这说明该集成与核心框架保持紧耦合的同步发布节奏。二、四个一等公民工具输入输出全参数详解CHANGELOG 的 0.1.0-alpha.0 条目定义了本包的 API 骨架源码 index.ts 完整导出了全部五个工厂函数。下面结合各工具实现逐一展开。2.1 createTavilySearchTool —— Web 搜索实现位于 search.ts工具 ID 为tavily-search。它通过createTool包装 Tavily 的search接口输入 Schema 完整覆盖了 Tavily 搜索的核心参数参数类型 / 取值说明querystring必填搜索查询词searchDepthbasic \| advanced \| fast \| ultra-fast可选搜索深度basic标准、advanced深入、fast/ultra-fast低延迟maxResultsnumber1–20可选返回结果条数上限includeAnswerboolean \| basic \| advanced可选是否返回 AI 生成答案摘要可传true、basic或advancedincludeImagesboolean可选是否返回查询相关图片includeImageDescriptionsboolean可选是否返回图片描述includeRawContentfalse \| markdown \| text可选是否包含每条结果的清洗后 HTML 内容false关闭或指定markdown/text格式includeDomainsstring[]可选仅返回这些域名的结果excludeDomainsstring[]可选排除这些域名的结果timeRangeday \| week \| month \| year可选按时间范围过滤结果输出 Schema 结构化为{ query, answer?, images?, results[], responseTime }其中results每项包含title、url、content、score与可选的rawContent。在execute中工具将入参逐项透传给底层tavilyClient.search()并把响应中的图片兼容字符串与对象两种形态与结果数组规整为统一结构后返回。2.2 createTavilyExtractTool —— URL 内容提取实现位于 extract.ts工具 ID 为tavily-extract用于从指定 URL 提取页面内容参数类型 / 取值说明urlsstring[]1–20 个必填待提取内容的 URL 列表单次请求最多 20 个extractDepthbasic \| advanced可选提取深度advanced可获取表格与内嵌内容等更多数据querystring可选用户意图用于对提取内容分块做相关性重排序rerankincludeImagesboolean可选是否包含页面中提取的图片formatmarkdown \| text可选输出格式默认markdown其输出 Schema 包含results每项含url、rawContent、可选images、failedResults每项含url与error用于定位提取失败的 URL以及responseTime。2.3 createTavilyCrawlTool —— 站点爬取实现位于 crawl.ts工具 ID 为tavily-crawl从根 URL 出发爬取站点并提取每个发现页面的结构化内容。其输入参数在 extract 的基础上增加了爬取控制维度参数类型说明urlstring必填爬取起始根 URLmaxDepthnumber可选相对基础 URL 的最大爬取深度maxBreadthnumber可选每个页面最多跟随的链接数limitnumber可选爬虫在停止前处理的总页面数instructionsstring可选面向爬虫的自然语言指令selectPaths/selectDomainsstring[]可选正则模式仅选择匹配的 URL 路径 / 域名excludePaths/excludeDomainsstring[]可选正则模式排除匹配的 URL 路径 / 域名allowExternalboolean可选是否跟随指向外部域名的链接extractDepth/includeImages/format同上内容提取深度、图片与输出格式输出 Schema 为{ baseUrl, results[], responseTime }results每项包含url、rawContent与可选images。2.4 createTavilyMapTool —— 站点地图发现实现位于 map.ts工具 ID 为tavily-map。与 crawl 不同的是map只发现并返回站点的 URL 列表而不提取页面内容适合在定向提取之前先理解站点结构。其输入参数与 crawl 的控制参数一致maxDepth、maxBreadth、limit、instructions、selectPaths、selectDomains、excludePaths、excludeDomains、allowExternal而输出 Schema 简化为{ baseUrl, results: string[], responseTime }results即发现到的 URL 数组。2.5 createTavilyTools —— 一键批量装配实现位于 tools.ts一个函数同时返回四个工具并共享同一份配置export function createTavilyTools(config?: TavilyClientOptions) { return { tavilySearch: createTavilySearchTool(config), tavilyExtract: createTavilyExtractTool(config), tavilyCrawl: createTavilyCrawlTool(config), tavilyMap: createTavilyMapTool(config), }; }三、客户端初始化与配置解析所有工具内部都通过 client.ts 中的getTavilyClient懒加载共享客户端首次调用时创建并缓存见各工具源码中的getClient闭包。其配置解析逻辑值得细看export function getTavilyClient(config?: TavilyClientOptions): TavilyClient { const apiKey config?.apiKey ?? process.env.TAVILY_API_KEY; if (!apiKey) { throw new Error(Tavily API key is required. Pass { apiKey } or set TAVILY_API_KEY env var.); } // defaulting clientName to mastra if not provided return tavily({ ...config, apiKey, clientName: config?.clientName ?? mastra }); }三个关键点API Key 三级解析优先级config.apiKey 环境变量TAVILY_API_KEY 抛出错误。也就是说你既可以在创建工具时显式传{ apiKey }也可以只在环境里设置TAVILY_API_KEYclientName 默认值未指定时默认写入mastra用于向 Tavily 标识请求来源。这正是 1.1.1 版本修复的核心——请求归属attribution改为通过X-Client-Name请求头传递保证来自 Mastra 的调用在 Tavily 侧被正确识别类型定义TavilyClient ReturnTypetypeof tavily直接复用tavily/core的客户端类型保证search、extract、crawl、map四个方法的类型安全。单测佐证client.test.ts 用 Vitest 逐条验证了上述行为无 Key 抛错、优先使用config.apiKey、回退到环境变量、支持自定义clientName以及返回的客户端对象四个方法齐全tools.test.ts 则验证了createTavilyTools返回四个工具、ID 正确tavily-search/tavily-extract/tavily-crawl/tavily-map且每个工具都带 description 与输入输出 Schema。四、版本演进中的工程化与安全修复CHANGELOG 记录的不仅是功能还有一系列真实的工程与安全问题值得逐一说明其背景4.1 1.0.1修复运行时ERR_MODULE_NOT_FOUND早期版本将tavily/core作为传递依赖消费者安装mastra/tavily后运行时可能因找不到该包而抛出ERR_MODULE_NOT_FOUND。1.0.1 将其改为直接依赖direct dependency消费者无需再手动安装tavily/core。这一点在 package.json 的dependencies中可以看到最终的固化结果。4.2 1.0.2 / 1.0.3依赖版本治理这两个版本对tavily/core做了连续升级^0.7.2 → ^0.7.3 → ^0.7.5 → ^0.7.6同时在 1.0.2 中同步更新了 ai-sdk 依赖。从中可以推断该项目对上游 SDK 保持及时跟进以获得 Tavily 官方客户端的 bug 修复与新能力。4.3 1.0.5供应链安全事件修复CHANGELOG 明确记载针对 2026-06-17 的 easy-day-js 供应链事件该版本发布干净版本并前移latestdist-tag以取代声明了恶意easy-day-js依赖的受影响版本。这是对包安全性的兜底处理——即便被破坏的版本来自上游依赖链维护者也通过重新发布来阻断影响。4.4 1.1.1X-Client-Name 请求归属头如前所述1.1.1 将 Tavily 请求归属改为使用X-Client-Name请求头与 client.ts 中clientName默认mastra的实现相呼应确保官方对集成方流量的准确归因与统计。4.5 1.1.2README 更新与包体积优化1.1.2 做了两件事一是更新 README 使其信息准确、与当前版本一致即你在 README 中看到的安装、用法与文档索引二是从 npm 分发产物中移除CHANGELOG.md减小安装包体积——对应 package.json 中files: [dist]仅发布构建产物的策略。4.6 1.0.0mastracode 搜索工具迁移1.0.0 除了正式发布四个工具外还完成了一件内部大事将mastracode的 Web 搜索工具迁移到本集成之上。这说明mastra/tavily不仅是对外提供的能力也是 Mastra 自家编码代理mastracode 目录实际使用的搜索基础设施属于吃自己的狗粮式验证。五、实战在 Agent 中装配搜索与提取结合 README 的用法示例与上述源码分析一个完整的实战配置如下import { Agent } from mastra/core/agent; import { createTavilyExtractTool, createTavilySearchTool } from mastra/tavily; export const researchAgent new Agent({ id: research-agent, name: Research Agent, model: openai/gpt-5.6-sol, instructions: Search for relevant pages, then extract the best sources before answering., tools: { search: createTavilySearchTool(), extract: createTavilyExtractTool(), }, });使用前需先设置环境变量export TAVILY_API_KEYyour_key_here也可以只用一个函数接入全部能力并共享同一份客户端配置例如统一的clientNameimport { createTavilyTools } from mastra/tavily; const tools createTavilyTools(); // 返回 tavilySearch / tavilyExtract / tavilyCrawl / tavilyMap依赖安装方式Node.js 22.13.0npm install mastra/tavily安装后tavily/core已作为直接依赖自动就绪无需手动安装。从源码结构看搜索到提取再到爬取/映射形成了完整的 Web 信息获取链路先用tavily-search定位候选来源用tavily-extract深度提取正文需要全面建站结构时再辅以tavily-map与tavily-crawl——这也正是 research agent 类应用的标准数据管线。六、结论mastra/tavily从 0.1.0-alpha 到 1.1.2 的 CHANGELOG 记录了一段完整的集成演进史五个工厂函数构成了清晰的 API 骨架源码 client.ts、search.ts、extract.ts、crawl.ts、map.ts 与 tools.ts 给出了完整的参数语义而 client.test.ts 与 tools.test.ts 则锁定了这些行为的正确性。无论你是要在 Mastra Agent 中快速接入 Web 搜索还是想借鉴一个生产级集成包在依赖治理、请求归属与供应链安全上的实践这个包都是一份值得精读的参考实现。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考