Riffle

---

Riffle 是一个 MCP 服务和 CLI。它会运行带有网页 JavaScript 的 Chrome，并将每个页面作为可供 Agent 阅读和操作的文本交给它。

为何选择 Riffle

Agent 看到的就是用户看到的

哪些内容被遮挡、隐藏、置于主要位置、禁用、划线或截断，都会以文字写在对应行上。没有 HTML、CSS 或图片：Riffle 将页面转换成简短的文本行，让 Agent 直接读取这些事实，而不是从标记或像素中猜测。

modal d1 "Cookie preferences" covers=page
  text "We use cookies."
  button b1 "Accept all" primary
  button b2 "Reject"
main covered-by=d1
  h1 "Your cart"
  list
    item "Trail shoe 42" "€89" strike "€69" red | "Qty" | spinbutton f1 "Qty" ="1" | button b3 "Remove"
  button b4 "Checkout"

购物车被 Cookie 对话框挡住，旧价格被划掉，新价格显示为红色。covered-by=d1 会告诉 Agent，结账按钮被对话框遮挡。

上下文贯穿整个任务

首次查看后，每条回复都只包含发生变化的内容。点击上方页面中的“拒绝”后，完整回复如下：

- d1
- text "We use cookies."
- b1
- b2
~ main -covered-by=d1

每次查看也会占用令牌预算，因此长页面的成本由你设定：view interactive budget=800。

减少往返，缩短等待

Agent 编写一个程序，每行一个步骤，Riffle 会在一次调用中运行所有步骤。完整的登录流程只需一次往返：

goto https://shop.example/login
try click "Reject"
fill "Email" "[email protected]"
fill "Password" $secret:shop
click "Sign in"
expect url ~ /account
view interactive budget=800

每一步执行后，Riffle 都会等待页面完成响应并进入空闲状态，而不是固定等待一段时间：点击后约等一秒，页面加载后等几秒。程序会在首个失败步骤处停止，并说明失败的是哪一步以及原因。

无需鼠标、键盘或截图

Agent 可以根据页面上的文字或查看页面时获得的 ref 指定操作目标：click "Reject"、fill "Email" "[email protected]"、click b4。Agent 无需操控指针、瞄准坐标或读取图片。fill 可在一步中填写整个字段，press Enter 可指定要按的键。如果某个步骤无法执行，回复会说明阻碍：

failed line 1: click "Checkout": blocked: b4 covered-by d1 "Cookie preferences"

接下来，Agent 会编写一个先关闭对话框的程序。

与以下方式相比

Agent 当前使用的方式	代价	使用 Riffle
截图和按坐标点击	每个操作都要一张图片并进行一次往返，还要根据像素猜测	文本，每次调用可执行多个步骤
每次操作后获取页面快照或原始 HTML	每次都要将整个页面重新放入 Agent 的上下文	只包含变化的内容
将网页获取为 Markdown	可以阅读，但无法点击、填写或登录	真实浏览器：点击、填写、登录

安装

npx @noetive/riffle init --client claude-code

其他编辑器：--client cursor、copilot、kiro、antigravity。不带 --client 运行 init，它会配置检测到的编辑器。--dry-run 会显示更改，但不会写入。--keep-state NAME 会让 Agent 在多次运行之间保持登录状态；请参阅保持登录状态。

任何 MCP 客户端都可以使用以下条目：

{
  "mcpServers": {
    "riffle": { "command": "npx", "args": ["-y", "@noetive/riffle", "mcp"] }
  }
}

在原生 Windows 上，通过 cmd 运行 npx："command": "cmd", "args": ["/c", "npx", "-y", "@noetive/riffle", "mcp"]。init 会为你写入这种形式。

或者安装二进制文件：go install github.com/noetive/riffle/cmd/riffle@latest，也可以从发行版中获取一个。

Riffle 需要机器上安装 Chrome 或 Chromium。使用以下命令检查：

riffle doctor

Riffle 会运行自己的临时 Chrome。它绝不会访问你保存的密码或钥匙串，并会在停止时自行清理。

使用

你的 Agent 会获得两个工具。browser_run 接受一个程序，每行一个步骤，例如减少调用次数，缩短等待时间中的登录操作。browser_view 用于读取页面。

不确定语法？请查看 view help，或运行 riffle grammar。

步骤：goto back forward click dblclick fill select check press hover scroll upload wait expect dialog try view eval。 视图：outline、interactive、read、table REF、find "text"、expand REF、net、unseen。

在 Shell 中：

riffle run  < program.txt      # run a program
riffle view interactive        # read the current page
riffle close                   # end the session and its browser
riffle stop                    # end Riffle and every session in it

每个编辑器的 Agent 都有自己的浏览器，因此两个窗口绝不会操控同一个页面。它的 MCP 服务会在启动时于 stderr 中显示会话名称；riffle view -s NAME 会显示该 Agent 的页面。传入相同 -s NAME 的条目（例如 riffle mcp -s shared）会共用一个浏览器。

Riffle 会避免浏览器在机器上越积越多。无论有多少 Agent 使用 Riffle，同时最多运行四个浏览器（通过 riffle serve -max-browsers N 更改此设置）。需要另一个浏览器的 Agent 会等待现有浏览器结束，之后会收到占用浏览器的会话名称。闲置 15 分钟的会话会结束；下次使用时会从空白页面开始，并告知你这一点。编辑器停止其 MCP 服务时，该编辑器的会话也会结束；Riffle 无事可做 30 分钟后会退出。

保持登录状态

在编辑器条目中指定会话名称，Riffle 就会保留登录状态。Agent 登录一次后，下次启动编辑器时仍会保持登录状态。

npx @noetive/riffle init --client claude-code --keep-state shop

或者，手动设置：

{ "mcpServers": { "riffle": { "command": "npx", "args": ["-y", "@noetive/riffle", "mcp", "-keep-state", "shop"] } } }

• 会保留的内容。 每次调用后都会保存 Cookie 和站点存储，因此即使编辑器重启、Riffle 停止或浏览器崩溃，这些内容也会保留。重新启动时不会向任何站点发送请求：第一个请求由 Agent 自行发起。
• 保存位置。 启动时，Riffle 会在其 MCP 服务日志中显示文件名。只有你能读取该文件，但任何能读取它的人都可以使用其中的登录状态：请勿将其放入共享备份或同步文件夹。要让该会话退出所有站点，请关闭使用该名称的编辑器并删除该文件。从早期版本升级的 Riffle 可能还会在旁边的 riffle.state 文件夹中保留旧副本：也请将其删除。
• 一个名称，一个浏览器。 使用相同名称的编辑器条目会共用一个浏览器和一组登录状态。请为每个项目指定不同的名称，以便彼此隔离。名称只能包含小写字母、数字、- 和 _。
• 限制仍然有效。 使用 -allow-origin 启动的会话只会恢复其允许站点的登录状态；除非设置了 -allow-private，否则不会恢复私有地址的登录状态。限制未包含的内容会继续保留，供允许该内容的会话使用。
• 不会保留的内容。 每次调用结束时，只会保留 Agent 所在站点的存储，不会保留调用期间仅途经的站点，也不会保留来自其他站点的框架内容。最多保留 50 个站点的存储；最久未使用的站点会最先被移除。无法恢复存储的站点会通过 event unrestored 告知 Agent，会话会在不含该站点存储的情况下启动；该存储仍会保留。

可以用它做什么

• 从页面中提取表格。 table REF 无论页面标记如何，都会以 TSV 格式返回行。
• 查看页面调用了什么。 view net 会列出页面背后的 fetch 和 XHR 请求。
• 测试自己的 Web 应用。 像用户一样操作 localhost，并运行真实的页面 JavaScript。使用 -allow-private 启动 Riffle，使其可以访问本地地址：在编辑器的入口中运行 riffle mcp -allow-private，或在 shell 中运行 riffle serve -allow-private；这会取代已经运行但未启用该选项的 Riffle，并结束其会话。
• 在多次运行之间保持登录状态。 使用 -keep-state NAME 登录一次，下次启动编辑器时，Agent 仍会保持登录状态。参见保持登录状态。

页面会像在任何浏览器中一样实时运行，并在 Agent 思考时继续运行：倒计时、过期的登录状态或稍后打开的面板都会继续变化，下一条回复会说明发生了什么变化。

如果某个步骤未能按要求执行，Riffle 也会说明，例如表单提交被拒绝，这样 Agent 就能修正并继续操作。

默认安全

• 密钥以 $secret:name 的形式写入，并绑定到一个来源，绝不会回显给 Agent。
• 统计用户在页面上看不到的文本，并且仅在你提出要求时才显示，同时用标记注明这是页面数据。
• 如果某个控件的隐藏标签与其表面文字相矛盾，就会标记为 name-differs，并同时提供用户能看到的文字。
• 页面文本属于数据。回复会将其引用，因此页面无法冒充你的指令。
• 本地和专用网络地址默认关闭；使用 -allow-private 开启后，页面才能访问这些地址，以免页面将 Agent 引向你的网络或云元数据服务。
• 上传和 eval 默认关闭；-allow-origin 和 -upload-dir 会限制会话可以访问的位置以及可以发送的内容。从 shell 启动的 Riffle，或在崩溃后启动的 Riffle，如果未指定 -allow-private、-allow-origin、-allow-eval 或 -upload-dir，会沿用上次运行时的设置。指定其中任一项都会设置全部四项，因此单独使用 -allow-private=false 会恢复默认设置。
• 登录状态会随会话结束，除非使用 -keep-state NAME 保留。保留的登录状态存储在只有你能读取的文件中；删除该文件即可清除。会话只能恢复其权限范围内的登录状态。

它不是什么

• 不是截图工具。如果答案只存在于像素中，Riffle 就无法提供给你。
• 不是绕过机器人防护或 CAPTCHA 的方法。它不会尝试绕过。每个请求都会注明来自 Riffle：用户代理以 Riffle/<version> 结尾。
• 不是用于视觉回归的测试框架。请使用专门为此构建的工具。
• 仅支持 Chrome 和 Chromium。iframe 内的内容会标记为 content-not-shown，而不会被读取。
• 打开邮件或电话应用的链接不会执行任何操作；新窗口会在同一标签页中打开，因此需要弹出窗口的流程无法使用。

与 Noetive 的其他产品协同工作

Riffle 可以独立运行，也可以与另一项 Noetive 服务搭配使用：

• Semantik 是一个语义消息代理。读取页面的 Agent 可以发布发现的信息，其同伴可以按含义找到这些信息，无需事先约定主题名称。

开发

make build
make test
make lint
go test -tags integration ./...   # drives a real Chrome

请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明报告安全问题。

许可证

ISC。版权所有 (c) 2026 Noetive.io