{"id":"2121fe46-b421-4e7e-9081-b0ca8df271ff","entityType":"agent","slug":"clawhub-brucetangc-tavily-web-search-full","name":"Tavily Web Search","canonicalUrl":"https://www.xpersona.co/agent/clawhub-brucetangc-tavily-web-search-full","canonicalPath":"/agent/clawhub-brucetangc-tavily-web-search-full","generatedAt":"2026-10-10T06:44:21.480Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":null},"description":"Full-featured Tavily web search with auto-update. All official API parameters supported. AI-optimized search for agents and RAG workflows.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17c86x64fn6cy26y1t8rwnn4983f35d:tavily-web-search-full","sourceUrl":"https://clawhub.ai/brucetangc/tavily-web-search-full","homepage":"https://clawhub.ai/brucetangc/skills/tavily-web-search-full","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/brucetangc/tavily-web-search-full","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/brucetangc/skills/tavily-web-search-full","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Tavily Web Search technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":null},"stars":null,"forks":null,"downloads":1824,"packageName":null,"latestVersion":"2.0.6","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T00:52:17.899Z","lastCrawledAt":"2026-10-10T00:52:17.899Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T00:52:17.899Z","lastVerifiedAt":null,"highlights":[{"version":"2.0.6","createdAt":"2026-03-22T14:56:36.782Z","changelog":"v2.0.6: Fixed metadata declarations (network access) + Security scan improvements","fileCount":16,"zipByteSize":48542},{"version":"2.0.5","createdAt":"2026-03-22T13:31:33.335Z","changelog":"v2.0.5: Fix extract.py rate_limit import + Stability improvements","fileCount":15,"zipByteSize":47719},{"version":"2.0.4","createdAt":"2026-03-22T00:36:28.615Z","changelog":"Fix metadata: correctly declare TAVILY_API_KEY requirement in _meta.json","fileCount":15,"zipByteSize":47663},{"version":"2.0.3","createdAt":"2026-03-22T00:13:23.101Z","changelog":"Revert unified search integration, keep Tavily and SearXNG as separate tools","fileCount":15,"zipByteSize":47653},{"version":"2.1.0","createdAt":"2026-03-22T00:08:47.031Z","changelog":"- Added new unified search script: scripts/unified_search.py - Version bump to 2.1.0 - No changes to documentation or existing code logic besides the new script addition","fileCount":16,"zipByteSize":50308},{"version":"2.0.2","createdAt":"2026-03-21T23:57:14.258Z","changelog":"tavily-web-search-full 2.0.2 - Enhanced error handling and parameter validation in scripts/search.py. - Updated documentation in SKILL.md to add best practices, clarify usage notes, and improve formatting. - Minor metadata or configuration updates in _meta.json to reflect latest changes.","fileCount":15,"zipByteSize":47653},{"version":"2.0.1","createdAt":"2026-03-21T23:49:05.289Z","changelog":"**Introduced built-in rate limit handling for all API commands** - Added centralized rate limit logic (`scripts/rate_limit.py`) and documentation (`RATE_LIMIT.md`) - Updated `extract.py`, `search.py`, and `update.py` to support automatic rate limit checks and pause/retry behavior - Included release notes (`RELEASE_NOTES.md`) - Provides better API stability and automatic waiting when credits or QPS are exceeded","fileCount":15,"zipByteSize":47071},{"version":"2.0.0","createdAt":"2026-03-21T23:36:27.124Z","changelog":"**2.0.0 is a major update adding API coverage & safety controls:** - Added support for Tavily Crawl, Map, and Research APIs with new script entry points. - Introduced strong safety controls: Crawl, Map, and Research APIs are disabled by default and require explicit enable flags to prevent accidental credit loss. - Added new scripts: `crawl.py`, `map.py`, `research.py`, and test runner `test_all.py`. - Major documentation revisions reflecting all API endpoints, credit costs, usage limits, and new security measures. - Updated metadata and version info.","fileCount":12,"zipByteSize":40409}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17c86x64fn6cy26y1t8rwnn4983f35d:tavily-web-search-full","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17c86x64fn6cy26y1t8rwnn4983f35d:tavily-web-search-full` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/brucetangc/tavily-web-search-full before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:44:21.478Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brucetangc-tavily-web-search-full/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":null},"readme":"Skill: Tavily Web Search\n\nOwner: brucetangc\n\nSummary: Full-featured Tavily web search with auto-update. All official API parameters supported. AI-optimized search for agents and RAG workflows.\n\nTags: latest:2.0.6\n\nVersion history:\n\nv2.0.6 | 2026-03-22T14:56:36.782Z | user\n\nv2.0.6: Fixed metadata declarations (network access) + Security scan improvements\n\nv2.0.5 | 2026-03-22T13:31:33.335Z | user\n\nv2.0.5: Fix extract.py rate_limit import + Stability improvements\n\nv2.0.4 | 2026-03-22T00:36:28.615Z | user\n\nFix metadata: correctly declare TAVILY_API_KEY requirement in _meta.json\n\nv2.0.3 | 2026-03-22T00:13:23.101Z | user\n\nRevert unified search integration, keep Tavily and SearXNG as separate tools\n\nv2.1.0 | 2026-03-22T00:08:47.031Z | auto\n\n- Added new unified search script: scripts/unified_search.py\n- Version bump to 2.1.0\n- No changes to documentation or existing code logic besides the new script addition\n\nv2.0.2 | 2026-03-21T23:57:14.258Z | auto\n\ntavily-web-search-full 2.0.2\n\n- Enhanced error handling and parameter validation in scripts/search.py.\n- Updated documentation in SKILL.md to add best practices, clarify usage notes, and improve formatting.\n- Minor metadata or configuration updates in _meta.json to reflect latest changes.\n\nv2.0.1 | 2026-03-21T23:49:05.289Z | auto\n\n**Introduced built-in rate limit handling for all API commands**\n\n- Added centralized rate limit logic (`scripts/rate_limit.py`) and documentation (`RATE_LIMIT.md`)\n- Updated `extract.py`, `search.py`, and `update.py` to support automatic rate limit checks and pause/retry behavior\n- Included release notes (`RELEASE_NOTES.md`)\n- Provides better API stability and automatic waiting when credits or QPS are exceeded\n\nv2.0.0 | 2026-03-21T23:36:27.124Z | auto\n\n**2.0.0 is a major update adding API coverage & safety controls:**\n\n- Added support for Tavily Crawl, Map, and Research APIs with new script entry points.\n- Introduced strong safety controls: Crawl, Map, and Research APIs are disabled by default and require explicit enable flags to prevent accidental credit loss.\n- Added new scripts: `crawl.py`, `map.py`, `research.py`, and test runner `test_all.py`.\n- Major documentation revisions reflecting all API endpoints, credit costs, usage limits, and new security measures.\n- Updated metadata and version info.\n\nv1.1.0 | 2026-03-21T23:24:53.686Z | auto\n\n**Expanded from search-only to a full Tavily toolkit with new Extract and Usage API support.**\n\n- Added Extract API: extract and analyze content from URLs (scripts/extract.py).\n- Added Usage API: check and report Tavily credit usage (scripts/usage.py).\n- Documentation and Skill metadata updated to reflect new APIs and expanded features.\n- File/folder structure updated for separate search, extract, and usage logs/caches.\n- README and SKILL.md now include examples and usage instructions for all three APIs.\n\nv1.0.1 | 2026-03-21T22:54:24.032Z | auto\n\nTavily Web Search v1.0.1\n\n- Initial release with comprehensive Tavily web search features for AI agents and RAG workflows.\n- Supports all official Tavily API parameters, including search depth, topic, date range, domain filtering, country targeting, AI answers, and image search.\n- Includes features like auto-retry, 1-hour query caching, detailed logging, multiple output formats, and automatic API updates.\n- Command-line usage examples, installation and API key setup instructions provided.\n- Documentation fully updated with troubleshooting and reference links.\n\nArchive index:\n\nArchive v2.0.6: 16 files, 48542 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (13043b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (6178b), skill-card.md (3082b), SKILL.md (15109b)\n\nFile v2.0.6:SKILL.md\n\n---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.3\nmetadata: {\n  \"clawdbot\": {\n    \"emoji\": \"🔍\",\n    \"requires\": {\n      \"bins\": [\"python3\"],\n      \"env\": [\"TAVILY_API_KEY\"]\n    },\n    \"primaryEnv\": \"TAVILY_API_KEY\"\n  }\n}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\"\n```\n\n### 🕷️ Crawl API（网站爬取）⚠️ 默认禁用\n\n**成本**: 3-5 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20\n```\n\n### 🗺️ Map API（网站地图）⚠️ 默认禁用\n\n**成本**: 1-2 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 生成网站地图\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --instructions \"find all blog posts\"\n\n# 输出 URL 列表\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n### 📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用\n\n**成本**: 4-250 信用/次 | **必须使用 `--enable --confirm`**\n\n```bash\n# 深度研究（必须使用 --enable AND --confirm）\npython3 {baseDir}/scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型（更贵但质量更高）\npython3 {baseDir}/scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 新闻搜索\n```bash\n# 今日新闻\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 本周财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --topic finance --time-range week\n\n# 指定日期范围\npython3 {baseDir}/scripts/search.py --query \"election results\" --start-date 2025-01-01 --end-date 2025-01-31\n```\n\n### 深度研究\n```bash\n# 高级模式（最高相关性，2 信用/次）\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 包含完整页面内容\npython3 {baseDir}/scripts/search.py --query \"React best practices\" --include-raw-content markdown\n\n# 详细 AI 答案\npython3 {baseDir}/scripts/search.py --query \"climate change impact\" --answer-type advanced\n```\n\n### 域名过滤\n```bash\n# 只搜索特定网站\npython3 {baseDir}/scripts/search.py --query \"JavaScript tips\" --include-domains \"github.com,dev.to,medium.com\"\n\n# 排除某些网站\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\" --exclude-domains \"w3schools.com\"\n\n# 组合使用\npython3 {baseDir}/scripts/search.py --query \"Rust programming\" --include-domains \"rust-lang.org,docs.rs\" --exclude-domains \"reddit.com\"\n```\n\n### 国家/地区定向\n```bash\n# 美国科技新闻\npython3 {baseDir}/scripts/search.py --query \"tech startups\" --country \"united states\" --topic news\n\n# 中国财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --country \"china\" --topic finance\n```\n\n### 图片搜索\n```bash\n# 搜索图片\npython3 {baseDir}/scripts/search.py --query \"sunset photography\" --include-images\n\n# 带描述\npython3 {baseDir}/scripts/search.py --query \"machine learning\" --include-images --include-image-descriptions\n```\n\n### 快速搜索（低延迟）\n```bash\n# 快速模式（1 信用，低延迟）\npython3 {baseDir}/scripts/search.py --query \"weather today\" --search-depth fast\n\n# 超快速（1 信用，最低延迟）\npython3 {baseDir}/scripts/search.py --query \"stock price\" --search-depth ultra-fast\n```\n\n### 自动参数\n```bash\n# 让 Tavily 自动配置（可能使用 advanced=2 信用）\npython3 {baseDir}/scripts/search.py --query \"comprehensive analysis of AI trends\" --auto-parameters\n\n# 自动参数但手动控制深度（控制成本）\npython3 {baseDir}/scripts/search.py --query \"research query\" --auto-parameters --search-depth basic\n```\n\n### 精确匹配\n```bash\n# 精确搜索人名/公司名\npython3 {baseDir}/scripts/search.py --query '\"John Smith\" CEO Acme Corp' --exact-match\n```\n\n## 📋 完整参数说明\n\n```bash\npython3 {baseDir}/scripts/search.py --help\n```\n\n### 必需参数\n| 参数 | 说明 |\n|------|------|\n| `--query` | 搜索关键词（建议 <400 字符） |\n\n### 搜索深度\n| 参数值 | 延迟 | 相关性 | 内容类型 | 信用 |\n|--------|------|--------|----------|------|\n| `ultra-fast` | 最低 | 较低 | NLP 摘要 | 1 |\n| `fast` | 低 | 良好 | 相关片段 | 1 |\n| `basic` | 中等 | 高 | NLP 摘要 | 1 |\n| `advanced` | 较高 | 最高 | 相关片段 | 2 |\n\n## 💡 最佳实践\n\n### 查询优化\n- ✅ **保持查询简洁** - 建议 <400 字符\n- ✅ **复杂查询拆分** - 分成多个小查询\n- ✅ **使用精确匹配** - 人名/公司名用 `--exact-match`\n- ✅ **合理设置 max-results** - 3-5 个足够（默认 5）\n\n### 搜索深度选择\n- `basic` - 日常搜索（推荐）\n- `advanced` - 深度研究（特定问题）\n- `fast` / `ultra-fast` - 实时应用\n\n### 结果过滤\n```bash\n# 按相关性分数过滤\npython3 scripts/search.py --query \"Python\" --min-score 0.7\n\n# 只搜索特定域名\npython3 scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n\n# 排除低质量站点\npython3 scripts/search.py --query \"AI\" --exclude-domains \"content-farm.com\"\n```\n\n### 成本优化\n- ⚠️ **auto_parameters 可能使用 advanced**（2 信用）\n- ✅ 手动设置 `--search-depth basic` 控制成本\n- ✅ 使用缓存（默认开启）\n- ✅ 批量提取 URL（5 个 URL = 1 信用）\n\n## 💰 API 信用说明\n\n### 日常 API（推荐）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Search** | basic/fast/ultra-fast | 1/次 | 1,000 次 |\n| **Search** | advanced | 2/次 | 500 次 |\n| **Extract** | basic | 1/5 URL | 5,000 URL |\n| **Extract** | advanced | 2/5 URL | 2,500 URL |\n| **Usage** | 查询 | 免费 | 无限 |\n\n### 高级 API（默认禁用 ⚠️）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Map** | 标准 | 1/10 页 | ~10,000 页 |\n| **Map** | 带指令 | 2/10 页 | ~5,000 页 |\n| **Crawl** | basic | ~3/10 页 | ~3,300 页 |\n| **Crawl** | advanced | ~5/10 页 | ~2,000 页 |\n\n### 研究 API（极度昂贵 ⚠️⚠️）\n\n| API | 模型 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Research** | mini | 4-110/次 | 9-250 次 |\n| **Research** | pro | 15-250/次 | 4-66 次 |\n\n**免费额度**: 1000 信用/月\n\n### 安全控制\n\n| API | 默认状态 | 启用方式 |\n|-----|---------|---------|\n| Search | ✅ 启用 | 直接使用 |\n| Extract | ✅ 启用 | 直接使用 |\n| Usage | ✅ 启用 | 直接使用 |\n| Map | ❌ 禁用 | `--enable` |\n| Crawl | ❌ 禁用 | `--enable` |\n| Research | ❌ 禁用 | `--enable --confirm` |\n\n### 节省信用技巧\n1. 日常使用 Search/Extract/Usage\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n5. 批量提取 URL（5 个 URL = 1 信用）\n6. **谨慎使用 Crawl/Map/Research**\n\n### 主题分类\n- `general` - 通用搜索（默认）\n- `news` - 新闻（包含 `published_date`）\n- `finance` - 财经\n\n### 时间过滤\n- `--time-range`: `day` / `week` / `month` / `year`\n- `--start-date`: YYYY-MM-DD\n- `--end-date`: YYYY-MM-DD\n\n### 输出格式\n- `compact` - 简洁 Markdown（默认）\n- `md` - 详细 Markdown（包含分数、完整内容）\n- `brave` - JSON（兼容 web_search 格式）\n- `raw` - 原始 JSON（包含所有字段）\n\n## 💰 API 信用说明\n\n| 操作 | 信用消耗 |\n|------|----------|\n| basic/fast/ultra-fast 搜索 | 1 |\n| advanced 搜索 | 2 |\n| include_answer (advanced) | +1 |\n| include_raw_content | +1 |\n| include_images | +1 |\n\n**免费额度**: 1000 信用/月\n\n### 节省信用技巧\n1. 使用 `basic` 深度进行日常搜索\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n\n## 🔄 自动更新\n\nTavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。\n\n### 手动检查更新\n```bash\n# 检查是否有更新\npython3 {baseDir}/scripts/update.py --check-only\n\n# 应用更新\npython3 {baseDir}/scripts/update.py\n\n# 强制更新（即使无变更）\npython3 {baseDir}/scripts/update.py --force\n\n# 查看状态\npython3 {baseDir}/scripts/update.py --status\n```\n\n### 自动更新（推荐）\n添加每周检查的 cron 任务：\n```bash\n# 编辑 crontab\ncrontab -e\n\n# 添加每周日 9:00 检查更新\n0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1\n```\n\n### 更新日志\n- 更新记录：`{baseDir}/update.log`\n- 最后检查：`{baseDir}/.last_check`\n- 版本信息：`{baseDir}/_meta.json`\n\n## 📁 文件位置\n\n```\n~/.openclaw/\n├── .env                          # API key 配置\n├── cache/tavily/                 # 缓存目录\n│   ├── search/                   # Search 缓存\n│   ├── extract/                  # Extract 缓存\n│   ├── crawl/                    # Crawl 缓存\n│   ├── map/                      # Map 缓存\n│   └── research/                 # Research 缓存\n├── logs/\n│   ├── tavily.log                # Search 日志\n│   ├── tavily_extract.log        # Extract 日志\n│   ├── tavily_usage.log          # Usage 日志\n│   ├── tavily_crawl.log          # Crawl 日志\n│   ├── tavily_map.log            # Map 日志\n│   └── tavily_research.log       # Research 日志\n└── workspace/skills/tavily-web-search/\n    ├── SKILL.md                  # 本文档\n    ├── README.md                 # 快速开始\n    ├── CHANGELOG.md              # 更新日志\n    ├── _meta.json                # 版本信息\n    ├── update.log                # 更新日志\n    ├── .last_check               # 最后检查记录\n    └── scripts/\n        ├── search.py             # Search API（搜索）✅ 默认启用\n        ├── extract.py            # Extract API（URL 提取）✅ 默认启用\n        ├── usage.py              # Usage API（使用量查询）✅ 默认启用\n        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用\n        ├── map.py                # Map API（网站地图）❌ 默认禁用\n        ├── research.py           # Research API（深度研究）❌ 默认禁用\n        ├── update.py             # 自动更新脚本\n        └── test_all.py           # 测试套件\n```\n\n## 🔧 故障排除\n\n### \"Missing TAVILY_API_KEY\"\n```bash\n# 检查配置\ncat ~/.openclaw/.env | grep TAVILY\n\n# 或设置环境变量\nexport TAVILY_API_KEY=\"tvly-xxx\"\n```\n\n### \"Search failed after 3 attempts\"\n- 检查网络连接\n- 查看日志：`tail -f ~/.openclaw/logs/tavily.log`\n- 验证 API key: https://app.tavily.com/home\n\n### 清除缓存\n```bash\nrm -rf ~/.openclaw/cache/tavily/*\n```\n\n### 禁用缓存\n```bash\npython3 {baseDir}/scripts/search.py --query \"test\" --no-cache\n```\n\n## 📚 参考链接\n\n- 官方文档：https://docs.tavily.com\n- API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search\n- 最佳实践：https://docs.tavily.com/documentation/best-practices/best-practices-search\n- 管理平台：https://app.tavily.com\n\nFile v2.0.6:README.md\n\n# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com\n\nFile v2.0.6:_meta.json\n\n{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.0.6\",\n  \"publishedAt\": 1774191396782\n}\n\nFile v2.0.6:CHANGELOG.md\n\n# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n- ✅ SKILL.md - 添加 Extract 和 Usage 完整文档\n- ✅ README.md - 更新使用示例\n- ✅ _meta.json - 版本更新到 1.1.0\n\n---\n\n## 📊 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 |\n|-----|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 |\n| Crawl | `/crawl` | ❌ | - | 3-5 信用/10 页 |\n| Map | `/map` | ❌ | - | 1-2 信用/10 页 |\n| Research | `/research` | ❌ | - | 4-250 信用/次 |\n\n---\n\n## 💰 成本对比\n\n### 免费额度（1000 信用/月）能做：\n\n| 操作 | 次数 |\n|------|------|\n| Search (basic) | 1,000 次 |\n| Search (advanced) | 500 次 |\n| Extract (basic) | 5,000 个 URL |\n| Extract (advanced) | 2,500 个 URL |\n| Usage | 无限次 |\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md                  # 完整文档\n├── README.md                 # 快速开始\n├── _meta.json                # 版本信息 (v1.1.0)\n├── CHANGELOG.md              # 本文件\n├── update.log                # 更新日志\n├── .last_check               # 最后检查记录\n└── scripts/\n    ├── search.py             # Search API (592 行)\n    ├── extract.py            # Extract API (464 行)\n    ├── usage.py              # Usage API (307 行)\n    ├── update.py             # 自动更新 (315 行)\n    └── test_all.py           # 测试套件 (120 行)\n```\n\n**总代码量**: ~1,800 行\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py --quick\n\n📍 Testing Search API...\n✅ PASS - search.py --query \"Python tutorial\"\n✅ PASS - search.py --query \"AI news\" --topic news\n✅ PASS - search.py --query \"Python\" --include-domains python.org\n✅ PASS - search.py --query \"test\" --format raw\n\n📊 TEST SUMMARY\nPassed: 4/4\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n# 发布 v1.1.0\nclawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 1.1.0\n\n# 输出\n✔ OK. Published tavily-web-search-full@1.1.0\n```\n\n---\n\n## 📈 使用统计\n\n### 典型工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n# 输出：Used: 150 | Remaining: 850 | Total: 1,000\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"AI trends 2026\" --max-results 5\n\n# 3. 提取感兴趣的文章\npython3 scripts/extract.py --urls \"https://example.com/article1,https://example.com/article2\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n# 输出：Used: 151 | Remaining: 849 | Total: 1,000\n```\n\n---\n\n## 🎯 下一步计划\n\n### 可选扩展\n- [ ] Crawl API（网站爬取）\n- [ ] Map API（网站地图）\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 结果评分过滤\n\n### 优化建议\n- [x] ✅ 添加 Extract API\n- [x] ✅ 添加 Usage API\n- [x] ✅ 完整测试套件\n- [ ] 性能基准测试\n- [ ] 更多输出格式模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n\n---\n\n**版本**: 1.1.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT\n\nFile v2.0.6:RATE_LIMIT.md\n\n# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] Success: 5 results\n```\n\n### 遇到 Rate Limit\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[INFO] Success: 5 results\n```\n\n### 超过限制\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[WARN] Rate limited. Waiting 4.0s before retry...\n[DEBUG] Request attempt 3/3: test...\n[ERROR] All 3 retries failed: Rate limit exceeded\n```\n\n## 🎯 最佳实践\n\n### 1. 批量请求时的延迟\n\n```python\n# ❌ 不好 - 快速连续请求\nfor query in queries:\n    search(query)\n\n# ✅ 好 - 添加延迟\nimport time\nfor query in queries:\n    search(query)\n    time.sleep(0.5)  # 每秒 2 个请求\n```\n\n### 2. 监控使用量\n\n```bash\n# 定期检查使用量\npython3 scripts/usage.py\n```\n\n### 3. 使用缓存\n\n```bash\n# 启用缓存（默认开启）\npython3 scripts/search.py --query \"test\"\n\n# 强制刷新（禁用缓存）\npython3 scripts/search.py --query \"test\" --no-cache\n```\n\n### 4. 了解限制\n\n- **Development Key**: 100 RPM = 每秒~1.6 个请求\n- **Production Key**: 1,000 RPM = 每秒~16 个请求\n\n## 📚 相关文件\n\n- `scripts/rate_limit.py` - Rate Limit 处理器\n- `scripts/search.py` - 已集成\n- `scripts/extract.py` - 已集成\n- https://docs.tavily.com/documentation/rate-limits.md - 官方文档\n\n## 🔄 后续更新\n\n待更新的脚本：\n- [ ] `crawl.py`\n- [ ] `map.py`\n- [ ] `research.py`\n- [ ] `usage.py`\n\n更新方法：\n```python\n# 1. 添加导入\nfrom rate_limit import rate_limit_handler\n\n# 2. 添加装饰器\n@rate_limit_handler(max_retries=MAX_RETRIES, base_delay=RETRY_DELAY, log_func=log)\ndef api_function():\n    # ...\n```\n\n---\n\n**版本**: 1.0.0  \n**更新日期**: 2026-03-22  \n**基于**: Tavily Rate Limits 官方文档\n\nFile v2.0.6:RELEASE_NOTES.md\n\n# Tavily Web Search Skill - v2.0.0 发布总结\n\n## 🎉 重大更新\n\n版本 2.0.0 实现了 Tavily **全部 6 个官方 API**，并引入了智能安全控制机制。\n\n---\n\n## 📦 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 | 默认 |\n|-----|------|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 | ✅ 启用 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL | ✅ 启用 |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 | ✅ 启用 |\n| **Crawl** | `/crawl` | ✅ 100% | `crawl.py` | 3-5 信用/10 页 | ❌ 禁用 |\n| **Map** | `/map` | ✅ 100% | `map.py` | 1-2 信用/10 页 | ❌ 禁用 |\n| **Research** | `/research` | ✅ 100% | `research.py` | 4-250 信用/次 | ❌ 禁用 |\n\n**总代码量**: ~3,500 行\n\n---\n\n## 🔒 安全控制机制\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n### 实现方式\n\n| API | 安全级别 | 启用方式 | 警告信息 |\n|-----|---------|---------|---------|\n| Search | ✅ 无 | 直接使用 | 无 |\n| Extract | ✅ 无 | 直接使用 | 无 |\n| Usage | ✅ 无 | 直接使用 | 无 |\n| Crawl | ⚠️ 中等 | `--enable` | 成本警告 |\n| Map | ⚠️ 中等 | `--enable` | 成本警告 |\n| Research | ⚠️⚠️ 高 | `--enable --confirm` | 强烈警告 |\n\n### 代码示例\n\n```python\n# Crawl API - 单标志确认\nif not args.enable:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable to proceed\", file=sys.stderr)\n    sys.exit(1)\n\n# Research API - 双重确认\nif not args.enable or not args.confirm:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable AND --confirm\", file=sys.stderr)\n    sys.exit(1)\n```\n\n---\n\n## 📊 成本对比\n\n### 免费额度（1000 信用/月）\n\n| API | 使用次数 |\n|-----|---------|\n| Search (basic) | 1,000 次 |\n| Extract (basic) | 5,000 URL |\n| Usage | 无限 |\n| Map | 5,000-10,000 页 |\n| Crawl | 2,000-3,300 页 |\n| Research (mini) | 9-250 次 |\n| Research (pro) | 4-66 次 |\n\n### 典型使用场景\n\n#### 日常开发（推荐）\n```bash\n# 搜索文档\npython3 scripts/search.py --query \"Python async tutorial\"\n\n# 提取文章内容\npython3 scripts/extract.py --urls \"https://realpython.com/article\"\n\n# 查看使用量\npython3 scripts/usage.py\n```\n\n**成本**: ~2-3 信用\n\n#### 网站分析（偶尔）\n```bash\n# 生成网站地图\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 爬取特定内容\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find pricing\"\n```\n\n**成本**: ~10-20 信用\n\n#### 深度研究（谨慎）\n```bash\n# 市场分析报告\npython3 scripts/research.py --query \"AI market 2026\" --enable --confirm\n```\n\n**成本**: 50-150 信用\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py\n\n📍 Testing Search API...\n✅ PASS (4 tests)\n\n📄 Testing Extract API...\n✅ PASS (4 tests)\n\n📊 Testing Usage API...\n✅ PASS (3 tests)\n\n🔒 Testing safety controls...\n✅ PASS (4 tests - all correctly disabled)\n\n============================================================\n📊 TEST SUMMARY\n============================================================\nPassed: 15/15\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md (15KB)         # 完整文档\n├── README.md (2.5KB)       # 快速开始\n├── CHANGELOG.md (8KB)      # 更新日志\n├── RELEASE_NOTES.md        # 本文件\n├── _meta.json              # v2.0.0 + 安全配置\n└── scripts/\n    ├── search.py (592 行)   # Search API ✅\n    ├── extract.py (464 行)  # Extract API ✅\n    ├── usage.py (307 行)    # Usage API ✅\n    ├── crawl.py (532 行)    # Crawl API ❌ (--enable)\n    ├── map.py (467 行)      # Map API ❌ (--enable)\n    ├── research.py (481 行) # Research API ❌ (--enable --confirm)\n    ├── update.py (315 行)   # 自动更新\n    └── test_all.py (180 行) # 测试套件\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n$ clawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 2.0.0\n\n- Preparing tavily-web-search-full@2.0.0\n✔ OK. Published tavily-web-search-full@2.0.0 (k9737e5bh0ac5td2ag6yvcsjm183bfyk)\n```\n\n- **ClawHub Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **状态**: ✅ 已发布\n\n---\n\n## 📈 使用建议\n\n### ✅ 推荐工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"your topic\" --max-results 5\n\n# 3. 提取感兴趣的内容\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 何时使用高级 API\n\n**使用 Crawl 当：**\n- 需要爬取整个网站\n- Search API 找不到足够信息\n- 有明确的爬取目标\n\n**使用 Map 当：**\n- 需要完整的网站地图\n- 准备批量处理网站页面\n- 需要了解网站结构\n\n**使用 Research 当：**\n- 需要深度分析报告\n- 预算充足（>100 信用）\n- Search API 无法满足需求\n\n### ❌ 避免的陷阱\n\n1. **不要随意使用 Research** - 几次就用光月度额度\n2. **Crawl 时设置 limit** - 避免爬取过多页面\n3. **始终先检查 usage** - 了解剩余额度\n\n---\n\n## 🎯 下一步计划\n\n### 已完成\n- ✅ 全部 6 个官方 API\n- ✅ 智能安全控制\n- ✅ 完整测试套件\n- ✅ 自动更新功能\n- ✅ 详细文档\n\n### 可选扩展\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 批量处理脚本\n- [ ] 结果评分过滤\n- [ ] 更多输出模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n- **最佳实践**: https://docs.tavily.com/documentation/best-practices\n\n---\n\n## 💡 关键决策\n\n### 为什么默认禁用 Crawl/Map/Research？\n\n1. **成本考虑**\n   - Research 单次最高 250 信用（1/4 月度额度）\n   - 新手可能无意中快速消耗信用\n\n2. **使用频率**\n   - 90% 场景 Search+Extract 足够\n   - Crawl/Map/Research 是特殊需求\n\n3. **用户体验**\n   - 默认启用可能导致意外消费\n   - 明确确认避免误用\n\n### 为什么 Research 需要双重确认？\n\n- **极端成本**: 4-250 信用/次\n- **不可逆**: 一旦开始无法取消\n- **替代方案**: Search API 通常够用\n- **教育意义**: 让用户三思而后行\n\n---\n\n**版本**: 2.0.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT  \n**测试通过率**: 100% (15/15)\n\nFile v2.0.6:skill-card.md\n\n## Description:\n\nComplete Tavily toolkit for Search, Extract, Usage, Crawl, Map, and Research APIs with safety controls.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[brucetangc](https://clawhub.ai/user/brucetangc)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent builders use this skill to give agents Tavily-backed web search, URL extraction, usage reporting, site crawl/map, and research workflows. It is suited for RAG, research, and documentation lookup tasks that can safely send queries and URLs to Tavily.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Tavily receives submitted queries, URLs, and research tasks.\n\nMitigation: Avoid sending confidential prompts or sensitive URLs unless the Tavily account and data handling posture are acceptable for the task.\n\nRisk: The Tavily API key can be exposed through plaintext configuration or terminal output.\n\nMitigation: Prefer a protected environment variable, restrict local access to configuration files, and avoid printing real keys in logs or shell history.\n\nRisk: Cached responses and logs may retain sensitive search or extraction content.\n\nMitigation: Use no-cache modes for confidential work and periodically review or clear local cache and log directories.\n\nRisk: Crawl, map, and research operations can consume paid credits quickly.\n\nMitigation: Keep explicit enable and confirm flags in place, review limits before running broad jobs, and monitor usage with the included usage command.\n\nRisk: Cron-based update checks introduce scheduled network activity and code changes.\n\nMitigation: Review the update workflow and destination before enabling scheduled checks.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/brucetangc/skills/tavily-web-search-full)\n- [Tavily](https://tavily.com)\n- [Tavily Documentation](https://docs.tavily.com)\n- [Tavily Search API Reference](https://docs.tavily.com/documentation/api-reference/endpoint/search)\n- [Tavily Search Best Practices](https://docs.tavily.com/documentation/best-practices/best-practices-search)\n- [Tavily Changelog](https://docs.tavily.com/changelog.md)\n- [Tavily Rate Limits](https://docs.tavily.com/documentation/rate-limits.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown, JSON, plain text, and Brave-compatible JSON depending on command flags.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires TAVILY_API_KEY; API responses may be cached and logged locally; costlier crawl, map, and research operations require explicit enable or confirm flags.]\n\n## Skill Version(s):\n\n2.0.6 (source: server release evidence; artifact frontmatter lists 2.0.3 and README/release notes list 2.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v2.0.5: 15 files, 47719 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (13043b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (15109b)\n\nFile v2.0.5:SKILL.md\n\n---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.3\nmetadata: {\n  \"clawdbot\": {\n    \"emoji\": \"🔍\",\n    \"requires\": {\n      \"bins\": [\"python3\"],\n      \"env\": [\"TAVILY_API_KEY\"]\n    },\n    \"primaryEnv\": \"TAVILY_API_KEY\"\n  }\n}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\"\n```\n\n### 🕷️ Crawl API（网站爬取）⚠️ 默认禁用\n\n**成本**: 3-5 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20\n```\n\n### 🗺️ Map API（网站地图）⚠️ 默认禁用\n\n**成本**: 1-2 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 生成网站地图\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --instructions \"find all blog posts\"\n\n# 输出 URL 列表\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n### 📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用\n\n**成本**: 4-250 信用/次 | **必须使用 `--enable --confirm`**\n\n```bash\n# 深度研究（必须使用 --enable AND --confirm）\npython3 {baseDir}/scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型（更贵但质量更高）\npython3 {baseDir}/scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 新闻搜索\n```bash\n# 今日新闻\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 本周财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --topic finance --time-range week\n\n# 指定日期范围\npython3 {baseDir}/scripts/search.py --query \"election results\" --start-date 2025-01-01 --end-date 2025-01-31\n```\n\n### 深度研究\n```bash\n# 高级模式（最高相关性，2 信用/次）\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 包含完整页面内容\npython3 {baseDir}/scripts/search.py --query \"React best practices\" --include-raw-content markdown\n\n# 详细 AI 答案\npython3 {baseDir}/scripts/search.py --query \"climate change impact\" --answer-type advanced\n```\n\n### 域名过滤\n```bash\n# 只搜索特定网站\npython3 {baseDir}/scripts/search.py --query \"JavaScript tips\" --include-domains \"github.com,dev.to,medium.com\"\n\n# 排除某些网站\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\" --exclude-domains \"w3schools.com\"\n\n# 组合使用\npython3 {baseDir}/scripts/search.py --query \"Rust programming\" --include-domains \"rust-lang.org,docs.rs\" --exclude-domains \"reddit.com\"\n```\n\n### 国家/地区定向\n```bash\n# 美国科技新闻\npython3 {baseDir}/scripts/search.py --query \"tech startups\" --country \"united states\" --topic news\n\n# 中国财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --country \"china\" --topic finance\n```\n\n### 图片搜索\n```bash\n# 搜索图片\npython3 {baseDir}/scripts/search.py --query \"sunset photography\" --include-images\n\n# 带描述\npython3 {baseDir}/scripts/search.py --query \"machine learning\" --include-images --include-image-descriptions\n```\n\n### 快速搜索（低延迟）\n```bash\n# 快速模式（1 信用，低延迟）\npython3 {baseDir}/scripts/search.py --query \"weather today\" --search-depth fast\n\n# 超快速（1 信用，最低延迟）\npython3 {baseDir}/scripts/search.py --query \"stock price\" --search-depth ultra-fast\n```\n\n### 自动参数\n```bash\n# 让 Tavily 自动配置（可能使用 advanced=2 信用）\npython3 {baseDir}/scripts/search.py --query \"comprehensive analysis of AI trends\" --auto-parameters\n\n# 自动参数但手动控制深度（控制成本）\npython3 {baseDir}/scripts/search.py --query \"research query\" --auto-parameters --search-depth basic\n```\n\n### 精确匹配\n```bash\n# 精确搜索人名/公司名\npython3 {baseDir}/scripts/search.py --query '\"John Smith\" CEO Acme Corp' --exact-match\n```\n\n## 📋 完整参数说明\n\n```bash\npython3 {baseDir}/scripts/search.py --help\n```\n\n### 必需参数\n| 参数 | 说明 |\n|------|------|\n| `--query` | 搜索关键词（建议 <400 字符） |\n\n### 搜索深度\n| 参数值 | 延迟 | 相关性 | 内容类型 | 信用 |\n|--------|------|--------|----------|------|\n| `ultra-fast` | 最低 | 较低 | NLP 摘要 | 1 |\n| `fast` | 低 | 良好 | 相关片段 | 1 |\n| `basic` | 中等 | 高 | NLP 摘要 | 1 |\n| `advanced` | 较高 | 最高 | 相关片段 | 2 |\n\n## 💡 最佳实践\n\n### 查询优化\n- ✅ **保持查询简洁** - 建议 <400 字符\n- ✅ **复杂查询拆分** - 分成多个小查询\n- ✅ **使用精确匹配** - 人名/公司名用 `--exact-match`\n- ✅ **合理设置 max-results** - 3-5 个足够（默认 5）\n\n### 搜索深度选择\n- `basic` - 日常搜索（推荐）\n- `advanced` - 深度研究（特定问题）\n- `fast` / `ultra-fast` - 实时应用\n\n### 结果过滤\n```bash\n# 按相关性分数过滤\npython3 scripts/search.py --query \"Python\" --min-score 0.7\n\n# 只搜索特定域名\npython3 scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n\n# 排除低质量站点\npython3 scripts/search.py --query \"AI\" --exclude-domains \"content-farm.com\"\n```\n\n### 成本优化\n- ⚠️ **auto_parameters 可能使用 advanced**（2 信用）\n- ✅ 手动设置 `--search-depth basic` 控制成本\n- ✅ 使用缓存（默认开启）\n- ✅ 批量提取 URL（5 个 URL = 1 信用）\n\n## 💰 API 信用说明\n\n### 日常 API（推荐）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Search** | basic/fast/ultra-fast | 1/次 | 1,000 次 |\n| **Search** | advanced | 2/次 | 500 次 |\n| **Extract** | basic | 1/5 URL | 5,000 URL |\n| **Extract** | advanced | 2/5 URL | 2,500 URL |\n| **Usage** | 查询 | 免费 | 无限 |\n\n### 高级 API（默认禁用 ⚠️）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Map** | 标准 | 1/10 页 | ~10,000 页 |\n| **Map** | 带指令 | 2/10 页 | ~5,000 页 |\n| **Crawl** | basic | ~3/10 页 | ~3,300 页 |\n| **Crawl** | advanced | ~5/10 页 | ~2,000 页 |\n\n### 研究 API（极度昂贵 ⚠️⚠️）\n\n| API | 模型 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Research** | mini | 4-110/次 | 9-250 次 |\n| **Research** | pro | 15-250/次 | 4-66 次 |\n\n**免费额度**: 1000 信用/月\n\n### 安全控制\n\n| API | 默认状态 | 启用方式 |\n|-----|---------|---------|\n| Search | ✅ 启用 | 直接使用 |\n| Extract | ✅ 启用 | 直接使用 |\n| Usage | ✅ 启用 | 直接使用 |\n| Map | ❌ 禁用 | `--enable` |\n| Crawl | ❌ 禁用 | `--enable` |\n| Research | ❌ 禁用 | `--enable --confirm` |\n\n### 节省信用技巧\n1. 日常使用 Search/Extract/Usage\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n5. 批量提取 URL（5 个 URL = 1 信用）\n6. **谨慎使用 Crawl/Map/Research**\n\n### 主题分类\n- `general` - 通用搜索（默认）\n- `news` - 新闻（包含 `published_date`）\n- `finance` - 财经\n\n### 时间过滤\n- `--time-range`: `day` / `week` / `month` / `year`\n- `--start-date`: YYYY-MM-DD\n- `--end-date`: YYYY-MM-DD\n\n### 输出格式\n- `compact` - 简洁 Markdown（默认）\n- `md` - 详细 Markdown（包含分数、完整内容）\n- `brave` - JSON（兼容 web_search 格式）\n- `raw` - 原始 JSON（包含所有字段）\n\n## 💰 API 信用说明\n\n| 操作 | 信用消耗 |\n|------|----------|\n| basic/fast/ultra-fast 搜索 | 1 |\n| advanced 搜索 | 2 |\n| include_answer (advanced) | +1 |\n| include_raw_content | +1 |\n| include_images | +1 |\n\n**免费额度**: 1000 信用/月\n\n### 节省信用技巧\n1. 使用 `basic` 深度进行日常搜索\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n\n## 🔄 自动更新\n\nTavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。\n\n### 手动检查更新\n```bash\n# 检查是否有更新\npython3 {baseDir}/scripts/update.py --check-only\n\n# 应用更新\npython3 {baseDir}/scripts/update.py\n\n# 强制更新（即使无变更）\npython3 {baseDir}/scripts/update.py --force\n\n# 查看状态\npython3 {baseDir}/scripts/update.py --status\n```\n\n### 自动更新（推荐）\n添加每周检查的 cron 任务：\n```bash\n# 编辑 crontab\ncrontab -e\n\n# 添加每周日 9:00 检查更新\n0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1\n```\n\n### 更新日志\n- 更新记录：`{baseDir}/update.log`\n- 最后检查：`{baseDir}/.last_check`\n- 版本信息：`{baseDir}/_meta.json`\n\n## 📁 文件位置\n\n```\n~/.openclaw/\n├── .env                          # API key 配置\n├── cache/tavily/                 # 缓存目录\n│   ├── search/                   # Search 缓存\n│   ├── extract/                  # Extract 缓存\n│   ├── crawl/                    # Crawl 缓存\n│   ├── map/                      # Map 缓存\n│   └── research/                 # Research 缓存\n├── logs/\n│   ├── tavily.log                # Search 日志\n│   ├── tavily_extract.log        # Extract 日志\n│   ├── tavily_usage.log          # Usage 日志\n│   ├── tavily_crawl.log          # Crawl 日志\n│   ├── tavily_map.log            # Map 日志\n│   └── tavily_research.log       # Research 日志\n└── workspace/skills/tavily-web-search/\n    ├── SKILL.md                  # 本文档\n    ├── README.md                 # 快速开始\n    ├── CHANGELOG.md              # 更新日志\n    ├── _meta.json                # 版本信息\n    ├── update.log                # 更新日志\n    ├── .last_check               # 最后检查记录\n    └── scripts/\n        ├── search.py             # Search API（搜索）✅ 默认启用\n        ├── extract.py            # Extract API（URL 提取）✅ 默认启用\n        ├── usage.py              # Usage API（使用量查询）✅ 默认启用\n        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用\n        ├── map.py                # Map API（网站地图）❌ 默认禁用\n        ├── research.py           # Research API（深度研究）❌ 默认禁用\n        ├── update.py             # 自动更新脚本\n        └── test_all.py           # 测试套件\n```\n\n## 🔧 故障排除\n\n### \"Missing TAVILY_API_KEY\"\n```bash\n# 检查配置\ncat ~/.openclaw/.env | grep TAVILY\n\n# 或设置环境变量\nexport TAVILY_API_KEY=\"tvly-xxx\"\n```\n\n### \"Search failed after 3 attempts\"\n- 检查网络连接\n- 查看日志：`tail -f ~/.openclaw/logs/tavily.log`\n- 验证 API key: https://app.tavily.com/home\n\n### 清除缓存\n```bash\nrm -rf ~/.openclaw/cache/tavily/*\n```\n\n### 禁用缓存\n```bash\npython3 {baseDir}/scripts/search.py --query \"test\" --no-cache\n```\n\n## 📚 参考链接\n\n- 官方文档：https://docs.tavily.com\n- API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search\n- 最佳实践：https://docs.tavily.com/documentation/best-practices/best-practices-search\n- 管理平台：https://app.tavily.com\n\nFile v2.0.5:README.md\n\n# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com\n\nFile v2.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.0.5\",\n  \"publishedAt\": 1774186293335\n}\n\nFile v2.0.5:CHANGELOG.md\n\n# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n- ✅ SKILL.md - 添加 Extract 和 Usage 完整文档\n- ✅ README.md - 更新使用示例\n- ✅ _meta.json - 版本更新到 1.1.0\n\n---\n\n## 📊 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 |\n|-----|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 |\n| Crawl | `/crawl` | ❌ | - | 3-5 信用/10 页 |\n| Map | `/map` | ❌ | - | 1-2 信用/10 页 |\n| Research | `/research` | ❌ | - | 4-250 信用/次 |\n\n---\n\n## 💰 成本对比\n\n### 免费额度（1000 信用/月）能做：\n\n| 操作 | 次数 |\n|------|------|\n| Search (basic) | 1,000 次 |\n| Search (advanced) | 500 次 |\n| Extract (basic) | 5,000 个 URL |\n| Extract (advanced) | 2,500 个 URL |\n| Usage | 无限次 |\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md                  # 完整文档\n├── README.md                 # 快速开始\n├── _meta.json                # 版本信息 (v1.1.0)\n├── CHANGELOG.md              # 本文件\n├── update.log                # 更新日志\n├── .last_check               # 最后检查记录\n└── scripts/\n    ├── search.py             # Search API (592 行)\n    ├── extract.py            # Extract API (464 行)\n    ├── usage.py              # Usage API (307 行)\n    ├── update.py             # 自动更新 (315 行)\n    └── test_all.py           # 测试套件 (120 行)\n```\n\n**总代码量**: ~1,800 行\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py --quick\n\n📍 Testing Search API...\n✅ PASS - search.py --query \"Python tutorial\"\n✅ PASS - search.py --query \"AI news\" --topic news\n✅ PASS - search.py --query \"Python\" --include-domains python.org\n✅ PASS - search.py --query \"test\" --format raw\n\n📊 TEST SUMMARY\nPassed: 4/4\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n# 发布 v1.1.0\nclawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 1.1.0\n\n# 输出\n✔ OK. Published tavily-web-search-full@1.1.0\n```\n\n---\n\n## 📈 使用统计\n\n### 典型工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n# 输出：Used: 150 | Remaining: 850 | Total: 1,000\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"AI trends 2026\" --max-results 5\n\n# 3. 提取感兴趣的文章\npython3 scripts/extract.py --urls \"https://example.com/article1,https://example.com/article2\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n# 输出：Used: 151 | Remaining: 849 | Total: 1,000\n```\n\n---\n\n## 🎯 下一步计划\n\n### 可选扩展\n- [ ] Crawl API（网站爬取）\n- [ ] Map API（网站地图）\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 结果评分过滤\n\n### 优化建议\n- [x] ✅ 添加 Extract API\n- [x] ✅ 添加 Usage API\n- [x] ✅ 完整测试套件\n- [ ] 性能基准测试\n- [ ] 更多输出格式模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n\n---\n\n**版本**: 1.1.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT\n\nFile v2.0.5:RATE_LIMIT.md\n\n# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] Success: 5 results\n```\n\n### 遇到 Rate Limit\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[INFO] Success: 5 results\n```\n\n### 超过限制\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[WARN] Rate limited. Waiting 4.0s before retry...\n[DEBUG] Request attempt 3/3: test...\n[ERROR] All 3 retries failed: Rate limit exceeded\n```\n\n## 🎯 最佳实践\n\n### 1. 批量请求时的延迟\n\n```python\n# ❌ 不好 - 快速连续请求\nfor query in queries:\n    search(query)\n\n# ✅ 好 - 添加延迟\nimport time\nfor query in queries:\n    search(query)\n    time.sleep(0.5)  # 每秒 2 个请求\n```\n\n### 2. 监控使用量\n\n```bash\n# 定期检查使用量\npython3 scripts/usage.py\n```\n\n### 3. 使用缓存\n\n```bash\n# 启用缓存（默认开启）\npython3 scripts/search.py --query \"test\"\n\n# 强制刷新（禁用缓存）\npython3 scripts/search.py --query \"test\" --no-cache\n```\n\n### 4. 了解限制\n\n- **Development Key**: 100 RPM = 每秒~1.6 个请求\n- **Production Key**: 1,000 RPM = 每秒~16 个请求\n\n## 📚 相关文件\n\n- `scripts/rate_limit.py` - Rate Limit 处理器\n- `scripts/search.py` - 已集成\n- `scripts/extract.py` - 已集成\n- https://docs.tavily.com/documentation/rate-limits.md - 官方文档\n\n## 🔄 后续更新\n\n待更新的脚本：\n- [ ] `crawl.py`\n- [ ] `map.py`\n- [ ] `research.py`\n- [ ] `usage.py`\n\n更新方法：\n```python\n# 1. 添加导入\nfrom rate_limit import rate_limit_handler\n\n# 2. 添加装饰器\n@rate_limit_handler(max_retries=MAX_RETRIES, base_delay=RETRY_DELAY, log_func=log)\ndef api_function():\n    # ...\n```\n\n---\n\n**版本**: 1.0.0  \n**更新日期**: 2026-03-22  \n**基于**: Tavily Rate Limits 官方文档\n\nFile v2.0.5:RELEASE_NOTES.md\n\n# Tavily Web Search Skill - v2.0.0 发布总结\n\n## 🎉 重大更新\n\n版本 2.0.0 实现了 Tavily **全部 6 个官方 API**，并引入了智能安全控制机制。\n\n---\n\n## 📦 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 | 默认 |\n|-----|------|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 | ✅ 启用 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL | ✅ 启用 |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 | ✅ 启用 |\n| **Crawl** | `/crawl` | ✅ 100% | `crawl.py` | 3-5 信用/10 页 | ❌ 禁用 |\n| **Map** | `/map` | ✅ 100% | `map.py` | 1-2 信用/10 页 | ❌ 禁用 |\n| **Research** | `/research` | ✅ 100% | `research.py` | 4-250 信用/次 | ❌ 禁用 |\n\n**总代码量**: ~3,500 行\n\n---\n\n## 🔒 安全控制机制\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n### 实现方式\n\n| API | 安全级别 | 启用方式 | 警告信息 |\n|-----|---------|---------|---------|\n| Search | ✅ 无 | 直接使用 | 无 |\n| Extract | ✅ 无 | 直接使用 | 无 |\n| Usage | ✅ 无 | 直接使用 | 无 |\n| Crawl | ⚠️ 中等 | `--enable` | 成本警告 |\n| Map | ⚠️ 中等 | `--enable` | 成本警告 |\n| Research | ⚠️⚠️ 高 | `--enable --confirm` | 强烈警告 |\n\n### 代码示例\n\n```python\n# Crawl API - 单标志确认\nif not args.enable:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable to proceed\", file=sys.stderr)\n    sys.exit(1)\n\n# Research API - 双重确认\nif not args.enable or not args.confirm:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable AND --confirm\", file=sys.stderr)\n    sys.exit(1)\n```\n\n---\n\n## 📊 成本对比\n\n### 免费额度（1000 信用/月）\n\n| API | 使用次数 |\n|-----|---------|\n| Search (basic) | 1,000 次 |\n| Extract (basic) | 5,000 URL |\n| Usage | 无限 |\n| Map | 5,000-10,000 页 |\n| Crawl | 2,000-3,300 页 |\n| Research (mini) | 9-250 次 |\n| Research (pro) | 4-66 次 |\n\n### 典型使用场景\n\n#### 日常开发（推荐）\n```bash\n# 搜索文档\npython3 scripts/search.py --query \"Python async tutorial\"\n\n# 提取文章内容\npython3 scripts/extract.py --urls \"https://realpython.com/article\"\n\n# 查看使用量\npython3 scripts/usage.py\n```\n\n**成本**: ~2-3 信用\n\n#### 网站分析（偶尔）\n```bash\n# 生成网站地图\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 爬取特定内容\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find pricing\"\n```\n\n**成本**: ~10-20 信用\n\n#### 深度研究（谨慎）\n```bash\n# 市场分析报告\npython3 scripts/research.py --query \"AI market 2026\" --enable --confirm\n```\n\n**成本**: 50-150 信用\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py\n\n📍 Testing Search API...\n✅ PASS (4 tests)\n\n📄 Testing Extract API...\n✅ PASS (4 tests)\n\n📊 Testing Usage API...\n✅ PASS (3 tests)\n\n🔒 Testing safety controls...\n✅ PASS (4 tests - all correctly disabled)\n\n============================================================\n📊 TEST SUMMARY\n============================================================\nPassed: 15/15\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md (15KB)         # 完整文档\n├── README.md (2.5KB)       # 快速开始\n├── CHANGELOG.md (8KB)      # 更新日志\n├── RELEASE_NOTES.md        # 本文件\n├── _meta.json              # v2.0.0 + 安全配置\n└── scripts/\n    ├── search.py (592 行)   # Search API ✅\n    ├── extract.py (464 行)  # Extract API ✅\n    ├── usage.py (307 行)    # Usage API ✅\n    ├── crawl.py (532 行)    # Crawl API ❌ (--enable)\n    ├── map.py (467 行)      # Map API ❌ (--enable)\n    ├── research.py (481 行) # Research API ❌ (--enable --confirm)\n    ├── update.py (315 行)   # 自动更新\n    └── test_all.py (180 行) # 测试套件\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n$ clawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 2.0.0\n\n- Preparing tavily-web-search-full@2.0.0\n✔ OK. Published tavily-web-search-full@2.0.0 (k9737e5bh0ac5td2ag6yvcsjm183bfyk)\n```\n\n- **ClawHub Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **状态**: ✅ 已发布\n\n---\n\n## 📈 使用建议\n\n### ✅ 推荐工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"your topic\" --max-results 5\n\n# 3. 提取感兴趣的内容\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 何时使用高级 API\n\n**使用 Crawl 当：**\n- 需要爬取整个网站\n- Search API 找不到足够信息\n- 有明确的爬取目标\n\n**使用 Map 当：**\n- 需要完整的网站地图\n- 准备批量处理网站页面\n- 需要了解网站结构\n\n**使用 Research 当：**\n- 需要深度分析报告\n- 预算充足（>100 信用）\n- Search API 无法满足需求\n\n### ❌ 避免的陷阱\n\n1. **不要随意使用 Research** - 几次就用光月度额度\n2. **Crawl 时设置 limit** - 避免爬取过多页面\n3. **始终先检查 usage** - 了解剩余额度\n\n---\n\n## 🎯 下一步计划\n\n### 已完成\n- ✅ 全部 6 个官方 API\n- ✅ 智能安全控制\n- ✅ 完整测试套件\n- ✅ 自动更新功能\n- ✅ 详细文档\n\n### 可选扩展\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 批量处理脚本\n- [ ] 结果评分过滤\n- [ ] 更多输出模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n- **最佳实践**: https://docs.tavily.com/documentation/best-practices\n\n---\n\n## 💡 关键决策\n\n### 为什么默认禁用 Crawl/Map/Research？\n\n1. **成本考虑**\n   - Research 单次最高 250 信用（1/4 月度额度）\n   - 新手可能无意中快速消耗信用\n\n2. **使用频率**\n   - 90% 场景 Search+Extract 足够\n   - Crawl/Map/Research 是特殊需求\n\n3. **用户体验**\n   - 默认启用可能导致意外消费\n   - 明确确认避免误用\n\n### 为什么 Research 需要双重确认？\n\n- **极端成本**: 4-250 信用/次\n- **不可逆**: 一旦开始无法取消\n- **替代方案**: Search API 通常够用\n- **教育意义**: 让用户三思而后行\n\n---\n\n**版本**: 2.0.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT  \n**测试通过率**: 100% (15/15)\n\nArchive v2.0.4: 15 files, 47663 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (12893b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (15109b)\n\nFile v2.0.4:SKILL.md\n\n---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.3\nmetadata: {\n  \"clawdbot\": {\n    \"emoji\": \"🔍\",\n    \"requires\": {\n      \"bins\": [\"python3\"],\n      \"env\": [\"TAVILY_API_KEY\"]\n    },\n    \"primaryEnv\": \"TAVILY_API_KEY\"\n  }\n}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\"\n```\n\n### 🕷️ Crawl API（网站爬取）⚠️ 默认禁用\n\n**成本**: 3-5 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20\n```\n\n### 🗺️ Map API（网站地图）⚠️ 默认禁用\n\n**成本**: 1-2 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 生成网站地图\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --instructions \"find all blog posts\"\n\n# 输出 URL 列表\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n### 📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用\n\n**成本**: 4-250 信用/次 | **必须使用 `--enable --confirm`**\n\n```bash\n# 深度研究（必须使用 --enable AND --confirm）\npython3 {baseDir}/scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型（更贵但质量更高）\npython3 {baseDir}/scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 新闻搜索\n```bash\n# 今日新闻\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 本周财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --topic finance --time-range week\n\n# 指定日期范围\npython3 {baseDir}/scripts/search.py --query \"election results\" --start-date 2025-01-01 --end-date 2025-01-31\n```\n\n### 深度研究\n```bash\n# 高级模式（最高相关性，2 信用/次）\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 包含完整页面内容\npython3 {baseDir}/scripts/search.py --query \"React best practices\" --include-raw-content markdown\n\n# 详细 AI 答案\npython3 {baseDir}/scripts/search.py --query \"climate change impact\" --answer-type advanced\n```\n\n### 域名过滤\n```bash\n# 只搜索特定网站\npython3 {baseDir}/scripts/search.py --query \"JavaScript tips\" --include-domains \"github.com,dev.to,medium.com\"\n\n# 排除某些网站\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\" --exclude-domains \"w3schools.com\"\n\n# 组合使用\npython3 {baseDir}/scripts/search.py --query \"Rust programming\" --include-domains \"rust-lang.org,docs.rs\" --exclude-domains \"reddit.com\"\n```\n\n### 国家/地区定向\n```bash\n# 美国科技新闻\npython3 {baseDir}/scripts/search.py --query \"tech startups\" --country \"united states\" --topic news\n\n# 中国财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --country \"china\" --topic finance\n```\n\n### 图片搜索\n```bash\n# 搜索图片\npython3 {baseDir}/scripts/search.py --query \"sunset photography\" --include-images\n\n# 带描述\npython3 {baseDir}/scripts/search.py --query \"machine learning\" --include-images --include-image-descriptions\n```\n\n### 快速搜索（低延迟）\n```bash\n# 快速模式（1 信用，低延迟）\npython3 {baseDir}/scripts/search.py --query \"weather today\" --search-depth fast\n\n# 超快速（1 信用，最低延迟）\npython3 {baseDir}/scripts/search.py --query \"stock price\" --search-depth ultra-fast\n```\n\n### 自动参数\n```bash\n# 让 Tavily 自动配置（可能使用 advanced=2 信用）\npython3 {baseDir}/scripts/search.py --query \"comprehensive analysis of AI trends\" --auto-parameters\n\n# 自动参数但手动控制深度（控制成本）\npython3 {baseDir}/scripts/search.py --query \"research query\" --auto-parameters --search-depth basic\n```\n\n### 精确匹配\n```bash\n# 精确搜索人名/公司名\npython3 {baseDir}/scripts/search.py --query '\"John Smith\" CEO Acme Corp' --exact-match\n```\n\n## 📋 完整参数说明\n\n```bash\npython3 {baseDir}/scripts/search.py --help\n```\n\n### 必需参数\n| 参数 | 说明 |\n|------|------|\n| `--query` | 搜索关键词（建议 <400 字符） |\n\n### 搜索深度\n| 参数值 | 延迟 | 相关性 | 内容类型 | 信用 |\n|--------|------|--------|----------|------|\n| `ultra-fast` | 最低 | 较低 | NLP 摘要 | 1 |\n| `fast` | 低 | 良好 | 相关片段 | 1 |\n| `basic` | 中等 | 高 | NLP 摘要 | 1 |\n| `advanced` | 较高 | 最高 | 相关片段 | 2 |\n\n## 💡 最佳实践\n\n### 查询优化\n- ✅ **保持查询简洁** - 建议 <400 字符\n- ✅ **复杂查询拆分** - 分成多个小查询\n- ✅ **使用精确匹配** - 人名/公司名用 `--exact-match`\n- ✅ **合理设置 max-results** - 3-5 个足够（默认 5）\n\n### 搜索深度选择\n- `basic` - 日常搜索（推荐）\n- `advanced` - 深度研究（特定问题）\n- `fast` / `ultra-fast` - 实时应用\n\n### 结果过滤\n```bash\n# 按相关性分数过滤\npython3 scripts/search.py --query \"Python\" --min-score 0.7\n\n# 只搜索特定域名\npython3 scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n\n# 排除低质量站点\npython3 scripts/search.py --query \"AI\" --exclude-domains \"content-farm.com\"\n```\n\n### 成本优化\n- ⚠️ **auto_parameters 可能使用 advanced**（2 信用）\n- ✅ 手动设置 `--search-depth basic` 控制成本\n- ✅ 使用缓存（默认开启）\n- ✅ 批量提取 URL（5 个 URL = 1 信用）\n\n## 💰 API 信用说明\n\n### 日常 API（推荐）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Search** | basic/fast/ultra-fast | 1/次 | 1,000 次 |\n| **Search** | advanced | 2/次 | 500 次 |\n| **Extract** | basic | 1/5 URL | 5,000 URL |\n| **Extract** | advanced | 2/5 URL | 2,500 URL |\n| **Usage** | 查询 | 免费 | 无限 |\n\n### 高级 API（默认禁用 ⚠️）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Map** | 标准 | 1/10 页 | ~10,000 页 |\n| **Map** | 带指令 | 2/10 页 | ~5,000 页 |\n| **Crawl** | basic | ~3/10 页 | ~3,300 页 |\n| **Crawl** | advanced | ~5/10 页 | ~2,000 页 |\n\n### 研究 API（极度昂贵 ⚠️⚠️）\n\n| API | 模型 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Research** | mini | 4-110/次 | 9-250 次 |\n| **Research** | pro | 15-250/次 | 4-66 次 |\n\n**免费额度**: 1000 信用/月\n\n### 安全控制\n\n| API | 默认状态 | 启用方式 |\n|-----|---------|---------|\n| Search | ✅ 启用 | 直接使用 |\n| Extract | ✅ 启用 | 直接使用 |\n| Usage | ✅ 启用 | 直接使用 |\n| Map | ❌ 禁用 | `--enable` |\n| Crawl | ❌ 禁用 | `--enable` |\n| Research | ❌ 禁用 | `--enable --confirm` |\n\n### 节省信用技巧\n1. 日常使用 Search/Extract/Usage\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n5. 批量提取 URL（5 个 URL = 1 信用）\n6. **谨慎使用 Crawl/Map/Research**\n\n### 主题分类\n- `general` - 通用搜索（默认）\n- `news` - 新闻（包含 `published_date`）\n- `finance` - 财经\n\n### 时间过滤\n- `--time-range`: `day` / `week` / `month` / `year`\n- `--start-date`: YYYY-MM-DD\n- `--end-date`: YYYY-MM-DD\n\n### 输出格式\n- `compact` - 简洁 Markdown（默认）\n- `md` - 详细 Markdown（包含分数、完整内容）\n- `brave` - JSON（兼容 web_search 格式）\n- `raw` - 原始 JSON（包含所有字段）\n\n## 💰 API 信用说明\n\n| 操作 | 信用消耗 |\n|------|----------|\n| basic/fast/ultra-fast 搜索 | 1 |\n| advanced 搜索 | 2 |\n| include_answer (advanced) | +1 |\n| include_raw_content | +1 |\n| include_images | +1 |\n\n**免费额度**: 1000 信用/月\n\n### 节省信用技巧\n1. 使用 `basic` 深度进行日常搜索\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n\n## 🔄 自动更新\n\nTavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。\n\n### 手动检查更新\n```bash\n# 检查是否有更新\npython3 {baseDir}/scripts/update.py --check-only\n\n# 应用更新\npython3 {baseDir}/scripts/update.py\n\n# 强制更新（即使无变更）\npython3 {baseDir}/scripts/update.py --force\n\n# 查看状态\npython3 {baseDir}/scripts/update.py --status\n```\n\n### 自动更新（推荐）\n添加每周检查的 cron 任务：\n```bash\n# 编辑 crontab\ncrontab -e\n\n# 添加每周日 9:00 检查更新\n0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1\n```\n\n### 更新日志\n- 更新记录：`{baseDir}/update.log`\n- 最后检查：`{baseDir}/.last_check`\n- 版本信息：`{baseDir}/_meta.json`\n\n## 📁 文件位置\n\n```\n~/.openclaw/\n├── .env                          # API key 配置\n├── cache/tavily/                 # 缓存目录\n│   ├── search/                   # Search 缓存\n│   ├── extract/                  # Extract 缓存\n│   ├── crawl/                    # Crawl 缓存\n│   ├── map/                      # Map 缓存\n│   └── research/                 # Research 缓存\n├── logs/\n│   ├── tavily.log                # Search 日志\n│   ├── tavily_extract.log        # Extract 日志\n│   ├── tavily_usage.log          # Usage 日志\n│   ├── tavily_crawl.log          # Crawl 日志\n│   ├── tavily_map.log            # Map 日志\n│   └── tavily_research.log       # Research 日志\n└── workspace/skills/tavily-web-search/\n    ├── SKILL.md                  # 本文档\n    ├── README.md                 # 快速开始\n    ├── CHANGELOG.md              # 更新日志\n    ├── _meta.json                # 版本信息\n    ├── update.log                # 更新日志\n    ├── .last_check               # 最后检查记录\n    └── scripts/\n        ├── search.py             # Search API（搜索）✅ 默认启用\n        ├── extract.py            # Extract API（URL 提取）✅ 默认启用\n        ├── usage.py              # Usage API（使用量查询）✅ 默认启用\n        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用\n        ├── map.py                # Map API（网站地图）❌ 默认禁用\n        ├── research.py           # Research API（深度研究）❌ 默认禁用\n        ├── update.py             # 自动更新脚本\n        └── test_all.py           # 测试套件\n```\n\n## 🔧 故障排除\n\n### \"Missing TAVILY_API_KEY\"\n```bash\n# 检查配置\ncat ~/.openclaw/.env | grep TAVILY\n\n# 或设置环境变量\nexport TAVILY_API_KEY=\"tvly-xxx\"\n```\n\n### \"Search failed after 3 attempts\"\n- 检查网络连接\n- 查看日志：`tail -f ~/.openclaw/logs/tavily.log`\n- 验证 API key: https://app.tavily.com/home\n\n### 清除缓存\n```bash\nrm -rf ~/.openclaw/cache/tavily/*\n```\n\n### 禁用缓存\n```bash\npython3 {baseDir}/scripts/search.py --query \"test\" --no-cache\n```\n\n## 📚 参考链接\n\n- 官方文档：https://docs.tavily.com\n- API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search\n- 最佳实践：https://docs.tavily.com/documentation/best-practices/best-practices-search\n- 管理平台：https://app.tavily.com\n\nFile v2.0.4:README.md\n\n# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com\n\nFile v2.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.0.4\",\n  \"publishedAt\": 1774139788615\n}\n\nFile v2.0.4:CHANGELOG.md\n\n# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n- ✅ SKILL.md - 添加 Extract 和 Usage 完整文档\n- ✅ README.md - 更新使用示例\n- ✅ _meta.json - 版本更新到 1.1.0\n\n---\n\n## 📊 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 |\n|-----|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 |\n| Crawl | `/crawl` | ❌ | - | 3-5 信用/10 页 |\n| Map | `/map` | ❌ | - | 1-2 信用/10 页 |\n| Research | `/research` | ❌ | - | 4-250 信用/次 |\n\n---\n\n## 💰 成本对比\n\n### 免费额度（1000 信用/月）能做：\n\n| 操作 | 次数 |\n|------|------|\n| Search (basic) | 1,000 次 |\n| Search (advanced) | 500 次 |\n| Extract (basic) | 5,000 个 URL |\n| Extract (advanced) | 2,500 个 URL |\n| Usage | 无限次 |\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md                  # 完整文档\n├── README.md                 # 快速开始\n├── _meta.json                # 版本信息 (v1.1.0)\n├── CHANGELOG.md              # 本文件\n├── update.log                # 更新日志\n├── .last_check               # 最后检查记录\n└── scripts/\n    ├── search.py             # Search API (592 行)\n    ├── extract.py            # Extract API (464 行)\n    ├── usage.py              # Usage API (307 行)\n    ├── update.py             # 自动更新 (315 行)\n    └── test_all.py           # 测试套件 (120 行)\n```\n\n**总代码量**: ~1,800 行\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py --quick\n\n📍 Testing Search API...\n✅ PASS - search.py --query \"Python tutorial\"\n✅ PASS - search.py --query \"AI news\" --topic news\n✅ PASS - search.py --query \"Python\" --include-domains python.org\n✅ PASS - search.py --query \"test\" --format raw\n\n📊 TEST SUMMARY\nPassed: 4/4\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n# 发布 v1.1.0\nclawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 1.1.0\n\n# 输出\n✔ OK. Published tavily-web-search-full@1.1.0\n```\n\n---\n\n## 📈 使用统计\n\n### 典型工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n# 输出：Used: 150 | Remaining: 850 | Total: 1,000\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"AI trends 2026\" --max-results 5\n\n# 3. 提取感兴趣的文章\npython3 scripts/extract.py --urls \"https://example.com/article1,https://example.com/article2\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n# 输出：Used: 151 | Remaining: 849 | Total: 1,000\n```\n\n---\n\n## 🎯 下一步计划\n\n### 可选扩展\n- [ ] Crawl API（网站爬取）\n- [ ] Map API（网站地图）\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 结果评分过滤\n\n### 优化建议\n- [x] ✅ 添加 Extract API\n- [x] ✅ 添加 Usage API\n- [x] ✅ 完整测试套件\n- [ ] 性能基准测试\n- [ ] 更多输出格式模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n\n---\n\n**版本**: 1.1.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT\n\nFile v2.0.4:RATE_LIMIT.md\n\n# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] Success: 5 results\n```\n\n### 遇到 Rate Limit\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[INFO] Success: 5 results\n```\n\n### 超过限制\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[WARN] Rate limited. Waiting 4.0s before retry...\n[DEBUG] Request attempt 3/3: test...\n[ERROR] All 3 retries failed: Rate limit exceeded\n```\n\n## 🎯 最佳实践\n\n### 1. 批量请求时的延迟\n\n```python\n# ❌ 不好 - 快速连续请求\nfor query in queries:\n    search(query)\n\n# ✅ 好 - 添加延迟\nimport time\nfor query in queries:\n    search(query)\n    time.sleep(0.5)  # 每秒 2 个请求\n```\n\n### 2. 监控使用量\n\n```bash\n# 定期检查使用量\npython3 scripts/usage.py\n```\n\n### 3. 使用缓存\n\n```bash\n# 启用缓存（默认开启）\npython3 scripts/search.py --query \"test\"\n\n# 强制刷新（禁用缓存）\npython3 scripts/search.py --query \"test\" --no-cache\n```\n\n### 4. 了解限制\n\n- **Development Key**: 100 RPM = 每秒~1.6 个请求\n- **Production Key**: 1,000 RPM = 每秒~16 个请求\n\n## 📚 相关文件\n\n- `scripts/rate_limit.py` - Rate Limit 处理器\n- `scripts/search.py` - 已集成\n- `scripts/extract.py` - 已集成\n- https://docs.tavily.com/documentation/rate-limits.md - 官方文档\n\n## 🔄 后续更新\n\n待更新的脚本：\n- [ ] `crawl.py`\n- [ ] `map.py`\n- [ ] `research.py`\n- [ ] `usage.py`\n\n更新方法：\n```python\n# 1. 添加导入\nfrom rate_limit import rate_limit_handler\n\n# 2. 添加装饰器\n@rate_limit_handler(max_retries=MAX_RETRIES, base_delay=RETRY_DELAY, log_func=log)\ndef api_function():\n    # ...\n```\n\n---\n\n**版本**: 1.0.0  \n**更新日期**: 2026-03-22  \n**基于**: Tavily Rate Limits 官方文档\n\nFile v2.0.4:RELEASE_NOTES.md\n\n# Tavily Web Search Skill - v2.0.0 发布总结\n\n## 🎉 重大更新\n\n版本 2.0.0 实现了 Tavily **全部 6 个官方 API**，并引入了智能安全控制机制。\n\n---\n\n## 📦 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 | 默认 |\n|-----|------|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 | ✅ 启用 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL | ✅ 启用 |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 | ✅ 启用 |\n| **Crawl** | `/crawl` | ✅ 100% | `crawl.py` | 3-5 信用/10 页 | ❌ 禁用 |\n| **Map** | `/map` | ✅ 100% | `map.py` | 1-2 信用/10 页 | ❌ 禁用 |\n| **Research** | `/research` | ✅ 100% | `research.py` | 4-250 信用/次 | ❌ 禁用 |\n\n**总代码量**: ~3,500 行\n\n---\n\n## 🔒 安全控制机制\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n### 实现方式\n\n| API | 安全级别 | 启用方式 | 警告信息 |\n|-----|---------|---------|---------|\n| Search | ✅ 无 | 直接使用 | 无 |\n| Extract | ✅ 无 | 直接使用 | 无 |\n| Usage | ✅ 无 | 直接使用 | 无 |\n| Crawl | ⚠️ 中等 | `--enable` | 成本警告 |\n| Map | ⚠️ 中等 | `--enable` | 成本警告 |\n| Research | ⚠️⚠️ 高 | `--enable --confirm` | 强烈警告 |\n\n### 代码示例\n\n```python\n# Crawl API - 单标志确认\nif not args.enable:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable to proceed\", file=sys.stderr)\n    sys.exit(1)\n\n# Research API - 双重确认\nif not args.enable or not args.confirm:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable AND --confirm\", file=sys.stderr)\n    sys.exit(1)\n```\n\n---\n\n## 📊 成本对比\n\n### 免费额度（1000 信用/月）\n\n| API | 使用次数 |\n|-----|---------|\n| Search (basic) | 1,000 次 |\n| Extract (basic) | 5,000 URL |\n| Usage | 无限 |\n| Map | 5,000-10,000 页 |\n| Crawl | 2,000-3,300 页 |\n| Research (mini) | 9-250 次 |\n| Research (pro) | 4-66 次 |\n\n### 典型使用场景\n\n#### 日常开发（推荐）\n```bash\n# 搜索文档\npython3 scripts/search.py --query \"Python async tutorial\"\n\n# 提取文章内容\npython3 scripts/extract.py --urls \"https://realpython.com/article\"\n\n# 查看使用量\npython3 scripts/usage.py\n```\n\n**成本**: ~2-3 信用\n\n#### 网站分析（偶尔）\n```bash\n# 生成网站地图\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 爬取特定内容\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find pricing\"\n```\n\n**成本**: ~10-20 信用\n\n#### 深度研究（谨慎）\n```bash\n# 市场分析报告\npython3 scripts/research.py --query \"AI market 2026\" --enable --confirm\n```\n\n**成本**: 50-150 信用\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py\n\n📍 Testing Search API...\n✅ PASS (4 tests)\n\n📄 Testing Extract API...\n✅ PASS (4 tests)\n\n📊 Testing Usage API...\n✅ PASS (3 tests)\n\n🔒 Testing safety controls...\n✅ PASS (4 tests - all correctly disabled)\n\n============================================================\n📊 TEST SUMMARY\n============================================================\nPassed: 15/15\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md (15KB)         # 完整文档\n├── README.md (2.5KB)       # 快速开始\n├── CHANGELOG.md (8KB)      # 更新日志\n├── RELEASE_NOTES.md        # 本文件\n├── _meta.json              # v2.0.0 + 安全配置\n└── scripts/\n    ├── search.py (592 行)   # Search API ✅\n    ├── extract.py (464 行)  # Extract API ✅\n    ├── usage.py (307 行)    # Usage API ✅\n    ├── crawl.py (532 行)    # Crawl API ❌ (--enable)\n    ├── map.py (467 行)      # Map API ❌ (--enable)\n    ├── research.py (481 行) # Research API ❌ (--enable --confirm)\n    ├── update.py (315 行)   # 自动更新\n    └── test_all.py (180 行) # 测试套件\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n$ clawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 2.0.0\n\n- Preparing tavily-web-search-full@2.0.0\n✔ OK. Published tavily-web-search-full@2.0.0 (k9737e5bh0ac5td2ag6yvcsjm183bfyk)\n```\n\n- **ClawHub Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **状态**: ✅ 已发布\n\n---\n\n## 📈 使用建议\n\n### ✅ 推荐工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"your topic\" --max-results 5\n\n# 3. 提取感兴趣的内容\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 何时使用高级 API\n\n**使用 Crawl 当：**\n- 需要爬取整个网站\n- Search API 找不到足够信息\n- 有明确的爬取目标\n\n**使用 Map 当：**\n- 需要完整的网站地图\n- 准备批量处理网站页面\n- 需要了解网站结构\n\n**使用 Research 当：**\n- 需要深度分析报告\n- 预算充足（>100 信用）\n- Search API 无法满足需求\n\n### ❌ 避免的陷阱\n\n1. **不要随意使用 Research** - 几次就用光月度额度\n2. **Crawl 时设置 limit** - 避免爬取过多页面\n3. **始终先检查 usage** - 了解剩余额度\n\n---\n\n## 🎯 下一步计划\n\n### 已完成\n- ✅ 全部 6 个官方 API\n- ✅ 智能安全控制\n- ✅ 完整测试套件\n- ✅ 自动更新功能\n- ✅ 详细文档\n\n### 可选扩展\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 批量处理脚本\n- [ ] 结果评分过滤\n- [ ] 更多输出模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n- **最佳实践**: https://docs.tavily.com/documentation/best-practices\n\n---\n\n## 💡 关键决策\n\n### 为什么默认禁用 Crawl/Map/Research？\n\n1. **成本考虑**\n   - Research 单次最高 250 信用（1/4 月度额度）\n   - 新手可能无意中快速消耗信用\n\n2. **使用频率**\n   - 90% 场景 Search+Extract 足够\n   - Crawl/Map/Research 是特殊需求\n\n3. **用户体验**\n   - 默认启用可能导致意外消费\n   - 明确确认避免误用\n\n### 为什么 Research 需要双重确认？\n\n- **极端成本**: 4-250 信用/次\n- **不可逆**: 一旦开始无法取消\n- **替代方案**: Search API 通常够用\n- **教育意义**: 让用户三思而后行\n\n---\n\n**版本**: 2.0.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT  \n**测试通过率**: 100% (15/15)\n\nArchive v2.0.3: 15 files, 47653 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (12893b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (15062b)\n\nFile v2.0.3:SKILL.md\n\n---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.0\nmetadata: {\"clawdbot\":{\"emoji\":\"🔍\",\"requires\":{\"bins\":[\"python3\"],\"env\":[\"TAVILY_API_KEY\"]},\"primaryEnv\":\"TAVILY_API_KEY\"}}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\"\n```\n\n### 🕷️ Crawl API（网站爬取）⚠️ 默认禁用\n\n**成本**: 3-5 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20\n```\n\n### 🗺️ Map API（网站地图）⚠️ 默认禁用\n\n**成本**: 1-2 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 生成网站地图\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --instructions \"find all blog posts\"\n\n# 输出 URL 列表\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n### 📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用\n\n**成本**: 4-250 信用/次 | **必须使用 `--enable --confirm`**\n\n```bash\n# 深度研究（必须使用 --enable AND --confirm）\npython3 {baseDir}/scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型（更贵但质量更高）\npython3 {baseDir}/scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 新闻搜索\n```bash\n# 今日新闻\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 本周财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --topic finance --time-range week\n\n# 指定日期范围\npython3 {baseDir}/scripts/search.py --query \"election results\" --start-date 2025-01-01 --end-date 2025-01-31\n```\n\n### 深度研究\n```bash\n# 高级模式（最高相关性，2 信用/次）\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 包含完整页面内容\npython3 {baseDir}/scripts/search.py --query \"React best practices\" --include-raw-content markdown\n\n# 详细 AI 答案\npython3 {baseDir}/scripts/search.py --query \"climate change impact\" --answer-type advanced\n```\n\n### 域名过滤\n```bash\n# 只搜索特定网站\npython3 {baseDir}/scripts/search.py --query \"JavaScript tips\" --include-domains \"github.com,dev.to,medium.com\"\n\n# 排除某些网站\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\" --exclude-domains \"w3schools.com\"\n\n# 组合使用\npython3 {baseDir}/scripts/search.py --query \"Rust programming\" --include-domains \"rust-lang.org,docs.rs\" --exclude-domains \"reddit.com\"\n```\n\n### 国家/地区定向\n```bash\n# 美国科技新闻\npython3 {baseDir}/scripts/search.py --query \"tech startups\" --country \"united states\" --topic news\n\n# 中国财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --country \"china\" --topic finance\n```\n\n### 图片搜索\n```bash\n# 搜索图片\npython3 {baseDir}/scripts/search.py --query \"sunset photography\" --include-images\n\n# 带描述\npython3 {baseDir}/scripts/search.py --query \"machine learning\" --include-images --include-image-descriptions\n```\n\n### 快速搜索（低延迟）\n```bash\n# 快速模式（1 信用，低延迟）\npython3 {baseDir}/scripts/search.py --query \"weather today\" --search-depth fast\n\n# 超快速（1 信用，最低延迟）\npython3 {baseDir}/scripts/search.py --query \"stock price\" --search-depth ultra-fast\n```\n\n### 自动参数\n```bash\n# 让 Tavily 自动配置（可能使用 advanced=2 信用）\npython3 {baseDir}/scripts/search.py --query \"comprehensive analysis of AI trends\" --auto-parameters\n\n# 自动参数但手动控制深度（控制成本）\npython3 {baseDir}/scripts/search.py --query \"research query\" --auto-parameters --search-depth basic\n```\n\n### 精确匹配\n```bash\n# 精确搜索人名/公司名\npython3 {baseDir}/scripts/search.py --query '\"John Smith\" CEO Acme Corp' --exact-match\n```\n\n## 📋 完整参数说明\n\n```bash\npython3 {baseDir}/scripts/search.py --help\n```\n\n### 必需参数\n| 参数 | 说明 |\n|------|------|\n| `--query` | 搜索关键词（建议 <400 字符） |\n\n### 搜索深度\n| 参数值 | 延迟 | 相关性 | 内容类型 | 信用 |\n|--------|------|--------|----------|------|\n| `ultra-fast` | 最低 | 较低 | NLP 摘要 | 1 |\n| `fast` | 低 | 良好 | 相关片段 | 1 |\n| `basic` | 中等 | 高 | NLP 摘要 | 1 |\n| `advanced` | 较高 | 最高 | 相关片段 | 2 |\n\n## 💡 最佳实践\n\n### 查询优化\n- ✅ **保持查询简洁** - 建议 <400 字符\n- ✅ **复杂查询拆分** - 分成多个小查询\n- ✅ **使用精确匹配** - 人名/公司名用 `--exact-match`\n- ✅ **合理设置 max-results** - 3-5 个足够（默认 5）\n\n### 搜索深度选择\n- `basic` - 日常搜索（推荐）\n- `advanced` - 深度研究（特定问题）\n- `fast` / `ultra-fast` - 实时应用\n\n### 结果过滤\n```bash\n# 按相关性分数过滤\npython3 scripts/search.py --query \"Python\" --min-score 0.7\n\n# 只搜索特定域名\npython3 scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n\n# 排除低质量站点\npython3 scripts/search.py --query \"AI\" --exclude-domains \"content-farm.com\"\n```\n\n### 成本优化\n- ⚠️ **auto_parameters 可能使用 advanced**（2 信用）\n- ✅ 手动设置 `--search-depth basic` 控制成本\n- ✅ 使用缓存（默认开启）\n- ✅ 批量提取 URL（5 个 URL = 1 信用）\n\n## 💰 API 信用说明\n\n### 日常 API（推荐）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Search** | basic/fast/ultra-fast | 1/次 | 1,000 次 |\n| **Search** | advanced | 2/次 | 500 次 |\n| **Extract** | basic | 1/5 URL | 5,000 URL |\n| **Extract** | advanced | 2/5 URL | 2,500 URL |\n| **Usage** | 查询 | 免费 | 无限 |\n\n### 高级 API（默认禁用 ⚠️）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Map** | 标准 | 1/10 页 | ~10,000 页 |\n| **Map** | 带指令 | 2/10 页 | ~5,000 页 |\n| **Crawl** | basic | ~3/10 页 | ~3,300 页 |\n| **Crawl** | advanced | ~5/10 页 | ~2,000 页 |\n\n### 研究 API（极度昂贵 ⚠️⚠️）\n\n| API | 模型 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Research** | mini | 4-110/次 | 9-250 次 |\n| **Research** | pro | 15-250/次 | 4-66 次 |\n\n**免费额度**: 1000 信用/月\n\n### 安全控制\n\n| API | 默认状态 | 启用方式 |\n|-----|---------|---------|\n| Search | ✅ 启用 | 直接使用 |\n| Extract | ✅ 启用 | 直接使用 |\n| Usage | ✅ 启用 | 直接使用 |\n| Map | ❌ 禁用 | `--enable` |\n| Crawl | ❌ 禁用 | `--enable` |\n| Research | ❌ 禁用 | `--enable --confirm` |\n\n### 节省信用技巧\n1. 日常使用 Search/Extract/Usage\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n5. 批量提取 URL（5 个 URL = 1 信用）\n6. **谨慎使用 Crawl/Map/Research**\n\n### 主题分类\n- `general` - 通用搜索（默认）\n- `news` - 新闻（包含 `published_date`）\n- `finance` - 财经\n\n### 时间过滤\n- `--time-range`: `day` / `week` / `month` / `year`\n- `--start-date`: YYYY-MM-DD\n- `--end-date`: YYYY-MM-DD\n\n### 输出格式\n- `compact` - 简洁 Markdown（默认）\n- `md` - 详细 Markdown（包含分数、完整内容）\n- `brave` - JSON（兼容 web_search 格式）\n- `raw` - 原始 JSON（包含所有字段）\n\n## 💰 API 信用说明\n\n| 操作 | 信用消耗 |\n|------|----------|\n| basic/fast/ultra-fast 搜索 | 1 |\n| advanced 搜索 | 2 |\n| include_answer (advanced) | +1 |\n| include_raw_content | +1 |\n| include_images | +1 |\n\n**免费额度**: 1000 信用/月\n\n### 节省信用技巧\n1. 使用 `basic` 深度进行日常搜索\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n\n## 🔄 自动更新\n\nTavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。\n\n### 手动检查更新\n```bash\n# 检查是否有更新\npython3 {baseDir}/scripts/update.py --check-only\n\n# 应用更新\npython3 {baseDir}/scripts/update.py\n\n# 强制更新（即使无变更）\npython3 {baseDir}/scripts/update.py --force\n\n# 查看状态\npython3 {baseDir}/scripts/update.py --status\n```\n\n### 自动更新（推荐）\n添加每周检查的 cron 任务：\n```bash\n# 编辑 crontab\ncrontab -e\n\n# 添加每周日 9:00 检查更新\n0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1\n```\n\n### 更新日志\n- 更新记录：`{baseDir}/update.log`\n- 最后检查：`{baseDir}/.last_check`\n- 版本信息：`{baseDir}/_meta.json`\n\n## 📁 文件位置\n\n```\n~/.openclaw/\n├── .env                          # API key 配置\n├── cache/tavily/                 # 缓存目录\n│   ├── search/                   # Search 缓存\n│   ├── extract/                  # Extract 缓存\n│   ├── crawl/                    # Crawl 缓存\n│   ├── map/                      # Map 缓存\n│   └── research/                 # Research 缓存\n├── logs/\n│   ├── tavily.log                # Search 日志\n│   ├── tavily_extract.log        # Extract 日志\n│   ├── tavily_usage.log          # Usage 日志\n│   ├── tavily_crawl.log          # Crawl 日志\n│   ├── tavily_map.log            # Map 日志\n│   └── tavily_research.log       # Research 日志\n└── workspace/skills/tavily-web-search/\n    ├── SKILL.md                  # 本文档\n    ├── README.md                 # 快速开始\n    ├── CHANGELOG.md              # 更新日志\n    ├── _meta.json                # 版本信息\n    ├── update.log                # 更新日志\n    ├── .last_check               # 最后检查记录\n    └── scripts/\n        ├── search.py             # Search API（搜索）✅ 默认启用\n        ├── extract.py            # Extract API（URL 提取）✅ 默认启用\n        ├── usage.py              # Usage API（使用量查询）✅ 默认启用\n        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用\n        ├── map.py                # Map API（网站地图）❌ 默认禁用\n        ├── research.py           # Research API（深度研究）❌ 默认禁用\n        ├── update.py             # 自动更新脚本\n        └── test_all.py           # 测试套件\n```\n\n## 🔧 故障排除\n\n### \"Missing TAVILY_API_KEY\"\n```bash\n# 检查配置\ncat ~/.openclaw/.env | grep TAVILY\n\n# 或设置环境变量\nexport TAVILY_API_KEY=\"tvly-xxx\"\n```\n\n### \"Search failed after 3 attempts\"\n- 检查网络连接\n- 查看日志：`tail -f ~/.openclaw/logs/tavily.log`\n- 验证 API key: https://app.tavily.com/home\n\n### 清除缓存\n```bash\nrm -rf ~/.openclaw/cache/tavily/*\n```\n\n### 禁用缓存\n```bash\npython3 {baseDir}/scripts/search.py --query \"test\" --no-cache\n```\n\n## 📚 参考链接\n\n- 官方文档：https://docs.tavily.com\n- API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search\n- 最佳实践：https://docs.tavily.com/documentation/best-practices/best-practices-search\n- 管理平台：https://app.tavily.com\n\nFile v2.0.3:README.md\n\n# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com\n\nFile v2.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.0.3\",\n  \"publishedAt\": 1774138403101\n}\n\nFile v2.0.3:CHANGELOG.md\n\n# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n- ✅ SKILL.md - 添加 Extract 和 Usage 完整文档\n- ✅ README.md - 更新使用示例\n- ✅ _meta.json - 版本更新到 1.1.0\n\n---\n\n## 📊 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 |\n|-----|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 |\n| Crawl | `/crawl` | ❌ | - | 3-5 信用/10 页 |\n| Map | `/map` | ❌ | - | 1-2 信用/10 页 |\n| Research | `/research` | ❌ | - | 4-250 信用/次 |\n\n---\n\n## 💰 成本对比\n\n### 免费额度（1000 信用/月）能做：\n\n| 操作 | 次数 |\n|------|------|\n| Search (basic) | 1,000 次 |\n| Search (advanced) | 500 次 |\n| Extract (basic) | 5,000 个 URL |\n| Extract (advanced) | 2,500 个 URL |\n| Usage | 无限次 |\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md                  # 完整文档\n├── README.md                 # 快速开始\n├── _meta.json                # 版本信息 (v1.1.0)\n├── CHANGELOG.md              # 本文件\n├── update.log                # 更新日志\n├── .last_check               # 最后检查记录\n└── scripts/\n    ├── search.py             # Search API (592 行)\n    ├── extract.py            # Extract API (464 行)\n    ├── usage.py              # Usage API (307 行)\n    ├── update.py             # 自动更新 (315 行)\n    └── test_all.py           # 测试套件 (120 行)\n```\n\n**总代码量**: ~1,800 行\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py --quick\n\n📍 Testing Search API...\n✅ PASS - search.py --query \"Python tutorial\"\n✅ PASS - search.py --query \"AI news\" --topic news\n✅ PASS - search.py --query \"Python\" --include-domains python.org\n✅ PASS - search.py --query \"test\" --format raw\n\n📊 TEST SUMMARY\nPassed: 4/4\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n# 发布 v1.1.0\nclawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 1.1.0\n\n# 输出\n✔ OK. Published tavily-web-search-full@1.1.0\n```\n\n---\n\n## 📈 使用统计\n\n### 典型工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n# 输出：Used: 150 | Remaining: 850 | Total: 1,000\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"AI trends 2026\" --max-results 5\n\n# 3. 提取感兴趣的文章\npython3 scripts/extract.py --urls \"https://example.com/article1,https://example.com/article2\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n# 输出：Used: 151 | Remaining: 849 | Total: 1,000\n```\n\n---\n\n## 🎯 下一步计划\n\n### 可选扩展\n- [ ] Crawl API（网站爬取）\n- [ ] Map API（网站地图）\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 结果评分过滤\n\n### 优化建议\n- [x] ✅ 添加 Extract API\n- [x] ✅ 添加 Usage API\n- [x] ✅ 完整测试套件\n- [ ] 性能基准测试\n- [ ] 更多输出格式模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n\n---\n\n**版本**: 1.1.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT\n\nFile v2.0.3:RATE_LIMIT.md\n\n# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] Success: 5 results\n```\n\n### 遇到 Rate Limit\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[INFO] Success: 5 results\n```\n\n### 超过限制\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[WARN] Rate limited. Waiting 4.0s before retry...\n[DEBUG] Request attempt 3/3: test...\n[ERROR] All 3 retries failed: Rate limit exceeded\n```\n\n## 🎯 最佳实践\n\n### 1. 批量请求时的延迟\n\n```python\n# ❌ 不好 - 快速连续请求\nfor query in queries:\n    search(query)\n\n# ✅ 好 - 添加延迟\nimport time\nfor query in queries:\n    search(query)\n    time.sleep(0.5)  # 每秒 2 个请求\n```\n\n### 2. 监控使用量\n\n```bash\n# 定期检查使用量\npython3 scripts/usage.py\n```\n\n### 3. 使用缓存\n\n```bash\n# 启用缓存（默认开启）\npython3 scripts/search.py --query \"test\"\n\n# 强制刷新（禁用缓存）\npython3 scripts/search.py --query \"test\" --no-cache\n```\n\n### 4. 了解限制\n\n- **Development Key**: 100 RPM = 每秒~1.6 个请求\n- **Production Key**: 1,000 RPM = 每秒~16 个请求\n\n## 📚 相关文件\n\n- `scripts/rate_limit.py` - Rate Limit 处理器\n- `scripts/search.py` - 已集成\n- `scripts/extract.py` - 已集成\n- https://docs.tavily.com/documentation/rate-limits.md - 官方文档\n\n## 🔄 后续更新\n\n待更新的脚本：\n- [ ] `crawl.py`\n- [ ] `map.py`\n- [ ] `research.py`\n- [ ] `usage.py`\n\n更新方法：\n```python\n# 1. 添加导入\nfrom rate_limit import rate_limit_handler\n\n# 2. 添加装饰器\n@rate_limit_handler(max_retries=MAX_RETRIES, base_delay=RETRY_DELAY, log_func=log)\ndef api_function():\n    # ...\n```\n\n---\n\n**版本**: 1.0.0  \n**更新日期**: 2026-03-22  \n**基于**: Tavily Rate Limits 官方文档\n\nFile v2.0.3:RELEASE_NOTES.md\n\n# Tavily Web Search Skill - v2.0.0 发布总结\n\n## 🎉 重大更新\n\n版本 2.0.0 实现了 Tavily **全部 6 个官方 API**，并引入了智能安全控制机制。\n\n---\n\n## 📦 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 | 默认 |\n|-----|------|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 | ✅ 启用 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL | ✅ 启用 |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 | ✅ 启用 |\n| **Crawl** | `/crawl` | ✅ 100% | `crawl.py` | 3-5 信用/10 页 | ❌ 禁用 |\n| **Map** | `/map` | ✅ 100% | `map.py` | 1-2 信用/10 页 | ❌ 禁用 |\n| **Research** | `/research` | ✅ 100% | `research.py` | 4-250 信用/次 | ❌ 禁用 |\n\n**总代码量**: ~3,500 行\n\n---\n\n## 🔒 安全控制机制\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n### 实现方式\n\n| API | 安全级别 | 启用方式 | 警告信息 |\n|-----|---------|---------|---------|\n| Search | ✅ 无 | 直接使用 | 无 |\n| Extract | ✅ 无 | 直接使用 | 无 |\n| Usage | ✅ 无 | 直接使用 | 无 |\n| Crawl | ⚠️ 中等 | `--enable` | 成本警告 |\n| Map | ⚠️ 中等 | `--enable` | 成本警告 |\n| Research | ⚠️⚠️ 高 | `--enable --confirm` | 强烈警告 |\n\n### 代码示例\n\n```python\n# Crawl API - 单标志确认\nif not args.enable:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable to proceed\", file=sys.stderr)\n    sys.exit(1)\n\n# Research API - 双重确认\nif not args.enable or not args.confirm:\n    print(COST_WARNING, file=sys.stderr)\n    print(\"❌ Error: Use --enable AND --confirm\", file=sys.stderr)\n    sys.exit(1)\n```\n\n---\n\n## 📊 成本对比\n\n### 免费额度（1000 信用/月）\n\n| API | 使用次数 |\n|-----|---------|\n| Search (basic) | 1,000 次 |\n| Extract (basic) | 5,000 URL |\n| Usage | 无限 |\n| Map | 5,000-10,000 页 |\n| Crawl | 2,000-3,300 页 |\n| Research (mini) | 9-250 次 |\n| Research (pro) | 4-66 次 |\n\n### 典型使用场景\n\n#### 日常开发（推荐）\n```bash\n# 搜索文档\npython3 scripts/search.py --query \"Python async tutorial\"\n\n# 提取文章内容\npython3 scripts/extract.py --urls \"https://realpython.com/article\"\n\n# 查看使用量\npython3 scripts/usage.py\n```\n\n**成本**: ~2-3 信用\n\n#### 网站分析（偶尔）\n```bash\n# 生成网站地图\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 爬取特定内容\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find pricing\"\n```\n\n**成本**: ~10-20 信用\n\n#### 深度研究（谨慎）\n```bash\n# 市场分析报告\npython3 scripts/research.py --query \"AI market 2026\" --enable --confirm\n```\n\n**成本**: 50-150 信用\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py\n\n📍 Testing Search API...\n✅ PASS (4 tests)\n\n📄 Testing Extract API...\n✅ PASS (4 tests)\n\n📊 Testing Usage API...\n✅ PASS (3 tests)\n\n🔒 Testing safety controls...\n✅ PASS (4 tests - all correctly disabled)\n\n============================================================\n📊 TEST SUMMARY\n============================================================\nPassed: 15/15\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md (15KB)         # 完整文档\n├── README.md (2.5KB)       # 快速开始\n├── CHANGELOG.md (8KB)      # 更新日志\n├── RELEASE_NOTES.md        # 本文件\n├── _meta.json              # v2.0.0 + 安全配置\n└── scripts/\n    ├── search.py (592 行)   # Search API ✅\n    ├── extract.py (464 行)  # Extract API ✅\n    ├── usage.py (307 行)    # Usage API ✅\n    ├── crawl.py (532 行)    # Crawl API ❌ (--enable)\n    ├── map.py (467 行)      # Map API ❌ (--enable)\n    ├── research.py (481 行) # Research API ❌ (--enable --confirm)\n    ├── update.py (315 行)   # 自动更新\n    └── test_all.py (180 行) # 测试套件\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n$ clawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 2.0.0\n\n- Preparing tavily-web-search-full@2.0.0\n✔ OK. Published tavily-web-search-full@2.0.0 (k9737e5bh0ac5td2ag6yvcsjm183bfyk)\n```\n\n- **ClawHub Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **状态**: ✅ 已发布\n\n---\n\n## 📈 使用建议\n\n### ✅ 推荐工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"your topic\" --max-results 5\n\n# 3. 提取感兴趣的内容\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 何时使用高级 API\n\n**使用 Crawl 当：**\n- 需要爬取整个网站\n- Search API 找不到足够信息\n- 有明确的爬取目标\n\n**使用 Map 当：**\n- 需要完整的网站地图\n- 准备批量处理网站页面\n- 需要了解网站结构\n\n**使用 Research 当：**\n- 需要深度分析报告\n- 预算充足（>100 信用）\n- Search API 无法满足需求\n\n### ❌ 避免的陷阱\n\n1. **不要随意使用 Research** - 几次就用光月度额度\n2. **Crawl 时设置 limit** - 避免爬取过多页面\n3. **始终先检查 usage** - 了解剩余额度\n\n---\n\n## 🎯 下一步计划\n\n### 已完成\n- ✅ 全部 6 个官方 API\n- ✅ 智能安全控制\n- ✅ 完整测试套件\n- ✅ 自动更新功能\n- ✅ 详细文档\n\n### 可选扩展\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 批量处理脚本\n- [ ] 结果评分过滤\n- [ ] 更多输出模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n- **最佳实践**: https://docs.tavily.com/documentation/best-practices\n\n---\n\n## 💡 关键决策\n\n### 为什么默认禁用 Crawl/Map/Research？\n\n1. **成本考虑**\n   - Research 单次最高 250 信用（1/4 月度额度）\n   - 新手可能无意中快速消耗信用\n\n2. **使用频率**\n   - 90% 场景 Search+Extract 足够\n   - Crawl/Map/Research 是特殊需求\n\n3. **用户体验**\n   - 默认启用可能导致意外消费\n   - 明确确认避免误用\n\n### 为什么 Research 需要双重确认？\n\n- **极端成本**: 4-250 信用/次\n- **不可逆**: 一旦开始无法取消\n- **替代方案**: Search API 通常够用\n- **教育意义**: 让用户三思而后行\n\n---\n\n**版本**: 2.0.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT  \n**测试通过率**: 100% (15/15)\n\nArchive v2.1.0: 16 files, 50308 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (12893b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/unified_search.py (9050b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (15062b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.0\nmetadata: {\"clawdbot\":{\"emoji\":\"🔍\",\"requires\":{\"bins\":[\"python3\"],\"env\":[\"TAVILY_API_KEY\"]},\"primaryEnv\":\"TAVILY_API_KEY\"}}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\"\n```\n\n### 🕷️ Crawl API（网站爬取）⚠️ 默认禁用\n\n**成本**: 3-5 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20\n```\n\n### 🗺️ Map API（网站地图）⚠️ 默认禁用\n\n**成本**: 1-2 信用/10 页 | **必须使用 `--enable`**\n\n```bash\n# 生成网站地图\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --instructions \"find all blog posts\"\n\n# 输出 URL 列表\npython3 {baseDir}/scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n### 📚 Research API（深度研究）⚠️⚠️ 强烈建议默认禁用\n\n**成本**: 4-250 信用/次 | **必须使用 `--enable --confirm`**\n\n```bash\n# 深度研究（必须使用 --enable AND --confirm）\npython3 {baseDir}/scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型（更贵但质量更高）\npython3 {baseDir}/scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 新闻搜索\n```bash\n# 今日新闻\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 本周财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --topic finance --time-range week\n\n# 指定日期范围\npython3 {baseDir}/scripts/search.py --query \"election results\" --start-date 2025-01-01 --end-date 2025-01-31\n```\n\n### 深度研究\n```bash\n# 高级模式（最高相关性，2 信用/次）\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 包含完整页面内容\npython3 {baseDir}/scripts/search.py --query \"React best practices\" --include-raw-content markdown\n\n# 详细 AI 答案\npython3 {baseDir}/scripts/search.py --query \"climate change impact\" --answer-type advanced\n```\n\n### 域名过滤\n```bash\n# 只搜索特定网站\npython3 {baseDir}/scripts/search.py --query \"JavaScript tips\" --include-domains \"github.com,dev.to,medium.com\"\n\n# 排除某些网站\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\" --exclude-domains \"w3schools.com\"\n\n# 组合使用\npython3 {baseDir}/scripts/search.py --query \"Rust programming\" --include-domains \"rust-lang.org,docs.rs\" --exclude-domains \"reddit.com\"\n```\n\n### 国家/地区定向\n```bash\n# 美国科技新闻\npython3 {baseDir}/scripts/search.py --query \"tech startups\" --country \"united states\" --topic news\n\n# 中国财经\npython3 {baseDir}/scripts/search.py --query \"stock market\" --country \"china\" --topic finance\n```\n\n### 图片搜索\n```bash\n# 搜索图片\npython3 {baseDir}/scripts/search.py --query \"sunset photography\" --include-images\n\n# 带描述\npython3 {baseDir}/scripts/search.py --query \"machine learning\" --include-images --include-image-descriptions\n```\n\n### 快速搜索（低延迟）\n```bash\n# 快速模式（1 信用，低延迟）\npython3 {baseDir}/scripts/search.py --query \"weather today\" --search-depth fast\n\n# 超快速（1 信用，最低延迟）\npython3 {baseDir}/scripts/search.py --query \"stock price\" --search-depth ultra-fast\n```\n\n### 自动参数\n```bash\n# 让 Tavily 自动配置（可能使用 advanced=2 信用）\npython3 {baseDir}/scripts/search.py --query \"comprehensive analysis of AI trends\" --auto-parameters\n\n# 自动参数但手动控制深度（控制成本）\npython3 {baseDir}/scripts/search.py --query \"research query\" --auto-parameters --search-depth basic\n```\n\n### 精确匹配\n```bash\n# 精确搜索人名/公司名\npython3 {baseDir}/scripts/search.py --query '\"John Smith\" CEO Acme Corp' --exact-match\n```\n\n## 📋 完整参数说明\n\n```bash\npython3 {baseDir}/scripts/search.py --help\n```\n\n### 必需参数\n| 参数 | 说明 |\n|------|------|\n| `--query` | 搜索关键词（建议 <400 字符） |\n\n### 搜索深度\n| 参数值 | 延迟 | 相关性 | 内容类型 | 信用 |\n|--------|------|--------|----------|------|\n| `ultra-fast` | 最低 | 较低 | NLP 摘要 | 1 |\n| `fast` | 低 | 良好 | 相关片段 | 1 |\n| `basic` | 中等 | 高 | NLP 摘要 | 1 |\n| `advanced` | 较高 | 最高 | 相关片段 | 2 |\n\n## 💡 最佳实践\n\n### 查询优化\n- ✅ **保持查询简洁** - 建议 <400 字符\n- ✅ **复杂查询拆分** - 分成多个小查询\n- ✅ **使用精确匹配** - 人名/公司名用 `--exact-match`\n- ✅ **合理设置 max-results** - 3-5 个足够（默认 5）\n\n### 搜索深度选择\n- `basic` - 日常搜索（推荐）\n- `advanced` - 深度研究（特定问题）\n- `fast` / `ultra-fast` - 实时应用\n\n### 结果过滤\n```bash\n# 按相关性分数过滤\npython3 scripts/search.py --query \"Python\" --min-score 0.7\n\n# 只搜索特定域名\npython3 scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n\n# 排除低质量站点\npython3 scripts/search.py --query \"AI\" --exclude-domains \"content-farm.com\"\n```\n\n### 成本优化\n- ⚠️ **auto_parameters 可能使用 advanced**（2 信用）\n- ✅ 手动设置 `--search-depth basic` 控制成本\n- ✅ 使用缓存（默认开启）\n- ✅ 批量提取 URL（5 个 URL = 1 信用）\n\n## 💰 API 信用说明\n\n### 日常 API（推荐）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Search** | basic/fast/ultra-fast | 1/次 | 1,000 次 |\n| **Search** | advanced | 2/次 | 500 次 |\n| **Extract** | basic | 1/5 URL | 5,000 URL |\n| **Extract** | advanced | 2/5 URL | 2,500 URL |\n| **Usage** | 查询 | 免费 | 无限 |\n\n### 高级 API（默认禁用 ⚠️）\n\n| API | 操作 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Map** | 标准 | 1/10 页 | ~10,000 页 |\n| **Map** | 带指令 | 2/10 页 | ~5,000 页 |\n| **Crawl** | basic | ~3/10 页 | ~3,300 页 |\n| **Crawl** | advanced | ~5/10 页 | ~2,000 页 |\n\n### 研究 API（极度昂贵 ⚠️⚠️）\n\n| API | 模型 | 信用消耗 | 免费额度可用次数 |\n|-----|------|----------|----------------|\n| **Research** | mini | 4-110/次 | 9-250 次 |\n| **Research** | pro | 15-250/次 | 4-66 次 |\n\n**免费额度**: 1000 信用/月\n\n### 安全控制\n\n| API | 默认状态 | 启用方式 |\n|-----|---------|---------|\n| Search | ✅ 启用 | 直接使用 |\n| Extract | ✅ 启用 | 直接使用 |\n| Usage | ✅ 启用 | 直接使用 |\n| Map | ❌ 禁用 | `--enable` |\n| Crawl | ❌ 禁用 | `--enable` |\n| Research | ❌ 禁用 | `--enable --confirm` |\n\n### 节省信用技巧\n1. 日常使用 Search/Extract/Usage\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n5. 批量提取 URL（5 个 URL = 1 信用）\n6. **谨慎使用 Crawl/Map/Research**\n\n### 主题分类\n- `general` - 通用搜索（默认）\n- `news` - 新闻（包含 `published_date`）\n- `finance` - 财经\n\n### 时间过滤\n- `--time-range`: `day` / `week` / `month` / `year`\n- `--start-date`: YYYY-MM-DD\n- `--end-date`: YYYY-MM-DD\n\n### 输出格式\n- `compact` - 简洁 Markdown（默认）\n- `md` - 详细 Markdown（包含分数、完整内容）\n- `brave` - JSON（兼容 web_search 格式）\n- `raw` - 原始 JSON（包含所有字段）\n\n## 💰 API 信用说明\n\n| 操作 | 信用消耗 |\n|------|----------|\n| basic/fast/ultra-fast 搜索 | 1 |\n| advanced 搜索 | 2 |\n| include_answer (advanced) | +1 |\n| include_raw_content | +1 |\n| include_images | +1 |\n\n**免费额度**: 1000 信用/月\n\n### 节省信用技巧\n1. 使用 `basic` 深度进行日常搜索\n2. 启用缓存（默认开启）\n3. 设置合理的 `max-results`（3-5 足够）\n4. 避免不必要的 `include_raw_content`\n\n## 🔄 自动更新\n\nTavily API 约每月更新 1-2 次。Skill 包含自动更新功能，定期检查官方 API 变更。\n\n### 手动检查更新\n```bash\n# 检查是否有更新\npython3 {baseDir}/scripts/update.py --check-only\n\n# 应用更新\npython3 {baseDir}/scripts/update.py\n\n# 强制更新（即使无变更）\npython3 {baseDir}/scripts/update.py --force\n\n# 查看状态\npython3 {baseDir}/scripts/update.py --status\n```\n\n### 自动更新（推荐）\n添加每周检查的 cron 任务：\n```bash\n# 编辑 crontab\ncrontab -e\n\n# 添加每周日 9:00 检查更新\n0 9 * * 0 cd ~/.openclaw/workspace/skills/tavily-web-search && python3 scripts/update.py >> /tmp/tavily-update.log 2>&1\n```\n\n### 更新日志\n- 更新记录：`{baseDir}/update.log`\n- 最后检查：`{baseDir}/.last_check`\n- 版本信息：`{baseDir}/_meta.json`\n\n## 📁 文件位置\n\n```\n~/.openclaw/\n├── .env                          # API key 配置\n├── cache/tavily/                 # 缓存目录\n│   ├── search/                   # Search 缓存\n│   ├── extract/                  # Extract 缓存\n│   ├── crawl/                    # Crawl 缓存\n│   ├── map/                      # Map 缓存\n│   └── research/                 # Research 缓存\n├── logs/\n│   ├── tavily.log                # Search 日志\n│   ├── tavily_extract.log        # Extract 日志\n│   ├── tavily_usage.log          # Usage 日志\n│   ├── tavily_crawl.log          # Crawl 日志\n│   ├── tavily_map.log            # Map 日志\n│   └── tavily_research.log       # Research 日志\n└── workspace/skills/tavily-web-search/\n    ├── SKILL.md                  # 本文档\n    ├── README.md                 # 快速开始\n    ├── CHANGELOG.md              # 更新日志\n    ├── _meta.json                # 版本信息\n    ├── update.log                # 更新日志\n    ├── .last_check               # 最后检查记录\n    └── scripts/\n        ├── search.py             # Search API（搜索）✅ 默认启用\n        ├── extract.py            # Extract API（URL 提取）✅ 默认启用\n        ├── usage.py              # Usage API（使用量查询）✅ 默认启用\n        ├── crawl.py              # Crawl API（网站爬取）❌ 默认禁用\n        ├── map.py                # Map API（网站地图）❌ 默认禁用\n        ├── research.py           # Research API（深度研究）❌ 默认禁用\n        ├── update.py             # 自动更新脚本\n        └── test_all.py           # 测试套件\n```\n\n## 🔧 故障排除\n\n### \"Missing TAVILY_API_KEY\"\n```bash\n# 检查配置\ncat ~/.openclaw/.env | grep TAVILY\n\n# 或设置环境变量\nexport TAVILY_API_KEY=\"tvly-xxx\"\n```\n\n### \"Search failed after 3 attempts\"\n- 检查网络连接\n- 查看日志：`tail -f ~/.openclaw/logs/tavily.log`\n- 验证 API key: https://app.tavily.com/home\n\n### 清除缓存\n```bash\nrm -rf ~/.openclaw/cache/tavily/*\n```\n\n### 禁用缓存\n```bash\npython3 {baseDir}/scripts/search.py --query \"test\" --no-cache\n```\n\n## 📚 参考链接\n\n- 官方文档：https://docs.tavily.com\n- API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search\n- 最佳实践：https://docs.tavily.com/documentation/best-practices/best-practices-search\n- 管理平台：https://app.tavily.com\n\nFile v2.1.0:README.md\n\n# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com\n\nFile v2.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.1.0\",\n  \"publishedAt\": 1774138127031\n}\n\nFile v2.1.0:CHANGELOG.md\n\n# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n- ✅ SKILL.md - 添加 Extract 和 Usage 完整文档\n- ✅ README.md - 更新使用示例\n- ✅ _meta.json - 版本更新到 1.1.0\n\n---\n\n## 📊 完整 API 支持\n\n| API | 端点 | 状态 | 脚本 | 成本 |\n|-----|------|------|------|------|\n| **Search** | `/search` | ✅ 100% | `search.py` | 1-2 信用/次 |\n| **Extract** | `/extract` | ✅ 100% | `extract.py` | 1-2 信用/5 URL |\n| **Usage** | `/usage` | ✅ 100% | `usage.py` | 免费 |\n| Crawl | `/crawl` | ❌ | - | 3-5 信用/10 页 |\n| Map | `/map` | ❌ | - | 1-2 信用/10 页 |\n| Research | `/research` | ❌ | - | 4-250 信用/次 |\n\n---\n\n## 💰 成本对比\n\n### 免费额度（1000 信用/月）能做：\n\n| 操作 | 次数 |\n|------|------|\n| Search (basic) | 1,000 次 |\n| Search (advanced) | 500 次 |\n| Extract (basic) | 5,000 个 URL |\n| Extract (advanced) | 2,500 个 URL |\n| Usage | 无限次 |\n\n---\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md                  # 完整文档\n├── README.md                 # 快速开始\n├── _meta.json                # 版本信息 (v1.1.0)\n├── CHANGELOG.md              # 本文件\n├── update.log                # 更新日志\n├── .last_check               # 最后检查记录\n└── scripts/\n    ├── search.py             # Search API (592 行)\n    ├── extract.py            # Extract API (464 行)\n    ├── usage.py              # Usage API (307 行)\n    ├── update.py             # 自动更新 (315 行)\n    └── test_all.py           # 测试套件 (120 行)\n```\n\n**总代码量**: ~1,800 行\n\n---\n\n## 🧪 测试结果\n\n```bash\n$ python3 scripts/test_all.py --quick\n\n📍 Testing Search API...\n✅ PASS - search.py --query \"Python tutorial\"\n✅ PASS - search.py --query \"AI news\" --topic news\n✅ PASS - search.py --query \"Python\" --include-domains python.org\n✅ PASS - search.py --query \"test\" --format raw\n\n📊 TEST SUMMARY\nPassed: 4/4\nSuccess Rate: 100.0%\n✅ All tests passed!\n```\n\n---\n\n## 🚀 发布到 ClawHub\n\n```bash\n# 发布 v1.1.0\nclawhub publish skills/tavily-web-search --slug tavily-web-search-full --version 1.1.0\n\n# 输出\n✔ OK. Published tavily-web-search-full@1.1.0\n```\n\n---\n\n## 📈 使用统计\n\n### 典型工作流\n\n```bash\n# 1. 先查看使用量\npython3 scripts/usage.py\n# 输出：Used: 150 | Remaining: 850 | Total: 1,000\n\n# 2. 搜索相关信息\npython3 scripts/search.py --query \"AI trends 2026\" --max-results 5\n\n# 3. 提取感兴趣的文章\npython3 scripts/extract.py --urls \"https://example.com/article1,https://example.com/article2\"\n\n# 4. 再次检查使用量\npython3 scripts/usage.py\n# 输出：Used: 151 | Remaining: 849 | Total: 1,000\n```\n\n---\n\n## 🎯 下一步计划\n\n### 可选扩展\n- [ ] Crawl API（网站爬取）\n- [ ] Map API（网站地图）\n- [ ] Project ID 支持（项目追踪）\n- [ ] 异步并发搜索\n- [ ] 结果评分过滤\n\n### 优化建议\n- [x] ✅ 添加 Extract API\n- [x] ✅ 添加 Usage API\n- [x] ✅ 完整测试套件\n- [ ] 性能基准测试\n- [ ] 更多输出格式模板\n\n---\n\n## 📚 相关链接\n\n- **ClawHub**: https://clawhub.com/skills/tavily-web-search-full\n- **Tavily 官方**: https://tavily.com\n- **API 文档**: https://docs.tavily.com\n- **定价**: https://docs.tavily.com/documentation/api-credits.md\n\n---\n\n**版本**: 1.1.0  \n**发布日期**: 2026-03-22  \n**作者**: System  \n**许可**: MIT\n\nFile v2.1.0:RATE_LIMIT.md\n\n# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] S\n\nArchive v2.0.2: 15 files, 47653 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (12893b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17990b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (15062b)\n\nArchive v2.0.1: 15 files, 47071 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), RATE_LIMIT.md (4121b), README.md (3201b), RELEASE_NOTES.md (6864b), scripts/crawl.py (15938b), scripts/extract.py (12893b), scripts/map.py (14532b), scripts/rate_limit.py (5148b), scripts/research.py (14529b), scripts/search.py (17159b), scripts/test_all.py (4953b), scripts/update.py (12688b), scripts/usage.py (9415b), SKILL.md (14095b)\n\nArchive v2.0.0: 12 files, 40409 bytes\n\nFiles: _meta.json (141b), CHANGELOG.md (7680b), README.md (3201b), scripts/crawl.py (15938b), scripts/extract.py (14381b), scripts/map.py (14532b), scripts/research.py (14529b), scripts/search.py (18552b), scripts/test_all.py (4953b), scripts/update.py (10432b), scripts/usage.py (9415b), SKILL.md (14095b)\n\nArchive v1.1.0: 7 files, 21585 bytes\n\nFiles: _meta.json (141b), README.md (2842b), scripts/extract.py (14381b), scripts/search.py (18552b), scripts/update.py (10432b), scripts/usage.py (9415b), SKILL.md (11033b)\n\nArchive v1.0.1: 5 files, 13284 bytes\n\nFiles: _meta.json (141b), README.md (1093b), scripts/search.py (18552b), scripts/update.py (9651b), SKILL.md (8459b)","readmeExcerpt":"Skill: Tavily Web Search Owner: brucetangc Summary: Full-featured Tavily web search with auto-update. All official API parameters supported. AI-optimized search for agents and RAG workflows. Tags: latest:2.0.6 Version history: v2.0.6 | 2026-03-22T14:56:36.782Z | user v2.0.6: Fixed metadata declarations (network access) + Security scan improvements v2.0.5 | 2026-03-22T13:31:33.335Z | user v2.0.5: Fix extract.py rate_l","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"clawhub install tavily-web-search-full"},{"language":"bash","snippet":"# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\""},{"language":"bash","snippet":"# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\""},{"language":"bash","snippet":"# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text"},{"language":"bash","snippet":"# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {baseDir}/scripts/usage.py --md\n\n# JSON 输出\npython3 {baseDir}/scripts/usage.py --json\n\n# 查询特定项目\npython3 {baseDir}/scripts/usage.py --project-id \"my-project-123\""},{"language":"bash","snippet":"# 爬取网站（必须使用 --enable）\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令爬取\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n\n# 限制页数\npython3 {baseDir}/scripts/crawl.py --url \"https://example.com\" --enable --limit 20"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: tavily-web-search\ndescription: Complete Tavily toolkit: Search, Extract, Usage, Crawl, Map, Research. All official APIs with safety controls.\nhomepage: https://tavily.com\nversion: 2.0.3\nmetadata: {\n  \"clawdbot\": {\n    \"emoji\": \"🔍\",\n    \"requires\": {\n      \"bins\": [\"python3\"],\n      \"env\": [\"TAVILY_API_KEY\"]\n    },\n    \"primaryEnv\": \"TAVILY_API_KEY\"\n  }\n}\n---\n\n# Tavily Web Search\n\n完整功能的 Tavily 网络搜索工具，基于官方 API 文档实现。专为 AI Agent 和 RAG 工作流设计。\n\n## ✨ 功能特性\n\n### 核心功能\n- 🔄 **自动重试** - 3 次重试 + 指数退避\n- 💾 **查询缓存** - 1 小时 TTL，节省 API 额度\n- 📝 **详细日志** - `~/.openclaw/logs/tavily.log`\n- 🎯 **多种输出** - JSON / Brave 兼容 / Markdown\n\n### 官方 API 完整支持\n| 功能 | 参数 | 说明 |\n|------|------|------|\n| **搜索深度** | `--search-depth` | `basic` / `advanced` / `fast` / `ultra-fast` |\n| **主题分类** | `--topic` | `general` / `news` / `finance` |\n| **时间过滤** | `--time-range` | `day` / `week` / `month` / `year` |\n| **日期范围** | `--start-date` / `--end-date` | YYYY-MM-DD 格式 |\n| **域名过滤** | `--include-domains` / `--exclude-domains` | 逗号分隔 |\n| **国家定向** | `--country` | `united states` / `china` 等 |\n| **AI 答案** | `--include-answer` / `--answer-type` | `basic` / `advanced` |\n| **完整内容** | `--include-raw-content` | `markdown` / `text` |\n| **图片搜索** | `--include-images` | 包含图片结果 |\n| **自动参数** | `--auto-parameters` | AI 自动配置 |\n| **精确匹配** | `--exact-match` | 精确短语匹配 |\n\n## 📦 安装\n\n### 从 ClawHub 安装（推荐）\n```bash\nclawhub install tavily-web-search-full\n```\n\n### 本地使用\nSkill 已放置在：`~/.openclaw/workspace/skills/tavily-web-search/`\n\n### 配置 API Key\n\n```bash\n# 方法 1: 添加到 ~/.openclaw/.env\necho \"TAVILY_API_KEY=tvly-your-key-here\" >> ~/.openclaw/.env\n\n# 方法 2: 环境变量\nexport TAVILY_API_KEY=\"tvly-your-key-here\"\n```\n\n获取 API Key: https://app.tavily.com/home (每月 1000 免费信用)\n\n## 🚀 使用示例\n\n### 🔍 Search API（搜索）\n\n```bash\n# 简单搜索（默认 compact Markdown 输出）\npython3 {baseDir}/scripts/search.py --query \"Python tutorial\"\n\n# 指定结果数量\npython3 {baseDir}/scripts/search.py --query \"Docker compose\" --max-results 10\n\n# 新闻搜索\npython3 {baseDir}/scripts/search.py --query \"AI breakthrough\" --topic news --time-range day\n\n# 深度研究\npython3 {baseDir}/scripts/search.py --query \"LLM architecture\" --search-depth advanced\n\n# 域名过滤\npython3 {baseDir}/scripts/search.py --query \"React\" --include-domains \"github.com,dev.to\"\n```\n\n### 📄 Extract API（URL 内容提取）\n\n```bash\n# 提取单个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 {baseDir}/scripts/extract.py --urls \"https://a.com,https://b.com,https://c.com\"\n\n# 带查询提取（按相关性重排内容）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --query \"find pricing information\"\n\n# 高级提取（更详细，2 信用/5 URL）\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --extract-depth advanced\n\n# 包含图片\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --include-images\n\n# 输出为纯文本\npython3 {baseDir}/scripts/extract.py --urls \"https://example.com\" --format text\n```\n\n### 📊 Usage API（使用量查询）\n\n```bash\n# 查看使用量（简洁模式）\npython3 {baseDir}/scripts/usage.py\n\n# 详细 Markdown 输出\npython3 {base"},{"path":"README.md","content":"# Tavily Web Search Skill - v2.0.0\n\n完整功能的 Tavily 工具包，包含所有 6 个官方 API。基于官方 API 文档实现。\n\n## 📦 ClawHub 发布\n\n- **Slug**: `tavily-web-search-full`\n- **版本**: 2.0.0\n- **发布**: ✅ 已发布到 ClawHub\n- **APIs**: Search + Extract + Usage + Crawl + Map + Research\n\n## 🚀 快速开始\n\n### ✅ 日常 API（默认启用）\n\n```bash\n# Search - 网络搜索\npython3 scripts/search.py --query \"你的问题\"\n\n# Extract - URL 内容提取\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# Usage - 查看使用量\npython3 scripts/usage.py\n```\n\n### ⚠️ 高级 API（默认禁用 - 需 `--enable`）\n\n```bash\n# Crawl - 网站爬取（3-5 信用/10 页）\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# Map - 网站地图（1-2 信用/10 页）\npython3 scripts/map.py --url \"https://example.com\" --enable\n```\n\n### ⚠️⚠️ 研究 API（极度昂贵 - 需 `--enable --confirm`）\n\n```bash\n# Research - 深度研究（4-250 信用/次）\npython3 scripts/research.py --query \"AI impact\" --enable --confirm\n```\n\n## 📊 API 对比\n\n| API | 默认 | 成本 | 启用方式 |\n|-----|------|------|---------|\n| **Search** | ✅ | 1-2 信用/次 | 直接使用 |\n| **Extract** | ✅ | 1-2 信用/5 URL | 直接使用 |\n| **Usage** | ✅ | 免费 | 直接使用 |\n| **Crawl** | ❌ | 3-5 信用/10 页 | `--enable` |\n| **Map** | ❌ | 1-2 信用/10 页 | `--enable` |\n| **Research** | ❌ | 4-250 信用/次 | `--enable --confirm` |\n\n## 💰 成本说明\n\n### 免费额度（1000 信用/月）可做：\n\n- **Search (basic)**: 1,000 次\n- **Extract (basic)**: 5,000 个 URL\n- **Map**: 5,000-10,000 页\n- **Crawl**: 2,000-3,300 页\n- **Research (mini)**: 9-250 次\n- **Research (pro)**: 4-66 次\n\n### 建议\n\n- ✅ **日常使用**: Search + Extract + Usage\n- ⚠️ **偶尔使用**: Crawl + Map（需要时加 `--enable`）\n- ❌ **谨慎使用**: Research（太贵，除非必要）\n\n## 📁 文件结构\n\n```\ntavily-web-search/\n├── SKILL.md              # 完整文档\n├── README.md             # 本文件\n├── CHANGELOG.md          # 更新日志\n├── _meta.json            # v2.0.0\n└── scripts/\n    ├── search.py         # Search API ✅\n    ├── extract.py        # Extract API ✅\n    ├── usage.py          # Usage API ✅\n    ├── crawl.py          # Crawl API ❌ (--enable)\n    ├── map.py            # Map API ❌ (--enable)\n    ├── research.py       # Research API ❌ (--enable --confirm)\n    ├── update.py         # 自动更新\n    └── test_all.py       # 测试套件\n```\n\n## 🔧 配置\n\n需要 API Key，添加到 `~/.openclaw/.env`:\n```\nTAVILY_API_KEY=tvly-your-key-here\n```\n\n获取 Key: https://app.tavily.com/home（1000 免费信用/月）\n\n## 📚 文档\n\n详细文档见 `SKILL.md` 或运行：\n```bash\npython3 scripts/search.py --help\npython3 scripts/extract.py --help\npython3 scripts/crawl.py --help\npython3 scripts/map.py --help\npython3 scripts/research.py --help\n```\n\n## 🔗 链接\n\n- ClawHub: https://clawhub.com/skills/tavily-web-search-full\n- Tavily 官方：https://tavily.com\n- API 文档：https://docs.tavily.com"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7afdk9ag1ftxjn0btmw2tj3h82y30x\",\n  \"slug\": \"tavily-web-search-full\",\n  \"version\": \"2.0.6\",\n  \"publishedAt\": 1774191396782\n}"},{"path":"CHANGELOG.md","content":"# Tavily Web Search Skill - 更新总结\n\n## 📦 版本 2.0.0 更新内容（重大更新）\n\n### 新增 API（默认禁用）\n\n#### 1. Crawl API（网站爬取）⚠️\n- **脚本**: `scripts/crawl.py`\n- **成本**: 3-5 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 智能网站遍历\n  - ✅ 自然语言指令\n  - ✅ 深度/广度控制\n  - ✅ 路径/域名过滤\n  - ✅ 自动缓存（2 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/crawl.py --url \"https://example.com\" --enable\n\n# 带指令\npython3 scripts/crawl.py --url \"https://example.com\" --enable --instructions \"find all pricing pages\"\n```\n\n#### 2. Map API（网站地图）⚠️\n- **脚本**: `scripts/map.py`\n- **成本**: 1-2 信用/10 页\n- **安全控制**: 必须使用 `--enable` 标志\n- **特性**:\n  - ✅ 快速生成网站地图\n  - ✅ 自然语言指令\n  - ✅ 多种输出格式（包括 URL 列表）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 必须使用 --enable\npython3 scripts/map.py --url \"https://example.com\" --enable\n\n# 输出 URL 列表\npython3 scripts/map.py --url \"https://example.com\" --enable --output urls\n```\n\n#### 3. Research API（深度研究）⚠️⚠️\n- **脚本**: `scripts/research.py`\n- **成本**: 4-250 信用/次（非常贵！）\n- **安全控制**: 必须使用 `--enable --confirm` 双重确认\n- **特性**:\n  - ✅ 深度研究报告\n  - ✅ 两种模型（mini/pro）\n  - ✅ 多源分析\n  - ✅ 自动缓存（24 小时）\n\n**使用示例**:\n```bash\n# 必须使用 --enable AND --confirm\npython3 scripts/research.py --query \"AI impact on healthcare\" --enable --confirm\n\n# Pro 模型\npython3 scripts/research.py --query \"market analysis\" --model pro --enable --confirm\n```\n\n### 安全控制策略\n\n| API | 默认状态 | 启用要求 | 原因 |\n|-----|---------|---------|------|\n| Search | ✅ 启用 | 无 | 便宜（1-2 信用） |\n| Extract | ✅ 启用 | 无 | 便宜（1-2 信用/5 URL） |\n| Usage | ✅ 启用 | 无 | 免费 |\n| Crawl | ❌ 禁用 | `--enable` | 较贵（3-5 信用/10 页） |\n| Map | ❌ 禁用 | `--enable` | 中等（1-2 信用/10 页） |\n| Research | ❌ 禁用 | `--enable --confirm` | 极贵（4-250 信用） |\n\n### 设计理念\n\n1. **日常 API 默认启用** - Search/Extract/Usage 足够满足 90% 场景\n2. **高级 API 需要确认** - 防止误用导致信用快速消耗\n3. **研究 API 双重确认** - 极端成本，必须明确意图\n\n---\n\n## 📦 版本 1.1.0 更新内容\n\n### 新增功能\n\n#### 1. Extract API（URL 内容提取）\n- **脚本**: `scripts/extract.py`\n- **功能**: 从指定 URL 提取完整内容\n- **成本**: 1 信用/5 个 URL（basic）或 2 信用/5 个 URL（advanced）\n- **特性**:\n  - ✅ 支持单个或多个 URL\n  - ✅ 查询重排（按相关性排序内容块）\n  - ✅ 两种提取深度（basic/advanced）\n  - ✅ 支持图片提取\n  - ✅ 支持 favicon\n  - ✅ 多种输出格式（markdown/text/JSON）\n  - ✅ 自动缓存\n\n**使用示例**:\n```bash\n# 提取单个 URL\npython3 scripts/extract.py --urls \"https://example.com/article\"\n\n# 提取多个 URL\npython3 scripts/extract.py --urls \"https://a.com,https://b.com\"\n\n# 带查询提取（重排内容）\npython3 scripts/extract.py --urls \"https://example.com\" --query \"find pricing info\"\n```\n\n#### 2. Usage API（使用量查询）\n- **脚本**: `scripts/usage.py`\n- **功能**: 查询 API 使用量和信用余额\n- **成本**: 免费\n- **特性**:\n  - ✅ 显示已用/剩余/总信用\n  - ✅ 可视化使用进度条\n  - ✅ 按端点分类统计\n  - ✅ 支持项目过滤\n  - ✅ 多种输出格式（compact/md/JSON）\n\n**使用示例**:\n```bash\n# 查看使用量\npython3 scripts/usage.py\n\n# 详细输出\npython3 scripts/usage.py --md\n\n# JSON 输出\npython3 scripts/usage.py --json\n```\n\n### 改进功能\n\n#### 1. 更新脚本增强\n- **脚本**: `scripts/update.py`\n- **改进**:\n  - ✅ 支持 Extract API 参数追踪\n  - ✅ 更详细的更新日志\n  - ✅ 自动版本号递增\n\n#### 2. 测试套件\n- **脚本**: `scripts/test_all.py`\n- **功能**: 自动化测试所有 API\n- **使用**:\n  ```bash\n  # 快速测试（仅 Search）\n  python3 scripts/test_all.py --quick\n  \n  # 完整测试\n  python3 scripts/test_all.py\n  ```\n\n### 文档更新\n\n-"},{"path":"RATE_LIMIT.md","content":"# Rate Limit 处理实现说明\n\n## 📊 Tavily 官方速率限制\n\n根据官方文档：https://docs.tavily.com/documentation/rate-limits.md\n\n| API | Development | Production |\n|-----|-------------|------------|\n| **Search/Extract/Map** | 100 RPM | 1,000 RPM |\n| **Crawl** | 100 RPM | 100 RPM |\n| **Research** | 20 RPM | 20 RPM |\n| **Usage** | 10 次/10 分钟 | 10 次/10 分钟 |\n\n## 🔧 实现方式\n\n### 1. 统一 Rate Limit 处理器\n\n创建了 `rate_limit.py` 模块，提供：\n\n- ✅ 429 错误自动检测\n- ✅ `retry-after` 头解析\n- ✅ 指数退避重试\n- ✅ 可配置的重试次数和延迟\n- ✅ 装饰器模式，易于集成\n\n### 2. 核心功能\n\n```python\n@rate_limit_handler(\n    max_retries=3,           # 最多重试 3 次\n    base_delay=1.0,          # 基础延迟 1 秒\n    max_delay=300.0,         # 最大延迟 5 分钟\n    exponential_base=2.0,    # 指数退避底数\n    log_func=log             # 日志函数\n)\ndef api_call():\n    # API 调用代码\n    pass\n```\n\n### 3. 重试策略\n\n| 尝试次数 | 延迟时间 | 说明 |\n|---------|---------|------|\n| 1 | - | 首次请求 |\n| 2 | 1-2 秒 | 第一次重试 |\n| 3 | 2-4 秒 | 第二次重试 |\n| 4 | 4-8 秒 | 第三次重试（如果 max_retries=4） |\n\n如果服务器返回 `retry-after` 头，则使用服务器指定的时间。\n\n### 4. 429 错误处理流程\n\n```\n请求 API\n   ↓\n收到 429 错误\n   ↓\n检查 retry-after 头\n   ↓\n计算等待时间\n   ↓\n等待指定时间\n   ↓\n重试请求\n   ↓\n成功 或 达到最大重试次数\n```\n\n## 📁 已更新的脚本\n\n| 脚本 | 状态 | 说明 |\n|------|------|------|\n| `rate_limit.py` | ✅ 新建 | 通用 Rate Limit 处理器 |\n| `search.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `extract.py` | ✅ 已更新 | 集成 Rate Limit 处理 |\n| `crawl.py` | ⏳ 待更新 | - |\n| `map.py` | ⏳ 待更新 | - |\n| `research.py` | ⏳ 待更新 | - |\n| `usage.py` | ⏳ 待更新 | - |\n\n## 🧪 测试\n\n```bash\n# 运行测试套件\npython3 scripts/test_all.py --quick\n\n# 输出\n✅ Passed: 4/4 (100%)\n```\n\n## 💡 使用示例\n\n### 正常情况\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[INFO] Success: 5 results\n```\n\n### 遇到 Rate Limit\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[INFO] Success: 5 results\n```\n\n### 超过限制\n```bash\n$ python3 scripts/search.py --query \"test\"\n\n[DEBUG] Request attempt 1/3: test...\n[WARN] Rate limited. Waiting 2.0s before retry...\n[DEBUG] Request attempt 2/3: test...\n[WARN] Rate limited. Waiting 4.0s before retry...\n[DEBUG] Request attempt 3/3: test...\n[ERROR] All 3 retries failed: Rate limit exceeded\n```\n\n## 🎯 最佳实践\n\n### 1. 批量请求时的延迟\n\n```python\n# ❌ 不好 - 快速连续请求\nfor query in queries:\n    search(query)\n\n# ✅ 好 - 添加延迟\nimport time\nfor query in queries:\n    search(query)\n    time.sleep(0.5)  # 每秒 2 个请求\n```\n\n### 2. 监控使用量\n\n```bash\n# 定期检查使用量\npython3 scripts/usage.py\n```\n\n### 3. 使用缓存\n\n```bash\n# 启用缓存（默认开启）\npython3 scripts/search.py --query \"test\"\n\n# 强制刷新（禁用缓存）\npython3 scripts/search.py --query \"test\" --no-cache\n```\n\n### 4. 了解限制\n\n- **Development Key**: 100 RPM = 每秒~1.6 个请求\n- **Production Key**: 1,000 RPM = 每秒~16 个请求\n\n## 📚 相关文件\n\n- `scripts/rate_limit.py` - Rate Limit 处理器\n- `scripts/search.py` - 已集成\n- `scripts/extract.py` - 已集成\n- https://docs.tavily.com/documentation/rate-limits.md - 官方文档\n\n## 🔄 后续更新\n\n待更新的脚本：\n- [ ] `crawl.py`\n- [ ] `map.py`\n- [ ] `research.py`\n- [ ] `usage.py`\n\n更新方法：\n```python\n# 1. 添加导入\nfrom rate_limit import "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1215,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T00:52:17.899Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:44:21.480Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}