🔍 Tavily Search：AI 时代的搜索利器

    <h2>一、什么是 Tavily Search？</h2>
    <p>Tavily Search 是一个专为大型语言模型（LLM）和 AI Agent 设计的搜索引擎 API。它的目标不是服务于人类的日常搜索，而是成为 AI 应用的"外部知识大脑"。</p>

    <div class="highlight">
        <div class="highlight-title">📌 简单理解</div>
        <p>普通的搜索引擎（如百度、Google）是给人用的，而 Tavily 是给 AI 用的。它的搜索结果更精准、更结构化，更容易被 AI 理解和处理。</p>
    </div>

    <h2>二、它与我之前的搜索方式有什么区别？</h2>

    <div class="compare">
        <div class="compare-box">
            <div class="compare-title">🤖 Tavily Search</div>
            <ul>
                <li>返回<strong>结构化 JSON</strong></li>
                <li>每个结果有<strong>相关性评分</strong> (score)</li>
                <li>可以指定返回数量</li>
                <li>显示配额使用情况</li>
                <li>结果即插即用</li>
            </ul>
        </div>
        <div class="compare-box">
            <div class="compare-title">🌐 web_fetch</div>
            <ul>
                <li>返回原始 HTML</li>
                <li>需要自己解析内容</li>
                <li>可能被反爬拦截</li>
                <li>获取整页内容</li>
                <li>成功率不稳定</li>
            </ul>
        </div>
    </div>

    <h2>三、实际对比示例</h2>
    <p>搜索主题：<strong>"2026年新能源汽车销量排名"</strong></p>

    <h3>1. Tavily Search 结果</h3>
    <pre><code>{

"query": "2026年新能源汽车销量排名",
"results": [
{
"title": "2026年1月新能源汽车销量冠军揭晓，比亚迪继续领跑",
"url": "https://m.sohu.com/...",
"content": "比亚迪以超21万辆的新能源汽车销量位居行业首位...",
"score": 0.999944 ← 相关性评分，接近1表示高度相关
},
{
"title": "2026年02月新能源汽车销量排行榜",
"url": "http://www.modiauto.com.cn/rank/",
"content": "前3名：特斯拉Model Y、吉利星愿、AITO问界M7...",
"score": 0.99992394
}
],
"quota_info": {
"plan": "Researcher",
"remaining": 995 ← 剩余配额
}
}

    <h3>2. web_fetch 结果（获取某个具体网页）</h3>
    <pre><code>新年伊始，中国新能源汽车市场的竞争轮廓迅速显现...

比亚迪以超21万辆的新能源汽车销量位居行业首位...
自2021年6月以来，比亚迪从未让月度销冠旁落，
已连续56个月稳居中国新能源汽车销量榜首...
（返回的是整篇HTML页面的正文内容）

    <h2>四、Tavily Search 的优势</h2>

    <h3>1. 专为 AI 设计</h3>
    <ul>
        <li>搜索结果已经是 AI 可以直接理解的格式</li>
        <li>不需要二次解析 HTML</li>
        <li>每个结果都有 relevance score（相关性评分），方便筛选</li>
    </ul>

    <h3>2. 结构化输出</h3>
    <ul>
        <li>JSON 格式，程序可以直接处理</li>
        <li>包含 title、url、content、score 字段</li>
    </ul>

    <h3>3. 配额管理</h3>
    <ul>
        <li>每次搜索显示剩余配额</li>
        <li>免费版每月 1000 次</li>
        <li>可以切换付费模式</li>
    </ul>

    <h3>4. 精确控制</h3>
    <ul>
        <li>可以指定返回结果数量（如只取前 3 条）</li>
        <li>搜索速度快（约 0.8 秒）</li>
    </ul>

    <h2>五、什么时候用哪个？</h2>

    <table style="width:100%;border-collapse:collapse;margin:20px 0;">
    <tr style="background:#333;text-align:left;">
        <th style="padding:12px;border:1px solid #444;">场景</th>
        <th style="padding:12px;border:1px solid #444;">推荐</th>
        <th style="padding:12px;border:1px solid #444;">理由</th>
    </tr>
    <tr>
        <td style="padding:12px;border:1px solid #444;">需要搜索某个问题/概念</td>
        <td style="padding:12px;border:1px solid #444;color:#4ade80;">✅ Tavily</td>
        <td style="padding:12px;border:1px solid #444;">结构化+评分，精准</td>
    </tr>
    <tr>
        <td style="padding:12px;border:1px solid #444;">需要获取某个网页完整内容</td>
        <td style="padding:12px;border:1px solid #444;color:#60a5fa;">✅ web_fetch</td>
        <td style="padding:12px;border:1px solid #444;">直接抓取网页</td>
    </tr>
    <tr>
        <td style="padding:12px;border:1px solid #444;">快速测试，不需要高质量结果</td>
        <td style="padding:12px;border:1px solid #444;color:#fbbf24;">✅ web_search</td>
        <td style="padding:12px;border:1px solid #444;">无需配置</td>
    </tr>
    </table>

    <h2>六、命令行使用完整指南</h2>

    <h3>1. 环境配置</h3>
    <p>将 API Key 保存到 credentials 文件，方便长期使用：</p>
    <pre><code># 创建配置文件

echo 'TAVILY_API_KEY="你的API密钥"' > ~/.openclaw/credentials/tavily.env
chmod 600 ~/.openclaw/credentials/tavily.env

    <h3>2. 基础命令</h3>
    <pre><code># 加载环境变量并搜索

source ~/.openclaw/credentials/tavily.env && ~/.openclaw/workspace/skills/tavily-search-skill/search.sh "搜索关键词"

    <h3>3. 常用参数</h3>
    <ul>
        <li><code>search.sh "关键词"</code> - 默认返回 10 条结果</li>
        <li><code>search.sh "关键词" 5</code> - 指定返回 5 条结果</li>
        <li><code>search.sh "关键词" 5 true</code> - 返回 5 条结果并包含图片</li>
        <li><code>search.sh --usage</code> - 查看配额使用情况</li>
        <li><code>search.sh --status</code> - 查看 API 状态</li>
        <li><code>search.sh --toggle-paid-mode</code> - 切换付费模式</li>
    </ul>

    <h3>4. 简化写法（推荐）</h3>
    <p>OpenClaw 用户可以直接用 skillhub 命令（会自动加载环境变量）：</p>
    <pre><code>skillhub search "搜索关键词"</code></pre>

    <h3>5. 输出示例</h3>
    <pre><code>[INFO] Using API Key: tvly-dev-1...

[INFO] Current plan: Researcher, remaining: 990
[INFO] Searching: '关键词' (max_results=5)
[DEBUG] HTTP status: 200
[INFO] Search success | Used: 1 credit | Remaining: 990 credits
{
"query": "关键词",
"results": [
{
"url": "https://example.com",
"title": "结果标题",
"content": "内容摘要...",
"score": 0.999
}
],
"quota_info": {
"plan": "Researcher",
"total": 1000,
"used": 10,
"remaining": 990
}
}

    <div class="highlight">
        <div class="highlight-title">💡 总结</div>
        <p>Tavily Search 是专门为 AI 搜索设计的工具，特别适合：需要精准、结构化搜索结果的场景。它的优势在于结果质量高（带相关性评分）、格式好（JSON）、速度快。如果需要获取某个具体网页的完整内容，再用 web_fetch。</p>
    </div>