kitesurf-bridge

Управляйте Cloudflare Kitesurf — браузером, ориентированным на агентов, который работает в изолятах V8 на Cloudflare Workers — откуда угодно. Ноль зависимостей, без локального Chrome.

Поставляется с четырьмя способами использования одного движка:

Команды установки ниже используют GitHub-спецификацию, которая работает сегодня без учётной записи в реестре. После публикации в npm как @truenix/kitesurf-bridge каждый github:TrueNix/kitesurf-bridge сокращается до @truenix/kitesurf-bridge.

npx -y github:TrueNix/kitesurf-bridge markdown https://news.ycombinator.com

Это отображает реальную страницу в реальном браузерном движке, в сети Cloudflare, без установленного локального браузера и без API-токена.

Почему это существует

Kitesurf не является открытым исходным кодом и не может работать на вашей машине. Cloudflare говорит, что намерен открыть его исходный код «когда мы будем готовы», и даже тогда заявленная цель — чтобы клиенты «развернули собственную версию Kitesurf в своих аккаунтах» — всё ещё на Workers.

В цикле разработки также нет локального Kitesurf: wrangler dev запускает ваш локальный Chrome, а не Kitesurf. Kitesurf существует только за browser=kitesurf на удалённых конечных точках.

Поэтому практический вопрос не в том, «можно ли запустить его локально», а в том, «можно ли управлять им из локального кода». Этот пакет и есть такой мост.

Установка

Как MCP-сервер

claude mcp add kitesurf -- npx -y github:TrueNix/kitesurf-bridge mcp

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "kitesurf": {
      "command": "npx",
      "args": ["-y", "github:TrueNix/kitesurf-bridge", "mcp"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-browser-run-token"
      }
    }
  }
}

Доступные инструменты: kitesurf_markdown, kitesurf_text, kitesurf_html, kitesurf_links, kitesurf_screenshot, kitesurf_evaluate, kitesurf_accessibility_tree, kitesurf_probe.

Как плагин DSH / Cordis

# in an agent preset composition
- '@truenix/kitesurf-bridge/cordis':
    cli: npx -y github:TrueNix/kitesurf-bridge
    timeoutMs: 120000

Плагин регистрирует те же инструменты на хосте. Он намеренно вызывает CLI: динамическая половина хоста Cordis не имеет доступа к WebSocket, fetch или node:*, поэтому CDP нельзя открыть внутри песочницы. См. cordis/plugin.mjs.

Как библиотека

npm install github:TrueNix/kitesurf-bridge

import { withSession } from '@truenix/kitesurf-bridge';

const md = await withSession({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

CLI

kitesurf-bridge <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JS runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Endpoint + engine capability report
  mcp                Run as an MCP server on stdio

Полезные опции: --main, --raw, --full, --width, --height, --json, --endpoint, --account, --token, --timeout.

Эндпоинты

Установите CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN (или CF_*) для переключения. Передача идентификатора аккаунта без токена — это жёсткая ошибка, а не тихий переход на общую песочницу.

[!WARNING] Песочница — это бесплатный, общий, неаутентифицированный ресурс без SLA. Подходит для оценки и локальной работы агентов — не стройте на ней продакшн.

Что стоит знать о Kitesurf

Это проверено на живом сервисе, а не скопировано из документации. kitesurf-bridge probe воспроизводит это.

Kitesurf не использует V8 для скриптов страниц — он использует Boa, JS-движок на Rust. Boa устанавливает гораздо более низкий предел рекурсии и выбрасывает RuntimeLimit: exceeded maximum number of recursive calls. Естественный рекурсивный обход DOM умирает на любой большой странице (Wikipedia, сайты документации). Поэтому конвертер Markdown в этом пакете обходит DOM с явным стеком, сохраняя глубину вызовов JS на уровне O(1). Если вы используете kitesurf_evaluate, предпочитайте итеративные выражения.

Ошибки навигации приходят как коды состояния edge Cloudflare, а не как ошибки CDP. Page.navigate возвращает обычные frameId/loaderId даже для несуществующего хоста, и Network.loadingFailed не срабатывает. Отсутствующий домен проявляется как HTTP 530, сломанный origin — как 520, оставляя документ-заглушку длиной ~16 символов. Доверие к Page.navigate даёт агенту пустую страницу и называет это успехом — поэтому этот пакет классифицирует результаты из домена Network и выбрасывает ошибку, когда статус >=400 приходит с пустым документом, при этом возвращая реальные страницы ошибок (с status), у которых есть читаемый контент.

Флаги возможностей (проверено):

Для этого используйте вместо него браузер Chromium по умолчанию из Browser Run.

Компромисс по производительности (собственные данные Cloudflare): Kitesurf использует в 3–7 раз меньше CPU и памяти, чем тёплый Chromium, но в 1.7–1.8 раза медленнее по реальному времени. Этот выигрыш — на счету Cloudflare для пиковых облачных нагрузок агентов — он ничего не экономит на вашем собственном оборудовании. Если вам просто нужна локальная автоматизация браузера и у вас уже есть Chrome, локальный Playwright быстрее и поддерживает WebGL и видео.

Ноль зависимостей

package.json имеет пустой блок dependencies, в том числе для транспорта WebSocket.

Глобальный WebSocket в Node (WHATWG) не может отправлять заголовки запросов, а конечной точке аккаунта нужен Authorization: Bearer …. undici нельзя импортировать как отдельный модуль. Поэтому src/ws.mjs реализует клиент RFC 6455 напрямую поверх node:http(s) — рукопожатие, маскирование, фрагменты продолжения, 64-битные длины, ping/pong, закрытие — всё, что нужно CDP, с поддержкой заголовков.

Тесты

npm test                        # live tests against the playground
KITESURF_SKIP_NETWORK=1 npm test   # offline only

Набор тестов намеренно обращается к реальному сервису: интересные сбои (предел рекурсии Boa, усечение pipe, edge-коды состояния) проявляются только при работе с реальным сервисом.

Требования

Node ≥ 18. Без браузера, без API-токена, без шага сборки.

Лицензия

MIT