ddgs-web-search — Терминальный инструмент для поиска в DuckDuckGo

--- name: ddgs-web-search description: Use when needing to search the web in AI coding tools or OpenClaw. Uses DuckDuckGo API without API key. --- # DuckDuckGo Web Search Skill An Agent Skill for searching web content via DuckDuckGo. ## Overview This Skill provides a command-line tool for web search using the `ddgs` Python package. Suitable for: - Real-time web information needs in AI coding tools - Fetching search results in OpenClaw workflows ## Core Features - **Web Search**: General web search - **News Search**: Dedicated news content search - **Multiple Output Formats**: Text or JSON format - **Flexible Configuration**: Region, time limits, and safe search level ## Installation This project uses `uv` as the Python package manager. ### Option 1: Run with uv (Recommended) ```bash # Run the script directly (uv will auto-install dependencies) uv run scripts/ddgs_search.py "Python programming" # Or navigate to the directory first cd skills/ddgs-search uv run scripts/ddgs_search.py "machine learning" ``` ### Option 2: Manual Dependency Installation ```bash # Install dependencies using uv uv pip install ddgs # Or use pip pip install ddgs ``` ## Quick Start ### Basic Usage ```bash # Run with uv (recommended) uv run scripts/ddgs_search.py "Python programming" # Limit the number of results uv run scripts/ddgs_search.py "machine learning" --max-results 5 # Search news uv run scripts/ddgs_search.py "tech news" --news # JSON output (for programmatic parsing) uv run scripts/ddgs_search.py "API documentation" --json # Time limit (today) uv run scripts/ddgs_search.py "breaking news" --timelimit d ``` ## Complete Parameter Reference | Parameter | Short | Description | Default | | --------- | ----- | ----------- | ------- | | `query` | - | Search keywords | Required | | `--max-results` | `-n` | Maximum number of results | 10 | | `--region` | `-r` | Region code | `wt-wt` | | `--safesearch` | `-s` | Safe search (on/moderate/off) | `moderate` | | `--timelimit` | `-t` | Time limit (d/w/m/y) | - | | `--backend` | `-b` | Search backend (auto/html/lite) | `auto` | | `--news` | - | Search news | - | | `--json` | `-j` | JSON format output | - | | `--verbose` | `-v` | Show detailed information | - | ### Region Code Examples - `wt-wt` - Worldwide (default) - `us-en` - United States English - `cn-zh` - China Chinese - `jp-jp` - Japan - `uk-en` - United Kingdom ### Time Limits - `d` - Past day - `w` - Past week - `m` - Past month - `y` - Past year ## Usage in OpenClaw In OpenClaw workflows, you can invoke it via the `bash` tool: ```yaml # Example workflow step - name: search_web tool: bash command: cd skills/ddgs-search && uv run scripts/ddgs_search.py "{{ query }}" --json ``` Or using the Python tool: ```python # Assuming the current directory is the project root import subprocess import json result = subprocess.run( ["uv", "run", "skills/ddgs-search/scripts/ddgs_search.py", "Python tips", "--json"], capture_output=True, text=True ) data = json.loads(result.stdout) ``` ## Return Result Format ### Web Search Results ```json [ { "title": "Result Title", "href": "https://example.com/page", "body": "Page snippet/description..." } ] ``` ### News Search Results ```json [ { "title": "News Headline", "href": "https://news.example.com/article", "body": "Article summary...", "date": "2024-01-15", "source": "News Source Name" } ] ``` ## Usage Examples ### Example 1: Search Technical Documentation ```bash uv run scripts/ddgs_search.py "FastAPI documentation" -n 5 ``` ### Example 2: Get Latest News ```bash uv run scripts/ddgs_search.py "artificial intelligence" --news -t d -n 3 ``` ### Example 3: Chinese Search ```bash uv run scripts/ddgs_search.py "机器学习教程" -r cn-zh -n 8 ``` ### Example 4: JSON Output Processing ```bash uv run scripts/ddgs_search.py "python tips" --json | jq '.[0].href' ``` ## FAQ ### uv Not Installed ```bash # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ### ImportError: No module named 'ddgs' ```bash # Install using uv uv pip install ddgs # Or run in the script directory (uv will auto-handle) cd skills/ddgs-search uv run scripts/ddgs_search.py "query" ``` ### Empty Search Results - Check network connection - Try changing the `--backend` parameter (auto/html/lite) - Some regions may require a proxy ### Rate Limiting DuckDuckGo has implicit rate limiting. If frequent requests fail: - Reduce request frequency - Add delays between requests - Use a different backend ## Dependencies - Python 3.9+ - `uv` (package manager) - `ddgs` >= 8.0.0