web-search-tavily

Web Search（Tavily API）

使用 Tavily 的 AI 优化搜索 API 搜索网页。返回高质量的结构化结果，包含相关性评分和可选的 AI 生成摘要。

**注意：**此技能需要 Tavily API 密钥。如需使用 Agent 内置功能进行基本网页搜索，请参阅 web-search。

何时使用此技能

在以下情况下使用此技能：

• 需要查找训练数据中没有的最新信息
• 用户询问近期事件、新闻或动态
• 需要核实事实或查找权威来源
• 研究需要实时网页数据
• 提到的关键词包括：搜索、查找、在线查找、当前、最新、新闻

在以下情况下不要使用此技能：

• 信息已在知识库中，无需核实
• 用户询问不会变化的历史事实
• 正在处理本地文件或代码（请使用其他工具）
• 存在更具体的任务技能（例如，文档查询）

前提条件

使用此技能前，请确保：

• TAVILY_API_KEY 环境变量已设置为有效的 API 密钥
• 已安装 Deno（用于运行搜索脚本）
• 可以访问互联网

在此处获取 Tavily API 密钥：https://tavily.com

快速开始

运行简单搜索：

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "your search query"

包含 AI 生成答案的示例：

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "React 19 new features" --answer

脚本用法

deno run --allow-env --allow-net=api.tavily.com scripts/search.ts [options] "query"

选项

选项	描述	默认值
--answer	包含 AI 生成的答案摘要	false
--depth <level>	搜索深度：basic 或 advanced	basic
--results <n>	返回的结果数量	5
--topic <type>	主题类型：general、news 或 finance	general
--time <range>	时间筛选：day、week、month 或 year	none
--include <domains>	仅包含这些域名（以逗号分隔）	none
--exclude <domains>	排除这些域名（以逗号分隔）	none
--raw	在结果中包含原始页面内容	false
--json	输出为 JSON（供程序使用）	false
--help	显示帮助信息	-

搜索参数

主题类型

• general（默认）：跨所有内容类型进行广泛网页搜索
• news：优先搜索新闻文章和时事
• finance：聚焦金融信息和市场数据

搜索深度

• basic（默认）：搜索速度快，适用于大多数查询
• advanced：进行更深入的搜索，结果更全面（速度较慢，API 成本较高）

时间范围

按时效筛选结果：

• day：过去 24 小时
• week：过去 7 天
• month：过去 30 天
• year：过去 365 天

域名筛选

控制结果中显示的网站：

# Only search documentation sites
scripts/search.ts "React hooks" --include docs.react.dev,developer.mozilla.org

# Exclude social media
scripts/search.ts "AI news" --exclude twitter.com,reddit.com

输出格式

易读输出（默认）

🔍 Search: "React 19 new features"

Found 5 results in 234ms

📝 AI Answer:
────────────────────────────────────────────────────────────
React 19 introduces several new features including...
────────────────────────────────────────────────────────────

1. React 19 Release Notes
   https://react.dev/blog/2024/04/25/react-19
   React 19 is now available on npm! This release includes...
   Score: 0.987

2. What's New in React 19
   https://example.com/react-19-features
   A comprehensive overview of React 19's new features...
   Score: 0.945

JSON 输出（--json）

{
  "query": "React 19 new features",
  "results": [
    {
      "title": "React 19 Release Notes",
      "url": "https://react.dev/blog/2024/04/25/react-19",
      "content": "React 19 is now available on npm...",
      "score": 0.987,
      "published_date": "2024-04-25"
    }
  ],
  "answer": "React 19 introduces several new features...",
  "response_time": 234
}

结果字段

字段	类型	描述
title	string	页面标题
url	string	来源 URL
content	string	页面中的相关摘录
score	number	相关性评分（0-1，越高越好）
published_date	string	发布日期（如有）
raw_content	string	完整页面内容（仅使用 --raw 时）

示例

示例 1：时事搜索

场景：查找某个技术主题的近期新闻

scripts/search.ts "OpenAI GPT-5 announcement" --topic news --time week --answer

预期输出：有关 GPT-5 的近期新闻文章，以及 AI 生成的摘要

示例 2：文档查询

场景：查找特定技术文档

scripts/search.ts "Deno deploy edge functions tutorial" --depth advanced --results 10

预期输出：来自文档和教程网站的全面结果

示例 3：事实核实

场景：核实某项具体说法或统计数据

scripts/search.ts "world population 2024" --include un.org,worldbank.org,census.gov --json

预期输出：来自权威来源的 JSON 结果，可用于程序化核实

示例 4：金融研究

场景：研究市场信息

scripts/search.ts "NVIDIA stock analysis 2024" --topic finance --answer

预期输出：金融分析和市场数据，以及 AI 摘要

常见问题和解决方案

问题：“未设置 TAVILY_API_KEY 环境变量”

症状：脚本立即退出，并提示 API 密钥错误

解决方案：

1. 从 https://tavily.com 获取 API 密钥
2. 设置环境变量：

   export TAVILY_API_KEY="your-api-key-here"
   

3. 或在运行时直接设置变量：

   TAVILY_API_KEY="your-key" deno run --allow-env --allow-net=api.tavily.com scripts/search.ts "query"
   

问题：“Tavily API 密钥无效”

症状：401 身份验证错误

解决方案：

1. 确认 API 密钥正确（没有多余空格）
2. 检查 API 密钥是否已过期
3. 确认 Tavily 账户处于有效状态

问题：“Tavily API 超出速率限制”

症状：返回 429 错误

解决方案：

1. 稍等片刻后重试
2. 降低请求频率
3. 考虑升级 Tavily 方案以提高限额

问题：未返回结果

症状：结果数组为空

解决方案：

1. 尝试使用更宽泛的搜索词
2. 移除可能限制过严的域名筛选条件
3. 检查该主题是否存在于网上
4. 对于较难的查询，尝试使用 --depth advanced

限制

此技能有以下限制：

• 需要有效的互联网连接
• API 速率限制取决于你的 Tavily 方案
• 结果取决于 Tavily 的索引覆盖范围
• 无法访问付费墙内容或需要登录的内容
• 实时准确性取决于 Tavily 的抓取频率
• 查询长度和结果数量受 API 限制

相关技能

• research-workflow：适用于需要通过规划和综合分析进行多次搜索的全面研究项目