dsh-sidebar-browser
DSH（DeepSeek Harness）动态插件：一个长在右侧栏里的浏览器，元素拾取是它的一项能力。多标签页、缩放、手机/平板视口、记住账号密码，页面就在侧栏里跑。需要时点「拾取」再点页面上的任意元素，元素就以 [标签][DOMn] 进入输入框，完整信息由模型通过 read_picked_element 工具按需读取。
新版 DeepSeek Harness 自带了一个只做浏览的「浏览器」页签，插件用自己的页签类型（「浏览器 · 拾取」）与它并排：内置那个继续负责日常浏览和聊天里的「在侧边栏打开链接」，这个负责代理浏览、开发调试和拾取。两者互不顶替。
原理
浏览器不允许跨源读取 iframe，而拾取必须读到目标页面的 DOM。所以插件在 loopback 上为每个「对话 + 目标源」开一个反向代理端口，把它当作目标站点的「同源替身」：外壳页面（工具栏 + 高亮框 + 拾取逻辑）与被测页面同源，于是能直接读 contentDocument、悬浮高亮、点击拦截、快照元素；这个源又和 DSH GUI 不同源，被测页面因此碰不到 GUI 的 DOM，也无法用 window.top 导航走 GUI。
代理把整个源映射到目标站点的根（不改写 URL，用 location.origin 拼绝对地址的应用照常工作），原样隧道转发 Upgrade（Vite / Next 热更新可用），只动框架相关响应头：摘掉 X-Frame-Options / CSP、去掉 Set-Cookie 的 Domain、把指向目标源的绝对 Location 改回本端口。同源多标签共用一个端口，异源各自一个，cookie 与 localStorage 不会在站点之间串。
特性
| 特性 | 说明 |
|---|---|
| 多标签页 | 标签条跟随页面标题；＋ 新建、×/中键关闭；target="_blank"、window.open、外链都变成新标签页而不是逃出代理 |
| 页面不会丢 | 标签状态由 host 持有，所有 iframe 始终挂载（切标签只换可见性），iframe 地址钉在产生它的那次导航上——拾取、标题变化这类重渲染不会重载页面 |
| 重启后还原 | 标签、地址、缩放、设备预览镜像到 localStorage，DSH 重启后自动恢复（页面本身会重新加载） |
| 缩放 25%–300% | 按 宽度/缩放 布局再整体 transform，媒体查询按缩放后的宽度生效，和真实浏览器缩放一致，不是拉伸模糊 |
| 手机 / 平板视口 | Galaxy S23、iPhone SE / 15 Pro / 15 Pro Max、Pixel 8、iPad mini / Air / Pro 11"，可横竖屏；页面拿到真实的窄视口，@media 真的命中 |
| 手动分辨率 | 点工具栏的尺寸读数（400×700）直接输入宽 × 高，回车应用，Esc 取消；尺寸在 160–4096 之间取整，可横竖屏，会随标签一起记住并在重启后还原 |
| 原生侧边栏页签 | 注册为右侧栏自己的页签类型「浏览器 · 拾取」，与文件/终端/Git 并列，无第三方依赖 |
| 输入框入口 | 工具行十字图标：浏览器为空时打开记忆中的地址，否则只把面板唤到前面，绝不会导航走你正在编辑的页面 |
| 记住账号密码 | 登录提交后像浏览器一样问「保存 localhost:8081 的账号密码？」，之后打开该站点自动填入（触发 input/change，React/Vue 受控表单也认）；SPA 可用工具栏钥匙按钮手动保存 |
| 端口记忆 | 每个目标源记住上次用的端口并优先复用，应用自己存在 localStorage / IndexedDB 里的登录态不会因为重启换端口而失效 |
| 拾取 | 点击即插入 [标签][DOMn]（同一次拾取去重）；完整信息含 HTML、CSS 选择器、DOM 路径、全部属性、坐标与尺寸、关键计算样式、页面 URL 及拾取时的视口尺寸 |
| 不注入被测页面 | 高亮框画在外壳里，被测 DOM 一个节点都不加；工具栏「拾取」或页面内 ` 启停，Esc 退出 |
| 地址栏容错 | localhost:3000/admin 这种不带协议的写法会被当成主机与端口；mailto: / file: 之类才拒绝 |
| 按需启停 | 端口在被打开时才分配，插件加载本身不开任何端口 |
安装
已装在 DeepSeek Harness 的 desktop profile（~/.dsh/profiles/desktop）上。重装或换机器：
node tools/install-into-profile.mjs --dry-run # 先看要改什么
node tools/install-into-profile.mjs # 幂等：软链 + link: 依赖 + bundle 挂载
node tools/uninstall-from-profile.mjs # 卸载 / 回退
不给参数时脚本自己找 profile：先认 ~/.dsh/profiles/desktop（DeepSeek Harness），其次 ~/Library/Application Support/dsh-desktop/harness/profiles/web（旧 DSH Desktop，插件最早的目标）。--profile / --name、$DSH_PROFILE_DIR / $DSH_HOME 依然优先。
脚本还会清掉改名前的旧包名残留（本包以前叫 dsh-sidebar-element-picker），并把旧的窗口版拾取器（dsh-webpage-element-picker）置为 disabled——它注册同名的 read_picked_element，不能并存。
为什么用 bundle 挂载：包自己在 cordis.patch.yml 里声明了要挂的那一行，装进 profile 的 dsh.profile.bundles 就完事；手写一行 insert 到 profile 的 cordis.patch.yml 会是同一个 entry id 的第二次挂载。
改完什么时候生效：
# profile 的 bundles 列表与 cordis.patch.yml 都是热加载的，装 / 卸都不用重启
# 改 client 半（lib/client.js）：模块图自己推送，跟不上就硬刷新页面
# 改 resources/（外壳页面）：新开一个标签页或换源，下一个代理端口生效
# 改 host 半（lib/index.js、resources/proxy.js）：默认要重启 app ——
# 除非给 profile 的 cordis.patch.yml 加上模块热重载（本机已加）：
#
# - id: hmr
# config:
# root:
# - /Users/ravooo/Code/Github/dsh-sidebar-browser/lib
# - /Users/ravooo/Code/Github/dsh-sidebar-browser/resources
#
# 加上后存盘即重挂；代价是重挂会清空插件内存态（已开的标签页、DOM 编号）
# 旧的 DSH Desktop：bundle 属于启动期配置，必须重启应用
⚠️ 目录改名后必须重跑安装脚本：profile 里的软链与 link: 依赖会指向旧路径，面板报 ENOENT ... resources/chrome.html。
使用
- 点输入框工具行的十字图标 → 右侧栏打开「浏览器 · 拾取」页签；还没有页面时直接打开上次的地址（从没用过则打开默认地址），没有启动页。
- 地址栏输入回车换页；
＋开新标签，×或中键关闭，点标签切换（不重载）。 − / 100% / + / ⤢缩放；设备下拉切手机 / 平板视口，↻横竖屏；点右边的尺寸读数（如1440×900）可以手动输入任意宽 × 高，回车应用——面板会切到「自定义」。- 点「拾取」或按
`，划过元素出现高亮与选择器提示，点击即插入[提交订单][DOM1]。 - 继续提问（如「把 [提交订单][DOM1] 改成红色」）；模型需要细节时调用
read_picked_element。登录场景先按`退出拾取模式。
面板永远直接给浏览器页：空浏览器会立刻自动打开上次的地址（最近访问 → 默认地址兜底），关掉最后一个标签页会立刻把刚才那一页重新打开（取的是页面上正在显示的那个地址，不是别处记住的另一个），地址栏就在页面工具栏上。打开页面的调用失败时面板会说出原因并保持可用，不会卡在「正在打开…」。
校验
npm test # 四个套件，不需要 DSH、不需要浏览器
npm i -D playwright-core && npm run test:browser # 真 Chromium 跑完整流程（或设 DSH_TEST_CHROME 指向本机 Chrome）
需要目标站点的套件默认起自带的 fixture 站点（resources/test/fixture.mjs，故意带难缠响应头），所以不依赖你本机跑着什么；想打真实站点就把地址作为第一个参数传入，例如 node resources/test/proxy-smoke.mjs http://localhost:3000。
| 套件 | 覆盖 |
|---|---|
proxy-smoke.mjs |
外壳资源、能力 cookie 门禁、目标文档与子资源代理、frame-ancestors 摘除、pick 接收 |
tunnel-smoke.mjs |
裸 socket 跑 Upgrade：101 握手、Host 改写、Sec-WebSocket-Accept、双向字节 |
host-smoke.mjs |
/invoke 全部方法、标签增删改选、同源共端口 / 异源分端口 / 关闭释放、快照还原、手动分辨率（存储 / 取值域 / 无值兜底）、read_picked_element |
client-smoke.mjs |
装载与页签槽位注册、空则开页（含默认地址与无启动页）、关最后一个标签自动重开（且重开的是屏幕上那一页）、开页失败不卡死、切标签与拾取后不重载、缩放设备与手动分辨率随 URL 还原、拾取去重写入草稿、自定义 scheme（dsh-app://app）下帧仍指向 loopback |
browser-e2e.mjs |
上面全部在真 Chromium 里跑通：视口 / 横竖屏 / 缩放、手输 400×700 后媒体查询真的命中、同异源导航分流、手机视口下高亮与拾取、登录自动填入、密码框在元素记录中被抹除、跨站页面里框架同样加载（app 的 dsh-app://app 形状） |
npm run screenshots 生成上架截图。
结构
lib/index.js host 半：每个对话的浏览器状态 / 代理端口 / 上下文 / 工具 / 系统提示 / /invoke
lib/client.js client 半：输入框按钮 + 原生「浏览器 · 拾取」页签（标签条 + 每标签一个 iframe）
resources/proxy.js 每个（对话, 目标源）一个 loopback 反向代理（含 Upgrade 隧道）
resources/chrome.* 浏览器外壳（工具栏 / 缩放 / 设备预览 / 同源拾取），由代理在自身源上提供
resources/test/ 五个套件 + fixture 目标站点
tools/profile-location.mjs 在 DeepSeek Harness / DSH Desktop 之间找 profile
tools/ 幂等安装与卸载
docs/research/ 动手前对 DSH 侧边栏 / 宿主 / 旧插件的逐项考证
已知限制与信任边界
- 同源既是拾取的前提，也是信任边界：被测页面理论上能访问外壳页面，也就能伪造一次「拾取」把内容推进对话上下文。只浏览你自己信任的页面。
- 保存的账号密码是 DSH GUI 源 localStorage 里的明文（这里没有系统钥匙串），按目标源一一对应；不发往 host、不进对话、不出现在拾取结果里（密码框
value被显式抹除）。 - 代理会摘掉被测页面的 CSP 与
X-Frame-Options——这正是原本不能被框的站点现在能被框的原因，也意味着页面的安全策略在侧栏里不生效。 /dsh-sidebar-browser/invoke走 webServer 的精确路由，不在 GUI 的登录围栏内（和它并列的插件路由都一样）。GUI 默认只绑127.0.0.1，但如果你把 web 服务改成对外监听，这个端口上任何人都能读写浏览器状态。- 设备预览是视口预览：媒体查询、布局、滚动按设备尺寸生效，但
devicePixelRatio、pointer: coarse、hover: none、User-Agent、触摸事件仍是桌面浏览器的。 - 面板窗口和代理都必须在本机：代理只绑
127.0.0.1，帧地址也一律按 loopback 拼（GUI 自己是localhost/127.0.0.1时沿用它的主机名，保持同站；DeepSeek Harness 的 GUI 跑在dsh-app://app，不是 http 源，所以显式用127.0.0.1）。从别的机器打开 GUI 时，浏览器到不了这台机器的 loopback 端口。 - 页签类型按 kind 唯一，所以浏览器面板同时只有一个，标签页在面板内部；内置的「浏览器」是另一个 kind，两边各自开各自的。
- 元素按「光标下最内层元素」命中，高亮会先告诉你要选的是哪一层；嵌套 iframe 内部的元素暂不支持。
- DSH 重启后页面会重新加载（地址 / 标签 / 缩放 / 视口还原），重启前未提交的表单内容不保留。
发布
投稿目标是精选列表 awesome-dsh-plugin：往 data/plugins/ 加一个 YAML 条目（submission/ 里已备好），市场和 dsh-market 会在一天内自动收录。完整步骤见 PUBLISHING.md。
License
MIT
