Tavily AI 搜索与内容提取
> 本 skill 为英文版 tavily 的中文版本。命令、参数、响应结构完全一致，仅文档语言不同。
安装
先确认 tavily 命令是否可用：
which tavily && tavily --version
npx @renxqoo/tavily-cli install
鉴权
> ⚠️ 安全红线：绝对不要将 API Key 硬编码到代码或聊天记录中。
> 禁止把 TAVILY_API_KEY 的值写入任何文件、命令回显或对话；只引用变量本身。
使用前需要配置 Tavily API Key：
# 方式一：系统环境变量（推荐，Key 不落盘到项目文件）
export TAVILY_API_KEY=tvly-xxxx # 可写入 ~/.zshrc 持久化，改后重启 WorkBuddy
# 方式二：保存到本地凭证库（~/.tavily-cli/credentials/，仅当前用户可读）
TAVILY_API_KEY=tvly-xxxx tavily auth login
# 检查状态（只显示来源，不回显 Key）
tavily auth status --json
API Key 以 tvly- 开头，可在 Tavily 控制台 获取。
Agent 安全约定：
- 需要 Key 时读取环境变量或 ~/.tavily-cli/credentials/，不要询问用户粘贴 Key 到对话中
- 鉴权失败时提示用户检查环境变量或运行 tavily auth login，不要打印或保存 Key 值
- Key 疑似泄露时建议用户到 Tavily 控制台吊销重建
命令
| 操作 | 命令 |
|---|---|
| 使用 Tavily AI 搜索网络内容 | tavily search <query> [--search_depth <string>] [--max_results <number>] [--topic <string>] [--time_range <string>] [--start_date <string>] [--end_date <string>] [--include_answer] [--include_raw_content] [--include_images] [--include_domains <string>...] [--exclude_domains <string>...] [--country <string>] |
| 从指定 URL 提取网页内容 | tavily extract <urls> [--query <string>] [--extract_depth <string>] [--include_images] [--format <string>] [--timeout <number>] |
| 爬取站点并提取多个页面的内容（图遍历） | tavily crawl <url> [--instructions <string>] [--max_depth <number>] [--max_breadth <number>] [--limit <number>] [--select_paths <string>...] [--select_domains <string>...] [--exclude_paths <string>...] [--exclude_domains <string>...] [--allow_external] [--include_images] [--extract_depth <string>] [--format <string>] [--include_favicon] [--timeout <number>] [--include_usage] |
| 生成站点 URL 地图（发现链接，不提取内容） | tavily map <url> [--instructions <string>] [--max_depth <number>] [--max_breadth <number>] [--limit <number>] [--select_paths <string>...] [--select_domains <string>...] [--exclude_paths <string>...] [--exclude_domains <string>...] [--allow_external] [--timeout <number>] [--include_usage] |
| 发起深度研究任务并等待报告生成（异步） | tavily research <input> [--model <string>] [--citation_format <string>] [--output_length <string>] [--include_domains <string>...] [--exclude_domains <string>...] [--wait] [--wait_timeout <number>] |
| 从环境变量 TAVILY_API_KEY 保存 API Key 到本地 | tavily auth login |
| 清除本地保存的 Tavily API Key | tavily auth logout |
| 检查当前凭证配置状态 | tavily auth status |
| 查询研究任务的状态与结果 | tavily research get <request_id> |
> 命令详解（参数范围、枚举值、响应结构、成本，按需查阅）：search · extract · crawl · map · research · auth
搜索 + 提取组合
# 1. 搜索找到相关页面
tavily search "Rust 异步编程" --max_results 3 --include_answer --json
# 2. 从搜索结果中提取感兴趣页面的完整内容
tavily extract https://blog.example.com/rust-async --format markdown --json
带过滤的新闻搜索
# 搜索最近一周的 AI 新闻，排除某些域名
tavily search "OpenAI" --topic news --time_range week --exclude_domains ads.com spam.com --json
金融搜索与域名过滤
# 查金融/行情类信息（topic=finance；注意：是金融新闻搜索，非实时行情或专业金融数据源）
tavily search "苹果股价" --topic finance --json
# 结果限定在指定域名内
tavily search "react hooks" --include_domains github.com --json
站点探索：map → extract 组合
# 1. 先用 map 低成本发现站点结构（只消耗少量 credits）
tavily map https://docs.example.com --max_depth 2 --json
# 2. 对感兴趣的页面用 extract 提取正文
tavily extract https://docs.example.com/api --json
> 当站点结构未知时，推荐 map 先行而非直接 crawl，成本更低。
深度研究（异步任务）
# 方式一：自动轮询直到报告生成（默认行为）
tavily research "2026 年 AI Agent 生态格局" --model pro --json
# 方式二：只创建任务，稍后查询（适合长任务，不阻塞）
tavily research "量化交易策略比较" --model mini --no-wait --json
tavily research get <request_id> --json
> research 任务创建后异步执行：mini 模型最快（约 1-2 分钟），pro 更全面但更慢。
> 默认自动轮询（--wait），可用 --wait_timeout <秒> 控制最大等待，超时返回 request_id 供后续查询。
前置条件
- 已配置 API Key:
tavily auth status --json - 网络可访问
https://api.tavily.com
错误处理
判断方式：命令失败时输出 {"ok":false,"error":{...}}，依据 error.type / error.subtype 判断错误类别（注意：进程 exit code 恒为 0，不要用 exit code 判断错误）：
| error.type | error.subtype | 处理 |
|---|---|---|
authentication |
no_credentials |
设置 TAVILY_API_KEY 环境变量或运行 tavily auth login |
authentication |
no_token |
API Key 无效或已过期，检查 Key 是否正确 |
api |
rate_limited |
请求过于频繁，等待后重试（最多 3 次，间隔递增） |
api |
server_error |
Tavily 服务端临时故障，稍后重试（最多 3 次），仍失败则告知用户服务不可用 |
validation |
invalid_argument |
参数错误，检查命令的 --help 输出 |
network |
任意 | 网络连接问题，检查网络后重试（最多 3 次） |
部分失败降级（不要整体报错，保留已成功的部分）：
- extract 多 URL 时部分失败：返回 results（成功项）+ failed_results（失败项及原因），只报告失败的 URL，成功内容照常交付
- research 自动轮询超时（--wait_timeout）：返回 request_id，用 tavily research get <request_id> --json 后续查询，不要重复创建任务
- crawl 超时或部分页面失败：已爬取页面的结果照常返回，缺失页面不重爬（重爬会重复计费）
恢复动作必须有限且确定：所有重试不超过 3 次；重试仍失败后停止，如实向用户报告错误信息（error.message），不要无限重试。
注意事项
--json是 agent 调用时必须使用的参数，确保输出为结构化 JSONadvanced搜索/提取深度消耗 2 credits（其他模式 1 credit），成本敏感时用默认深度- 站点结构未知时优先
map（低成本发现），再对选中页面extract，避免直接crawl的高成本
