- name
- xiaogua-tavily-search
- description
- Tavily-powered live web search skill for current information, news, online research, source gathering, and fallback web search when built-in web_search is rate-limited or insufficient. Primary credential:
TAVILY_API_KEY. Also supports--api-keyand local.secrets/tavily.keyfor private setups. Use when Tavily search is explicitly desired and you want cleaner result ranking, official-source preference, path-level scoring, deduplication, noisy-domain suppression, and readable terminal output. 适用于需要实时网页搜索、新闻检索、在线研究、资料收集，或内置 web_search 限流/效果不足时作为高质量备用搜索通道的场景。主推荐凭据方式：TAVILY_API_KEY；也支持--api-key与本地.secrets/tavily.key（仅适合私有本地环境）。适合希望优先官方来源、按路径质量排序、自动去重、压制低质量噪音站点并输出更易读结果的任务。
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.keyis 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_KEYis the primary documented credential, while--api-keyand.secrets/tavily.keyremain 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 / 快速开始
- Set
TAVILY_API_KEYin your environment (recommended). - As alternatives, use
--api-keyor a local.secrets/tavily.keyfile for private setups. - Run:
python skills/xiaogua-tavily-search/scripts/tavily_search.py "your query"- Use
--jsonif you want raw structured output.
- 推荐先在环境变量中设置
TAVILY_API_KEY。 - 本地私有使用场景下，也可使用
--api-key或本地.secrets/tavily.key。 - 运行：
python skills/xiaogua-tavily-search/scripts/tavily_search.py "your query"- 如需原始结构化结果，使用
--json。
Recommended usage / 推荐使用场景
Use this skill when:
在这些场景下推荐使用本技能：
- built-in
web_searchis 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-defaultCommon 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-answerRaw JSON / 原始 JSON 输出:
python skills/xiaogua-tavily-search/scripts/tavily_search.py "OpenClaw latest release notes" --jsonTroubleshooting query / 排障查询:
python skills/xiaogua-tavily-search/scripts/tavily_search.py "WSL localhost proxy NAT not supported fix" --include-answerNews-style query / 新闻查询:
python skills/xiaogua-tavily-search/scripts/tavily_search.py "AI infrastructure funding" --topic news --days 7 --include-answerSecurity notes / 安全说明
- This published skill should not include any API key.
- Put your key in local environment variables or local
.secretsfiles 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 搜索脚本。