点击定位源码 GULI-lab/DSH-element-source

dsh-element-source

给 DeepSeek Harness 内置浏览器用的点击定位源码插件。

在 DSH 桌面端的「内置浏览器」里打开你的前端 dev 页面，从浏览器自己的工具栏开启拾取，再点击目标元素右下角的 「添加到对话」 气泡。元素对应的源码文件（连同行号）会以 文件引用 chip 的形式进入当前会话输入框；点击这个 chip 会在内置预览里直接滚动到对应行。
默认不会发送任何消息。

0.2.0 —— 围绕内置浏览器重建

这是一次有意为之的产品面重置：插件只围绕 DeepSeek Harness 内置浏览器工作，不做别的。

- 只支持内置浏览器。 旧的「本地预览」Tab、右侧停靠侧边栏、iframe 预览和预览代理全部删除；请使用 DSH 桌面端自带的内置浏览器。
- 不再兼容 dsh-better-sidebar。 与它的集成、侧边栏「本地预览」Tab 和兜底侧边栏都已移除；两者同时安装不再是受支持配置。如果你只是为了本插件才装 dsh-better-sidebar，可以卸载它。
- 浏览器工具栏里只多一个图标。 在开发页面上，插件把「选择元素」图标追加为 浏览器工具栏的最后一项（在「外部打开 ↗」右侧），地址栏自动让位；没有插件的地址栏、标签页或侧边栏。页面一旦不是开发页面，图标会被移除。
- 拾取默认开启，页面受保护。 拾取模式下普通页面点击和右键菜单都会被拦截（不导航、不切主题、不提交表单），只有「添加到对话」气泡执行定位——你本想选中元素的那一次点击，绝不会变成对页面的操作。
- 定位结果变成文件引用 chip。 当前会话输入框会收到「文件 + 行号」的 chip；点击 chip 能在内置预览里直接滚到那一行。插件永远不会替你发送消息。
- 安装到 desktop profile。 内置浏览器在桌面端里，所以一键安装脚本默认使用 desktop profile。

为什么移除旧预览？ 内置浏览器已经提供地址栏、标签页、历史、Cookie 和 Electron 会话；再造一套 iframe/代理只是重复，还会和 dsh-better-sidebar 抢同一个入口。
插件现在只做两件事：把选择器加到浏览器工具栏，把定位结果交给当前聊天输入框。

前置条件

| 条件 | 说明 |
| DSH | DSH 桌面端 0.2.x，且内置浏览器可用。纯网页的 dsh web 页面没有 Electron <webview>，不会出现选择图标。 |
| 前端 | 正在运行的 dev server（Vite / webpack 等），页面必须是 开发构建。 |
| 工作区 | 当前会话的工作目录必须是前端项目根目录；解析结果落在工作区外会被拒绝。 |
| 框架 | React、Vue 2/3、Svelte、Angular、code-inspector，或通用文本搜索兜底。 |

生产构建没有运行期源码元数据，因此选择图标只在开发页面出现。

安装

一条命令安装到 desktop profile：

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/GULI-lab/DSH-element-source/main/scripts/install.sh | DSH_PROFILE=desktop bash

Windows PowerShell 5.1+ / pwsh：

$env:DSH_PROFILE = "desktop"
irm https://raw.githubusercontent.com/GULI-lab/DSH-element-source/main/scripts/install.ps1 | iex

手动安装：

cd ~/.dsh/profiles/desktop
npx -y --package @deepseek-ai/dsh dsh plugin --profile desktop add dsh-element-source

如果你的桌面端使用别的 profile 名称，把 desktop 换成实际名称。
安装完成后重启 DSH，或重新加载桌面端窗口，让浏览器端代码生效。

本地源码试用：

git clone https://github.com/GULI-lab/DSH-element-source
cd ~/.dsh/profiles/desktop
npx -y --package @deepseek-ai/dsh dsh plugin --profile desktop add link:/path/to/DSH-element-source

使用

1. 启动前端 dev server，例如 http://localhost:3000。
2. 打开 DSH 内置浏览器，访问这个地址。
3. 如果页面是开发构建，浏览器工具栏最后一项（↗ 右侧）会出现 选择元素图标；拾取开启时图标高亮，默认已开启。
4. 鼠标悬停目标元素：出现虚线轮廓，以及元素右下角（元素外侧）的 「添加到对话」 气泡——不会盖住元素内容。
5. 点气泡，不要点页面。 拾取开启时页面点击会被拦截，只有气泡会执行定位。
定位结果会以文件引用 chip 的形式进入当前会话输入框，例如 LoginPage.tsx:90。
6. 在输入框补充你的修改需求并发送。助手会读取文件、展示定位到的代码，然后等你提出修改。
7. 点击输入框里的 chip，可在内置文件预览中直接滚到对应行。

按 Esc 或点工具栏图标可关闭拾取，页面点击恢复正常；图标颜色和提示文字会反映当前状态。

拾取默认开启，这是为了避免「想定位却点成了页面操作」。代价是普通点击被拦截；需要正常操作页面时，先按 Esc 或点工具栏图标关闭。

输入框里收到什么

- 主路径：一个 文件引用 chip，例如 LoginPage.tsx:90，与内置 @ 文件菜单使用同一套 @path 引用语义；序列化后是 @path:90，模型能拿到具体行号；chip 可点击，点击后在内置预览里跳到对应行。
- 兜底：如果输入框的引用 API 不可用，则追加纯文本 [元素定位] src/App.vue:12。
- 默认不发送。只有把 autoSteer 设为 true，拾取成功后才会额外唤醒当前会话助手，并发送一条双语定位消息。

配置

在 profile 的 cordis.patch.yml 中覆盖插件行：

- id: element-source
config:
autoSteer: false # 拾取后是否唤醒助手（默认 false：只填输入框草稿） mappings: # 源码路径前缀映射（monorepo / node_modules 重定向）
- find: '@app/ui/src'
replacement: 'D:/workspace/my-app/packages/ui/src'
sessionId: 'fixed-session' # 固定会话（一般不需要）

- autoSteer：默认 false。设为 true 时，定位成功后会同时唤醒当前会话助手，但不会替你发送输入框里的草稿。
- mappings：路径前缀重写，在规范化之前应用；最终路径仍必须落在会话工作区内。
- sessionId：把解析固定到某个会话；默认使用当前会话。

proxyHosts 已移除；不再有预览代理。

工作原理

DSH 桌面端 └─ 内置浏览器 <webview> ├─ dev 页面：在 dom-ready / did-navigate / did-navigate-in-page 时注入探针 │ 悬停 → 「添加到对话」气泡 → 拾取结果写入 window.__dshEsPicks ├─ 工具栏：把选择元素图标追加为最后一项（仅 dev 页面； │ 页面变为非开发页面时自动移除） └─ 客户端 overlay 每 300ms 轮询 webview 拾取 → POST /dsh-element-source/api/pick （公开、只写的队列） host → GET /dsh-element-source/api/pending （信任围栏 + 真实会话）在会话 cwd 内解析 → file[:line[:column]] client → 当前会话输入框中的文件引用 chip chip 点击 → 内置文件预览滚动到对应行

没有页面代理，也没有第二套 UI。探针直接注入 Electron <webview>，页面保留真实 origin 和自己的网络行为。解析有预算（2.5 秒搜索上限、60 秒结果缓存），大 monorepo 里拾取也不会卡住输入框。

框架支持

| 框架 | 文件 | 行 | 说明 |
| React（dev 构建） | 精确 | 精确 | 读取 fiber 上的 JSX __source（@vitejs/plugin-react / CRA 注入） |
| Vue 2 / Vue 3（dev 构建） | 精确 | 近似 | __file 定位文件；行号由模板文本匹配 |
| Svelte（dev 构建） | 精确 | 精确 | 读取 dev 模式的 __svelte_meta |
| Angular | 尽力 | 尽力 | 识别 ng-reflect- 标记，再走组件/文本搜索 |
| 任意框架 + code-inspector-plugin | 精确 | 精确 | 直接读取注入的 data-insp- DOM 属性 |
| 其他 / 未知框架 | 可以 | 近似 | 在会话工作区内按文本 / 类名 / id 全文搜索 |

可选：在内置浏览器之外调试

内置浏览器是受支持的主路径，也只有它会显示工具栏图标。如果你必须在普通浏览器里检查页面，可以自行加载探针；拾取仍会通过同一队列进入 DSH 桌面端。

方式 A：script 标签：

方式 B：Vite 插件：

// vite.config.ts
import { defineConfig } from 'vite'
import { dshElementSourcePlugin } from 'dsh-element-source/vite-plugin'

export default defineConfig({
plugins: [dshElementSourcePlugin(), /* 你的其他插件 */],
})

Vite 插件只在 dev 注入（apply: 'serve'），生产构建不受影响。如果 DSH 不在默认地址：

dshElementSourcePlugin({ dshOrigin: 'http://192.168.1.5:3080' })

这种模式没有工具栏图标；探针在开发页面自动开启并显示「添加到对话」气泡。
DSH 桌面端必须保持运行，拾取才会被当前会话取走。

安全

- POST /dsh-element-source/api/pick 是公开且允许跨域的，因为页面运行在隔离的 webview 里；它只写不读，队列有界（32 条），不返回拾取数据。
- GET /dsh-element-source/api/pending 与 DSH /api 网关使用同一套浏览器信任围栏，并要求真实会话。
- 解析使用会话的权威 cwd；落在工作区外的文件会被拒绝。mappings 只能重写前缀，不能逃出工作区。
- inject.js 是公开的只读探针代码，只收集元素元数据和可选的框架源码元数据，不访问 DSH 数据。
- 不再有预览代理，也不再任意抓取 URL，旧代理的 origin 取舍问题一并消失。

从 0.1.x 迁移

| 旧行为 | 新行为 |
| 独立「本地预览」Tab / 右侧边栏 | 只使用 DSH 内置浏览器 |
| dsh-better-sidebar 集成 | 已移除，不再支持 |
| GET /dsh-element-source/preview 代理 | 已移除（404） |
| proxyHosts 配置 | 已移除 |
| 安装到 web profile | 安装到 desktop profile |
| 拾取后向输入框插入纯文本 | 文件引用 chip（+ 纯文本兜底） |

autoSteer、mappings、sessionId 仍然有效。
0.1.x 安装可能还留下 dsh-better-sidebar，不再需要时请单独卸载。

常见问题

| 现象 | 检查项 |
| 工具栏没有选择图标 | 使用 DSH 桌面端的内置浏览器，而不是普通浏览器里的 dsh web 页面；页面必须是开发构建；确认插件装在 desktop profile，然后重启应用。 |
| 有图标，但悬停没有「添加到对话」气泡 | 探针可能没激活：页面可能是生产构建，或页面在插件之前加载。刷新页面再悬停。 |
| 拾取成功，但输入框没有结果 | 当前会话需要工作目录。把会话工作区切到项目根目录，并确认 DSH 应用在运行。 |
| 提示定位结果在工作区外 | 解析出的文件不在会话 cwd 内。把会话工作目录切到项目根目录。 |
| 点 chip 打开预览停在顶部，没跳到行 | 行号按本次运行插入的 chip 记录；App 重启后恢复的旧 chip 会退化为从顶部打开，重新拾取一次即可恢复跳行。 |
| dsh-better-sidebar 里还显示旧的「本地预览」Tab | 那是 0.1.x 的旧集成。安装新版本并重启；如果 better-sidebar 只为这个插件安装，可以卸载。 |
| autoSteer 没有唤醒助手 | 会话必须有在线 agent；单纯拾取不会发送消息。 |

已知限制

- 仅桌面端。 纯网页的 dsh web 没有 Electron <webview> 页面，工具栏图标和探针都不会出现。
- 仅开发页面。 生产构建没有运行期源码元数据，图标会隐藏并从该页面移除。
- 工具栏 DOM 是内置实现。 选择图标追加在内置浏览器工具栏上；未来 DSH UI 重构可能需要插件同步更新。
- 工作区限制。 如果会话工作区不是项目根目录，定位会落到错误目录或被拒绝；请先切换会话工作区。
- Vue 行号是启发式。 纯图标 / 无文本元素可能退化为文件级或组件定义行。
- Angular / Svelte 需要 dev 构建。 生产构建没有可用源码元数据。
- autoSteer 需要会话助手在线。 它只唤醒已有 agent，不会替你发送输入框草稿。
- 不支持 dsh-better-sidebar。 旧侧边栏入口已不存在，也没有兜底侧边栏。

开发

pnpm install
pnpm typecheck # tsc --noEmit
pnpm test # vitest：draft / probes / protocol / resolve / steer
pnpm build # tsc 类型 + tsdown 产物

产物：lib/index.js（host）、lib/client.js（浏览器端）、lib/inject.js（页面探针）、 lib/vite-plugin.js（可选 Vite 注入）。

参与贡献

欢迎贡献！开发环境搭建与提交流程见 CONTRIBUTING.md。
发现 bug 或有新想法，欢迎开 issue。

License

MIT © dsh-element-source contributors