功能说明: 本技能涵盖 中文交互、化执行搜索、化工作流场景 等核心能力。

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

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

概述

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

核心定位

核心能力

1. 浏览器自动化搜索

import subprocess
import json

class GoogleSearcher:
    """Google搜索器（免费版）"""

    def __init__(self, script_path="scripts/search-google.js"):
        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 scripts/search-google.js "人工智能" --num 10 --format json

bun scripts/search-google.js "人工智能" --num 10 --format json

120秒标准搭建

npm install playwright
npx playwright install chromium

node --version
node --eval "require('playwright')" && echo "Playwright已安装"

js "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", "scripts/search-google.js")
    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 配置

• 免费版无需任何API Key
• 搜索基于浏览器自动化执行，不调用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: 执行完成,结果如下: 操作成功

安全注意事项

使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

效率量化分析

差异化对比

核心功能

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据