clawd-tavily

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Tavily Search Skill for Clawdbot

AI-optimized web search integration for Clawdbot using the Tavily Search API.

## Features

- 🤖 **AI-Optimized Results**: Search results specifically formatted for LLM consumption
- ⚡ **Fast & Comprehensive Modes**: Choose between quick lookups (`basic`) or deep research (`advanced`)
- 🎯 **Domain Filtering**: Include or exclude specific domains for trusted sources
- 📰 **News Mode**: Current events search (last 7 days)
- 🖼️ **Image Search**: Include relevant images in results
- 📄 **Content Extraction**: Get raw HTML content for deeper analysis
- ✨ **AI Answer Generation**: Optional synthesized answers from search results

## Quick Start

### Installation

1. **Clone this repository**:
   ```bash
   git clone https://github.com/bert-builder/clawd-tavily.git
   cd clawd-tavily
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Get a Tavily API key**:
   - Visit https://tavily.com
   - Sign up for an account
   - Generate an API key from your dashboard

4. **Configure the skill**:
   
   **Option A**: Add to Clawdbot config (`~/.clawdbot/clawdbot.json`):
   ```json
   {
     "skills": {
       "entries": {
         "tavily": {
           "enabled": true,
           "apiKey": "tvly-YOUR_API_KEY_HERE"
         }
       }
     }
   }
   ```
   
   **Option B**: Set environment variable:
   ```bash
   export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"
   ```

### Basic Usage

```bash
# Simple search
./tavily/scripts/tavily_search.py "What is quantum computing?"

# Advanced research
./tavily/scripts/tavily_search.py "AI safety research" --depth advanced --max-results 10

# News search
./tavily/scripts/tavily_search.py "latest AI developments" --topic news

# Domain-specific search
./tavily/scripts/tavily_search.py "Python tutorials" \
  --include-domains python.org docs.python.org

# With images
./tavily/scripts/tavily_search.py "modern architecture" --images
```

## Installation for Clawdbot

### Local Installation (Testing)

1. **Install the skill**:
   ```bash
   # From the repo root
   clawdbot skills install ./tavily
   ```

2. **Verify installation**:
   ```bash
   clawdbot skills list | grep tavily
   ```

3. **Test the skill**:
   ```bash
   # In a Clawdbot session
   /skill tavily
   ```

### Publishing to ClawdHub

Once tested and ready:

1. **Package the skill**:
   ```bash
   python3 /opt/homebrew/lib/node_modules/clawdbot/skills/skill-creator/scripts/package_skill.py ./tavily
   ```

2. **Create a PR to Clawdbot**:
   - Fork https://github.com/clawdbot/clawdbot
   - Add the skill to `skills/`
   - Submit a pull request

3. **Publish to ClawdHub**:
   - Follow the ClawdHub submission guidelines
   - Share on Discord: https://discord.com/invite/clawd

## Documentation

- **SKILL.md**: Complete usage guide with examples and best practices
- **references/api-reference.md**: Detailed API documentation
- **Architecture diagram**: See SKILL.md for Mermaid flow diagram

## Testing

### Manual Testing

```bash
# Run the test suite
python3 -m pytest tests/ -v

# Test basic search
./tavily/scripts/tavily_search.py "test query" --api-key "$TAVILY_API_KEY"

# Test advanced features
./tavily/scripts/tavily_search.py "test" \
  --depth advanced \
  --topic news \
  --images \
  --max-results 10 \
  --include-domains example.com
```

### Integration Testing

```bash
# Test with Clawdbot
clawdbot chat --agent test-agent
> Search for "quantum computing" using Tavily
```

## API Key Management

### Secure Storage

**DO NOT** commit API keys to the repository!

1. Use environment variables
2. Store in Clawdbot config
3. Use `.env` files (ignored by git)
4. Use secret management services for production

### Key Format

Tavily API keys start with `tvly-` followed by the key string:
```
tvly-abc123def456ghi789...
```

## Cost & Rate Limits

- Each search consumes credits based on depth:
  - `basic`: 1 credit
  - `advanced`: ~3-5 credits (varies)
- Free tier available
- Check https://tavily.com/pricing for current plans

## Comparison with Other Search APIs

| Feature | Tavily | Brave | Perplexity |
|---------|--------|-------|------------|
| AI Answer | ✅ | ❌ | ✅ |
| Raw Content | ✅ | ❌ | ❌ |
| Domain Filter | ✅ | Limited | ❌ |
| News Mode | ✅ | ✅ | ✅ |
| Free Tier | ✅ | ✅ | Limited |
| LLM Optimized | ✅ | ❌ | ✅ |

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/clawd-tavily.git
cd clawd-tavily

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Package for testing
python3 /path/to/package_skill.py ./tavily
```

## License

MIT License - see [LICENSE](https://github.com/bert-builder/clawd-tavily/tree/HEAD/LICENSE) for details

## Support

- **Issues**: https://github.com/bert-builder/clawd-tavily/issues
- **Clawdbot Discord**: https://discord.com/invite/clawd
- **Tavily Docs**: https://docs.tavily.com

## Credits

- Built for [Clawdbot](https://github.com/clawdbot/clawdbot)
- Powered by [Tavily Search API](https://tavily.com)
- Created by [@bert-builder](https://github.com/bert-builder)

## Changelog

### v1.0.0 (2026-01-24)

- Initial release
- Basic and advanced search modes
- Domain filtering
- News topic support
- Image search
- AI answer generation
- Raw content extraction
- Comprehensive documentation
- Mermaid architecture diagram

Tavily Search Skill for Clawdbot

AI-optimized web search integration for Clawdbot using the Tavily Search API.

Features

🤖 AI-Optimized Results: Search results specifically formatted for LLM consumption
⚡ Fast & Comprehensive Modes: Choose between quick lookups (basic) or deep research (advanced)
🎯 Domain Filtering: Include or exclude specific domains for trusted sources
📰 News Mode: Current events search (last 7 days)
🖼️ Image Search: Include relevant images in results
📄 Content Extraction: Get raw HTML content for deeper analysis
✨ AI Answer Generation: Optional synthesized answers from search results

Quick Start

Installation

Clone this repository:

git clone https://github.com/bert-builder/clawd-tavily.git
cd clawd-tavily

Install dependencies:
```
pip install -r requirements.txt
```
Get a Tavily API key:
- Visit https://tavily.com
- Sign up for an account
- Generate an API key from your dashboard

Configure the skill:

Option A: Add to Clawdbot config (~/.clawdbot/clawdbot.json):

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Option B: Set environment variable:

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

Basic Usage

# Simple search
./tavily/scripts/tavily_search.py "What is quantum computing?"

# Advanced research
./tavily/scripts/tavily_search.py "AI safety research" --depth advanced --max-results 10

# News search
./tavily/scripts/tavily_search.py "latest AI developments" --topic news

# Domain-specific search
./tavily/scripts/tavily_search.py "Python tutorials" \
  --include-domains python.org docs.python.org

# With images
./tavily/scripts/tavily_search.py "modern architecture" --images

Installation for Clawdbot

Local Installation (Testing)

Install the skill:

# From the repo root
clawdbot skills install ./tavily

Verify installation:
```
clawdbot skills list | grep tavily
```
Test the skill:
```
# In a Clawdbot session
/skill tavily
```

Publishing to ClawdHub

Once tested and ready:

Package the skill:

python3 /opt/homebrew/lib/node_modules/clawdbot/skills/skill-creator/scripts/package_skill.py ./tavily

Create a PR to Clawdbot:
- Fork https://github.com/clawdbot/clawdbot
- Add the skill to skills/
- Submit a pull request
Publish to ClawdHub:
- Follow the ClawdHub submission guidelines
- Share on Discord: https://discord.com/invite/clawd

Documentation

SKILL.md: Complete usage guide with examples and best practices
references/api-reference.md: Detailed API documentation
Architecture diagram: See SKILL.md for Mermaid flow diagram

Testing

Manual Testing

# Run the test suite
python3 -m pytest tests/ -v

# Test basic search
./tavily/scripts/tavily_search.py "test query" --api-key "$TAVILY_API_KEY"

# Test advanced features
./tavily/scripts/tavily_search.py "test" \
  --depth advanced \
  --topic news \
  --images \
  --max-results 10 \
  --include-domains example.com

Integration Testing

# Test with Clawdbot
clawdbot chat --agent test-agent
> Search for "quantum computing" using Tavily

API Key Management

Secure Storage

DO NOT commit API keys to the repository!

Use environment variables
Store in Clawdbot config
Use .env files (ignored by git)
Use secret management services for production

Key Format

Tavily API keys start with tvly- followed by the key string:

tvly-abc123def456ghi789...

Cost & Rate Limits

Each search consumes credits based on depth:
- basic: 1 credit
- advanced: ~3-5 credits (varies)
Free tier available
Check https://tavily.com/pricing for current plans

Comparison with Other Search APIs

Feature	Tavily	Brave	Perplexity
AI Answer	✅	❌	✅
Raw Content	✅	❌	❌
Domain Filter	✅	Limited	❌
News Mode	✅	✅	✅
Free Tier	✅	✅	Limited
LLM Optimized	✅	❌	✅

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/clawd-tavily.git
cd clawd-tavily

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Package for testing
python3 /path/to/package_skill.py ./tavily

License

MIT License - see LICENSE for details

Support

Issues: https://github.com/bert-builder/clawd-tavily/issues
Clawdbot Discord: https://discord.com/invite/clawd
Tavily Docs: https://docs.tavily.com

Credits

Built for Clawdbot
Powered by Tavily Search API
Created by @bert-builder

Changelog

v1.0.0 (2026-01-24)

Initial release
Basic and advanced search modes
Domain filtering
News topic support
Image search
AI answer generation
Raw content extraction
Comprehensive documentation
Mermaid architecture diagram