前言¶

用智能体改前端界面时，最难的往往不是改代码，而是把「改哪里」说清楚。「左边那个卡片的边距大了点」——模型得猜是哪个卡片；截一张图贴进对话——又得反复圈画。DeepSeek Harness（DSH）默认的浏览器工具多半是独立的 headless Chromium，你看不见它在操作什么，也不方便对着真实 DOM 逐条指路。

下面介绍的 dsh-web-annotate（维护者 nubeslove）把真实浏览器放进 DSH 侧栏：鼠标指向哪个元素，标签、尺寸、背景色、字体就摆在那儿，点一下写一句人话，最后汇总成带选择器的结构化清单，可一键回填对话输入框。分类属于社区目录里的「联网工具」；仓库 GitHub，目录页 skillhub.cn。

这是什么¶

一句话：DSH 侧栏网页批注——宿主里用 Playwright 起 Chromium，页面是真跑的；侧栏通过 CDP 画面流展示，支持元素拾取、就地评论、框选区域，并导出或回填成 Markdown 式指令列表。

和同属侧栏的 dsh-web-preview 相比：预览用 iframe 直出、速度快但不能跨域批注；本插件用 CDP 推帧、有几十毫秒延迟，但能指向元素并穿透 iframe（最多 4 层）。两个插件可同时安装，各占一种 tab 类型。

核心功能¶

资料与 README 中已写明的能力如下。

1. 真实浏览器与画面推流：宿主侧复用 DSH 自带的 Playwright/Chromium；Page.startScreencast 出帧，经 SSE 推到侧栏，页面变化会刷新画面。
2. 元素拾取与就地评论：开启批注模式后高亮当前元素，显示标签、尺寸、背景色、字体、字号、字重；点击元素弹出输入框，回车保存；下方列表可逐条删除。
3. 框选区域：按住拖动框一块区域批注，适合「这一整块间距不对」这类不好对应单一元素的意见。
4. 快捷键与回填：Ctrl+Shift+. 切换批注模式；点 ↩ 把汇总写进对话输入框（依赖 conversation.input.left 插槽，不可用时退回复制）；点 ⧉ 复制到剪贴板。
5. 交互转发：退出拾取后，点击、滚轮、方向键、Enter、Tab、Esc、Backspace、PageUp/PageDown 会转发给页面，可当普通预览用。
6. 批注持久化：按页面地址存 localStorage，关 tab 再开仍在；删完自动清空。
7. 页面内输入：工具栏 ⌨ 把一段文本（含中文）送进页面当前焦点，绕开键盘布局与输入法；可打印字符不走逐键转发。
8. 导出：⤓ 把汇总写成 Markdown，存到 ~/.dsh/web-annotate/。
9. 手动入口：对话输入框左侧 ◱ 网页 按钮，可随时打开面板自输地址。
10. 可被 DSH 接管：浏览器启动时暴露 CDP 端点，playwright-mcp 以 mode: attach 可接上侧栏里同一个浏览器（需先打开面板让浏览器就绪，GET /api/web-annotate/health 里 cdpEndpoint 不为 null）。
11. 模型侧提示：插件注册 web-annotate:guidance（order 8600），引导模型在调试网页、验证前端时优先让用户在侧栏打开页面，而非独立 headless 或外部浏览器；卸载插件后该段提示随插件消失。

汇总示例如下（来自 README）：

## 网页批注

页面：http://localhost:5173/

1. `#card-a`（div，936×54）
   卡片内边距太大，收到 12px

2. `#card-b.accent`（div，936×54）
   强调色换成主题蓝

安装与启用¶

安装命令以仓库 README 为准：

dsh plugin --profile desktop add "github:nubeslove/dsh-web-annotate"

然后在 $DSH_HOME/profiles/desktop/package.json 的 dsh.profile.bundles 里追加 "dsh-web-annotate"，重启 DSH。插件 dependencies 为空，Playwright 在运行时从 DSH profile 目录解析，复用自带 Chromium，不会额外下载浏览器。package.json 要求 Node >=22.19，许可证 MIT。

本地改代码可用 link（路径按你机器上的绝对路径填写）：

dsh plugin --profile desktop add "link:/absolute/path/to/dsh-web-annotate"

典型用法¶

1. 点右侧栏 tab 条的添加按钮，选 网页批注。
2. 地址栏输入例如 localhost:5173，回车；首次启动浏览器需等待数秒。
3. 点工具栏 ◱ 批注（或 Ctrl+Shift+.）进入拾取模式；指向元素看信息，点一下写评论；可拖动框选区域。
4. 点 ↩ 回填输入框，或 ⧉ 复制；需要文件时点 ⤓ 导出。

退出拾取模式后，页面可正常点击、滚动操作。

若要让 DSH 的浏览器工具操作侧栏里这个浏览器，先打开一次「网页批注」面板，再改 $DSH_HOME/profiles/desktop/cordis.patch.yml 中 playwright 提供方（README 给出完整 insert 片段：mode: attach，endpoint: http://127.0.0.1:9222），重启 DSH。端口可用环境变量 DSH_ANNOTATE_CDP_PORT 修改；未开调试端口时 cdpEndpoint 为 null，attach 会失败。退回独立浏览器时将 mode 改回 launch 并去掉 endpoint。

技术要点与边界¶

宿主入口在 lib/index.js：按地址维护 page 会话，提供创建会话、SSE 取帧、输入转发、拾取、重载、关闭等 HTTP 路由；未使用 WebSocket，输入走 POST。选择器生成走 id → 类名 → nth-of-type 降级，最多上溯 6 层。

权限方面需知：会启动本地 Chromium 进程；只放行 http/https，拒绝 file://；页面内仅执行固定的取元素信息逻辑，不注入任意脚本；批注默认在客户端内存与 localStorage，导出目录固定为 ~/.dsh/web-annotate/。无客户端连接且空闲 5 分钟后会话自动回收。

已知限制包括：帧流在快速滚动或动画多时略有延迟；拾取模式会拦截点击与滚动；iframe 穿透最多 4 层；README 写明仅在 Windows + DeepSeek Harness 0.2.x 桌面端验证过。装不上或与文档不符可发邮件 1992335297@qq.com（README 建议附插件版本、dsh --version、报错全文），或开 GitHub Issues。

结尾¶

dsh-web-annotate 把「指路改界面」收成侧栏里的点选与清单，并可选与 DSH 浏览器工具共用同一 Chromium 实例。安装前请自行查看源码与 MIT 许可证；插件以当前 DSH 进程权限运行，只访问你输入的 URL。

• 目录页：https://www.skillhub.cn/plugins/nubeslove/dsh-web-annotate
• 仓库：https://github.com/nubeslove/dsh-web-annotate

社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，按需选用即可。