SkillHub

tavilysearch

v1.0.4

Tavily 搜索引擎集成，支持 web 搜索、内容提取、实时新闻查询等功能。使用场景：需要搜索最新网络信息、查找实时新闻、获取专业资料、验证事实准确性等。

Sourced from ClawHub, Authored by xRay

Installation

Please help me install the skill `tavilysearch` from SkillHub official store. npx skills add raydoomed/tavilysearch

Tavily Search Skill

Tavily 是专门为 AI 代理设计的搜索引擎，提供快速、准确的网络搜索能力，支持实时信息检索、内容提取、多维度过滤等功能。

前置配置

  1. 首先获取 Tavily API Key：https://tavily.com/
  2. 安装依赖：pip install -r requirements.txt
  3. 新建 .env 文件，填入你的 API Key： env TAVILY_API_KEY=tvly-你的实际API密钥
  4. 程序会自动读取技能目录下的 .env 文件，无需配置全局环境变量

核心功能

1. 网页搜索

Tavily 核心搜索能力，支持多维度过滤和优化：

# 命令行调用
python scripts/search.py search "搜索关键词" [选项]

# 最简调用
curl -X POST https://api.tavily.com/search 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $TAVILY_API_KEY" 
  -d '{"query": "搜索关键词", "include_answer": true}'

搜索选项： | 参数 | 说明 | 默认值 | |------|------|--------| | --depth <basic/advanced/fast/ultra-fast> | 搜索深度，basic=1信用点，advanced=2信用点 | basic | | --chunks <1-3> | 每个来源返回的内容片段数量（仅advanced深度有效） | 3 | | --max <0-20> | 返回结果数量 | 5 | | --topic <general/news/finance> | 搜索主题，news适合实时新闻 | general | | --time <day/week/month/year> | 相对时间范围过滤 | 无 | | --start-date <YYYY-MM-DD> | 仅返回该日期之后的结果 | 无 | | --end-date <YYYY-MM-DD> | 仅返回该日期之前的结果 | 无 | | --answer | 包含LLM生成的直接答案 | false | | --raw | 包含网页原始内容 | false | | --images | 包含图片搜索结果 | false | | --image-descriptions | 包含图片描述文本 | false | | --favicon | 包含网站图标URL | false | | --include <域名1,域名2> | 限定搜索的域名列表（最多300个） | 无 | | --exclude <域名1,域名2> | 排除的域名列表（最多150个） | 无 | | --country <国家/地区> | 优先返回指定国家/地区的结果 | 无 | | --auto-params | 开启自动参数优化（自动调整搜索深度等） | false | | --exact | 精确匹配查询短语 | false | | --usage | 响应中包含用量信息 | false | | --json | 输出JSON格式 | false |

使用示例：

# 搜索2025年全年AI行业新闻
python scripts/search.py search "2025年AI行业大事件" 
  --topic news 
  --start-date 2025-01-01 
  --end-date 2025-12-31 
  --max 20 
  --answer

# 高级技术搜索，限定学术/技术域名
python scripts/search.py search "大语言模型推理优化技术" 
  --depth advanced 
  --chunks 3 
  --include arxiv.org,github.com,stackoverflow.com 
  --favicon

2. 网页内容提取

批量提取指定URL的结构化内容，自动清理广告和无关元素：

# 命令行调用
python scripts/search.py extract "url1,url2,..." [选项]

提取选项： | 参数 | 说明 | 默认值 | |------|------|--------| | --query <关键词> | 按关键词重排内容片段 | 无 | | --chunks <1-5> | 每个URL返回的片段数量 | 3 | | --extract-depth <basic/advanced> | 提取深度，advanced支持表格/嵌入内容 | basic | | --markdown | 输出Markdown格式 | false | | --images | 包含图片 | false | | --favicon | 包含网站图标 | false | | --json | 输出JSON格式 | false |

使用示例：

# 批量提取3个技术文档，按"API"关键词重排内容
python scripts/search.py extract "https://docs.tavily.com,https://example.com/docs,https://api.example.com" 
  --query "API" 
  --extract-depth advanced 
  --chunks 5 
  --markdown > docs.md

3. 整站爬取

自动遍历整个网站，智能发现并爬取所有相关页面：

# 命令行调用
python scripts/search.py crawl "根URL" [选项]

爬取选项： | 参数 | 说明 | 默认值 | |------|------|--------| | --instructions <文本> | 自然语言爬取指令（如"查找所有API文档页面"） | 无 | | --max-depth <1-5> | 最大爬取深度 | 1 | | --max-breadth <1-500> | 每层页面的最大链接数 | 20 | | --limit <数字> | 总爬取页面上限 | 50 | | --select-paths <正则1,正则2> | 只爬取匹配路径的页面 | 无 | | --select-domains <域名1,域名2> | 只爬取指定域名的页面 | 无 | | --exclude-paths <正则1,正则2> | 排除匹配路径的页面 | 无 | | --exclude-domains <域名1,域名2> | 排除指定域名的页面 | 无 | | --allow-external | 允许爬取外部域名 | true | | --extract-depth <basic/advanced> | 内容提取深度 | basic | | --markdown | 输出Markdown格式 | false | | --images | 包含图片 | false | | --favicon | 包含网站图标 | false | | --json | 输出JSON格式 | false |

使用示例：

# 爬取Tavily文档站，只收集API相关页面
python scripts/search.py crawl "https://docs.tavily.com" 
  --instructions "Find all API documentation pages" 
  --max-depth 3 
  --limit 100 
  --select-paths "/api/.*,/documentation/.*"

4. 深度研究

自动进行多轮搜索、信息整合，生成结构化研究报告：

# 命令行调用
python scripts/search.py research "研究主题" [选项]

研究选项： | 参数 | 说明 | 默认值 | |------|------|--------| | --model <mini/pro/auto> | 研究模型，mini适合简单主题，pro适合复杂主题 | auto | | --citation <numbered/mla/apa/chicago> | 引用格式 | numbered | | --json | 输出JSON格式 | false |

使用示例：

# 生成行业研究报告
python scripts/search.py research "2026年AI Agent行业发展趋势" 
  --model pro 
  --citation apa

# 查询已有研究任务结果
python scripts/search.py get-research "任务ID"

5. 用量查询

官方文档：https://docs.tavily.com/documentation/api-reference/endpoint/usage

查看API信用点使用情况和剩余额度：

# 脚本调用
python scripts/search.py usage

返回结构说明：

{
  "key": {
    "usage": 135,
    "limit": 1000,
    "search_usage": 81,
    "crawl_usage": 0,
    "extract_usage": 2,
    "map_usage": 0,
    "research_usage": 52
  },
  "account": {
    "current_plan": "Researcher",
    "plan_usage": 135,
    "plan_limit": 1000,
    "search_usage": 81,
    "crawl_usage": 0,
    "extract_usage": 2,
    "map_usage": 0,
    "research_usage": 52,
    "paygo_usage": 0,
    "paygo_limit": null
  }
}
  • key 字段：当前使用的API Key的用量统计
  • account 字段：整个Tavily账户的总用量统计
  • 用量查询结果有5-10分钟缓存，如需实时数据请直接调用官方API

2. 高级搜索参数

参数 类型 默认值 说明
query string 必填 搜索关键词
search_depth enum basic 搜索深度：basic(1信用点, 平衡) / advanced(2信用点, 更高精度) / fast(快速) / ultra-fast(极速)
max_results integer 5 返回结果数量，范围 0-20
topic enum general 搜索主题：general(通用) / news(新闻) / finance(财经)
time_range enum 可选 时间范围：day/week/month/year
include_answer boolean false 是否包含 LLM 生成的直接答案
include_images boolean false 是否返回图片结果
include_raw_content boolean false 是否返回网页原始内容
include_domains array 可选 限定搜索的域名列表
exclude_domains array 可选 排除的域名列表
country string 可选 按国家/地区优先返回结果

3. 响应格式

{
  "query": "搜索关键词",
  "answer": "LLM生成的直接答案（当include_answer=true时返回）",
  "results": [
    {
      "title": "结果标题",
      "url": "页面链接",
      "content": "内容摘要",
      "score": 0.85,
      "favicon": "网站图标链接"
    }
  ],
  "response_time": 1.23,
  "usage": {
    "credits": 1
  }
}

使用示例

搜索最新新闻

curl -X POST https://api.tavily.com/search 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $TAVILY_API_KEY" 
  -d '{
    "query": "2026年3月科技行业最新动态",
    "topic": "news",
    "time_range": "day",
    "include_answer": true,
    "max_results": 10
  }'

专业资料搜索

curl -X POST https://api.tavily.com/search 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $TAVILY_API_KEY" 
  -d '{
    "query": "大语言模型推理优化技术",
    "search_depth": "advanced",
    "include_raw_content": true,
    "include_domains": ["arxiv.org", "github.com", "openai.com"]
  }'

注意事项

  • API 调用信用点：基础搜索1点/次，高级搜索2点/次，内容提取1点/次，整站爬取2点/次，深度研究5点/次
  • 免费 tier 提供 1000 次/月搜索额度
  • 搜索结果默认按相关性排序，score 越高越相关
  • 实时新闻查询请使用 topic: "news" 参数确保获取最新内容
  • 深度研究任务耗时较长（通常30-60秒），请耐心等待
  • 爬取大量页面时建议设置合理的 limit 参数，避免信用点过度消耗

版本更新

v1.0.4 (2026-03-15)

  • ✅ 修复环境变量读取逻辑，只读取 TAVILY_API_KEY 避免暴露敏感信息
  • ✅ 在 SKILL.md 中添加环境变量声明，确保注册数据与实际需求一致
  • ✅ 移除未使用的 python-dotenv 依赖，优化依赖管理
  • ✅ 添加 urllib3 依赖，确保脚本正常运行
  • ✅ 所有核心功能测试通过