元素选择器 safroigor/dh_picker

DeepSeek Harness 元素选择器

为 DeepSeek Harness 桌面浏览器打造的 Codex 风格可视化元素选择器。

在 Harness 浏览器里打开任意网站，点选一个元素，就在它旁边写评论，按 Enter —— 评论会以紧凑的 chip 形式落进聊天输入框。想写多少条就写多少条，最后一次性发出请求。智能体收到你的指令，外加每个标注元素的结构化描述，于是能定位并修改对应的源码组件。

标注元素上的编号标记；评论显示在聊天输入框里

这个选择器是Harness 插件包，不是往网站里粘贴的脚本。装进 Harness 配置档一次，之后浏览器能打开的任何站点都能用 —— Next.js、React、Vue、Svelte 或纯 HTML —— 不用给这些项目加一行代码。

目录

- 为什么做这个
- 工作原理
- 环境要求
- 安装
- 使用
- 智能体收到什么
- 数据载荷
- 安全
- 限制
- 故障排查
- 开发
- 版本与升级
- 替代方案
- 许可证

为什么做这个

评审 UI 改动时，通常得用文字描述元素：「hero 下面那个按钮」「右边那张卡片」。选择器用元素本身取代描述：

- 在真实页面里指向真实元素，
- 看着它的时候就把指令挂上去，
- 让聊天保持紧凑（一条评论一个 chip），
- 再给智能体足够的上下文 —— 选择器、文本、盒子、标记、计算样式、框架线索 —— 把评论映射回组件。

工作原理

Harness Web GUI (trusted renderer) Browser page (sandboxed guest)
┌──────────────────────────────────────┐ ┌───────────────────────────────┐
│ composer: "Select element" toggle │ executeJava │ injected picker (zero deps) │
│ chips: Element 1 · … Element 2 · … │ ────────────► │ hover · click · inline editor │
│ (send stays user-controlled) │ ◄──────────── │ small numbered markers │
└──────────────────────────────────────┘ console msg └───────────────────────────────┘
│ per comment
▼
one chat message: your text + each chip expanded to structured context → the agent

- Harness 浏览器是一个 Electron <webview>。受信任的渲染进程调用 <webview>.executeJavaScript(...) —— 这是 Electron 有文档的 API。没有改动任何 Harness 文件，没有放宽任何安全设置，页面依然拿不到 Node、IPC 或 DSH 源权限。
- 每条保存的评论都以分块的 console-message 事件返回，使用前会先校验。
- 页面包零依赖，运行在 shadow root 里，因此既不会把样式泄漏到站点，也不会继承站点的样式。
- 评论是真正的 composer 引用：发送时，输入机调用本包的 codec.serialize，结构化块就在这里生成。可见的聊天保持紧凑，模型拿到细节。
- 在对话记录里，已发送的评论折叠成一个 chip（#1 comment ▾）；点击它，展开模型读到的那个块。

环境要求

- DeepSeek Harness Desktop，带右侧栏的 Browser 标签页。
已在 0.2.1-rc.3（Electron 44.7.0，Windows x64）上验证。
- 在同一窗口里，Browser 标签页打开一个 http(s) 页面，且与聊天同窗。
- 构建和测试需要 Node.js 22.19+ 或 24+（运行时不需要）。

不支持：Web 配置档（它的 Browser 是站点源上的 iframe，没有站点配合就无法注入）、外部系统浏览器，以及 file:/data: 页面。

安装

可安装的包是 packages/deepseek-harness-element-picker。
它是普通的 Harness 配置档包：一行记录、一个客户端模块，自身没有依赖。

git clone https://github.com/safroigor/dh_picker.git
cd dh_picker
node scripts/build.mjs # regenerates packages/.../client.js from src/

然后把它装进 desktop 配置档：

Windows（PowerShell）

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
plugin --profile desktop add ".\packages\deepseek-harness-element-picker"

macOS

"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
plugin --profile desktop add "$PWD/packages/deepseek-harness-element-picker"

Linux / dsh 在 PATH 上

dsh plugin --profile desktop add "$PWD/packages/deepseek-harness-element-picker"

dsh plugin add 会为该配置档运行 pnpm，把包记录到 $DSH_HOME/profiles/desktop/package.json，并加入 dsh.profile.bundles。

重启一次 DeepSeek Harness，让配置档带上新包重新组合。重启后，只要 Browser 页面开着，聊天 composer 里就会出现 Select element。

不重启也能验证安装：

& "…\dsh.cmd" plugin --profile desktop --dump-config | Select-String "element-picker"

配置档把这个包记成指向当前 checkout 的 link:。别移动这个目录，移动后要重新安装。

更新

git pull
node scripts/build.mjs
dsh plugin --profile desktop add "$PWD/packages/deepseek-harness-element-picker"

如果只改了 client.js（常见情况），重载窗口（Ctrl+R） 就能加载新的客户端模块；只有配置档本身变了（安装、包列表、行配置），才需要完整重启。

卸载

dsh plugin --profile desktop remove deepseek-harness-element-picker

删除该行、客户端模块和配置档依赖。不会改动任何 Harness 安装文件、网站和会话数据。

用法

1. 在 Browser 标签页（右侧边栏）打开一个页面。
2. 点击聊天输入框里的 Select element。输入框状态栏会确认已进入选取模式。
3. 把鼠标悬停在页面上：光标下的元素会显示轮廓。点击它。选取或输入期间，页面无法跳转，也不会触发事件处理器。
4. 输入评论，按 Enter。正在编辑的消息里会出现一个标签块：

text
[Element 1 · Reduce the top padding to 24px…]

不会发送任何内容 —— 和附加文件完全一样。选取模式保持开启，等待下一个元素。
5. 重复操作。每条评论都是独立的标签块。
6. 点击页面上带编号的标记，重新打开对应评论；保存后更新标注，并就地重命名它的标签块。
7. 删除标签块，即可移除该标注及其标记。
8. 准备好后按输入框的 Send，可以带自己的文字，也可以不带。一次请求会发出你的指令，以及每个标签块对应的一个结构化块。发送后（或清空消息后），选取模式自动重置。

键盘

| 按键 | 位置 | 效果 |
| Enter | 评论编辑器 | 保存评论并添加标签块。绝不发送请求。 |
| Shift+Enter | 评论编辑器 | 换行。 |
| Escape | 评论编辑器 | 丢弃当前草稿，留在选取模式。 |
| Escape | 选取模式 | 退出选取模式；页面恢复可用，标记保留。 |

页面内 UI

页面只显示三样东西，都不是面板：

锚定到所选元素的行内评论编辑器

- 悬停轮廓，带简短的元素标签，
- 所选元素旁的行内评论编辑器（限制在视口内），
- 已标注元素上的小编号标记。

查看、编辑和发送都在输入框和对话记录里完成。

智能体收到什么

每个标签块都会就地替换为一个有界块（最多约 8 行，约 1.4 kB）： text Element 1 — — comment: “Reduce the top padding to 24px.” selector: #cta classes: btn btn-primary · text: “Buy now” · box: 81×33 at (496,58) styles: padding: 8px 14px · font-size: 15px · color: rgb(255, 255, 255) html: Buy now react: PricingCard ← App (/src/Card.tsx:42:7) page: https://example.com/pricing — Pricing

selector 是临时定位符，永远不是身份标识。文本、类名、标记片段、盒模型和框架提示，才能让智能体把评论映射到源码组件。React 提示包含所属组件栈，开发构建里还有 _debugSource 的 file:line；Vue 提示使用 __vueParentComponent。

载荷

每条保存的评论，都会有一个标注跨过页面与嵌入方的边界。
- Schema：schema/annotation.schema.json（schemaVersion: 1）
- Types：types/index.d.ts jsonc { "schemaVersion": 1, "kind": "dsh-visual-feedback/annotation",
"annotation": {
"ref": "element-1", "index": 1, "comment": "Reduce the top padding to 24px.",
"createdAt": "…", "pageUrl": "…", "pageTitle": "…",
"element": {
"tag": "button", "id": "cta", "classes": ["btn", "btn-primary"], "text": "Buy now",
"selector": "#cta", "alternativeSelectors": ["button.btn.btn-primary"], "xpath": "/html/body[1]/…", "outerHTML": "Buy now",
"rect": { "x": 496, "y": 58, "width": 81, "height": 33, "docX": 496, "docY": 58 },
"styles": { "padding": "8px 14px", "font-size": "15px" },
"framework": [{ "framework": "react", "componentStack": ["PricingCard", "App"],
"source": "/src/Card.tsx:42:7" }],
"context": { "parent": { "tag": "div", "selector": "#hero" }, "parentHTML": "…" }
}
}
}

采集到的数据会做净化并限制大小：密码输入框和隐藏输入框会被脱敏，value、checked、selected、srcdoc 和 on 属性会被丢弃，data- 走白名单，带凭证类参数的 URL 会被脱敏，文本、HTML 和样式都有大小上限。

安全

- 访客页面沿用出厂策略：sandbox: true、contextIsolation: true、nodeIntegration: false，不加载 preload。插件不会削弱其中任何一项。
- 没有任何特权对象进入页面。页面只返回纯 JSON，适配器在使用前会限制并校验每个字段。
- 覆盖层隔离在 shadow root 里，除自身控件外都是 pointer-events: none，只在拾取/编辑模式下拦截页面点击。
- 不向站点写入任何东西（不碰 DOM、storage 或 cookie），也不新增后端：bundle 的 Host 部分刻意留空。
- 标注文本最终进入已提交的消息，因此和普通消息文本一样，重载和 fork 之后依然存在。

上报策略见 SECURITY.md。

限制

- 仅桌面端，且仅右侧栏 Browser（见环境要求）。
- 跨域 iframe 是不透明的：在里面点击，标注的是 元素。
- closed shadow root 无法检查；open 的会向下遍历，并记录宿主选择器。
- 会话进行期间，标记浮在页面之上（18 px 徽标）。会话结束后它们消失：发送之后，或所有 chip 都被删除时。
- 对话记录存的是展开后的块，不是 chip：chip 只是消息文本的渲染器，详情本来就在消息文本里。复制消息复制的是块。
- 输入框里的 chip 是原子的：改评论要在页面上改（标记 → 编辑器），不能直接编辑 chip 文本。
- 没有截图。 webview.capturePage(rect) 是存在的，但设备像素映射和第二个
- 附件流程未随包发布。
- 多个可见 Browser 窗格：以最大的可见 guest 为目标；每条标注记录各自的页面 URL。
- SPA 路由变化保留会话；标注保留捕获时的 URL。真正的导航会关闭会话并明确提示——标注绝不会被静默重新关联。
- 此版本的 UI 文案仅提供英文。

故障排查

| 现象 | 原因与修复 |
| 输入框里没有 Select element 控件 | 插件包已安装，但应用未重启：配置档在启动时组装。重启 DeepSeek Harness，然后检查 dsh plugin --profile desktop --dump-config。 |
| 控件置灰 | 没有可用的 Browser 页面：在 Browser 标签页打开一个 http(s) URL 并保持可见。工具提示会说明原因。 |
| 控件可用，但悬停页面无反应 | guest 拒绝了注入。在 Browser 中重新加载页面（工具栏刷新），然后再次点击开关。 |
| 插件更新后，页面行为仍像旧版本 | 页面会保留注入的构建，直到发生导航。重新加载 Browser 页面或 Harness 窗口。 |
| 发送的消息显示原始 Element 1 — … 文本，而不是 chip | 消息在 0.2.0 块格式化之前发送，或同一行后面还有第二个块；更新插件后重新发送。 |
| 拾取模式一直处于激活状态 | 已在 0.2.0 修复：重置现在由插件监视输入框，而不是由 slot 组件监视。更新并重新加载。 |

开发 bash
node scripts/build.mjs # regenerate packages/…/client.js
node scripts/build.mjs --check # fail when the committed bundle is stale
node --test "tests/unit/.test.mjs" "tests/integration/.test.mjs"
node scripts/docs-screenshot.mjs # regenerate docs screenshots
node scripts/inspect-harness.mjs --list sidebar-browser # inspect the installed app.asar

测试套件通过 playwright-core 在真实 Chromium 中运行拾取器（npm i -D playwright-core，或将 PLAYWRIGHT_CORE 指向现有安装）。它需要 Chromium 系浏览器；harness 会启动 Chrome/Edge，或在环境禁止管道 stdio 时通过 CDP 自行启动浏览器。

| 套件 | 覆盖内容 |
| tests/unit/selector.test.mjs | 选择器生成、唯一性、备选方案、XPath、shadow root、iframe |
| tests/unit/sanitize.test.mjs | 密码/隐藏字段脱敏、属性剥离、URL 脱敏、大小限制 |
| tests/unit/annotation.test.mjs | 生成的标注与已发布 JSON Schema 的对比、重新编号 |
| tests/unit/client-adapter.test.mjs | 构建产物契约、slot/source 注册、校验、chip 文本、transcript 匹配器（无需浏览器） |
| tests/integration/picker.test.mjs | 选择、编辑器、键盘、标记、多标注、标记编辑、重置、视口钳制 |

仓库布局：

src/page/picker.js 与框架无关的页面包（picker 本体） src/harness/client.js Harness 客户端适配器（构建时内联进最终发布的包） packages/…/ 可安装的包：client.js（生成）、patch、locale、icon schema/, types/ 带版本号的载荷契约 tests/ 测试夹具、辅助函数、单元测试与集成测试套件 docs/ 架构、迁移、截图 scripts/ 构建、Harness 检查器、文档截图

提交 pull request 前先看 CONTRIBUTING.md。

版本管理与升级

- 插件版本遵循 semver；载荷自带整数 schemaVersion，页面包自带 PICKER_VERSION（更新后仍存活的页面会替换掉过期的注入构建，而不是复用它）。
- CHANGELOG.md 记录用户可见的变更。
- docs/MIGRATION.md 精确列出本插件依赖哪些 Harness 与 Electron 接口、Harness 升级后如何重新核对这些接口，以及每个接口最小的兜底方案。

其他方案

- TEGONG00/dsh-plugin-browser —— 一个由 Playwright 驱动的录屏面板，带元素→输入框标签的 picker。它自带浏览器界面；本插件标注的是内置 Browser 实际正在显示的页面。它的 picker 脚本和引用标签设计启发了本插件的工作。
- pick / picked 技能（Chrome 扩展 + 一个 picker MCP 服务器）在独立的 Chrome 实例里工作，看不到 Harness Browser。

许可证

MIT。