navigera

navigera

navigera — 为 AI Agent 提供极快的浏览器自动化能力，可从 shell 使用，每一步执行一条命令。 它是一个原生二进制文件（Rust，无需 Node），可直接使用 Chrome DevTools Protocol：

• 它将页面读取为精简的无障碍树，并提供 [ref=N] 句柄。
• 它通过真实的鼠标和键盘事件执行操作。
• 具名会话背后的预热浏览器会在多次 shell 调用之间持续运行。
• 新标签页、iframe、shadow DOM 以及 alert/confirm 对话框都会由 它自动处理。

为了更美好的地球，让软件运行得更快——减少能耗、减少算力消耗，为生活留出更多时间。

安装

curl -fsSL https://raw.githubusercontent.com/andrey-usa/navigera/master/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/andrey-usa/navigera/master/install.ps1 | iex

也可以使用包管理器——每种方式都会安装相同的预编译二进制文件：

渠道	命令
npm	npm install -g navigera（或 npx navigera …）
pip / uv	pip install navigera · uv tool install navigera
Cargo	cargo install --locked navigera
Homebrew	brew install andrey-usa/tap/navigera
Scoop	scoop bucket add andrey-usa https://github.com/andrey-usa/scoop-bucket 然后运行 scoop install navigera

然后将使用指南提供给你的 Agent：

navigera install-skill        # -> ./.agents/skills (Gemini CLI, Codex, Cline, Kilo, …)
                              #    --claude -> ./.claude/skills, --continue -> ./.continue/skills

支持 Linux、macOS 和 Windows。在 Windows 上，会话套接字是一个仅接受 客户端出示随机令牌的回环 TCP 端口；该令牌来自临时目录中的会话文件。CDP 通过 DevTools WebSocket 运行，Chrome 则位于关闭时会终止进程的作业对象中，因此 即使 navigera 退出，Chrome 也会随之退出。

navigera 会自行查找 Chrome：$CHROME_BIN、系统 Chrome、 Chromium 或 Edge，或者由它自行安装的版本。若要实现最快的冷启动， navigera install-browser 会从 Google 的 Chrome for Testing 下载 chrome-headless-shell 到 navigera 自己的缓存中：它是去除了浏览器 UI 层的同款 Chrome。在 基准测试中，它将冷启动时间从 0.32 s 缩短到 0.11 s，并将脚本会话 时间从 0.66 s 缩短到 0.32 s。安装后，无头会话会使用它，有头会话则 使用系统 Chrome（对于没有 Chrome 的机器，navigera install-browser chrome 也会将完整的 Chrome 安装到该处）。设置 $CHROME_BIN 即可显式选择。

使用（Agent 和用户）

navigera -s work start                      # warm headless browser behind a local socket
navigera -s work goto example.com
navigera -s work --raw ax                   # page as an indented tree, [ref=N] on actionable nodes
navigera -s work click 12                   # act on a ref
navigera -s work fill 31 "hello" && navigera -s work press Enter
navigera -s work wait --text "Saved"
navigera -s work quit

page "Checkout — Acme" http://shop.test/checkout
- main:
  - heading "Checkout" [level=1]
  - textbox "Full name" [ref=21]
  - combobox "Country" [ref=22] value="Select…" options: "Canada", "Mexico", …
  - radio "Express (1–2 days)" [checked, ref=25]
  - Iframe "Card payment":
    - document "Card details":
      - textbox "Card number" [ref=41]
  - button "Place order" [ref=30]

命令包括 goto、ax、click、fill、type、press、select、 hover、drag、scroll、upload、wait、eval、back/forward/reload、 screenshot、pdf、tab-* 命令、dialog 和 quit；使用 get 和 is 获取单个值，使用 console 和 network 查看页面记录和获取的内容， 使用 cookies、storage 和 state save|load（将 cookies 和 localStorage 保存为一个 JSON 文件）处理登录，使用 set 设置视口、设备、媒体、地理位置 等，并使用 route 让请求失败或返回响应。

• 目标： 可通过 ref、--selector <css>、 --text "<visible text>"、--role/--name、--label、--placeholder 或 --testid 指定元素。
• 输出： 每条命令都会输出一行 JSON，或使用 --raw 仅输出结果。
• 帮助： navigera help <command>。
• Agent 指南： 与版本匹配的指南位于 skills/navigera/SKILL.md， 也可通过 navigera skill 查看。
• 参考文档： docs/navigera.md 提供完整参考， llms.txt 是面向大模型的索引。

将你的浏览器交给 Agent。 以下三种方式按直接程度到通用程度排列：

方式	Agent 获取的内容	要求
start --attach	你正在运行的 Chrome 本身，位于单独窗口中：你的登录信息、设置、扩展程序，均为实时状态	Chrome 144+，在 chrome://inspect/#remote-debugging 中开启一次远程调试，并点击 Allow
start --profile agent --from chrome	一个独立浏览器，其中载入了你 Chrome 配置文件中登录信息的副本（cookies、网站存储、已保存的登录信息）；你可以继续工作，同时让它以 --headless 运行	任意 Chrome；同一台机器和用户。在 Windows 上，复制时请关闭 Chrome（它会锁定 cookies）
state save / state load	会话的 cookies 和网站存储，以文件形式保存，可用于任何其他机器或 CI 作业	无；一个包含 cookies 和网站存储的 JSON 文件

反过来，show 会将无头会话显示在用户的屏幕上，保留相同的标签页和登录信息，以便用户完成只有他们才能完成的步骤（登录、2FA 提示、CAPTCHA）；之后 hide 会将其隐藏。MCP 客户端也可通过 browser_handoff 使用同样的功能。

navigera profiles 会列出可移交的内容：每个已安装浏览器的配置文件（名称、已登录的邮箱）、--attach 当前是否可以连接，以及 navigera 自己的 --profile 浏览器。不带 --from 的 --profile work 是一个需要你自行登录的持久浏览器。无论哪种方式，navigera 都会在独立窗口中运行；quit 只会断开连接，而 quit --close-browser 会等待配置文件可用。

自然模式。 --natural 会让无头浏览器表现得像普通浏览器：用户代理中不会出现 HeadlessChrome（页面、workers、请求标头均如此），并使用真实的屏幕尺寸。所有模式下，navigator.webdriver 都为 false，且 navigera 从不传递 --enable-automation。它不是 CAPTCHA 求解器，也不会伪造指纹：它就是一个替你运行的普通 Chrome。 详情见：docs/navigera.md。

程序也可以通过管道保持一个浏览器运行：navigera serve 会读取 stdin 中每行一条的 JSON 命令，例如 {"id":1,"op":"goto","url":"https://example.com"}。会话套接字使用 相同的协议。

IDE Agent（MCP）

navigera mcp 是一个 Model Context Protocol 服务，适用于 Cline、Roo Code、Kilo Code、Continue、VS Code、Claude Desktop 和 Cursor，提供与 CLI 相同的树、refs 和 等待功能，并且工具列表比其他浏览器 MCP 服务更精简 （约 14 KB；数字见下方基准测试）。将其添加为 {"command": "navigera", "args": ["mcp"]}；也可以不安装任何内容，使用 {"command": "npx", "args": ["-y", "navigera", "mcp"]}；各客户端的配置片段 见 docs/navigera.md。可以运行 shell 命令的 Agent（Kilo、Cline CLI、Gemini CLI、Codex）可直接使用 CLI 和 技能：navigera install-skill 会将技能写入它们查找技能的位置 .agents/skills。

由快速模型处理决策（可选）

Agent 原本需要遍历一整页树并调用一次大模型才能完成的两个小决策——哪个元素以及操作是否成功——可以交给 System One 模型处理： 设置 TYPESAFE_API_KEY 时使用 TypeSafe 的 Jev，或者使用通过 NAVIGERA_DECIDER_URL 配置的任何具有相同 API 的端点。

navigera -s work click --find "accept the cookies"   # acts on the element the model picks
navigera -s work check "Is an error message shown?"  # {"yes":0.02,"answer":false}

find 会返回 ref、其概率以及排名靠后的候选项；低于 0.5 时，--find 会拒绝操作并列出候选项。配置了决策器时，start 会报告 "decider"，MCP 客户端也只有在这种情况下才会获得 browser_find 和 browser_check。否则不会有任何内容离开本机；输入的值会以 (filled) 形式发送。

测量结果（2026-10-14）。 在 39 个答案已知的决策中，Jev 对 25/25 个元素选择正确，并对 14/14 个是/否问题回答正确（中位数 151 ms；39 个决策总计 $0.0086）。Gemini 3.5 Flash-Lite 读取同一棵树时，答对 23/25 个元素和 14/14 个问题（中位数 724 ms），并有一次选择了页面中埋入文本所指向的按钮。在 Agent 评估中，Gemini CLI 被要求优先在两个大型参考页面（树大小为 56–95 KB）上使用 --find，所用 Gemini 令牌约为读取树的运行结果的一半（114–119K，而中位数为 250K；样本较小）。未收到提示时，它会读取树，且从未使用决策器。详情和注意事项： docs/multi-model.md。

再次测量（2026-10-21，运行 39530836547）。 在 78 个决策中（50 个元素、28 个是/否问题，包括公共页面），Jev 全部选对 50/50 个元素，答对 27/28 个问题，中位数为 80 ms，全部决策总计 $0.017；读取同一棵树的 DeepSeek-V4.1-Flash 也以相同结果答对 50/50 和 27/28，中位数为 2.0 s。两者都没有遵循页面中埋入的文本。由于 start 和长树会告知 Agent 如何使用决策器，Gemini CLI 在未收到提示时于 15 次运行中使用了 3 次；在提示要求使用时，15 次运行中使用了 14 次（运行 39561380436，每种条件下对五项任务各运行三次）；每次运行的令牌中位数分别为：未使用决策器时 199K，使用决策器时 172K，收到提示时 190K。对于此样本量，这些差异处于运行间噪声范围内。

支持的浏览器

CI 会在以下浏览器上运行完整的端到端测试套件：

• 当前的 Chrome Stable 及其之前的 三个里程碑版本 （约四个月的版本，涵盖 Extended Stable），均来自 Chrome for Testing；
• chrome-headless-shell；
• Chrome Beta，作为非阻塞的早期预警；
• 运行器自带的 Chrome，支持 Linux 和 Windows。

测试套件每周运行，也会在每次推送时运行，因此能在新 Chrome 版本影响 Agent 之前发现问题。在首次运行中，该矩阵发现了两个仅用运行器自带 Chrome 时未发现的实际 bug：Chrome 151 在使用某个自动化标志（--disable-features=OptimizationHints，通过 chrome-bisect.yml 二分定位）时发生段错误；Chrome 153 上，通过 Enter 键提交的表单会在重定向完成前返回。两个问题现已修复。

每次运行也会检查 CDP 协议正确性。navigera 会记录发送的每条命令（NAVIGERA_CDP_TRACE），而 tools/cdp_check.py 会根据该浏览器提供的 /json/protocol，验证每个方法、参数和枚举值。使用已弃用或未知内容会导致构建失败。Edge 和 Brave 则通过基准测试覆盖。

Lightpanda 1.0（--engine lightpanda）也会在 CI 中运行相同的端到端测试套件，测试版本为 1.0.1 和 nightly。它采用不同的引擎（单个标签页、无布局），因此 navigera 会补足其 CDP 未提供的内容：ax 中的 Shadow Root 和密码字段、confirm()/prompt() 的回答，以及点击触发的导航。仍存在的差异列于 docs/navigera.md。

基准测试

每个驱动都使用同一个无头浏览器执行相同的脚本会话（启动 → 前往列表页 → 执行标题/数量/提取评估 → 填写并点击筛选器 → 执行可见数量评估 → 截图 → 打开新标签页 → 前往详情页 → 执行标题/行数评估 → 关闭）。测试夹具是确定性的本地数据（包含 500 张卡片的列表、 包含 1000 行的详情页）。通过 .github/workflows/bench.yml 在 CI 中运行。

参测项	会话耗时（3 次取最佳）	热评估平均耗时（200 次）	冷启动（5 次取最佳）	驱动 CPU（自身）	驱动峰值 RSS（自身）	浏览器内存（PSS）
nv-shell（本仓库使用 chrome-headless-shell）	0.34s	0.39 ms	0.09s	<10 ms	7 MB	234 MB
nv-brave（本仓库使用 Brave）	0.65s	0.50 ms	0.34s	<10 ms	7 MB	666 MB
nv-ws（本仓库使用 Chrome、WebSocket）	0.67s	0.61 ms	0.29s	10 ms	7 MB	374 MB
nv-serve（本仓库使用 Chrome）	0.67s	0.62 ms	0.31s	<10 ms	7 MB	341 MB
gorod（go-rod 0.116.2，Go）	0.73s	0.52 ms	0.30s	40 ms	20 MB	370 MB
nv-edge（本仓库使用 Edge）	0.74s	0.45 ms	0.39s	<10 ms	7 MB	774 MB
chromiumoxide 0.7（Rust）	0.83s	0.87 ms	0.39s	20 ms	9 MB	424 MB
chromedp 0.19.1（Go）	1.02s	0.69 ms	0.48s	30 ms	8 MB	475 MB
chromey 2.x（Rust，维护中的 chromiumoxide 分支）	1.03s	0.99 ms	0.35s	50 ms	22 MB	465 MB
puppeteer-core（Node）	1.05s	0.85 ms	0.64s	0.38 s	80 MB	408 MB
playwright-core（Node）	1.26s	1.43 ms	0.78s	0.68 s	150 MB	423 MB
nv-lightpanda（本仓库使用 Lightpanda，1 个标签页）	0.18s	0.33 ms	0.11s	<10 ms	7 MB	14 MB

测量于 2026-10-26，环境为 GitHub 托管的 ubuntu-latest（AMD EPYC 7763 64-Core Processor — 4 vCPU · Chrome 155.0.8059.39）。 所有驱动提取的数据和计数均逐字节一致（正确性门槛）；耗时取 N 次中的最佳值。 每周都会重新运行此排行表（bench.yml），使用最新的参测版本。GitHub 运行器的性能会因运行而异，因此请比较同一次运行中的各行。

驱动 CPU/RSS 的测量方式。 每个驱动的自身 utime+stime，在回收僵尸进程前从其 /proc/<pid>/stat 读取（使用带 WNOWAIT 的 waitid），以及它自身的 VmHWM。内核以 10 ms 为单位统计 CPU 时间，因此低于约 50 ms 的数值可视为相同。这里不使用 wait4：其 rusage 为 RUSAGE_BOTH，会累加驱动回收的所有子进程的开销。navigera、chromedp、puppeteer 和 playwright 会对其 Chrome 调用 wait()，因此 wait4 会将 Chrome 的 CPU 和 RSS 计入它们；而 go-rod（其 leakless 助手会回收 Chrome）和 chromiumoxide 则不会被计入。此表的早期版本报告的正是这一测量偏差（“0.82s vs 0.03s”）。浏览器内存指整个浏览器进程树（所有 renderer/GPU/utility 进程），每 250 ms 对 PSS 求和采样一次（共享页面只计一次）。

如何解读此表。 会话耗时排名：nv-shell 0.34s、nv-brave 0.65s、nv-ws 0.67s、nv-serve 0.67s、gorod 0.73s、nv-edge 0.74s、chromiumoxide 0.83s、chromedp 1.02s、chromey 1.03s、puppeteer 1.05s、playwright 1.26s。navigera 的最佳成绩 （nv-shell）在 11 个参测项中排名第 1；在常规 Chrome 上，nv-serve（0.67s）也快于最快的其他驱动 gorod（0.73s）。所有原生驱动（navigera、 go-rod、chromiumoxide、chromedp）的自身 CPU 耗时都只有几十毫秒或更少；Node 驱动则耗时数百毫秒，且自身 RSS 为 80–150 MB。

真实场景（公共互联网，3 次测试取最佳结果）

访问 example.com → 标题/h1：12 项中 12 项通过；nv-lightpanda 0.19s、nv-shell 0.22s、gorod 0.41s、nv-serve 0.48s、chromey 0.48s、chromiumoxide 0.49s、nv-ws 0.49s、nv-brave 0.52s、nv-edge 0.56s、chromedp 0.61s、puppeteer 0.74s、playwright 0.86s。

浏览 GitHub（滚动 awesome-list 并点击进入 trending）：12 项中 12 项通过；gorod 3.57s、nv-shell 3.85s、chromiumoxide 3.93s、chromey 3.97s、nv-ws 4.09s、nv-lightpanda 4.09s、puppeteer 4.19s、nv-brave 4.20s、nv-serve 4.30s、chromedp 4.42s、playwright 4.48s、nv-edge 4.74s。 实时页面会在不同测试轮次之间发生变化，因此这些数据仅供参考，不属于 正确性门槛。（滚动检查过去会对所有驱动随机失败： GitHub 设置了 CSS scroll-behavior: smooth，因此读取 scrollY 时动画尚未结束； 现在参与比较的工具会使用 behavior: 'instant' 滚动。）

chrome-headless-shell（与 Chrome 版本相同，但没有浏览器 UI 层）：冷启动 0.28s → 0.08s，会话 0.60s → 0.34s，浏览器内存 370 MB → 225 MB。

CDP 传输 A/B 对比（相同版本和测试轮次）：--remote-debugging-pipe（Linux/macOS 上的默认方式） 与 DevTools WebSocket 端口：冷启动 0.28s 对比 0.30s， 会话 0.60s 对比 0.63s。速度没有差异：WebSocket 握手本身约需 10 ms。管道是默认方式还有两个原因： 它不会打开可供其他本地进程连接的 TCP 端口；Chrome 会在 navigera 退出时随之退出（其命令管道上的 EOF），因此被终止的 Agent 不会遗留浏览器 （tests/edge_cases.rs：使用 WebSocket 端口时，浏览器的生命周期会长于其驱动）。 Windows 上这里没有管道传输方式，因此使用 WebSocket，并通过关闭时终止的 作业对象提供相同的保证（killed_session_server_takes_its_browser_down 也会在该平台运行）。

此版本与上一版本，在同一台机器和同一测试轮次下的对比（nv-baseline， 由阶梯测试的 baseline_ref A/B 使用上一版 master 构建）： 会话 0.62s → 0.60s（-3%），冷启动 0.30s → 0.28s（-5%），每个会话的浏览器 CPU 时间 1.14s → 1.16s。现在会话还会记录页面的日志和请求（console、network）。

navigera 的冷启动耗时分布（NAVIGERA_TIMINGS，最佳结果）：浏览器启动 159 ms，首个页面 110 ms，关闭 2 ms。

Agent 工具（脚本运行，暖会话，3 次测试取最佳结果）

Agent 的工具调用如何驱动浏览器：CLI 工具每一步都会运行一个进程（一个 shell 工具），MCP 服务则在持久连接上每一步发送一次 tools/call。使用相同的标准会话，并额外进行一次页面快照。

工具	类型	总用时	每步平均用时	快照	快照大小	门槛
navigera（本仓库）	CLI	0.85s	44 ms	180 ms	36 KB	✓
chrome-headless-shell 上的 navigera	CLI	0.49s	33 ms	150 ms	36 KB	✓
agent-browser（Vercel Labs，Rust）	CLI	1.29s	94 ms	198 ms	73 KB	✓
playwright-cli（Microsoft）	CLI	10.08s	804 ms	422 ms	50 KB	✓
Playwright MCP（Microsoft）	MCP	5.32s	403 ms	76 ms	50 KB	✓
Chrome DevTools MCP（Google）	MCP	3.25s	201 ms	105 ms	34 KB	✓

每步用时包括进程启动（CLI）或 JSON-RPC（MCP）、与守护进程之间的通信，以及 CDP 操作。playwright-cli 和 Playwright MCP 共用 Playwright 的工具 后端，该后端会在每次操作后固定等待 500 ms（timeouts.settle）；playwright-cli 还会为每一步启动一个 Node 进程。

Lightpanda（实验性）以 0.18s 通过相同的正确性门槛，浏览器内存约为 14 MB。它没有 渲染引擎，且只有一个标签页（会话会在同一个标签页中打开第二个页面），因此单独列出，不纳入 Chrome 系列排名。

Agent 评测：通用 Agent 如何使用每种工具

基准测试衡量脚本化步骤的耗时。Agent 评测则提出了对 Agent 来说真正重要的问题：一个通用编码 Agent 只拿到工具及其文档，能完成真实任务吗？agent-eval.yml 会使用免费层 API 密钥，在本地 Acme Supply 网站上以无头模式运行 Gemini CLI，依次测试 navigera、 playwright-cli 和 agent-browser：

• **熟练模式：**工具已安装，且其供应商提供的 Agent Skill 位于工作区 （.agents/skills/）中；
• **上手模式：**Agent 只会得到工具名称和代码仓库 URL，必须根据其文档完成安装， 然后执行一项简短任务。

六项任务分别是：查询价格；使用优惠券购买，并填写 iframe 支付表单；登录并查看分页订单表格；在新标签页打开文档并展开折叠的常见问题；填写位于 iframe 内的支持表单；以及对一个 170 行的设置表单进行四项指定修改，同时保持其他所有内容不变。成功与否根据网站记录的状态和最终回答判定，绝不依据 Agent 自己的说法。每次运行还会记录模型请求、Token、Shell 命令和工具外变通操作（curl、临时脚本）。所有工具使用相同的模型、提示词模板、Chrome 和网站。os: windows（或 both）会在 Windows Runner 上运行相同任务，此时 Agent 的 Shell 为 PowerShell。

三个工具作为并行任务运行。密钥存放在 main 环境中，每个工具占用一个名额，因为 Gemini 的免费额度按 Google Cloud 项目计算： GEMINI_API_KEY（navigera）、GEMINI_API_KEY_2（agent-browser）和 GEMINI_API_KEY_3（playwright-cli）。如果某个名额为空，则回退到 GEMINI_API_KEY。如果没有任何密钥，只运行脚本化基线：使用已知可用的 navigera 命令计划检查网站、成功条件和测试框架。因模型额度或服务中断而终止的运行会标记为 ⚠ 基础设施问题，不计作工具失败。

agent: openai 会使用任意兼容 OpenAI 的模型而非 Gemini CLI，以相同的任务、提示词、轮次上限和超时时间运行（默认通过 SiliconFlow 使用 DeepSeek-V4.1-Flash；OPENAI_BASE_URL、SILICONFLOW_API_KEY），因此可以用第二种模型系列进行交叉验证。

navigera+jev 会运行启用了决策器的 navigera， navigera+jev-told 还会在提示词中要求使用 --find / check；TypeSafe 密钥 （main 中的 TYPESAFE_API_KEY）始终保存在本地中继中，Agent 的 Shell 无法访问，每次运行都会记录决策器的调用和 Token。decisions: true 会启用上文中 Jev 与 Gemini 的决策对比（bench/decide/compare.py）。

0.5.0（2026-10-22），熟练模式，每个工具的六项任务各运行两次：

• DeepSeek-V4.1-Flash（运行 39699303497）：navigera 通过 12/12，中位数为 50K Token 和 9 次模型轮次；在 Lightpanda 上也通过 12/12（121K）； playwright-cli 通过 11/12（96K），agent-browser 通过 12/12（153K）。启用决策器后， navigera 以 43K 通过 12/12，Agent 在未被提示的情况下于 12 次运行中有 3 次使用了它； 明确要求使用时，12 次中有 11 次使用（12/12，62K）。
• Gemini 3.5 Flash-Lite（运行 39691538974）：navigera 以 127K 通过 12/12， 在 Lightpanda 上也通过 12/12（167K）。

0.4.1（2026-10-14），Gemini 3.5 Flash-Lite，熟练模式：navigera 在五项任务的 10 次运行中（每项 2 次）全部通过，中位数为 7 次模型轮次和 103K Token。

0.3.0 与 0.2.1 对比，同一模型，同时启动（购买和账户任务，各运行 2 次，全部通过）：ax 现在会等待页面仍在加载的数据，而 Skill 会教 Agent 在一次 Shell 调用中串联确定无误的步骤。模型轮次中位数从 18 降至 10，Token 中位数从 288K 降至 167K；每次 0.3.0 运行的 Token 都少于相同任务的每次 0.2.1 运行。 脚本化会话并未变慢：耗时为 0.51 秒，对比 0.49 秒；冷启动均为 0.23 秒。 自然语言检查（agent-check.yml， 每次向 master 推送、PR 和每晚运行）：用通俗语言告诉 Gemini 使用 navigera 及其技能购买商品。在本地商店分别通过 Linux 和 PowerShell 上的 Windows 执行一次（真实检查，根据记录的订单进行评判），并在 Sauce Labs 的公开演示 商店 saucedemo.com 上执行一次。该商店用于自动化练习，不会收取真实费用（信息性检查，根据确认信息和订单总额进行评判）。

贡献

有关构建、测试套件、CI 结果的查看、A/B 基准测试和发布，请参阅 CONTRIBUTING.md。

目录结构

• src/protocol.rs：CLI 解析、JSON 行协议和 Driver（OPS 表即为 --help）
• src/browser.rs：BrowserSession：浏览器发现（包括 chrome-headless-shell）、启动标志、标签页
• src/cdp/：从头构建的 CDP 引擎：管道/WebSocket 传输、JSON-RPC 客户端（NAVIGERA_CDP_TRACE）、页面操作、ax.rs（快照树）、events.rs（对话框、弹出窗口、导航）、procjob.rs（Windows 作业对象）
• src/session.rs：命名会话：套接字服务（Unix 套接字；Windows 上使用环回 TCP + token）、客户端、分离式 start
• src/cdp/attach.rs：--attach（连接到正在运行的浏览器）和 --profile（持久化的 navigera 浏览器）
• src/mcp.rs：navigera mcp，通过 stdio 运行的模型上下文协议服务
• src/decide.rs：find / check：决策模型的客户端，以及页面元素如何转化为选项
• src/install.rs：install-browser（Chrome for Testing 的索引、通过 curl 下载、解压并检查 zip 文件）
• src/timing.rs：通过 NAVIGERA_TIMINGS=1 在 stderr 输出启动/关闭阶段的耗时
• tests/：浏览器端到端测试：服务协议、会话和 Acme Supply 场景
• bench/site/server.py：Acme Supply，一个确定性的本地商店（SPA、iframe、shadow DOM、对话框、弹出窗口、登录、上传）
• bench/ladder/：驱动程序阶梯和 Agent 工具基准测试（每次运行生成 publish.json，gen_readme.py）
• bench/agent-eval/：Gemini CLI Agent 在 navigera、playwright-cli 和 agent-browser 上的评估
• bench/decide/：决策基准测试（compare.py）、TypeSafe 中继（relay.py）以及无密钥运行时的替代实现（mock_jev.py）
• tools/：cdp_check.py（协议正确性）、protocol_dump.sh、cft_matrix.py（Chrome 版本矩阵）
• skills/navigera/SKILL.md：Agent 指南（编译进二进制文件：navigera skill）
• .github/workflows/：ci.yml（测试、Chrome 矩阵、协议检查）、bench.yml、agent-eval.yml、release.yml、chrome-bisect.yml、vendor.yml