SnapRef

SnapRef — это ядро автоматизации браузера с минимальными зависимостями и локальным приоритетом для агентов: изолированные сеансы, интерактивные снимки с исполняемыми ссылками, привязанными к ревизии, типизированные действия/проверки, скрипты, MCP с управлением политиками, телеметрические квитанции и кроссплатформенные шлюзы жизненного цикла.

go install github.com/nstranquist/snapref/cmd/snapref@v0.2.0-rc.1
snapref runtime install --runtime chrome-for-testing --channel stable
snapref runtime install --runtime headless-shell --channel stable
snapref self-test

В рабочей копии исходного кода make init выполняет те же две установки среды выполнения.

Статус: 0.2.0-rc.1 на https://github.com/nstranquist/snapref. Поддержка Windows не заявляется, пока не будет пройден физический шлюз Windows+Chrome.

Пакеты

• browser: сеансы, CDP, снимки/ссылки, готовность к действию, доказательства, навыки;

• contract: типизированный реестр операций/разрешений/результатов;

• script: повторяемый движок рабочих процессов YAML/JSON/Starlark;

• mcp: сервер MCP stdio с управлением политиками;

• cmd/snapref: автономный CLI и живое самотестирование.

Автономные команды skill и job-posting выдают только общую типизированную экстракцию. Передача продуктов, специфичных для хоста, выходит за рамки этого модуля.

Related MCP server: ChromePlayMCP

Золотой путь

snapref runtime install --runtime chrome-for-testing --channel stable
snapref runtime install --runtime headless-shell --channel stable
snapref runtime verify --all
snapref open demo
snapref exec demo navigate http://localhost:3000
snapref exec demo snapshot --wait-for-selector '[data-test="app-ready"]' --settle 1s
snapref exec demo click 'sr-…:e1'
snapref close demo --purge-profile

Безголовый режим используется по умолчанию. auto использует только проверенные управляемые среды выполнения (или явное внешнее переопределение SNAPREF_CHROME); он никогда не ищет и не запускает личную установку браузера оператора. Работа с головным режимом и распакованными расширениями направляется в Chrome for Testing. Обычная безголовая работа использует Headless Shell только после прохождения локального эталонного теста точной версии; в противном случае используется управляемый Chrome for Testing. Установка среды выполнения является явной и является единственной командой браузера, которая загружает файлы.

Именованные CLI-сеансы имеют отказоустойчивую 10-минутную аренду простоя; каждая операция браузера продлевает её. Используйте --idle-timeout (или SNAPREF_BROWSER_IDLE_TIMEOUT) для более длительного ограниченного рабочего процесса и --keep-alive только когда сохранение состояния намеренно. Истечение простоя сохраняет именованный профиль для повторного использования файлов cookie/состояния; snapref gc показывает предпросмотр устаревших мёртвых сеансов и профилей, а snapref gc --apply восстанавливает их. Делайте снимок перед действием. Используйте самую новую ссылку. MCP drive, чтение хоста, запись на хост и разрешения источников — это отдельные полномочия SNAPREF_MCP_*.

Скриншоты по умолчанию полноразмерные. В YAML/JSON-плейбуках можно объявить screenshot_mode: full-page для архивных доказательств или screenshot_mode: viewport для точного доказательства сгиба/фокуса; отдельный шаг может переопределить план. Полноразмерный захват измеряет отображаемый документ, но не запускает специфичную для приложения отложенную загрузку или раскрытие при прокрутке. Каждая квитанция скрипта записывает эффективный режим и измеренные ширину/высоту PNG.

Проверка

make verify
make verify-release

make verify запускает тесты, детектор гонок, vet, нативную компиляцию, кросс-компиляцию Windows и проверки контракта выпуска.

make verify-release также дважды собирает артефакты выпуска. Требуется, чтобы каждый артефакт был побайтно идентичен при обеих сборках.

Сборщик артефактов использует только локальный кэш модулей. Он отключает загрузку зависимостей, переопределения рабочей области, пользовательские настройки Go и автоматическую загрузку цепочек инструментов.

Живой snapref self-test проверяет готовность гидратированных снимков. Он также проверяет активацию ссылок в открытых теневых корнях и фреймах того же источника.

make release-dist воспроизводимо собирает архивы CGO-free macOS arm64, Linux amd64 и Windows amd64 с юридическими/защитными файлами и манифестом SHA256SUMS. Он не публикует их.

Команда выпуска собирает все файлы в соседнем промежуточном каталоге. Она изменяет только указанные архивы и SHA256SUMS в существующем выходном каталоге.

Несвязанные выходные файлы остаются без изменений. Команда отклоняет корни файловой системы, дерево исходников, родительские каталоги дерева исходников, символические ссылки и нерегулярные управляемые артефакты.

Если восстановление не удается после ошибки публикации, команда выводит и сохраняет промежуточный каталог восстановления. Не удаляйте этот каталог, пока не восстановите или не скопируете сохранённые артефакты.

Используйте выходной каталог, контролируемый оператором. Транзакция выпуска не защищает от недоверенного процесса, который одновременно изменяет каталог.

EXTRACTION.json фиксирует дайджест каждого общего пути к исходному коду, канонический режим обычного файла и байт файла. Разрешения Windows-чекаута нормализуются до требуемого режима 0644; на других платформах происходит сбой при изменении разрешений. Несовпадение дайджеста означает, что извлечённое дерево отклонилось от проверенной блокировки исходного кода и должно быть повторно синхронизировано перед выпуском.

Версионируемые общедоступные контракты артефактов находятся в schemas/telemetry-v2.schema.json и schemas/script-run-v2.schema.json. Каждый архив выпуска включает обе схемы и docs/VERSIONING.md.

Архитектура

SnapRef — это локальный движок, а не размещённый парк браузеров.

• browser владеет изолированными сеансами Chromium, CDP, снимками, привязанными к ревизии ссылками, готовностью к действию, записями и управляемыми средами выполнения.

• contract — это типизированный реестр операций и разрешений.

• script выполняет YAML/JSON/Starlark-планы в открытом сеансе.

• mcp — это сервер stdio с управлением политиками. Drive, чтение хоста, запись на хост и разрешения источников — отдельные полномочия.

• cmd/snapref — автономный CLI. Хостовые адаптеры находятся за пределами этого модуля.

• processtree — это вендорная копия MIT, используемая только для ограниченной отмены подпроцессов в инструментах выпуска и тестирования.

См. docs/ARCHITECTURE.md.

Использование

snapref open demo
snapref exec demo navigate https://example.com
snapref exec demo snapshot --wait-for-selector body --settle 1s
snapref exec demo click 'sr-…:e1'
snapref close demo --purge-profile
snapref mcp

snapshot — это значение по умолчанию для обнаружения. Действуйте по самой новой привязанной к ревизии ссылке. eval — это запасной вариант, а не путь обнаружения. MCP drive, чтение хоста, запись на хост и разрешения источников — отдельные явные полномочия.

Конфигурация

Установка среды выполнения — единственная команда, которая загружает файлы. Пакеты записи, кодирующие видео или GIF, требуют ffmpeg в PATH; пакеты стоп-кадров — нет.

Устранение неполадок

• no Chromium-class browser found: выполните snapref runtime install --runtime chrome-for-testing --channel stable.

• Сеанс отсутствует после простоя: именованные сеансы истекают через 10 минут; профиль остаётся до close --purge-profile или gc --apply.

• Устаревшая исполняемая ссылка: сделайте новый snapshot и используйте самую новую ссылку sr-….

• Отказ MCP-управления: установите SNAPREF_MCP_ALLOW_DRIVE=1 (или --allow-drive) и список разрешённых источников, если вы ограничиваете хосты.

• already recording после сбоя: следующий внутрипроцессный запуск восстанавливает заброшенное внутрипроцессное состояние. Отсоединённый запуск, завершившийся сбоем до установки PID, необходимо удалить: удалите $SNAPREF_HOME/recordings/<name> (по умолчанию ~/.snapref/browser/recordings/<name>). Если отсоединённый PID всё ещё активен, сначала остановите этот процесс.

• Сбой кодирования видео: установите ffmpeg; для стоп-кадров он не нужен. CLI выводит ограниченный stderr ffmpeg при сбое.

Apache-2.0. См. SECURITY.md, docs/VERSIONING.md, NOTICE, THIRD_PARTY_NOTICES.md и прилагаемые тексты third_party/licenses/ перед распространением.