引言

“The go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. No API keys, no cloud, $0/query.”

这是「每日一个开源项目」系列的第 163 篇。今天的项目是 wigolo —— 一个专为 AI agent 设计的本地优先 Web 情报工具，通过 MCP 提供搜索、抓取、爬取、研究等能力，零 API Key，零查询费用。

给 AI agent 配「搜索工具」是一个看似简单实则分层很深的问题。Tavily、Exa、Firecrawl 这些云端服务已经很成熟，但它们都有一个共同特征：按查询计费、数据出境、需要注册账号。wigolo 的切入点是：搜索引擎的 raw data 是公开的，排序和提取的算法是可以本地跑的，为什么 agent 的每一次搜索都要付费、都要走云端？

1,218 颗 Star，创建于 2026 年 4 月，公开测试阶段。

你会学到什么

• wigolo 的 10 个工具及其设计逻辑
• 「字节级来源定位」和「可解释评分」是什么，为什么重要
• 本地优先架构：哪些组件本地跑，哪些需要选择性接入云端
• 与 Tavily、Exa、Firecrawl 的横向对比：各自的差异化定位
• 什么场景适合用 wigolo，什么场景云端工具更合适

前提知识

• 使用过 Claude Code 或任意 AI agent
• 了解 MCP（Model Context Protocol）的基本概念
• 对 AI agent 的工具调用机制有基本认知

---

项目背景

概述

wigolo 是一个 Node.js 进程，以 MCP server 形式暴露 10 个 Web 相关工具，让 AI agent 通过标准 MCP 协议调用搜索、抓取、爬取、提取等功能。

核心设计原则：

• 本地优先：缓存、向量索引、嵌入模型、重排序模型都跑在本地（~/.wigolo/）
• 零强制 API Key：搜索、抓取、爬取、提取、缓存、相似查找六个核心工具不需要任何 API Key
• 显式失败：Bot 拦截、失效引擎、陈旧缓存都会在结果里明确标注，不会伪装成空结果

项目信息

• 作者: KnockOutEZ
• 主语言: TypeScript
• 许可证: AGPL-3.0
• 状态: Public Beta
• 官网: knockoutez.github.io/wigolo

项目数据

• ⭐ GitHub Stars: 1,218+
• 🍴 Forks: 83+
• 📄 许可证: AGPL-3.0
• 📅 创建时间: 2026-04-12

---

快速安装

# 一条命令完成初始化：下载浏览器引擎和本地模型，写入 MCP 配置
npx wigolo init --agents=claude-code

# 或多个 agent 同时配置
npx wigolo init --agents=claude-code,cursor,codex

# 检查所有组件健康状态
npx wigolo doctor

需要 Node ≥ 20，约 1.5 GB 磁盘空间（浏览器引擎 + 本地 ML 模型）。

安装后所有核心工具立即可用，无需任何 API Key。如果需要 research 和 agent 工具的「综合答案」输出（而不是原始数据），接入一个免费的 Gemini key 是最大的质量提升：

export WIGOLO_LLM_PROVIDER=gemini
export GEMINI_API_KEY=<aistudio.google.com 上的免费 key>

也可以用 Ollama 本地模型完全不出境：WIGOLO_LLM_PROVIDER=ollama。

---

10 个工具详解

核心检索工具

search — 多引擎并行搜索

• 18 个直连引擎适配器（不走中间代理 API）
• rank fusion 合并多引擎结果 + ML 重排序
• 传入 query 数组可并行发出多个查询（一次 MCP 调用扇出多个搜索）
• 每个结果附带可解释评分：semantic + lexical + engine_consensus 三路得分

fetch — 分级路由页面抓取

纯 HTTP 请求
    ↓（失败或检测到 SPA 标志）
无头浏览器（处理 JS 渲染）
    ↓（遭遇 Bot 挑战）
挑战清除流程
    ↓（清除失败）
标注 blocked_by_challenge，不伪装成内容

学习每个域名的「需要哪一级抓取」，不重复踩坑。

crawl — 多页爬取

支持 BFS、DFS、sitemap 模式或仅建立站点地图（map-only）。遵守 robots.txt，有 per-domain rate limit，内置模板去重。

extract — 结构化提取

从页面提取：表格、JSON-LD、metadata、品牌资产、命名 schema（Article / Recipe / Product / …），或传入自定义 JSON Schema 提取任意结构。

记忆与发现工具

cache — 本地语义缓存

所有访问过的页面自动缓存。支持关键词查询和语义相似查询，离线可用。还提供缓存统计、清空、变更检测。

find_similar — 相似内容发现

找与某 URL 或概念相似的页面，三路融合：关键词 + 语义 + 实时 Web。

研究与自治工具

research — 深度研究

分解问题 → 并行发出子查询 → 抓取来源 → 合成带引用的报告（或生成结构化摘要由宿主 LLM 自行撰写）。

agent — 自治 gather 循环

自主规划 → 搜索 → 抓取 → 提取 → 综合，支持时间预算和可选输出 JSON Schema。

监控工具

diff + watch — 页面变更检测

查看某 URL 自上次访问以来发生了什么变化；设置定期监控，将变更推送到 webhook。

---

核心特性深度解析

字节级来源定位（Byte-Pinned Provenance）

这是 wigolo 在所有对比工具中独有的特性。每个搜索结果不只返回摘要，还附带：

{
  "excerpt": "Logical replication is a method of replicating data objects…",
  "citation_id": "src-1",
  "source_span": { "start": 1042, "end": 1305 },
  "evidence_score": {
    "final": 0.86,
    "semantic": 0.91,
    "lexical": 0.78,
    "engine_consensus": 3
  }
}

source_span 精确到字节偏移量 —— agent 引用这段内容时，可以明确追溯到原文的哪个位置，不是「大概在这篇文章里」。

evidence_score 是可解释的三路分数：语义相关度 + 词汇匹配度 + 多少引擎也返回了这个结果（engine_consensus）。弱结果被 wigolo 自身的评分器标记为 junk 并在结果里显示，不是悄悄过滤掉。

为什么重要：AI agent 在构建 RAG 或回答需要引用来源的问题时，字节级定位让引用可以真正可验证，而不是模糊的「参考了某篇文章」。

本地优先架构

AI agent（任意 MCP 客户端 / REST / SDK）
    ↓
wigolo 进程（单 Node 进程）
    │
    ├── 搜索层
    │   18 个引擎直连适配器
    │   rank fusion + ML 重排序（本地模型）
    │
    ├── 抓取层
    │   分级路由（HTTP → 无头浏览器 → 挑战清除）
    │   per-domain 学习 + 缓存复用
    │
    ├── 本地存储（~/.wigolo/）
    │   关键词索引 + 向量索引（本地嵌入模型）
    │   浏览器引擎 + ML 模型
    │
    └── 可选接入（虚线）
        LLM API（仅用于 research/agent 综合答案）
        聚合器后端（扩展搜索宽度，legacy 模式）

哪些组件是本地的：

• ✅ 搜索引擎直连适配器
• ✅ ML 重排序模型
• ✅ 向量嵌入模型（all-MiniLM-L6-v2 等）
• ✅ 无头浏览器引擎
• ✅ 本地缓存（SQLite + 向量索引）

哪些是可选云端：

• 🔲 LLM 合成（research/agent 输出综合答案时）
• 🔲 聚合器后端（扩宽搜索漏斗，可选）

---

横向对比：wigolo vs Tavily / Exa / Firecrawl

这是本文的重点部分。wigolo 在 README 里有一张对比表，但缺少对各工具定位和使用场景的深度说明。

功能矩阵

能力	wigolo	Tavily	Exa	Firecrawl
多引擎 Web 搜索	✅	✅	✅	✅
页面抓取与结构化提取	✅	✅	✅	✅
全站爬取	✅	✅	—	✅
字节级来源定位	✅	—	—	—
可解释评分分解	✅	—	—	—
持久本地缓存（支持离线再查询）	✅	—	—	—
查询数据留在本机	✅	—	—	—
需要 API Key / 账号	无	必须	必须	必须
查询费用	$0	按量计费	按量计费	按量计费

各工具的实际定位

Tavily — 专门为 AI agent 设计的搜索 API，目前是「RAG + agent 搜索」场景里最常被集成的付费服务。优势是产品成熟、LangChain/LlamaIndex 等框架原生支持、搜索质量经过专门优化；劣势是按查询计费，agent 频繁调用时成本会快速累积。

Exa — 定位为「语义 Web 搜索」，擅长理解查询的含义而不只是关键词匹配。有一个显著特点：官方文档页面、技术内容的检索质量很高（README 的基准测试里提到 Exa 能完整渲染官方文档的对比矩阵）。同样需要注册 + 按量计费。

Firecrawl — 专注于网页爬取和结构化提取，而不是搜索。主要优势是处理复杂 JS 渲染页面、大规模爬取任务、结构化数据提取的能力。适合「给定一批 URL，批量提取结构化内容」的场景，而不是「给定问题，搜索相关内容」。

wigolo — 试图把上述三种能力合并到一个本地工具里，同时消除 API Key 和费用。核心差异化：字节级来源定位、可解释评分、本地缓存（支持离线再查询）、$0 查询成本。

使用场景推荐

选 wigolo 的场景：

• 开发过程中频繁做技术文档查询（无需付费限制）
• 需要来源可追溯性（字节级定位 → agent 引用可核验）
• 隐私要求高，不希望查询内容传出本机
• agent 查询量大，云端 API 成本是问题
• 需要结合本地缓存做「记忆型」研究任务

选 Tavily 的场景：

• 需要开箱即用的生产级质量，不想维护本地依赖
• 已在 LangChain/LlamaIndex 生态，需要框架原生集成
• 查询量可控，按量付费可接受

选 Exa 的场景：

• 主要查询技术文档、学术内容，对语义相关性要求高
• 需要高质量的官方文档检索（文档页面渲染能力强）

选 Firecrawl 的场景：

• 批量爬取特定网站，提取结构化内容（非搜索场景）
• 大规模网页内容处理管道

一个诚实的限制

wigolo 的 README 里提到了一点：数据中心 IP 在 IP 信誉评分上不如家庭网络，某些有反爬措施的网站在云服务器上运行时清除率会低于本地。自托管场景需要注意这一点，README 里提供了可选代理方案。

---

其他接入方式

wigolo 不只是 Claude Code 插件，支持多种调用方式：

REST API

wigolo serve   # 启动在 127.0.0.1:3333

curl -sX POST http://127.0.0.1:3333/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"local-first software","max_results":5}'

跨越 loopback 的连接强制要求 bearer token，fail-closed 设计。

TypeScript / Python SDK

from wigolo import local_client

with local_client() as client:
    res = client.search(query="local-first web search", max_results=5)
    for r in res["results"]:
        print(r["title"], r["url"])

SDK 自动复用已运行的 daemon，或在需要时启动一个，调用结束后按需关闭。

框架集成

框架	包名	提供的接口
LangChain	wigolo-langchain	每个工具作为 BaseTool + RAG 用的 BaseRetriever
CrewAI	wigolo-crewai	wigolo_tools() 直接传给 crew
LlamaIndex	wigolo-llamaindex	BaseReader，把页面加载为 documents
Vercel AI SDK	wigolo-vercel-ai-sdk	generateText/streamText 的 tool factory

---

参考资源

官方链接

• 🌟 GitHub: KnockOutEZ/wigolo
• 🌐 官网: knockoutez.github.io/wigolo
• 📦 npm: wigolo
• 📄 文档: docs/README.md

---

总结

wigolo 的核心主张是：agent 的 Web 访问层不应该是一个持续计费的云端 API 黑盒。搜索引擎的原始数据是公开的，重排序和提取算法可以本地跑，查询历史可以缓存到本地语义索引里 —— 这些事情加在一起，就是一个零费用、数据留本地、可离线复用的 Web 情报层。

两个设计决策值得单独记：

字节级来源定位：在所有对比工具里独有。agent 引用搜索结果时，source_span 给出字节偏移量，引用可以真正追溯到原文位置。对于需要「来源可验证」的研究类任务，这个特性直接减少了一层「AI 可能在编造引用位置」的不确定性。

显式失败而非沉默：Bot 拦截标注为 blocked_by_challenge，失效引擎上报，弱结果被评分器标记为 junk 并显示在结果里。这种「始终告诉你它站在什么地基上」的设计，在 agent 场景里比「假装成功」要可靠得多。

如果你的 Claude Code 日常工作里有大量文档查询、技术信息搜索，或者正在构建需要 Web 搜索的 agent pipeline，wigolo 的 npx wigolo init --agents=claude-code 是目前成本最低的接入方式 —— 字面意义上的零成本。

---

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。