Free Web Search for AI Agents — Zero Paid Search API / AI 智能体免费网页检索技能（零付费搜索 API）

简体中文

Free Web Search for AI Agents — Zero Paid Search API

为 AI Agent 提供网页搜索与网页调研能力，避免消耗 Tavily、Firecrawl 等付费搜索 API 的额度。

本项目是一个可分发的“全局 Skill + 本地 CLI”完整技能包。它使用 DDGS/SearXNG 发现网页，使用本地工具读取 HTML、JSON、文本和 PDF，通过缓存、去重与失败升级策略减少对付费工具的依赖。

一键安装

要求 Python 3.10 或更高版本。安装器会创建独立虚拟环境、安装 CLI、复制 Skill，并生成用户级命令，不污染系统 Python。

python3 scripts/install.py

也可直接将本 Skill（当前仓库）分发；其目录已包含完整 CLI 源码与安装器。下载后在仓库目录执行：

python3 scripts/install.py

默认安装位置：

  • Skill：${CODEX_HOME:-~/.codex}/skills/web-search-free
  • CLI 环境：~/.local/share/free-web-research/venv
  • 命令：~/.local/bin/free-web-research

如需本地浏览器渲染支持：

python3 scripts/install.py --with-browser

Windows 可执行：

py scripts/install.py

使用

free-web-research health --online
free-web-research search "腾讯 最新季度业绩 官方" --max-results 5 --prefer-domain tencent.com
free-web-research fetch "https://www.tencent.com/investors/"
free-web-research fetch "https://example.com/dynamic" --fallback jina,browser
free-web-research cache stats

命令默认输出适合代理消费的 JSON。使用 --format markdown 可获得便于阅读的结果。

更新与卸载

从新版本目录重新执行安装器，并显式允许可恢复备份：

python3 scripts/install.py --force

卸载默认采用移动备份而非永久删除：

python3 scripts/uninstall.py --yes

免费边界

本项目本身不调用任何付费搜索 API。DDGS 与 SearXNG 仍依赖外部搜索引擎，可能遇到速率限制、验证码或上游条款变化；Jina Reader 是可选第三方兜底，可能有免费频率限制。CLI 只返回是否建议升级付费工具，不会自动调用 Tavily 或 Firecrawl。

English

Free Web Search for AI Agents — Zero Paid Search API

Give your AI agents web search and web research capabilities without consuming Tavily, Firecrawl, or other paid-search API credits.

This is a distributable skill pack that combines a global Skill and a local CLI. It uses DDGS/SearXNG for discovery and local tools to read HTML, JSON, plain text, and PDF, with caching, deduplication, and explicit fallback escalation rules to reduce paid tool usage.

Quick Installation

Requires Python 3.10+. The installer creates an isolated virtual environment, installs the CLI, copies the skill files, and adds user-level executable commands without touching system Python.

python3 scripts/install.py

You can also distribute this repository as a standalone Skill; it already includes the full CLI source and installer. Run:

python3 scripts/install.py

Default install paths:

  • Skill: ${CODEX_HOME:-~/.codex}/skills/web-search-free
  • CLI virtualenv: ~/.local/share/free-web-research/venv
  • Executable: ~/.local/bin/free-web-research

To enable local browser rendering:

python3 scripts/install.py --with-browser

Windows:

py scripts/install.py

Usage

free-web-research health --online
free-web-research search "Tencent latest quarter results official" --max-results 5 --prefer-domain tencent.com
free-web-research fetch "https://www.tencent.com/investors/"
free-web-research fetch "https://example.com/dynamic" --fallback jina,browser
free-web-research cache stats

Default output is JSON for agent consumption. Use --format markdown for human-friendly results.

Update and Uninstall

Re-run the installer from the updated folder with recoverable backup allowed:

python3 scripts/install.py --force

Uninstall uses movable backup by default instead of permanent deletion:

python3 scripts/uninstall.py --yes

Free/No-API Boundary

This project does not call any paid search API by itself. DDGS and SearXNG are still external search systems and may face rate limits, CAPTCHAs, or upstream policy changes. Jina Reader is an optional fallback and may also have free usage limits. The CLI only indicates whether escalation to paid tools is recommended; it does not automatically invoke Tavily or Firecrawl.