pi-browser-use-lite0.4.1

Pi extension: drive your own Chrome through a companion browser extension.

GitHub Actions Published 4 days ago MIT ~406 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

pi-browser-use-lite

简体中文 | English

五个 chrome_* 工具，操作你自己的浏览器：你已经登录的标签页、你的 cookie 和会话。

包分两半。pi 扩展注册这些工具，并在 127.0.0.1 上跑一个本地桥。配套的 Chrome 扩展轮询这个桥，用 chrome.debugger 执行每条命令。

工具

工具	做什么
`chrome_act`	navigate、click、type、fill、press、hover、drag、scroll、upload、eval、wait、batch
`chrome_see`	快照：refs、text、changes、full；读控制台与网络日志
`chrome_tab`	list、new、switch、close
`chrome_vision`	截视口或整页
`chrome_cdp`	一条裸 CDP 调用，另四个盖不住的用它

值得知道的行为：

每个会话一个独立浏览器窗口。工具不碰你自己的标签页。会话结束时关掉本会话开的标签。
这个窗口不聚焦地打开。点击或打字时页面若不可见，扩展会开焦点模拟让 Chrome 接受输入，不把窗口带到前台。读操作不会打扰你。
输入走可信 CDP 事件，拒绝合成事件的页面也会响应。
控制台与网络抓取从导航开始，不从第一次读取开始。
每次失败都带类别和一句 hint，说明下一步做什么。

安装

pi install npm:pi-browser-use-lite

扩展就在包里。每个浏览器装一次：

在 pi 里运行 /chrome status。扩展没连上时，回复会打印要加载的目录。
打开 chrome://extensions，开开发者模式，点「加载已解压的扩展程序」，选那个目录。
再跑一次 /chrome status。connected: yes 表示桥看到了扩展。

然后给这次会话授权：

/chrome authorize on

五个 chrome_* 工具只有授权后才出现。它们注册时不活动，所以授权前既不在模型的工具表里，也不在 codemode 的描述里。/chrome authorize off 会把它们再摘掉。

授权随会话结束。想每个会话一开始就已授权，把 policy.authorizeOnStart 设为 true。输入 /chrome 再按 Tab 列出子命令。

配置

一个 JSON 文件：<agent dir>/pi-browser-use-lite/config.json。agent dir 是 PI_CODING_AGENT_DIR，没设时是 ~/.pi/agent。

没有这个文件时全部取默认值。类型错或未知键会让启动失败，并一次列出所有坏字段。枚举值不认识时取默认值。数字越界时夹到最近的边界。下面的注释只作解释，真正的文件必须是严格 JSON。

最小配置：不用写。五个工具在默认值下都能用。

{}

完整示例：每个键都跟着默认值，以及什么时候该改。

{
  // 本地桥。扩展里编译了同一个端口
  // （browser-extension/background/transport.js）：两处一起改，然后重载扩展
  "bridge": { "port": 17318 },

  // 会话规则
  "policy": {
    "authorizeOnStart": false,  // true = 不用 /chrome authorize on 就能用工具
    "closeOwnTabsOnExit": true  // 会话结束时关掉本会话开的标签
  },

  // 输入与时限
  "input": {
    "dragSteps": 10,            // 按下与松开之间的鼠标移动次数
    "scrollSteps": 5            // 每次 scroll 的滚轮事件数
  },
  "timing": { "navigateTimeoutMs": 15000 },  // 等 load 事件的时长；navigate 调用再多给 2 秒

  // 模型可见的输出
  "output": {
    "maxElements": 80,          // 快照元素上限
    "textChars": 18000          // see 的 text 模式正文上限，其余带提示丢掉
  },

  // 截图
  "screenshot": {
    "dir": "/home/me/.pi/agent/pi-browser-use-lite/screenshots",  // 第一次用时创建
    "format": "png",            // png | jpeg
    "keepNewest": 20            // 这个目录里更旧的截图会被删掉
  },

  // 工具开关与名字。至少留一个启用；名字不能重复，也不能盖住宿主已有的工具
  "tools": {
    "chrome_act": { "enabled": true, "name": "chrome_act" },
    "chrome_see": { "enabled": true, "name": "chrome_see" },
    "chrome_tab": { "enabled": true, "name": "chrome_tab" },
    "chrome_vision": { "enabled": true, "name": "chrome_vision" },
    "chrome_cdp": { "enabled": true, "name": "chrome_cdp" }
  },

  // 按工具改内置提示。"" 清空 description 或 promptSnippet；[] 表示不加规则。
  // 规则写句子就行：工具名前缀由扩展补，改名后规则跟着改
  "guidance": {
    "chrome_act": {
      "description": "操作用户真实的浏览器。",
      "promptSnippet": "操作浏览器",
      "promptGuidelines": ["navigate 时带上 see: refs。"]
    }
  }
}

每个键都可选。范围与默认值在 src/config/schema.ts。

文档

文档	内容
ARCHITECTURE	模块边界与 seam；改结构之前先读它
GLOSSARY	一个概念只用一个词
Modules	每个模块的取舍与坑
Decisions	为什么是这个形状

开发

在仓库根执行：

pnpm -C packages/pi-browser-use-lite lint
pnpm -C packages/pi-browser-use-lite check:imports
pnpm -C packages/pi-browser-use-lite typecheck
pnpm -C packages/pi-browser-use-lite test

端到端测试会驱动真实浏览器。把 packages/pi-browser-use-lite/browser-extension 加载进扩展，留一个开着的 Chromium 系浏览器，然后运行：

pnpm -C packages/pi-browser-use-lite test:e2e

关掉其他装了本扩展的浏览器。两份扩展会抢同一个桥，命令落到先问的那一份。

桥报出的版本与扩展不同的时候，扩展会自己重载。改了扩展代码但没升版本号时，去扩展页手动重载一次。

许可证

MIT，见 LICENSE。

Untested on omp

Did it work for you?

Reports 0

Readme

pi-browser-use-lite

工具

安装

配置

文档

开发

许可证