谷歌搜索(免费版)

搜索、解析、筛选、导出。四步完成Google搜索与结果处理。

无需API Key，通过浏览器自动化方式即可执行Google搜索，解析结果，提取关键信息。免费版聚焦轻量场景，让免费搜索触手可及.

概述

免费版谷歌搜索工具为个人用户提供基础的Google搜索能力。通过浏览器自动化（Playwright/Puppeteer）执行搜索，解析搜索结果页面，提取标题、URL、摘要等信息，无需申请任何API Key.

核心定位

核心能力

1. 浏览器自动化搜索

输入格式

import subprocess
import json
# ..
class GoogleSearcher:
    """Google搜索器（免费版）"""
# ..
    def __init__(self, script_path="（请参考skill目录中的脚本文件）"):
        self.script_path = script_path
        self.runtime = self._detect_runtime()
# ..
    def _detect_runtime(self):
        """检测JS运行时"""
        for runtime in ["bun", "node"]:
            result = subprocess.run(["which", runtime], capture_output=True)
            if result.returncode == 0:
                return runtime
        return "node"
# ..
    def search(self, query, num_results=10, language="zh-CN", timeout=30):
        """执行Google搜索"""
        print(f"搜索：{query}（语言：{language}，结果数：{num_results}）")
# ..
        cmd = [
            self.runtime, self.script_path,
            "--query", query,
            "--num", str(num_results),
            "--lang", language,
            "--timeout", str(timeout),
            "--format", "json"
        ]
# ..
        try:
                cmd, capture_output=True, text=True,
                timeout=timeout + 10, encoding="utf-8"
            )
# ..
                return {"success": False, "error": result.stderr}
# ..
            results = json.loads(result.stdout)
            return {"success": True, "results": results, "query": query}
# ..
        except subprocess.TimeoutExpired:
            return {"success": False, "error": "搜索超时"}
        except json.JSONDecodeError:
            return {"success": False, "error": "解析失败"}
        except Exception as e:
            return {"success": False, "error": str(e)}
# ..
searcher = GoogleSearcher()
result = searcher.search("人工智能最新进展", num_results=10)
if result.get("success"):
    print(f"找到 {len(result['results'])} 条结果")
    for i, r in enumerate(result["results"][:3], 1):
        print(f"\n{i}. {r.get('title', '')}")
        print(f"   URL: {r.get('url', '')}")
else:
    print(f"搜索失败：{result.get('error')}")

处理: 解析浏览器自动化搜索的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回浏览器自动化搜索的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

2. 搜索结果解析

详细代码示例已移至 references/detail.md

处理: 解析搜索结果解析的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回搜索结果解析的响应数据,包含状态码、结果和日志.

3. 基础筛选

处理: 解析基础筛选的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回基础筛选的响应数据,包含状态码、结果和日志.

4. 结果导出

处理: 解析结果导出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果导出的响应数据,包含状态码、结果和日志. 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：谷歌搜索免费版、通过浏览器自动化、解析结果、基础摘要生成、谷歌搜索助手免费、版是面向个人用户、的轻量、搜索工具、方式执行搜索、API、Key、解析搜索结果、提取标题、与摘要、Use、when、SEO、关键词分析、排名提升、搜索流量优化时使、不适用于黑帽、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：快速信息检索

场景描述：搜索某个主题的快速信息.

searcher = GoogleSearcher()
parser = SearchResultParser()
# ..
result = searcher.search("Python 异步编程教程", num_results=5)
if result.get("success"):
    parsed = parser.parse_results(result["results"])
    print(parser.format_results(parsed, "text"))

场景二：研究资料收集

场景描述：为研究项目收集相关资料.

searcher = GoogleSearcher()
parser = SearchResultParser()
filterer = ResultFilter()
exporter = ResultExporter()
# ..
queries = ["机器学习入门", "深度学习教程", "神经网络原理"]
all_results = []
# ..
for query in queries:
    result = searcher.search(query, num_results=10)
    if result.get("success"):
        parsed = parser.parse_results(result["results"])
        all_results.extend(parsed)
# ..
unique = filterer.deduplicate(all_results)
print(f"共收集 {len(unique)} 条独特结果")
# ..
exporter.export_markdown(unique, query="机器学习研究资料")

场景三：学习参考

场景描述：搜索特定技术问题的解决方案.

searcher = GoogleSearcher()
parser = SearchResultParser()
filterer = ResultFilter()
# ..
result = searcher.search("Python 'ConnectionError' 解决方法 site:stackoverflow.com", num_results=5)
if result.get("success"):
    parsed = parser.parse_results(result["results"])
    so_results = filterer.filter_by_domain(parsed, ['stackoverflow.com'])
    print(f"找到 {len(so_results)} 条Stack Overflow结果")
    for r in so_results:
        print(f"\n- {r['title']}")
        print(f"  {r['url']}")

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

30秒上手

node （请参考skill目录中的脚本文件） "人工智能" --num 10 --format json
# ..
bun （请参考skill目录中的脚本文件） "人工智能" --num 10 --format json

120秒标准搭建

npm install playwright
npx playwright install chromium
# ..
node --version
node -e "require('playwright')" && echo "Playwright已安装"
# ..
node （请参考skill目录中的脚本文件） "Python教程" --num 10 --format json > results.json
# ..
cat results.json | python3 -m json.tool | head -50
# ..
python3 export.py --input results.json --format markdown --output results.md

配置示例

基础配置

import os
# ..
class GoogleSearchConfig:
    """谷歌搜索配置（免费版）"""
    SCRIPT_PATH = os.getenv("GS_SCRIPT_PATH", "（请参考skill目录中的脚本文件）")
    RUNTIME = os.getenv("GS_RUNTIME", "node")  # node 或 bun
    DEFAULT_NUM = int(os.getenv("GS_DEFAULT_NUM", "10"))
    DEFAULT_LANG = os.getenv("GS_DEFAULT_LANG", "zh-CN")
    TIMEOUT = int(os.getenv("GS_TIMEOUT", "30"))
    OUTPUT_DIR = os.getenv("GS_OUTPUT_DIR", "./output")
# ..
    @classmethod
    def show(cls):
        print("=== 谷歌搜索配置 ===")
        print(f"脚本路径：{cls.SCRIPT_PATH}")
        print(f"运行时：{cls.RUNTIME}")
        print(f"默认结果数：{cls.DEFAULT_NUM}")
        print(f"默认语言：{cls.DEFAULT_LANG}")
        print(f"超时时间：{cls.TIMEOUT}s")
# ..
GoogleSearchConfig.show()

搜索参数

SEARCH_PARAMS = {
    'num_results': 10,          # 结果数量
    'language': 'zh-CN',        # 搜索语言
    'country': 'cn',            # 搜索国家
    'safe_search': True,        # 安全搜索
    'time_range': None,         # 时间范围：day/week/month/year
    'site_search': None,        # 站内搜索：example.com
    'exclude_sites': [],        # 排除站点
    'file_type': None,          # 文件类型：pdf/doc/xls
}

最佳实践

1. 搜索技巧

SEARCH_OPERATORS = {
    'site:': '限定特定站点（如 site:stackoverflow.com）',
    'filetype:': '限定文件类型（如 filetype:pdf）',
    'intitle:': '标题包含关键词',
    'inurl:': 'URL包含关键词',
    '".."': '精确匹配',
    '-': '排除关键词（如 -广告）',
    'OR': '或者（如 Python OR Java）',
    '.': '数字范围（如 2020.2024）',
}
# ..
query = "Python async site:stackoverflow.com -广告"

2. 结果优化

def optimize_results(results, query):
    """优化搜索结果"""
    filterer = ResultFilter()
    unique = filterer.deduplicate(results)
    exclude = ['pinterest.com', 'facebook.com', 'twitter.com']
    cleaned = filterer.exclude_domains(unique, exclude)
    sorted_results = filterer.sort_by_relevance(cleaned, query)
    return sorted_results

错误处理

def safe_search(query, max_retries=2):
    """带重试的安全搜索"""
    searcher = GoogleSearcher()
    for attempt in range(max_retries):
        if result.get("success"):
            return result
        print(f"第{attempt+1}次失败：{result.get('error')}")
        if attempt < max_retries - 1:
            import time
            time.sleep(3)
    return {"success": False, "error": "重试次数已用完"}

常见问题

Q1：免费版需要API Key吗？

不需要。免费版通过浏览器自动化方式执行搜索，无需申请Google API Key。但需要安装Playwright与Chromium浏览器.

Q2：搜索速度慢怎么办？

可能原因：(1) 首次启动Chromium较慢，后续会加快；(2) 网络问题，建议使用代理；(3) 搜索结果过多，减少 num_results；(4) 使用Bun运行时（比Node.js快）.

Q3：搜索失败怎么办？

可能原因：(1) 网络无法访问Google，需配置代理；(2) 触发反爬机制，降低搜索频率；(3) 浏览器版本过旧，更新Playwright；(4) 搜索查询包含特殊字符，尝试简化查询.

Q4：免费版支持批量搜索吗？

不支持。免费版每次只能搜索一个查询。如需批量搜索多个查询、并发执行、结果聚合，需升级至专业版.

Q5：搜索结果不准确怎么办？

建议：(1) 使用更具体的关键词；(2) 使用搜索运算符（如 site: filetype:）；(3) 添加引号精确匹配；(4) 排除不相关关键词（用 -）；(5) 限定时间范围.

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux
• Node.js: 16+ 或 Bun: 1.0+
• 网络: 需能访问Google（可能需要代理）

第三方依赖

API Key 配置

• 免费版基础LLM由Agent平台提供
• 搜索基于浏览器自动化执行，不调用Google官方API
• 如需使用代理，配置 HTTP_PROXY 与 HTTPS_PROXY 环境变量
• LLM模型路由由Agent平台内置提供

可用性分类

• 分类: MD+EXEC（Markdown指令+命令行执行）
• 说明: 通过自然语言指令驱动Agent执行Google搜索与结果处理任务

已知限制

本免费体验版限制以下高级功能（需升级至专业版解锁）：

• 批量搜索（多查询并发执行）
• AI智能摘要（基于LLM的结果摘要）
• 定时监控（关键词变化监控）
• 多语言搜索（中英日韩多语言）
• 搜索结果缓存（避免重复搜索）
• 图片搜索（Google Images）
• 新闻搜索（Google News）
• 学术搜索（Google Scholar）
• 优先技术支持

解锁全部高级能力请使用专业版：free-google-search-tool-pro

示例

基本用法

输出：返回执行结果,包含操作状态和输出数据

用户: 执行核心功能
Skill: 正在执行核心功能..
Skill: 执行完成,结果如下: 操作成功

输出格式

{
  "success": true,
  "data": {
    "result": "谷歌搜索(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "free google search"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}