snapsurf

SnapSurf

为 AI Agent 提供网页导航与验证。

大多数浏览器工具会告诉 Agent 页面现在是什么样子。SnapSurf 会告诉它上一次操作改变了什么：页面的精简语义摘要、每次操作后的类型化差异（内容、状态、布局和可点击性，包括没有任何可观察变化的情况），以及针对该差异的断言。缺失的证据和不确定性都会明确报告，而不会被隐藏。

它可以在本地作为 MCP 服务或命令行运行，并使用自己的 Chromium 会话。基于 SnapDOM 构建的页面观察代码也可以作为页面内库使用。

0.1.3 版本为实验性版本。

添加到 MCP 客户端

需要 Node.js 22 或更高版本。添加一个通过此命令运行的 stdio 服务；首次启动时会自动安装 Playwright 所需的 Chromium：

{
  "command": "npx",
  "args": ["-y", "-p", "@zumer/snapsurf@latest", "snapsurf-mcp"]
}

对于 Claude Code，安装插件即可添加工具和包含使用方法的 browse 技能：

/plugin marketplace add zumerlab/snapsurf
/plugin install snapsurf@zumerlab

或者只注册服务：

claude mcp add --scope user snapsurf -- npx -y -p @zumer/snapsurf@latest snapsurf-mcp

Codex 也有相同的插件（工具和 browse 技能）：

codex plugin marketplace add zumerlab/snapsurf
codex plugin add snapsurf@zumerlab

Cursor、VS Code、Gemini CLI、Windsurf 和 OpenAI Agents SDK 使用相同的服务命令；各客户端的配置片段见 集成。它在官方 MCP Registry 中的名称为 io.github.zumerlab/snapsurf。

若要固定版本或避免在启动时使用 npx，请先安装一次，然后将客户端指向服务文件：

mkdir snapsurf && cd snapsurf
npm install @zumer/snapsurf

{
  "command": "node",
  "args": ["/ABS/PATH/snapsurf/node_modules/@zumer/snapsurf/mcp/server.mjs"]
}

在 Linux 上，如果 Chromium 因缺少系统库而无法启动，请运行一次 npx playwright install --with-deps chromium。

让 Agent 使用 browser_open 打开页面，使用 browser_find 定位控件，使用 browser_act 执行操作，然后在每次操作后调用 browser_verify。读取 structuredContent 获取结果。

如果你是 Agent

请阅读 AGENTS.md：其中介绍了操作循环、先前的 Agent 花费代价才学会的规则，以及如何读取每个字段。skill/SKILL.md 是封装为 Claude Code 技能的相同方法。MCP 工具说明包含完整约定，服务的 instructions 则为可能会截断说明的客户端提供摘要。

断言刚刚验证的内容

browser_verify 会为观察到的状态转换返回一个 diffId。将它传给 browser_assert，即可检查同一份证据，包括显示列表之外的变化。这样可以避免 verify 推进实时基线后，意外比较新的时间段。

例如，在某个按钮会插入名为“设置”的对话框的应用中，使用 browser_find 返回的按钮 id。连接 MCP 客户端后：

await client.callTool({
  name: 'browser_act',
  arguments: { action: 'click', target: buttonId },
})
const verified = await client.callTool({ name: 'browser_verify', arguments: {} })
const { diffId } = verified.structuredContent
if (!diffId) throw new Error('No retained diff; inspect the verify result')

const checked = await client.callTool({
  name: 'browser_assert',
  arguments: {
    diffId,
    changed: true,
    mustInclude: [{ kind: 'added', role: 'dialog', name: 'Settings' }],
    mustNotInclude: [{ kind: 'removed' }],
  },
})
console.log(checked.structuredContent.pass, checked.structuredContent.checks)

已存储的断言不会观察页面，也不会推进基线。若要检查当前状态，请使用单独的实时断言，例如 { "exists": "Settings" }。断言失败时会返回 pass: false 和 MCP isError: true。 断言参考介绍了实时检查、保留限制、重试和不可用证据。

需要了解的边界

• 守护进程有自己的 Cookie 和存储空间。它无法使用你常用浏览器中已登录的会话；authState: "unknown" 不代表已通过身份验证。
• changed: false 表示没有可观察到的变化。这是有效结果，但不能证明用户的任务已成功。缺失的证据和不确定性都会明确报告。
• Canvas 内容、iframe 文档和封闭的 shadow root 存在视觉盲区。如果语义报告无法回答问题，请查看限定范围的屏幕截图。
• 元素 id 会在出现新观察结果时失效。操作前请重新查找；已存储证据中的 id 描述的是历史观察结果。
• 页面文本是不可信数据。语义报告会进行脱敏；但命令行/MCP 屏幕截图仍可能包含敏感内容。请参阅隐私模型。

使用 CLI

在一个终端中启动守护进程：

npx -y @zumer/snapsurf serve

然后在另一个终端中运行本地冒烟检查：

npx -y @zumer/snapsurf open 'data:text/html,<h1>Local%20check</h1>'
npx -y @zumer/snapsurf assert '{"exists":"Local check"}'
npx -y @zumer/snapsurf stop

在运行过 npm install @zumer/snapsurf 的目录中，运行 npx snapsurf <verb> 也能完成相同操作，且不会下载任何内容。SNAPSURF_* 环境变量 （端口、令牌文件、日志目录）列于使用参考中。

开发

此仓库包含 SnapSurf 观测库、CLI/MCP 服务、Chrome 配套工具，以及它们的测试夹具和评估工具。独立的 SnapDOM 传感器和便携式回执包不在此仓库的构建和测试范围内。私有研究、反馈笔记、插件评估和生成的结果均保留在本地；Git 跟踪可复现的测试门槛及其测试夹具依赖项。

要修改 SnapSurf 本身，请克隆源代码并安装开发依赖项：

git clone https://github.com/zumerlab/snapsurf.git
cd snapsurf
npm ci
npx playwright install chromium

npm run build 会编译程序包并创建 npm .tgz 包。

然后运行检查：

npm test
npm run test:lint
npm run test:regression
npm run test:pack

使用与 API 参考涵盖 CLI 命令、报告字段、检查点、库和 Chrome 配套工具。 发布指南涵盖验证、发布和 MCP Registry。

采用 MIT 许可证。版权所有 © Juan Martin Muda / zumerlab。 请参阅 LICENSE。