前言¶
在 DeepSeek Harness（DSH）里和 agent 改前端时，常见做法是截图加口头描述：「下面那个蓝色按钮」「左下角卡片」。agent 只能对着像素猜元素，你也难以把 selector、样式和布局意图一次说清。若页面还在 localhost 或 dev server 上，公网 iframe 往往被 X-Frame-Options、CSP 拦住，侧边栏更难直接对照真实页面。
dsh-sidepanel-web 由维护者 AleixRocal 发布，归类为联网工具。它在 DSH Web 右侧边栏增加 浏览器 标签页：本地开发页走同源代理保持可交互，公共站点由宿主机 Chromium 经 CDP 渲染。你可以在页面上点选元素、写备注，把 selector、HTML 片段、计算样式、位置与一张带标注钉的截图一并插入对话。
这是什么¶
dsh-sidepanel-web 是对话旁的一个真实浏览器面板，核心是把「页面上的某个 DOM 节点」变成 agent 能顺着查找的结构化消息，而不是只靠截图猜位置。
- 维护者：AleixRocal（npm 作者字段为 Aleix Rocal）
- 许可证：MIT
- npm 包版本（资料中的
package.json）：0.4.1 - 运行范围：DSH Web profile（不支持 DSH Desktop）
- DSH 版本要求：
>=0.2.1-rc.2且<0.3.0-0 - Node.js：
>=22（README 写明 22.19+）
生态上，DSH 贯彻「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系，安装前仍应以 GitHub 仓库 源码与许可证为准。
核心功能¶
DOM 标注进对话¶
流程分三步：打开页面 → 在 DOM 里点选元素并写备注 → 插入 到输入框再发送。
每条标注是一段文本（含 selector、文本、HTML 摘录、计算样式、尺寸与位置、页面 URL 与标题、你的备注），后面跟 一张 带编号标注钉的视口截图。多个 pick 可先 加入列表，再一次 插入，文本块全部送出，图片仍是一张、包含全部标注钉。插入通过 InputActions.insertText 在光标处写入，不覆盖已有草稿。
两种页面载体¶
面板按 URL 自动选择载体，并按 origin 记住；也可在菜单里手动切换。
| URL | 载体 | 作用 |
|---|---|---|
localhost、*.localhost、*.local、私有/回环/link-local IP |
原生（同源代理） | 真实 DOM、完全可交互、支持标注 overlay；接受自签名证书 |
其他 http(s) 公共页 |
远程（CDP） | 宿主机 Chromium 渲染并推流，可绕过 X-Frame-Options、CSP，使用浏览器配置里的登录状态 |
本地页经 DSH 拉取并重写 URL，注入 shim 与 overlay；公共页由 CDP 转发画面与输入。两套载体产出同一套标注 payload。
边栏浏览器能力¶
- 地址栏自动补协议：公共主名默认
https://，本地/私有地址默认http://；mailto:、file:等非 Web 协议会被拒绝。 - 设备模拟：响应式、桌面 1280×800、笔记本 1440×900、平板、iPhone、Android 等预设，含触摸与
devicePixelRatio。 - 可连接已有 Chrome（
cdpUrl/wsUrl），或让插件在常见 CDP 端口探测失败后自动启动带持久 profile 的 Chromium。 - 对话里「在侧边栏打开链接」可落到
kind: "browser"标签页。
安装与启用¶
环境需满足 DSH Web profile、Node 22.19+，以及宿主机上的 Chromium 系浏览器（可自动检测，亦可用 Playwright Chromium 缓存）。
下列命令来自官方 README，任选其一：
# 从 npm
dsh plugin --profile web add dsh-sidepanel-web
# 从 GitHub
dsh plugin --profile web add github:AleixRocal/dsh-sidepanel-web
安装后重启一次 dsh web 并刷新 GUI，右侧边栏会出现 浏览器 标签页。
若要从本地源码目录开发调试，README 还提供 dsh plugin --profile web add link:/absolute/path/to/dsh-sidepanel-web；带 scope 的副本 @aleixrocal/dsh-sidepanel-web 在 GitHub Packages，规范包名仍是 npmjs 上的 dsh-sidepanel-web。
可选：复用已有浏览器登录态时，单独 user-data-dir 暴露 CDP 端口，并在 profile 里配置 endpoint：
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/chrome-dsh" &
- id: dsh-sidepanel-web
config:
cdpUrl: http://127.0.0.1:9222 # 或 wsUrl: ws://127.0.0.1:9222/devtools/browser/…
典型用法¶
- 展开右侧边栏，选择 浏览器，在地址栏输入
example.com或localhost:5173（协议会自动补上）。 - 点击 标注，悬停查看检查器信息，点击目标元素，在便签卡写下要改什么。
- 需要多个元素时选 加入列表；完成后点 插入，确认输入框内有标注文本与截图，再发送给 agent。
对话里收到的标注块结构大致如下（README 示例）：
[Annotation 1] button#save.primary
· Selector: #save
· Text: Save changes
· HTML: <button id="save" class="btn primary" type="button">Save changes</button>
· Styles: display=inline-block; position=static; color=rgb(255, 255, 255); background=rgb(37, 99, 235); font=…; padding=12px 20px; radius=8px
· Position: 132×40 @ (24, 680)
· Page: Settings https://localhost:5173/settings
· Note: Make this primary action sticky on mobile
· Screenshot: ~/.dsh/data/dsh-sidepanel-web/crops/…
用 ⋯ 菜单可切换设备预设、清除标注钉，或在 原生视图 (proxy) 与 远程视图 (CDP) 之间切换。
配置要点¶
在 ~/.dsh/profiles/web/cordis.patch.yml 中，于插件条目下设置 config，例如：
- id: dsh-sidepanel-web
config:
chromePath: /path/to/chrome
headless: true
常用键包括：chromePath、headless（默认 true）、autoLaunch、cdpUrl / wsUrl、profileDir（默认 ~/.local/share/dsh-sidepanel-web/profile）、homeUrl、device（responsive、desktop、laptop、tablet、mobile、android）、以及 CDP 推流相关的 streamMode、streamFps 等。未在资料中逐条展开的项以 README 配置表 为准。
适用场景与注意¶
适合谁：在 DSH Web 里做前端联调、对照线上或本地页面，希望 agent 直接拿到 selector 与样式而不是猜截图的人。
权限与安全：插件在 DSH 宿主机进程里运行，会启动或连接 Chromium、代理本地开发页、截取并合成标注图。安装前应阅读源码与 SECURITY.md。同源代理默认只接受本地/开发主机；对公共站点使用 强制原生视图 会让页面与 DSH 同源，仅应对你信任的站点操作。标注文本与页面内容对 agent 均应按不可信数据处理。
已知限制（README）：
- 原生载体不代理 WebSocket/HMR，热更新可能失效，可切 CDP 视图。
- 不能标注跨域 iframe 或 closed shadow DOM 内部，只能标容器。
- 跨域登录、Cookie 在部分流程仍可能失败。
- 产品阶段标注为 Alpha，API 与行为可能变化。
结尾¶
dsh-sidepanel-web 把「边看页面边改代码」收进 DSH 右侧边栏：本地页保持 DOM 级交互，公共页靠 CDP 越过嵌入限制，标注则把元素身份与意图写进对话。若要核对功能与版本，可看社区目录 SkillHub 与源码仓库 github.com/AleixRocal/dsh-sidepanel-web；npm 包名为 dsh-sidepanel-web。
