pi-browser-cdp-extension

Pi coding-agent extension exposing BrowserCode CDP browser_execute

Packages

Package details

extension

Install pi-browser-cdp-extension from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-browser-cdp-extension
Package
pi-browser-cdp-extension
Version
1.1.0
Published
May 13, 2026
Downloads
not available
Author
ego_agent_lab
License
MIT
Types
extension
Size
2.5 MB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions"
  ],
  "image": "https://raw.githubusercontent.com/citrolabs/pi-browser-cdp-extension/main/logo.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

这是一个为 Pi 提供 CDP 浏览器执行能力的扩展。它把 BrowserCode 风格的 browser_execute 工具带到 pi-coding-agent，让 Pi 可以通过 Chrome DevTools Protocol 连接 Chromium/Chrome，执行 JavaScript、驱动页面、读取 DOM、截图，并把截图作为图片结果返回。

这个项目的出发点很直接：pi-coding-agent 很适合处理代码任务，但框架本身不提供内置的 web search 或浏览器访问能力。这个扩展为 Pi 提供一个小而明确的入口，让 agent 在任务需要时可以使用由用户授权的真实浏览器。

它不是独立的浏览器测试框架，也不托管 daemon；它是一个 Pi 扩展，会复用 Pi 进程里的持久 CDP session。

English: README.md

快速开始

1. 安装扩展

pi install git:github.com/citrolabs/pi-browser-cdp-extension

本地开发时也可以：

pi install .

安装完成后，正常和 Pi 对话，让它使用浏览器即可。需要操作真实页面时，Pi 会调用扩展提供的 browser_execute 工具。

例如：

打开 https://example.com，告诉我页面标题，并返回一张截图。

Pi 会连接已授权的 Chromium 浏览器，打开页面、读取结果，并把截图附在回复里。

给 Pi 提供什么

  • browser_execute：Pi 可调用的工具名。
  • session：持久 CDP Session，同一个 Pi session 内多次调用会复用状态。
  • console：捕获 log/error/warn/info/debug，作为工具输出流式返回。
  • 截图收集：成功的 Page.captureScreenshot 会自动转成 Pi image content。
  • Workspace：可复用脚本放在 .pi/browser-execute-workspace，snippet 里用 await import(...) 加载。

为什么不只用 web search？

Web-search 工具解决的是“帮 Pi 找资料、总结网页”。pi-browser-cdp-extension 解决的是“让 Pi 直接操控一个真实 Chromium 浏览器”，所以它能处理搜索/抓取工具很难表达成纯文本的任务。

能力 pi-web-access / @ollama/pi-web-search pi-browser-cdp-extension
搜索公开网页 很适合 不是主要目标
抓取并总结静态页面 很适合 可以做，但通常没必要
点击按钮、填写表单、走完整 UI 流程 受限或不支持 通过 CDP 原生操控浏览器
使用登录态 通常依赖 API 权限或手动复制 cookie 直接复用用户已授权的浏览器 session
使用浏览器扩展和真实浏览器行为 不支持 支持，因为 Pi 操控的就是实际浏览器
读取 JavaScript 运行后的动态 DOM 通常只能拿到抓取 HTML 或文本 直接访问 live DOM 和 DevTools Protocol
验证用户实际看到的页面 文本优先 截图会作为 Pi image result 返回
跨多轮 agent 步骤保持状态 取决于工具/后端 Pi 进程内持久 CDP session

任务是“找信息”时，用 web-search 包；任务是“操作网站”时，用这个扩展。

适用场景

适合：

  • 想让 Pi 操作真实 Chrome 页面，而不是只读 HTML。
  • 需要登录态、扩展、真实浏览器环境或 DevTools 协议能力。
  • 希望 agent 在同一会话里持续复用 browser session。

不适合：

  • 纯单元测试场景；用 Playwright/Vitest 更直接。
  • 不可信网页或不可信 CDP endpoint。CDP 能控制浏览器，必须只连你授权的浏览器。

配置

环境变量：

  • BU_CDP_WS / BU_CDP_URL：默认浏览器 WebSocket endpoint，供 session.connect() 使用。
  • BCODE_SCREENSHOT_DIR：可选；把截图同时 dump 到本地目录。

一次性加载扩展：

pi -e ./extensions/browser-execute.ts

Validation

本仓库覆盖核心执行、CDP session helper、Pi extension adapter 三层测试。

npm run typecheck
npm test

当前测试覆盖包括：session 复用/隔离、workspace import、console streaming、timeout、screenshot 收集、CDP target 过滤、active sessionId 路由、Pi image content 转换。

致谢

这个项目的设计思路受到以下项目启发：

Star History

Star History Chart