tavily-search

name	tavily-search
description	使用 Tavily API 进行实时网页搜索。当用户需要搜索最新信息、查找资料、核实事实、研究话题时触发。支持自然语言如 "搜索XX"、"查一下XX"、"帮我找XX"、"search for XX"、"look up XX" 等。也作为 /tavily-search slash command 被调用。

Tavily Search

通过 Tavily Search API 执行实时网页搜索，获取最新、准确的信息。

API 配置

• API 端点: https://api.tavily.com/search
• API Key: 从环境变量 TAVILY_API_KEY 读取
• 请求方式: POST，Content-Type: application/json

关键参数

参数	类型	默认值	说明
api_key	string	必填	从 $TAVILY_API_KEY 环境变量读取
query	string	必填	搜索查询字符串
search_depth	string	"advanced"	"basic" 快速搜索，"advanced" 深度搜索
max_results	number	10	返回结果数，范围 1-20
include_answer	boolean	true	是否包含 AI 生成的摘要回答
include_domains	array	无	限定搜索域名列表
exclude_domains	array	无	排除的域名列表
include_raw_content	boolean	false	是否包含页面原始内容
days	number	无	仅返回最近 N 天内的内容（如 7 表示一周内）

执行流程

Step 1: 检查 API Key

首先检查环境变量是否设置：

echo $TAVILY_API_KEY

如果为空，告知用户需要设置 TAVILY_API_KEY 环境变量。获取方式：访问 https://tavily.com 注册并获取 API key。

Step 2: 理解用户意图

分析用户的搜索请求，确定：

• 查询语句：提炼核心搜索词，英文查询通常效果更好
• 搜索深度：简单事实用 basic，需要全面信息的复杂话题用 advanced
• 结果数量：快速了解用 5 条，深入研究用 10-20 条
• 时间范围：如果用户关心最新信息，加上 days 参数
• 域名过滤：如果用户指定了来源偏好，使用 include_domains 或 exclude_domains

Step 3: 执行搜索

使用 curl 调用 Tavily API。将 JSON body 写入临时文件以避免 shell 转义问题：

# 基础用法
curl -s -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'"$TAVILY_API_KEY"'",
    "query": "搜索查询",
    "search_depth": "advanced",
    "max_results": 10,
    "include_answer": true
  }'

Step 4: 格式化输出

将 API 返回的结果整理为清晰易读的格式。必须包含：

1. AI 摘要（如果存在）：首先展示 answer 字段作为概览
2. 结果列表：每条结果包含：
   • 标题（可点击的 URL）
   • 内容摘要
   • 相关性评分（score，0-1 之间）
3. 查询信息：响应时间、结果数量

输出格式模板：

## 搜索结果：{query}

> {answer} （AI 摘要）

### 相关结果

1. **[{title}]({url})**  `相关度: {score}`
   {content}

2. **[{title}]({url})**  `相关度: {score}`
   {content}

...

---
*共 {n} 条结果 · 响应时间 {response_time}s*

高级用法

限定时间范围

用户要最新信息时，添加 days 参数：

curl -s -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "'"$TAVILY_API_KEY"'", "query": "...", "days": 7, ...}'

限定或排除域名

# 只看特定来源
"include_domains": ["github.com", "stackoverflow.com"]

# 排除低质量来源
"exclude_domains": ["pinterest.com", "quora.com"]

获取完整内容

需要更详细的上下文时，设置 "include_raw_content": true。注意这会增加响应体积。

错误处理

错误	原因	处理
TAVILY_API_KEY 为空	未配置 API key	引导用户去 tavily.com 注册获取 key，然后 export TAVILY_API_KEY=xxx
API 返回 401	API key 无效	提示用户检查 key 是否正确
API 返回 429	超出速率限制	告知用户稍后重试，免费版有每日限额
API 返回 500+	服务端错误	稍后重试或联系用户确认
curl 网络错误	网络不通	检查网络连接
返回结果为空	搜索无匹配	尝试更通用的关键词或去掉过滤条件

注意事项

• Tavily 免费版每天有查询次数限制，具体限额见 tavily.com/pricing
• 英文查询通常比中文查询返回更多高质量结果
• advanced 深度搜索耗时更长但结果更全面
• 结果中的 score 是 0-1 的相关性评分，越高越相关
• 如果用户需要的是实时新闻，配合 days: 1 或 days: 3 使用