From dd25f9110454085bdb2e3760e139a73cc566ab2f Mon Sep 17 00:00:00 2001 From: opencode Date: Sun, 13 Sep 2026 04:35:58 -0400 Subject: [PATCH] docs: rewrite README to v2 quality bar, J1 branding, real screenshot Co-Authored-By: opencode --- README.md | 174 ++++------------- browser-search/README.md | 286 ---------------------------- browser-search/i18n/README.ar.md | 227 ---------------------- browser-search/i18n/README.de.md | 227 ---------------------- browser-search/i18n/README.es.md | 227 ---------------------- browser-search/i18n/README.fr.md | 227 ---------------------- browser-search/i18n/README.it.md | 227 ---------------------- browser-search/i18n/README.ja.md | 227 ---------------------- browser-search/i18n/README.ko.md | 227 ---------------------- browser-search/i18n/README.pt-BR.md | 227 ---------------------- browser-search/i18n/README.ru.md | 227 ---------------------- browser-search/i18n/README.zh-CN.md | 227 ---------------------- noc-dashboard/README.md | 60 ------ 13 files changed, 35 insertions(+), 2755 deletions(-) delete mode 100644 browser-search/README.md delete mode 100644 browser-search/i18n/README.ar.md delete mode 100644 browser-search/i18n/README.de.md delete mode 100644 browser-search/i18n/README.es.md delete mode 100644 browser-search/i18n/README.fr.md delete mode 100644 browser-search/i18n/README.it.md delete mode 100644 browser-search/i18n/README.ja.md delete mode 100644 browser-search/i18n/README.ko.md delete mode 100644 browser-search/i18n/README.pt-BR.md delete mode 100644 browser-search/i18n/README.ru.md delete mode 100644 browser-search/i18n/README.zh-CN.md delete mode 100644 noc-dashboard/README.md diff --git a/README.md b/README.md index da1115c..fec9e84 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,17 @@ -
- -![StackForge banner](docs/assets/banner.svg) - # StackForge -**CPU-only, privacy-focused Docker Compose stack for AI agents** — local LLM, vector search, long-term memory, and synced notes, all self-hosted. +> CPU-only, privacy-focused Docker Compose stack that gives AI agents local LLMs, vector search, long-term memory, private search, and a synced notes vault on hardware you control. + +[![License](https://img.shields.io/github/license/OneByJorah/StackForge?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/StackForge) +[![Top Language](https://img.shields.io/github/languages/top/OneByJorah/StackForge?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/StackForge) +[![Stars](https://img.shields.io/github/stars/OneByJorah/StackForge?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/StackForge/stargazers) +[![Last Commit](https://img.shields.io/github/last-commit/OneByJorah/StackForge?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/StackForge/commits) -Stars -Last commit -License -Docker Compose -CPU only -Ollama +![StackForge landing page](docs/screenshots/landing-hero.png) -![StackForge screenshot](docs/assets/screenshot.png) +## What This Is -
+StackForge bundles the pieces an AI agent needs to run privately on your own hardware — a local LLM, a vector database, persistent memory, private web search, a synced Obsidian vault, and browser automation — into one compose file. It targets CPU-only boxes: a VPS, homelab server, or bare-metal machine. Built for people who want agent infrastructure without renting a vendor's cloud. ## Quick Start @@ -26,145 +22,45 @@ cp .env.example .env docker compose up -d ``` -For an interactive first-run wizard that generates secrets and sets your IP, run `bash bootstrap.sh` instead. Open **http://localhost:8083** for the vault viewer. - -## What This Is - -StackForge bundles the pieces an AI agent needs to run privately on your own hardware: a local LLM, a vector database, persistent memory, private search, a synced notes vault, and browser automation. It targets CPU-only boxes — a VPS, homelab server, or bare-metal machine — and keeps all agent context on infrastructure you control instead of a vendor's. +For a guided first run that generates secrets and sets your IP, use `bash bootstrap.sh`. Open `http://localhost:8083` for the vault viewer. ## Features -- **One-command deploy** — `docker compose up -d` (or `bootstrap.sh` for a guided setup) brings the stack online. -- **Interactive first run** — `bootstrap.sh` prompts for secrets, generates random passwords, and seeds the vault. -- **CPU-only** — no GPU required; GPU acceleration can be enabled by uncommenting the Ollama deploy block. -- **Local LLMs** — Ollama serves Llama 3, Mistral, Phi, and more, with Honcho embeddings via `nomic-embed-text`. -- **Agent memory** — Honcho (pgvector Postgres + Redis) provides long-term agent memory. -- **Private search** — SearXNG aggregates web search without tracking. -- **Obsidian sync** — CouchDB LiveSync plus Syncthing for laptop ↔ server vault sync. -- **Web automation** — Selenium standalone Chrome for browser tasks. - -## Services - -| Service | Port | Purpose | Image | -|---------|------|---------|-------| -| **Ollama** | `11434` | Local LLM hosting | `ollama/ollama` | -| **Qdrant** | `6333` | Vector database for embeddings | `qdrant/qdrant` | -| **Honcho API** | `8000` | Long-term agent memory | `ghcr.io/plastic-labs/honcho` | -| **SearXNG** | `8080` | Privacy-respecting metasearch | `searxng/searxng` | -| **PostgreSQL** | `5432` | Honcho backend (pgvector) | `pgvector/pgvector:pg15` | -| **Redis** | `6379` | Cache / queues | `redis:8.2` | -| **CouchDB** | `5984` | Obsidian LiveSync document store | `couchdb:3.4` | -| **Obsidian** | `8083` | Web vault viewer (Caddy) | `caddy:2-alpine` | -| **Syncthing** | `8384` | P2P file sync (laptop ↔ server) | `syncthing/syncthing` | -| **Selenium** | `4444` | Browser automation (Chrome) | `selenium/standalone-chrome` | +- One-command deploy of ten services via Docker Compose, with an interactive `bootstrap.sh` wizard +- Ollama serving local LLMs (Llama, Mistral, Phi, and more) on CPU; GPU off-load is a one-line change +- Honcho long-term agent memory backed by PostgreSQL + pgvector and Redis +- SearXNG metasearch for private, tracking-free web queries +- Obsidian vault sync via CouchDB LiveSync plus Syncthing for laptop-to-server replication +- Standalone Selenium Chrome container for browser automation tasks +- Optional overlays for Headroom monitoring and Portainer container management ## Architecture +Two Docker networks isolate traffic: a `tailnet` bridge for exposed services and an internal `backend` network for the database and cache. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#0a0a09','primaryTextColor':'#FFB300','lineColor':'#FFB300'}}}%% +graph LR + A[AI Agent] --> B[Ollama :11434] + A --> C[Qdrant :6333] + A --> D[Honcho :8000] + D --> E[(PostgreSQL + pgvector)] + D --> F[(Redis)] + A --> G[SearXNG :8080] + A --> H[Obsidian Vault :8083] + A --> I[Selenium Chrome :4444] + H --> J[(CouchDB LiveSync)] + I[Web UI] --> K[Caddy] ``` - ┌─────────────┐ - │ AI Agent │ - └──────┬──────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ┌─────┴─────┐ ┌────┴────┐ ┌──────┴──────┐ - │ Ollama │ │ Qdrant │ │ Honcho │ - │ :11434 │ │ :6333 │ │ :8000 │ - │ LLM Host │ │ Vector │ │ Memory │ - └───────────┘ │ DB │ └──────┬──────┘ - └─────────┘ │ - ┌──────┴──────┐ - │ PostgreSQL │ Redis - │ :5432 │ :6379 - └─────────────┘ - - ┌──────────┐ ┌──────────┐ ┌─────────────┐ - │ SearXNG │ │ Obsidian │ │ Selenium │ - │ :8080 │ │ :8083 │ │ :4444 │ - │ Search │ │ Vault │ │ Automation │ - └──────────┘ └──────────┘ └─────────────┘ -``` - -Two Docker networks are used: a `tailnet` bridge for exposed services and an internal `backend` network for the database and cache. Optional `docker-compose.headroom.yml` and `docker-compose.portainer.yml` overlays add monitoring and container management. - -## Configuration - -Copy `.env.example` to `.env` and set real values. Key variables: - -| Variable | Default | Description | -|----------|---------|-------------| -| `SERVER_IP` | *(required)* | Host IP used in service URLs (Tailscale IP recommended) | -| `HONCHO_DB_PASSWORD` | `changeme` | PostgreSQL password (Honcho backend) — **change it** | -| `HONCHO_TOKEN` | *(required)* | Honcho API auth token | -| `SVC_HONCHO_PORT` | `8000` | Honcho API port | -| `SVC_SEARXNG_PORT` | `8080` | SearXNG port | -| `SVC_QDRANT_PORT` | `6333` | Qdrant API port | -| `SVC_COUCHDB_PORT` | `5984` | CouchDB / LiveSync port | -| `SVC_SYNCTHING_UI_PORT` | `8384` | Syncthing web UI port | -| `COUCHDB_ADMIN_USER` | `admin` | CouchDB admin username | -| `COUCHDB_ADMIN_PASSWORD` | `changeme` | CouchDB admin password — **change it** | -| `OBSIDIAN_VAULT_PATH` | `/path/to/your/obsidian/vault` | Host path for the vault | -| `OLLAMA_HOST` | `http://ollama:11434` | Ollama endpoint used by Honcho | -Honcho's LLM provider is configured separately in `.env.honcho.example` (OpenRouter/OpenAI-compatible). Headroom settings live in `.env.headroom.example`. +## Stack -> [!WARNING] -> `bootstrap.sh` writes generated credentials to `obsidian/vault/credentials.md`. Delete that file after recording them, or keep the deployment behind Tailscale only. - -## Use Cases - -1. **Homelabbers** — run a private AI brain on a CPU-only server. -2. **AI developers** — build and test agents against local inference and memory. -3. **Privacy-conscious teams** — keep search, notes, and memory off third-party clouds. -4. **Field / edge deployments** — sync a vault from a laptop to a server with Syncthing. - -## Tech Stack - -Docker Compose, Ollama, Qdrant, Honcho, SearXNG, PostgreSQL + pgvector, Redis, CouchDB, Caddy, Syncthing, Selenium, Jinja2-based config templates. - -## Screenshots - -| View | Preview | -|------|---------| -| Landing hero | ![StackForge landing hero](docs/screenshots/landing-hero.png) | -| Full landing | ![StackForge landing page](docs/screenshots/landing-full.png) | -| Main viewport | ![StackForge main view](docs/screenshots/main.viewport.png) | -| SearXNG | ![StackForge SearXNG](docs/screenshots/searxng.png) | -| Vault viewer | ![StackForge vault viewer](docs/screenshots/vault-viewer.png) | - -## Project Structure - -``` -StackForge/ -├── docker-compose.yml # Main compose file (all services) -├── docker-compose.headroom.yml # Headroom monitoring add-on -├── docker-compose.portainer.yml # Portainer container management -├── .env.example # Environment variable template -├── bootstrap.sh # Interactive first-run setup wizard -├── index.html # Landing page -├── docs/ # Setup guides + assets -├── scripts/ # healthcheck, init, install helpers -├── searxng/ # SearXNG configuration -├── honcho/ # Honcho config -├── headroom/ # Headroom config -├── obsidian/ # Vault + Caddyfile -├── obsidian-skills/ # Obsidian plugin skills -├── noc-dashboard/ # NOC monitoring dashboard -├── browser-search/ # Browser search utilities -├── vendor/ # Submodules (honcho, headroom) -└── tests/ # Integration tests -``` +Docker Compose, Ollama, Qdrant, Honcho, SearXNG, PostgreSQL + pgvector, Redis, CouchDB, Caddy, Syncthing, Selenium, Jinja2 config templates ## Contributing -Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), then [open an issue](https://github.com/OneByJorah/StackForge/issues) or a pull request. +Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md) and [open an issue](https://github.com/OneByJorah/StackForge/issues) to report a bug or request a feature. ## License MIT — see [LICENSE](LICENSE). - -## Connect - -- [jorahone.com](https://jorahone.com) -- [GitHub Org](https://github.com/OneByJorah) -- [info@jorahone.com](mailto:info@jorahone.com) diff --git a/browser-search/README.md b/browser-search/README.md deleted file mode 100644 index 8dc90f8..0000000 --- a/browser-search/README.md +++ /dev/null @@ -1,286 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **A skill for AI agents.** OpenCode, Claude Code, Cursor, OpenClaw and -> beyond. Search the web with SearXNG, browse with Camofox, bypass -> protections with CloakBrowser. All self-hosted, free, unlimited. - -

English · 简体中文 · Español · 日本語 · 한국어 · Português (Brasil) · Français · Deutsch · Русский · العربية · Italiano

- -## Why it exists - -browser-search is a SKILL — an instruction set for AI agents like OpenCode, -Claude Code, Cursor, OpenClaw and others. It teaches your agent how to -search and browse the web using three orchestrated open source tools. - -The problem? The web is hostile to automation. Cloudflare, Akamai, DataDome -and other anti-bot systems block simple requests. Modern sites use heavy -JavaScript, lazy loading, and client-side rendering. One single solution -is not enough. - -`browser-search` orchestrates **three open source tools** into a single -search and browsing system designed for AI agents. Each tool has its role, -orchestrated by the skill with escalation logic, automatic selection, -and ready-to-use integration: - -1. **[SearXNG](https://github.com/searxng/searxng)** — metasearch engine for the search phase (multi-source, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — browser navigable via REST API for standard sites -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — stealth browser for anti-bot protected sites - -The typical flow: the agent first searches with SearXNG, then browses the -results with Camofox (or CloakBrowser if the site is protected). - -## Benefits - -- **100% free, self-hosted, unlimited.** No API keys to buy, no - subscriptions, no rate limits. Everything runs on your machine, - Docker and npm. Unlimited usage, zero cost. - -- **Lightweight, runs anywhere.** Built and tested on a Raspberry Pi - — if it runs there, it runs everywhere. Minimal resource consumption, - no heavy infrastructure needed, runs 24/7 on low-power hardware. - -- **Search + browse in one kit.** No manual integration needed. - Searching and browsing are two distinct phases, both covered. - -- **Automatic navigation escalation.** If Camofox gets blocked by - Cloudflare/Akamai, the agent automatically switches to CloakBrowser. - -- **Smart performance.** SearXNG for the search phase (milliseconds). - Camofox and CloakBrowser are only used to browse the sites that - actually need it. - -- **Automatic agent choice.** The AI agent decides which tool to use: - SearXNG for initial search, Camofox for browsing, CloakBrowser if - the site is protected. Zero human intervention. - -- **Deep Research mode.** The skill instructs the agent to go beyond - superficial answers: explore multiple angles, cross-verify sources, - cover every aspect, and never cut corners. - -- **Fully customizable.** The SKILL.md is plain text. You can edit the - core rules, add your own, remove what you don't need. Adapt it to - your workflow, your team, your standards. - -- **Native stealth.** CloakBrowser automatically detects Cloudflare, - Akamai, DataDome, Imperva, PerimeterX, and DDoS-Guard challenges, - and waits for them to resolve before extracting content. - -- **Works with any agent.** The SKILL.md is written for OpenCode, - but the logic is identical for any AI agent. Same README, same - package.json, everything works everywhere. Just ask your agent - how to convert the skill for its environment. - -## 🏆 State of the art - -These three tools were chosen because they represent the current -state of the art available today. A skill like this is designed -to evolve: when better tools emerge, updating the SKILL.md is -all it takes to swap them in. 🔄 - -⭐ **Star the repo and follow** to stay up to date on new tools, -flow improvements, and orchestration updates over time. 🚀 - -## Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Search │ │ -│ │ │ │ -│ │ SearXNG │ search engines → URLs │ -│ │ (Docker) │ JSON results, fast │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ results ready → to browse │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Browsing │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ browser + REST │ │ -│ │ │ (Docker) │ JS, click, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ if blocked │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ stealth Chromium │ │ -│ │ │ (npm) │ anti-bot, proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## How it works - -### Phase 1 — Search with SearXNG - -Docker container on `localhost:8080`. Metasearch engine that queries -Google, Wikipedia, Bing, DuckDuckGo and many others simultaneously. -JSON output with titles, snippets, and URLs. - -**Example:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -The agent now has a list of URLs to visit and autonomously decides -whether to browse them with Camofox or CloakBrowser based on the site. - -### Phase 2 — Browse with Camofox - -Docker container on `localhost:9377`. Exposes a full Firefox browser -through a REST API. The agent can create tabs, navigate, click, -scroll, execute arbitrary JavaScript, and structure data. - -**Includes:** Mozilla's Readability.js for extracting clean articles, -removing nav, sidebar, and ads (~70% token savings). - -**Main commands:** - -```bash -# Create tab and navigate -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Read snapshot (accessibility tree) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Execute JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Phase 3 — Browse with CloakBrowser (when Camofox isn't enough) - -npm package based on Playwright + `cloakbrowser`. Launches a Chromium -browser with advanced fingerprinting to bypass Cloudflare, Akamai, -DataDome and other anti-bot systems. Automatic challenge detection -with wait and retry. - -**Available scripts:** - -- `cloak-fetch.mjs` — universal fetch with challenge detection -- `cloak-script.mjs` — custom Playwright script execution - -**Example:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Why both Camofox and CloakBrowser? - -Because speed and stealth are a tradeoff, and the right tool depends on the site. - -**Camofox — fast, structured, persistent.** -Camofox wraps Camoufox (a C++-level Firefox fork) in a REST API with an -always-warm browser. After a ~1-3s cold start, every request is near-instant. -Its accessibility snapshots are ~90% smaller than raw HTML, with stable -element refs (e1, e2, ...) for reliable interaction. It handles the ~90% of -sites that don't use advanced anti-bot protection: articles, docs, search -engines, standard web pages. - -**CloakBrowser — stealth, anti-bot, on-demand.** -CloakBrowser launches a fresh Chromium instance per request (~1-3s startup -each time). It uses advanced fingerprinting, proxy support, geoip, and -automatic challenge detection to bypass Cloudflare, Akamai, DataDome, -Imperva, PerimeterX, and DDoS-Guard. It is the last resort for the ~10% of -sites that block Camofox. - -**Real-world numbers:** - -| Tool | Cloudflare standard | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (Camofox engine) | up to **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** applies **58 C++ source-level patches** and scores **0.9 reCAPTCHA v3** (human-level, server-verified), passing all major anti-bot tests including Cloudflare Turnstile and FingerprintJS [²] -- **Camofox** cold start: **~1-3s** (one-time, then ~0ms per request via warm REST API) [³] -- **Playwright/Chromium** cold start: **~0.5-6s** (every launch, varies by environment) [⁴] - -Camofox handles the fast path. CloakBrowser handles the edge cases. Together -they cover the entire web with no gaps. The agent decides which to use. - -### Sources - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Installation - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Show this README to your AI agent for a complete installation -tailored to your environment and platform. - -**Services overview:** - -| Service | How | Reference | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (included) | `scripts/cloak/cloak-fetch.mjs` | - -**For the AI agent — read these files:** - -| File | What it contains | -|---|---| -| `SKILL.md` | Complete skill: commands, escalation, troubleshooting | -| `scripts/cloak/cloak-fetch.mjs` | CloakBrowser CLI usage and all options | -| `scripts/setup-dependencies.sh` | System dependencies | -| `scripts/check-browser-search.sh` | Post-installation verification | -| `docker/setup.md` | Docker setup tips | - -**Note:** `SKILL.md` is written for **OpenCode** syntax (`exec`, `curl`). -If your agent uses a different format (Claude Code, Cursor, etc.), read it -and convert the commands to your agent's syntax before using the skill. - -## Environment variables - -| Variable | Required for | Default | -|----------------------|-----------------------------------|---------| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup in Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Camofox stop endpoint | — | - -## What this skill does NOT do - -- **Social media.** Instagram, Facebook, TikTok, LinkedIn, and Twitter/X - require login. `browser-search` does not attempt to browse them. -- **Download files.** It is read-only (except for explicit screenshots). -- **Bypass paywalls.** Does not circumvent payment or login systems. - -## Get involved - -browser-search is open source and free. If you find it useful: - -- ⭐ **Star the repo** — helps others discover it -- 🐛 **Open an issue** — report bugs or suggest features -- 🔀 **Submit a PR** — fix, improve, extend -- 💬 **Share it** — with your team, on Reddit, Twitter, Discord -- 🧠 **Adapt it** — fork it, tweak the SKILL.md, make it yours - -Every contribution, no matter how small, makes this better. - -## License - -MIT diff --git a/browser-search/i18n/README.ar.md b/browser-search/i18n/README.ar.md deleted file mode 100644 index 785c718..0000000 --- a/browser-search/i18n/README.ar.md +++ /dev/null @@ -1,227 +0,0 @@ -# بحث-المتصفح - -

- browser-search logo -

- -> **مهارة لوكلاء الذكاء الاصطناعي.** OpenCode، Claude Code، Cursor، OpenClaw وغيرهم. ابحث في الويب باستخدام SearXNG، تصفح باستخدام Camofox، تجاوز الحماية باستخدام CloakBrowser. كل شيء مستضاف ذاتياً، مجاني، غير محدود. - -## لماذا هي موجودة - -browser-search هي مهارة — مجموعة تعليمات لوكلاء الذكاء الاصطناعي مثل OpenCode وClaude Code وCursor وOpenClaw وغيرهم. إنها تعلم وكيلك كيفية البحث والتصفح في الويب باستخدام ثلاث أدوات مفتوحة المصدر منسقة. - -المشكلة؟ الويب معادٍ للأتمتة. Cloudflare وAkamai وDataDome وأنظمة مكافحة البوت الأخرى تمنع الطلبات البسيطة. المواقع الحديثة تستخدم JavaScript ثقيلاً وتحميلاً بطيئاً وعرضاً من جانب العميل. حل واحد لا يكفي. - -`browser-search` ينسق **ثلاث أدوات مفتوحة المصدر** في نظام بحث وتصفح واحد مصمم لوكلاء الذكاء الاصطناعي. كل أداة لها دورها، يتم تنسيقها بواسطة المهارة مع منطق التصعيد والاختيار التلقائي والتكامل الجاهز للاستخدام: - -1. **[SearXNG](https://github.com/searxng/searxng)** — محرك بحث وصفي لمرحلة البحث (متعدد المصادر، JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — متصفح يمكن الوصول إليه عبر REST API للمواقع القياسية -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — متصفح متخفي للمواقع المحمية بمكافحة البوت - -التدفق النموذجي: يبحث الوكيل أولاً باستخدام SearXNG، ثم يتصفح النتائج باستخدام Camofox (أو CloakBrowser إذا كان الموقع محمياً). - -## الفوائد - -- **مجاني 100%، مستضاف ذاتياً، غير محدود.** لا حاجة لشراء مفاتيح API، لا اشتراكات، لا حدود للمعدل. كل شيء يعمل على جهازك، Docker وnpm. استخدام غير محدود، تكلفة صفرية. - -- **خفيف، يعمل في أي مكان.** تم بناؤه واختباره على Raspberry Pi — إذا كان يعمل هناك، فإنه يعمل في كل مكان. استهلاك موارد ضئيل، لا حاجة لبنية تحتية ثقيلة، يعمل 24/7 على أجهزة منخفضة الطاقة. - -- **بحث + تصفح في حزمة واحدة.** لا حاجة لتكامل يدوي. البحث والتصفح مرحلتان متميزتان، كلتاهما مغطاة. - -- **تصعيد تلقائي للتنقل.** إذا تم حظر Camofox بواسطة Cloudflare/Akamai، يتحول الوكيل تلقائياً إلى CloakBrowser. - -- **أداء ذكي.** SearXNG لمرحلة البحث (ملي ثانية). Camofox وCloakBrowser يُستخدمان فقط لتصفح المواقع التي تحتاج ذلك فعلاً. - -- **اختيار تلقائي للوكيل.** وكيل الذكاء الاصطناعي يقرر أي أداة يستخدم: SearXNG للبحث الأولي، Camofox للتصفح، CloakBrowser إذا كان الموقع محمياً. تدخل بشري صفري. - -- **وضع البحث العميق.** المهارة توجه الوكيل لتجاوز الإجابات السطحية: استكشاف زوايا متعددة، التحقق من المصادر بشكل متقاطع، تغطية كل جانب، وعدم أخذ اختصارات أبداً. - -- **قابل للتخصيص بالكامل.** SKILL.md هو نص عادي. يمكنك تحرير القواعد الأساسية، إضافة قواعدك الخاصة، إزالة ما لا تحتاجه. كيّفه مع سير عملك، فريقك، معاييرك. - -- **تخفي أصلي.** CloakBrowser يكتشف تلقائياً تحديات Cloudflare وAkamai وDataDome وImperva وPerimeterX وDDoS-Guard، وينتظر حلها قبل استخراج المحتوى. - -- **يعمل مع أي وكيل.** SKILL.md مكتوب لـ OpenCode، لكن المنطق متطابق لأي وكيل ذكاء اصطناعي. نفس README، نفس package.json، كل شيء يعمل في كل مكان. فقط اطلب من وكيلك تحويل المهارة لبيئته. - -## 🏆 أحدث ما توصلت إليه التكنولوجيا - -تم اختيار هذه الأدوات الثلاث لأنها تمثل أحدث ما توصلت إليه التكنولوجيا المتاحة اليوم. مثل هذه المهارة مصممة لتتطور: عندما تظهر أدوات أفضل، كل ما يتطلبه الأمر هو تحديث SKILL.md لاستبدالها. 🔄 - -⭐ **ضع نجمة على المستودع وتابع** لتبقى على اطلاع دائم بالأدوات الجديدة وتحسينات التدفق وتحديثات التنسيق. 🚀 - -## البنية - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ بحث │ │ -│ │ │ │ -│ │ SearXNG │ محركات البحث ← URLs │ -│ │ (Docker) │ نتائج JSON، سريعة │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ النتائج جاهزة → للتصفح │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ تصفح │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ متصفح + REST │ │ -│ │ │ (Docker) │ JS، نقرة، تقييم │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ إذا تم الحظر │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Chromium متخفي │ │ -│ │ │ (npm) │ مضاد للبوت، وكيل │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## كيف يعمل - -### المرحلة 1 — البحث باستخدام SearXNG - -حاوية Docker على `localhost:8080`. محرك بحث وصفي يستعلم Google وWikipedia وBing وDuckDuckGo والعديد من الآخرين في وقت واحد. مخرجات JSON مع عناوين ومقتطفات وروابط URL. - -**مثال:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -الوكيل لديه الآن قائمة عناوين URL لزيارتها ويقرر بشكل مستقل ما إذا كان سيتصفحها باستخدام Camofox أو CloakBrowser بناءً على الموقع. - -### المرحلة 2 — التصفح باستخدام Camofox - -حاوية Docker على `localhost:9377`. يعرض متصفح Firefox كاملاً عبر REST API. يمكن للوكيل إنشاء علامات تبويب، والتنقل، والنقر، والتمرير، وتنفيذ JavaScript عشوائي، وهيكلة البيانات. - -**يشمل:** Readability.js من Mozilla لاستخراج مقالات نظيفة، مع إزالة التنقل والشريط الجانبي والإعلانات (توفير ~70% من الرموز). - -**الأوامر الرئيسية:** - -```bash -# إنشاء علامة تبويب والتنقل -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# قراءة لقطة (شجرة الوصول) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# تنفيذ JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### المرحلة 3 — التصفح باستخدام CloakBrowser (عندما لا يكون Camofox كافياً) - -حزمة npm مبنية على Playwright + `cloakbrowser`. تطلق متصفح Chromium ببصمة رقمية متقدمة لتجاوز Cloudflare وAkamai وDataDome وأنظمة مكافحة البوت الأخرى. كشف تلقائي للتحديات مع الانتظار وإعادة المحاولة. - -**البرامج النصية المتاحة:** - -- `cloak-fetch.mjs` — جلب عالمي مع كشف التحديات -- `cloak-script.mjs` — تنفيذ برنامج Playwright مخصص - -**مثال:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## لماذا كل من Camofox وCloakBrowser؟ - -لأن السرعة والتخفي هما مقايضة، والأداة المناسبة تعتمد على الموقع. - -**Camofox — سريع، منظم، دائم.** -Camofox يغلف Camoufox (شوكة Firefox على مستوى C++) في REST API مع متصفح دافئ دائماً. بعد بدء بارد ~1-3ث، كل طلب يكاد يكون فورياً. لقطات الوصول الخاصة به أصغر بنسبة ~90% من HTML الخام، مع مراجع عناصر مستقرة (e1، e2، ...) للتفاعل الموثوق. يتعامل مع ~90% من المواقع التي لا تستخدم حماية متقدمة لمكافحة البوت: المقالات، المستندات، محركات البحث، صفحات الويب القياسية. - -**CloakBrowser — متخفي، مضاد للبوت، عند الطلب.** -CloakBrowser يطلق مثيل Chromium جديد لكل طلب (~1-3ث بدء في كل مرة). يستخدم بصمة رقمية متقدمة، دعم وكيل، تحديد الموقع الجغرافي، وكشف التحديات التلقائي لتجاوز Cloudflare وAkamai وDataDome وImperva وPerimeterX وDDoS-Guard. إنه الملاذ الأخير لـ ~10% من المواقع التي تحظر Camofox. - -**أرقام من العالم الحقيقي:** - -| الأداة | Cloudflare قياسي | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (محرك Camofox) | حتى **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** يطبق **58 تصحيحاً على مستوى كود مصدر C++** ويحقق **0.9 reCAPTCHA v3** (مستوى بشري، تم التحقق منه بالخادم)، مجتازاً جميع اختبارات مكافحة البوت الرئيسية بما في ذلك Cloudflare Turnstile وFingerprintJS [²] -- **Camofox** بدء بارد: **~1-3ث** (مرة واحدة، ثم ~0ملث لكل طلب عبر REST API دافئ) [³] -- **Playwright/Chromium** بدء بارد: **~0.5-6ث** (كل إطلاق، يختلف حسب البيئة) [⁴] - -Camofox يتعامل مع المسار السريع. CloakBrowser يتعامل مع الحالات الحدية. معاً يغطيان الويب بأكمله دون ثغرات. الوكيل يقرر أي منهما يستخدم. - -### المصادر - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## التثبيت - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -أظهر هذا README لوكيل الذكاء الاصطناعي الخاص بك لتثبيت كامل مصمم خصيصاً لبيئتك ومنصتك. - -**نظرة عامة على الخدمات:** - -| الخدمة | الطريقة | المرجع | -|---|---|---| -| SearXNG | Docker، `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker، `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (مضمن) | `scripts/cloak/cloak-fetch.mjs` | - -**لوكيل الذكاء الاصطناعي — اقرأ هذه الملفات:** - -| الملف | ما يحتويه | -|---|---| -| `SKILL.md` | المهارة الكاملة: الأوامر، التصعيد، استكشاف الأخطاء | -| `scripts/cloak/cloak-fetch.mjs` | استخدام واجهة CLI لـ CloakBrowser وجميع الخيارات | -| `scripts/setup-dependencies.sh` | تبعيات النظام | -| `scripts/check-browser-search.sh` | التحقق بعد التثبيت | -| `docker/setup.md` | نصائح إعداد Docker | - -**ملاحظة:** `SKILL.md` مكتوب بناء جملة **OpenCode** (`exec`، `curl`). إذا كان وكيلك يستخدم تنسيقاً مختلفاً (Claude Code، Cursor، إلخ)، اقرأه وحوّل الأوامر إلى بناء جملة وكيلك قبل استخدام المهارة. - -## متغيرات البيئة - -| المتغير | مطلوب لـ | الافتراضي | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate، session، cleanup في Camofox | — | -| `CAMOFOX_ADMIN_KEY` | نقطة إيقاف Camofox | — | - -## ما لا تفعله هذه المهارة - -- **وسائل التواصل الاجتماعي.** Instagram وFacebook وTikTok وLinkedIn وTwitter/X تتطلب تسجيل الدخول. `browser-search` لا يحاول تصفحها. -- **تحميل الملفات.** هو للقراءة فقط (باستثناء لقطات الشاشة الصريحة). -- **تجاوز جدران الدفع.** لا يتجاوز أنظمة الدفع أو تسجيل الدخول. - -## شارك - -browser-search مفتوح المصدر ومجاني. إذا وجدته مفيداً: - -- ⭐ **ضع نجمة على المستودع** — يساعد الآخرين على اكتشافه -- 🐛 **افتح issue** — أبلغ عن الأخطاء أو اقترح ميزات -- 🔀 **أرسل PR** — أصلح، حسن، وسع -- 💬 **شاركه** — مع فريقك، على Reddit، Twitter، Discord -- 🧠 **كيّفه** — انسخ المستودع، عدّل SKILL.md، اجعله ملكك - -كل مساهمة، مهما كانت صغيرة، تجعله أفضل. - -## الترخيص - -MIT diff --git a/browser-search/i18n/README.de.md b/browser-search/i18n/README.de.md deleted file mode 100644 index 4ba71c4..0000000 --- a/browser-search/i18n/README.de.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Eine Skill für KI-Agenten.** OpenCode, Claude Code, Cursor, OpenClaw und mehr. Durchsuchen Sie das Web mit SearXNG, browsen Sie mit Camofox, umgehen Sie Schutzmaßnahmen mit CloakBrowser. Alles selbst gehostet, kostenlos, unbegrenzt. - -## Warum es existiert - -browser-search ist eine SKILL — ein Anweisungssatz für KI-Agenten wie OpenCode, Claude Code, Cursor, OpenClaw und andere. Sie bringt Ihrem Agenten bei, wie er mit drei orchestrierten Open-Source-Tools das Web durchsuchen und browsen kann. - -Das Problem? Das Web ist feindlich gegenüber Automatisierung. Cloudflare, Akamai, DataDome und andere Anti-Bot-Systeme blockieren einfache Anfragen. Moderne Websites verwenden schweres JavaScript, verzögertes Laden und clientseitiges Rendering. Eine einzige Lösung reicht nicht aus. - -`browser-search` orchestriert **drei Open-Source-Tools** zu einem einzigen Such- und Browsingsystem, das für KI-Agenten entwickelt wurde. Jedes Tool hat seine Rolle, orchestriert durch die Skill mit Eskalationslogik, automatischer Auswahl und sofort einsatzbereiter Integration: - -1. **[SearXNG](https://github.com/searxng/searxng)** — Metasuchmaschine für die Suchphase (multiquelle, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — über REST API navigierbarer Browser für Standard-Websites -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — Tarnkappenbrowser für anti-bot-geschützte Websites - -Der typische Ablauf: Der Agent sucht zuerst mit SearXNG, dann durchsucht er die Ergebnisse mit Camofox (oder CloakBrowser, wenn die Website geschützt ist). - -## Vorteile - -- **100% kostenlos, selbst gehostet, unbegrenzt.** Keine API-Schlüssel zu kaufen, keine Abonnements, keine Ratenbegrenzungen. Alles läuft auf Ihrer Maschine, Docker und npm. Unbegrenzte Nutzung, null Kosten. - -- **Leicht, läuft überall.** Entwickelt und getestet auf einem Raspberry Pi — wenn es dort läuft, läuft es überall. Minimaler Ressourcenverbrauch, keine schwere Infrastruktur erforderlich, läuft 24/7 auf stromsparender Hardware. - -- **Suche + Browsen in einem Kit.** Keine manuelle Integration erforderlich. Suche und Browsen sind zwei verschiedene Phasen, beide abgedeckt. - -- **Automatische Navigationseskalation.** Wenn Camofox von Cloudflare/Akamai blockiert wird, wechselt der Agent automatisch zu CloakBrowser. - -- **Intelligente Leistung.** SearXNG für die Suchphase (Millisekunden). Camofox und CloakBrowser werden nur zum Browsen der Websites verwendet, die es tatsächlich benötigen. - -- **Automatische Agentenauswahl.** Der KI-Agent entscheidet, welches Tool verwendet wird: SearXNG für die erste Suche, Camofox zum Browsen, CloakBrowser wenn die Website geschützt ist. Kein menschliches Eingreifen. - -- **Tiefenrecherche-Modus.** Die Skill weist den Agenten an, über oberflächliche Antworten hinauszugehen: mehrere Blickwinkel erkunden, Quellen kreuzweise verifizieren, jeden Aspekt abdecken und niemals Abkürzungen nehmen. - -- **Vollständig anpassbar.** Die SKILL.md ist reiner Text. Sie können die Kernregeln bearbeiten, eigene hinzufügen, entfernen was Sie nicht brauchen. Passen Sie sie an Ihren Workflow, Ihr Team, Ihre Standards an. - -- **Native Tarnung.** CloakBrowser erkennt automatisch Cloudflare-, Akamai-, DataDome-, Imperva-, PerimeterX- und DDoS-Guard-Herausforderungen und wartet auf deren Lösung, bevor es Inhalte extrahiert. - -- **Funktioniert mit jedem Agenten.** Die SKILL.md ist für OpenCode geschrieben, aber die Logik ist für jeden KI-Agenten identisch. Gleiches README, gleiches package.json, alles funktioniert überall. Bitten Sie einfach Ihren Agenten, die Skill für seine Umgebung zu konvertieren. - -## 🏆 Stand der Technik - -Diese drei Werkzeuge wurden ausgewählt, weil sie den aktuellen Stand der Technik repräsentieren. Eine solche Skill ist darauf ausgelegt, sich weiterzuentwickeln: wenn bessere Werkzeuge auftauchen, reicht ein Update der SKILL.md, um sie auszutauschen. 🔄 - -⭐ **Gib dem Repository einen Stern und folge ihm**, um über neue Tools, Verbesserungen des Ablaufs und Orchestrierungs-Updates auf dem Laufenden zu bleiben. 🚀 - -## Architektur - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Suche │ │ -│ │ │ │ -│ │ SearXNG │ Suchmaschinen → URLs │ -│ │ (Docker) │ JSON-Ergebnisse, schnell │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ Ergebnisse bereit → browsen │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Browsen │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ Browser + REST │ │ -│ │ │ (Docker) │ JS, Klick, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ wenn blockiert │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Tarn-Chromium │ │ -│ │ │ (npm) │ Anti-Bot, Proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Wie es funktioniert - -### Phase 1 — Suche mit SearXNG - -Docker-Container auf `localhost:8080`. Metasuchmaschine, die gleichzeitig Google, Wikipedia, Bing, DuckDuckGo und viele andere abfragt. JSON-Ausgabe mit Titeln, Ausschnitten und URLs. - -**Beispiel:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -Der Agent hat nun eine Liste von zu besuchenden URLs und entscheidet autonom, ob er sie mit Camofox oder CloakBrowser basierend auf der Website durchsucht. - -### Phase 2 — Browsen mit Camofox - -Docker-Container auf `localhost:9377`. Stellt einen vollständigen Firefox-Browser über eine REST-API bereit. Der Agent kann Tabs erstellen, navigieren, klicken, scrollen, beliebiges JavaScript ausführen und Daten strukturieren. - -**Enthalten:** Mozillas Readability.js zum Extrahieren sauberer Artikel, Entfernen von Navigation, Seitenleiste und Werbung (~70% Token-Ersparnis). - -**Hauptbefehle:** - -```bash -# Tab erstellen und navigieren -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Snapshot lesen (Barrierefreiheitsbaum) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# JavaScript ausführen -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Phase 3 — Browsen mit CloakBrowser (wenn Camofox nicht ausreicht) - -npm-Paket basierend auf Playwright + `cloakbrowser`. Startet einen Chromium-Browser mit erweiterter Fingerabdruckerkennung, um Cloudflare, Akamai, DataDome und andere Anti-Bot-Systeme zu umgehen. Automatische Erkennung von Herausforderungen mit Warte- und Wiederholungsfunktion. - -**Verfügbare Skripte:** - -- `cloak-fetch.mjs` — universeller Fetch mit Herausforderungserkennung -- `cloak-script.mjs` — benutzerdefinierte Playwright-Skriptausführung - -**Beispiel:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Warum sowohl Camofox als auch CloakBrowser? - -Weil Geschwindigkeit und Tarnung ein Kompromiss sind und das richtige Werkzeug von der Website abhängt. - -**Camofox — schnell, strukturiert, persistent.** -Camofox kapselt Camoufox (einen C++-basierten Firefox-Fork) in eine REST-API mit einem immer warmen Browser. Nach einem Kaltstart von ~1-3s ist jede Anfrage nahezu sofort. Seine Barrierefreiheits-Snapshots sind ~90% kleiner als rohes HTML, mit stabilen Elementreferenzen (e1, e2, ...) für zuverlässige Interaktion. Es bewältigt ~90% der Websites, die keine erweiterte Anti-Bot-Schutz verwenden: Artikel, Dokumente, Suchmaschinen, Standard-Webseiten. - -**CloakBrowser — Tarnung, Anti-Bot, auf Abruf.** -CloakBrowser startet eine neue Chromium-Instanz pro Anfrage (~1-3s Startzeit jedes Mal). Es verwendet erweiterte Fingerabdruckerkennung, Proxy-Unterstützung, GeoIP und automatische Herausforderungserkennung, um Cloudflare, Akamai, DataDome, Imperva, PerimeterX und DDoS-Guard zu umgehen. Es ist die letzte Ressource für die ~10% der Websites, die Camofox blockieren. - -**Zahlen aus der Praxis:** - -| Werkzeug | Cloudflare Standard | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (Camofox-Engine) | bis zu **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** wendet **58 C++-Quellcode-Patches** an und erreicht **0.9 reCAPTCHA v3** (menschliches Niveau, serververifiziert), bestehend alle wichtigen Anti-Bot-Tests einschließlich Cloudflare Turnstile und FingerprintJS [²] -- **Camofox** Kaltstart: **~1-3s** (einmalig, dann ~0ms pro Anfrage über warme REST-API) [³] -- **Playwright/Chromium** Kaltstart: **~0.5-6s** (jeder Start, variiert je nach Umgebung) [⁴] - -Camofox bewältigt den schnellen Pfad. CloakBrowser bewältigt die Grenzfälle. Zusammen decken sie das gesamte Web ohne Lücken ab. Der Agent entscheidet, welches verwendet wird. - -### Quellen - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Installation - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Zeigen Sie dieses README Ihrem KI-Agenten für eine vollständige, auf Ihre Umgebung und Plattform zugeschnittene Installation. - -**Diensteübersicht:** - -| Dienst | Wie | Referenz | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (enthalten) | `scripts/cloak/cloak-fetch.mjs` | - -**Für den KI-Agenten — lesen Sie diese Dateien:** - -| Datei | Was sie enthält | -|---|---| -| `SKILL.md` | Vollständige Skill: Befehle, Eskalation, Fehlerbehebung | -| `scripts/cloak/cloak-fetch.mjs` | CloakBrowser CLI-Nutzung und alle Optionen | -| `scripts/setup-dependencies.sh` | Systemabhängigkeiten | -| `scripts/check-browser-search.sh` | Überprüfung nach der Installation | -| `docker/setup.md` | Docker-Einrichtungstipps | - -**Hinweis:** `SKILL.md` ist für die **OpenCode**-Syntax (`exec`, `curl`) geschrieben. Wenn Ihr Agent ein anderes Format verwendet (Claude Code, Cursor, etc.), lesen Sie sie und konvertieren Sie die Befehle in die Syntax Ihres Agenten, bevor Sie die Skill verwenden. - -## Umgebungsvariablen - -| Variable | Erforderlich für | Standard | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup in Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Camofox stop-Endpunkt | — | - -## Was diese Skill NICHT tut - -- **Soziale Medien.** Instagram, Facebook, TikTok, LinkedIn und Twitter/X erfordern eine Anmeldung. `browser-search` versucht nicht, sie zu durchsuchen. -- **Dateien herunterladen.** Es ist schreibgeschützt (außer bei expliziten Screenshots). -- **Paywalls umgehen.** Umgeht keine Zahlungs- oder Anmeldesysteme. - -## Mitmachen - -browser-search ist Open Source und kostenlos. Wenn Sie es nützlich finden: - -- ⭐ **Star das Repository** — hilft anderen, es zu entdecken -- 🐛 **Öffne ein Issue** — melde Fehler oder schlage Funktionen vor -- 🔀 **Sende eine PR** — korrigiere, verbessere, erweitere -- 💬 **Teile es** — mit deinem Team, auf Reddit, Twitter, Discord -- 🧠 **Passe es an** — forke es, passe die SKILL.md an, mach es zu deinem - -Jeder Beitrag, egal wie klein, macht dies besser. - -## Lizenz - -MIT diff --git a/browser-search/i18n/README.es.md b/browser-search/i18n/README.es.md deleted file mode 100644 index 897bfaf..0000000 --- a/browser-search/i18n/README.es.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Una skill para agentes de IA.** OpenCode, Claude Code, Cursor, OpenClaw y más. Busca en la web con SearXNG, navega con Camofox, evade protecciones con CloakBrowser. Todo autoalojado, gratuito, sin límites. - -## Por qué existe - -browser-search es una SKILL — un conjunto de instrucciones para agentes de IA como OpenCode, Claude Code, Cursor, OpenClaw y otros. Enseña a tu agente cómo buscar y navegar por la web utilizando tres herramientas open source orquestadas. - -¿El problema? La web es hostil a la automatización. Cloudflare, Akamai, DataDome y otros sistemas anti-bot bloquean las solicitudes simples. Los sitios modernos usan JavaScript pesado, carga diferida y renderizado del lado del cliente. Una sola solución no es suficiente. - -`browser-search` orquesta **tres herramientas open source** en un único sistema de búsqueda y navegación diseñado para agentes de IA. Cada herramienta tiene su rol, orquestada por la skill con lógica de escalado, selección automática e integración lista para usar: - -1. **[SearXNG](https://github.com/searxng/searxng)** — metabuscador para la fase de búsqueda (multifuente, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — navegador accesible vía API REST para sitios estándar -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — navegador sigiloso para sitios protegidos contra bots - -El flujo típico: el agente primero busca con SearXNG, luego navega los resultados con Camofox (o CloakBrowser si el sitio está protegido). - -## Beneficios - -- **100% gratuito, autoalojado, sin límites.** Sin claves API que comprar, sin suscripciones, sin límites de tasa. Todo se ejecuta en tu máquina, Docker y npm. Uso ilimitado, costo cero. - -- **Ligero, funciona en cualquier lugar.** Construido y probado en una Raspberry Pi — si funciona allí, funciona en todas partes. Consumo mínimo de recursos, sin necesidad de infraestructura pesada, funciona 24/7 en hardware de bajo consumo. - -- **Búsqueda + navegación en un solo kit.** Sin necesidad de integración manual. La búsqueda y la navegación son dos fases distintas, ambas cubiertas. - -- **Escalado automático de navegación.** Si Camofox es bloqueado por Cloudflare/Akamai, el agente cambia automáticamente a CloakBrowser. - -- **Rendimiento inteligente.** SearXNG para la fase de búsqueda (milisegundos). Camofox y CloakBrowser solo se usan para navegar los sitios que realmente lo necesitan. - -- **Selección automática del agente.** El agente de IA decide qué herramienta usar: SearXNG para la búsqueda inicial, Camofox para navegar, CloakBrowser si el sitio está protegido. Cero intervención humana. - -- **Modo de investigación profunda.** La skill instruye al agente para ir más allá de respuestas superficiales: explorar múltiples ángulos, verificar fuentes de forma cruzada, cubrir cada aspecto y nunca tomar atajos. - -- **Totalmente personalizable.** La SKILL.md es texto plano. Puedes editar las reglas principales, añadir las tuyas, eliminar lo que no necesites. Adáptala a tu flujo de trabajo, tu equipo, tus estándares. - -- **Sigilo nativo.** CloakBrowser detecta automáticamente los desafíos de Cloudflare, Akamai, DataDome, Imperva, PerimeterX y DDoS-Guard, y espera a que se resuelvan antes de extraer contenido. - -- **Funciona con cualquier agente.** La SKILL.md está escrita para OpenCode, pero la lógica es idéntica para cualquier agente de IA. El mismo README, el mismo package.json, todo funciona en todas partes. Solo dile a tu agente que convierta la skill para su entorno. - -## 🏆 Estado del arte - -Estas tres herramientas fueron elegidas porque representan el estado del arte actual disponible hoy. Una skill como esta está diseñada para evolucionar: cuando surjan mejores herramientas, basta con actualizar la SKILL.md para reemplazarlas. 🔄 - -⭐ **Marca la estrella del repo y sigue** para mantenerte al día sobre nuevas herramientas, mejoras del flujo y actualizaciones de la orquestación. 🚀 - -## Arquitectura - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Búsqueda │ │ -│ │ │ │ -│ │ SearXNG │ motores de búsqueda → URLs │ -│ │ (Docker) │ resultados JSON, rápido │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ resultados listos → navegar │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Navegación │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ navegador + REST │ │ -│ │ │ (Docker) │ JS, clic, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ si está bloqueado │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Chromium sigiloso│ │ -│ │ │ (npm) │ anti-bot, proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Cómo funciona - -### Fase 1 — Búsqueda con SearXNG - -Contenedor Docker en `localhost:8080`. Metabuscador que consulta Google, Wikipedia, Bing, DuckDuckGo y muchos otros simultáneamente. Salida JSON con títulos, fragmentos y URLs. - -**Ejemplo:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -El agente ahora tiene una lista de URLs para visitar y decide autónomamente si navegarlas con Camofox o CloakBrowser según el sitio. - -### Fase 2 — Navegación con Camofox - -Contenedor Docker en `localhost:9377`. Expone un navegador Firefox completo a través de una API REST. El agente puede crear pestañas, navegar, hacer clic, desplazarse, ejecutar JavaScript arbitrario y estructurar datos. - -**Incluye:** Readability.js de Mozilla para extraer artículos limpios, eliminando navegación, barra lateral y anuncios (~70% de ahorro de tokens). - -**Comandos principales:** - -```bash -# Crear pestaña y navegar -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Leer instantánea (árbol de accesibilidad) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Ejecutar JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Fase 3 — Navegación con CloakBrowser (cuando Camofox no es suficiente) - -Paquete npm basado en Playwright + `cloakbrowser`. Lanza un navegador Chromium con huella digital avanzada para eludir Cloudflare, Akamai, DataDome y otros sistemas anti-bot. Detección automática de desafíos con espera y reintento. - -**Scripts disponibles:** - -- `cloak-fetch.mjs` — fetch universal con detección de desafíos -- `cloak-script.mjs` — ejecución de scripts Playwright personalizados - -**Ejemplo:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Por qué tanto Camofox como CloakBrowser? - -Porque la velocidad y el sigilo son un compromiso, y la herramienta adecuada depende del sitio. - -**Camofox — rápido, estructurado, persistente.** -Camofox envuelve a Camoufox (un fork de Firefox a nivel C++) en una API REST con un navegador siempre caliente. Después de un arranque en frío de ~1-3s, cada solicitud es casi instantánea. Sus instantáneas de accesibilidad son ~90% más pequeñas que el HTML bruto, con referencias de elementos estables (e1, e2, ...) para una interacción fiable. Maneja ~90% de los sitios que no usan protección anti-bot avanzada: artículos, documentos, motores de búsqueda, páginas web estándar. - -**CloakBrowser — sigiloso, anti-bot, bajo demanda.** -CloakBrowser lanza una nueva instancia de Chromium por solicitud (~1-3s de arranque cada vez). Utiliza huella digital avanzada, soporte de proxy, geoip y detección automática de desafíos para eludir Cloudflare, Akamai, DataDome, Imperva, PerimeterX y DDoS-Guard. Es el último recurso para el ~10% de los sitios que bloquean a Camofox. - -**Números del mundo real:** - -| Herramienta | Cloudflare estándar | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (motor de Camofox) | hasta **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** aplica **58 parches a nivel de código fuente C++** y obtiene **0.9 reCAPTCHA v3** (nivel humano, verificado por servidor), superando todas las pruebas anti-bot principales, incluyendo Cloudflare Turnstile y FingerprintJS [²] -- **Camofox** arranque en frío: **~1-3s** (una vez, luego ~0ms por solicitud vía API REST caliente) [³] -- **Playwright/Chromium** arranque en frío: **~0.5-6s** (cada lanzamiento, varía según el entorno) [⁴] - -Camofox maneja la ruta rápida. CloakBrowser maneja los casos extremos. Juntos cubren toda la web sin huecos. El agente decide cuál usar. - -### Fuentes - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Instalación - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Muestra este README a tu agente de IA para una instalación completa adaptada a tu entorno y plataforma. - -**Resumen de servicios:** - -| Servicio | Cómo | Referencia | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (incluido) | `scripts/cloak/cloak-fetch.mjs` | - -**Para el agente de IA — lee estos archivos:** - -| Archivo | Qué contiene | -|---|---| -| `SKILL.md` | Skill completa: comandos, escalado, solución de problemas | -| `scripts/cloak/cloak-fetch.mjs` | Uso de CloakBrowser CLI y todas las opciones | -| `scripts/setup-dependencies.sh` | Dependencias del sistema | -| `scripts/check-browser-search.sh` | Verificación post-instalación | -| `docker/setup.md` | Consejos de configuración Docker | - -**Nota:** `SKILL.md` está escrita para la sintaxis de **OpenCode** (`exec`, `curl`). Si tu agente usa un formato diferente (Claude Code, Cursor, etc.), léela y convierte los comandos a la sintaxis de tu agente antes de usar la skill. - -## Variables de entorno - -| Variable | Requerida para | Por defecto | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup en Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Endpoint stop de Camofox | — | - -## Qué NO hace esta skill - -- **Redes sociales.** Instagram, Facebook, TikTok, LinkedIn y Twitter/X requieren inicio de sesión. `browser-search` no intenta navegarlas. -- **Descargar archivos.** Es de solo lectura (excepto capturas de pantalla explícitas). -- **Eludir muros de pago.** No evita sistemas de pago o inicio de sesión. - -## Participa - -browser-search es open source y gratuito. Si te resulta útil: - -- ⭐ **Marca la estrella del repo** — ayuda a otros a descubrirlo -- 🐛 **Abre un issue** — reporta errores o sugiere funciones -- 🔀 **Envía un PR** — corrige, mejora, extiende -- 💬 **Compártelo** — con tu equipo, en Reddit, Twitter, Discord -- 🧠 **Adáptalo** — haz un fork, ajusta la SKILL.md, hazlo tuyo - -Cada contribución, por pequeña que sea, lo hace mejor. - -## Licencia - -MIT diff --git a/browser-search/i18n/README.fr.md b/browser-search/i18n/README.fr.md deleted file mode 100644 index 0d55a7a..0000000 --- a/browser-search/i18n/README.fr.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Une skill pour les agents IA.** OpenCode, Claude Code, Cursor, OpenClaw et bien d'autres. Recherchez sur le web avec SearXNG, naviguez avec Camofox, contournez les protections avec CloakBrowser. Le tout auto-hébergé, gratuit, illimité. - -## Pourquoi ça existe - -browser-search est une SKILL — un ensemble d'instructions pour des agents IA comme OpenCode, Claude Code, Cursor, OpenClaw et autres. Elle apprend à votre agent comment rechercher et naviguer sur le web en utilisant trois outils open source orchestrés. - -Le problème ? Le web est hostile à l'automatisation. Cloudflare, Akamai, DataDome et d'autres systèmes anti-bot bloquent les requêtes simples. Les sites modernes utilisent du JavaScript lourd, du chargement différé et du rendu côté client. Une seule solution ne suffit pas. - -`browser-search` orchestre **trois outils open source** en un seul système de recherche et de navigation conçu pour les agents IA. Chaque outil a son rôle, orchestré par la skill avec une logique d'escalade, une sélection automatique et une intégration prête à l'emploi : - -1. **[SearXNG](https://github.com/searxng/searxng)** — métamoteur de recherche pour la phase de recherche (multisource, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — navigateur accessible via API REST pour les sites standards -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — navigateur furtif pour les sites protégés anti-bot - -Le flux typique : l'agent recherche d'abord avec SearXNG, puis navigue dans les résultats avec Camofox (ou CloakBrowser si le site est protégé). - -## Avantages - -- **100% gratuit, auto-hébergé, illimité.** Pas de clés API à acheter, pas d'abonnements, pas de limites de débit. Tout fonctionne sur votre machine, Docker et npm. Utilisation illimitée, coût zéro. - -- **Léger, fonctionne partout.** Construit et testé sur un Raspberry Pi — si ça fonctionne là, ça fonctionne partout. Consommation de ressources minimale, pas d'infrastructure lourde nécessaire, fonctionne 24h/24 et 7j/7 sur du matériel basse consommation. - -- **Recherche + navigation dans un seul kit.** Pas d'intégration manuelle nécessaire. La recherche et la navigation sont deux phases distinctes, toutes deux couvertes. - -- **Escalade automatique de navigation.** Si Camofox est bloqué par Cloudflare/Akamai, l'agent bascule automatiquement vers CloakBrowser. - -- **Performances intelligentes.** SearXNG pour la phase de recherche (millisecondes). Camofox et CloakBrowser ne sont utilisés que pour naviguer sur les sites qui en ont réellement besoin. - -- **Choix automatique de l'agent.** L'agent IA décide quel outil utiliser : SearXNG pour la recherche initiale, Camofox pour la navigation, CloakBrowser si le site est protégé. Intervention humaine zéro. - -- **Mode de recherche approfondie.** La skill ordonne à l'agent d'aller au-delà des réponses superficielles : explorer plusieurs angles, vérifier les sources de manière croisée, couvrir tous les aspects et ne jamais prendre de raccourcis. - -- **Entièrement personnalisable.** Le SKILL.md est en texte brut. Vous pouvez modifier les règles principales, ajouter les vôtres, supprimer ce dont vous n'avez pas besoin. Adaptez-le à votre flux de travail, votre équipe, vos standards. - -- **Furtivité native.** CloakBrowser détecte automatiquement les défis Cloudflare, Akamai, DataDome, Imperva, PerimeterX et DDoS-Guard, et attend leur résolution avant d'extraire le contenu. - -- **Fonctionne avec n'importe quel agent.** Le SKILL.md est écrit pour OpenCode, mais la logique est identique pour tout agent IA. Même README, même package.json, tout fonctionne partout. Demandez simplement à votre agent de convertir la skill pour son environnement. - -## 🏆 État de l'art - -Ces trois outils ont été choisis parce qu'ils représentent l'état de l'art actuel disponible aujourd'hui. Une skill comme celle-ci est conçue pour évoluer : lorsque de meilleurs outils émergent, il suffit de mettre à jour la SKILL.md pour les remplacer. 🔄 - -⭐ **Mettez une étoile au dépôt et suivez** pour rester informé des nouveaux outils, des améliorations de flux et des mises à jour d'orchestration. 🚀 - -## Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Recherche │ │ -│ │ │ │ -│ │ SearXNG │ moteurs de recherche → URLs │ -│ │ (Docker) │ résultats JSON, rapide │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ résultats prêts → naviguer │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Navigation │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ navigateur + REST│ │ -│ │ │ (Docker) │ JS, clic, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ si bloqué │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Chromium furtif │ │ -│ │ │ (npm) │ anti-bot, proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Comment ça fonctionne - -### Phase 1 — Recherche avec SearXNG - -Conteneur Docker sur `localhost:8080`. Métamoteur qui interroge Google, Wikipedia, Bing, DuckDuckGo et bien d'autres simultanément. Sortie JSON avec titres, extraits et URLs. - -**Exemple :** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -L'agent a maintenant une liste d'URLs à visiter et décide de manière autonome s'il doit les naviguer avec Camofox ou CloakBrowser en fonction du site. - -### Phase 2 — Navigation avec Camofox - -Conteneur Docker sur `localhost:9377`. Expose un navigateur Firefox complet via une API REST. L'agent peut créer des onglets, naviguer, cliquer, faire défiler, exécuter du JavaScript arbitraire et structurer des données. - -**Inclut :** Readability.js de Mozilla pour extraire des articles propres, supprimant la navigation, la barre latérale et les publicités (~70% d'économies de tokens). - -**Commandes principales :** - -```bash -# Créer un onglet et naviguer -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Lire un instantané (arbre d'accessibilité) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Exécuter du JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Phase 3 — Navigation avec CloakBrowser (quand Camofox ne suffit pas) - -Paquet npm basé sur Playwright + `cloakbrowser`. Lance un navigateur Chromium avec des empreintes numériques avancées pour contourner Cloudflare, Akamai, DataDome et autres systèmes anti-bot. Détection automatique des défis avec attente et nouvelle tentative. - -**Scripts disponibles :** - -- `cloak-fetch.mjs` — fetch universel avec détection de défi -- `cloak-script.mjs` — exécution de script Playwright personnalisé - -**Exemple :** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Pourquoi à la fois Camofox et CloakBrowser ? - -Parce que la vitesse et la furtivité sont un compromis, et l'outil approprié dépend du site. - -**Camofox — rapide, structuré, persistant.** -Camofox encapsule Camoufox (un fork de Firefox au niveau C++) dans une API REST avec un navigateur toujours chaud. Après un démarrage à froid de ~1-3s, chaque requête est quasi-instantanée. Ses instantanés d'accessibilité sont ~90% plus petits que le HTML brut, avec des références d'éléments stables (e1, e2, ...) pour une interaction fiable. Il gère ~90% des sites qui n'utilisent pas de protection anti-bot avancée : articles, documents, moteurs de recherche, pages web standard. - -**CloakBrowser — furtif, anti-bot, à la demande.** -CloakBrowser lance une nouvelle instance Chromium par requête (~1-3s de démarrage à chaque fois). Il utilise des empreintes numériques avancées, le support proxy, le geoip et la détection automatique des défis pour contourner Cloudflare, Akamai, DataDome, Imperva, PerimeterX et DDoS-Guard. C'est le dernier recours pour les ~10% de sites qui bloquent Camofox. - -**Chiffres réels :** - -| Outil | Cloudflare standard | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (moteur Camofox) | jusqu'à **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** applique **58 correctifs au niveau du code source C++** et obtient un score **0.9 reCAPTCHA v3** (niveau humain, vérifié par le serveur), réussissant tous les principaux tests anti-bot, y compris Cloudflare Turnstile et FingerprintJS [²] -- **Camofox** démarrage à froid : **~1-3s** (une fois, puis ~0ms par requête via API REST chaude) [³] -- **Playwright/Chromium** démarrage à froid : **~0.5-6s** (chaque lancement, varie selon l'environnement) [⁴] - -Camofox gère la voie rapide. CloakBrowser gère les cas extrêmes. Ensemble, ils couvrent tout le web sans lacunes. L'agent décide lequel utiliser. - -### Sources - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Installation - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Montrez ce README à votre agent IA pour une installation complète adaptée à votre environnement et votre plateforme. - -**Aperçu des services :** - -| Service | Comment | Référence | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (inclus) | `scripts/cloak/cloak-fetch.mjs` | - -**Pour l'agent IA — lisez ces fichiers :** - -| Fichier | Ce qu'il contient | -|---|---| -| `SKILL.md` | Skill complète : commandes, escalade, dépannage | -| `scripts/cloak/cloak-fetch.mjs` | Utilisation de la CLI CloakBrowser et toutes les options | -| `scripts/setup-dependencies.sh` | Dépendances système | -| `scripts/check-browser-search.sh` | Vérification post-installation | -| `docker/setup.md` | Conseils de configuration Docker | - -**Remarque :** `SKILL.md` est écrite pour la syntaxe **OpenCode** (`exec`, `curl`). Si votre agent utilise un format différent (Claude Code, Cursor, etc.), lisez-la et convertissez les commandes dans la syntaxe de votre agent avant d'utiliser la skill. - -## Variables d'environnement - -| Variable | Requise pour | Défaut | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup dans Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Point d'arrêt stop de Camofox | — | - -## Ce que cette skill NE fait PAS - -- **Réseaux sociaux.** Instagram, Facebook, TikTok, LinkedIn et Twitter/X nécessitent une connexion. `browser-search` ne tente pas de les naviguer. -- **Télécharger des fichiers.** Il est en lecture seule (sauf captures d'écran explicites). -- **Contourner les paywalls.** Ne contourne pas les systèmes de paiement ou de connexion. - -## Participer - -browser-search est open source et gratuit. Si vous le trouvez utile : - -- ⭐ **Mettez une étoile au dépôt** — aide d'autres à le découvrir -- 🐛 **Ouvrez une issue** — signalez des bugs ou suggérez des fonctionnalités -- 🔀 **Soumettez une PR** — corrigez, améliorez, étendez -- 💬 **Partagez-le** — avec votre équipe, sur Reddit, Twitter, Discord -- 🧠 **Adaptez-le** — fork, ajustez le SKILL.md, faites-le vôtre - -Chaque contribution, aussi petite soit-elle, rend ce projet meilleur. - -## Licence - -MIT diff --git a/browser-search/i18n/README.it.md b/browser-search/i18n/README.it.md deleted file mode 100644 index 42afb50..0000000 --- a/browser-search/i18n/README.it.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Una skill per agenti AI.** OpenCode, Claude Code, Cursor, OpenClaw e oltre. Cerca sul web con SearXNG, naviga con Camofox, bypassa le protezioni con CloakBrowser. Tutto self-hosted, gratuito, illimitato. - -## Perché esiste - -browser-search è una SKILL — un insieme di istruzioni per agenti AI come OpenCode, Claude Code, Cursor, OpenClaw e altri. Insegna al tuo agente come cercare e navigare sul web usando tre strumenti open source orchestrati. - -Il problema? Il web è ostile all'automazione. Cloudflare, Akamai, DataDome e altri sistemi anti-bot bloccano le richieste semplici. I siti moderni usano JavaScript pesante, caricamento lazy e rendering lato client. Una singola soluzione non basta. - -`browser-search` orchestra **tre strumenti open source** in un unico sistema di ricerca e navigazione progettato per agenti AI. Ogni strumento ha il suo ruolo, orchestrato dalla skill con logica di escalation, selezione automatica e integrazione pronta all'uso: - -1. **[SearXNG](https://github.com/searxng/searxng)** — metamotore di ricerca per la fase di ricerca (multi-fonte, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — browser navigabile via REST API per siti standard -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — browser stealth per siti protetti anti-bot - -Il flusso tipico: l'agente prima cerca con SearXNG, poi naviga i risultati con Camofox (o CloakBrowser se il sito è protetto). - -## Benefici - -- **100% gratuito, self-hosted, illimitato.** Nessuna chiave API da comprare, nessun abbonamento, nessun limite di velocità. Tutto gira sulla tua macchina, Docker e npm. Utilizzo illimitato, costo zero. - -- **Leggero, funziona ovunque.** Costruito e testato su un Raspberry Pi — se funziona lì, funziona ovunque. Consumo minimo di risorse, nessuna infrastruttura pesante necessaria, funziona 24/7 su hardware a basso consumo. - -- **Ricerca + navigazione in un unico kit.** Nessuna integrazione manuale necessaria. Ricerca e navigazione sono due fasi distinte, entrambe coperte. - -- **Escalation automatica della navigazione.** Se Camofox viene bloccato da Cloudflare/Akamai, l'agente passa automaticamente a CloakBrowser. - -- **Prestazioni intelligenti.** SearXNG per la fase di ricerca (millisecondi). Camofox e CloakBrowser vengono usati solo per navigare i siti che ne hanno effettivamente bisogno. - -- **Scelta automatica dell'agente.** L'agente AI decide quale strumento usare: SearXNG per la ricerca iniziale, Camofox per la navigazione, CloakBrowser se il sito è protetto. Zero intervento umano. - -- **Modalità Deep Research.** La skill istruisce l'agente ad andare oltre le risposte superficiali: esplorare più angolazioni, verificare le fonti in modo incrociato, coprire ogni aspetto e mai tagliare gli angoli. - -- **Completamente personalizzabile.** La SKILL.md è testo semplice. Puoi modificare le regole principali, aggiungere le tue, rimuovere ciò che non ti serve. Adattala al tuo flusso di lavoro, al tuo team, ai tuoi standard. - -- **Stealth nativo.** CloakBrowser rileva automaticamente le sfide di Cloudflare, Akamai, DataDome, Imperva, PerimeterX e DDoS-Guard, e attende che si risolvano prima di estrarre il contenuto. - -- **Funziona con qualsiasi agente.** La SKILL.md è scritta per OpenCode, ma la logica è identica per qualsiasi agente AI. Stesso README, stesso package.json, tutto funziona ovunque. Chiedi semplicemente al tuo agente di convertire la skill per il suo ambiente. - -## 🏆 Stato dell'arte - -Questi tre strumenti sono stati scelti perché rappresentano al momento lo stato dell'arte di quanto disponibile sul mercato. Una skill come questa è pensata per evolversi: quando usciranno strumenti migliori, basterà aggiornare qualche riga nella SKILL.md per sostituirli. 🔄 - -⭐ **Metti una stella al repo e seguici** per restare sempre aggiornato su nuovi strumenti, miglioramenti del flusso e aggiornamenti dell'orchestrazione. 🚀 - -## Architettura - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Ricerca │ │ -│ │ │ │ -│ │ SearXNG │ motori di ricerca → URL │ -│ │ (Docker) │ risultati JSON, veloci │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ risultati pronti → navigare │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Navigazione │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ browser + REST │ │ -│ │ │ (Docker) │ JS, click, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ se bloccato │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Chromium stealth │ │ -│ │ │ (npm) │ anti-bot, proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Come funziona - -### Fase 1 — Ricerca con SearXNG - -Container Docker su `localhost:8080`. Metamotore che interroga Google, Wikipedia, Bing, DuckDuckGo e molti altri simultaneamente. Output JSON con titoli, snippet e URL. - -**Esempio:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -L'agente ora ha un elenco di URL da visitare e decide autonomamente se navigarli con Camofox o CloakBrowser in base al sito. - -### Fase 2 — Navigazione con Camofox - -Container Docker su `localhost:9377`. Espone un browser Firefox completo tramite API REST. L'agente può creare schede, navigare, cliccare, scorrere, eseguire JavaScript arbitrario e strutturare dati. - -**Include:** Readability.js di Mozilla per estrarre articoli puliti, rimuovendo navigazione, barra laterale e pubblicità (~70% di risparmio token). - -**Comandi principali:** - -```bash -# Creare scheda e navigare -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Leggere snapshot (albero di accessibilità) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Eseguire JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Fase 3 — Navigazione con CloakBrowser (quando Camofox non basta) - -Pacchetto npm basato su Playwright + `cloakbrowser`. Avvia un browser Chromium con impronta digitale avanzata per bypassare Cloudflare, Akamai, DataDome e altri sistemi anti-bot. Rilevamento automatico delle sfide con attesa e riprova. - -**Script disponibili:** - -- `cloak-fetch.mjs` — fetch universale con rilevamento sfide -- `cloak-script.mjs` — esecuzione script Playwright personalizzato - -**Esempio:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Perché sia Camofox che CloakBrowser? - -Perché velocità e stealth sono un compromesso, e lo strumento giusto dipende dal sito. - -**Camofox — veloce, strutturato, persistente.** -Camofox avvolge Camoufox (un fork di Firefox a livello C++) in una API REST con un browser sempre caldo. Dopo un avvio a freddo di ~1-3s, ogni richiesta è quasi istantanea. I suoi snapshot di accessibilità sono ~90% più piccoli dell'HTML grezzo, con riferimenti a elementi stabili (e1, e2, ...) per un'interazione affidabile. Gestisce ~90% dei siti che non usano protezione anti-bot avanzata: articoli, documenti, motori di ricerca, pagine web standard. - -**CloakBrowser — stealth, anti-bot, on-demand.** -CloakBrowser avvia una nuova istanza Chromium per richiesta (~1-3s di avvio ogni volta). Usa impronte digitali avanzate, supporto proxy, geoip e rilevamento automatico delle sfide per bypassare Cloudflare, Akamai, DataDome, Imperva, PerimeterX e DDoS-Guard. È l'ultima risorsa per il ~10% dei siti che bloccano Camofox. - -**Numeri reali:** - -| Strumento | Cloudflare standard | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (motore Camofox) | fino a **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** applica **58 patch a livello di codice sorgente C++** e ottiene **0.9 reCAPTCHA v3** (livello umano, verificato dal server), superando tutti i principali test anti-bot inclusi Cloudflare Turnstile e FingerprintJS [²] -- **Camofox** avvio a freddo: **~1-3s** (una tantum, poi ~0ms per richiesta via API REST calda) [³] -- **Playwright/Chromium** avvio a freddo: **~0.5-6s** (ogni avvio, varia in base all'ambiente) [⁴] - -Camofox gestisce il percorso veloce. CloakBrowser gestisce i casi limite. Insieme coprono l'intero web senza lacune. L'agente decide quale usare. - -### Fonti - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Installazione - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Mostra questo README al tuo agente AI per un'installazione completa adattata al tuo ambiente e piattaforma. - -**Panoramica servizi:** - -| Servizio | Come | Riferimento | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (incluso) | `scripts/cloak/cloak-fetch.mjs` | - -**Per l'agente AI — leggi questi file:** - -| File | Cosa contiene | -|---|---| -| `SKILL.md` | Skill completa: comandi, escalation, risoluzione problemi | -| `scripts/cloak/cloak-fetch.mjs` | Utilizzo CLI CloakBrowser e tutte le opzioni | -| `scripts/setup-dependencies.sh` | Dipendenze di sistema | -| `scripts/check-browser-search.sh` | Verifica post-installazione | -| `docker/setup.md` | Suggerimenti configurazione Docker | - -**Nota:** `SKILL.md` è scritta per la sintassi di **OpenCode** (`exec`, `curl`). Se il tuo agente usa un formato diverso (Claude Code, Cursor, ecc.), leggila e converti i comandi nella sintassi del tuo agente prima di usare la skill. - -## Variabili d'ambiente - -| Variabile | Richiesta per | Default | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup in Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Endpoint stop di Camofox | — | - -## Cosa NON fa questa skill - -- **Social media.** Instagram, Facebook, TikTok, LinkedIn e Twitter/X richiedono l'accesso. `browser-search` non tenta di navigarli. -- **Scaricare file.** È in sola lettura (tranne screenshot espliciti). -- **Bypassare paywall.** Non aggira sistemi di pagamento o login. - -## Partecipa - -browser-search è open source e gratuito. Se lo trovi utile: - -- ⭐ **Metti una stella sul repo** — aiuta altri a scoprirlo -- 🐛 **Apri un issue** — segnala bug o suggerisci funzionalità -- 🔀 **Invia una PR** — correggi, migliora, estendi -- 💬 **Condividilo** — con il tuo team, su Reddit, Twitter, Discord -- 🧠 **Adattalo** — fanne un fork, modifica SKILL.md, rendilo tuo - -Ogni contributo, per quanto piccolo, lo rende migliore. - -## Licenza - -MIT diff --git a/browser-search/i18n/README.ja.md b/browser-search/i18n/README.ja.md deleted file mode 100644 index c30a821..0000000 --- a/browser-search/i18n/README.ja.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **AIエージェントのためのスキル。** OpenCode、Claude Code、Cursor、OpenClawなど。SearXNGでウェブ検索、Camofoxでブラウジング、CloakBrowserで保護をバイパス。すべてセルフホスト、無料、無制限。 - -## なぜ存在するのか - -browser-searchはスキルです — OpenCode、Claude Code、Cursor、OpenClawなどのAIエージェントのための命令セットです。3つのオーケストレーションされたオープンソースツールを使って、エージェントがウェブを検索・ブラウジングする方法を教えます。 - -問題は何か？ウェブは自動化に敵対的です。Cloudflare、Akamai、DataDomeなどのアンチボットシステムは単純なリクエストをブロックします。最新のサイトは重いJavaScript、遅延読み込み、クライアントサイドレンダリングを使用しています。単一の解決策では不十分です。 - -`browser-search`は**3つのオープンソースツール**を、AIエージェント向けに設計された単一の検索・ブラウジングシステムにオーケストレーションします。各ツールには役割があり、エスカレーションロジック、自動選択、すぐに使える統合によってスキルがオーケストレーションします： - -1. **[SearXNG](https://github.com/searxng/searxng)** — 検索フェーズのためのメタサーチエンジン（マルチソース、JSON） -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — 標準サイト向けのREST API経由で操作可能なブラウザ -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — アンチボット保護サイト向けのステルスブラウザ - -典型的な流れ：エージェントは最初にSearXNGで検索し、次にCamofox（またはサイトが保護されている場合はCloakBrowser）で結果をブラウジングします。 - -## 利点 - -- **100%無料、セルフホスト、無制限。** APIキーの購入不要、サブスクリプション不要、レート制限なし。すべてあなたのマシン、Docker、npmで動作します。無制限の使用、ゼロコスト。 - -- **軽量、どこでも実行可能。** Raspberry Piで構築・テスト済み — そこで動作すれば、どこでも動作します。最小限のリソース消費、大規模なインフラストラクチャ不要、低電力ハードウェアで24時間365日稼働。 - -- **検索＋ブラウジングがワンキットに。** 手動統合は不要。検索とブラウジングは2つの異なるフェーズであり、両方ともカバーされています。 - -- **自動ナビゲーションエスカレーション。** CamofoxがCloudflare/Akamaiにブロックされた場合、エージェントは自動的にCloakBrowserに切り替えます。 - -- **スマートパフォーマンス。** 検索フェーズにはSearXNG（ミリ秒）。CamofoxとCloakBrowserは実際に必要なサイトのブラウジングにのみ使用されます。 - -- **自動エージェント選択。** AIエージェントが使用するツールを決定します：初期検索にSearXNG、ブラウジングにCamofox、保護されたサイトにCloakBrowser。人間の介入はゼロ。 - -- **ディープリサーチモード。** スキルはエージェントに表面的な回答を超えるよう指示します：複数の角度を探求し、ソースを相互検証し、あらゆる側面をカバーし、決して手を抜かない。 - -- **完全にカスタマイズ可能。** SKILL.mdはプレーンテキストです。コアルールの編集、独自ルールの追加、不要なものの削除が可能。自分のワークフロー、チーム、標準に合わせて調整できます。 - -- **ネイティブステルス。** CloakBrowserはCloudflare、Akamai、DataDome、Imperva、PerimeterX、DDoS-Guardのチャレンジを自動検出し、それらが解決されるのを待ってからコンテンツを抽出します。 - -- **任意のエージェントで動作。** SKILL.mdはOpenCode用に書かれていますが、ロジックはどのAIエージェントでも同じです。同じREADME、同じpackage.json、すべてがどこでも機能します。エージェントに、その環境用にスキルを変換するように依頼するだけです。 - -## 🏆 最先端技術 - -これら3つのツールは、現在市場で入手可能な最先端を代表するものとして選ばれました。このようなスキルは進化するように設計されています：より良いツールが登場したら、SKILL.mdの数行を更新するだけで交換できます。🔄 - -⭐ **リポジトリにスターを付けてフォロー**すると、新しいツール、フローの改善、オーケストレーションの更新について最新情報を入手できます。🚀 - -## アーキテクチャ - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ 検索 │ │ -│ │ │ │ -│ │ SearXNG │ 検索エンジン → URL │ -│ │ (Docker) │ JSON結果、高速 │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ 結果準備完了 → ブラウジングへ │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ ブラウジング │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ ブラウザ+REST │ │ -│ │ │ (Docker) │ JS、クリック、評価│ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ ブロックされた場合 │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ ステルスChromium │ │ -│ │ │ (npm) │ アンチボット、プロキシ│ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## 仕組み - -### フェーズ1 — SearXNGで検索 - -`localhost:8080`でDockerコンテナ稼働。Google、Wikipedia、Bing、DuckDuckGoなどを同時にクエリするメタサーチエンジン。タイトル、スニペット、URLを含むJSON出力。 - -**例：** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -エージェントは訪問するURLのリストを取得し、サイトに応じてCamofoxとCloakBrowserのどちらでブラウジングするかを自律的に決定します。 - -### フェーズ2 — Camofoxでブラウジング - -`localhost:9377`でDockerコンテナ稼働。REST APIを通じて完全なFirefoxブラウザを公開。エージェントはタブの作成、ナビゲーション、クリック、スクロール、任意のJavaScriptの実行、データの構造化が可能。 - -**含まれるもの：** MozillaのReadability.jsによるクリーンな記事抽出、ナビ、サイドバー、広告を除去（約70%のトークン節約）。 - -**主要コマンド：** - -```bash -# タブを作成してナビゲート -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# スナップショットを読み取り（アクセシビリティツリー） -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# JavaScriptを実行 -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### フェーズ3 — CloakBrowserでブラウジング（Camofoxが不十分な場合） - -Playwright + `cloakbrowser`ベースのnpmパッケージ。高度なフィンガープリンティングを備えたChromiumブラウザを起動し、Cloudflare、Akamai、DataDomeなどのアンチボットシステムをバイパス。待機とリトライを備えた自動チャレンジ検出。 - -**利用可能なスクリプト：** - -- `cloak-fetch.mjs` — チャレンジ検出付きユニバーサルフェッチ -- `cloak-script.mjs` — カスタムPlaywrightスクリプト実行 - -**例：** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## なぜCamofoxとCloakBrowserの両方なのか？ - -スピードとステルスはトレードオフの関係であり、適切なツールはサイトによって異なるからです。 - -**Camofox — 高速、構造化、永続的。** -CamofoxはCamoufox（C++レベルのFirefoxフォーク）をREST APIでラップし、常時ウォームなブラウザを提供します。約1〜3秒のコールドスタート後、すべてのリクエストはほぼ瞬時です。アクセシビリティスナップショットは生のHTMLより約90%小さく、安定した要素参照（e1、e2、...）により信頼性の高いインタラクションが可能です。高度なアンチボット保護を使用しない約90%のサイト（記事、ドキュメント、検索エンジン、標準的なWebページ）を処理します。 - -**CloakBrowser — ステルス、アンチボット、オンデマンド。** -CloakBrowserはリクエストごとに新しいChromiumインスタンスを起動します（毎回約1〜3秒の起動時間）。高度なフィンガープリンティング、プロキシサポート、地理位置情報、自動チャレンジ検出を使用して、Cloudflare、Akamai、DataDome、Imperva、PerimeterX、DDoS-Guardをバイパスします。Camofoxをブロックする約10%のサイトに対する最後の手段です。 - -**実世界の数値：** - -| ツール | Cloudflare標準 | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox**（Camofoxエンジン） | 最大 **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser**は**58のC++ソースレベルパッチ**を適用し、**0.9 reCAPTCHA v3**（人間レベル、サーバー検証済み）をスコアリングし、Cloudflare TurnstileやFingerprintJSを含むすべての主要なアンチボットテストに合格 [²] -- **Camofox**のコールドスタート：**約1〜3秒**（一度だけ、その後はウォームREST API経由でリクエストあたり約0ms）[³] -- **Playwright/Chromium**のコールドスタート：**約0.5〜6秒**（起動ごと、環境によって異なる）[⁴] - -Camofoxが高速パスを処理し、CloakBrowserがエッジケースを処理します。両者でウェブ全体を隙間なくカバーします。エージェントがどちらを使用するかを決定します。 - -### ソース - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## インストール - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -このREADMEをAIエージェントに渡せば、あなたの環境とプラットフォームに合わせた完全なインストールを行います。 - -**サービス概要：** - -| サービス | 方法 | 参照 | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm（含む） | `scripts/cloak/cloak-fetch.mjs` | - -**AIエージェント向け — 以下のファイルを読んでください：** - -| ファイル | 内容 | -|---|---| -| `SKILL.md` | 完全なスキル：コマンド、エスカレーション、トラブルシューティング | -| `scripts/cloak/cloak-fetch.mjs` | CloakBrowser CLIの使用法と全オプション | -| `scripts/setup-dependencies.sh` | システム依存関係 | -| `scripts/check-browser-search.sh` | インストール後検証 | -| `docker/setup.md` | Dockerセットアップのヒント | - -**注意：** `SKILL.md`は**OpenCode**の構文（`exec`、`curl`）で書かれています。エージェントが異なる形式（Claude Code、Cursorなど）を使用する場合は、これを読んでスキルを使用する前にコマンドをエージェントの構文に変換してください。 - -## 環境変数 - -| 変数 | 必要な場面 | デフォルト | -|---|---|---| -| `CAMOFOX_API_KEY` | Camofoxのevaluate、session、cleanup | — | -| `CAMOFOX_ADMIN_KEY` | Camofoxのstopエンドポイント | — | - -## このスキルがやらないこと - -- **ソーシャルメディア。** Instagram、Facebook、TikTok、LinkedIn、Twitter/Xはログインが必要です。`browser-search`はそれらのブラウジングを試みません。 -- **ファイルのダウンロード。** 読み取り専用です（明示的なスクリーンショットを除く）。 -- **ペイウォールのバイパス。** 支払いやログインシステムを回避しません。 - -## 参加する - -browser-searchはオープンソースで無料です。役に立ったなら： - -- ⭐ **リポジトリにスターを** — 他の人が見つけやすくなります -- 🐛 **Issueを開く** — バグ報告や機能提案 -- 🔀 **PRを送信する** — 修正、改善、拡張 -- 💬 **共有する** — チーム、Reddit、Twitter、Discordで -- 🧠 **適応させる** — フォークしてSKILL.mdを調整し、自分だけのものに - -どんなに小さな貢献でも、これを作り上げていきます。 - -## ライセンス - -MIT diff --git a/browser-search/i18n/README.ko.md b/browser-search/i18n/README.ko.md deleted file mode 100644 index 05f0513..0000000 --- a/browser-search/i18n/README.ko.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **AI 에이전트를 위한 스킬.** OpenCode, Claude Code, Cursor, OpenClaw 등. SearXNG로 웹 검색, Camofox로 브라우징, CloakBrowser로 보호 우회. 모두 셀프호스팅, 무료, 무제한. - -## 왜 필요한가 - -browser-search는 스킬입니다 — OpenCode, Claude Code, Cursor, OpenClaw 등과 같은 AI 에이전트를 위한 명령어 세트입니다. 세 가지 오케스트레이션된 오픈소스 도구를 사용하여 에이전트가 웹을 검색하고 브라우징하는 방법을 가르칩니다. - -문제는 무엇인가? 웹은 자동화에 적대적입니다. Cloudflare, Akamai, DataDome 및 기타 안티봇 시스템은 단순한 요청을 차단합니다. 최신 사이트는 무거운 JavaScript, 지연 로딩 및 클라이언트 측 렌더링을 사용합니다. 단일 솔루션만으로는 충분하지 않습니다. - -`browser-search`는 **세 가지 오픈소스 도구**를 AI 에이전트를 위해 설계된 단일 검색 및 브라우징 시스템으로 오케스트레이션합니다. 각 도구에는 역할이 있으며, 에스컬레이션 로직, 자동 선택 및 즉시 사용 가능한 통합을 통해 스킬이 오케스트레이션합니다: - -1. **[SearXNG](https://github.com/searxng/searxng)** — 검색 단계를 위한 메타검색 엔진 (다중 소스, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — 표준 사이트를 위한 REST API로 탐색 가능한 브라우저 -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — 안티봇 보호 사이트를 위한 스텔스 브라우저 - -일반적인 흐름: 에이전트가 먼저 SearXNG로 검색한 다음, Camofox(또는 사이트가 보호된 경우 CloakBrowser)로 결과를 브라우징합니다. - -## 이점 - -- **100% 무료, 셀프호스팅, 무제한.** API 키 구매 불필요, 구독 불필요, 속도 제한 없음. 모든 것이 여러분의 머신, Docker 및 npm에서 실행됩니다. 무제한 사용, 비용 제로. - -- **가벼움, 어디서나 실행.** Raspberry Pi에서 구축 및 테스트 완료 — 거기서 실행되면 어디서나 실행됩니다. 최소한의 리소스 소비, 무거운 인프라 불필요, 저전력 하드웨어에서 24/7 실행. - -- **검색 + 브라우징이 하나의 키트에.** 수동 통합 불필요. 검색과 브라우징은 두 가지 별개 단계이며, 둘 다 다룹니다. - -- **자동 내비게이션 에스컬레이션.** Camofox가 Cloudflare/Akamai에 차단되면 에이전트가 자동으로 CloakBrowser로 전환합니다. - -- **스마트 성능.** 검색 단계에는 SearXNG(밀리초). Camofox와 CloakBrowser는 실제로 필요한 사이트를 브라우징하는 데만 사용됩니다. - -- **자동 에이전트 선택.** AI 에이전트가 사용할 도구를 결정합니다: 초기 검색에 SearXNG, 브라우징에 Camofox, 보호된 사이트에 CloakBrowser. 인간의 개입 제로. - -- **딥 리서치 모드.** 스킬은 에이전트가 표면적인 답변을 넘어서도록 지시합니다: 여러 각도 탐색, 소스 교차 검증, 모든 측면 커버, 절대 지름길을 택하지 않음. - -- **완전히 사용자 정의 가능.** SKILL.md는 일반 텍스트입니다. 핵심 규칙을 편집하고, 자신의 규칙을 추가하고, 필요 없는 것을 제거할 수 있습니다. 워크플로우, 팀, 표준에 맞게 조정하세요. - -- **네이티브 스텔스.** CloakBrowser는 Cloudflare, Akamai, DataDome, Imperva, PerimeterX 및 DDoS-Guard 챌린지를 자동 감지하고, 콘텐츠를 추출하기 전에 해결될 때까지 기다립니다. - -- **모든 에이전트에서 작동.** SKILL.md는 OpenCode용으로 작성되었지만 로직은 모든 AI 에이전트에서 동일합니다. 동일한 README, 동일한 package.json, 모든 것이 어디서나 작동합니다. 에이전트에게 해당 환경에 맞게 스킬을 변환하도록 요청하세요. - -## 🏆 최신 기술 - -이 세 가지 도구는 현재 시장에서 사용 가능한 최신 기술을 대표하기 때문에 선택되었습니다. 이러한 스킬은 진화하도록 설계되었습니다: 더 나은 도구가 등장하면 SKILL.md의 몇 줄만 업데이트하면 교체할 수 있습니다. 🔄 - -⭐ **저장소에 스타를 달고 팔로우**하여 새로운 도구, 흐름 개선 및 오케스트레이션 업데이트에 대한 최신 정보를 받아보세요. 🚀 - -## 아키텍처 - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ 검색 │ │ -│ │ │ │ -│ │ SearXNG │ 검색 엔진 → URL │ -│ │ (Docker) │ JSON 결과, 빠름 │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ 결과 준비 → 브라우징 시작 │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ 브라우징 │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ 브라우저 + REST │ │ -│ │ │ (Docker) │ JS, 클릭, 평가 │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ 차단된 경우 │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ 스텔스 Chromium │ │ -│ │ │ (npm) │ 안티봇, 프록시 │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## 작동 방식 - -### 1단계 — SearXNG로 검색 - -`localhost:8080`에서 Docker 컨테이너 실행. Google, Wikipedia, Bing, DuckDuckGo 등을 동시에 쿼리하는 메타검색 엔진. 제목, 스니펫 및 URL이 포함된 JSON 출력. - -**예시:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -이제 에이전트는 방문할 URL 목록을 가지고 사이트에 따라 Camofox 또는 CloakBrowser로 브라우징할지 자율적으로 결정합니다. - -### 2단계 — Camofox로 브라우징 - -`localhost:9377`에서 Docker 컨테이너 실행. REST API를 통해 완전한 Firefox 브라우저를 노출합니다. 에이전트는 탭 생성, 탐색, 클릭, 스크롤, 임의 JavaScript 실행 및 데이터 구조화가 가능합니다. - -**포함:** Mozilla의 Readability.js로 깔끔한 기사 추출, 네비게이션, 사이드바, 광고 제거 (약 70% 토큰 절약). - -**주요 명령어:** - -```bash -# 탭 생성 및 탐색 -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# 스냅샷 읽기 (접근성 트리) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# JavaScript 실행 -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### 3단계 — CloakBrowser로 브라우징 (Camofox가 충분하지 않을 때) - -Playwright + `cloakbrowser` 기반 npm 패키지. 고급 핑거프린팅을 갖춘 Chromium 브라우저를 실행하여 Cloudflare, Akamai, DataDome 및 기타 안티봇 시스템을 우회합니다. 대기 및 재시도 기능을 갖춘 자동 챌린지 감지. - -**사용 가능한 스크립트:** - -- `cloak-fetch.mjs` — 챌린지 감지 기능이 있는 범용 페치 -- `cloak-script.mjs` — 사용자 정의 Playwright 스크립트 실행 - -**예시:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## 왜 Camofox와 CloakBrowser 둘 다인가? - -속도와 스텔스는 트레이드오프이며, 올바른 도구는 사이트에 따라 다르기 때문입니다. - -**Camofox — 빠름, 구조화됨, 지속적.** -Camofox는 Camoufox(C++ 수준의 Firefox 포크)를 REST API로 래핑하여 항상 웜 상태인 브라우저를 제공합니다. 약 1~3초의 콜드 스타트 후 모든 요청이 거의 즉각적입니다. 접근성 스냅샷은 원시 HTML보다 약 90% 작으며, 안정적인 요소 참조(e1, e2, ...)로 안정적인 상호작용이 가능합니다. 고급 안티봇 보호를 사용하지 않는 약 90%의 사이트(기사, 문서, 검색 엔진, 표준 웹 페이지)를 처리합니다. - -**CloakBrowser — 스텔스, 안티봇, 온디맨드.** -CloakBrowser는 요청당 새 Chromium 인스턴스를 실행합니다(매번 약 1~3초 시작). 고급 핑거프린팅, 프록시 지원, 지리적 위치 및 자동 챌린지 감지를 사용하여 Cloudflare, Akamai, DataDome, Imperva, PerimeterX 및 DDoS-Guard를 우회합니다. Camofox를 차단하는 약 10%의 사이트에 대한 최후의 수단입니다. - -**실제 수치:** - -| 도구 | Cloudflare 표준 | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox**(Camofox 엔진) | 최대 **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser**는 **58개의 C++ 소스 수준 패치**를 적용하고 **0.9 reCAPTCHA v3**(인간 수준, 서버 검증됨)를 점수화하여 Cloudflare Turnstile 및 FingerprintJS를 포함한 모든 주요 안티봇 테스트 통과 [²] -- **Camofox** 콜드 스타트: **약 1~3초**(한 번, 그 후 웜 REST API를 통해 요청당 약 0ms) [³] -- **Playwright/Chromium** 콜드 스타트: **약 0.5~6초**(실행할 때마다, 환경에 따라 다름) [⁴] - -Camofox는 빠른 경로를 처리합니다. CloakBrowser는 엣지 케이스를 처리합니다. 함께 웹 전체를 간격 없이 커버합니다. 에이전트가 사용할 도구를 결정합니다. - -### 출처 - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## 설치 - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -이 README를 AI 에이전트에 보여주면 환경과 플랫폼에 맞게 완전히 설치합니다. - -**서비스 개요:** - -| 서비스 | 방법 | 참조 | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (포함) | `scripts/cloak/cloak-fetch.mjs` | - -**AI 에이전트용 — 다음 파일을 읽으세요:** - -| 파일 | 내용 | -|---|---| -| `SKILL.md` | 전체 스킬: 명령어, 에스컬레이션, 문제 해결 | -| `scripts/cloak/cloak-fetch.mjs` | CloakBrowser CLI 사용법 및 모든 옵션 | -| `scripts/setup-dependencies.sh` | 시스템 종속성 | -| `scripts/check-browser-search.sh` | 설치 후 검증 | -| `docker/setup.md` | Docker 설정 팁 | - -**참고:** `SKILL.md`는 **OpenCode** 구문(`exec`, `curl`)으로 작성되었습니다. 에이전트가 다른 형식(Claude Code, Cursor 등)을 사용하는 경우, 이를 읽고 스킬을 사용하기 전에 명령어를 에이전트 구문으로 변환하세요. - -## 환경 변수 - -| 변수 | 필요한 경우 | 기본값 | -|---|---|---| -| `CAMOFOX_API_KEY` | Camofox의 evaluate, session, cleanup | — | -| `CAMOFOX_ADMIN_KEY` | Camofox stop 엔드포인트 | — | - -## 이 스킬이 하지 않는 것 - -- **소셜 미디어.** Instagram, Facebook, TikTok, LinkedIn 및 Twitter/X는 로그인이 필요합니다. `browser-search`는 이를 브라우징하지 않습니다. -- **파일 다운로드.** 읽기 전용입니다(명시적 스크린샷 제외). -- **페이월 우회.** 결제 또는 로그인 시스템을 회피하지 않습니다. - -## 참여하기 - -browser-search는 오픈소스이며 무료입니다. 유용하다고 생각하신다면: - -- ⭐ **저장소에 스타를** — 다른 사람들이 발견하는 데 도움이 됩니다 -- 🐛 **Issue 열기** — 버그 신고 또는 기능 제안 -- 🔀 **PR 제출하기** — 수정, 개선, 확장 -- 💬 **공유하기** — 팀, Reddit, Twitter, Discord에서 -- 🧠 **적응시키기** — 포크하고 SKILL.md를 조정하여 나만의 것으로 만드세요 - -작은 기여라도 모두 이 프로젝트를 더 좋게 만듭니다. - -## 라이선스 - -MIT diff --git a/browser-search/i18n/README.pt-BR.md b/browser-search/i18n/README.pt-BR.md deleted file mode 100644 index 7cceeae..0000000 --- a/browser-search/i18n/README.pt-BR.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Uma skill para agentes de IA.** OpenCode, Claude Code, Cursor, OpenClaw e muito mais. Pesquise na web com SearXNG, navegue com Camofox, burle proteções com CloakBrowser. Tudo auto-hospedado, gratuito, ilimitado. - -## Por que existe - -browser-search é uma SKILL — um conjunto de instruções para agentes de IA como OpenCode, Claude Code, Cursor, OpenClaw e outros. Ela ensina seu agente como pesquisar e navegar na web usando três ferramentas open source orquestradas. - -O problema? A web é hostil à automação. Cloudflare, Akamai, DataDome e outros sistemas anti-bot bloqueiam requisições simples. Sites modernos usam JavaScript pesado, carregamento lazy e renderização do lado do cliente. Uma única solução não é suficiente. - -`browser-search` orquestra **três ferramentas open source** em um único sistema de pesquisa e navegação projetado para agentes de IA. Cada ferramenta tem seu papel, orquestrada pela skill com lógica de escalonamento, seleção automática e integração pronta para uso: - -1. **[SearXNG](https://github.com/searxng/searxng)** — metabuscador para a fase de pesquisa (multifonte, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — navegador acessível via API REST para sites padrão -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — navegador furtivo para sites protegidos contra bots - -O fluxo típico: o agente primeiro pesquisa com SearXNG, depois navega pelos resultados com Camofox (ou CloakBrowser se o site estiver protegido). - -## Benefícios - -- **100% gratuito, auto-hospedado, ilimitado.** Sem chaves de API para comprar, sem assinaturas, sem limites de taxa. Tudo roda na sua máquina, Docker e npm. Uso ilimitado, custo zero. - -- **Leve, funciona em qualquer lugar.** Construído e testado em um Raspberry Pi — se funciona lá, funciona em qualquer lugar. Consumo mínimo de recursos, sem necessidade de infraestrutura pesada, funciona 24/7 em hardware de baixo consumo. - -- **Pesquisa + navegação em um único kit.** Sem necessidade de integração manual. Pesquisa e navegação são duas fases distintas, ambas cobertas. - -- **Escalonamento automático de navegação.** Se o Camofox for bloqueado por Cloudflare/Akamai, o agente muda automaticamente para o CloakBrowser. - -- **Desempenho inteligente.** SearXNG para a fase de pesquisa (milissegundos). Camofox e CloakBrowser são usados apenas para navegar nos sites que realmente precisam. - -- **Escolha automática do agente.** O agente de IA decide qual ferramenta usar: SearXNG para pesquisa inicial, Camofox para navegação, CloakBrowser se o site estiver protegido. Intervenção humana zero. - -- **Modo de pesquisa aprofundada.** A skill instrui o agente a ir além de respostas superficiais: explorar múltiplos ângulos, verificar fontes de forma cruzada, cobrir todos os aspectos e nunca cortar caminhos. - -- **Totalmente personalizável.** A SKILL.md é texto simples. Você pode editar as regras principais, adicionar as suas, remover o que não precisa. Adapte ao seu fluxo de trabalho, sua equipe, seus padrões. - -- **Furtividade nativa.** CloakBrowser detecta automaticamente desafios do Cloudflare, Akamai, DataDome, Imperva, PerimeterX e DDoS-Guard, e aguarda sua resolução antes de extrair conteúdo. - -- **Funciona com qualquer agente.** A SKILL.md é escrita para OpenCode, mas a lógica é idêntica para qualquer agente de IA. Mesmo README, mesmo package.json, tudo funciona em qualquer lugar. Basta pedir ao seu agente para converter a skill para seu ambiente. - -## 🏆 Estado da arte - -Estas três ferramentas foram escolhidas porque representam o estado da arte atual disponível hoje. Uma skill como esta é projetada para evoluir: quando ferramentas melhores surgirem, basta atualizar a SKILL.md para substituí-las. 🔄 - -⭐ **Dê uma estrela no repositório e siga** para ficar atualizado sobre novas ferramentas, melhorias no fluxo e atualizações de orquestração. 🚀 - -## Arquitetura - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Pesquisa │ │ -│ │ │ │ -│ │ SearXNG │ mecanismos de busca → URLs │ -│ │ (Docker) │ resultados JSON, rápido │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ resultados prontos → navegar │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Navegação │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ navegador + REST │ │ -│ │ │ (Docker) │ JS, clique, eval │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ se bloqueado │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ Chromium furtivo │ │ -│ │ │ (npm) │ anti-bot, proxy │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Como funciona - -### Fase 1 — Pesquisa com SearXNG - -Container Docker em `localhost:8080`. Metabuscador que consulta Google, Wikipedia, Bing, DuckDuckGo e muitos outros simultaneamente. Saída JSON com títulos, trechos e URLs. - -**Exemplo:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -O agente agora tem uma lista de URLs para visitar e decide autonomamente se as navega com Camofox ou CloakBrowser com base no site. - -### Fase 2 — Navegação com Camofox - -Container Docker em `localhost:9377`. Expõe um navegador Firefox completo através de uma API REST. O agente pode criar abas, navegar, clicar, rolar, executar JavaScript arbitrário e estruturar dados. - -**Inclui:** Readability.js da Mozilla para extrair artigos limpos, removendo navegação, barra lateral e anúncios (~70% de economia de tokens). - -**Comandos principais:** - -```bash -# Criar aba e navegar -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Ler snapshot (árvore de acessibilidade) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Executar JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Fase 3 — Navegação com CloakBrowser (quando Camofox não é suficiente) - -Pacote npm baseado em Playwright + `cloakbrowser`. Inicia um navegador Chromium com impressão digital avançada para burlar Cloudflare, Akamai, DataDome e outros sistemas anti-bot. Detecção automática de desafios com espera e tentativa novamente. - -**Scripts disponíveis:** - -- `cloak-fetch.mjs` — fetch universal com detecção de desafios -- `cloak-script.mjs` — execução de script Playwright personalizado - -**Exemplo:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Por que tanto Camofox quanto CloakBrowser? - -Porque velocidade e furtividade são um tradeoff, e a ferramenta certa depende do site. - -**Camofox — rápido, estruturado, persistente.** -Camofox envolve o Camoufox (um fork do Firefox em nível C++) em uma API REST com um navegador sempre aquecido. Após uma inicialização a frio de ~1-3s, cada requisição é quase instantânea. Seus snapshots de acessibilidade são ~90% menores que HTML bruto, com referências de elemento estáveis (e1, e2, ...) para interação confiável. Ele lida com ~90% dos sites que não usam proteção anti-bot avançada: artigos, documentos, mecanismos de busca, páginas web padrão. - -**CloakBrowser — furtivo, anti-bot, sob demanda.** -CloakBrowser inicia uma nova instância do Chromium por requisição (~1-3s de inicialização cada vez). Usa impressão digital avançada, suporte a proxy, geoip e detecção automática de desafios para burlar Cloudflare, Akamai, DataDome, Imperva, PerimeterX e DDoS-Guard. É o último recurso para os ~10% dos sites que bloqueiam o Camofox. - -**Números do mundo real:** - -| Ferramenta | Cloudflare padrão | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (motor do Camofox) | até **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** aplica **58 patches em nível de código-fonte C++** e pontua **0.9 reCAPTCHA v3** (nível humano, verificado pelo servidor), passando em todos os principais testes anti-bot, incluindo Cloudflare Turnstile e FingerprintJS [²] -- **Camofox** inicialização a frio: **~1-3s** (uma vez, depois ~0ms por requisição via API REST aquecida) [³] -- **Playwright/Chromium** inicialização a frio: **~0.5-6s** (cada inicialização, varia conforme o ambiente) [⁴] - -Camofox lida com o caminho rápido. CloakBrowser lida com os casos extremos. Juntos, eles cobrem toda a web sem lacunas. O agente decide qual usar. - -### Fontes - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Instalação - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Mostre este README ao seu agente de IA para uma instalação completa adaptada ao seu ambiente e plataforma. - -**Visão geral dos serviços:** - -| Serviço | Como | Referência | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (incluído) | `scripts/cloak/cloak-fetch.mjs` | - -**Para o agente de IA — leia estes arquivos:** - -| Arquivo | O que contém | -|---|---| -| `SKILL.md` | Skill completa: comandos, escalonamento, solução de problemas | -| `scripts/cloak/cloak-fetch.mjs` | Uso da CLI do CloakBrowser e todas as opções | -| `scripts/setup-dependencies.sh` | Dependências do sistema | -| `scripts/check-browser-search.sh` | Verificação pós-instalação | -| `docker/setup.md` | Dicas de configuração Docker | - -**Nota:** `SKILL.md` está escrita para a sintaxe do **OpenCode** (`exec`, `curl`). Se seu agente usar um formato diferente (Claude Code, Cursor, etc.), leia-a e converta os comandos para a sintaxe do seu agente antes de usar a skill. - -## Variáveis de ambiente - -| Variável | Obrigatória para | Padrão | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup no Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Endpoint stop do Camofox | — | - -## O que esta skill NÃO faz - -- **Redes sociais.** Instagram, Facebook, TikTok, LinkedIn e Twitter/X exigem login. `browser-search` não tenta navegá-los. -- **Baixar arquivos.** É somente leitura (exceto capturas de tela explícitas). -- **Burlar paywalls.** Não contorna sistemas de pagamento ou login. - -## Participe - -browser-search é open source e gratuito. Se você achar útil: - -- ⭐ **Dê uma estrela no repositório** — ajuda outros a descobri-lo -- 🐛 **Abra uma issue** — reporte bugs ou sugira funcionalidades -- 🔀 **Envie um PR** — corrija, melhore, estenda -- 💬 **Compartilhe** — com sua equipe, no Reddit, Twitter, Discord -- 🧠 **Adapte-o** — faça um fork, ajuste a SKILL.md, torne-o seu - -Cada contribuição, por menor que seja, torna isso melhor. - -## Licença - -MIT diff --git a/browser-search/i18n/README.ru.md b/browser-search/i18n/README.ru.md deleted file mode 100644 index 0928426..0000000 --- a/browser-search/i18n/README.ru.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **Навык для ИИ-агентов.** OpenCode, Claude Code, Cursor, OpenClaw и другие. Ищите в интернете с SearXNG, просматривайте сайты с Camofox, обходите защиту с CloakBrowser. Всё самостоятельно размещённое, бесплатное, без ограничений. - -## Зачем это нужно - -browser-search — это НАВЫК — набор инструкций для ИИ-агентов, таких как OpenCode, Claude Code, Cursor, OpenClaw и других. Он учит вашего агента искать и просматривать веб-сайты, используя три оркестрированных инструмента с открытым исходным кодом. - -В чём проблема? Интернет враждебен к автоматизации. Cloudflare, Akamai, DataDome и другие антибот-системы блокируют простые запросы. Современные сайты используют тяжёлый JavaScript, ленивую загрузку и рендеринг на стороне клиента. Одного решения недостаточно. - -`browser-search` оркестрирует **три инструмента с открытым исходным кодом** в единую систему поиска и просмотра, разработанную для ИИ-агентов. Каждый инструмент имеет свою роль, оркестрируемую навыком с логикой эскалации, автоматическим выбором и готовой к использованию интеграцией: - -1. **[SearXNG](https://github.com/searxng/searxng)** — метапоисковая система для фазы поиска (мультиисточник, JSON) -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — браузер с доступом через REST API для стандартных сайтов -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — скрытый браузер для сайтов с антибот-защитой - -Типичный поток: агент сначала ищет с помощью SearXNG, затем просматривает результаты с помощью Camofox (или CloakBrowser, если сайт защищён). - -## Преимущества - -- **100% бесплатно, самостоятельно размещено, без ограничений.** Никаких ключей API для покупки, никаких подписок, никаких ограничений скорости. Всё работает на вашей машине, Docker и npm. Неограниченное использование, нулевая стоимость. - -- **Лёгкий, работает везде.** Создан и протестирован на Raspberry Pi — если работает там, работает везде. Минимальное потребление ресурсов, не требует тяжёлой инфраструктуры, работает 24/7 на маломощном оборудовании. - -- **Поиск + просмотр в одном наборе.** Никакой ручной интеграции не требуется. Поиск и просмотр — это две разные фазы, обе охвачены. - -- **Автоматическая эскалация навигации.** Если Camofox блокируется Cloudflare/Akamai, агент автоматически переключается на CloakBrowser. - -- **Умная производительность.** SearXNG для фазы поиска (миллисекунды). Camofox и CloakBrowser используются только для просмотра сайтов, которые действительно в этом нуждаются. - -- **Автоматический выбор агента.** ИИ-агент решает, какой инструмент использовать: SearXNG для начального поиска, Camofox для просмотра, CloakBrowser если сайт защищён. Нулевое вмешательство человека. - -- **Режим глубокого исследования.** Навык предписывает агенту выходить за рамки поверхностных ответов: исследовать несколько углов, перекрёстно проверять источники, охватывать каждый аспект и никогда не срезать углы. - -- **Полностью настраиваемый.** SKILL.md — это обычный текст. Вы можете редактировать основные правила, добавлять свои, удалять то, что вам не нужно. Адаптируйте его к своему рабочему процессу, своей команде, своим стандартам. - -- **Встроенная скрытность.** CloakBrowser автоматически обнаруживает вызовы Cloudflare, Akamai, DataDome, Imperva, PerimeterX и DDoS-Guard и ожидает их решения перед извлечением контента. - -- **Работает с любым агентом.** SKILL.md написан для OpenCode, но логика идентична для любого ИИ-агента. Тот же README, тот же package.json, всё работает везде. Просто попросите вашего агента преобразовать навык для своей среды. - -## 🏆 Современный уровень - -Эти три инструмента были выбраны, потому что они представляют современный уровень доступных сегодня решений. Такой навык создан для развития: когда появятся лучшие инструменты, достаточно обновить несколько строк в SKILL.md, чтобы заменить их. 🔄 - -⭐ **Поставьте звезду репозиторию и подпишитесь**, чтобы быть в курсе новых инструментов, улучшений потока и обновлений оркестрации. 🚀 - -## Архитектура - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ Поиск │ │ -│ │ │ │ -│ │ SearXNG │ поисковые системы → URL │ -│ │ (Docker) │ JSON-результаты, быстро │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ результаты готовы → просмотр │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ Просмотр │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ браузер + REST │ │ -│ │ │ (Docker) │ JS, клик, оценка │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ если заблокирован │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ скрытый Chromium │ │ -│ │ │ (npm) │ антибот, прокси │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Как это работает - -### Фаза 1 — Поиск с SearXNG - -Docker-контейнер на `localhost:8080`. Метапоисковая система, которая одновременно запрашивает Google, Wikipedia, Bing, DuckDuckGo и многие другие. Вывод JSON с заголовками, фрагментами и URL. - -**Пример:** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -Теперь у агента есть список URL для посещения, и он автономно решает, просматривать ли их с помощью Camofox или CloakBrowser в зависимости от сайта. - -### Фаза 2 — Просмотр с Camofox - -Docker-контейнер на `localhost:9377`. Предоставляет полный браузер Firefox через REST API. Агент может создавать вкладки, переходить по ссылкам, кликать, прокручивать, выполнять произвольный JavaScript и структурировать данные. - -**Включает:** Readability.js от Mozilla для извлечения чистых статей, удаляя навигацию, боковую панель и рекламу (~70% экономии токенов). - -**Основные команды:** - -```bash -# Создать вкладку и перейти -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# Прочитать снимок (дерево доступности) -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# Выполнить JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### Фаза 3 — Просмотр с CloakBrowser (когда Camofox недостаточно) - -npm-пакет на основе Playwright + `cloakbrowser`. Запускает браузер Chromium с расширенной цифровой отпечаткой для обхода Cloudflare, Akamai, DataDome и других антибот-систем. Автоматическое обнаружение вызовов с ожиданием и повторной попыткой. - -**Доступные скрипты:** - -- `cloak-fetch.mjs` — универсальный fetch с обнаружением вызовов -- `cloak-script.mjs` — выполнение пользовательского скрипта Playwright - -**Пример:** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## Почему и Camofox, и CloakBrowser? - -Потому что скорость и скрытность — это компромисс, и правильный инструмент зависит от сайта. - -**Camofox — быстрый, структурированный, постоянный.** -Camofox оборачивает Camoufox (форк Firefox на уровне C++) в REST API с постоянно тёплым браузером. После холодного запуска ~1-3с каждый запрос происходит почти мгновенно. Его снимки доступности ~90% меньше необработанного HTML, со стабильными ссылками на элементы (e1, e2, ...) для надёжного взаимодействия. Он обрабатывает ~90% сайтов, которые не используют расширенную антибот-защиту: статьи, документы, поисковые системы, стандартные веб-страницы. - -**CloakBrowser — скрытный, антибот, по требованию.** -CloakBrowser запускает новый экземпляр Chromium на каждый запрос (~1-3с запуска каждый раз). Он использует расширенную цифровую отпечатку, поддержку прокси, геолокацию и автоматическое обнаружение вызовов для обхода Cloudflare, Akamai, DataDome, Imperva, PerimeterX и DDoS-Guard. Это последнее средство для ~10% сайтов, которые блокируют Camofox. - -**Реальные показатели:** - -| Инструмент | Cloudflare стандартный | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox** (движок Camofox) | до **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** применяет **58 патчей на уровне исходного кода C++** и набирает **0.9 reCAPTCHA v3** (человеческий уровень, проверено сервером), проходя все основные антибот-тесты, включая Cloudflare Turnstile и FingerprintJS [²] -- **Camofox** холодный запуск: **~1-3с** (однократно, затем ~0мс на запрос через тёплый REST API) [³] -- **Playwright/Chromium** холодный запуск: **~0.5-6с** (каждый запуск, варьируется в зависимости от среды) [⁴] - -Camofox обрабатывает быстрый путь. CloakBrowser обрабатывает крайние случаи. Вместе они покрывают весь интернет без пробелов. Агент решает, какой использовать. - -### Источники - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## Установка - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -Покажите этот README вашему ИИ-агенту для полной установки, адаптированной под вашу среду и платформу. - -**Обзор сервисов:** - -| Сервис | Как | Ссылка | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm (включено) | `scripts/cloak/cloak-fetch.mjs` | - -**Для ИИ-агента — прочитайте эти файлы:** - -| Файл | Что содержит | -|---|---| -| `SKILL.md` | Полный навык: команды, эскалация, устранение неполадок | -| `scripts/cloak/cloak-fetch.mjs` | Использование CLI CloakBrowser и все опции | -| `scripts/setup-dependencies.sh` | Системные зависимости | -| `scripts/check-browser-search.sh` | Проверка после установки | -| `docker/setup.md` | Советы по настройке Docker | - -**Примечание:** `SKILL.md` написан для синтаксиса **OpenCode** (`exec`, `curl`). Если ваш агент использует другой формат (Claude Code, Cursor и т.д.), прочитайте его и преобразуйте команды в синтаксис вашего агента перед использованием навыка. - -## Переменные окружения - -| Переменная | Требуется для | По умолчанию | -|---|---|---| -| `CAMOFOX_API_KEY` | evaluate, session, cleanup в Camofox | — | -| `CAMOFOX_ADMIN_KEY` | Точка остановки Camofox | — | - -## ЧТО этот навык НЕ делает - -- **Социальные сети.** Instagram, Facebook, TikTok, LinkedIn и Twitter/X требуют входа в систему. `browser-search` не пытается их просматривать. -- **Загрузка файлов.** Он только для чтения (за исключением явных скриншотов). -- **Обход платных стен.** Не обходит платёжные системы или системы входа. - -## Участвуйте - -browser-search — это открытый исходный код и бесплатно. Если вы находите его полезным: - -- ⭐ **Поставьте звезду репозиторию** — помогает другим найти его -- 🐛 **Откройте issue** — сообщите об ошибках или предложите функции -- 🔀 **Отправьте PR** — исправляйте, улучшайте, расширяйте -- 💬 **Поделитесь им** — с вашей командой, на Reddit, Twitter, Discord -- 🧠 **Адаптируйте его** — форкните, настройте SKILL.md, сделайте его своим - -Каждый вклад, каким бы маленьким он ни был, делает это лучше. - -## Лицензия - -MIT diff --git a/browser-search/i18n/README.zh-CN.md b/browser-search/i18n/README.zh-CN.md deleted file mode 100644 index e2640e3..0000000 --- a/browser-search/i18n/README.zh-CN.md +++ /dev/null @@ -1,227 +0,0 @@ -# browser-search - -

- browser-search logo -

- -> **面向AI代理的技能。** 适用于OpenCode、Claude Code、Cursor、OpenClaw等。使用SearXNG搜索网页，使用Camofox浏览网页，使用CloakBrowser绕过防护。全部自托管、免费、无限制。 - -## 为什么存在 - -browser-search是一项技能——一套为OpenCode、Claude Code、Cursor、OpenClaw等AI代理设计的指令集。它教会你的代理如何使用三个协同工作的开源工具来搜索和浏览网页。 - -问题是什么？网络对自动化充满敌意。Cloudflare、Akamai、DataDome和其他反机器人系统会拦截简单的请求。现代网站使用繁重的JavaScript、延迟加载和客户端渲染。单一的解决方案是不够的。 - -`browser-search`将**三个开源工具**编排成一个专为AI代理设计的搜索和浏览系统。每个工具都有自己的角色，由技能通过升级逻辑、自动选择和即用集成进行编排： - -1. **[SearXNG](https://github.com/searxng/searxng)** — 搜索阶段的元搜索引擎（多源，JSON） -2. **[Camofox](https://github.com/jo-inc/camofox-browser)** — 可通过REST API导航的浏览器，适用于标准网站 -3. **[CloakBrowser](https://github.com/cloakhq/cloakbrowser)** — 用于受反机器人保护网站的隐形浏览器 - -典型流程：代理首先使用SearXNG搜索，然后使用Camofox（如果网站受保护则使用CloakBrowser）浏览结果。 - -## 优势 - -- **100%免费、自托管、无限制。** 无需购买API密钥，无需订阅，无速率限制。一切在你的机器上运行，Docker和npm。无限使用，零成本。 - -- **轻量级，随处运行。** 在树莓派上构建和测试——如果能在那里运行，就能在任何地方运行。资源消耗极低，无需重型基础设施，可在低功耗硬件上全天候运行。 - -- **搜索+浏览一体化。** 无需手动集成。搜索和浏览是两个不同的阶段，两者都已覆盖。 - -- **自动导航升级。** 如果Camofox被Cloudflare/Akamai拦截，代理会自动切换到CloakBrowser。 - -- **智能性能。** 搜索阶段使用SearXNG（毫秒级）。Camofox和CloakBrowser仅用于浏览实际需要它们的网站。 - -- **自动代理选择。** AI代理决定使用哪个工具：SearXNG用于初始搜索，Camofox用于浏览，CloakBrowser用于受保护的网站。无需人工干预。 - -- **深度研究模式。** 该技能指导代理超越肤浅的答案：探索多个角度，交叉验证来源，覆盖每个方面，绝不偷工减料。 - -- **完全可定制。** SKILL.md是纯文本。你可以编辑核心规则，添加自己的规则，删除不需要的内容。根据你的工作流程、你的团队、你的标准进行调整。 - -- **原生隐形。** CloakBrowser自动检测Cloudflare、Akamai、DataDome、Imperva、PerimeterX和DDoS-Guard挑战，并在提取内容前等待它们解决。 - -- **适用于任何代理。** SKILL.md是为OpenCode编写的，但其逻辑适用于任何AI代理。相同的README，相同的package.json，一切随处可用。只需询问你的代理如何根据其环境转换该技能。 - -## 🏆 技术前沿 - -选择这三个工具是因为它们代表了当前市场的最高水平。这样的技能设计就是为了不断进化：当更好的工具出现时，只需更新 SKILL.md 中的几行代码即可完成替换。🔄 - -⭐ **给仓库加星并关注**，随时了解新工具、流程改进和编排更新的最新动态。🚀 - -## 架构 - -``` -┌─────────────────────────────────────────────────────────┐ -│ browser-search │ -│ │ -│ ┌──────────────┐ │ -│ │ 搜索 │ │ -│ │ │ │ -│ │ SearXNG │ 搜索引擎 → URL │ -│ │ (Docker) │ JSON结果, 快速 │ -│ │ :8080 │ │ -│ └──────────────┘ │ -│ │ │ -│ │ 结果就绪 → 开始浏览 │ -│ ↓ │ -│ ┌─────────────────────────────────────┐ │ -│ │ 浏览 │ │ -│ │ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ Camofox │ 浏览器 + REST │ │ -│ │ │ (Docker) │ JS, 点击, 评估 │ │ -│ │ │ :9377 │ │ │ -│ │ └──────┬───────┘ │ │ -│ │ │ │ │ -│ │ │ 如果被拦截 │ │ -│ │ ↓ │ │ -│ │ ┌──────────────┐ │ │ -│ │ │ CloakBrowser │ 隐形Chromium │ │ -│ │ │ (npm) │ 反机器人, 代理 │ │ -│ │ └──────────────┘ │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## 工作原理 - -### 第一阶段 — 使用SearXNG搜索 - -Docker容器运行在`localhost:8080`。元搜索引擎，同时查询Google、Wikipedia、Bing、DuckDuckGo等多个引擎。JSON输出包含标题、摘要和URL。 - -**示例：** - -```bash -curl -s "http://localhost:8080/search?format=json&q=largest+llm+benchmark+2026" -``` - -代理现在有了要访问的URL列表，并根据网站自主决定使用Camofox还是CloakBrowser进行浏览。 - -### 第二阶段 — 使用Camofox浏览 - -Docker容器运行在`localhost:9377`。通过REST API暴露完整的Firefox浏览器。代理可以创建标签页、导航、点击、滚动、执行任意JavaScript和结构化数据。 - -**包含：** Mozilla的Readability.js，用于提取干净的文章，去除导航栏、侧边栏和广告（节省约70%的token）。 - -**主要命令：** - -```bash -# 创建标签页并导航 -curl -s -X POST "http://localhost:9377/tabs" \ - -H 'Content-Type: application/json' \ - -d '{"userId":"bot","url":"https://example.com"}' - -# 读取快照（无障碍树） -curl -s "http://localhost:9377/tabs//snapshot?userId=bot" - -# 执行JavaScript -curl -s -X POST "http://localhost:9377/tabs//evaluate" \ - -H 'Content-Type: application/json' \ - -H "Authorization: Bearer $CAMOFOX_API_KEY" \ - -d '{"userId":"bot","expression":"document.title"}' -``` - -### 第三阶段 — 使用CloakBrowser浏览（当Camofox不够时） - -基于Playwright + `cloakbrowser`的npm包。启动具有高级指纹识别的Chromium浏览器，以绕过Cloudflare、Akamai、DataDome和其他反机器人系统。自动检测挑战并带等待和重试。 - -**可用脚本：** - -- `cloak-fetch.mjs` — 通用获取，带挑战检测 -- `cloak-script.mjs` — 自定义Playwright脚本执行 - -**示例：** - -```bash -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" -node scripts/cloak/cloak-fetch.mjs "https://protected-site.com" --proxy socks5://... --geoip -``` - -## 为什么同时使用Camofox和CloakBrowser？ - -因为速度和隐身是一种权衡，正确的工具取决于网站。 - -**Camofox — 快速、结构化、持久化。** -Camofox将Camoufox（一个C++级别的Firefox分支）封装在一个REST API中，带有始终温热的浏览器。在约1-3秒的冷启动后，每个请求几乎是即时的。其无障碍快照比原始HTML小约90%，具有稳定的元素引用（e1, e2, ...），可实现可靠的交互。它处理约90%不使用高级反机器人保护的网站：文章、文档、搜索引擎、标准网页。 - -**CloakBrowser — 隐身、反机器人、按需使用。** -CloakBrowser每次请求启动一个新的Chromium实例（每次启动约1-3秒）。它使用高级指纹识别、代理支持、地理位置和自动挑战检测，以绕过Cloudflare、Akamai、DataDome、Imperva、PerimeterX和DDoS-Guard。它是针对约10%拦截Camofox的网站的最后手段。 - -**实际数据：** - -| 工具 | Cloudflare标准 | Cloudflare Turnstile | DataDome | -|---|---|---|---| -| **Camoufox**（Camofox引擎） | 高达 **~92%** [¹] | **~65-78%** [¹] | **60-75%** [¹] | -| **Playwright Stealth** | ~70-80% [¹] | ~40-55% [¹] | ~30-50% [¹] | - -- **CloakBrowser** 应用了**58个C++源码级补丁**，得分**0.9 reCAPTCHA v3**（人类级别，服务器验证），通过了包括Cloudflare Turnstile和FingerprintJS在内的所有主要反机器人测试 [²] -- **Camofox** 冷启动：**约1-3秒**（一次性，然后通过温热REST API每次请求约0毫秒）[³] -- **Playwright/Chromium** 冷启动：**约0.5-6秒**（每次启动，因环境而异）[⁴] - -Camofox处理快速路径。CloakBrowser处理边缘情况。两者结合覆盖整个网络，不留空白。代理决定使用哪个。 - -### 来源 - -¹ "Camoufox Vs Playwright Stealth: Complete Comparison & Alternatives (2026)" — [blog.send.win](https://blog.send.win/camoufox-vs-playwright-stealth-complete-comparison-alternatives-2026/) -² CloakBrowser README — [github.com/cloakhq/cloakbrowser](https://github.com/cloakhq/cloakbrowser) -³ camoufox-pi README (cold start comparison) — [github.com/MonsieurBarti/camoufox-pi](https://github.com/MonsieurBarti/camoufox-pi) -⁴ Playwright issue #4345 (launch time variability) — [github.com/microsoft/playwright/issues/4345](https://github.com/microsoft/playwright/issues/4345) - -## 安装 - -```bash -git clone https://github.com/johell1ns/browser-search -cd browser-search -npm install -``` - -将此README展示给你的AI代理，它将根据你的环境和平台进行完整安装。 - -**服务概览：** - -| 服务 | 方式 | 参考 | -|---|---|---| -| SearXNG | Docker, `:8080` | [docs.searxng.org](https://docs.searxng.org/admin/installation-docker.html) | -| Camofox | Docker, `:9377` | [github.com/jo-inc/camofox-browser](https://github.com/jo-inc/camofox-browser) | -| CloakBrowser | npm（已包含） | `scripts/cloak/cloak-fetch.mjs` | - -**供AI代理参考——阅读以下文件：** - -| 文件 | 内容 | -|---|---| -| `SKILL.md` | 完整技能：命令、升级、故障排除 | -| `scripts/cloak/cloak-fetch.mjs` | CloakBrowser CLI用法及所有选项 | -| `scripts/setup-dependencies.sh` | 系统依赖 | -| `scripts/check-browser-search.sh` | 安装后验证 | -| `docker/setup.md` | Docker设置技巧 | - -**注意：** `SKILL.md`是使用**OpenCode**语法（`exec`， `curl`）编写的。如果你的代理使用不同的格式（Claude Code、Cursor等），请阅读它并在使用该技能前将命令转换为你的代理语法。 - -## 环境变量 - -| 变量 | 适用于 | 默认值 | -|---|---|---| -| `CAMOFOX_API_KEY` | Camofox中的评估、会话、清理 | — | -| `CAMOFOX_ADMIN_KEY` | Camofox停止端点 | — | - -## 此技能不做什么 - -- **社交媒体。** Instagram、Facebook、TikTok、LinkedIn和Twitter/X需要登录。`browser-search`不会尝试浏览它们。 -- **下载文件。** 它是只读的（明确的截图除外）。 -- **绕过付费墙。** 不规避支付或登录系统。 - -## 参与其中 - -browser-search是开源且免费的。如果你觉得它有用： - -- ⭐ **给仓库加星** — 帮助他人发现它 -- 🐛 **提交Issue** — 报告错误或建议功能 -- 🔀 **提交PR** — 修复、改进、扩展 -- 💬 **分享它** — 与你的团队，在Reddit、Twitter、Discord上 -- 🧠 **改编它** — Fork它，调整SKILL.md，让它成为你的 - -每一份贡献，无论多小，都会让它变得更好。 - -## 许可证 - -MIT diff --git a/noc-dashboard/README.md b/noc-dashboard/README.md deleted file mode 100644 index a1cdd74..0000000 --- a/noc-dashboard/README.md +++ /dev/null @@ -1,60 +0,0 @@ -# NOC Dashboard - -Read-only monitoring dashboard for StackForge. Polls every service's real health -endpoint (the same ones in `docker-compose.yml` / `scripts/healthcheck.sh`) over the -internal Docker network, plus optional Portainer container stats. - -**This does not replace or proxy anything.** Every service still exposes its own -port/API exactly as before — this just gives you one screen to see all of them at once. - -## Install into StackForge - -1. Drop this whole `noc-dashboard/` folder into the root of your `StackForge` repo, - alongside `docker-compose.yml`. -2. Copy `docker-compose.dashboard.yml` to the repo root too (next to - `docker-compose.yml` / `docker-compose.headroom.yml`). -3. (Optional) add to `.env`: - ``` - PORTAINER_URL=http://:9000 - PORTAINER_API_KEY= - NOC_POLL_INTERVAL=10 - ENABLE_HEADROOM_MONITORING=false - ``` -4. Deploy: - ``` - docker compose -f docker-compose.yml -f docker-compose.dashboard.yml up -d --build - ``` -5. Open `http://:9500` - -## Running everything together - -``` -docker compose \ - -f docker-compose.yml \ - -f docker-compose.dashboard.yml \ - -f docker-compose.portainer.yml \ - -f docker-compose.headroom.yml \ - up -d --build -``` - -Leave out `-f docker-compose.portainer.yml` or `-f docker-compose.headroom.yml` if you -don't want those. All overlays are independent — mix and match freely. - -## Notes - -- **Portainer is now a real service** (`docker-compose.portainer.yml`) — it was previously - only mentioned in the README and healthcheck script with no actual compose definition. - It's still optional/separate so you're not forced to run it. To wire the dashboard to it, - set `PORTAINER_URL=http://portainer:9000` in `.env` (container-name resolution works - automatically since both are on the same Docker network) and generate an API key in - Portainer's UI for `PORTAINER_API_KEY`. -- **Fixed:** `headroom-qdrant` previously claimed host ports 6333/6334, colliding with the - main `qdrant` service. It's remapped to 6335/6336 on the host in `docker-compose.headroom.yml` - — internal container config is untouched, so nothing else needed to change. -- If you run the headroom overlay, set `ENABLE_HEADROOM_MONITORING=true` so the dashboard - also monitors it. -- `honcho-db` and `honcho-redis` aren't published to the host in the main compose file, - so the dashboard checks them over the internal Docker network only (TCP connect) — - there's no "open service" link for those two by design. -- Adding a new service later: add one entry to the `SERVICES` list in `backend/app.py` - with its container name, internal port, health path, and group — no frontend changes needed.