escalator

Дайте ему URL — получите чистый Markdown. Он поднимается по самой дешёвой ступени, которая работает: обычный HTTP-запрос, тот же запрос через резидентный прокси, затем скрытый браузер — и останавливается на первой, которая возвращает реальный контент.

$ escalator scrape https://en.wikipedia.org/wiki/Web_scraping | head -3
# Web scraping

**Web scraping**, **web harvesting**, or **web data extraction** is [data scraping](...)

Быстрый старт

# 1. install uv (https://docs.astral.sh/uv/getting-started/installation/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. configure this machine -- finds your browser, or fetches one
uvx escalator init

# 3. use it
uvx escalator scrape https://en.wikipedia.org/wiki/Web_scraping

Это весь вход. init создаёт один файл конфигурации, и перед первым запуском ничего не нужно редактировать вручную. Если что-то выглядит не так: escalator doctor.

На минимальном Linux (голый контейнер, свежий VPS) Chrome требует системные библиотеки, которые на десктопе уже есть. escalator не устанавливает их за вас — он выводит точную команду apt-get, и escalator doctor повторяет её. Одна команда, один раз:

sudo apt-get update && sudo apt-get install -y \
  libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 \
  libgbm1 libglib2.0-0t64 libpango-1.0-0 libcairo2 libasound2t64 \
  libatspi2.0-0t64 libxcb1 libdbus-1-3 libexpat1

Никаких батареек — осознанно. escalator поставляется без конфигурации — без встроенного браузера, без встроенных прокси, без телеметрии, ничего не записывается за пределами его собственных каталогов. init существует для того, чтобы настройка была двухминутным разговором, а не поиском по README.

Related MCP server: Safer Fetch MCP Server

Установка

Всё необходимое для основного процесса есть в стандартной установке, включая ступень браузера — она не приносит с собой браузер, для этого и существует escalator browser install. Есть одно дополнение: escalator[mcp] добавляет интерфейс MCP, и Docker-образ включает его.

Docker

docker run --rm \
  -e ESCALATOR_SERVER_API_KEYS=your-key \
  -p 8000:8000 -v ./data:/data \
  ghcr.io/ruslanstarikov/escalator serve

Образ содержит зафиксированный браузер и настраивается полностью через переменные окружения — см. docker-compose.example.yml для настройки прокси. Он работает под uid 1000, поэтому примонтированный ./data должен быть доступен для записи.

Команды

escalator init [--yes]     configure this machine; --yes for scripts
escalator doctor [--json]  check everything, one fix per failure
escalator browser list     every browser found, and which one wins
escalator browser install  download Chrome for Testing into the data dir
escalator scrape URL       one page to stdout, so it pipes
escalator serve            the HTTP API and the MCP face
escalator --version        tool, python, platform

Лестница

policy      robots.txt (cached) + rate limit  → may short-circuit (skip/deny/wait)
http        curl_cffi, impersonate=chrome     → ~100ms; clears undefended sites
http_proxy  same, routed via residential IP   → beats datacenter-IP bans
browser     nodriver, headless Chrome         → JS/SPA + Cloudflare-class defenses
                    │
                    └─ walled on the last rung? → status="challenged". Surrender.

Две вещи делают это не просто циклом for:

200 OK — это не успех. Ступень, возвращающая HTTP 200 с промежуточной страницей Cloudflare, не достигла успеха. core/detect.py классифицирует каждый ответ после извлечения — content, thin или blocked — и только content считается. Без этого лестница никогда бы не поднималась, и кэш навсегда запомнил бы «http работает» для домена, который отдаёт мусор.

Кэш забывает. Выученная стартовая ступень, которая только повышалась, со временем уводила бы каждый домен к браузеру+прокси и незаметно раздувала счёт за прокси. Записи содержат learned_at; после ladder.tier_cache_ttl_hours домен пробует на одну ступень дешевле.

См. DESIGN.md о том, почему она устроена именно так — и о том, что она сознательно отказывается делать.

Конфигурация

Один файл, создаваемый init, в системном каталоге конфигурации (~/.config/escalator/config.toml на Linux, ~/Library/Application Support/escalator/config.toml на macOS). Переопределите расположение с помощью --config.

Приоритет везде:

CLI flag  >  environment  >  config.toml  >  default

Каждый ключ имеет переменную окружения, именно так Docker-образ настраивается без файла вообще:

Данные — база SQLite и любой загруженный браузер — хранятся в системном каталоге данных, который можно переопределить через ESCALATOR_STORAGE_DATA_DIR. Ничего не записывается за его пределами.

Откуда берётся браузер

escalator browser list показывает поиск по порядку:

1. явный путь — --browser-path, затем ESCALATOR_BROWSER_PATH, затем browser.path. Если он задан и неверен, это ошибка с указанием пути, а не молчаливый переход дальше.

2. браузеры, установленные на этой машине: сначала настоящий Google Chrome, затем Chromium, затем Edge и Brave.

3. браузер, загруженный ранее командой escalator browser install.

Если ни один из них ничего не находит, вы получаете ошибку с указанием двух команд, которые это исправляют. Разрешение никогда не загружает само — серверный запрос или cron-задача не должны устанавливать программное обеспечение как побочный эффект.

Использование сервера

escalator serve   # 127.0.0.1:8000 by default

POST /scrape   {url, markdown?, min_tier?, max_tier?, timeout_ms?}  -> FetchResult
GET  /healthz                                                       -> {status, version}

Аутентифицируйтесь с помощью Authorization: Bearer <key>, где ключ — один из server.api_keys. Этот список есть истина: удалите ключ — и он будет отозван при следующем запуске. Нет конечной точки для создания нового.

Стена возвращается как 200 OK с {"status": "challenged"}, а не как HTTP-ошибка. Это осознанно: агент на другом конце может на это отреагировать. Повторные попытки в цикле не помогут — escalator не решает CAPTCHA, по замыслу.

С дополнением [mcp] та же лестница доступна на /mcp как один инструмент, scrape_url(url, force_browser=False).

Устранение неполадок

Начните здесь:

escalator doctor

Он проверяет Python, файл конфигурации, каталог данных, разрешение браузера, реальный запуск в headless-режиме и — если прокси настроен — один реальный запрос через него, сообщая исходящий IP и страну с замаскированным паролем. Каждый ❌ сопровождается одной строкой, которая это исправляет, и код выхода ненулевой, если что-то не удалось, так что скрипты тоже могут это использовать. escalator doctor --json для машин.

Если всё ещё не работает, вставьте весь вывод escalator doctor в issue — именно об этом просит его последняя строка, и это самый быстрый путь к ответу.

Разработка

См. CONTRIBUTING.md. Кратко: uv sync, uv run pytest.

Лицензия

Выпущено в общественное достояние — см. UNLICENSE. Без гарантий, без обязательного указания авторства, делайте что хотите.