Когда вы просите кодинг-агента (будь то Claude Code, Codex, Cursor или терминальный CLI) изменить что-то в интерфейсе веб-приложения, начинается классическая игра в испорченный телефон. Вы пишете: «сделай карточку во втором сайдбаре чуть шире и перемести кнопку назад». Агент уходит искать нужный компонент среди десятков файлов, ориентируется по примерным названиям классов или тексту, путает родительские контейнеры и часто меняет совершенно другой кусок верстки. В итоге вместо экономии времени разработчик вынужден вручную инспектировать DOM в Chrome DevTools, копировать классы и указывать агенту точные имена компонентов.
Проект Agentation решает эту проблему на фундаментальном уровне. Это агентно-независимый (agent-agnostic) инструмент визуального фидбека, созданный специально для связки человека и кодинг-агентов. Вы просто кликаете по нужному элементу прямо на странице работающего приложения, пишете замечание — а инструмент автоматически извлекает точные DOM-селекторы, координаты, текст и упаковывает всё это в структурированный контекст, готовый для мгновенного grep агентом или передачи по протоколу MCP (Model Context Protocol).
Сравнение: ручное описание правок против визуальной разметки в Agentation
Главный выигрыш при использовании Agentation — устранение контекстных галлюцинаций агента и сокращение времени передачи UI-задач:
| Параметр | Словесное описание в чате | Скриншот экрана | Разметка в Agentation (MCP) |
|---|---|---|---|
| Точность локализации | Низкая: поиск по примерным именам и тексту | Средняя: агент видит картинку, но не видит код и селекторы | 100% точность: точный CSS-селектор, путь в DOM и классы |
| Потребление токенов | Низкое, но требует долгих уточнений | Очень высокое (тяжёлые изображения в контексте) | Минимальное: легковесный структурированный Markdown |
| Скорость до первого диффа | 2–5 минут на итерации и объяснения | 1–3 минуты (агент ищет похожий код) | Секунды: агент сразу делает grep по селектору или атрибуту |
| Динамические состояния | Трудно поймать анимации и выпадающие меню | Сложно успеть сделать скриншот нужного кадра | Встроенная пауза: остановка CSS/Web Animations и видео |
| Автоматизация передачи | Ручной копипаст текста | Перетаскивание файла картинки в терминал/чат | Прямой синк: фоновый MCP-сервер отдаёт аннотации агенту |
Архитектура и ключевые инженерные возможности Agentation
1. Извлечение селекторов и Grep-ready разметка
Когда вы кликаете по элементу, Agentation вычисляет не просто плоский путь, а оптимальный набор идентификаторов: уникальные классы, атрибуты доступности (ARIA), теги и контекст родительских элементов. Вместо абстрактного «синяя кнопка» агент получает точную конструкцию вроде .sidebar > button.primary или data-атрибуты компонента. Агент сразу запускает поиск по кодовой базе и моментально находит нужный JSX/TSX-файл.
2. Поддержка MCP (Model Context Protocol) для прямой синхронизации
Agentation не ограничивается буфером обмена. В экосистеме проекта есть официальный сервер agentation-mcp, работающий по протоколу Model Context Protocol. Вы настраиваете свой любимый агент (например, Claude Code) на работу с локальным сервером, а компонент тулбара подключаете к локальному endpoint:
<Agentation endpoint="http://localhost:4747" />Агент получает доступ к инструменту agentation_get_all_pending. Разработчик оставляет аннотации в браузере, возвращается в терминал и пишет: «Проверь задачи из Agentation и примени правки». Агент сам забирает свежие замечания с сервера, находит файлы и правит код.
3. Продвинутые режимы выделения
Интерфейсы бывают сложными, поэтому инструмент поддерживает несколько способов разметки:
- Точечный клик: автоматическое определение селектора элемента под курсором.
- Множественный выбор (Multi-select): зажав клавишу
CmdилиCtrl, можно отметить сразу несколько независимых элементов, либо выделить область рамкой. - Выделение текста: позволяет привязать замечание к конкретному слову, заголовку или абзацу текста.
- Выделение произвольной области (Area selection): прямоугольная рамка на свободном пространстве страницы, если элемент ещё не сверстан.
4. Заморозка анимаций и видео (Animation Pause)
Одна из самых частых болей верстки — поймать баг в момент анимации, дропдауна или появления тултипа. В Agentation встроен механизм перехвата: инструмент умеет ставить на паузу активные CSS-анимации, переходы (transitions), воспроизведение видео и анимации через Web Animations API. Вы можете остановить кадр в нужной фазе и спокойно кликнуть по анимированному элементу.
5. Работа с Shadow DOM, iFrame и Hash-роутингом
В отличие от простых userscript-расширений, Agentation глубоко интегрирован в браузерные API:
- Корректно погружается в открытые узлы Shadow Root веб-компонентов.
- Позволяет размечать элементы внутри same-origin iframes.
- Поддерживает опцию
useHashLocationдля SPA-приложений на базе hash-роутинга, изолируя сессии и аннотации для каждого экранного маршрута.
6. Zero Dependencies и лёгкий вес
Пакет написан на чистом TypeScript и не тянет за собой громоздкие внешние библиотеки. Единственная зависимость — peer-зависимость от React 18+. Весь код тулбара изолирован и не конфликтует со стилями вашего проекта.
Пошаговый гайд: установка, интеграция в React и подключение к MCP
Шаг 1. Установка пакета в проект
Установите библиотеку как dev-зависимость в ваш проект:
npm install agentation -D
# или через pnpm
pnpm add -D agentationШаг 2. Добавление компонента в приложение
Импортируйте компонент и добавьте его в корневой файл (например, App.tsx или корневой layout Next.js / Vite). Рекомендуется подключать его только в режиме разработки:
import { Agentation } from 'agentation';
function App() {
return (
<>
<YourMainApplication />
{process.env.NODE_ENV === 'development' && (
<Agentation endpoint="http://localhost:4747" />
)}
</>
);
}В правом нижнем углу экрана появится аккуратная кнопка вызова панели инструментов Agentation.
Шаг 3. Запуск MCP-сервера для агента
Чтобы ваш кодинг-агент видел фидбек в реальном времени, зарегистрируйте MCP-сервер. Для Claude Code или других клиентов добавьте в конфигурацию:
npx -y agentation-mcp serverСервер поднимется на порту 4747. Теперь страница в браузере и ваш терминальный агент подключены к одному локальному каналу обмена данными.
Шаг 4. Практический тест и рабочий процесс
- Откройте локальное веб-приложение в браузере.
- Кликните на иконку Agentation и выберите элемент, требующий доработки (например, неровный заголовок или кнопку с неправильным отступом).
- В появившемся поле введите комментарий: «Добавь отступ снизу 16px и сделай скругление углов 8px». Нажмите Enter.
- Перейдите в терминал к вашему агенту и напишите:
Исправь UI по замечаниям из Agentation. - Агент вызовет метод
agentation_get_all_pending, увидит точный селектор, откроет нужный TSX/CSS-файл и сразу применит корректный патч.
Резюме
Agentation закрывает критический разрыв между визуальным представлением интерфейса и текстовым миром LLM. Вместо размытых словесных промптов и тяжёлых скриншотов вы даёте агенту точечный, структурированный контекст. Поддержка протокола MCP делает связку с терминальными ассистентами бесшовной, экономя часы рутинной работы при верстке и полировке веб-приложений.
