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

楔子回执位于此检出中：

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 检查延迟水合、开放影子 DOM 和同源 iframe，然后点击全部三个。demo mcp-policy 不启动 Chrome。demo ref-integrity 需要受管运行时。

GitHub Actions 的 go 和本地 make verify 通过 -short，因此即使执行 make init 后也不会启动 Chrome。Ubuntu 的 self-test 作业安装 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 回执位于此检出中，不在该标签中。在物理 Windows+Chrome 门控通过之前，不宣传 Windows 支持。

包

• browser：会话、CDP、快照/引用、可操作性、证据、技能；

• contract：类型化操作/权限/结果注册表；

• script：YAML/JSON/Starlark 可重复工作流引擎；

• mcp：策略门控的 MCP stdio 服务器；

• cmd/snapref：独立 CLI、实时自检和检出演示回执。

独立的 skill 和 job-posting 命令仅输出通用类型化提取。主机特定的产品交接在此模块之外。

Related MCP server: ChromePlayMCP

证明

这两个回执是公开楔子。它们不是 example.com YAML。

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 验证水合快照就绪性。它还验证跨开放影子 DOM 和同源框架的引用操作。该命令是机器回执（--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 是仅用于发布和基准工具中有界子进程取消的 vendored 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 的录制包需要 PATH 上的 ffmpeg；静态截图包不需要。

故障排除

• 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 在失败时打印有界的 ffmpeg stderr。

Apache-2.0。重新分发前请参阅 SECURITY.md、docs/VERSIONING.md、NOTICE、THIRD_PARTY_NOTICES.md 和捆绑的 third_party/licenses/ 文本。