# Tavily Search

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

- Skill: `flingjie/tavily-search` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flingjie/tavily-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flingjie/tavily-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: flingjie (https://skillmd.com/u/flingjie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flingjie/tavily-search

---


# 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

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

```bash
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 转义问题：

```bash
# 基础用法
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` 参数：

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

### 限定或排除域名

```bash
# 只看特定来源
"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` 使用