Перейти к основному содержимому

Page Agent

Встраивайте alibaba/page-agent в своё веб-приложение — это чистый JavaScript-агент для работы с GUI на странице, который поставляется в виде одного тега <script> или npm-пакета и позволяет конечным пользователям вашего сайта управлять интерфейсом на естественном языке («нажми «Войти», заполни имя пользователя как Иван»). Никакого Python, headless-браузера или расширений не требуется. Используйте этот навык, если пользователь — веб-разработчик, который хочет добавить ИИ-помощника в свой SaaS / админ-панель / B2B-инструмент, сделать устаревшее веб-приложение доступным через естественный язык или протестировать page-agent с локальной (Ollama) или облачной (Qwen / OpenAI / OpenRouter) LLM. НЕ для серверной автоматизации браузера — направляйте таких пользователей к встроенному инструменту браузера VibeOS.

Метаданные навыка​

ИсточникОпционально — установка: vibeos skills install official/web-development/page-agent
Путьoptional-skills/web-development/page-agent
Версия1.0.0
АвторVibeOS
ЛицензияMIT
Платформыlinux, macos, windows
Тегиweb, javascript, agent, browser, gui, alibaba, embed, copilot, saas

Справочник: полный SKILL.md​

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Это то, что агент видит в качестве инструкций, когда навык активен.

page-agent

alibaba/page-agent (https://github.com/alibaba/page-agent, 17k+ звёзд, MIT) — это внутристраничный GUI-агент, написанный на TypeScript. Он работает внутри веб-страницы, читает DOM как текст (без скриншотов, без мультимодальной LLM) и выполняет инструкции на естественном языке, такие как «нажми кнопку входа, затем заполни имя пользователя как Иван» на текущей странице. Полностью клиентский — хост-сайт просто подключает скрипт и передаёт OpenAI-совместимую LLM-конечную точку.

Когда использовать этот навык​

Загружайте этот навык, когда пользователь хочет:

  • Встроить ИИ-помощника в своё веб-приложение (SaaS, админ-панель, B2B-инструмент, ERP, CRM) — «пользователи моей панели управления должны иметь возможность написать «создать счёт для Acme Corp и отправить по email» вместо того, чтобы щёлкать по пяти экранам»
  • Модернизировать устаревшее веб-приложение без переписывания фронтенда — page-agent накладывается поверх существующего DOM
  • Добавить доступность через естественный язык — пользователи голосовых / экранных дикторов управляют интерфейсом, описывая, что они хотят
  • Демонстрировать или тестировать page-agent с локальной (Ollama) или хостинговой (Qwen, OpenAI, OpenRouter) LLM
  • Создавать интерактивные обучающие / продуктовые демонстрации — пусть ИИ проведёт пользователя через «как отправить отчёт о расходах» в реальном интерфейсе

Когда НЕ использовать этот навык​

  • Пользователь хочет, чтобы сам VibeOS управлял браузером → используйте встроенный инструмент браузера VibeOS (Browserbase / Camofox). page-agent — это противоположное направление.
  • Пользователь хочет автоматизацию между вкладками без встраивания → используйте Playwright, browser-use или расширение Chrome для page-agent
  • Пользователю нужна визуальная привязка / скриншоты → page-agent работает только с текстовым DOM; используйте мультимодального браузерного агента

Предварительные требования​

  • Node 22.13+ или 24+, npm 10+ (в документации указано 11+, но 10.9 работает отлично)
  • OpenAI-совместимая LLM-конечная точка: Qwen (DashScope), OpenAI, Ollama, OpenRouter или что-либо, поддерживающее /v1/chat/completions
  • Браузер с инструментами разработчика (для отладки)

Путь 1 — 30-секундная демонстрация через CDN (без установки)​

Самый быстрый способ увидеть, как это работает. Использует бесплатный тестовый LLM-прокси alibaba — только для оценки, на условиях alibaba.

Добавьте на любую HTML-страницу (или вставьте в консоль инструментов разработчика как букмарклет):

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

Появится панель. Введите инструкцию. Готово.

Форма букмарклета (перетащите на панель закладок, нажмите на любой странице):

javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();

Путь 2 — установка через npm в ваше веб-приложение (продуктивное использование)​

Внутри существующего веб-проекта (React / Vue / Svelte / обычный):

npm install page-agent

Подключите его с вашей собственной LLM-конечной точкой — никогда не поставляйте демо-версию CDN реальным пользователям:

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: process.env.LLM_API_KEY,   // никогда не хардкодьте
    language: 'en-US',
})

// Показать панель конечным пользователям:
agent.panel.show()

// Или управлять программно:
await agent.execute('Нажми кнопку отправки, затем заполни имя пользователя как Иван')

Примеры провайдеров (работает любая OpenAI-совместимая конечная точка):

ПровайдерbaseURLmodel
Qwen / DashScopehttps://dashscope.aliyuncs.com/compatible-mode/v1qwen3.5-plus
OpenAIhttps://api.openai.com/v1gpt-4o-mini
Ollama (локально)http://localhost:11434/v1qwen3:14b
OpenRouterhttps://openrouter.ai/api/v1anthropic/claude-sonnet-4.6

Ключевые поля конфигурации (передаются в new PageAgent({...})):

  • model, baseURL, apiKey — подключение к LLM
  • language — язык интерфейса (en-US, zh-CN и т.д.)
  • Для ограничения доступа агента существуют хуки белого списка и маскировки данных — см. https://alibaba.github.io/page-agent/ для полного списка опций

Безопасность. Не помещайте свой apiKey в клиентский код для реального развёртывания — проксируйте LLM-вызовы через свой бэкенд и указывайте baseURL на ваш прокси. Демо-версия CDN существует, потому что alibaba запускает этот прокси для оценки.

Путь 3 — клонирование исходного репозитория (для внесения изменений или экспериментов)​

Используйте это, когда пользователь хочет изменить сам page-agent, протестировать его на произвольных сайтах через локальную IIFE-сборку или разработать расширение для браузера.

git clone https://github.com/alibaba/page-agent.git
cd page-agent
npm ci              # точная установка из lock-файла (или `npm i` для разрешения обновлений)

Создайте .env в корне репозитория с LLM-конечной точкой. Пример:

LLM_MODEL_NAME=gpt-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Вариант для Ollama:

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=NA
LLM_MODEL_NAME=qwen3:14b

Часто используемые команды:

npm start           # dev-сервер документации/сайта
npm run build       # сборка всех пакетов
npm run dev:demo    # запуск IIFE-сборки на http://localhost:5174/page-agent.demo.js
npm run dev:ext     # разработка расширения для браузера (WXT + React)
npm run build:ext   # сборка расширения

Тестирование на любом веб-сайте с помощью локальной IIFE-сборки. Добавьте этот букмарклет:

javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent готов!');document.head.appendChild(s);})();

Затем: npm run dev:demo, нажмите букмарклет на любой странице — и локальная сборка внедрится. Автоматическая пересборка при сохранении.

Предупреждение: ваш LLM_API_KEY из .env встраивается в IIFE-сборку во время dev-сборок. Не распространяйте сборку. Не коммитьте её. Не вставляйте URL в Slack. (Проверено: поиск по публичной dev-сборке возвращает буквальные значения из .env.)

Структура репозитория (Путь 3)​

Монорепозиторий с npm workspaces. Ключевые пакеты:

ПакетПутьНазначение
page-agentpackages/page-agent/Главная точка входа с панелью UI
@page-agent/corepackages/core/Базовая логика агента, без UI
@page-agent/mcppackages/mcp/MCP-сервер (бета)
—packages/llms/LLM-клиент
—packages/page-controller/DOM-операции + визуальная обратная связь
—packages/ui/Панель + i18n
—packages/extension/Расширение для Chrome/Firefox
—packages/website/Документация + лендинг

Проверка работоспособности​

После Пути 1 или Пути 2:

  1. Откройте страницу в браузере с открытыми инструментами разработчика
  2. Вы должны увидеть плавающую панель. Если нет, проверьте консоль на наличие ошибок (самые частые: CORS на LLM-конечной точке, неправильный baseURL или неверный API-ключ)
  3. Введите простую инструкцию, соответствующую чему-то видимому на странице («нажми ссылку «Войти»»)
  4. Посмотрите вкладку «Сеть» — вы должны увидеть запрос к вашему baseURL

После Пути 3:

  1. npm run dev:demo выводит Accepting connections at http://localhost:5174
  2. curl -I http://localhost:5174/page-agent.demo.js возвращает HTTP/1.1 200 OK с Content-Type: application/javascript
  3. Нажмите букмарклет на любом сайте; появится панель

Подводные камни​

  • Демо-версия CDN в продакшене — не делайте так. Она имеет ограничение по скорости, использует бесплатный прокси alibaba, и их условия запрещают использование в продакшене.
  • Раскрытие API-ключа — любой ключ, переданный в new PageAgent({apiKey: ...}), попадает в ваш JS-бандл. Всегда проксируйте через свой бэкенд для реальных развёртываний.
  • Не-OpenAI-совместимые конечные точки молча терпят неудачу или выдают малопонятные ошибки. Если ваш провайдер требует нативного форматирования Anthropic/Gemini, используйте прокси совместимости с OpenAI (LiteLLM, OpenRouter) перед ним.
  • Блокировка CSP — сайты со строгой Content-Security-Policy могут отказаться загружать CDN-скрипт или запретить встроенный eval. В этом случае разместите скрипт на своём домене.
  • Перезапустите dev-сервер после редактирования .env в Пути 3 — Vite читает env только при запуске.
  • Версия Node — репозиторий объявляет ^22.13.0 || >=24. Node 20 не пройдёт npm ci с ошибками движка.
  • npm 10 vs 11 — в документации указано npm 11+; npm 10.9 на самом деле работает отлично.

Ссылки​