Tavily Web

为不连接外部世界的 agent 提供取数路径：广度（search/map）→ 深度（extract/crawl）→ 综合（research）。

启动方式

先把本 SKILL.md 所在目录的绝对路径保存为 Skill 目录。不得假设当前工作目录就是 Skill 目录：

TAVILY_SKILL_DIR="/absolute/path/to/installed/tavily-web"
tv() { python3 "$TAVILY_SKILL_DIR/scripts/tavily.py" "$@"; }

工具为纯 Python 标准库脚本，无第三方依赖；凭据只读 TAVILY_API_KEY 环境变量。

前置检查（每次会话首次使用必做）

1. 运行 tv check。
   • 退出码 2：TAVILY_API_KEY 未配置或为空白。只提示用户：到 https://app.tavily.com 获取 key，然后 export TAVILY_API_KEY="tvly-..."；本 Skill 不代用户写 shell 配置，也不把 key 写入任何文件。等待用户配置完成后重跑 tv check。
   • 退出码 3：key 无效或过期，提示用户核对后更换。
   • 退出码 4：网络不可达，报告并停止。
2. check 正常返回前，不执行任何数据检索。

取数路由

默认升级路径：search 发现 → extract 读全 → map+crawl 扩大面 → research 做综合。

结果组织

• 所有子命令输出 JSON；把 results 里的 url、title、published_date 等来源信息保留进最终回答，引用时给出链接。
• research 报告的正文（content）与来源列表（sources）整体呈现，不删引用；extract 失败 URL 看 failed_results。
• search 的 snippet 不足以回答时，对 top 1-2 条结果补一次 extract，不要重复 search 换关键词碰运气超过两次。

失败与降级

• 401/403：提示用户刷新 key，停止重试。
• 429：告知限流，建议稍后重试或减小 --max-results。
• 5xx：重试一次，仍失败则报告。
• 网络不可达（退出码 4）：改用用户本地已有信息作答，并明确声明数据新鲜度边界（截至 agent 训练/本地文件的时间点）。
• 任何情况下不得把 key 打印到输出、日志或文件。

验证

运行包内确定性测试（不触网）：

python3 -m unittest discover -s "$TAVILY_SKILL_DIR/tests"

版本漂移、能力探测与失败处理细则见 CLI 兼容性契约。