当网页搜索结果过大需要先落盘再过滤时，用 Tavily…

用 Tavily CLI 做程序化搜索与抽取，将大体积原始网页内容保存到磁盘并本地过滤，只返回任务所需证据。

适用场景

解决思路

1. 先做不带原始内容的宽泛搜索，检查标题、URL、分数和摘要片段。
2. 只对最佳来源抓取完整内容。
3. 当原始输出可能很大时，用 -o 保存到文件，并在打印任何内容到模型上下文之前先过滤该文件。
4. 在每条抽取出的事实旁保留来源 URL。
5. 当用户把证据限制在官方或指定域名时，在本地过滤阶段校验每个选中 URL 的主机名；--include-domains 只收窄搜索，并不保证每个返回结果都属于允许的主机。
6. 如果无法做整页抽取，就把结论标注为搜索摘要证据，而不要暗示已验证页面正文。
7. 当相关来源和过滤条件已知时，把流程保持在同一个回合内；只有当第一次搜索改变了应当抽取的内容时才使用另一个回合。
8. 在保存证据前创建一个唯一的临时任务目录，避免并发 agent 互相覆盖；当 mktemp 不被允许时可用 Python 的 tempfile.mkdtemp()；该任务的所有原始和过滤产物都复用这个目录。
9. 对小结果直接过滤 JSON 响应即可，用管道把 tvly search "query" --max-results 5 --json 的输出交给 python3 解析 results，逐条打印分数、标题、URL 和截断到 300 字符的 content。
10. 不要丢弃 stderr；认证失败、无密钥上限提示和 API 错误都是可操作信息，必须保持可见。
11. 对大结果先保存再过滤：运行 tvly search "query" --include-raw-content markdown --max-results 8 --json -o /tmp/tavily-search-results.json，让原始页面内容不经过工具响应。
12. 随后只打印有界证据：用 python3 读取该 JSON，逐条打印标题、URL 和 raw_content 或 content 截断到 1200 字符的内容。
13. 按问题调整过滤逻辑；当目标信息已知时优先提取相关段落或字段，而不是固定字符切片；每个来源大约控制在 150-600 tokens，除非表格或代码块确实需要更多。
14. 当搜索已确定正确 URL 时，只抽取这些页面：tvly extract "https://example.com/article" --json -o /tmp/tavily-extract-results.json。
15. 对主题聚焦的页面，让 Tavily 在本地过滤前先缩减响应：tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json -o /tmp/tavily-extract-results.json。
16. 多角度研究时，运行一小组聚焦搜索，按 URL 去重，并在抽取前排序。
17. 在 Python 中编排命令时使用 subprocess.run(..., capture_output=True, text=True)，检查 returncode；若命令失败，暴露其 stderr 并有意识地停止或重试；绝不要用笼统的 except Exception: continue 掩盖缺失证据。
18. 了解响应结构：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 和可选 images。
19. 过滤时把字段都当作可选并用 .get()；检查 failed_results，不要假设每个请求的 URL 都成功。
20. 按需使用选项：--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 把完整响应保存到文件。
21. 仅在 Python 不可用时用 jq 做短过滤，例如 tvly search "query" --json | jq '[.results[] | {title, url, score, content}]'。
22. 运行前：搜索和抽取支持有上限的无密钥访问，tvly 可用时直接运行；若 tvly 缺失，按 tavily-cli 的 setup 处理；首次请求前不要寻找 API key 或做认证；交互式会话中达到无密钥上限时运行 tvly login 打开浏览器 OAuth，然后重试被阻塞的请求一次；无人值守环境中报告上限和认证选项，而不要启动交互流程。

适用边界 · 注意事项

• 不要把这个工作流用于普通 tvly search --json 就能直接回答的简单查询。
• 不要在首次请求前就寻找 API key 或进行认证。
• 无人值守环境中不要启动交互式 OAuth 流程。