diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 000000000..d52bc3640 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,419 @@ +
+ +wigolo — エージェントのための頼れる Web ツール + +AI エージェント向けのローカルファーストな Web インテリジェンス — **キー不要、クラウド不要、従量課金なし。** + +対応  **Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity** +
+さらに  **LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n とセルフホスト型エージェント · あらゆる MCP クライアント · 素の REST** + +[![npm](https://img.shields.io/npm/v/wigolo?color=cb3837&logo=npm)](https://www.npmjs.com/package/wigolo) +[![npm downloads](https://img.shields.io/npm/dm/wigolo?color=cb3837&logo=npm&label=downloads)](https://www.npmjs.com/package/wigolo) +[![GitHub stars](https://img.shields.io/github/stars/KnockOutEZ/wigolo?style=flat&logo=github&color=e3b341)](https://github.com/KnockOutEZ/wigolo/stargazers) +[![CI](https://img.shields.io/github/actions/workflow/status/KnockOutEZ/wigolo/ci.yml?branch=main&logo=github&label=CI)](https://github.com/KnockOutEZ/wigolo/actions/workflows/ci.yml) +[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org) +[![MCP](https://img.shields.io/badge/MCP-server-7c3aed)](https://modelcontextprotocol.io) +[![license](https://img.shields.io/badge/license-AGPL--3.0-2563eb)](#ライセンス) +[![status](https://img.shields.io/badge/status-public%20beta-b7791f)](#ベータ版とフィードバック) +[![follow on X](https://img.shields.io/badge/follow-%40yourtowhid-000000?logo=x&logoColor=white)](https://x.com/yourtowhid) + +Trendshift の wigolo +KnockOutEZ%2Fwigolo | Trendshift + +[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) + +[クイックスタート](#クイックスタート) · [ツール](#ツール) · [wigolo の違い](#違い) · [ベンチマーク](#ベンチマーク) · [ドキュメント](docs/README.md) · [例](examples/README.md) · [フィードバック](#ベータ版とフィードバック) · [よくある質問](#よくある質問) + +新機能とアップデートは継続的にリリースされます。X で @yourtowhid をフォローして、すべての更新情報や wigolo の新しい活用方法をご覧ください。協業やフィードバックについては X、または LinkedIn からご連絡ください。 + +
+ +--- + +wigolo は、Web に関するあらゆる操作を AI エージェント向けの一つのインターフェースにまとめます。対象は**検索、取得、クロール、抽出、キャッシュ、類似検索、リサーチ**、そして自律的な収集ループです。エージェントが動く場所ならどこでも実行できます。コーディングエージェントの隣で MCP サーバーとして、セルフホスト型エージェントが動くマシン上で REST/MCP エンドポイントとして、あるいは SDK を通じて独自アプリに組み込めます。中核ツールに API キーは不要で、扱ったデータが `~/.wigolo/` の外に出ることはなく、エージェントが考えるほど請求額が増えることもありません。 + +
+ +wigolo のデモ — Claude Code が API キーなしで wigolo を通じてリアルタイムの Web 質問に回答 + +
+ +## クイックスタート + +```bash +npx wigolo init # set up the local engine — any system +npx wigolo init --agents=claude-code,cursor # …or set up + wire your day-to-day agents in one command +``` + +**Node ≥ 20** と、macOS、Linux、Windows のいずれかで約 1.5 GB の空きディスク容量が必要です。引数なしの `init` はローカルエンジンをセットアップします。ブラウザーエンジンとオンデバイスモデルをダウンロードし、ヘルスチェックを実行して各コンポーネントを報告します。`--agents` を追加すると同じ実行内で指定したエージェントも接続されるため、日常的に使うコーディングエージェントを一つのコマンドで利用可能にできます。 + +- **対応エージェント** — `--agents` には `claude-code`、`cursor`、`codex`、`gemini-cli`、`vscode`、`windsurf`、`zed`、`antigravity` の任意の組み合わせを指定できます（カンマ区切り）。wigolo は各エージェントの MCP 設定と指示を書き込みます。 +- **その他のセットアップ** — あらゆる MCP クライアント、エージェントフレームワーク、セルフホスト型エージェントは、自身の MCP 設定に `npx -y wigolo` を登録できます。[インストールガイド](docs/installation.md)には、各クライアント向けの正確な設定ブロックに加え、Docker、Homebrew、単一ファイルバイナリの導入方法があります。 +- **今後も追加予定** — 対応リストは拡大を続けています。お使いのエージェントを追加する PR も歓迎します。[CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。 +- **対話型セットアップ** — `--interactive` はプレーンテキストのフロー、`--wizard` は完全なターミナル TUI です。 +- **ダウンロードの延期** — `--no-warmup` は初回利用までダウンロードを待ちます。コンポーネントのダウンロード失敗でセットアップ全体が失敗することはありません。init は準備できていない項目と正確な修正方法を報告し、そのまま完了します。 + +`init` は既定で無人実行されるため、スクリプトや CI でも安全に利用できます。セットアップ上の問題は、エージェントが初めて呼び出す前に、このコンポーネント別レポートへ表示されます。**検索、取得、クロール、抽出、キャッシュ、類似検索は API キーなしで動作します。**次のコマンドでいつでも状態を確認できます。 + +```bash +npx wigolo doctor +``` + +すべてをきれいに削除するには `npx wigolo config --uninstall --yes` を実行します。[インストールガイド](docs/installation.md)を任意の AI アシスタントに貼り付け、セットアップを任せることもできます。このガイドは単独で完結するように書かれています。 + +### 推奨 — `research` と `agent` 用の無料キー + +検索、取得、クロール、抽出、キャッシュ、類似検索は**完全にキー不要**です。`research`、`agent`、`search format=answer` は LLM を使い、統合された引用付きの回答を作成します。LLM がない場合は、エージェントがまとめられるように生のブリーフと証拠を返します。無料の Gemini キーを使えば、完成した回答を生成できます。 + +```bash +export WIGOLO_LLM_PROVIDER=gemini +export GEMINI_API_KEY= # grab one at aistudio.google.com/apikey — the free tier is plenty +``` + +どのプロバイダーでも利用できます（`anthropic`、`openai`、`groq`）。`WIGOLO_LLM_PROVIDER=ollama`（または任意の OpenAI 互換 URL）を指定すれば、完全にローカルかつキーなしでも利用できます。シェルまたはエージェントの MCP `env` ブロックに設定してください。プロバイダー、モデル、キー不要のローカルモデルフォールバックについては[設定ガイド](docs/configuration.md)をご覧ください。 + +## エージェントが受け取るもの + +各検索結果は、エージェントが行動に利用できる証拠です。ソース内の正確な位置に固定された逐語的な抜粋、エージェントが引用できる引用 ID、そして確認可能なスコアが含まれます（以下は実際の形式を簡略化したものです）。 + +```jsonc +{ + "results": [{ + "title": "Logical replication - PostgreSQL docs", + "url": "https://www.postgresql.org/docs/current/logical-replication.html", + "excerpt": "Logical replication is a method of replicating data objects…", + "citation_id": "src-1", + "source_span": { "start": 1042, "end": 1305 }, // byte-exact provenance + "evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 } + }], + "citations": [{ "id": "src-1", "url": "…" }], + "freshness_signal": { "published": "2026-05-12", "confidence": "high" } +} +``` + +品質の低い結果は wigolo 自身のスコアラーによって不要な結果としてマークされます。失敗したエンジンは報告され、古いキャッシュにもラベルが付くため、エージェントは常に何を根拠にしているか把握できます。ツールごとの完全なレスポンス契約は[ツールリファレンス](docs/tools.md)にあります。 + +## ツール + +| ツール | 機能 | +|------|--------------| +| 🔎 `search` | 複数エンジンによる Web 検索（18 の直接アダプター）。ランキング融合、ML 再ランキング、説明可能な結果別スコアを備えています。クエリの**配列**を渡すと、並列に広く検索できます。ドメインと期間による絞り込み、完全一致フレーズ、画像結果にも対応します。 | +| 📄 `fetch` | 段階的ルーターを通じて一つの URL を読み込みます。ボット対策や SPA シェルを検出すると、通常の HTTP からヘッドレスブラウザーへ自動的に切り替わります。きれいな Markdown、メタデータ、リンクを返します。PDF、単一見出しの `section`、認証済みセッション、ページ操作（クリック、入力、スクロール、スクリーンショット）に対応します。 | +| 🕸️ `crawl` | 複数ページをクロールします。BFS、DFS、サイトマップ、マップのみのモードを選べます。ドメインごとのレート制限、robots.txt の尊重、定型部分の重複排除に対応します。 | +| 🧩 `extract` | ページから構造化データを抽出します。テーブル、メタデータ、JSON-LD、ブランド情報、名前付き schema（Article、Recipe、Product など）、または任意のカスタム JSON Schema に対応します。 | +| 💾 `cache` | これまでに取得したすべての内容を、キーワードまたはハイブリッド意味検索で照会します。統計、消去、変更検出も提供します。 | +| 🧲 `find_similar` | キーワード、意味検索、リアルタイム Web の 3 方向融合により、URL や概念に似たページを見つけます。 | +| 🧠 `research` | 質問を分解 → サブクエリを並列実行 → ソースを取得 → 引用付きレポートへ統合（またはホスト LLM が執筆する構造化ブリーフを返却）します。 | +| 🤖 `agent` | 自律的な収集ループです。計画 → 検索 → 取得 → 抽出 → 統合を、ステップログ、時間制限、任意の出力 schema とともに実行します。 | +| 🔁 `diff` + ⏱️ `watch` | 前回の訪問以降にページで変わった内容を正確に確認し、必要に応じて再チェックして webhook に変更を配信します。 | + +すべてのツールは、ターミナル（`wigolo search "…" --json`）、NDJSON パイプを使える対話型シェル（`wigolo shell`）、REST、SDK からも実行できます。詳しくは [CLI リファレンス](docs/cli.md) をご覧ください。完全なパラメーターを含むツール別ガイドは [docs/tools.md](docs/tools.md)、実行可能な例は [examples/](examples/README.md) にあります。 + +## 違い + +wigolo は有料ツールの安価な代用品ではなく、同等の性能を目指して構築されています。エージェント専用の Web レイヤーとして、MCP と REST のインターフェースを直接呼び出せます。有料サービスが課金して提供する検索・抽出品質を実現します。主な違いは次のとおりです。 + +- **エージェント専用の設計。**一度の MCP 呼び出しで複数のクエリを複数のエンジンへ並列展開できます。これは直列的なホストツールループでは再現できません。各結果には透明なスコアが付き、出力はコンテキスト予算を考慮します。 +- **正直な出力。**古いキャッシュ、取得失敗、劣化したバックエンド、切り捨ては結果に明示されます。ボット保護されたページを読めない場合は、チャレンジ画面を内容として返すのではなく、`blocked_by_challenge` と明示された失敗が返ります。 +- **1 クエリ 0 ドル、再照会も無料。**既定の検索は直接アダプターを通じて公開エンジンへ接続し、再ランカーと埋め込みはデバイス上で動きます。すべてのレスポンスがキャッシュされるため、同じ質問には即座に無料で応答できます。 +- **プライバシーを既定で保護。**キャッシュ、埋め込み、モデル、設定は `~/.wigolo/` に保存されます。統合処理に LLM を明示的に選択しない限り、第三者へ送信されるものはありません。 + +以下は実際の結果を分解したものです。失敗したエンジンと弱い結果も回答の一部であるため、そのまま含まれています。 + +
+ + + +wigolo の結果を分解：説明可能なスコア内訳、ライブのエンジンテレメトリ、明示された劣化、自動的にマークされた不要な結果 — 実際の一回のクエリ + + +
+ +## ベンチマーク + +> **4 つのツールはすべて同じ中核的な回答に到達し、そのうち一つだけが逐語的かつバイト単位で位置づけられた証拠を返しました。** + +一つのコールドクエリを単一の **Claude Fable 5** セッション内でリアルタイムに実行し、4 つの Web ツール（組み込みの **WebSearch**、**wigolo**、**Tavily**、**Exa**）へ同じ条件で展開しました。エージェントは証拠だけを基に評価しました。4 つすべてが同じ回答と同じ最上位ソースに到達したため、画面上で同等性が示されています。逐語的な抜粋をバイトオフセットのソース範囲に固定し、説明可能なスコア内訳とエンジン別のライブテレメトリを返したのは wigolo だけでした。さらに自身のスコアラーが二つの弱い結果を不要なものとしてマークしました。クラウドツールにも強みがあります。Exa は公式ドキュメントの比較マトリクスを完全にレンダリングしました。独自のクエリを実行しても、同じ形の結果を確認できます。 + +
+ +Claude Fable 5 が実行した一つの実クエリで wigolo、組み込み WebSearch、Tavily、Exa を比較 + +
+ +### 比較 + +| | wigolo | Firecrawl | Exa | Tavily | +|---|:---:|:---:|:---:|:---:| +| 複数エンジン Web 検索 | ✅ | ✅ | ✅ | ✅ | +| 取得と構造化抽出 | ✅ | ✅ | ✅ | ✅ | +| サイト全体のクロールとマップ | ✅ | ✅ | — | ✅ | +| バイトオフセットのソース範囲に固定された逐語的な抜粋 | ✅ | — | — | — | +| 説明可能な結果別スコア内訳 | ✅ | — | — | — | +| 永続的なローカルメモリ — 即時かつオフラインで再照会 | ✅ | — | — | — | +| クエリデータをローカルに保持 | ✅ | — | — | — | +| API キー / アカウント | 不要 | 必要 | 必要 | 必要 | +| クエリごとの費用 | 0 ドル | 従量課金 | 従量課金 | 従量課金 | + +機能の状況は 2026 年 7 月時点です。最新情報は各ベンダーのドキュメントをご確認ください。 + +エージェントは短時間に多くの質問をするため、最後の行の差は積み重なります。 + +
+ + + +メーター：従量課金のクラウド API はクエリごとに費用が増える一方、wigolo は常に 0 ドル — 料金の例示 + + +
+ +## エディターの外でも + +同じ 10 個のツールをあらゆる種類のエージェントで利用できます。用途に合うインターフェースを選べます。コーディングエージェントには MCP、それ以外には REST、組み込みには SDK、既存フレームワークにはラッパーを使えます。 + +### REST API — `wigolo serve` + +一つのプロセスが MCP トランスポートと並んでプレーン JSON の REST API を公開します。MCP クライアントは不要で、curl だけで利用できます。 + +```bash +wigolo serve # 127.0.0.1:3333 — loopback is open; off-loopback requires a token + +curl -sX POST http://127.0.0.1:3333/v1/search \ + -H 'Content-Type: application/json' \ + -d '{"query":"local-first software","max_results":5}' +``` + +`POST /v1/{tool}` は 10 個すべてのツールを扱い、`GET /openapi.json` は OpenAPI 3.1 契約を提供します。`/mcp` と `/sse` は同じポートからリモート MCP クライアントへサービスを提供します。ループバック以外へバインドする場合は bearer token が必須で、サーバーは既定で安全側に失敗します。n8n、Hermes 形式のアシスタント、任意のセルフホスト型エージェントを接続できます。→ [REST API](docs/rest-api.md) + +### SDK — TypeScript と Python + +軽量で型付きのクライアントです。ローカル埋め込みモードがデーモンを検出し、必要なら起動します。別途 `serve` を実行する必要はありません。 + +**TypeScript** — `npm install wigolo-sdk`（依存関係なし。Node、Bun、Deno、edge に対応）： + +```ts +import { createLocalClient } from 'wigolo-sdk/local'; + +const { client, close } = await createLocalClient(); // reuse a running daemon, or spawn one +const res = await client.search({ query: 'local-first web search', max_results: 5 }); +console.log(res.results.map((r) => r.title)); +await close(); // stops the daemon only if this call spawned it +``` + +**Python** — `pip install wigolo`（標準ライブラリのみ。同期と非同期に対応）： + +```python +from wigolo import local_client + +with local_client() as client: # reuse a healthy daemon, or spawn one + res = client.search(query="local-first web search", max_results=5) + for r in res["results"]: + print(r["title"], r["url"]) +``` + +→ [SDK と埋め込みモード](docs/sdks.md) + +### フレームワーク連携 + +wigolo のツールを既に利用しているフレームワークへそのまま追加できます。多くのフレームワーク用 Web ツールにはない cache、find_similar、research、agent を含む、10 個すべてのツールを利用できます。 + +| フレームワーク | パッケージ | 利用できるもの | +|-----------|---------|--------------| +| **LangChain** | `wigolo-langchain` | 各ツールを `BaseTool` として提供し、RAG 用に search / find_similar を使う `BaseRetriever` も提供 | +| **CrewAI** | `wigolo-crewai` | `wigolo_tools()` → 任意の crew に一式を渡せます | +| **LlamaIndex** | `wigolo-llamaindex` | 取得、クロール、検索したページをドキュメントとして読み込む `BaseReader` | +| **Vercel AI SDK** | `wigolo-vercel-ai-sdk` | `generateText` / `streamText` 用のツールファクトリー。edge 対応 | + +→ [フレームワーク連携](docs/sdks.md) + +### Docker + +```bash +# stdio MCP — wire it into any MCP client as command: docker +docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo + +# HTTP server for remote / multi-client use +docker run -p 3333:3333 -v wigolo-data:/data \ + -e WIGOLO_API_TOKEN=a-long-random-secret \ + ghcr.io/knockoutez/wigolo serve --host 0.0.0.0 +``` + +スリムイメージはモデルをボリュームへ遅延読み込みします。`:full` はブラウザーエンジンを事前インストールします。Docker Hub では `towhid69420/wigolo` としても提供されています。→ [インストールと全配布チャネル](docs/installation.md) + +### エージェントスキル + +11 個のスキルカタログが、コーディングエージェントに各ツールの効果的な使い方を教えます。`init` によってインストールされ、`wigolo skills add|list|remove` で管理します。→ [スキル](docs/skills.md) + +セルフホスト時の注意点として、一部のチャレンジ保護サイトは IP レピュテーションを評価するため、家庭回線では通過できる壁をデータセンター IP では通過できない場合があります。wigolo はその失敗を明示し、[セルフホストガイド](docs/self-hosting.md)では任意で利用できるプロキシによる解決策を説明しています。 + +## Star の推移 + +
+ + + + +wigolo の GitHub Star 推移 + + + +GitHub API から毎日更新されます。wigolo が役に立ったら⭐ を付けてください。 + +
+ +## アーキテクチャ + +一つの Node プロセスが stdio 経由で MCP（JSON-RPC）を処理します。重い処理はすべてローカルで遅延読み込みされるため、キーなしのインストールでは使わない部分のコストを負いません。 + +```mermaid +flowchart TD + A["🤖 AI agent
any MCP client · REST · SDK"] + A -->|MCP over stdio| B["wigolo
10 tools · dynamic instructions
in-process browser pool + cache + models"] + + B --> C{"Tool layer"} + C --> T1["search · fetch · crawl · extract"] + C --> T2["cache · find_similar · research · agent"] + + T1 --> F["⚙️ Fetch router
tiered escalation, learned per domain"] + T1 --> S["⚙️ Search
18 engines → rank fusion → ML rerank
explainable evidence score"] + T2 --> DB[("🗄️ Local cache
keyword + vector index")] + T2 --> ML["🧠 On-device ML
embeddings + reranker"] + + F -.->|optional| LLM["☁️ LLM
synthesis only · opt-in"] + S -.->|optional| SX["🔀 Aggregator backend
opt-in legacy / hybrid"] + + F --> WEB["🌍 Public web"] + S --> WEB + + style B fill:#7c3aed,stroke:#5b21b6,color:#fff + style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff + style DB fill:#1e293b,stroke:#334155,color:#fff + style LLM stroke-dasharray: 5 5 + style SX stroke-dasharray: 5 5 +``` + +- **コードで処理できることをモデルに任せない。**正規化、ランキング融合、重複排除、schema 照合などの決定的な処理はコードで行います。モデルは判断にのみ使い、明示的に有効化し、リクエストごとに上限を設けます。LLM が埋めたフィールドはソースと照合し、存在しなければ null にします。 +- **シグナル駆動のルーティング。**取得の段階的処理は、ドメインの推測ではなく観測可能なシグナルに基づいて実ブラウザーへ切り替わります。SPA マーカー、チャレンジ本文、内容の薄いページなどが対象です。ドメインごとに学習し、不要になれば学習結果を取り消します。`wigolo tune list` で学習内容を正確に確認できます。 +- **ブラウザーと同じ方法でページを読む。**段階的な取得は中間チャレンジを待ち、ドメインごとに通過情報を再利用しながら、礼儀正しく動作します。robots.txt を尊重し、ドメインごとのレート制限を設け、研究用途相当のアクセス量に抑えます。壁を越えられない場合は、その失敗を明示して報告します。 + +## 設定 + +新規インストールはそのまま動作します。次の三つの設定で出力品質を高められます。 + +```bash +# 1. Synthesis — the biggest lever (research / agent / search-answer write real prose) +export WIGOLO_LLM_PROVIDER=gemini # or anthropic / openai / groq / ollama (keyless) +export GEMINI_API_KEY= + +# 2. Wider retrieval funnel +export WIGOLO_SEARCH=hybrid # core engines + aggregator fallback +export WIGOLO_GITHUB_TOKEN=... # GitHub code search 10 → 30 req/min + +# 3. Land more fetches, stay warm +export WIGOLO_TLS_TIER=auto # per-domain learned fetch hardening +export WIGOLO_EAGER_WARMUP=1 # pay the ~1s model load up front +``` + +**呼び出しごとに効果のある習慣：**クエリの**配列**（`["a","b","c"]`）で並列に広く検索し、重要なクエリには `search_depth: "deep"` を使い、ドキュメント検索では `include_domains` を厳密なフィルターとして利用します。すべての環境変数、設定ファイルキー、検索バックエンド、キャッシュ TTL、serve の制限については[設定ガイド](docs/configuration.md)をご覧ください。 + +## ドキュメントと例 + +**[docs/](docs/README.md)** — 完全なマニュアル： +[はじめに](docs/getting-started.md) · [インストールと配布チャネル](docs/installation.md) · [設定](docs/configuration.md) · [ツールリファレンス](docs/tools.md) · [CLI と shell](docs/cli.md) · [REST API](docs/rest-api.md) · [SDK と連携](docs/sdks.md) · [セルフホスト](docs/self-hosting.md) · [エージェントスキル](docs/skills.md) · [プラグイン](docs/plugins.md) · [トラブルシューティングと FAQ](docs/troubleshooting.md) · [プライバシーとセキュリティ](docs/privacy-security.md) + +**[examples/](examples/README.md)** — 実行可能な例です。それぞれに README があり、多くにはターミナル録画も含まれます。単発 CLI、NDJSON シェルパイプライン、curl による REST、TypeScript と Python SDK、Vercel AI SDK ツール、セルフホスト型 n8n からリモート wigolo への接続、webhook による監視、独自検索エンジンプラグインの作成を扱います。ドキュメントは **[knockoutez.github.io/wigolo/docs](https://knockoutez.github.io/wigolo/docs/)** にもレンダリングされています。 + +## ベータ版とフィードバック + +wigolo は**パブリックベータ**です。ここに記載された機能はすべて動作し、7,600 件のテストスイートで維持されています。すでに安定しており、ベータが意味するのは仕上がりの水準です。十分な人数が利用し、試し、Star を付けて、v1 と呼ぶにふさわしくなるまでベータを続けます。皆さまのフィードバックが次の方向を決めます。すべての報告に目を通し、通常はその日のうちに確認します。 + +- 🐛 **[バグを報告](https://github.com/KnockOutEZ/wigolo/issues/new?template=bug_report.yml)** — 壊れた、誤動作した、予想外だった場合 +- 💡 **[機能をリクエスト](https://github.com/KnockOutEZ/wigolo/issues/new?template=feature_request.yml)** — 追加してほしい機能がある場合 +- 💬 **[何でも質問](https://github.com/KnockOutEZ/wigolo/discussions)** — 質問、セットアップ、成果紹介など + +wigolo があなたの環境で役に立ったなら、三つの方法で継続を支援できます。⭐ **Star**（オープンソースが見つかる仕組みです）、**[☕ コーヒー](https://buymeacoffee.com/knockoutez)**（有料プランはなく、今後もありません）、または全コードを書いた一人の開発者へ直接届く**[メール](mailto:ktowhid20@gmail.com)**です。 + +## トラブルシューティング + +`wigolo doctor` は壊れたコンポーネントと、それを直す正確な環境変数またはコマンドを示します。`wigolo doctor --fix` は一般的な問題を修復し、`wigolo verify` はすべてのコンポーネントをヘルスチェックします。`init` 中にコンポーネントが失敗しても wigolo 全体は壊れません。`init` は終了コード 0 のまま完了し、モデルやブラウザーがなくても中核の search、fetch、crawl、extract、cache は動作します。よくある問題： + +- **ダウンロードが遅い、または失敗する** — `wigolo warmup --all`（または `--browser`、`--embeddings`、`--reranker`）を再実行してください。続きから再開して再試行します。 +- **Linux でブラウザーが起動しない** — `wigolo warmup --browser` が OS ライブラリをインストールします（または正確なコマンドを表示します）。 +- **ネイティブビルドエラー / 特殊な Node** — LTS の **Node 20、22、24** を使ってください。 +- **プロキシ環境** — `USE_PROXY=true` と `PROXY_URL` を設定し、TLS を検査するプロキシでは `NODE_EXTRA_CA_CERTS` を追加してください。 + +完全なガイドには症状別の対処法、「X が失敗したときに何が動くか」の一覧、プラットフォーム固有の注意（linux-arm64 を含む）、オフラインインストールが記載されています。**[docs/troubleshooting.md](docs/troubleshooting.md)** をご覧ください。 + +## よくある質問 + +
+無料ですか？何か裏がありますか？ + +設計上、裏はありません。費用のかかる部分（ランキング、埋め込み、ブラウザーエンジン）は*あなたの*ハードウェア上で動くため、クエリごとの費用を回収する必要も、メーターを設ける理由もありません。寄付によって維持され、AGPL ライセンスが閉鎖的なホスト製品への転換を法的に防ぎます。 + +
+ +
+本当に有料サービスと同等の品質ですか？ + +上のベンチマークは再現可能なリアルタイムの 4 者比較です。日常的なエージェントクエリでは同等の結果に到達します。有料ツールが一部の深い抽出のエッジケースで勝ることもありますが、クロールは wigolo が最も得意とする領域です。各結果にスコアが表示されるため、作者の言葉をそのまま信じる必要はありません。 + +
+ +
+公開検索エンジンにブロックされたり、使えなくなったりしませんか？ + +まさにその状況を想定して設計されています。18 のエンジンをランキング融合するため、一つが失敗しても結果はほとんど変わりません。ドメイン別学習を備えた段階的取得と、任意のアグリゲーターフォールバックもあります。劣化したバックエンドは出力に報告され、ローカルキャッシュによって一度取得した内容は外部状況にかかわらず利用できます。 + +
+ +
+このようなスクレイピングは問題ありませんか？ + +wigolo はブラウザーと同じように公開 Web を読みます。既定で robots.txt を尊重し、ドメインごとのレート制限を設け、一台のマシン上の一つのエージェントに適した研究用途相当のアクセス量に抑えます。意図的に礼儀正しい側に位置づけています。 + +
+ +
+AGPL — 仕事で使えますか？ + +はい、社内全体で無料で利用できます。ライセンス上の義務が生じるのは、*wigolo を変更してネットワークサービスとして実行する*場合だけです。その場合は変更内容を公開する必要があります。ローカル開発ツールとして使うだけなら義務はありません。商用ライセンスについてはお問い合わせください。 + +
+ +
+なぜ 1.5 GB ものディスク容量が必要なのですか？ + +オンデバイスの頭脳に必要な容量です。完全なブラウザーエンジンと、クラウドサービスがサーバー側で動かして課金しているランキング・埋め込みモデルが含まれます。一度ディスクに保存すれば、すべてのクエリで無料で利用できます。 + +
+ +## 入手先 + +- **npm** — [`wigolo`](https://www.npmjs.com/package/wigolo)（主要チャネル — 上記のクイックスタートを参照） +- **PyPI** — [`wigolo`](https://pypi.org/project/wigolo/)（Python SDK） +- **Docker** — [`ghcr.io/knockoutez/wigolo`](https://github.com/KnockOutEZ/wigolo/pkgs/container/wigolo) · [`towhid69420/wigolo`](https://hub.docker.com/r/towhid69420/wigolo) +- **公式 MCP Registry** — `io.github.KnockOutEZ/wigolo` +- **ディレクトリ** — [Glama](https://glama.ai/mcp/servers/KnockOutEZ/wigolo) · [Smithery](https://smithery.ai/server/ktowhid20/wigolo) · [mcp.so](https://mcp.so/server/wigolo/KnockOutEZ) · [LobeHub](https://lobehub.com/mcp/knockoutez-wigolo) + +Homebrew、`curl | sh`、単一ファイルバイナリについては[インストールガイド](docs/installation.md)で説明しています。マシンごとに一つのチャネルを使用してください。すべて `~/.wigolo` を共有します。 + +## コントリビューション + +バグ報告、機能リクエスト、PR を歓迎します。**[CONTRIBUTING.md](CONTRIBUTING.md)** をご覧ください。ツールハンドラーを薄く保ち、テストを追加し、PR を開く前にテストスイートを実行してください。最も取り組みやすい入口は、カスタム検索エンジンと抽出器のためのプラグインシステムです。[約 100 行で検索エンジンを追加](docs/plugins.md)する方法と、[`examples/plugin-search-engine`](examples/plugin-search-engine) のテンプレートをご覧ください。 + +## ライセンス + +**[GNU AGPL-3.0-only](LICENSE)。**社内利用を含め、自由に使用、変更、セルフホストできます。唯一の義務は、**変更した**バージョンをネットワークサービスとして実行する場合、その変更したソースを同じライセンスで公開することです。これにより wigolo をオープンに保ち、閉鎖的なホスト型フォークを防ぎます。脆弱性の報告は **[SECURITY.md](SECURITY.md)**、名称の使用については **[TRADEMARK.md](TRADEMARK.md)** をご覧ください。商用ライセンスについてはお問い合わせください。 + +
+
+ +wigolo は無料で活発にメンテナンスされており、今後もその方針を維持します。 +従量課金の検索費用を節約できたなら、⭐、的確な Issue、または**[☕ コーヒー](https://buymeacoffee.com/knockoutez)**でプロジェクトの継続を支援できます。 + +@KnockOutEZ が開発・保守 · ktowhid20@gmail.com · X · LinkedIn + +
diff --git a/README.md b/README.md index 1b9928b77..e05d6e3bc 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ Local-first web intelligence for AI agents — **no keys, no cloud, no metered b wigolo on Trendshift KnockOutEZ%2Fwigolo | Trendshift +[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) + [Quickstart](#quickstart) · [Tools](#tools) · [Why wigolo](#why-its-different) · [Benchmark](#benchmark) · [Docs](docs/README.md) · [Examples](examples/README.md) · [Feedback](#beta--feedback) · [FAQ](#faq) New features and updates ship steadily. Follow @yourtowhid on X for all of it and new ways to use wigolo, and reach out there for collaborations or feedback · also on LinkedIn diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 000000000..56c45af90 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,419 @@ +
+ +wigolo——智能体的首选 Web 工具 + +面向 AI 智能体的本地优先 Web 智能工具——**无需密钥、无需云服务、没有按量计费账单。** + +适用于  **Claude Code · Cursor · Codex · Gemini CLI · VS Code · Windsurf · Zed · Antigravity** +
+以及更多场景  **LangChain · CrewAI · LlamaIndex · Vercel AI SDK · n8n 与自托管智能体 · 任何 MCP 客户端 · 纯 REST** + +[![npm](https://img.shields.io/npm/v/wigolo?color=cb3837&logo=npm)](https://www.npmjs.com/package/wigolo) +[![npm downloads](https://img.shields.io/npm/dm/wigolo?color=cb3837&logo=npm&label=downloads)](https://www.npmjs.com/package/wigolo) +[![GitHub stars](https://img.shields.io/github/stars/KnockOutEZ/wigolo?style=flat&logo=github&color=e3b341)](https://github.com/KnockOutEZ/wigolo/stargazers) +[![CI](https://img.shields.io/github/actions/workflow/status/KnockOutEZ/wigolo/ci.yml?branch=main&logo=github&label=CI)](https://github.com/KnockOutEZ/wigolo/actions/workflows/ci.yml) +[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)](https://nodejs.org) +[![MCP](https://img.shields.io/badge/MCP-server-7c3aed)](https://modelcontextprotocol.io) +[![license](https://img.shields.io/badge/license-AGPL--3.0-2563eb)](#许可证) +[![status](https://img.shields.io/badge/status-public%20beta-b7791f)](#beta-与反馈) +[![follow on X](https://img.shields.io/badge/follow-%40yourtowhid-000000?logo=x&logoColor=white)](https://x.com/yourtowhid) + +Trendshift 上的 wigolo +KnockOutEZ%2Fwigolo | Trendshift + +[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) + +[快速开始](#快速开始) · [工具](#工具) · [wigolo 有何不同](#有何不同) · [基准测试](#基准测试) · [文档](docs/README.md) · [示例](examples/README.md) · [反馈](#beta-与反馈) · [常见问题](#常见问题) + +新功能与更新持续发布。请在 X 上关注 @yourtowhid，了解所有动态和使用 wigolo 的新方法；也欢迎通过 X 联系合作或提供反馈，亦可在 LinkedIn 上联系。 + +
+ +--- + +wigolo 为 AI 智能体提供统一的 Web 操作界面，涵盖**搜索、获取、抓取、提取、缓存、查找相似内容、研究**以及自主收集循环。它可以在智能体运行的任何位置运行：作为 MCP 服务器与编码智能体并行运行；作为 REST/MCP 端点部署在自托管智能体所在的机器上；或通过 SDK 嵌入你自己的应用。核心工具无需 API 密钥，所处理的任何内容都不会离开 `~/.wigolo/`，也不会随着智能体思考次数增加而产生不断上涨的账单。 + +
+ +wigolo 演示——Claude Code 通过 wigolo 回答实时 Web 问题，无需 API 密钥 + +
+ +## 快速开始 + +```bash +npx wigolo init # set up the local engine — any system +npx wigolo init --agents=claude-code,cursor # …or set up + wire your day-to-day agents in one command +``` + +需要 **Node ≥ 20**，并在 macOS、Linux 或 Windows 上预留约 1.5 GB 可用磁盘空间。直接运行 `init` 会设置本地引擎：下载浏览器引擎和设备端模型、执行健康检查，并报告每个组件的状态。添加 `--agents` 后，同一次运行还会配置指定的智能体，因此日常使用的编码智能体只需一条命令即可就绪。 + +- **支持的智能体**——`--agents` 接受 `claude-code`、`cursor`、`codex`、`gemini-cli`、`vscode`、`windsurf`、`zed`、`antigravity` 中的任意项（以逗号分隔）；wigolo 会为每个智能体写入 MCP 配置和说明。 +- **其他设置方式**——任何 MCP 客户端、智能体框架或自托管智能体都可以在自己的 MCP 配置中注册 `npx -y wigolo`。[安装指南](docs/installation.md)提供每种客户端的准确配置块，以及 Docker、Homebrew 和单文件二进制安装渠道。 +- **更多支持即将推出**——支持列表会持续扩展，也欢迎提交 PR 来添加你的智能体；请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 +- **交互式设置**——`--interactive` 提供纯文本流程；`--wizard` 提供完整的终端 TUI。 +- **延后下载**——`--no-warmup` 会等到首次使用时再下载。组件下载失败不会导致设置失败；init 会报告尚未就绪的内容及准确修复方法，同时仍会完成设置。 + +`init` 默认无需人工干预，因此可安全用于脚本和 CI。任何设置问题都会在这里的逐组件报告中呈现，早于智能体的第一次调用。**搜索、获取、抓取、提取、缓存和查找相似内容均无需 API 密钥。**你可以随时运行以下命令检查健康状态： + +```bash +npx wigolo doctor +``` + +要彻底移除所有内容，请运行 `npx wigolo config --uninstall --yes`。你也可以把[安装指南](docs/installation.md)粘贴到任意 AI 助手中，让它代为完成设置；该指南内容完备，可独立使用。 + +### 推荐——为 `research` 与 `agent` 获取免费密钥 + +搜索、获取、抓取、提取、缓存和查找相似内容**完全无需密钥**。`research`、`agent` 和 `search format=answer` 会使用 LLM 撰写综合且带引用的答案。没有 LLM 时，它们会返回原始简报和证据，交由你的智能体整理。免费的 Gemini 密钥可以将其转化为完整答案： + +```bash +export WIGOLO_LLM_PROVIDER=gemini +export GEMINI_API_KEY= # grab one at aistudio.google.com/apikey — the free tier is plenty +``` + +任何提供商均可使用（`anthropic`、`openai`、`groq`），你也可以将 `WIGOLO_LLM_PROVIDER=ollama`（或任意兼容 OpenAI 的 URL）设为完全本地且无需密钥的方案。可在 shell 或智能体 MCP 的 `env` 块中设置。提供商、模型和无密钥本地模型降级链详见[配置指南](docs/configuration.md)。 + +## 智能体会获得什么 + +每条搜索结果都是智能体可据此行动的证据。它包含固定到来源准确位置的逐字摘录、可供智能体引用的引用 ID，以及可供检查的评分（以下为经过精简的真实结构）： + +```jsonc +{ + "results": [{ + "title": "Logical replication - PostgreSQL docs", + "url": "https://www.postgresql.org/docs/current/logical-replication.html", + "excerpt": "Logical replication is a method of replicating data objects…", + "citation_id": "src-1", + "source_span": { "start": 1042, "end": 1305 }, // byte-exact provenance + "evidence_score": { "final": 0.86, "semantic": 0.91, "lexical": 0.78, "engine_consensus": 3 } + }], + "citations": [{ "id": "src-1", "url": "…" }], + "freshness_signal": { "published": "2026-05-12", "confidence": "high" } +} +``` + +wigolo 自身的评分器会将质量较差的结果标记为垃圾结果。失败的引擎会被报告，过期缓存也会被标注，因此智能体始终清楚其依据。每个工具的完整响应契约位于[工具参考](docs/tools.md)中。 + +## 工具 + +| 工具 | 功能 | +|------|--------------| +| 🔎 `search` | 多引擎 Web 搜索（18 个直接适配器），支持排名融合、ML 重排和可解释的逐结果评分。传入查询**数组**即可并行扩展搜索范围。可按域名和时间范围限定、匹配精确短语或返回图片结果。 | +| 📄 `fetch` | 通过分层路由器加载单个 URL；遇到反机器人挑战或 SPA 外壳时，会从普通 HTTP 自动升级到无头浏览器引擎。返回干净的 Markdown、元数据和链接。支持 PDF、单个标题 `section`、已认证会话，以及页面操作（点击、输入、滚动、截图）。 | +| 🕸️ `crawl` | 多页面抓取，可使用 BFS、DFS、站点地图或仅映射模式。支持按域名限速、遵守 robots.txt 及样板内容去重。 | +| 🧩 `extract` | 从页面提取结构化数据：表格、元数据、JSON-LD、品牌标识、命名 schema（Article、Recipe、Product 等），或任意自定义 JSON Schema。 | +| 💾 `cache` | 查询已访问的所有内容，可使用关键词或混合语义检索，并提供统计、清除和变更检测功能。 | +| 🧲 `find_similar` | 通过关键词、语义和实时 Web 三路融合，查找与某个 URL 或概念相似的页面。 | +| 🧠 `research` | 分解问题 → 并行发出子查询 → 获取来源 → 综合为带引用的报告（或由宿主 LLM 撰写的结构化简报）。 | +| 🤖 `agent` | 自主收集循环：规划 → 搜索 → 获取 → 提取 → 综合，并包含步骤日志、时间预算和可选输出 schema。 | +| 🔁 `diff` + ⏱️ `watch` | 查看页面自上次访问以来的准确变化；按需重新检查，并将变化发送到 webhook。 | + +每个工具也都可以从终端运行（`wigolo search "…" --json`）、通过支持 NDJSON 管道的交互式 shell（`wigolo shell`）运行、通过 REST 调用，或通过 SDK 使用——请参阅 [CLI 参考](docs/cli.md)。每个工具的指南和完整参数集位于 [docs/tools.md](docs/tools.md)，可运行示例位于 [examples/](examples/README.md)。 + +## 有何不同 + +wigolo 并非付费工具的廉价替代品——它的目标就是达到同等水准。它是面向智能体的专用 Web 层：智能体可以直接调用其 MCP 和 REST 接口，获得付费服务才会提供的搜索与提取质量。它的不同之处在于： + +- **专为智能体构建。**一次 MCP 调用即可跨多个引擎并行展开多个查询，这是串行宿主工具循环无法复制的。每条结果都带有透明的逐结果评分，且输出会顾及上下文预算。 +- **输出诚实透明。**过期缓存、获取失败、后端降级和截断都会在结果中明确呈现。无法读取受机器人保护的页面时，你会得到标记为 `blocked_by_challenge` 的失败，而不是挑战页面外壳冒充的内容。 +- **每次查询成本为 0 美元，可自由重新查询。**默认搜索通过直接适配器访问公共引擎；重排器和嵌入模型在设备端运行。每个响应都会缓存，因此再次询问可即时获得结果且不产生费用。 +- **默认保护隐私。**缓存、嵌入、模型和配置均位于 `~/.wigolo/`。除非你明确选择使用 LLM 进行综合，否则任何内容都不会发送给第三方。 + +下面对一条真实结果进行拆解。失败的引擎和质量较差的结果也会展示，因为它们同样是答案的一部分： + +
+ + + +wigolo 结果剖析：可解释的评分分解、实时引擎遥测、明确呈现的降级、自行标记的垃圾结果——来自一次真实查询 + + +
+ +## 基准测试 + +> **四种工具得出了相同的核心答案，而其中只有一种返回了逐字且精确定位到字节的证据。** + +一次冷启动查询在同一个 **Claude Fable 5** 会话中实时运行，并以同等条件并行交给四种 Web 工具（内置 **WebSearch**、**wigolo**、**Tavily**、**Exa**），随后由智能体仅根据证据进行评判。四者得出了相同的答案和同一个首要来源，因此屏幕上的结果证明了它们达到了同等水平。只有 wigolo 返回了固定到字节偏移来源范围的逐字摘录、可解释的评分分解和实时逐引擎遥测，其自身评分器还将两个较差结果标记为垃圾结果。云端工具也各有优势：Exa 完整渲染了官方文档的对比矩阵。你可以运行自己的查询，并看到相同的结果结构。 + +
+ +在一次真实查询中比较 wigolo、内置 WebSearch、Tavily 和 Exa，由 Claude Fable 5 驱动 + +
+ +### 对比情况 + +| | wigolo | Firecrawl | Exa | Tavily | +|---|:---:|:---:|:---:|:---:| +| 多引擎 Web 搜索 | ✅ | ✅ | ✅ | ✅ | +| 获取与结构化提取 | ✅ | ✅ | ✅ | ✅ | +| 整站抓取与映射 | ✅ | ✅ | — | ✅ | +| 固定到字节偏移来源范围的逐字摘录 | ✅ | — | — | — | +| 可解释的逐结果评分分解 | ✅ | — | — | — | +| 持久化本地记忆——即时、离线重新查询 | ✅ | — | — | — | +| 查询数据留在本机 | ✅ | — | — | — | +| API 密钥/账户 | 无需 | 必需 | 必需 | 必需 | +| 每次查询成本 | 0 美元 | 按量计费 | 按量计费 | 按量计费 | + +功能状态截至 2026 年 7 月——请查阅各供应商文档了解当前状态。 + +最后一行的影响会不断累积，因为智能体往往会突发式地提出大量查询： + +
+ + + +计量表：按量计费的云 API 成本随每次查询上升，而 wigolo 始终保持零美元——示意价格 + + +
+ +## 编辑器之外 + +无论智能体属于哪种类型，都可以通过合适的接口使用相同的十种工具：编码智能体使用 MCP，其他场景使用 REST，需要嵌入时使用 SDK，还可直接接入框架包装器。 + +### REST API——`wigolo serve` + +一个进程即可在 MCP 传输旁提供纯 JSON REST API。无需 MCP 客户端，只需 curl： + +```bash +wigolo serve # 127.0.0.1:3333 — loopback is open; off-loopback requires a token + +curl -sX POST http://127.0.0.1:3333/v1/search \ + -H 'Content-Type: application/json' \ + -d '{"query":"local-first software","max_results":5}' +``` + +`POST /v1/{tool}` 覆盖全部十种工具，`GET /openapi.json` 提供 OpenAPI 3.1 契约，`/mcp` 和 `/sse` 则通过同一端口为远程 MCP 客户端提供服务。绑定到回环地址之外时必须提供 bearer token，因此服务器默认采用失败关闭策略。可让 n8n、Hermes 风格助手或任何自托管智能体指向该端点。→ [REST API](docs/rest-api.md) + +### SDK——TypeScript 与 Python + +轻量、带类型的客户端，提供嵌入式本地模式，可以自动发现或启动守护进程，无需单独执行 `serve`。 + +**TypeScript**——`npm install wigolo-sdk`（零依赖；支持 Node、Bun、Deno 和 edge）： + +```ts +import { createLocalClient } from 'wigolo-sdk/local'; + +const { client, close } = await createLocalClient(); // reuse a running daemon, or spawn one +const res = await client.search({ query: 'local-first web search', max_results: 5 }); +console.log(res.results.map((r) => r.title)); +await close(); // stops the daemon only if this call spawned it +``` + +**Python**——`pip install wigolo`（仅使用标准库；支持同步与异步）： + +```python +from wigolo import local_client + +with local_client() as client: # reuse a healthy daemon, or spawn one + res = client.search(query="local-first web search", max_results=5) + for r in res["results"]: + print(r["title"], r["url"]) +``` + +→ [SDK 与嵌入式模式](docs/sdks.md) + +### 框架集成 + +将 wigolo 的工具直接接入你已经使用的框架。你会获得完整的十种工具，包括多数框架 Web 工具并不提供的 cache、find_similar、research 和 agent： + +| 框架 | 软件包 | 可获得的功能 | +|-----------|---------|--------------| +| **LangChain** | `wigolo-langchain` | 每个工具都作为 `BaseTool` 提供，另有一个基于 search/find_similar、用于 RAG 的 `BaseRetriever` | +| **CrewAI** | `wigolo-crewai` | `wigolo_tools()` → 将整套工具交给任意 crew | +| **LlamaIndex** | `wigolo-llamaindex` | 一个 `BaseReader`，可将已获取、抓取或搜索到的页面作为文档加载 | +| **Vercel AI SDK** | `wigolo-vercel-ai-sdk` | 用于 `generateText`/`streamText` 的工具工厂，兼容 edge | + +→ [框架集成](docs/sdks.md) + +### Docker + +```bash +# stdio MCP — wire it into any MCP client as command: docker +docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo + +# HTTP server for remote / multi-client use +docker run -p 3333:3333 -v wigolo-data:/data \ + -e WIGOLO_API_TOKEN=a-long-random-secret \ + ghcr.io/knockoutez/wigolo serve --host 0.0.0.0 +``` + +精简镜像会将模型延迟加载到卷中；`:full` 会预装浏览器引擎。Docker Hub 上也提供 `towhid69420/wigolo`。→ [安装与所有渠道](docs/installation.md) + +### 智能体技能 + +一套包含 11 项内容的技能目录会教编码智能体如何妥善使用每种工具。它由 `init` 安装，并通过 `wigolo skills add|list|remove` 管理。→ [技能](docs/skills.md) + +自托管用户请注意：一些受挑战保护的网站会评估 IP 信誉，因此数据中心 IP 可能无法通过家庭网络可以通过的防护墙。wigolo 会标记这些失败，[自托管指南](docs/self-hosting.md)介绍了可选择启用的代理解决方案。 + +## Star 历史 + +
+ + + + +wigolo 的 GitHub Star 历史 + + + +每天通过 GitHub API 刷新。如果 wigolo 对你有用，请点一个 ⭐。 + +
+ +## 架构 + +单个 Node 进程通过 stdio 使用 MCP（JSON-RPC）。所有重型组件都在本地按需加载，因此无密钥安装不会为未使用的部分付出代价。 + +```mermaid +flowchart TD + A["🤖 AI agent
any MCP client · REST · SDK"] + A -->|MCP over stdio| B["wigolo
10 tools · dynamic instructions
in-process browser pool + cache + models"] + + B --> C{"Tool layer"} + C --> T1["search · fetch · crawl · extract"] + C --> T2["cache · find_similar · research · agent"] + + T1 --> F["⚙️ Fetch router
tiered escalation, learned per domain"] + T1 --> S["⚙️ Search
18 engines → rank fusion → ML rerank
explainable evidence score"] + T2 --> DB[("🗄️ Local cache
keyword + vector index")] + T2 --> ML["🧠 On-device ML
embeddings + reranker"] + + F -.->|optional| LLM["☁️ LLM
synthesis only · opt-in"] + S -.->|optional| SX["🔀 Aggregator backend
opt-in legacy / hybrid"] + + F --> WEB["🌍 Public web"] + S --> WEB + + style B fill:#7c3aed,stroke:#5b21b6,color:#fff + style WEB fill:#0ea5e9,stroke:#0369a1,color:#fff + style DB fill:#1e293b,stroke:#334155,color:#fff + style LLM stroke-dasharray: 5 5 + style SX stroke-dasharray: 5 5 +``` + +- **能用代码完成的工作不交给模型。**确定性任务由代码处理，包括规范化、排名融合、去重和 schema 匹配。模型仅用于判断，需主动选择启用，并限制每次请求的用量。LLM 填充的字段会与来源核对，不存在时则设为 null。 +- **信号驱动的路由。**获取阶梯根据可观察信号而非域名猜测来升级到真实浏览器，包括 SPA 标记、挑战响应体和内容过少。它会针对每个域名学习；网站不再需要时也会取消学习。`wigolo tune list` 会准确显示它学到了什么。 +- **像浏览器一样读取页面。**分层获取会等待中间挑战结束，并按域名复用放行凭据，同时保持礼貌：遵守 robots.txt、按域名限速，使用研究级访问量。如果仍然无法通过防护墙，失败会被标记并报告。 + +## 配置 + +全新安装开箱即用。以下三项设置可以提高输出质量： + +```bash +# 1. Synthesis — the biggest lever (research / agent / search-answer write real prose) +export WIGOLO_LLM_PROVIDER=gemini # or anthropic / openai / groq / ollama (keyless) +export GEMINI_API_KEY= + +# 2. Wider retrieval funnel +export WIGOLO_SEARCH=hybrid # core engines + aggregator fallback +export WIGOLO_GITHUB_TOKEN=... # GitHub code search 10 → 30 req/min + +# 3. Land more fetches, stay warm +export WIGOLO_TLS_TIER=auto # per-domain learned fetch hardening +export WIGOLO_EAGER_WARMUP=1 # pay the ~1s model load up front +``` + +**值得采用的逐调用习惯：**使用查询**数组**（`["a","b","c"]`）并行扩展范围；对重要查询使用 `search_depth: "deep"`；使用 `include_domains` 作为文档查找的硬性过滤条件。完整参考涵盖所有环境变量、配置文件键、搜索后端、缓存 TTL 和 serve 限制，详见[配置指南](docs/configuration.md)。 + +## 文档与示例 + +**[docs/](docs/README.md)**——完整手册： +[入门](docs/getting-started.md) · [安装与渠道](docs/installation.md) · [配置](docs/configuration.md) · [工具参考](docs/tools.md) · [CLI 与 shell](docs/cli.md) · [REST API](docs/rest-api.md) · [SDK 与集成](docs/sdks.md) · [自托管](docs/self-hosting.md) · [智能体技能](docs/skills.md) · [插件](docs/plugins.md) · [故障排除与常见问题](docs/troubleshooting.md) · [隐私与安全](docs/privacy-security.md) + +**[examples/](examples/README.md)**——可运行示例，每个示例都有 README（大多数还包含终端录制）：一次性 CLI、NDJSON shell 管道、通过 curl 使用 REST、TypeScript 与 Python SDK、Vercel AI SDK 工具、让自托管 n8n 指向远程 wigolo、使用 webhook 监视，以及编写自己的搜索引擎插件。文档也会渲染到网站 **[knockoutez.github.io/wigolo/docs](https://knockoutez.github.io/wigolo/docs/)**。 + +## Beta 与反馈 + +wigolo 目前处于**公开 Beta** 阶段。这里记录的所有功能都可正常工作，并由 7,600 项测试套件保障；它已经稳定，Beta 阶段关注的是打磨程度。只有当足够多的人使用、检验并为它加星，使“v1”名副其实之后，它才会结束 Beta。你的反馈会影响下一步发展，每一份报告都会被阅读，通常就在当天： + +- 🐛 **[报告错误](https://github.com/KnockOutEZ/wigolo/issues/new?template=bug_report.yml)**——出现故障、行为异常或结果出乎意料 +- 💡 **[请求功能](https://github.com/KnockOutEZ/wigolo/issues/new?template=feature_request.yml)**——你认为它应该实现的功能 +- 💬 **[提出任何问题](https://github.com/KnockOutEZ/wigolo/discussions)**——问题、设置、成果展示与交流 + +如果 wigolo 在你的工作流中有一席之地，有三种方式可以帮助它持续发展：点一个 ⭐ **Star**（开源软件正是这样被发现的）、请作者喝一杯**[☕ 咖啡](https://buymeacoffee.com/knockoutez)**（这里没有付费层，以后也不会有），或者发一封**[电子邮件](mailto:ktowhid20@gmail.com)**，直接联系编写全部代码的唯一开发者。 + +## 故障排除 + +`wigolo doctor` 会指出发生故障的组件，以及可修复问题的准确环境变量或命令；`wigolo doctor --fix` 会修复常见问题，`wigolo verify` 则对每个组件进行健康检查。组件在 `init` 期间失败不会破坏 wigolo：`init` 仍会以状态码 0 退出，且核心 search、fetch、crawl、extract 和 cache 在没有模型与浏览器时仍可工作。常见问题速查： + +- **下载缓慢或失败**——重新运行 `wigolo warmup --all`（或 `--browser`、`--embeddings`、`--reranker`）；下载会继续并重试。 +- **浏览器无法在 Linux 上启动**——`wigolo warmup --browser` 会安装操作系统库（或输出准确命令）。 +- **原生构建错误/不常见的 Node 版本**——使用 LTS 版本：**Node 20、22 或 24**。 +- **位于代理之后**——设置 `USE_PROXY=true` 和 `PROXY_URL`；若代理会检查 TLS，请添加 `NODE_EXTRA_CA_CERTS`。 + +完整指南按具体症状提供解决方案，还包含“当 X 失败时哪些功能仍可工作”的映射、平台说明（包括 linux-arm64）和离线安装方法：**[docs/troubleshooting.md](docs/troubleshooting.md)**。 + +## 常见问题 + +
+免费吗？有什么隐藏条件？ + +从设计上就没有隐藏条件。昂贵的部分（排名、嵌入和浏览器引擎）都在*你的*硬件上运行，因此无需回收逐次查询成本，也就没有设置计量器的理由。项目依靠捐赠维持，而 AGPL 许可证从法律上防止它转变为闭源托管产品。 + +
+ +
+质量真的能与付费服务相当吗？ + +上面的基准测试是可复现的实时四方比较：在日常智能体查询中，结果达到了同等水准；付费工具在一些深度提取的边缘案例中仍然更胜一筹，而抓取是 wigolo 最强的领域。每条结果都会展示评分，因此你无需仅凭作者的一面之词。 + +
+ +
+公共搜索引擎不会封锁请求或逐渐失效吗？ + +它正是为应对这种情况而设计的：18 个引擎通过排名融合组合（任意一个失败都几乎不会影响结果）、带逐域名学习功能的分层获取阶梯，以及可选的聚合器回退。降级的后端会在输出中报告，而本地缓存意味着已访问的所有内容始终可用，不受外部情况影响。 + +
+ +
+这种抓取方式合规吗？ + +wigolo 像浏览器一样读取公共 Web：默认遵守 robots.txt、按域名限速，并采用适合单个智能体的研究级访问量。它刻意选择了礼貌访问的一端。 + +
+ +
+AGPL——可以在工作中使用吗？ + +可以，整个公司都能免费使用。只有当你*修改 wigolo 并将其作为网络服务运行*时，许可证才会产生义务；此时必须公开这些修改。将它用作本地开发工具不会带来任何义务。如有商业许可问题，请联系作者。 + +
+ +
+为什么需要 1.5 GB 磁盘空间？ + +这是设备端“大脑”所需的空间：完整浏览器引擎，以及云服务在服务器端运行并向你收费的排名和嵌入模型。下载到磁盘后，每次查询都可以免费使用它们。 + +
+ +## 获取渠道 + +- **npm**——[`wigolo`](https://www.npmjs.com/package/wigolo)（主要渠道——见上面的快速开始） +- **PyPI**——[`wigolo`](https://pypi.org/project/wigolo/)（Python SDK） +- **Docker**——[`ghcr.io/knockoutez/wigolo`](https://github.com/KnockOutEZ/wigolo/pkgs/container/wigolo) · [`towhid69420/wigolo`](https://hub.docker.com/r/towhid69420/wigolo) +- **官方 MCP Registry**——`io.github.KnockOutEZ/wigolo` +- **目录**——[Glama](https://glama.ai/mcp/servers/KnockOutEZ/wigolo) · [Smithery](https://smithery.ai/server/ktowhid20/wigolo) · [mcp.so](https://mcp.so/server/wigolo/KnockOutEZ) · [LobeHub](https://lobehub.com/mcp/knockoutez-wigolo) + +Homebrew、`curl | sh` 和单文件二进制的使用方式见[安装指南](docs/installation.md)。每台机器只使用一个安装渠道；它们都共享 `~/.wigolo`。 + +## 参与贡献 + +欢迎提交错误报告、功能请求和 PR；请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)**。让工具处理程序保持精简、添加测试，并在创建 PR 前运行测试套件。最容易上手的是自定义搜索引擎和提取器的插件系统：请参阅[用约 100 行代码添加搜索引擎](docs/plugins.md)，模板位于 [`examples/plugin-search-engine`](examples/plugin-search-engine)。 + +## 许可证 + +**[GNU AGPL-3.0-only](LICENSE)。**可自由使用、修改和自托管，包括在公司内部使用。唯一的义务是：如果将**修改后的**版本作为网络服务运行，就必须以相同许可证发布修改后的源代码。这能让 wigolo 保持开放，同时防止出现闭源托管分支。安全漏洞请按照 **[SECURITY.md](SECURITY.md)** 报告，名称使用方式请参阅 **[TRADEMARK.md](TRADEMARK.md)**。如有商业许可问题，请联系作者。 + +
+
+ +wigolo 免费且积极维护，并且会一直如此。 +如果它帮你省下了按量计费的搜索账单，点一个 ⭐、提交一份精准的 Issue，或请作者喝一杯**[☕ 咖啡](https://buymeacoffee.com/knockoutez)**，都能帮助项目持续发展。 + +由 @KnockOutEZ 构建和维护 · ktowhid20@gmail.com · X · LinkedIn + +