dsh-annotate-browser：在 DSH 面板中标注浏览器页面

前言¶

DeepSeek Harness（DSH）的理念是「一切皆插件」，让用户在对话中直接对页面进行标注，再由 agent 修改代码。传统做法要么依赖第三方浏览器插件，要么需要手动截图、复制选择器，链路割裂、容易出错。本插件提供了一条更直接的路径：在 DSH 右侧栏嵌入一个可操作的浏览器，点选元素、写备注，带着源码位置、组件栈、样式和裁图直接插入对话。

是什么¶

这是一个 DSH 插件：zengxiaolou/dsh-annotate-browser。维护者是 zengxiaolou，分类为客户端。它不依赖 dsh-browser-cdp 或任何第三方浏览器插件，而是自己实现了一个零依赖的 CDP 客户端。插件在 DSH 右侧栏渲染一个真实可操作的浏览器，通过 CDP screencast 推流画面，支持元素高亮、选中文字、多选标注、元素裁图，并将结构化载荷写入 JSON 文件。

核心功能¶

1. 浏览与操作¶

右侧栏「标注浏览器」tab 撑满侧栏，按面板尺寸 1:1 渲染，视口随宽高自适应。
地址栏 + ← → ⟳ + 标签页（新建 / 切换 / 关闭，>1 个才显示标签条）。
支持点击 / 双击 / 右键 / 拖拽 / 滚轮 / 键盘（含 Backspace、方向键、Tab），⌘A/C/V/X/Z 转发给页面。
画面走 CDP screencast 推流，只在画面变化时推送（15fps 上限），断线自动退回 450ms 轮询。
「⋯」菜单里提供设备宽度预设（390/768/1280）、移动端模拟（触屏 + iPhone UA + 390×800@2x）。

2. 标注与插入¶

⌘I 开启标注模式，鼠标悬停时出现 DevTools 式高亮（白框 + tag/尺寸/AX 信息）。
点元素选中：穿透全屏透明遮罩，取真正被点到的元素，页面留下编号钉 + 蓝框。
拖拽 = 在页面里真实选中文字，以选区文本作为标注对象。
多选：写备注 →「加入列表」→ 继续选 →「插入 N 条」一次性写入。
标注钉的备注气泡 hover 才显示，不遮挡页面。
⌘C 复制悬停元素的载荷（不插入对话也能粘贴到别处）。

3. 携带的信息¶

选择器、属性、role/aria-label、源码位置（file:line:col，基于 React _debugSource / Vue __file / Svelte __svelte_meta）、组件栈、计算样式子集、位置与视口、父级链、父级文本上下文、outerHTML 截断、页面 route、元素裁图 PNG（~/.dsh/data/dsh-annotate-browser/crops/）、结构化载荷 JSON（~/.dsh/data/dsh-annotate-browser/annotations/<日期>-<host>.json）。输入框内只放一行摘要 + 文件路径。

4. 与「长文本胶囊」的接入¶

标注插入对话框时有两层兼容，任何一层生效都会变成胶囊：

主动：ctx.inject(["pasteChip"]) → pasteChip.insert(正文, { sessionId, span: inputActions.captureInsertion(), label: "标注 · N 条" })，原子插入，标签带条数，草稿里只有芯片。
被动（兜底）：退回 inputActions.setDraft() 追加文本，dsh-paste-chip 的差异观察器会认出「外部插入」并折叠成芯片。
回退（都不行）：pasteChip 不在 / 没有 span / 超 20 万字 → 直接写普通文本。

胶囊服务缺失时只打印一条 console.warn，不影响标注主流程。

5. 后端与自启 Chrome¶

DSH 面板是主入口，但后端可以单独起（不经过 DSH 的 web 鉴权，便于排障）：

node scripts/annotate-server.mjs：自检（连端点、列页面、抓一帧、取一个元素）。
node scripts/annotate-server.mjs start：没有端点就拉起一台无头 Chrome 并打开首页。
node scripts/annotate-server.mjs stop：关闭「本脚本拉起的」Chrome（外部端点不动）。

CDP 端点与自动启动顺序：

设置里的 wsUrl（显式指定）。
~/.local/state/ego-lite-linux/browser.json（有别的插件/脚本起了 Chrome 就复用）。
自己拉起一台 Chrome（lib/launcher.js）：--remote-debugging-port=0 + 独立 profile（默认 ~/.local/share/dsh-annotate-browser/profile），读 DevToolsActivePort 拿 ws 地址；无头优先。

6. 设置项¶

装了 @deepseek-ai/dsh-settings 时出现在插件设置页；也可以直接在 cordis.patch.yml 里写 config：

键	默认	说明
`wsUrl`	`""`	显式 CDP 端点；空 = 复用或自己启动
`chromePath`	`""`	Chrome 路径；空 = 自动探测
`headless`	`true`	自己启动的浏览器是否无头
`autoLaunch`	`true`	没有现成端点时是否自动启动
`profileDir`	`""`	空 = `~/.local/share/dsh-annotate-browser/profile`
`pollMs`	`1200`	面板拉画面间隔
`quality`	`82`	画面 JPEG 质量

- id: dsh-annotate-browser
  config:
    headless: true
    pollMs: 1200
    quality: 85

安装与启用¶

目前还未发布到 npm，直接从仓库安装：

dsh plugin --profile desktop add github:zengxiaolou/dsh-annotate-browser
# 或本地联调：
dsh plugin --profile desktop add file:~/Documents/study/探索/dsh-annotate-browser

装完重启 DSH，输入框上方应出现胶囊。

典型用法¶

启动 DSH，确认已安装并启用插件。
在右侧栏切换到「标注浏览器」tab，地址栏输入目标 URL 并访问。
按 ⌘I 开启标注模式，鼠标悬停元素查看高亮信息。
点击目标元素或拖拽选中文字，在备注栏写说明，点击「加入列表」。
继续标注其他元素，最后点击「插入 N 条」，将多条标注合并成胶囊插入对话。
对话中的胶囊可展开编辑或删除；如遇胶囊服务缺失，会退回普通文本。

适用场景与注意¶

适合需要「人指出问题 → agent 改代码」的开发场景，尤其是前端团队在讨论 UI、布局、组件交互时。插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。

结语¶

本插件为「人指出问题 → agent 改代码」的链路提供了一个完全自主的壳，后续功能可按需要扩展。目录页与源码见：

https://www.skillhub.cn/plugins/zengxiaolou/dsh-annotate-browser
https://github.com/zengxiaolou/dsh-annotate-browser