webnav

webnav

让你的网页浏览 AI Agent 不再每次运行都重新探索相同的网站。 你的 Agent 只需绘制一次网站地图——之后就能通过 webnav walk 永久畅行：确定性、零大模型的页面间自动导航，只会在真正需要抉择时暂停（例如买什么、点击不可撤销的按钮），然后把控制权交还给你。它是可复用的网站地图，而非页面压缩——大多数节省 token 的工具会缩减 Agent 读取的内容；webnav 记住的是各处的位置，让 Agent 不必再寻找路线。webnav 提供地图和导航机制；所有判断仍由 Agent 完成。

效果展示

使用 saucedemo 的完整结账流程进行的一次真实运行（地图和凭据已记录）：

$ webnav walk --start www.saucedemo.com:login --goal www.saucedemo.com:checkout-overview
{ "status": "needs-navigation",
  "semanticStep": "open the shopping cart",
  "question": "before \"open the shopping cart\", fire these in-page affordances: aff_addcart",
  "snapshot": "…", "session": "walk-w-…", "browserSession": "w-…" }
   # ^ paused at a REAL fork: webnav won't decide what you buy. The agent picks from the snapshot:

$ webnav use click e54 --session w-…          # add-to-cart — the agent's one judgment call
$ webnav walk-resume walk-w-… --ref e124      # continue; e124 = the icon-only cart badge
{ "status": "done", "cost": { "playwright_calls": 12 } }

只需调用 4 次 Agent 可见的 CLI，即可完成登录 → 商品列表 → 购物车 → 结账表单（从本地存储的凭据自动填入——地图中绝不会包含这些信息）→ 概览。底层执行了 12 次浏览器操作，导航没有消耗任何 Agent token。

在我们的导航基准测试中（两种方案均使用 Haiku，底层使用相同的浏览器），面对一条多步骤深层路线，walk 使用的 Agent 步骤约少 3 倍：中位数为 6 次调用，而 Agent 临时操控原始浏览器为 18 次；同时更可靠地达成目标（3/3 对比 2/3）。 该文件中也如实说明了限制：这一优势出现在深层且可稳定导航的路线中；对于浅层的 1–2 跳路线，或 Agent 改为手动操控时，两种方案不相上下。webnav 最能发挥作用的地方，恰恰是临时操控最费力的地方——漫长、重复的旅程。

从侧边栏操控标签页（Chrome 扩展）

此外还有一个 Chrome 扩展 webnav-extension/——一个停靠式侧边栏，你可以在其中输入目标，并观看 Agent 操控你的活动标签页（通过 chrome.debugger/CDP 执行读取／点击／输入／滚动），使用你自己的 Claude Code 订阅。它会先进行回忆（list_routes → check_route），因此已绘制地图的网站会直接重放，而不是重新探索；每次运行也都会记录回地图中，让下一次能够通过低成本、确定性的 walk 完成。

• Ask（先批准计划）或 Act（自动执行）；不可撤销的步骤（付款／下单／删除）始终会暂停，等待你的确认。
• 观看每一步——叙述和工具轨迹实时呈现；光标会移动到每个操作的位置。
• 随时接管，手动操作，然后再交还控制权。
• 教学模式——切换到 Teach，手动演示一次任务；它就会变成一条命名的确定性路线，任何 Agent 都可以通过 walk 执行（输入的值不会离开浏览器）。

试用（零大模型导航和录制需要本地服务）：

cd webnav-extension && npm i && npm run build   # emits the *.js next to *.ts
webnav dev agent-serve --port 7779              # prints a token — paste it into the panel

然后打开 chrome://extensions → 开启开发者模式 → 加载已解压的扩展程序 → 选择 webnav-extension/，打开侧边栏（工具栏图标或 ⌘/Ctrl-E），粘贴 token 并输入目标。运行记录会显示在仪表板上，并标记为 Extension。完整操作指南：webnav-extension/README.md。

原因

Web Agent 每天都会重新发现相同的网站，每次都要支付相同的 Token 费用：快照 → 推理 → 点击 → 快照。对于你（或你的 Agent）会反复使用的网站——内部工具、自动化测试、后台工作流——这种导航应该被记住，而不是重新推理。webnav 会存储每一步持久的意图，以确定性方式重放；网站发生变化时会自行修复，并且绝不会自动执行不可逆操作：每到提交点都会暂停，让 Agent（或你）决定。

快速开始（约 2 分钟即可完成一次操作）

# Node 18, 20, or 22
npm install --global @playwright/cli@latest @dikshanty94/webnav@latest

# A complete Saucedemo map ships with webnav. Credentials stay local on your machine.
webnav creds set www.saucedemo.com username=standard_user password=secret_sauce
webnav walk --start www.saucedemo.com:login \
            --goal www.saucedemo.com:checkout-complete --headless
# → webnav drives the known route and pauses before irreversible decisions.

webnav dev list             # inspect the local map store

预置的 Saucedemo 地图是一个可用示例。要映射你自己的网站，可以把 docs/LEARNING-A-SITE.md 中的提示词交给 Agent、自己录制会话，或使用下方的 Chrome 扩展。有关开发、地图包以及从源代码参与贡献：

git clone https://github.com/lucyfuur94/webnav-core
cd webnav-core
npm install && npm link     # source checkout: runs current TypeScript via tsx
webnav --help               # the tool menu (a peer of playwright-cli)
npm test                    # unit tests (+ gated browser e2e)
npm run build               # tsc -> dist/ (only for the published build; the CLI runs src directly)

通过 MCP 客户端使用（Claude Desktop/Code 等）——webnav 会通过 stdio 将每个操作作为 MCP 工具提供，因此你的 Agent 可以原生使用 walk/use/search/…，无需调用 shell。一行即可：

{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }

地图如何扩展（新手请从这里开始）

webnav 是一张地图——新安装时并非空白，但内容不多。以下如实说明你会得到什么，以及地图如何扩展，避免出现意外：

• 开箱即用的内容。 首次运行任何动词时，webnav 都会在 ~/.webnav/webnav.db 中初始化一份共享地图（按用户存储，在这台机器上的所有终端和文件夹间共享——不是按目录存储的文件）。它预置了 一个完整示例：saucedemo.com——一份涵盖登录→浏览→购物车→结账的 walk 地图。它可以立即使用：

  webnav walk --start www.saucedemo.com:login \
              --goal www.saucedemo.com:checkout-complete      # saucedemo, seeded
  

  不会预置其他内容——webnav 是一款空白地图工具，而 saucedemo 是证明它能正常工作的唯一示例。你需要记录自己的网站（见下文）；这就是产品本身。它适用于你需要在同一网站上重复执行的任何流程：自动化测试、内部工具、后台工作流、重复的 Agent 任务。（早期的 GitHub 回忆 + 互联网图谱引擎——v1 引擎验证版——已于 2026-06-13 从代码库中移除；如果这部分功能回归，可在 git 历史记录中找到。）

• 地图会持久保存并自动修复。 地图保存在 ~/.webnav/webnav.db 中，并在每次运行时重复使用——你不必每次都重新构建。当已记录的步骤发生偏移（元素重命名或移动）时，walk 会升级一次，让 Agent 选择元素，然后将修复写回地图，以便下次运行时能确定性地解析（原则 #3）。你使用的路线会保持最新。需要登录的网站，其凭据保存在本地、地图之外的 ~/.webnav/credentials.json 中（chmod 600）——绝不存入数据库，也绝不共享。

• 映射新网站——把学习提示词交给你的 Agent。 webnav 专为 Agent 打造，因此你不必手动映射：只需将可复用提示词 docs/LEARNING-A-SITE.md 交给 Agent（即使是轻量级 Agent 也可以——我们使用 Haiku），让它自主运行。Agent 会通过 webnav 的 use 原语记录操作，并运行一次网站流程；随后，dev graph-analyse --draft 会将记录整理成一份自我验证的地图（包含绝对 URL、唯一元素指纹、页面内交互方式集合以及声明的域名范围），并通过 dev graph-edit 将其保存。无需手动编写指纹或 URL。（该提示词曾在一次运行中学习了预置的 OrangeHRM 地图——登录和 11 个模块，均已实际操作。）使用 dev node-clear 可重新学习。

• 或者跳过学习——导入别人制作的地图包。 地图以地图包形式流通，因此只需由第一个人学习网站。使用 webnav dev import-map <pack.json> 加载网站骨架；再用 dev creds set 设置你自己的登录信息（地图包仅包含骨架，绝不包含凭据）。mappacks/ 中附带两个地图包（saucedemo、OrangeHRM）；运行 dev export-map <site> 即可制作并分享自己的地图包。

• 或者自己浏览并记录网站。 无需 Agent：运行 webnav dev record-live --session S --url <site>——它会在指定 URL 打开一个带界面的浏览器，你可以像平常一样点击完成流程。你执行的每项操作都会被捕获（使用真实的 Playwright 无障碍快照，绝不记录输入的值——只记录哪个字段发生了变化），并写入与 Agent 记录流程相同的会话存储。按 Ctrl-C 或运行 webnav dev record-stop --session S 停止，之后使用相同的 dev graph-analyse <session> --draft → graph-edit → walk 流程。

• 或者通过 Chrome 扩展操作并记录——见上文的侧边栏：向 Agent 提出目标，它会操作你当前的标签页（先回忆已知路线），并将运行记录写回地图。（早期的扩展仅捕获流程会从原始 DOM 推测无障碍树，现已停用——该流程在 SPA 上会出错；当前扩展会通过真实的 CDP 无障碍功能进行捕获。dev ingest 仍然存在，作为旧版接收器。）

• 随时检查已有内容：运行 webnav dev dashboard（本地操作界面）。其 Sessions 标签页会列出所有已记录的运行——按来源标记（Extension / Agent / Manual），并提供筛选、步骤计数和 Verified 徽章；此外还支持点击录制和回放：

  或使用文本视图 dev outline <site> / dev mermaid <site>。

**简而言之：**开箱即用即可对 saucedemo 执行 walk；其他所有站点都需要自行映射。同一台机器 + 已映射的站点 → 即时、缓存、自我修复。全新站点 → 你（或你的 Agent）需要先录制一次。

动词

# Travel a map you've built (the core win: deterministic, low-token replay)
webnav walk --start <state> --goal <state>   autopilot a multi-step route; pauses at genuine forks
webnav walk-resume <session> --ref|--classify   answer a paused walk's fork and continue
webnav creds set <site> key=value...         store login/form creds locally (~/.webnav, chmod 600)

# Drive a live browser one step at a time (explore/build; each step recordable)
webnav use navigate <url> --session S        open a URL (records a landing if S is recording)
webnav use snapshot --session S              read the page + element refs (never records)
webnav use click <ref> / use type <ref> <t>  act on a ref; records the before/after effect
webnav read <url> [--raw]                    open a URL -> distilled content
webnav search "<query>" [--top N]            open-web search -> extracted evidence
webnav eval <url> "<js>" | network <url>     targeted JS extraction | the page's API calls

# Author a site's map (the record -> analyse -> edit flow)
webnav dev record-start / record-stop        bracket a mapping session
webnav dev record-live --session S --url U   headed browser; click through it yourself, webnav records
webnav dev agent-serve [--port 7779]         local server the Chrome extension drives (SSE + CDP); records each run
webnav dev ingest [--port 7778]              legacy receiver for the retired DOM-capture extension path
webnav dev graph-analyse --session S [--draft]  mechanical structure from what you recorded
                                             (--draft = a self-verified, ready-to-edit graph spec)
webnav dev graph-edit --node <id> --graph J  write the validated graph
webnav dev effects --session S               the RAW recorded before/after snapshots
webnav dev outline <site> | mermaid <site>   completeness check | renderable diagram
webnav dev graph-show --node <id>            a site's stored states + edges (JSON)
webnav dev export-map <site>                 a site's map pack as JSON (skeleton only, no creds)
webnav dev dashboard [--port N]              local operator UI: sites + JSON map + credentials
webnav dev list                              the sites you have maps for + state counts
webnav dev node-clear / node-rm --node <id>  empty a site's map (re-learn) / delete it entirely
webnav dev node-add / edge-add / capture     teach + inspect helpers

使用 webnav <verb> --help 查看详情。输出为 stdout 上的 JSON；成功时退出码为 0，出错时为 2，无结果时为 3。

MCP 服务

webnav mcp 会通过 stdio 将每个动词作为 MCP 工具提供服务——将 MCP 客户端指向它，Agent 就能直接使用这些动词（无需调用 shell）。工具由与 --help 相同的命令注册表生成，每次调用都会运行真正的 CLI，因此这两个接口不会出现偏差：

{ "mcpServers": { "webnav": { "command": "webnav", "args": ["mcp"] } } }

使用者动词也可以通过 webnav use <verb> ... 以规范形式调用，地图编写动词则可以通过 webnav dev <verb> ... 调用；裸使用者动词（例如 webnav read ...）仍然可用。

检查站点地图

地图面向调用它的 Agent（walk），而不是人类仪表板。要检查已捕获的内容，请使用文本视图——无需 UI：

webnav dev outline www.saucedemo.com    # top-to-bottom states + affordances + completeness cues
webnav dev mermaid www.saucedemo.com     # paste into GitHub/mermaid.live to render
webnav dev graph-show --node <id>        # raw JSON

架构（一个 CLI，三个组件，零大模型）

• Explorer — 读取站点声明的结构（优先观察），将录制内容整理为经过自我验证的地图草案（状态、类型化操作项、声明域的影子），并识别状态。
• MapStore — SQLite 持久化：状态（及操作项和声明影子）、投影边、站点节点索引和录制会话。
• Router — 遍历路线并重放（缓存的选择器 → 确定性指纹重新解析），自我修复，返回证据或向 Agent 返回 needs-navigation/needs-classification“轮到你了”响应。绝不评判，也绝不调用大模型。

源码地图（src/）

cli.ts, cli-spec.ts, cli-help.ts     CLI: parsing, command registry, help rendering
protocol.ts, contract.ts             walk response types · published @dikshanty94/webnav types
paths.ts, creds.ts, hosted.ts        ~/.webnav paths · local credential store · remote-map client
mcp/       server.ts                 `webnav mcp`: every verb as an MCP tool (generated from cli-spec)
mapstore/  types.ts, store.ts, record.ts, schema.sql   SQLite persistence (states+affordances+shadow, edges, nodes, node_edges, record sessions)
playwright/ adapter.ts, snapshot.ts, capture.ts, fingerprint.ts, sessions.ts, throttle.ts   playwright-cli child-process · a11y snapshot parser · element fingerprints · session guardrails
explorer/  analyse.ts, diff.ts, draft.ts, shadow.ts, fingerprint.ts, fingerprint-page.ts   analyse a recording → self-verified draft (affordances + declared domain shadow) + state recognition
router/    resolve.ts, replay.ts, path.ts, walk.ts, walk-live.ts, walk-session.ts   deterministic resolve/replay + interactive multi-step walk + pathfinding
           readiness.ts, extract.ts, extract-content.ts, tokens.ts, browse.ts, read.ts   bot-wall detection · signal/content extraction · token-savings · page reading
           search.ts, search-providers.ts, search-live.ts                 multi-provider open-web search
           catalog.ts                                                     dev list (the map index)
graph/     seed.ts, teach.ts, edit.ts, show.ts, coverage.ts               map authoring + inspection (saucedemo seed, graph-edit, graph-show, outline/mermaid)
dashboard/ server.ts, shell.ts                                            `webnav dev dashboard` local operator UI

测试在 tests/ 下采用相同结构。实时端到端遍历测试需通过 WEBNAV_LIVE=1 启用。

原则（完整列表见 CLAUDE.md）

1. 优先观察，尽量少遍历。2. 绝不遍历声明的提交点。3. 存储持久路线；缓存选择器。4. 使用中学习到的权重属于托管服务的范畴。5. 地图呈现证据；由 Agent 评判。5a. webnav 中零大模型——所有推理均通过请求与响应协议交由调用它的 Agent 完成。6. 地图是独立于用例的导航骨架；目标声明信号关注点。绝不规避机器人拦截墙——检测并升级处理。

状态

当前所有工作均已合并到 main，测试全部通过。实时检查清单、待处理工作和已知限制见 docs/STATUS.md；已确定的设计、思维模型和原则见 CLAUDE.md。设计文档：docs/superpowers/specs/。

贡献

欢迎提交 PR——请参阅 CONTRIBUTING.md（其中介绍已确定的原则、开发环境设置，以及如何贡献 站点地图或地图包——这是最有价值的贡献）。地图包仅包含骨架，绝不包含凭据；已随附的示例位于 mappacks/。请按照 SECURITY.md 中的说明私下报告安全问题。请友善相待：CODE_OF_CONDUCT.md。

许可证

Apache License 2.0。可免费使用、修改和再分发（包括商业用途），但须注明出处：保留版权声明和 NOTICE 文件。包含明确的专利授权。版权所有 2026 Dikshant Yadav。