Xiaogua Tavily Search / 小瓜 Tavily 搜索

A practical Tavily search skill for OpenClaw, optimized for better ranking, cleaner output, and safer day-to-day use.

这是一个面向 OpenClaw 的实用 Tavily 搜索技能，重点优化了排序质量、输出可读性，以及日常长期使用时的稳定性与安全性。

Credential requirements / 凭据要求

Primary credential / 主要凭据

• TAVILY_API_KEY

Also supported / 其他支持方式

• --api-key
• local .secrets/tavily.key

Notes / 说明

• This skill requires a Tavily API key to run.
• The published package does not include any API key.
• For public/shared installs, prefer TAVILY_API_KEY.
• skills/xiaogua-tavily-search/.secrets/tavily.key is intended for local private setups only, and this published script does not search parent directories for secrets.

• 本技能运行时需要 Tavily API key。
• 公开发布的 skill 包不包含任何 API key。
• 对公共/共享安装场景，优先使用 TAVILY_API_KEY。
• .secrets/tavily.key 仅建议用于本地私有环境。

Key advantages / 当前版本优势

Compared with simpler public Tavily skills, this version adds:

相比更基础的公共 Tavily skill，这个版本额外做了这些增强：

• Consistent credential behavior: TAVILY_API_KEY is the primary documented credential, while --api-key and .secrets/tavily.key remain supported as secondary paths.
• 更一致的凭据策略：公开说明中已将 TAVILY_API_KEY 作为主推荐凭据，--api-key 和 .secrets/tavily.key 作为补充方式，避免用户混淆。
• Official-source preference for recognized products/topics such as OpenClaw, WSL, Ubuntu, and Tavily.
• 官方来源优先：针对 OpenClaw、WSL、Ubuntu、Tavily 等主题，会优先官方文档/官方仓库/更可信来源。
• Path-level ranking instead of domain-only ranking.
• 路径级排序：不只看域名，还会区分 /releases、/docs、/issues、/discussions 等 URL 路径质量。
• Intent-aware ranking for release notes, docs/setup, troubleshooting, and news.
• 按查询意图排序：能根据“发布说明 / 文档安装 / 故障排查 / 新闻”这几类问题调整结果排序逻辑。
• Deduplication for near-identical URLs.
• 结果去重：避免同类页面重复占据前排。
• Noisy-domain suppression for common low-signal social/content-farm results.
• 噪音站点压制：默认压低或排除 Facebook、Reddit、Pinterest、Instagram、X/Twitter、Quora 等低信噪比来源。
• Readable terminal output with source labels, host display, scores, and trimmed snippets.
• 更适合终端阅读的输出：显示来源标签、域名、分数，并对摘要做裁剪，方便快速判断结果质量。
• Windows-friendly UTF-8 output handling.
• 适配 Windows 终端编码问题：避免部分字符导致输出报错。
• Minimal dependency footprint: Python stdlib only.
• 依赖最小化：只使用 Python 标准库，便于审查和维护。

Quick start / 快速开始

1. Set TAVILY_API_KEY in your environment (recommended).
2. As alternatives, use --api-key or a local .secrets/tavily.key file for private setups.
3. Run:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "your query"

1. Use --json if you want raw structured output.

1. 推荐先在环境变量中设置 TAVILY_API_KEY。
2. 本地私有使用场景下，也可使用 --api-key 或本地 .secrets/tavily.key。
3. 运行：

python skills/xiaogua-tavily-search/scripts/tavily_search.py "your query"

1. 如需原始结构化结果，使用 --json。

Recommended usage / 推荐使用场景

Use this skill when:

在这些场景下推荐使用本技能：

• built-in web_search is rate-limited or temporarily unavailable
• you explicitly want Tavily results
• you need a cleaner ranked result list
• you care about official docs/releases/issues being surfaced earlier
• you want a deterministic script you can inspect and modify locally

• 内置 web_search 被限流或暂时不可用
• 你明确想用 Tavily 搜索
• 你希望搜索结果排序更干净
• 你希望官方文档 / 官方发布 / 官方 issue 更早浮出来
• 你希望这是一个可本地审查、可继续修改的确定性脚本

Ranking behavior / 排序逻辑

By default, the script behaves like a careful human researcher:

默认情况下，脚本会尽量模拟“认真做检索的人”的行为：

• product-specific official domains are preferred
• release/changelog queries boost release-note paths
• install/configuration queries boost documentation paths
• troubleshooting queries boost issues, FAQ, and troubleshooting pages
• GitHub community discussions rank below official docs/repo pages for factual product questions

• 产品相关问题优先官方域名
• 发布说明/更新日志类问题提升 release 路径权重
• 安装/配置类问题提升 docs/guide/configure 路径权重
• 故障排查类问题提升 issue/faq/troubleshooting 路径权重
• 对事实型产品问题，GitHub 社区讨论会排在官方文档/官方仓库之后

Disable defaults when needed:

如有需要，也可以关闭默认优化：

python skills/xiaogua-tavily-search/scripts/tavily_search.py "query" --no-official-first --no-exclude-noisy-default

Common commands / 常用命令

Basic search / 基础搜索:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "OpenClaw latest release notes"

Search with Tavily answer / 带 Tavily 综合回答:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "OpenClaw latest release notes" --include-answer

Raw JSON / 原始 JSON 输出:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "OpenClaw latest release notes" --json

Troubleshooting query / 排障查询:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "WSL localhost proxy NAT not supported fix" --include-answer

News-style query / 新闻查询:

python skills/xiaogua-tavily-search/scripts/tavily_search.py "AI infrastructure funding" --topic news --days 7 --include-answer

Security notes / 安全说明

• This published skill should not include any API key.
• Put your key in local environment variables or local .secrets files after installation.
• Do not commit or publish your real key.

• 公开发布的 skill 包本身不应包含任何 API key。
• 请在安装后于本地环境变量或本地 .secrets 文件中放置密钥。
• 不要把真实密钥提交或发布出去。

Resources / 资源

scripts/

• tavily_search.py: Tavily search wrapper with source cleanup, intent detection, path scoring, deduplication, and result labeling.
• tavily_search.py：带来源清洗、意图识别、路径级排序、去重与结果标签能力的 Tavily 搜索脚本。

��去重与结果标签能力的 Tavily 搜索脚本。