Скриншоти як докази для ШІ-агентів: уся сторінка, регіони та диффи

Щоб агент встановив Playwright і зберіг PNG, вистачить кількох рядків. Із цим давно ніхто не мучиться. Проблеми починаються, коли такі зображення потрапляють у робочий процес у продакшені й комусь доводиться на них покладатися.

Тоді агент уже має довести, що довгу сторінку знято до самого низу. Треба порізати результат на шматки, які модель зору справді зможе прочитати, зберігати докази так, щоб вони згодом не змінювалися, порівнювати два релізи без хибних тривог через зсуви верстки, запускати перевірки за розкладом і не виходити за бюджет, коли за процесом ніхто не стежить.

Один зі способів зібрати все це докупи — керований API для скриншотів із віддаленим MCP-сервером, для публічних сторінок або сторінок, до яких має доступ сторона, що викликає. Замінювати звичайний Playwright там, де досить одноразового знімка, він не мусить. Його завдання — бути шаром доказів для процесів, що повторюються.

Знімок сторінки в заданому стані

Сам лише URL не визначає, що буде на скриншоті. Ширина екрана на десктопі, планшеті й телефоні різна, світла й темна теми виглядають по-різному, а сторінка після кліку — вже інша сторінка. Тому сервісу знімків потрібні налаштування: іменовані пристрої та власні розміри вікна, бажана тема, стратегія очікування, очищення, приховані селектори, заголовки, cookies і сценарії взаємодії. З ними процес сам каже, яку версію сторінки зберегти, а не задовольняється тим, що встигло завантажитися після переходу.

У знімка всієї сторінки є своя пастка. Висота може змінюватися, поки підвантажується лінивий контент, вебшрифти й зображення, і браузер цілком може повернути картинку з порожнім низом. Рятує порядок дій: прокручувати крок за кроком, чекати, доки висота документа перестане змінюватися, повернутися нагору, зробити знімок і звірити ширину та висоту готового PNG або JPEG із документом. Якщо сторінка так і не заспокоїлася або росте далі, виклик повертає типізовану помилку. Видимий збій кращий за неповний доказ, який видають за повний.

Нарізка довгих сторінок на читабельні регіони

Якщо втиснути скриншот заввишки 12 000 пікселів у невеликий вхід моделі зору, текст перетвориться на кашу. Сервіс розв'язує це прапорцем regions у запиті.

curl --request POST https://api.scrinly.com/render/screenshot \
  --header "Authorization: Bearer $SCRINLY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com",
    "device": "macbook-pro-14",
    "theme": "dark",
    "fullPage": true,
    "regions": true,
    "format": "jpg",
    "quality": 80
  }'

У відповіді приходить увесь скриншот і впорядковані фрагменти: панель навігації, hero-блок, основний контент, заклики до дії, футер та інші знайдені області. У маніфесті для кожного регіону вказано межі, порядок, впевненість, покриття, розміри й хеш. Кожен фрагмент вирізають із фінального відданого скриншота, а не з повторного знімка, який міг би відрізнятися.

Прапорець design додає детерміновані дані про кольори, типографіку, відступи, верстку й анімації, очищені та обмежені за розміром. Жодна ШІ-модель у їх створенні не бере участі.

Якщо обробка регіонів зламалася, а сам скриншот вдався, сторона, що викликає, все одно його отримує, а повертається лише доплата за регіони.

Докази, які не можна перезаписати

Два знімки одного URL ніколи не повинні затирати один одного. Тому файли зберігаються під іменами, виведеними з хешу фінальних закодованих байтів.

{storagePrefix}/{screenshotSha256}.jpg

Різні байти дають різні ключі, а однакові знімки спокійно ділять один. Результати посилаються прямо на сховище, а не на проксі для зображень. За замовчуванням файли лежать у Backblaze B2, а клієнти REST API можуть спрямувати їх у власні бакети B2, S3 чи R2. Кешування вмикається прапорцем cache, а пакети публічних скриншотів вміщують до 100 збережених знімків, причому оплату й повернення рахують для кожного елемента окремо.

Порівняння релізів без хибних спрацювань

Режимів порівняння два: точне попіксельне й перцептивне, яке терпить шум. На виході може бути розмічений оверлей, контекстна теплова карта, бінарна маска або лише метадані.

Уся складність порівняння — у зсувах. Додайте нову секцію під hero-блоком, і звичайний дифф цілого зображення позначить зміненим усе, що нижче. Та якщо обидва знімки мають сумісні маніфести регіонів, кожну логічну секцію порівнюють окремо. Вставлений блок позначається як доданий, а футер, що просто з'їхав донизу, вважається незмінним.

Моніторинг працює на тому самому конвеєрі. Монітор робить новий знімок і порівнює його з ковзним або фіксованим еталоном. Коли поріг перевищено або регіон з'явився чи зник, він відкриває візуальний інцидент, надсилає підписаний вебхук або лист на підтверджену адресу й повідомляє про відновлення, щойно сторінка повертається до норми.

Повільні завдання зі скриншотами й диффами можна запускати асинхронно. API повертає id завдання в межах акаунта, опитування статусу безкоштовне, а готовий результат може надійти підписаним вебхуком.

ШІ — лише після детермінованих кроків

Скриншоти, регіони, дані про дизайн, хеші й диффи повністю детерміновані. Необов'язковий візуальний стайлгайд додає інтерпретацію моделлю, але тільки коли ці дані вже зібрано.

Модель, яку обирає сервер, отримує оглядове зображення обмеженого розміру, впорядковані зображення регіонів і очищену проєкцію. Цільовий URL, ім'я хоста, HTML, cookies, заголовки, селектори, облікові дані та переданий текст сторінки їй як текст не передаються. Звісно, тексти й бренд, видимі на екрані, все одно можуть потрапити в пікселі.

Результат описує візуальну основу, колір, типографіку, відступи, компоненти, анімації, адаптивність і прогалини в даних, а твердження звіряються з цими даними. Стайлгайди кешуються автоматично, а прапорець regenerate запитує свіжий. Можна також передати тимчасовий ключ OpenAI в окремому заголовку, його не зберігають. Якщо генерація не вдалася, скриншот і регіони лишаються доступними, а повертається тільки доплата за ШІ.

Доступ для агентів через MCP

Віддалений MCP-сервер пропонує чотири інструменти:

• capture_screenshot
• compare_screenshots
• get_job_status
• get_usage

Підключення йде через OAuth, запасний варіант — API-ключ. У Codex це виглядає так:

codex mcp add scrinly --url https://mcp.scrinly.com/mcp

Сервер доповнює навичка для агентів із відкритим кодом. MCP робить інструменти доступними для виклику, а навичка вчить сумісних агентів, коли знімок справді потрібен, як обрати найменший робочий ліміт кредитів, що робити, поки прийняте завдання ще виконується, щоб не надіслати платний запит двічі, і як зберігати відповідні скриншоти, регіони й хеші одним набором.

npx skills add davmixcool/skills --skill scrinly -g

Платні операції MCP вимагають значення maxCredits. Якщо списання в найгіршому разі перевищить заявлений користувачем ліміт, запит відхиляють ще до рендерингу й оплати. Так з'являється зрозуміла межа між тим, що агент може робити сам, і тим, за що платить користувач.

Уроки проєктування, що знадобляться й деінде

1. Успішний виклик браузера не доводить, що скриншот повний.
2. Похідні фрагменти треба вирізати з того самого зображення, яке віддали.
3. Для стабільних доказів потрібне сховище з адресацією за вмістом.
4. Детермінована обробка має йти до інтерпретації ШІ.
5. У разі часткового успіху слід віддавати корисний результат і повертати гроші лише за частину, що зламалася.
6. Автономним інструментам потрібні явні ліміти витрат, а не тільки автентифікація.
7. Playwright керує браузером, але робочому процесу візуальних доказів у продакшені потрібна навколо нього чимала інфраструктура.

Щодо цін: безкоштовний тариф дає 100 кредитів на місяць. Голий скриншот коштує один кредит, із регіонами — три, кожен візуальний дифф — один, а новий стайлгайд коштом платформи — до шести.