tavily-dynamic-search

Tavily 动态搜索

将大量原始网页内容保存在磁盘上，只返回任务所需的证据。在使用 --include-raw-content、组合多个查询或提取多个长网页时，这很有用。对于普通的 tvly search --json 可直接回答的简单查询，不要使用此工作流。

运行前

搜索和提取支持有上限的免密访问。如果 tvly 可用，请直接运行。如果缺少 tvly，请按照 tavily-cli setup 操作。首次请求前不要查找 API 密钥，也不要进行身份验证。如果在交互式会话中达到免密上限，请运行 tvly login 以打开浏览器 OAuth，然后重试一次被阻止的请求。在无人值守环境中，请报告上限及身份验证选项，不要启动交互流程。

工作流

1. 在不获取原始内容的情况下进行广泛搜索，并检查标题、URL、分数和摘要。
2. 仅获取最佳来源的完整内容。
3. 如果原始输出可能很大，请使用 -o 保存，并在将任何内容打印到模型上下文之前筛选文件。
4. 在每条提取出的事实旁保留来源 URL。

当用户将证据限制为官方域名或指定域名时，请在本地筛选期间验证每个所选 URL 的主机名。--include-domains 会缩小搜索范围，但不能证明每条返回结果都属于允许的主机。如果无法提取完整网页，请将结论标注为基于搜索摘要的证据，不要暗示已核实网页正文。

如果相关来源和筛选条件已明确，请在一个轮次中完成整个流程。只有当首次搜索改变了需要提取的内容时，才使用另一个轮次。

保存证据前，请创建一个唯一的临时任务目录，避免并发 Agent 相互覆盖。若不允许使用 mktemp，可使用 Python 的 tempfile.mkdtemp()。该任务的所有原始文件和筛选后文件都应保存在这个目录中。

小型结果：筛选直接返回的 JSON

对于较小的搜索响应，使用管道即可：

tvly search "query" --max-results 5 --json | python3 -c '
import json, sys
data = json.load(sys.stdin)
for result in data.get("results", []):
    score = result.get("score") or 0
    title = result.get("title") or ""
    print(f"[{score:.2f}] {title}")
    print(result.get("url", ""))
    print(result.get("content", "")[:300])
'

不要丢弃 stderr。身份验证失败、免密访问上限提示和 API 错误都需要采取相应措施，必须保留并显示。

大型结果：先保存，再筛选

使用 CLI 的文件输出功能，避免网页原始内容经过工具响应传递：

tvly search "query" \
  --include-raw-content markdown \
  --max-results 8 \
  --json \
  -o /tmp/tavily-search-results.json

然后只打印有限范围内的证据：

python3 -c '
import json
from pathlib import Path

data = json.loads(Path("/tmp/tavily-search-results.json").read_text())
for result in data.get("results", []):
    title = result.get("title") or ""
    url = result.get("url") or ""
    print(f"## {title}")
    print(f"URL: {url}")
    print((result.get("raw_content") or result.get("content") or "")[:1200])
    print()
'

根据问题调整筛选逻辑。如果目标信息已明确，优先提取相关段落或字段，而非固定长度的字符片段。除非确实需要更长内容来呈现表格或代码块，否则每个来源尽量控制在约 150–600 个令牌。

定向提取

搜索确定合适的 URL 后，只提取这些网页：

tvly extract "https://example.com/article" \
  --json \
  -o /tmp/tavily-extract-results.json

对于聚焦特定主题的网页，可让 Tavily 在本地筛选前缩减响应内容：

tvly extract "https://example.com/docs" \
  --query "authentication API" \
  --chunks-per-source 3 \
  --json \
  -o /tmp/tavily-extract-results.json

多个查询

进行多角度研究时，运行少量重点明确的搜索，按 URL 去重并排序后再提取。在 Python 中编排命令时，使用 subprocess.run(..., capture_output=True, text=True)。检查 returncode；如果命令失败，请显示其 stderr，并明确停止或重试。切勿使用会隐藏缺失证据的笼统 except Exception: continue。

响应结构

tvly search --json 会返回 query、可选的 answer、results 和 response_time。每条结果通常包含 url、title、content、score 和可选的 raw_content。

tvly extract --json 会返回 results、failed_results 和 response_time。每条成功的结果通常包含 url、raw_content 和可选的图片。

将字段视为可选字段，并在筛选时使用 .get()。请检查 failed_results，不要假定每个请求的 URL 都提取成功。

实用选项

选项	用途
--max-results	限制搜索结果数量；默认值为 5，最大值为 20
--depth	选择 ultra-fast、fast、basic 或 advanced
--time-range	将结果限制为 day、week、month 或 year
--include-domains	将结果限制为以逗号分隔的可信域名列表
--exclude-domains	排除以逗号分隔的域名列表
--include-raw-content	以 markdown 或 text 格式包含完整内容
-o, --output	将完整响应保存到文件

仅在无法使用 Python 时，才使用 jq 进行简短筛选：

tvly search "query" --json | jq '[.results[] | {title, url, score, content}]'