ogulcancelik/herdr-browser

# Herdr Browser Herdr Browser 会在 Herdr 窗格中渲染真实的 Chromium 视图，并将其暴露给 Chrome DevTools Protocol 客户端。Agent 可以驱动浏览器，你可以在窗格中观看它，并且随时可以通过鼠标和键盘接管控制，而不会断开自动化客户端的连接。 浏览器自动化通常是不可见的。Agent 在后台无头运行，你只能在事后通过截图来还原发生了什么，或者你需要时刻盯着一个与你当前会话毫无关联的独立 Chrome 窗口。Herdr Browser 将自动化的浏览器直接放入你正在使用的布局中，实时显示，并使其可以直接交互。 ## 这不是什么 这不是一个通用型浏览器。桌面浏览器在 devtools、扩展、视频、下载、右键菜单和 IME 方面更具优势，此插件并不试图在这些方面与之竞争。请使用它来观察和引导自动化操作，以及在不离开终端的情况下预览本地开发服务器。 ## 系统要求 - Herdr 0.7.4 或更新版本 - Linux 或 macOS - Bun - Google Chrome 或 Chromium - 兼容 Kitty 图形显示的终端，例如 Ghostty、kitty 或 WezTerm 在你的 Herdr 配置中启用实验性的图形支持： ``` [experimental] kitty_graphics = true ``` 重启 Herdr 或运行以下命令以应用更改： ``` herdr server reload-config ``` ## 安装 从 GitHub 安装已发布的插件： ``` herdr plugin install ogulcancelik/herdr-browser --yes ``` 对于本地开发，请改为链接此检出版本： ``` herdr plugin link ~/Projects/herdr-browser ``` ## Agent 浏览器自动化 Herdr Browser 在插件目录中包含一个 CLI；它不会安装全局可执行文件。使用以下命令查找当前活动的检出路径： ``` herdr plugin list --plugin official.browser --json ``` 读取 `result.plugins[0].plugin_root`，然后使用 Bun 运行 CLI： ``` bun run "/src/cli.ts" views bun run "/src/cli.ts" connect --view ``` `views` 会列出当前由可见插件窗格支撑的浏览器视图。`connect` 会启动一个限定于所选视图的环回 CDP 网关，并返回其 HTTP 和 WebSocket endpoint。该网关代表完整的浏览器视图，而不仅仅是其活动标签页。Browser Use、PinchTab、Playwright 和其他 CDP 客户端可以通过它们常规的 API 导航和管理标签页，同时 Herdr 的标签栏和渲染页面会遵循标准的 CDP target 激活机制。 将客户端指向返回的 endpoint： - Browser Use：将 `BU_CDP_URL` 设置为 `cdp_http_url`，或将 `BU_CDP_WS` 设置为 `browser_ws_url`。 - Playwright：调用 `chromium.connectOverCDP(cdp_http_url)`。 - Playwright MCP：传入 `--cdp-endpoint=`。 - Chrome DevTools MCP：传入 `--browser-url=`。 当客户端连接时，该窗格将保持完全可交互的状态。点击、滚动、悬停、输入和工具栏操作都会作用于自动化客户端所看到的相同 target，因此你可以在运行中途进行干预，并在无需重新连接的情况下交还控制权。 该 endpoint 授予对该浏览器视图的完全控制权。请将其保留在本地，不要通过网络暴露。Herdr Browser 保留对 Chromium 的所有权；关闭已挂载的自动化客户端只会断开其连接，而不会终止插件浏览器。 面向 Agent 的工作流程记录在 [`skills/herdr-browser/SKILL.md`](skills/herdr-browser/SKILL.md) 中。 ## 打开浏览器窗格 在右侧分屏中打开一个空白浏览器： ``` herdr plugin pane open \ --plugin official.browser \ --entrypoint browser \ --placement split \ --direction right \ --focus ``` 使用 `--placement tab`、`--placement zoomed` 或 `--placement overlay` 来选择其他支持的布局。第一行工具栏提供标签页选择、关闭和新建标签页控制。第二行提供后退、前进、重新加载、停止、缩放和 URL 输入功能。页面点击、滚动、悬停和键盘输入都会被转发给 Chromium。 当其他插件打开窗格时，可以传入一个初始 URL： ``` herdr plugin pane open \ --plugin official.browser \ --entrypoint browser \ --placement zoomed \ --env HERDR_BROWSER_INITIAL_URL=http://127.0.0.1:3000 \ --focus ``` ## 打开本地开发链接 该插件会为使用 `localhost`、`127.0.0.1` 或 `[::1]` 的 HTTP URL 注册一个链接处理器。在任意 Herdr 终端窗格中按住 Control 并点击匹配的 URL： ``` http://localhost:5173 http://127.0.0.1:3000/dashboard http://[::1]:8080 ``` 在 macOS 和 Linux 上均使用 Control-click。普通点击仍作为终端输入，且与本地链接处理器不匹配的 URL 会继续通过 Herdr 的常规外部浏览器行为进行处理。 默认情况下，本地链接会在获得焦点的右侧分屏中打开浏览器。你可以在插件配置目录下的 `browser.json` 中配置该行为： ``` herdr plugin config-dir official.browser ``` 配置示例： ``` { "linkOpenPlacement": "split", "splitDirection": "right", "focusOnOpen": true, "browserZoom": 1.25, "showDiagnostics": false, "captureScale": 1, "captureBackend": "screenshot", "screencastEveryNthFrame": 1, "screencastPollMs": 250, "profileRoot": "/absolute/path/to/herdr-browser-profiles" } ``` `browserZoom` 设置初始页面缩放比例，范围从 `0.5` 到 `2.5`，默认值为 `1`。浏览器工具栏的 `[-]` 和 `[+]` 控件会以 10% 的步长更改当前窗格的缩放比例，并将新的默认值持久化到此文件中。调整窗格大小不会更改浏览器缩放比例。 `showDiagnostics` 会保留底部的状态行，用于显示流和视口指标。它默认为 `false`，主要用于性能调试。 `captureScale` 用于减小捕获帧的尺寸，范围从 `0.1` 到 `1`，默认值为 `1`。帧是以完整的设备像素捕获的，因此 HiDPI 显示器会为每一个像素付出双重代价：一次在 Chromium 的编码器中，另一次在终端的解码和纹理上传过程中。设置为 `0.75` 可以减少大约 44% 的像素数量，而清晰度只有轻微下降；如果浏览器窗格消耗的 CPU 超出了你的预期，这是目前最有效的调节参数。由于窗格本身已经被缩小以适应字符网格，因此即便比例远低于 `1`，文本依然清晰可读。 `captureBackend`、`screencastEveryNthFrame` 和 `screencastPollMs` 用于微调帧 pipeline 本身，很少需要更改。`captureBackend` 为按需获取帧选择 `screenshot` 或 `screencast`，默认为 `screenshot`；而实时窗格流无论何种情况都使用 screencast。`screencastEveryNthFrame` 接受 `1` 或 `2`，当为 `2` 时会将生产者的速率减半。`screencastPollMs` 接受 `50` 到 `5000` 的值，默认为 `250`。 Chrome 配置文件默认持久化存储在插件状态目录下，并按 Herdr 会话进行隔离。`profileRoot` 可以选择性地更改其父目录；为了防止并发会话之间出现 Chrome 配置文件锁定冲突，处理过的 Herdr 会话名称仍会被追加到路径中。请勿将其指向当前已被其他 Chrome 进程使用的配置文件。 `linkOpenPlacement` 接受 `split`、`tab`、`zoomed` 或 `overlay`。overlay 是推荐的瞬时、类弹窗式浏览器界面。不支持真正的 Herdr `popup` 放置方式，因为弹出窗口没有图形流所需的窗格标识。 ## 快捷键 将自定义命令添加到你的 Herdr 配置中，以便在没有链接的情况下打开浏览器。此示例绑定了右侧分屏和一个瞬态 overlay： ``` [[keys.command]] key = "prefix+b" type = "shell" command = '"${HERDR_BIN_PATH}" plugin pane open --plugin official.browser --entrypoint browser --placement split --direction right --focus' description = "open browser in right split" [[keys.command]] key = "prefix+shift+b" type = "shell" command = '"${HERDR_BIN_PATH}" plugin pane open --plugin official.browser --entrypoint browser --placement overlay --focus' description = "open browser overlay" ``` 编辑后请重新加载配置： ``` herdr server reload-config ``` ## Chromium 发现 该插件会为每个 Herdr 会话启动一个独立的 headless Chromium 进程，并附带专属的持久化配置文件。在该会话中，Cookie、origin 存储、同意状态和登录信息在浏览器窗格和 daemon 重启后依然会保留。它不会挂载到你常规的浏览器进程，也不会复用你常规的浏览器配置文件。 在 Linux 上，它会在 `PATH` 中搜索常见的 Chrome 和 Chromium 可执行文件名。在 macOS 上，它还会搜索标准的 Google Chrome 和 Chromium 应用程序位置。当自动发现无法满足需求时，请在用于启动 Herdr 服务器的环境中设置显式的可执行文件，然后重启 Herdr： ``` export HERDR_BROWSER_CHROME="/path/to/chrome" ``` 当前版本不会自动下载 Chromium。如果未安装兼容的浏览器，启动时会失败并报出发现错误。 ## 渲染 帧来自于 CDP screencast，并通过 Herdr 的窗格图形流到达终端。捕获是由绘制事件驱动的，并通过延迟 `Page.screencastFrameAck` 来进行节奏控制，这会在 Chromium 编码下一帧之前施加背压，而不是在已经付出代价之后再丢弃帧。被动上限为 15 FPS；直接输入会将其提升至 30 FPS 并持续 750 毫秒，随后恢复至被动速率。而已稳定的页面几乎不会产生任何帧。 ## 本地冒烟测试 在 Herdr 窗格中通过未使用的端口启动包含的测试页面： ``` HERDR_BROWSER_TEST_PORT=43127 bun run test-page ``` 按住 Control 并点击打印出的本地 URL。确认页面能够打开、随窗格调整大小、接受点击和输入，并且在窗格关闭时能够关闭其浏览器视图。 运行自动化检查： ``` bun test bun run typecheck ``` ## 当前限制 不支持 Windows、真正的 popup 放置方式、下载、右键菜单、DevTools 和 IME。目前还没有页面文本选择、剪贴板复制或页面查找功能。渲染需要启用 Herdr 的实验性 Kitty 图形设置，并且是针对本地会话进行调优的；其单帧带宽过高，无法用于远程 SSH 使用。

标签：CDP, Chromium, RPA, SOC Prime, 开发工具, 浏览器自动化, 终端工具, 自动化攻击