Scout Pilot

Scout Pilot — учебный автономный браузерный агент для интервью-проекта. Репозиторий показывает, как разнести браузерную автоматизацию, LLM-провайдера, планирование, память, безопасность и отчеты по понятным слоям.

Это не готовый продукт для реальной эксплуатации. Репозиторий можно установить, проверить локальными тестами, посмотреть CLI в dry-run режиме, запустить live-цикл через scout-pilot run --live и вручную выполнить smoke-тест на HH.ru без hardcoded selectors и без автоматической отправки заявок.

Что уже есть

• Browser Engine на Playwright с persistent profile, navigation, screenshots, cleanup и structured failures.
• Semantic Observation Engine: компактное представление страницы без полного HTML и значений чувствительных полей.
• Observation классифицирует типовые блокеры: modal dialog, cookie/banner overlay, login wall, CAPTCHA/block page, region/location prompt, empty/loading page; runtime записывает это в report/replay и останавливается на CAPTCHA/login wall без обхода.
• Provider-neutral Tool Runtime с валидацией, history, timeout handling и Security Policy перед выполнением действий.
• LLM Provider Layer для OpenAI/Anthropic за общим интерфейсом. В автоматических тестах используются только mocks.
• Planning Engine, Hierarchical Memory, Context Budgeting, Execution Intelligence и Autonomous Agent Runtime.
• Generic semantic navigation без CSS selectors, XPath, hardcoded URLs и site-specific workflows: выбор учитывает role, accessible name, visible text, локальный контекст секции, location и form labels; stale IDs восстанавливаются через re-observe и semantic fingerprint.
• CLI на русском: menu, status, doctor, run --dry-run, run --live, profile-info, profile-open, provider-smoke, interactive, browser-smoke, live-local-demo, mail-spam-demo, food-order-demo, interview-demo, demo-vacancy-search.
• Compact/verbose dashboard показывает задачу, состояние, шаг агента, шаг плана, краткое наблюдение, выбранный tool, очищенные аргументы, решение Security Policy и результат.
• Безопасные JSON report/replay артефакты без raw HTML, cookies, tokens, browser profiles, чувствительных значений и приватных путей.

Ограничения

• scout-pilot run --live запускает настоящий runtime loop: видимый браузер, semantic observation, planning/reasoning, Tool Runtime, Security Policy, reflection и report/replay. Для воспроизводимой проверки есть --provider mock; для OpenAI/Anthropic нужны локальные API-ключи в .env.
• HH.ru используется только для ручного smoke-теста. Автоматические тесты не зависят от живого сайта.
• Live HH.ru может показать CAPTCHA, вход, выбор региона или другую динамическую страницу. Это нормальный результат smoke-теста; его не нужно подменять успешным сценарием.
• Файл LICENSE не добавлен, потому что владелец проекта пока не выбрал лицензию.

Быстрый старт

Требования: Python 3.11+ и установленный браузер Chromium через Playwright. Текущий локальный прогон проекта выполнялся на Python 3.14.3; нижняя граница в pyproject.toml оставлена 3.11, потому что код не использует синтаксис новее 3.11.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m playwright install chromium

Для live-режима с OpenAI или Anthropic установите provider SDKs:

python -m pip install -e ".[dev,providers]"

Если нужен один полный локальный набор для ревью, можно поставить .[all]. Базовая установка без providers поддерживает mock/demo режимы и не тянет SDK платных провайдеров.

Создайте локальный .env из безопасного примера:

Copy-Item .env.example .env

Проверьте установку:

python -m pytest
scout-pilot doctor
scout-pilot status

Для демонстрации без длинных команд можно открыть меню:

scout-pilot menu

По умолчанию меню использует локальный Codex CLI, авторизованный через ChatGPT: отдельный API-ключ в .env для этого режима не нужен. Установка и проверка:

npm install -g @openai/codex
codex login
scout-pilot provider-smoke --provider codex
scout-pilot menu

В меню пункт 0 открывает чат с агентом: сначала вводится URL сайта, затем браузер остается открытым, а в строку Вы > можно писать обычные задачи подряд. Enter на URL открывает https://hh.ru. При запуске CLI явно показывает путь persistent profile и режим браузера. После задачи он печатает оценку контекста до/после сжатия, число ресурсных страниц в контексте задачи и число предотвращенных повторных переходов. Команды внутри режима: /url сменить сайт, /open N открыть пронумерованную ссылку из последнего ответа в текущем браузере, /report показать последний replay/report, /debug включить подробный trace, /exit выйти и закрыть браузер. В Windows Terminal ссылки также можно открывать через Ctrl + клик; для старого cmd.exe надежнее использовать /open N. Codex запускается в ephemeral/read-only режиме и получает только provider-neutral сообщения, компактные semantic observations и tool schemas; браузерные действия по-прежнему выполняет Scout Pilot через Tool Runtime и Security Policy. Пункты 1-8 открывают готовые проверки, report/replay, persistent profile и provider smoke.

doctor проверяет версию Python, импорт пакета, наличие Playwright, headless-запуск Chromium через Browser Engine, .env, Git ignore для browser profile и reports/tmp, состояние working tree и архитектурные границы. Проверка границ подтверждает, что Playwright импортируется только Browser Engine, SDK провайдеров только LLM Layer, а независимые слои не содержат полного HTML API и HH.ru-специфичной логики. Отсутствие .env или грязный Git показываются как предупреждения, не как падение команды.

Запустите безопасный CLI dry-run:

scout-pilot run "Найди три подходящие вакансии Python AI Developer" --dry-run

Запустите live-режим без внешних LLM-вызовов, но с реальным браузером и runtime:

scout-pilot run "Проверь страницу и подготовь краткий отчет" `
  --live `
  --provider mock `
  --start-url https://example.com `
  --headed `
  --dashboard verbose

В compact и verbose режимах терминал показывает безопасную трассу tool-вызовов. Значения форм, cookies, tokens, API keys, raw HTML и приватные пути редактируются перед выводом и перед записью report/replay.

Обычный live-запуск имеет жесткий аварийный потолок 128 автономных шагов и десять минут wall-clock time; для интерактивного чата из пункта 0 предел сокращен до четырех минут на задачу. Runtime не должен стремиться использовать эти лимиты полностью. Для задач с явно указанным количеством разных страниц агент завершает browser phase сразу после чтения нужного числа ресурсов и делает отдельный final-answer-only запрос без tools. После первой карточки следующие ссылки того же ресурсного типа собираются детерминированно, без отдельного LLM-вызова на каждый переход; ссылки работодателей и справки в эту серию не попадают. browser.back возвращает к выдаче через Browser Engine без Alt+Left. После двух уточнений одного поиска runtime предпочитает непосещенные ссылки повторному заполнению поля. Если смысловой выбор ссылки оказался неоднозначным, Execution Intelligence берет следующую непосещенную ссылку из текущей выдачи без дополнительного вызова модели. Верхние числовые границы не передаются в неоднозначный поисковый фильтр: они проверяются по видимому тексту результатов и деталей. Если защитный лимит все же достигнут, CLI показывает best-effort ответ из уже сохраненных semantic facts вместо пустой ошибки.

Обычный поиск не требует подтверждения: ввод в семантически распознанное поле поиска, запуск поиска, фильтры, сортировка, чтение и переходы выполняются сразу. Если Security Policy видит реальный внешний эффект, например Apply, отправку сообщения, удаление или оплату, run --live останавливается до browser action. В интерактивном терминале CLI показывает действие, очищенную цель и последствия. Ответ да разрешает только этот запрос инструмента один раз; пустой ответ, нет или n отменяет действие. В неинтерактивном запуске запрос подтверждения только сохраняется в report/replay.

Для live-режима с OpenAI или Anthropic добавьте ключ в локальный .env и выберите провайдера:

scout-pilot run "Проверь страницу и подготовь краткий отчет" `
  --live `
  --provider openai `
  --start-url https://example.com `
  --headed `
  --dashboard verbose

Ручная проверка live-провайдера без браузера и без приватного контекста:

scout-pilot provider-smoke --provider openai

Для Anthropic используйте --provider anthropic и совместимую модель в локальном .env. Автоматические тесты эти команды не вызывают. Если команда live-провайдера сообщает, что SDK не установлен, повторите установку с extra providers. Перед live-проверкой конкретного провайдера можно отдельно проверить наличие ключа без запроса к модели:

scout-pilot doctor --provider openai

Проверка браузера без живых сайтов:

scout-pilot browser-smoke --headless --hold-seconds 0

Проверка persistent profile:

scout-pilot profile-info
scout-pilot profile-open --profile default --start-url https://example.com --headed

profile-open открывает видимый браузер с тем же профилем, который использует scout-pilot run --live по умолчанию. Войдите на сайт вручную, закройте браузер, затем запускайте агента с тем же default profile. Логины не автоматизируются, credentials не сохраняются в репозиторий, storage state не экспортируется.

Локальное runtime demo без реальных сайтов, учетных данных и live LLM-вызовов:

scout-pilot live-local-demo --headless --slow-mo-ms 0 --dashboard off

Синтетическое почтовое demo показывает, что агент не завязан только на вакансии. Команда создает локальный inbox с 10 безопасными тестовыми письмами, читает их через браузерные инструменты, классифицирует вероятный спам и останавливается перед Move to spam/Delete message:

scout-pilot mail-spam-demo --headless --slow-mo-ms 0

Это не подключение к Yandex Mail, Gmail или другому реальному почтовому сервису. Демо не удаляет письма и не переносит их в спам без подтверждения; report/replay сохраняются в reports/tmp/ и не содержат raw HTML.

Синтетическое food-order demo проверяет пример с checkout/payment. Агент ищет ресторан, различает похожие позиции меню, добавляет BBQ Burger и French Fries, открывает checkout и останавливается перед финальной кнопкой оплаты:

scout-pilot food-order-demo --headless --slow-mo-ms 0

Это локальный сайт без реальных сервисов доставки, платежей и личных данных. Финальная кнопка Pay and confirm order проходит через Security Policy и не нажимается без подтверждения.

После любого demo или run --live можно посмотреть короткую безопасную сводку JSON-артефакта:

scout-pilot replay-summary reports/tmp/<file>.json

Команда читает report/replay как источник истины и печатает задачу, итог, страницы, tool-вызовы, паузы безопасности, метрики контекста, заметки и блокеры. Если файл содержит raw HTML, неочищенные секреты или приватные пути, сводка не выводится как обычный отчет.

Старое scripted interview demo тоже доступно как дополнительная проверка:

scout-pilot interview-demo --headless --slow-mo-ms 0 --wait-after-search-ms 50

Документация

• Установка и конфигурация
• Архитектура
• Тестирование
• Техническая защита проекта
• Release checklist
• Interview demo
• Сценарий видео на 3–5 минут
• Ручной smoke-тест HH.ru
• Как вносить изменения

Interview Demo

Для короткого видео используйте локальный deterministic demo через обычный autonomous runtime:

scout-pilot live-local-demo --headed --slow-mo-ms 120 --dashboard compact

Команда сама создает локальный тестовый сайт в reports/tmp/, открывает видимый браузер, запускает нормальный runtime loop, читает три страницы, пишет report/replay и показывает остановку безопасности перед действием Apply. Старый interview-demo оставлен как scripted fallback. Подробный чек-лист: docs/interview_demo.md.

Демо HH.ru

Демо-команда начинает с URL, который передает пользователь, и дальше использует только семантические наблюдения и обнаруженные ссылки. В коде нет маршрутов HH.ru, CSS selectors или XPath под сайт.

Локальная проверка демо:

python -m pytest tests/test_demo_vacancy_search.py

Ручной live smoke:

scout-pilot demo-vacancy-search `
  --start-url https://hh.ru `
  --query "AI Engineer Python AI Developer" `
  --max-vacancies 3 `
  --headed `
  --probe-security `
  --report-path reports/tmp/hh-demo-report.json

Во время запуска CLI пишет короткие сообщения вроде Открыл стартовую страницу, Нашел поле поиска, Нашел N кандидатов, Читаю страницу 1/N и Остановился перед внешним действием. Отчет содержит start_url, discovered_urls, pages_read, blockers, security_pauses и final_notes.

Security Policy отличает поисковый submit от отклика по роли, имени, видимому тексту и контексту элемента. Поиск проходит автоматически; отклики, сообщения, загрузки файлов и другие внешние действия остаются на подтверждении.

Подробный чек-лист: docs/hh_demo.md.

Безопасность данных

Не коммитьте .env, browser profiles, session state, cookies, tokens, приватные скриншоты, временные отчеты и реальные резюме. .gitignore уже закрывает типовые локальные артефакты:

• .env, .venv, caches;
• .browser-profiles/, .browser-sessions/, storage-state*.json, cookies*.json, tokens*.json;
• reports/tmp/, reports/private/, приватные screenshots и .har.

Перед коммитом полезно проверить:

git status --short
git diff --check
python -m pytest
python -m ruff check .

Структура

src/scout_pilot/
  browser/       # изоляция Playwright
  observation/   # семантические наблюдения страницы
  tools/         # provider-neutral tool runtime
  llm/           # адаптеры OpenAI/Anthropic и reasoning
  planning/      # создание и пересмотр планов
  memory/        # ограниченная иерархическая память
  runtime/       # автономный цикл и state machine
  security/      # детерминированная политика действий
  navigation/    # разрешение семантических целей
  reporting/     # безопасные отчеты и replay
  cli/           # пользовательский CLI на русском
tests/           # детерминированные unit/integration tests
docs/            # документация на русском