navette — the browser for agents

navette — v1.9.0

面向 Agent 的浏览器。 一个小巧的 Rust 二进制程序，驱动操作系统自带的 WebView——无需 Chromium，无需下载，也不会造成内存灾难。

Navette 在法语中意为穿梭船——一艘载着 Agent 穿梭于各个页面之间的小船。它始终燃料充足（引擎随操作系统提供），轻巧到无需在意，还会过滤掉人类网络上的垃圾，让 Agent 不必操心。

单个 Rust 二进制程序，三种模式：

$ ls -lh target/release/navette
-rwxr-xr-x  1 user  staff   725K  navette

在 macOS 上安装后仅占用 725 KB（发布二进制文件会跟踪这一数据；用于已登录状态的 OS 钥匙串存储约占 100 KB）。Windows-x64 / linux-x64 使用 wry 后端。Playwright 占用 218 MB。Lightpanda 占用 96 MB（且无法截图）。这些数据均经过测量，可用一条命令复现（BENCHMARKS.md）：

• 在我们测量的所有指标上都快于 Playwright + Chromium——安装、冷启动、导航→读取（8 ms）、操作（1 ms）、峰值内存、爬取 100 个页面（0.9–2.8 s，与 Lightpanda 性能相当，差异在误差范围内，且比 Playwright 快约 2–3 倍）、真实网站成功率（95–100% 对比 85%）。
• 渲染页面的同时，爬取速度媲美 Lightpanda（通过零偏差 raw-CDP 探针测得，性能差异在误差范围内；Lightpanda 是最快的页面读取器，耗时 3.3–3.4 ms——它会解析部分 DOM，但无法渲染；navette 则是最快的完整渲染读取器：通过相同客户端测得为 17.9–19.4 ms，而 Chromium 为 28–34 ms）。
• Lightpanda 胜出的两项指标——新进程启动和峰值内存——就是渲染所付出的代价。 如果你的 Agent 只需要读取静态页面，请使用 fetch + readability；如果它需要 JS、会话、操作和视觉能力，那么这笔代价就是产品本身。

常见问题

为什么不用 Apple 的 Safari MCP 服务（2026）？ 理念相同，范围不同：navette 以 Agent 为先（8 个原语、幽灵窗口、常驻守护进程），开源，并从设计上支持跨平台（Windows 上的 WebView2 就是 Chromium，且预装）。Apple 的方案则围绕 macOS 和 Safari 打造。

为什么不直接用 fetch + readability？ 对于静态页面，就这么做——它胜过所有方案。navette 专为 fetch 无法处理的情况而存在：由 JS 构建的页面、登录、会话、表单、截图，以及像人一样操作。

为什么不用 ML 提取模型？ 这是两种取舍，并非排名先后——pulpie-mcp 属于这条路线中的 ML 方案。经过训练的提取模型能应对恶意 HTML——机构模板、被破坏的 CMS 输出——在这些情况下，DOM 遍历可能会选错节点；代价是每页约需 ~600 ms 的计算时间。navette 的原生 DOM 遍历每页约需 ~10 ms，在标记结构正常时表现更好，而大多数文档、新闻和开发工具页面都属于这种情况——也就是 Agent 实际阅读内容中的大部分。两层方案可以组合使用：如果某个目标的标记结构恶劣到原生提取会选出垃圾内容，就将该页面的原始 HTML 交给 ML 流程处理。

navette 是爬虫吗？ 不是——这是有意为之。navette 会对你提供的 URL 执行导航、读取、截图和操作；robots → sitemap → 链接发现属于更上层的功能，而非核心原语。如果爬虫的目标需要真正的浏览器引擎，就让它使用 navette。

截图保真度如何？ 从 v1.3+ 起，捕获由各引擎原生完成——捕获的是合成器实际绘制的内容，而非重新渲染的结果；截图尺寸与视口一致。要获得可重复的截图，请在导航前设置视口。目前尚未实现整页截图；我们如实记录这一点，而非用近似方案代替。

安全性如何？ 服务仅绑定到 127.0.0.1，拒绝非本地 Host 标头（DNS 重绑定防护；/health 除外），令牌比较采用恒定时间，代理 URL 在日志中会隐藏凭据。会话隔离由 CI 在每种引擎上强制验证——导入某个会话的 Cookie 不得出现在另一个会话的 Cookie 存储中，否则构建失败：macOS（每个会话使用非持久化 WKWebsiteDataStore）· Windows（每个会话使用一个 WebView2 配置文件 + InPrivate——仅使用 InPrivate 时，各控制器仍会共享同一个配置文件，#6）· Linux（每个会话使用新的 WebContext；Cookie 永不写入磁盘——HTTP 缓存/HSTS 仍会写入，#6）。跨运行的状态通过 state_export / state_import 显式迁移。Agent 的 JS 在操作系统的 WebKit 沙箱中运行，而非你的终端中。对于个人笔记本以外的使用场景，--token SECRET 会要求所有路由（/health 除外）都提供 Authorization: Bearer——MCP 主机通过 NAVETTE_TOKEN 环境变量进行连接。已登录状态应保存在操作系统钥匙串中，而非明文旁路文件中（#8）：navette state save NAME 会在守护进程内保存 Cookie 存储，仅返回元数据——请求携带名称，钥匙串保存机密信息；使用新二进制文件时，macOS 会再次提示（ACL），这相当于每个版本都会隐式征求同意。凭据的保护更进一步（第 2 阶段，已发布）：用户通过 navette creds set SITE 保存登录信息（从隐藏的 stdin 输入，并绑定到会话当前页面的确切来源），之后任何 Agent 都可以通过 POST /login {"site": SITE} 填写登录表单——密码在守护进程内部解析并注入页面；它绝不会出现在请求、响应或日志中，而且完全没有读取接口。在任何其他来源上都会拒绝填写——恶意页面或遭提示词注入的 Agent 既无法窃取机密信息，也无法将其发送到其他位置。双因素验证仍由用户处理（session_show）。唯一需要如实说明的限制是：填写时密码确实会传递到页面——这与人手动输入相同；来源绑定就是防护措施。

运维标志（serve）：--proxy URL（HTTP CONNECT / SOCKS5，wry 后端——macOS 使用系统代理）、--user-agent UA（针对单次 serve 的覆盖设置）、--idle-release MIN（释放空闲的 WebKit 会话，守护进程保持常驻）。

构建与运行

brew install slabbdev/tap/navette   # macOS arm64
cargo install navette-browser   # any platform, from source
docker run -i --rm ghcr.io/slabbdev/navette navette mcp   # container, stdio MCP (amd64+arm64)
navette serve --port 8765       # HTTP API on loopback
navette mcp                     # MCP stdio for agent hosts
navette state save NAME         # the session's login state → OS keychain
navette creds set NAME          # a login the agent can use but never see
navette install-daemon          # resident: warm from login

或从源代码构建：

cargo build --release          # rustup; macOS fully shipped — Windows (WebView2) / Linux (WebKitGTK) backends aboard
./target/release/navette serve --port 8765   # HTTP API on loopback
./target/release/navette mcp                 # MCP stdio for agent hosts
./target/release/navette install-daemon      # resident: warm from login, 24 ms first page
./target/release/navette uninstall-daemon

如果没有任何进程在监听，mcp 模式会自动启动 serve（如果端口已由另一个 navette 提供服务，则会礼貌地保持空闲）。常驻守护进程是一个启用了 KeepAlive 的 LaunchAgent——会话处于热状态时，Agent 感受到的冷启动时间会降至 24–37 ms。使用 --idle-release MIN 后，这段时间会有明显改进：空闲会话会被释放，之后的首个请求会通过预热路径重新预热，耗时 ~100 ms——守护进程本身不会退出。

HTTP API（仅限 127.0.0.1，JSON）

路由	请求体	返回值
GET /health	—	{ok, name, engine}
GET /sessions	—	包含 url + title 的会话
POST /navigate	{url, session?, with_content?, format?}	{ok, url, title[, content]} — with_content 会将读取操作合并为一次往返
POST /read	{session?, format?} markdown/text/html	{ok, content}
POST /screenshot	{session?}	PNG 字节
POST /click	{selector, session?, wait_navigation?}	{ok}（真实指针和鼠标事件——也可打开 Radix/HeadlessUI 菜单；可选择自动等待表单 POST 导航）
POST /type	{selector, value, session?}	{ok}（兼容 React 的原生 setter）
POST /evaluate	{js, session?}	{ok, result}
POST /wait	{selector, ms?, session?}	{ok}
POST /sessions/state	{session, store?}	cookies JSON——即已登录状态；使用 store 时，凭据包会以该名称存入 OS 钥匙串，并且只返回 {stored, origin, cookies}——凭据包绝不会通过网络传输
POST /sessions/load	{session, cookies} 或 {session, store}	{ok, imported[, origin, saved_at]} 从 JSON 或钥匙串恢复已登录状态
GET /states	—	已存储的状态——名称、来源、时间戳；绝不包含凭据包
POST /states/delete	{name}	{ok} 删除一项
POST /creds/set	{site, username, password, session}	{site, origin} — 人工步骤（CLI 会在隐藏的 stdin 上提示输入）；凭据绑定到会话页面的确切来源
GET /creds	—	站点 + 来源 + 用户名——绝不包含密码
POST /creds/delete	{site}	{ok} 删除一项
POST /login	{site, session?, submit?}	使用钥匙串中的凭据填写并提交登录表单——密码绝不会出现在请求、响应或日志中；除非会话位于凭据对应的来源，否则返回 403
POST /sessions/viewport	{width, height, session?}	{ok, width, height} 设置视口（默认值为 1280x800）
POST /sessions/show	{session?}	{ok, visible} 将会话窗口显示在屏幕上——带标题、可聚焦、居中；用于在会话中进行一次性人工登录
POST /sessions/hide	{session?}	{ok, visible} 将窗口收起（会话和状态保持不变）
POST /hover	{selector, session?}	{ok}（在元素中心触发 mouseover/mousemove）
POST /key	{key, selector?, session?}	{ok}（在获得焦点的元素上触发 keydown+keyup）
POST /scroll	{y?, selector?, session?}	{ok, y} 绝对滚动或滚动到视图中
POST /upload	{selector, filename, content_base64, mime?, session?}	{ok, files} — 使用内存中的内容填充文件输入框（DataTransfer；不弹出 OS 对话框）
POST /sessions/close	{session}	{ok}

会话会按需创建；只有在需要截图时才会附加幽灵窗口。

JS 对话框（alert/confirm/prompt）会在页面内自动处理：alert 会记录日志并执行空操作，confirm 会接受，prompt 会返回默认值——Agent 不会因隐藏的模态框而陷入死锁。

面向 Agent 宿主的 MCP

注册一次（ZCode 示例，工作区 .zcode/config.json）：

{ "mcp": { "servers": { "navette": {
    "command": "/abs/path/to/navette/target/release/navette",
    "args": ["mcp"]
} } } }

宿主会获得 19 个工具：navigate、read、screenshot（以 MCP 图像内容的形式返回——Agent 能看到 页面）、click、hover、type、key、evaluate、wait、scroll、upload、viewport、sessions、session_close、session_show / session_hide（将窗口显示在屏幕上，让人类登录，然后再将其隐藏——状态会保留）、login（从密钥链填写并提交——Agent 永远看不到密码）、state_export / state_import（Cookie——相当于 Playwright 的 storageState——可选 store 名称，用于将 Cookie 存储在操作系统密钥链中，使其绝不会通过网络传输）。

架构

src/main.rs          HTTP server (std::net), routes, agent-first JS snippets
src/mcp.rs           MCP stdio adapter + serve auto-start
src/webviewkit.rs    the kit contract — a trait every backend must implement,
                     so surface parity is compile-enforced (a backend that
                     misses a primitive or drifts on a signature won't build)
src/backend_macos.rs WKWebView via raw objc2 — ghost windows, lazy attach,
                     measured cold-start ordering (AppKit -> listener -> pre-warm)
src/backend_wry.rs   Windows (WebView2) / Linux (WebKitGTK) via wry + tao —
                     same surface, IPC-shim results, URL-matched navigation
src/backend_stub.rs  fallback for other targets (placeholder, same contract)

这 8 个基本操作与引擎无关；每个平台后端都是系统 WebView 上的一层薄封装，遵循这一精确接口——如今该接口由 WebviewKit trait 固定，未来手写的后端（直接使用 WebKitGTK/WebView2 FFI，不使用 wry）可接入这一接口。引擎策略：优先使用系统引擎，嵌入式引擎作为后备（WebView2 Fixed Version / 通过 apt 安装的 WebKitGTK / WPE）——参见 ONEPAGER.md。

状态

v1.9.0（2026-10-08） — 当前版本。macOS 原生按键输入已验证：show_window 是焦点门控（ghost 窗口会变为有标题的键窗口——在发送任何 CGEvent 前，Window Server 必须确认 isKeyWindow，因此按键绝不会落入其他人的应用）；单个字符通过附加的 unicode 字符串发送，因此在任何键盘布局下，传递的 e.key 都是 Agent 请求的按键（在 AZERTY 布局上已验证：a、Enter、Z、Tab、ArrowLeft 在原生模式下均以 isTrusted: true 成功传递）；只有在页面内验证传递成功后，才会报告 mode: native——若达不到这一要求，就会如实回退到合成输入。此外：为运行缓慢或争用严重的环境提供 NAVETTE_EVAL_TIMEOUT_SECS（默认值为 20，限制范围为 5–300），用于缓解问题 #7。现在，所有三种引擎都采用优先尝试原生输入的方式：SendInput（Windows，已完成端到端验证）、XTEST（Linux/X11）、CGEvents（macOS，已验证）。

v1.8.1（2026-10-08） — 会话隔离，所有引擎均由 CI 强制验证。会话隔离，所有引擎均由 CI 强制验证：每个会话都有自己的 WebView2 配置文件，且在 Windows 上启用 InPrivate（单独使用 InPrivate 会让所有控制器共用一个配置文件——已实测；命名配置文件可隔离各会话的 Cookie/存储/缓存）；macOS 使用非持久化的 WKWebsiteDataStore；Linux 使用隔离的 WebContexts；现在，跨会话 Cookie 泄漏会导致所有三种操作系统上的构建失败。安全加固：常量时间令牌比较、DNS 重绑定 Host 防护（非本地主机的 Host → 403，/health 除外）、日志中的代理凭据脱敏。此外：demo/signed-webhook — 密封的交易对手事件，将欺诈分析作为差异展示（HMAC 链接的模拟数据，解决 #5）；收费站数据集已采用 CC BY 4.0 许可，并加入 x402/付费墙信号（v1.8.0）。

v1.8.0（2026-10-08） — 可见的会话窗口 + 真实指针事件：session_show/session_hide 会将 ghost 会话显示在屏幕上，并保留页面状态，以便人类一次性完成登录（OAuth、2FA、验证码），之后再将其移回屏幕外；/click 会在鼠标事件之前分发 pointerover/pointerdown/pointerup，因此 Radix/headless-UI 组件会像面对人类操作时一样打开；macOS /wait 布尔值字符串化错误已修复（桥接程序报告 1，探测程序却期望 true——导致每个存在的选择器都“超时”）。内部实现：后端契约现为 webviewkit kit，并由编译器强制要求每个后端遵守。收费站第二轮：围墙网络基准测试除 robots.txt AI 条款和 llms.txt 外，还会测量 x402/付费墙信号（200 个 URL × 5 个类别；数据集位于 bench/，采用 CC BY 4.0 许可）。一套完整的可用配方已随 demo/dailydev 发布——可在没有 API 的网站上发布内容。 v1.7.0 (2026-10-07) — 原生键盘输入：POST /key 会优先尝试真实的操作系统级事件（macOS 上使用 CGEvent、Windows 上使用 SendInput、Linux 上使用 XTEST — isTrusted: true），并在失败时自动回退到合成事件派发，同时报告实际运行的 mode。Windows 是已通过端到端验证的原生输入平台；macOS 和无头 Linux 会正常回退（各平台的具体情况请参阅 issue #3）。运维版本：--token（HTTP API 的 Bearer 身份验证）、--proxy（每次服务运行使用 HTTP CONNECT / SOCKS5）、--user-agent（每次服务运行的覆盖设置）。空闲释放看门狗：navette serve --idle-release 15 会在 15 分钟没有请求后释放 WebKit 会话 — 守护进程继续常驻，内存得以回收，下一个请求到来时再按需预热（已在 macOS 和 Linux 上验证）。18 个 MCP 工具，包括文件上传（通过页面端 DataTransfer — 无需操作系统对话框）、滚动；已在 crates.io 上发布为 navette-browser（cargo install navette-browser → navette）；一个 bench 工作流会在全部三个引擎上测量导航、读取和截图性能。三个操作系统上的 CI 均通过：macOS（WKWebView）、Windows（WebView2）、Linux（WebKitGTK）。

近期版本：v1.8.1 — 跨引擎会话隔离（由 CI 断言）、恒定时间令牌、DNS 重绑定防护、docs/SECURITY.md · v1.8.0 — 可见的会话窗口、指针事件点击、macOS /wait 修复、webviewkit 工具包、tollbooth 第 2 轮 · v1.7.0 — 原生键盘输入（优先尝试 /key，如实报告 mode）· v1.6.0 — 运维版本（--token、--proxy、--user-agent）、linux-arm64 资源 · v1.5.0 — 空闲释放看门狗、tollbooth 基准测试工具、原生与 ML 提取方案之间的权衡文档 · v1.4.1 — 容器镜像（ghcr，amd64+arm64）、--help/--version、brew tap、官方 MCP 注册表条目 · v1.3.0 — 完整的平台一致性（各引擎的原生截图、Cookie 状态导出/导入、视口控制、所有平台均支持常驻守护进程、悬停与按键、自动处理对话框）。

已知缺口，直言不讳：真实的（操作系统级）鼠标输入、请求/响应网络拦截、操作系统文件对话框自动化。MIT。