Wiggle‑on‑the‑Web：wigolo 的功能

摘要

• wigolo 是一个本地优先、默认零密钥成本的网页工具包**，专为 AI 代理设计**。
• 它整合了搜索、抓取、爬取与提取，以及更高阶的研究和自主收集循环，代理协调器（Claude 5 Fable …）可通过 MCP JSON‑RPC over stdio 或 REST 调用。
• 所有搜索引擎无关的工作流程‑‑18 引擎融合抓取‑‑ML 重排序‑‑可解释‑‑缓存‑‑离线‑‑私密**。
• 可选的 LLM 合成（Gemini、Anthropic、OpenAI、Groq、Ollama）将原始证据转化为完整答案。
• 在 macOS、Linux 或 Windows 上运行于 Node ≥ 20（约 1.5 GB 磁盘空间）；以 npm CLI、Docker 镜像、SDK（TS/Python）和 MCP 服务器形式提供。

---

它实际上是什么

面向	细节
类别	本地优先的 AI 代理网页智能层（搜索、抓取、爬取、提取、缓存、相似度、研究、自主循环）。
主要接口	MCP（JSON‑RPC over stdio）——与 Claude Code、Cursor、Codex、Gemini CLI 等编码代理使用的相同协议。
次要接口	REST API（wigolo serve）、TypeScript 与 Python SDK、Docker 容器、框架封装（LangChain、CrewAI、LlamaIndex、Vercel AI SDK）。
关键主张	• 核心工具（搜索/抓取/爬取/…）无需 API 密钥；• 每次查询零成本‑‑所有缓存皆为本地；• 证据丰富的结果，附带字节精确引用与可解释评分；• 在初次下载无头浏览器引擎与设备端模型后可离线运作。
支持的代理	Claude Code、Cursor、Codex、Gemini CLI、OpenCode、VS Code、Windsurf、Zed、Antigravity（可添加任何 MCP 客户端）。
安装	npx wigolo init（下载浏览器引擎与设备端模型），可选 --agents 自动连接代理，--interactive/--wizard 进行引导式设置，wigolo doctor 验证健康状态。
核心工具	search、fetch、crawl、extract、cache、find_similar、research、agent、diff、watch。
结果结构	JSON 包含 results（标题、url、摘要、citation_id、source_span、evidence_score）、citations 和新鲜度信号。
隐私	所有缓存、嵌入和模型皆位于 ~/.wigolo/ 下；除非您启用 LLM 提供商，否则不会向第三方服务发送任何内容。
授权	AGPL‑3.0（见 LICENSING.md）。
状态	公开测试版‑‑积极维护中（CI 徽章、星标历史、Discord 社区）。

---

运作方式（简化）

1. 代理 → wigolo – AI 代理发出 MCP/REST 调用，例如 search {query:"…"}。
2. 工具层 – wigolo 将请求扇出至多个网页引擎适配器（18 个引擎），合并结果，运行设备端 ML 重排序器，并附加透明评分。
3. 抓取路由器 – 对于 URL，wigolo 首先尝试纯 HTTP 抓取；若检测到机器人挑战或 SPA，则升级至无头浏览器池。
4. 缓存与嵌入 – 结果存储在本地（关键词 + 向量索引），因此重复查询即时且可离线。
5. 可选合成 – 若设置 WIGOLO_LLM_PROVIDER，选定的 LLM 会将证据改写为精炼答案；否则返回原始证据。
6. 响应 – 代理收到结构化 JSON，包含引用、字节精确摘录、评分及任何降级标志。

---

何时会使用它？

• 您有编码助手（Claude Code、Cursor 等），并希望它能浏览网页而不暴露 API 密钥或按查询付费。
• 您需要可重现、可审计的证据 – 每个片段都固定到其精确的字节偏移并评分。
• 您在本地运行代理（自托管 LLM、私有数据），并要求网页层保持本地。
• 您想要在 LangChain、CrewAI、LlamaIndex 等中直接替换云端网页搜索 API，且查询零成本。
• 您在初次引擎下载后需要离线能力（例如在 CI 管道或气隙环境中）。

---

快速入门检查清单

# 1. 安装与初始化（下载浏览器与模型）
npx wigolo init

# 2. 验证健康状态
npx wigolo doctor

# 3. 从 CLI 尝试搜索
wigolo search "local‑first software" --json

# 4. 运行 REST 服务器（可选）
wigolo serve   # → http://127.0.0.1:3333

# 5. 使用 Python SDK（示例）
python - <<'PY'
from wigolo import local_client
with local_client() as c:
    print(c.search(query='local‑first web search')['results'][0]['title'])
PY

---

限制与未解问题

领域	当前状态
网页引擎覆盖范围	18 个适配器，但某些利基或付费 API 可能仍缺失。
LLM 合成	可选，且仍需外部密钥（Gemini 免费层、OpenAI 等）。
重量级爬取	专为研究级量级设计；大规模企业爬取可能需要专用爬虫。
平台	基于 Node；非 Node 环境必须使用 REST/SDK 桥接。
授权	AGPL‑3.0 – 可能影响商业再分发。

---

何处找到更多信息

• 文档 – docs/README.md（安装、CLI、工具、REST、SDK、自托管）。
• 示例 – examples/README.md（真实世界代理脚本）。
• 社区 – Discord 链接、X @yourtowhid。
• 基准测试 – README 中的章节将 wigolo 与 Firecrawl、Exa 和 Tavily 进行比较。

---

以上所有陈述直接取自仓库的 README；未推断任何额外功能。