# SearXNG API 使用指南

## 快速开始

### Python 脚本方式

```bash
# 安装依赖 (如需要)
pip3 install requests

# 搜索示例
python3 /tmp/searxng_search.py "python教程"

# 指定分类
python3 /tmp/searxng_search.py "猫咪图片" -c images

# 指定时间范围
python3 /tmp/searxng_search.py "科技新闻" --time-range week

# 输出 JSON
python3 /tmp/searxng_search.py "python" --raw
```

### cURL 方式

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

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

### Python 代码方式

```python
import requests

def search(query):
    response = requests.get(
        "https://searxng.erhe.top/search",
        params={
            "q": query,
            "format": "json",
            "token": "fGWEFWGrgasegtjt1jUJG"
        }
    )
    return response.json()

# 使用
results = search("python教程")
for r in results['results'][:5]:
    print(r['title'], r['url'])
```

## 常用命令参考

| 用途 | 命令 |
|------|------|
| 基础搜索 | `python3 /tmp/searxng_search.py "关键词"` |
| 图片搜索 | `python3 /tmp/searxng_search.py "关键词" -c images` |
| 视频搜索 | `python3 /tmp/searxng_search.py "关键词" -c videos` |
| 中文结果 | `python3 /tmp/searxng_search.py "关键词" -l zh` |
| 最近一周 | `python3 /tmp/searxng_search.py "关键词" -t week` |
| 限制结果数 | `python3 /tmp/searxng_search.py "关键词" -m 20` |
| 原始 JSON | `python3 /tmp/searxng_search.py "关键词" --raw` |
| 查看帮助 | `python3 /tmp/searxng_search.py --help` |

## Agent 集成示例

### Claude Code 工具定义

```json
{
  "name": "searxng_search",
  "description": "使用 SearXNG 隐私搜索引擎进行网络搜索",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索关键词"
      },
      "category": {
        "type": "string",
        "enum": ["general", "images", "videos", "news", "music"],
        "description": "搜索分类"
      },
      "language": {
        "type": "string",
        "default": "auto",
        "description": "语言代码"
      },
      "max_results": {
        "type": "integer",
        "default": 10,
        "description": "最大结果数"
      }
    },
    "required": ["query"]
  }
}
```

### Python 工具实现

```python
def searxng_search_tool(query, category="general", language="auto", max_results=10):
    """
    SearXNG 搜索工具
    """
    try:
        response = requests.get(
            "https://searxng.erhe.top/search",
            params={
                "q": query,
                "format": "json",
                "token": "fGWEFWGrgasegtjt1jUJG",
                "language": language,
                "categories": category if category != "general" else None
            },
            timeout=15
        )
        
        if response.status_code == 200:
            data = response.json()
            results = []
            
            for r in data.get('results', [])[:max_results]:
                results.append({
                    "title": r.get('title', ''),
                    "url": r.get('url', ''),
                    "snippet": r.get('content', '')[:200],
                    "source": r.get('engine', '')
                })
            
            return {
                "success": True,
                "query": data.get('query', query),
                "count": len(results),
                "results": results
            }
        else:
            return {
                "success": False,
                "error": f"HTTP {response.status_code}"
            }
            
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }

# 使用示例
result = searxng_search_tool("如何安装Python", max_results=5)
if result['success']:
    for r in result['results']:
        print(f"📄 {r['title']}\n   {r['url']}\n")
```

## 完整文档

查看详细文档: `cat /tmp/searxng_skills.md`

## 测试

```bash
# 测试脚本
python3 /tmp/searxng_search.py "test" -m 3

# 测试 cURL
curl -s "https://searxng.erhe.top/search?q=test&format=json&token=fGWEFWGrgasegtjt1jUJG" | head -20
```

## 故障排除

### 常见问题

1. **Token 错误 403**
   - 确保请求中包含 `token=fGWEFWGrgasegtjt1jUJG`

2. **连接超时**
   - 检查网络连接
   - 尝试增加超时时间

3. **结果为空**
   - 尝试更换关键词
   - 检查语言设置

### 获取帮助

- 查看详细文档: `/tmp/searxng_skills.md`
- 查看脚本帮助: `python3 /tmp/searxng_search.py --help`