Skill: guogithubname/tavilysearch-1-0-4 (version 1.0.0)

--- name: tavily-search description: Tavily 搜索引擎集成，支持 web 搜索、内容提取、实时新闻查询等功能。使用场景：需要搜索最新网络信息、查找实时新闻、获取专业资料、验证事实准确性等。 env: - name: TAVILY_API_KEY description: Tavily API 密钥，用于调用搜索、提取、爬取等功能 required: true --- # 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 核心搜索能力，支持多维度过滤和优化： ```bash # 命令行调用 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` | **使用示例：** ```bash # 搜索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的结构化内容，自动清理广告和无关元素： ```bash # 命令行调用 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` | **使用示例：** ```bash # 批量提取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. 整站爬取 自动遍历整个网站，智能发现并爬取所有相关页面： ```bash # 命令行调用 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` | **使用示例：** ```bash # 爬取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. 深度研究 自动进行多轮搜索、信息整合，生成结构化研究报告： ```bash # 命令行调用 python scripts/search.py research "研究主题" [选项] ``` **研究选项：** | 参数 | 说明 | 默认值 | |------|------|--------| | `--model <mini/pro/auto>` | 研究模型，mini适合简单主题，pro适合复杂主题 | `auto` | | `--citation <numbered/mla/apa/chicago>` | 引用格式 | `numbered` | | `--json` | 输出JSON格式 | `false` | **使用示例：** ```bash # 生成行业研究报告 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信用点使用情况和剩余额度： ```bash # 脚本调用 python scripts/search.py usage ``` **返回结构说明：** ```json { "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. 响应格式 ```json { "query": "搜索关键词", "answer": "LLM生成的直接答案（当include_answer=true时返回）", "results": [ { "title": "结果标题", "url": "页面链接", "content": "内容摘要", "score": 0.85, "favicon": "网站图标链接" } ], "response_time": 1.23, "usage": { "credits": 1 } } ``` ## 使用示例 ### 搜索最新新闻 ```bash 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 }' ``` ### 专业资料搜索 ```bash 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 依赖，确保脚本正常运行 - ✅ 所有核心功能测试通过

path: requirements.txt
content: requests>=2.31.0
urllib3>=2.0.0

path: _meta.json
content: ownerId: kn752xgexz2ttxjbd35tdehn0981y6zf
slug: tavilysearch
version: 1.0.4
publishedAt: 1773577125941

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)