---
name: element-picker
description: ③段独立工具 —— 在浏览器里点选任意组件，取出它的 CSS 选择器与所属网页，复制给 AI 后可直接定位到源码改样式/改结构。两条路：① Chrome 扩展（装一次，任意网页可用，按 Z 或点胶囊进拾取模式）；② 页面注入（本地开发页加一行 script ＋ URL 带 ?pick）。点「确认」后剪贴板得到「选择器：… / 网页：…」两行，同时把完整上下文（文本 / class / 属性 / 尺寸 / 关键计算样式 / HTML 片段）落到 marks/_ui-marks.json。当用户说「选中这个组件」「把这个元素的位置给你」「改这个页面的样式」「这个按钮在哪」「点选元素」「取组件路径」「改界面」「调样式」时调用。
version: "1.0"
updated_at: "2026-10-16"
agent_created: true
---

# element-picker · 页面元素拾取（③段独立工具）

把「页面上那个组件」变成「AI 能精确定位的坐标」—— 点一下，拿到它的选择器与所属网页，交给 AI 改代码。

## 一、什么时候用

- 用户说「选中这个组件」「把这个元素的位置给你」「改这个页面的样式」「这个按钮在哪」。
- 用户要改界面，但靠嘴说不清是哪一个（"左上角那个"、"第二张卡片"，讲不准）。
- 做完原型/页面后做局部微调，需要把改动点精确指出来。

## 二、两条路，按场景二选一

### 路 1 · Chrome 扩展（任意网页都能用）

装一次，之后每个页面都有拾取器。适合改线上页面、别人的网站、或不在本地开发的服务。

装法：`chrome://extensions/` → 开发者模式 → 「加载已解压的扩展程序」→ 选本目录下的 `chrome-extension/`。
扩展目录变了（换机器、换路径）要重新加载一次。

用法：打开任意页面 → 右下角有半透明胶囊（拾取器已在）→ 按 `Z`、点胶囊、点扩展图标、或按 `Alt+Shift+Z` 进拾取模式 → 点元素 → 确认窗里点「确认」。

### 路 2 · 页面注入（本地开发页）

只给本地开发中的页面用。在页面 HTML 的 `</body>` 前加一行，访问时 URL 带 `?pick`：

```html
<script src="http://127.0.0.1:8890/picker.js"></script>
```

不带 `?pick` 时脚本完全不碰页面，所以可以常留在开发页里。

## 三、点一下之后拿到什么

- 剪贴板两行，直接粘给 AI 即可：

```
选择器：div#recentScriptsList > button.recent-card:nth-of-type(3)
网页：短视频工作台
```

- 同时往 `marks/_ui-marks.json` 追加一条完整上下文：选择器、祖先路径、元素文本、class 列表、`data-*` 属性、位置尺寸、关键计算样式、`outerHTML` 片段。选择器定位"在哪儿"，这份档案定位"是哪一个"。

## 四、服务怎么起

扩展与注入脚本都要连本地服务（可选 —— 不连也能复制，只是少一份存档）：

```bash
node ui-picker-server.js 8890
```

端点：`GET /picker.js`、`POST /mark`、`GET /marks`、`POST /clear`、`GET /health`。零依赖，只用 Node 标准库。

## 五、选择器的准确边界

- 选择器描述的是元素在 DOM 里的**位置**（标签 ＋ class ＋ 第几个），不是它的**身份**。生成时会自校验「是否恰好只命中这一个」，不通过就退到每一级都带 `:nth-of-type` 的完整树路径。
- 动态列表增删或换序之后，同一条选择器可能落到别的条目上 —— 所以它是"此刻的点位"，不是长期坐标。
- 真正落到源码的路径是：从选择器里读 class 名 → 去项目源码里反查是哪段模板渲染的 → 用存档里的文本/属性/HTML 片段交叉确认。

## 六、铁律

1、**默认不激活**。拾取模式会接管页面点击，所以扩展在每个页面只挂一个半透明胶囊，等用户按 `Z` 或点它才进拾取模式；退出后页面点击立刻恢复正常。
2、**只落本地**。不上传任何数据，不调外部接口；存档只写在技能目录下的 `marks/` 里。
3、**页内按键**：`Z` 进/出拾取模式，`Esc` 有弹窗先关弹窗、没弹窗就退出拾取模式，`Ctrl+Enter` 等同确认窗的「确认」。
4、**浏览器内部页面注入不了**（`chrome://`、扩展商店、其它浏览器内部页），这些页面按 `Z` 不会有反应，属正常。

## 七、改代码怎么生效

- 注入版：改完脚本刷新页面即可（响应头带 `no-store`，不吃缓存）。
- 扩展版：改完在 `chrome://extensions/` 点本扩展卡片的刷新（⟳），再刷新目标页面。不需要重新「加载已解压的扩展程序」。