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+Chrome 门控通过之前，不宣称支持 Windows。

包

• 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 驱动、主机读取、主机写入和来源授权是独立的 SNAPREF_MCP_* 权限。

截图默认全页。YAML/JSON 剧本可以声明 screenshot_mode: full-page 用于存档证据，或 screenshot_mode: viewport 用于精确折叠/焦点证据；单个步骤可以覆盖。全页捕获测量渲染后的文档，但不会触发特定于应用的滚动揭示。每个脚本回执记录有效模式和所测 PNG 宽度/高度。

验证

make verify
make verify-release

make verify 运行测试、竞态检测器、vet、原生编译、跨平台编译和发布契约检查。

make verify-release 还会两次构建发布工件。它要求两次构建的工件逐字节相同。

工件构建器仅使用本地模块缓存。它禁用依赖下载、工作区覆盖、用户 Go 设置和自动工具链下载。

实时 snapref self-test 验证水合快照就绪状态。它还验证跨开放影子根和同源框架的引用操作。

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 是策略门控的 MCP stdio 服务器；

• cmd/snapref 是独立 CLI 和实时自测。

独立的 skill 和 job-posting 命令仅生成通用类型提取。主机特定的交接在本模块之外。

黄金路径

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 驱动、主机读取、主机写入和来源授予是单独的显式权限。

配置

验证

GXP5

snapshot 是默认命令。eval 是显式的替代方案。MCP 驱动、主机读取、主机写入和来源授权是单独的显式权限。

配置

使用方法

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 驱动、主机读取、主机写入和来源授予是单独的显式权限。

Apache-2.0。参见 SECURITY.md、NOTICE、THIRD_PARTY_NOTICES.md 和捆绑的 third_party/licenses/。