bdg 浏览器调试 CLI
在终端逐步驱动 Chrome，并检查 DOM、网络、控制台和页面状态。
- Star 数
- ★ 177
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 68/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 前端开发者想排查按钮无响应时，点击页面后查看对应请求、HTTP 错误和控制台消息。
- 不适合
- 需要 Firefox 或 Safari 支持的团队
- 需要原生 PowerShell 或 Git Bash 的用户
- 需要长篇脚本测试套件的团队
这个 Agent 能做什么，适合哪些场景？
bdg 是一个 Node.js 命令行工具，会在后台保持 Chromium 浏览器会话，并让用户通过独立的 shell 命令逐步操作页面。它提供导航、点击、填写表单、等待元素、检查 DOM 与样式，以及读取网络请求、Cookie 和控制台消息等命令。遇到未覆盖的 DevTools 功能时，可以通过 bdg cdp 直接调用 Chrome DevTools Protocol。命令输出简洁，并支持 --json，便于代理继续处理或通过 jq 管道筛选。它面向 Claude Code、Codex 和 Gemini CLI 等编码代理，也能由开发者直接在终端使用；需要 Node.js 22.12+ 和 Chrome、Chromium 或 Microsoft Edge。
安装 browser-debugger-cli 后运行 bdg <URL> 启动浏览器会话，再用 bdg dom 命令导航、点击、填写、等待和检查元素。用户可用 bdg network 查看请求、请求头、Cookie 和 HAR，用 bdg console 读取页面消息，并用 bdg eval 执行 JavaScript。bdg cdp 可搜索、描述或调用 CDP 方法；命令也提供机器可读帮助、JSON 输出和错误建议。会话可命名并行运行，也可附加到已开启远程调试的浏览器。
- 前端开发者想排查按钮无响应时，点击页面后查看对应请求、HTTP 错误和控制台消息。
- 编码代理需要在无需预先编写 Playwright 脚本的情况下，逐步填写表单并读取页面反馈。
- 开发者想检查 CSS 规则、元素布局、可访问性树或页面对比度问题。
- 测试人员要检查失败请求、HAR、Cookie 或授权请求头，以定位登录和 API 问题。
- 性能工程师想通过 CDP 读取指标、启用 CPU 节流或进行堆与 CPU 分析。
如何安装或部署这个 Agent？
需要 Node.js 22.12+ 和 Chrome、Chromium 或 Microsoft Edge。通过 npm 全局安装：
npm install -g browser-debugger-cli如需在 Claude Code、Codex、Gemini CLI 等代理中使用其技能，可安装技能文件：
bdg install-skillClaude Code 单独安装：
bdg install-skill --claude安装技能后启动新的代理会话。文档未要求 API 密钥。
如何使用这个 Agent？
启动目标页面并保持会话运行：
bdg localhost:3000再逐步操作和读取结果：
bdg dom fill 'input[name="q"]' "shoes"
bdg dom click 'button:has-text("Search")'
bdg dom wait "#result" --visible
bdg network list --preset errors
bdg console
bdg stop对任意 CDP 方法可使用 bdg cdp <方法名>；例如 bdg cdp Network.getCookies。JSON 输出可用 --json 启用。
这个 Agent 有哪些优点和局限？
- 命令逐步驱动持久浏览器会话，代理可根据每步返回的页面结果调整后续操作。
bdg cdp可调用 Chrome DevTools Protocol，覆盖常规命令之外的 DevTools 能力。- 提供网络、控制台、Cookie、HAR、DOM、CSS、可访问性和性能相关检查。
- 帮助、命令说明、方法搜索和错误建议针对代理的机器调用场景设计。
- 依赖 Node.js 22.12+ 和 Chromium 系浏览器；Firefox 与 Safari 不受支持。
- 原生 PowerShell 和 Git Bash 暂不支持，Windows 用户需使用 WSL。
- 长篇脚本测试套件更适合 Playwright 或 Puppeteer。
- 基准测试结果来自 2025 年 11 月的一次五项任务测试，README 也说明两款工具后来已有变化。
这个 Agent 与同类方案有什么区别？
与 Playwright 和 Puppeteer 相比，bdg 面向实时页面的逐步交互和排查；README 将长篇脚本测试套件列为更适合这两者的场景。与 Chrome DevTools MCP 相比，bdg 以 CLI 命令运行，不需要 MCP；README 提到 MCP 适合已有 MCP 架构或需要 Lighthouse 审计、性能追踪洞察和堆快照分析工具的用户。README 所列基准测试是 2025 年 11 月对五项任务的一次测试，不能视为当前普遍性能结论。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| bdg 浏览器调试 CLI 当前 | 68 · 存在缺口 | 命令行工具免费 | ★ 177 | 今天 | TypeScript | Codex · Claude Code |
| Chrome DevTools MCP | 79 · 存在缺口 | MCP 服务器免费 | ★ 54k | 今天 | TypeScript | Codex · Claude Code |
| JS Reverse MCP | 82 · 表现良好 | MCP 服务器免费 | ★ 3k | 1 个月前 | TypeScript | Codex · Claude Code |
| browser-control | 72 · 存在缺口 | 命令行工具免费 | ★ 3.2k | 1 个月前 | Rust | — |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
CLI 将页面交互、任意 JavaScript eval 和原始 CDP 暴露给调用者，且能读取 Authorization 头、HttpOnly Cookie 和本地存储令牌；材料展示了这些敏感数据的提取与转发示例，却未说明脱敏、访问控制或保护措施，因此敏感数据处理为 0、最小权限与外部影响为 1。材料没有说明高影响操作前的确认机制，用户确认仅得 1；会话可用 stop 结束、可指定独立会话目录，但页面操作的回滚能力有限，回滚为 1。命令输出、JSON 与数据用途有具体示例，数据流透明度为 2。工作流包含 npm audit，但审计不阻止合并或发布，依赖安全为 2。package.json 列出作者和仓库，但发布者身份未由给定材料验证，来源归属为 1。
README 描述称无需截图，但同一文档的功能表列出 screenshots，存在表述不一致，自洽性为 1。要求 Node.js 22.12+ 和 Chromium，安装方式及受支持环境明确；依赖也有锁定安装与构建流程说明，依赖可用性为 2。README 给出拼写错误、无效 CDP 方法、建议命令和退出码的具体错误示例，错误消息处理为 3。
文档明确面向编码代理与终端开发者，并覆盖调试、交互、遥测、可访问性和性能场景，得 3。Firefox、Safari、原生 PowerShell 和 Git Bash 的限制，以及适合改用 Playwright 或 MCP 的情况均有说明；不过原始 CDP 与 eval 的能力边界和风险没有充分展开，能力边界为 2。安装技能及命令帮助提供代理触发指引，但示例中技能何时加载的说明较简略，触发精确度为 2。Node、浏览器、平台、连接现有浏览器和多会话配置均有具体说明，环境适配为 3。
README 按场景、快速开始、功能、安装、限制和贡献组织，并链接命令参考与专题文档，信息架构为 3。安装步骤、要求、浏览器配置和不支持的平台写得具体，安装说明为 3。bdg 与 browser-debugger-cli 的命名关系清楚，但文档中也使用 Agent skill、CLI、MCP 等多种术语，命名稳定性为 2。命令示例、帮助调用、错误处理和常见用途丰富，FAQ 式限制说明也具体，示例与 FAQ 为 3；已知限制为 3。仓库含 MIT 全文许可，许可证为 3。package.json 给出 0.18.0，发布流程要求版本与标签一致且在发布前更新变更日志，但给定材料没有实际变更日志内容，版本与变更记录为 2。贡献入口和发布流程存在，但维护责任主要以作者元数据和贡献邀请表示，未见明确维护承诺或支持期限，维护责任为 2。
短命令、紧凑输出、JSON、jq 管道及针对代理的帮助和错误建议有具体材料支持，输出可用性为 3。无需预写脚本即可逐步操作浏览器，并可通过 CDP 访问 DevTools 能力，显示出对代理工作流的明确增益，边际价值为 3。安装和使用路径清晰，但项目要求较新 Node 与 Chromium，且高级能力需要谨慎处理敏感数据；成本收益为 2。
命令、标志、安装要求及部分错误行为有 README 和 CLI 参考入口等可追溯说明；部分性能与基准结论只在文档中自述，主张可追溯性为 2。package.json、CI 和发布工作流分别说明版本、构建、质量检查及审计流程，能相互印证存在这些流程，但给定材料不能证明其在该修订上实际通过，交叉佐证为 2。文档对基准时间、范围及 MCP 能力变化给出限定，也区分支持平台和限制；但部分效能表述仍属项目自述，事实与推断区分为 2。
- 源码中未见：敏感信息处理使用专用、低权限、可随时吊销的 API 密钥，不要复用生产凭据，也不要让密钥出现在日志里。
- 该工具可访问浏览器中的令牌、Cookie 和授权头，也支持任意 eval 与原始 CDP。使用前应确认目标浏览器会话和页面中的敏感数据符合你的预期。
- README 对截图支持的表述不一致；基准数据来自一次五项任务的比较，且文档说明工具能力随后有所变化。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
v0.20.0: the last 0.x release The last 0.x release. bdg 1.0 renames a set of commands and flags (#465). In 0.20.0 every old spelling still works, prints one Warning: line on stderr (in --json: an entry in the envelope's warnings array) and is hidden from help; in 1.0 each one stops working and exits 81 naming its replacement. Switch scripts and notes now; the warnings name the new spelling. | Old | Use instead | |---|---| | bdg tail | bdg peek --follow | | bdg details network <id> / bdg details console <n> | bdg network details <id> / bdg console details <n> | …在 GitHub 查看 ↗ -
发布说明摘录
bdg 0.19.0 makes interrupting a slow start reliable and fixes HAR body sizes. Action results get better at telling what *you* changed from what the page changes on its own. Behaviour changes (no breaking changes) - A start you interrupt now force-kills its Chrome after 500 ms (#804, #801). This applies to Ctrl-C, SIGTERM or bdg stop while bdg <url> is still starting. bdg sends Browser.close, waits up to 500 ms, then kills Chrome's process group (SIGKILL). The command returns in well under a second (exit 130 or 143) and leaves no session. …在 GitHub 查看 ↗ -
发布说明摘录
bdg v0.18.0 bdg can now attach to the Chrome you already have open (bdg attach), without reloading your tab. Action results are more honest about what happened (form submits, silent DOM changes, blocked submits, tracker noise removed), Ctrl-C now ends every command with a clear envelope or line, and the release workflow is hardened so no project code runs where the npm token exists. Highlights …在 GitHub 查看 ↗
常见问题
使用它需要付费的模型或 API 密钥吗？
它能驱动哪些浏览器？
能否使用已经登录的浏览器会话？
bdg attach 可列出并附加到已开启远程调试的浏览器标签页，且不重新加载页面；Chrome 会要求允许每次连接。