SnapRef

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

Тег v0.2.0-rc.1 — это опубликованный неподписанный предварительный выпуск. Он включает self-test. Он не включает demo.

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

Квитанции wedge находятся в этой рабочей копии:

go run ./cmd/snapref demo mcp-policy
go run ./cmd/snapref runtime install --runtime chrome-for-testing --channel stable
go run ./cmd/snapref demo ref-integrity

self-test проверяет отложенную гидратацию, открытые теневые корни и iframe того же происхождения, затем нажимает на все три. demo mcp-policy не запускает Chrome. demo ref-integrity требует управляемого рантайма.

GitHub Actions go и локальный make verify проходят с -short, поэтому они не запускают Chrome даже после make init. Задание self-test на Ubuntu устанавливает Chrome for Testing и запускает snapref self-test и snapref demo ref-integrity. demo mcp-policy покрывается go test.

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

Статус: опубликованный неподписанный предварительный выпуск v0.2.0-rc.1 на https://github.com/nstranquist/snapref. Квитанции demo wedge находятся в этой рабочей копии, а не в этом теге. Поддержка Windows не анонсируется, пока не пройдёт физический шлюз Windows+Chrome.

Пакеты

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

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

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

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

• cmd/snapref: автономный CLI, живой self-test и демонстрационные квитанции рабочей копии.

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

Related MCP server: ChromePlayMCP

Доказательства

Эти две квитанции — публичный клин. Это не YAML с example.com.

go run ./cmd/snapref demo mcp-policy
go run ./cmd/snapref demo ref-integrity

Смотрите examples/mcp-policy/ и examples/ref-integrity/. Говорите о SnapRef как о ядре под хост-адаптером, а не как о втором бренде автоматизации браузера.

Золотой путь

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 на управление, чтение хоста, запись хоста и происхождение — отдельные полномочия 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 проверяет готовность гидратированного снимка. Он также проверяет активацию ссылок через открытые теневые корни и iframe того же происхождения. Эта команда — машинная квитанция (--json). GitHub Actions запускает её на Ubuntu после snapref runtime install --runtime chrome-for-testing. Локальный make verify проходит с -short и не запускает Chrome. После make init живыми квитанциями являются snapref self-test, snapref demo ref-integrity и make test-live.

snapref demo mcp-policy — это квитанция разрешений на управление/происхождение. snapref demo ref-integrity — это квитанция устаревшей ссылки: снимок, клик по sr-…, снова снимок, старая ссылка закрывается с ошибкой.

make release-dist воспроизводимо собирает архивы без CGO для 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 с политиками. Разрешения на управление, чтение хоста, запись хоста и происхождение — отдельные полномочия.

• 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 на управление, чтение хоста, запись хоста и происхождение — отдельные явные полномочия.

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

Установка рантайма — единственная команда, которая загружает файлы. Пакеты записей, кодирующие видео или 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/ перед распространением.