可视化点击选元素：pi-skills的browser-pick.js交互式选择器实现原理剖析-二趣网

可视化点击选元素：pi-skills的browser-pick.js交互式选择器实现原理剖析

【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills

pi-skills 是一款为 pi coding agent（兼容 Claude Code、Codex CLI 等）打造的技能集合仓库，其中的 browser-pick.js 提供了"可视化点击选元素"能力：一个交互式选择器，让你在真实浏览器里用鼠标点选页面元素，把结构化的元素信息直接交给 AI。当 AI 分不清你说的"那个按钮"到底是哪一个时，这个工具就是最佳答案。

🎯 它解决什么问题？

用 AI 操作网页时，最常见的卡点是元素定位：页面 DOM 复杂、选择器含糊，AI 只能靠猜。传统的做法是 AI 反复执行 JavaScript 探查页面，效率低、易出错。

browser-pick.js 换了一个思路：把选择权交还给用户。它在你肉眼可见的浏览器页面上叠加一层高亮框和提示横幅，你点哪里，AI 就拿哪里的信息。一次点击，胜过十次猜测。

⚙️ 快速上手：三步跑通元素选择

前置要求：已安装 Chrome 和 Node.js，并在技能目录执行过依赖安装（依赖声明见 package.json）。

步骤	操作	说明
1️⃣ 启动浏览器	运行 browser-start.js	以远程调试模式启动 Chrome，监听`localhost:9222`
2️⃣ 打开目标页面	运行 browser-nav.js + 网址	导航到你要选元素的页面
3️⃣ 发起选择	运行`browser-pick.js "Click the submit button"`	页面出现蓝色高亮框，鼠标点选即可

⚠️ 小提醒：browser-pick.js 连接浏览器有5 秒超时，如果提示"Could not connect to browser"，先执行第 1 步即可（对应 browser-pick.js）。

🔬 实现原理拆解（无代码也能看懂）

整个脚本只有不到 160 行，却五脏俱全。它的工作可以分为四个阶段：

阶段一：通过 CDP 连接正在运行的 Chrome

脚本基于 Chrome DevTools Protocol（CDP），使用 puppeteer-core 连接localhost:9222端口上已启动的浏览器，并自动锁定最后一个标签页作为操作对象（browser-pick.js）。这意味着它是"接管"你正在看的页面，而不是另开一个无头窗口——这正是"可视化"的关键。

阶段二：向页面注入一个"悬浮工具层"

脚本通过 browser-pick.js 向当前页面注入一个pick()函数，它会在页面上创建两个关键 DOM 元素：

全屏透明遮罩层（overlay）：z-index设为最大整数 2147483647，但pointer-events:none——看得见却"不挡手"，所有鼠标事件仍能穿透到下面的真实元素；
底部提示横幅（banner）：深色圆角提示条，实时显示你传入的提示语、已选数量和快捷键说明（Enter 完成 / ESC 取消 / Cmd/Ctrl+点击追加选择）。

同时还有一个highlight 高亮框，鼠标划过时如影随形，用蓝色边框实时标出你悬停的元素。

阶段三：用两个 API 精准"捕获"元素

这是整个选择器的灵魂，只有两步：

document.elementFromPoint(x, y)：鼠标移动/点击的坐标，反查出坐标下最顶层的真实 DOM 元素；
el.getBoundingClientRect()：拿到该元素相对视口的精确位置和尺寸，据此把蓝色高亮框"贴"上去。

注意脚本在捕获时会主动排除 overlay 和 banner 自身，确保你永远选不到工具层，只会选到页面元素。

阶段四：三种交互，覆盖所有选择场景

操作	行为
普通单击	立即结束选择，返回该元素信息
Cmd/Ctrl + 单击	追加选中（绿色 3px 描边标记），支持多选
Enter	批量提交所有已选元素
ESC	取消选择，清理现场

无论哪种方式结束，脚本都会执行清理逻辑：移除遮罩层和横幅、还原被描边的元素样式，页面恢复原样。

📦 AI 最终拿到什么？

选择完成后，脚本对每个元素调用 buildElementInfo，输出一份面向 AI 的结构化档案：

字段	内容	对 AI 的价值
`tag`	标签名（如`button`）	知道元素类型
`id`/`class`	ID 与类名	直接构造 CSS 选择器
`text`	元素文本（截断至 200 字符）	理解元素语义
`html`	外层 HTML（截断至 500 字符）	复现精确结构
`parents`	从元素到 body 的完整父级路径	消除同名元素歧义

这些信息经标准输出回传给 Agent（结果格式化逻辑），AI 无需再反复探查页面，一步到位。

🤝 它在 pi-skills 生态中的位置

browser-tools/SKILL.md 明确规定了 Agent 何时应调用它：

用户说"我想点那个按钮" → 让用户用选择器指出来；
用户说"提取这几条数据" → 让用户圈出目标元素；
页面结构复杂、选择器有歧义 → 视觉选择最可靠。

它与同目录的 browser-eval.js（执行任意 JS）、browser-screenshot.js（截图）、browser-cookies.js（查看 Cookie）等工具组合，构成一套完整的"人机协作式浏览器自动化"工具箱。

❓ 常见问题

Q：为什么提示无法连接浏览器？A：先运行 browser-start.js 启动带调试端口的 Chrome。

Q：为什么我选不到某些元素？A：检查该元素是否被pointer-events:none或更高层级的遮罩覆盖，elementFromPoint只能命中视觉最顶层的元素。

Q：多选是怎么去重的？A：脚本内部用 Set 记录已选元素，重复点击同一元素不会重复计入（点击处理逻辑）。

📎 相关文件导航

文件	作用
browser-pick.js	交互式元素选择器（本文主角）
browser-start.js	启动远程调试模式的 Chrome
browser-nav.js	页面导航
browser-eval.js	页面内执行 JavaScript
SKILL.md	技能说明书：Agent 何时、如何使用各工具
README.md	pi-skills 全部技能一览

【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析