pagouse

按引用，而非按像素。 pagouse 是供编码代理使用的页面代理：一款运行在日常配置（daily profile）上的 Chromium 扩展，读取无障碍树（accessibility tree），将稳定的 ref_N 标签交给你的代理，并且——仅在获得授权时——点击、填写和导航这些节点。

默认只观察。变更需要 --allow-input。可选的 MCP 服务器仅可观察，无法被诱导进行输入。

$ pagouse --json snapshot --tab 1840 | jq -r '.snapshot.tree' | head
RootWebArea "Inbox" [ref_1]
  textbox "Search" [ref_2]
  button "Compose" [ref_3]

工作原理

• MV3 扩展在页面内部构建无障碍树，使 refs 在多次独立的 CLI 调用之间保持有效。

• 原生消息（Native Messaging）会启动 pagoused——一个运行在仅属主可访问的 Unix socket 上的本地守护进程。不需要远程调试端口，也不需要 chrome.debugger。

• 一个零依赖的 Python 核心将这一切封装在带版本的 --json 信封中（schema: 1）。

各层架构与非目标：docs/architecture.md。

Related MCP server: Playwright MCP

环境要求

• Linux

• Python 3.13+ 和 uv

• 运行在 daily profile（日常配置）上的 Chromium 系浏览器（Chrome、Chromium、Brave、Edge）

核心本身零依赖。magick 是 --fit 缩放时的可选依赖。

安装

git clone https://github.com/gianlucamazza/pagouse
cd pagouse
./install.sh

install.sh 将 pagouse 安装为 uv 工具；如果 ~/.config/pagouse/config.toml 不存在则创建它；将代理技能（agent skill）链接到任何已有的技能根目录；并注册原生消息宿主。该脚本是幂等的。详见 docs/quickstart.md。

然后以未打包方式加载 extension/（chrome://extensions → 开发者模式）。一旦弹窗变绿，pagouse --json doctor 应报告 ready。

用法

观察——永远不需要授权：

pagouse --json tabs
pagouse --json snapshot --tab ID

驱动——添加 --allow-input，按 ref 点击，绝不按坐标：

pagouse --json --allow-input click --ref ref_4 --tab ID --then snapshot

每个命令和标志：docs/cli-reference.md。信封格式与错误码：docs/json-contract.md。

MCP 附加组件与代理技能

uv tool install 'pagouse[mcp]' 提供 pagouse-mcp：仅包含只读的观察工具（doctor、tabs、snapshot、shot、wait、wait_ref）。没有变更工具；请通过 CLI 并配合授权来驱动页面。

install.sh 还会把 skills/pagouse/SKILL.md 链接到任何已有的代理技能根目录，让你的代理无需配置即可获得操作手册。

安全

观察从不请求权限；没有明确授权时，变更会被拒绝。核心强制执行协议拒绝（scheme deny）、来源策略和机密信息脱敏。标签页标题、URL、无障碍树文本和截图像素都是不可信输入。在启用输入功能之前，请阅读 docs/security-model.md。请按 SECURITY.md 报告漏洞。

文档

许可证

MIT。参见 LICENSE。