# SearXNG API Skills

## 基本信息

- **URL**: `https://searxng.erhe.top`
- **API Token**: `fGWEFWGrgasegtjt1jUJG`
- **端口**: 通过 Caddy 反向代理

## API 调用方法

### 1. 搜索 API

```bash
# 基础搜索
curl "https://searxng.erhe.top/search?q=关键词&token=fGWEFWGrgasegtjt1jUJG"

# JSON 格式返回（推荐）
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG"
```

### 2. Python 调用示例

```python
import requests
import json

def search_searxng(query, format_type="json"):
    """
    使用 SearXNG 搜索
    
    参数:
        query: 搜索关键词
        format_type: 返回格式 (json/html/csv/rss)
    
    返回:
        dict: 搜索结果
    """
    url = "https://searxng.erhe.top/search"
    params = {
        "q": query,
        "format": format_type,
        "token": "fGWEFWGrgasegtjt1jUJG"
    }
    
    response = requests.get(url, params=params)
    
    if format_type == "json":
        return response.json()
    else:
        return response.text

# 使用示例
results = search_searxng("python 教程")
print(f"找到 {len(results['results'])} 个结果")
for result in results['results'][:5]:
    print(f"- {result['title']}: {result['url']}")
```

### 3. Claude Code / Agent 调用示例

```python
import urllib.request
import urllib.parse
import json

def search(query):
    """搜索函数"""
    base_url = "https://searxng.erhe.top/search"
    params = urllib.parse.urlencode({
        "q": query,
        "format": "json",
        "token": "fGWEFWGrgasegtjt1jUJG"
    })
    
    url = f"{base_url}?{params}"
    
    with urllib.request.urlopen(url) as response:
        data = json.loads(response.read().decode())
        
    return data

# Agent 中使用
results = search("如何在 Linux 中查找文件")
for r in results['results'][:3]:
    print(f"标题: {r['title']}")
    print(f"链接: {r['url']}\n")
```

## 高级搜索

### 1. 指定语言

```bash
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&language=zh"
```

语言代码:
- `zh` - 中文
- `en` - 英文
- `ja` - 日文
- `de` - 德文
- `fr` - 法文

### 2. 指定分类

```bash
# 图片搜索
curl "https://searxng.erhe.top/search?q=猫&format=json&token=fGWEFWGrgasegtjt1jUJG&categories=images"

# 视频搜索
curl "https://searxng.erhe.top/search?q=教程&format=json&token=fGWEFWGrgasegtjt1jUJG&categories=videos"

# 新闻搜索
curl "https://searxng.erhe.top/search?q=科技&format=json&token=fGWEFWGrgasegtjt1jUJG&categories=news"
```

分类列表:
- `general` - 通用
- `images` - 图片
- `videos` - 视频
- `news` - 新闻
- `music` - 音乐
- `files` - 文件
- `it` - IT
- `science` - 科学

### 3. 安全搜索

```bash
# 关闭安全搜索 (0)
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&safesearch=0"

# 适中 (1)
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&safesearch=1"

# 严格 (2)
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&safesearch=2"
```

### 4. 时间范围

```bash
# 最近一天
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&time_range=day"

# 最近一周
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&time_range=week"

# 最近一月
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&time_range=month"

# 最近一年
curl "https://searxng.erhe.top/search?q=关键词&format=json&token=fGWEFWGrgasegtjt1jUJG&time_range=year"
```

## JSON 返回格式说明

```json
{
  "query": "搜索关键词",
  "results": [
    {
      "title": "结果标题",
      "url": "https://example.com",
      "content": "结果摘要",
      "engine": "搜索引擎名称",
      "template": "模板类型",
      "publishedDate": "发布日期 (如果有)",
      "img_src": "图片URL (如果有)",
      "thumbnail": "缩略图URL (如果有)",
      "category": "分类"
    }
  ],
  "answers": [],
  "corrections": [],
  "infoboxes": [],
  "suggestions": ["建议搜索词"],
  "unresponsive_engines": []
}
```

## 获取配置信息

```bash
# 获取 SearXNG 配置
curl "https://searxng.erhe.top/config&token=fGWEFWGrgasegtjt1jUJG"
```

## 完整 Python 示例

```python
#!/usr/bin/env python3
"""
SearXNG API 客户端示例
"""

import requests
import json
import sys

SEARXNG_URL = "https://searxng.erhe.top"
API_TOKEN = "fGWEFWGrgasegtjt1jUJG"

def search(query, 
            format_type="json",
            categories=None,
            language="auto",
            safesearch=0,
            time_range=None):
    """
    搜索函数
    
    参数:
        query: 搜索关键词
        format_type: 返回格式 (json/html/csv/rss)
        categories: 分类列表 (images/videos/news/music)
        language: 语言代码 (auto/zh/en/ja/de/fr)
        safesearch: 安全搜索级别 (0/1/2)
        time_range: 时间范围 (day/week/month/year)
    
    返回:
        dict: 搜索结果
    """
    params = {
        "q": query,
        "format": format_type,
        "token": API_TOKEN,
        "language": language,
        "safesearch": safesearch
    }
    
    if categories:
        params["categories"] = categories
    
    if time_range:
        params["time_range"] = time_range
    
    response = requests.get(f"{SEARXNG_URL}/search", params=params)
    
    if format_type == "json":
        return response.json()
    else:
        return response.text

def format_results(results, max_results=10):
    """格式化输出结果"""
    print(f"\n{'='*60}")
    print(f"查询: {results.get('query')}")
    print(f"找到 {len(results.get('results', []))} 个结果")
    print(f"{'='*60}\n")
    
    for i, result in enumerate(results.get('results', [])[:max_results], 1):
        print(f"{i}. {result.get('title', '无标题')}")
        print(f"   链接: {result.get('url', '无链接')}")
        if result.get('content'):
            content = result.get('content', '')[:150]
            print(f"   摘要: {content}...")
        print(f"   来源: {result.get('engine', '未知')}")
        print()

if __name__ == "__main__":
    # 示例搜索
    if len(sys.argv) > 1:
        query = " ".join(sys.argv[1:])
    else:
        query = "Python 编程"
    
    try:
        results = search(query, categories="general")
        format_results(results)
    except Exception as e:
        print(f"搜索失败: {e}")
```

## 错误处理

```python
import requests

def safe_search(query):
    """安全的搜索函数，包含错误处理"""
    try:
        response = requests.get(
            "https://searxng.erhe.top/search",
            params={
                "q": query,
                "format": "json",
                "token": "fGWEFWGrgasegtjt1jUJG"
            },
            timeout=10
        )
        
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 403:
            return {"error": "API token 无效或缺失"}
        else:
            return {"error": f"请求失败: {response.status_code}"}
            
    except requests.exceptions.Timeout:
        return {"error": "请求超时"}
    except requests.exceptions.ConnectionError:
        return {"error": "连接失败，请检查网络"}
    except Exception as e:
        return {"error": str(e)}
```

## 快速参考

| 功能 | 命令 |
|------|------|
| 基础搜索 | `curl "https://searxng.erhe.top/search?q=关键词&token=fGWEFWGrgasegtjt1jUJG"` |
| JSON 返回 | 添加 `&format=json` |
| 图片搜索 | 添加 `&categories=images` |
| 中文结果 | 添加 `&language=zh` |
| 最近一周 | 添加 `&time_range=week` |
| 获取配置 | `curl "https://searxng.erhe.top/config&token=fGWEFWGrgasegtjt1jUJG"` |

## 注意事项

1. **Token 必须**: 所有 API 请求必须包含 `token` 参数
2. **返回格式**: 推荐使用 `format=json` 获取结构化数据
3. **超时处理**: 搜索可能需要几秒钟，建议设置超时
4. **请求频率**: 避免过于频繁的请求，可能触发限制
5. **结果数量**: 默认返回多个搜索引擎的结果

## 获取帮助

- SearXNG 主页: `https://searxng.erhe.top`
- SearXNG 文档: `https://docs.searxng.org`