WorkBuddy Tavily 统一搜索

> 专为 WorkBuddy 设计的 Tavily 全功能集成。统一所有 Tavily API 入口（Search/Extract/Crawl/Map/Research），提供一致的命令行界面、结构化输出和最佳实践指南。

为什么需要这个技能

市面上已有 20+ 个 Tavily 技能，但都没有专门为 WorkBuddy 优化：
- 命名混乱：tavily/tavily-search/tavily-websearch/tavily-tool...
- 能力分散：有些只有 search，有些没有 research，有些没有 usage 查询
- 输出不一致：有些是文本，有些是 JSON，有些是混合
- 文档缺失：很多技能没有故障排查指南

本技能一次性解决所有问题：
- ✅ 统一 CLI 入口（5 大功能 + 4 个搜索子模式）
- ✅ 一致的 JSON 输出格式（便于 WorkBuddy 处理）
- ✅ 完整的 best practices 文档（pitfalls、credits、verification）
- ✅ 整合 Tavily 最新 API（5 模式 + 新闻/财经 + 引用格式）

必备配置

1. 获取 Tavily API Key

访问 https://tavily.com 注册并获取 API Key（免费 tier 提供 1000 次/月）。

2. 配置环境变量

将 API Key 设置为环境变量 TAVILY_API_KEY：

Windows PowerShell（用户级）：

[System.Environment]::SetEnvironmentVariable('TAVILY_API_KEY', 'tvly-your-key-here', 'User')

Linux/macOS：

echo 'export TAVILY_API_KEY=tvly-your-key-here' >> ~/.bashrc
source ~/.bashrc

WorkBuddy 内（通过 setup）：
将以下加入 ~/.hermes/.env：

TAVILY_API_KEY=tvly-your-key-here

⚠️ 绝对不要将 API Key 硬编码到代码或聊天记录中，参考 references/bp-api-key-management.md。

快速开始

# 1. 基础搜索
python scripts/tavily.py search --query "latest OpenAI API changes" --max-results 5

# 2. 新闻搜索（含LLM直接回答）
python scripts/tavily.py search --query "AI regulation" --topic news --include-answer basic --time-range week

# 3. 内容提取（精准抓取）
python scripts/tavily.py extract --url "https://example.com/article" --query "pricing" --format markdown

# 4. 整站爬取
python scripts/tavily.py crawl --url "https://docs.example.com" --instructions "Find API documentation" --limit 20

# 5. 深度研究（带引用）
python scripts/tavily.py research --input "Impact of AI on healthcare 2026" --model pro --citation-format numbered

# 6. 查看用量
python scripts/tavily.py usage

所有命令输出标准 JSON，便于 WorkBuddy 解析。

5 大功能详解

1. search — 网页搜索（最常用）

支持 3 种 topic：general（通用）/ news（新闻）/ finance（财经）

核心参数：
| 参数 | 默认 | 说明 |
|------|------|------|
| --query | 必填 | 搜索查询 |
| --max-results | 5 | 返回结果数（0-20） |
| --search-depth | basic | basic/advanced/fast/ultra-fast |
| --topic | general | general/news/finance |
| --time-range | — | day/week/month/year |
| --include-answer | false | false/true/basic/advanced |
| --include-raw-content | false | false/true/markdown/text |
| --include-images | false | 包含图片结果 |
| --include-domains | — | 限定域名（逗号分隔） |
| --exclude-domains | — | 排除域名（逗号分隔） |
| --country | — | 国家/地区优先（仅 general） |

示例：

# 基础搜索
python scripts/tavily.py search --query "量子计算最新进展"

# 高级搜索 + 学术域名限定
python scripts/tavily.py search --query "transformer architecture" \
  --search-depth advanced --chunks-per-source 3 \
  --include-domains arxiv.org,nature.com,openai.com

# 财经搜索
python scripts/tavily.py search --query "NVIDIA stock analysis" \
  --topic finance --time-range month --include-answer true

# 实时新闻 + 引用
python scripts/tavily.py search --query "AI safety summit 2026" \
  --topic news --time-range day --max-results 10

2. extract — 内容提取

从指定 URL 提取结构化内容，支持关键词重排。

核心参数：
| 参数 | 默认 | 说明 |
|------|------|------|
| --url / --urls | 必填 | URL（可重复或逗号分隔） |
| --query | — | 关键词重排 |
| --chunks-per-source | 3 | 每源片段数（1-5） |
| --extract-depth | basic | basic/advanced |
| --format | markdown | markdown/text |
| --timeout-seconds | — | Tavily 超时（1-60） |

示例：

# 提取单个 URL
python scripts/tavily.py extract --url "https://example.com/article"

# 批量提取 + 关键词重排
python scripts/tavily.py extract --url "https://docs.tavily.com" --url "https://example.com/docs" \
  --query "API authentication" --chunks-per-source 5 --format markdown

3. crawl — 整站爬取

从根 URL 智能遍历整个网站。

核心参数：
| 参数 | 默认 | 说明 |
|------|------|------|
| --url | 必填 | 根 URL |
| --instructions | — | 自然语言指令（如"找所有 API 文档"） |
| --max-depth | 2 | 最大链接深度 |
| --max-breadth | 10 | 每层最大页数 |
| --limit | 10 | 总页数上限 |
| --select-paths | — | 包含路径模式（逗号分隔） |
| --exclude-paths | — | 排除路径模式 |

示例：

# 基础爬取
python scripts/tavily.py crawl --url "https://docs.python.org"

# 智能爬取（自然语言指令）
python scripts/tavily.py crawl --url "https://docs.example.com" \
  --instructions "Find all API reference pages" --limit 50

# 限定路径
python scripts/tavily.py crawl --url "https://example.com" \
  --select-paths "/blog,/docs" --max-depth 3

4. map — 站点地图发现

快速发现网站所有 URL（轻量级，不抓取内容）。

示例：

# 基础 sitemap
python scripts/tavily.py map --url "https://example.com" --limit 100

5. research — 深度研究

AI 多轮研究 + 自动引用生成（异步任务，自动轮询直到完成）。

核心参数：
| 参数 | 默认 | 说明 |
|------|------|------|
| --input | 必填 | 研究问题 |
| --model | auto | mini/pro/auto |
| --citation-format | numbered | numbered/mla/apa/chicago |
| --max-wait-seconds | 180 | 最长等待时间 |
| --poll-interval-seconds | 2 | 轮询间隔 |

模型选择指南：
- mini：单主题、针对性研究（~30s）
- pro：多角度综合分析、对比研究（~60-120s）
- auto：让 API 自动选择

示例：

# 快速研究
python scripts/tavily.py research --input "What is RAG?" --model mini

# 深度行业分析
python scripts/tavily.py research --input "Fintech landscape 2026" \
  --model pro --citation-format apa --max-wait-seconds 300

# 仅创建任务，不等待
python scripts/tavily.py research --input "..." --no-wait

6. usage — 用量查询

查看 API Key 用量、剩余额度。

python scripts/tavily.py usage

返回结构：

{
  "key": {"usage": 135, "limit": 1000, "search_usage": 81, ...},
  "account": {"current_plan": "Researcher", "plan_usage": 135, ...}
}

最佳实践（来自实战经验）

1. 成本控制

• ✅ 默认使用 search-depth=basic（1 信用点），仅在需要高精度时用 advanced（2 信用点）
• ✅ 用 --max-results 5 而非 20，保持输出可控
• ✅ research 用 mini 即可满足大多数场景

2. 输出大小控制

• ❌ 不要在 search 上直接用 --include-raw-content true（输出会爆炸）
• ✅ 推荐两阶段流程：search 找 URL → extract 精准抓取
• ✅ 给 extract 加 --query 关键词重排，避免抓整页

3. 引用与可信度

• ✅ 始终返回 results[].url 作为引用源
• ✅ 用 research --citation-format 自动生成带引用的报告
• ✅ 优先用 score 排序筛选高质量结果

4. 错误处理

• 检查 request_id（失败时 Tavily 返回）用于 support 沟通
• 401 → API Key 错误；429 → 限流；5xx → Tavily 服务问题
• 详见 references/error-codes.md

5. 任务编排建议

• 简单查询 → 直接 search
• 需要原文 → search + extract
• 调研类问题 → research（含引用）
• 网站结构盘点 → map
• 批量内容抓取 → crawl

故障排查

更多细节见 references/pitfalls.md 和 references/error-codes.md。

API Key 安全

• ✅ 只从环境变量读取 TAVILY_API_KEY，不读取其他变量
• ✅ 硬编码 API base URL 为 https://api.tavily.com，防止 base URL 注入
• ✅ 拒绝意外 redirect（防止 exfiltration）
• ❌ 永远不要把 API Key 写进代码、git、聊天记录
• 🔄 建议每 90 天轮换一次 API Key

详见 references/bp-api-key-management.md。

命令速查

# 搜索
tavily search --query "..." [--topic general|news|finance] [--max-results N] [--search-depth basic|advanced] ...

# 提取
tavily extract --url "URL" [--query "..."] [--chunks-per-source N] ...

# 爬取
tavily crawl --url "URL" [--instructions "..."] [--max-depth N] [--limit N] ...

# 站点地图
tavily map --url "URL" [--max-depth N] [--limit N]

# 研究
tavily research --input "..." [--model mini|pro|auto] [--citation-format numbered|mla|apa|chicago]

# 研究查询（已创建的任务）
tavily research-get --request-id "..."

# 用量
tavily usage

Credits & Pricing

免费 tier：1000 credits/月。

版本历史

v1.0.0 (2026-07-06)

• ✨ 整合 5 大功能（Search/Extract/Crawl/Map/Research）+ Usage 查询
• ✨ 统一 CLI 入口，一致 JSON 输出
• ✨ 完整 best practices 文档
• ✨ 严格安全策略（仅读 TAVILY_API_KEY、硬编码 base URL、拒绝意外 redirect）
• ✨ 整合新闻/财经子模式、4 种引用格式、auto_parameters/exact_match 等高级参数

参考资料

• 官方 API 文档：https://docs.tavily.com/
• 完整文档索引：https://docs.tavily.com/llms.txt
• API Key 管理：references/bp-api-key-management.md
• Pitfalls：references/pitfalls.md
• 错误码：references/error-codes.md
• Search 详解：references/search.md
• Extract 详解：references/extract.md
• Research 详解：references/research.md