protostatis/unbrowser

Пробник действий высокого уровня. Кликает по элементу по ref или видимому тексту действия, ожидает стабилизации и возвращает URL до/после, сводки BlockMap/page_model, количество сетевых запросов, хэши и классификацию: navigated, dom_changed, network_changed, no_effect или unsupported.

Пересчитывает BlockMap для текущей страницы. Используйте после eval-кода или клика/ввода, изменяющего DOM. По форме совпадает со встроенным blockmap из navigate.

Возвращает сырое HTML-тело последней навигации. Используется как запасной вариант, когда BlockMap или селекторов недостаточно, но ответ может быть большим (часто 100 КБ и более).

Отправляет событие клика по элементу с ref (например, e:142, полученный из запроса). Если элемент <a href> и для клика не был вызван preventDefault, автоматически переходит по href через navigate (возвращает полный результат навигации с новым BlockMap). В противном случае возвращает {ok, ref, tag, follow: null}.

Удаляет все куки из банки.

Возвращает все файлы cookie, находящиеся в данный момент в хранилище, в виде [{name, value, domain, path, secure, http_only}]. Использует это, чтобы экспортировать файлы cookie на диск для последующего сеанса.

Добавляет куки в session jar. Каждый элемент - это объект {name, value, domain, path?, secure?, http_only?, url?} или необработанная строка Set-Cookie. Продолжает использовать состояние сеанса из браузера, в котором авторизован пользователь, где это разрешено, повторно предъявляя куки доступа (например, PerimeterX _px3), полученные в реальном Chrome - это требует явного подтверждения пользователя и эфемерного хранилища с областью действия origin.

Высокоуровневое обнаружение информации с приоритетом дешёвых источников. Опционально переходит по URL, выполняет лёгкий JavaScript, объединяет DOM-маршруты, выведенные URL форм/запросов и сетевые JSON-маршруты в один ранжированный граф с указанием происхождения и подсказками по эскалации на уровне маршрутов. Используйте это, когда нужно найти, где находится информация, перед её извлечением.

Выполняет произвольный JavaScript во встроенном рантайме QuickJS на разобранном DOM текущей страницы. Возвращает результат в виде JSON-строки. Инструмент с полным контролем: предпочитайте query/text/blockmap, когда движок CSS-селекторов может выразить то, что вам нужно. Канонический параметр - code; сырой JSON-RPC также принимает псевдонимы script или expression и выдает ошибку, если отсутствует параметр, похожий на code.

Автоматическая стратегия извлечения структурированных данных. Пробует JSON-LD (schema.org) → NEXT_DATA → Nuxt → JSON-in-script (скрипты с пользовательскими типами Magento, Shopify, BigCommerce) → OpenGraph/meta → microdata → запасной вариант text_main, возвращает наиболее уверенное совпадение в виде {strategy, confidence, data, tried}. Используйте этот инструмент как одноразовый вызов 'дай мне данные, а как - разберись сам', когда не хотите сами планировать стратегию. Передайте strategy='json_ld' (или любое из указанных выше имён), чтобы принудительно использовать конкретный экстрактор.

Автоматически определяет повторяющиеся блоки статей/карточек/товаров/курсов/списков и возвращает нормализованные элементы [{title, price, condition, url, availability, snippet, meta, image_alt, score}]. Отдаёт предпочтение этому методу перед extract_list, когда на странице есть семантически неоднозначные карточки рецептов, курсов, товаров или моделей и вы ещё не знаете селекторы полей. Необязательный селектор ограничивает обнаружение до известных узлов карточек; параметр kind может смещать оценку (recipe, course, product, listing).

Извлекает повторяющийся паттерн карточек в [{...}, {...}]. Подходит для списков в стиле HN, результатов поиска, сеток товаров: избавляет от шаблонного кода eval для каждого сайта. Формы спецификации полей: 'css selector' (текстовое содержимое), 'css selector @attr' (атрибут) или ['css selector', '@attr'] (кортежная форма). Если подселектор возвращает null, значение поля равно null.

Преобразует <table> в {headers, rows, row_count}. Заголовки берутся из <thead><th>...</th></thead>, если он есть, иначе из ячеек <th> первого <tr>. Ячейки <td> каждой последующей строки <tr> становятся словарём строки, где ключи - заголовки (или 'col_N', если для этой колонки заголовка нет). Отлично подходит для таблиц цен, спецификаций, финансовых и листинговых таблиц - избавляет от написания eval для маппинга каждой ячейки.

Находит локализованные текстовые совпадения и возвращает [{ref, tag, attrs, before, match, after, text}]. Ранжирует совпадения article/main/content выше шаблонного кода nav/header/footer.

Раскрывает полный инструментарий, начиная с минимальных 3. Возвращает сгруппированный каталог всех 32 инструментов с указанием, когда использовать, и примером. Минимальный профиль показывает только navigate (как open), extract, help; help открывает остальные. Используйте help(topic) для фильтрации, например 'query', 'extraction', 'discovery'.

Загружает URL по HTTP с Chrome-отпечатком, используя активный профиль. Разбирает HTML, подготавливает JS DOM, возвращает BlockMap прямо в ответе. При exec_scripts: true извлекает встроенные И внешние теги <script> из разобранного HTML, параллельно загружает внешние скрипты (таймаут 8 секунд на запрос), выполняет их через eval в порядке появления в документе в QuickJS (с шимами для setTimeout/fetch и т.д.), затем завершает цикл событий и инициирует DOMContentLoaded + load. <script async> учитывается: асинхронные скрипты выполняются после синхронной очереди. Когда задан --policy=blocklist, URL-адреса трекеров блокируются на этапе загрузки скриптов (см. scripts.policy_blocked в результате). Возвращает сводку scripts с полями inline_count, external_count, async_count, policy_blocked, executed, errors. Автоизвлечение: когда страница содержит встроенные теги <script> с JSON (density.json_scripts > 0, охватывает application/json, application/ld+json, text/x-magento-init, text/x-shopify-app и т.д.), navigate автоматически запускает extract() и возвращает результат в поле extract. Это избавляет от лишнего запроса в типичном случае, когда данные, которые отрисовал бы JS, уже лежат в HTML: JSON-LD-схемы статей на новостных сайтах, состояние страницы NEXT_DATA в приложениях Next.js, json_in_script-блоки товаров в Magento/Shopify, RSC-пейлоады GitHub и т.д. Ограничение: 16 КБ встроенных данных; сверх лимита extract возвращает заглушку с полями strategy/confidence/size_bytes/hint, и агенту нужно явно вызвать extract(), чтобы получить полные данные. Страницы без встроенного JSON получают extract:null и не несут дополнительных затрат. Подсказки по инструментам: navigate также возвращает tool_likelihoods и tool_recommendations, вычисленные на основе конкретных сигналов страницы (структура/заголовки, подсказки по селекторам, плотность, встроенные данные, сетевые перехваты, состояние челленджа и патологии скриптов), чтобы агенты могли выбрать следующий инструмент, не гадая. Авторешение: JS-челлендж proof-of-work от Reddit (provider: reddit_js_challenge) решается прозрачно: челлендж обнаруживается, вычисляется GET-URL решения (solution = hex_value + hex_value),…

Преобразует захваченные JSON/API/сетевые ответы в семантические объекты с полями, оценками, совпавшими с запросом терминами и происхождением захвата/пути. Используйте после navigate или activate, когда network_stores показывает захваты JSON/GraphQL/NDJSON, а сырой body_preview слишком шумный.

Возвращает содержащие контент ответы fetch/XHR, перехваченные во время navigate, отсортированные по предполагаемой ценности контента. SPA часто хранят свои данные в API-ответах (JSON, GraphQL, NDJSON, данные маршрутов Next/Nuxt), которые чище, чем отрисованный DOM. Этот инструмент показывает их напрямую. Каждая запись содержит capture_id, URL, статус, content-type, body_preview (усечён до 256 КБ), body_bytes (полный размер), флаг body_truncated, navigation_id и эвристическую оценку. Тела ответов для трекеров/рекламы/CSS/HTML/медиа НЕ перехватываются. Результат navigate уже содержит сводку из топ-5, ограниченную этой навигацией; используйте этот инструмент, чтобы получить больше записей, отфильтровать по хосту или извлечь захваченные данные из другой навигации.

Отбрасывает все перехваченные сетевые ответы из сетевого хранилища сеанса. Используйте это между несвязанными переходами, если не хотите, чтобы более ранние перехваты появлялись в последующих вызовах network_stores.

Преобразует текущую страницу в семантические JSON-объекты, по которым можно обнаружить задачи. Восстанавливает структуру страницы в виде объектов search_form, nav_link, article_card, course_card, model_card, product_card, table, answer_block и limitation с действиями, нормализованными полями, оценкой на основе целей и происхождением. Предпочитайте этот инструмент как первый инструмент планирования после navigate, когда сырые ссылки/текст слишком широки.

Применяет CSS-селектор к распарсенному DOM текущей страницы. Возвращает совпавшие элементы в виде [{ref, tag, attrs, text, text_chars, text_truncated}]. Ссылки на элементы (e:NN) служат стабильными дескрипторами для click/type/submit. Движок селекторов поддерживает теги, id, классы, операторы сравнения атрибутов (=, ^=, $=, *=, ~=), все четыре комбинатора (потомок, >, +, ~), псевдоклассы (:first/last/nth-child включая формулы An+B, :first/last/nth-of-type, :only-child/of-type), :not() и :has().

Диагностирует, почему CSS-селектор сработал или не сработал. Возвращает matched_count, примеры совпадений, сводные счётчики DOM, подсказки по селекторам (основные теги, классы, data-атрибуты, id) и практические рекомендации для selector_miss, thin_shell или embedded_json. Используйте этот инструмент, когда query() возвращает [] и нужно отличить неверный селектор от пустого DOM или DOM, отрисованного браузером.

Находит элементы по видимому текстовому содержимому. Возвращает самый маленький/глубокий элемент, чей textContent совпадает с искомой строкой, пропуская chrome (header/nav/footer/aside). Повышение до якоря: если элемент span/strong и т.п. находится внутри <a>, результатом будет якорь (так что click() нацеливается на кликабельный элемент). Подходящий инструмент, когда CSS-селекторы нестабильны (страницы, отрисованные React, с хешированными именами классов), но видимая подпись надёжна - например, найти кнопку 'Sign in', не зная её класса.

Привязывает результат задачи (успех/неудачу/качество) к предыдущему navigation_id из вызова navigate(). Его использует протокол результатов каркаса политик, см. docs/probabilistic-policy.md §4.5. v0 генерирует событие outcome_reported в формате NDJSON для навигации. Апостериорных обновлений пока нет. Драйверы должны вызывать этот инструмент один раз на задачу агента, чтобы будущие байесовские фазы (B/D-2) могли приписывать успех или неудачу извлечения конкретным решениям политик.

Находит принадлежащие странице навигационные/поисковые маршруты для цели. Возвращает ранжированные видимые ссылки, формы с элементами управления и предпросмотрами query_url, а также выведенные URL-адреса на основе маршрутов страницы и терминов цели. Используйте перед ручным угадыванием URL-адресов.

Опустошает цикл событий JS: попеременно выполняет поставленные в очередь микрозадачи (разрешения Promise) и запускает просроченные обратные вызовы setTimeout/setInterval, переходя в режим ожидания до следующего срабатывания, когда остаются только таймеры. Завершается, когда очередь пуста ИЛИ истекает max_ms ИЛИ завершаются max_iters итераций. По умолчанию: max_ms=2000, max_iters=50. Используйте после заполнения DOM (или после выполнения eval-кода, который планирует таймеры), чтобы дать запуститься ожидающим обратным вызовам.

Отправляет форму, собирая значения input/textarea/select и переходя по итоговому URL действия. Поддерживает GET и POST с типом application/x-www-form-urlencoded. Значения отмеченных checkbox/radio сериализуются; формы с multipart-загрузкой не поддерживаются.

Псевдоним для extract_table с первой таблицей по умолчанию. Извлекает таблицу в {headers, rows, row_count}; селектор по умолчанию: 'table'. Используйте этот инструмент, когда агенту нужен удобный конвертер таблицы в JSON.

Получает textContent первого элемента, соответствующего селектору (по умолчанию: body). Примечание: на сайтах Wikipedia, MDN и новостных порталах первый <p> часто оказывается служебной пометкой или подписью к изображению, а не вводным абзацем. Для чтения основного содержимого страницы лучше использовать text_main.

Возвращает очищенный окружающий текст вокруг ссылки на элемент или наилучшее ранжированное текстовое совпадение. Возвращает {ref, before, match, after, text}.

Возвращает текст из селектора или лучшего корневого элемента контента, очищенный от элементов оформления, JSON и со схлопнутыми пробелами. Удаляет script/style/noscript/svg, элементы оформления страницы (nav/header/footer/aside), очевидные скрытые виджеты и повторяющиеся шаблонные блоки.

Получает textContent основной области контента страницы, исключая служебные элементы (header/nav/footer/aside). Пробует <main>, затем [role=main], затем одиночный <article>, а затем переходит к самому длинному поддереву без служебных элементов. Используйте это для чтения тела статьи, страницы документации или содержимого блога.

Устанавливает значение input/textarea (на который ссылается ref) и отправляет события input и change. Используйте перед отправкой формы на полях формы.