Free Web Search

---
name: free-web-search
description: 基于Bing国内版的稳定联网搜索工具，中文环境深度优化，支持全文内容抓取，绕过常见反爬限制，返回结构化搜索结果。
version: 7
author: free-web-search
trigger_keywords:
  - 搜索
  - 查一下
  - 找一下
  - 最新消息
  - 新闻
  - 最新动态
  - 官网
  - 教程
  - 是什么
tools:
  - name: web_search
    description: 联网搜索并返回结构化结果，中文环境优化，支持全文内容抓取
    script: scripts/web_search.py
    parameters:
      query:
        type: string
        description: 【必填】搜索关键词/短句，必须简洁精准，符合下方Query优化规范，禁止长句/反问句
        required: true
      max:
        type: integer
        description: 最大返回的搜索结果条数，默认10，最大不超过20
        required: false
      full:
        type: integer
        description: 抓取前N条结果的网页全文内容，默认0（不抓取），最大不超过5
        required: false
      engine:
        type: string
        description: 搜索引擎选择，bing/duckduckgo/auto（默认bing）
        required: false
      filter:
        type: boolean
        description: 过滤低质量域名（如知乎），默认false（不过滤）
        required: false
---

# free-web-search v14 联网搜索工具

基于 Playwright 浏览器实现的稳定搜索工具，**意图识别** + **请求节流** + **结果质量评分** + **保留CSS修复**。

## v14 更新内容

- ✅ **[关键修复] 保留CSS**：之前拦截CSS导致Bing搜索结果标题文字丢失
- ✅ **意图识别+query改写**：搜索质量差时自动改写query（城市游玩→景点推荐、今日价格→实时行情等）
- ✅ **改写仅在质量差时触发**：先搜原始query，质量好就不改写，避免改写搞坏本来好的query
- ✅ **请求节流**：两次Bing请求间隔≥3s，避免触发限流
- ✅ **限流检测+退避**：0结果时递增等待重试，排除重试也0结果时停止
- ✅ **`--filter` 回退**：过滤后为空自动回退到不过滤结果
- ✅ **单域名排除重试**：最多2轮，结果更好才替换
- ✅ **DuckDuckGo国内快速失败**：10s超时×1次
- ✅ **`--no-rewrite`**：禁用query改写（调试用）

## 核心能力

- ✅ **中文环境深度优化**：强制 Bing 返回中文结果
- ✅ **反爬检测绕过**：多层反检测措施（stealth.js）
- ✅ **全文抓取**：支持按需抓取目标网页的完整正文内容
- ✅ **Headless 模式**：服务器可用，无需显示器

---

## 【核心必读】搜索Query优化规范

**搜索效果的好坏，90%取决于Query是否合理**，请严格遵循以下规则生成搜索词：

### 一、黄金原则
1.  **简洁精准**：只保留核心关键词，用2-5个核心词组合，禁止长句、反问句、口语化描述
2.  **限定明确**：需要时效性/领域/地区内容时，必须加上对应的限定词
3.  **格式正确**：使用中文关键词 + 英文/数字限定词，禁止特殊符号、无意义助词

### 二、正确示例 vs 错误示例
| 搜索场景 | 正确Query（推荐） | 错误Query（禁止） |
|----------|--------------------|--------------------|
| 时效性新闻 | 2026年04月 美伊局势 最新 | 你能帮我查一下最近美国和伊朗之间发生了什么事吗 |
| 技术教程 | Python 异步编程 最佳实践 2026 | 我想学习一下Python的异步编程，有没有好的教程 |
| 知识科普 | 中国大型邮轮 花城号 出坞 最新消息 | 中国的那个大型邮轮花城号现在怎么样了 |
| 本地内容 | 广东东莞 今日天气 | 我现在在东莞，今天天气怎么样啊 |
| 官方信息 | 华为云 ModelArts 官方文档 | 华为云的那个ModelArts的官网在哪里，文档怎么看 |

---

## 参数说明
| 参数名 | 类型 | 说明 | 默认值 | 取值限制 |
|--------|------|------|--------|----------|
| `query` | 字符串 | 【必填】搜索关键词 | - | 不能为空 |
| `max` | 整数 | 最多返回的搜索结果条数 | 10 | 1-20 |
| `full` | 整数 | 抓取前N条结果的网页全文 | 0 | 0-5 |
| `engine` | 字符串 | 搜索引擎选择 | bing | bing/duckduckgo/auto |
| `filter` | 布尔 | 过滤低质量域名 | false | - |

---

## 使用示例

```bash
# 基础搜索
python scripts/web_search.py "经济新闻 今日" --max=10

# 抓取前3条结果的全文
python scripts/web_search.py "经济新闻 最新" --full=3

# 使用 auto 模式（Bing 结果不足时切换 DuckDuckGo）
python scripts/web_search.py "技术教程" --engine=auto

# 过滤知乎等低质量域名
python scripts/web_search.py "某个话题" --filter
```

---

## 常见问题

### 搜索返回空结果
1. 检查网络连接（VPN 可能影响 Bing 国内版）
2. 尝试 `--engine=duckduckgo` 直接用 DuckDuckGo
3. 检查 Query 是否过于冗长或口语化

### 浏览器启动失败
```bash
pip install playwright && playwright install chromium
```

### 全文抓取失败
- 某些网站有强反爬限制
- 知乎等域名在全文抓取时自动跳过

### 结果集中在单一域名
- 脚本会自动检测并警告 `[WARN] 结果集中在单一域名`
- **解决方案**：换用更具体的关键词，避免歧义词

### 搜索关键词避坑指南
| ❌ 避免 | ✅ 推荐 |
|---------|---------|
| `民生新闻` | `住房 医疗 就业` 或 `社会政策 百姓生活` |
| `经济新闻` | `财经政策 GDP` 或 `A股 沪指` |
| `长护险` | `长期护理保险 养老服务` |

### 服务器环境
- 脚本强制使用 `headless=True`，无需显示器
- 已添加服务器兼容的浏览器参数