浏览器标注 iimaguest/dsh-browser-annotate

DSH Desktop —— 浏览器和它的标注，就在你的智能体旁边

两块东西在 loopback 上碰头：

| 部分 | 是什么 |
| 本仓库根目录 | DSH 插件（dsh-browser-annotate）：智能体的十二个浏览器工具，一条 dsh plugin 命令就能安装。它通过 http://127.0.0.1:7391 跟应用通信 —— 不共享任何服务，除了插件本身，什么都不会加载进 DSH。 |
| desktop/ | 一个 Electron 应用。左窗格：你的 DSH Web UI，由你启动，独占一个标签页。右窗格：真正的 Chromium，标签页数量随意。 |

左窗格里的 DSH 是你自己的：你在终端里跑它（dsh web --port 3090），复制它打印出来的带 token 的 URL，粘贴进应用。应用从不启动 DSH，也不拥有 DSH。

运行

./dev.sh 'http://127.0.0.1:3090/?token=…' # first start, or to change the conversation URL ./dev.sh # every later start; the URL persists in .dev-url

dev.sh 只杀掉本应用的 Electron（其他 Electron 应用和你的 dsh web 都不动），启动应用，等标注桥接就绪，然后打印日志路径（/tmp/dsh-desktop.log）。

想构建 macOS 磁盘映像，而不是从源码运行：

cd desktop && npm install && npm run dist # unsigned DSH-<version>-arm64.dmg in desktop/dist/

DMG 未签名：首次启动需要 右键 → 打开（或者系统设置 → 隐私与安全性 → 仍要打开），之后就能正常打开。

窗口

- 左窗格 —— 一个标签页，就是对话。它受保护：任何东西都无法把它从 DSH 导航走，因为对话一旦离开自己的 URL，就等于丢了。
- 右窗格 —— 标签页想开多少开多少。地址栏接受任何 URL。⌘T 新建标签页，⌘W 关闭，⌘L 地址栏，⌘R 重新加载，⌘[/⌘] 后退/前进 —— 在指针所在的窗格里生效。
- 应用始终为自己开一个 Chrome DevTools Protocol 端口；它发布在 GET /health 的 debugPort 里，插件的 Playwright 就是这样找到它的。

标注

应用存在的意义就是这个手势：

- 快速 —— 右键点任何东西 → Add comment to this element。评论框会锚定到该元素打开；输入，按 Enter。元素在右键那一刻就被记录下来了，所以那些抢自己事件的页面照样能标注。
- 检查 —— 右键 → Inspect this element。悬停时用 DevTools 风格的面板遍历 DOM（选择器、尺寸、位置、计算样式）；↑/↓ 走到父节点/首个子节点，选中项跟着移动；Enter 标注选中的节点。

每条标注都带着评论，外加精确的前端事实：CSS 选择器、DOM 路径、标签、role、无障碍名称、边界矩形、计算样式、元素 HTML、页面 URL/标题，以及裁剪到该元素的截图。
标注是排队而不是直接触发：工具栏会显示正在等待的内容，你可以丢弃其中任意一条，而 Add to input 会把整批内容送进会话的输入框——格式化文本，加上每张截图作为真实附件，走的是人类打字和拖入文件时产生的同一套事件。可以先攒任意多条。

智能体通过它的 annotations 工具读取同一个队列：list 会报告队列，并把截图附在结果里；inject 还会把它作为上下文块送进会话；clear 在你已经接手这批内容之后将其移除。

智能体的十二个工具

| 工具 | 作用 |
| openBrowserPage | 在新标签页打开 URL（无法访问主机时拒绝，并给出真实错误） |
| navigatePage | url / reload / back / forward |
| readPage | 某个标签页的无障碍树快照，可选限定到某个选择器 |
| screenshotPage | 视口或元素裁剪，作为图片附件 |
| clickElement / hoverElement / typeInPage | 按 @ref 或选择器操作元素；输入可以提交 |
| dragElement | 通过引擎做真实拖拽，失败时回退到 Playwright 的 dragAndDrop，并报告实际执行的是哪一个 |
| handleDialog | 报告 / 接受 / 关闭 alert/confirm/prompt（应用不再自动应答） |
| runPlaywrightCode | 通过 CDP 对应用的 Chromium 执行真实 Playwright 函数——任何定制需求都走这条正路 |
| cdp | 对任意标签页调用任意 Chrome DevTools Protocol 方法 |
| annotations | 人类标注的反馈，如上所述 |

有两套引擎响应这套词汇：桌面应用（HTTP POST /rpc），以及你从 extension/ 挂载 Chrome 扩展后的那个 Chrome。两者都挂载时，扩展优先。Playwright 只能通过应用使用——扩展不暴露 CDP 端口——runPlaywrightCode 会说明这一点。

Chrome DevTools Protocol

cdp 把任意方法转发给任意标签页（Input、DOM、Runtime、Network、Emulation……）。应用自己的端口就是普通 Chromium 端口，所以常见的客户端库都能用；Electron 没有实现 Target.createTarget 和 Target.createBrowserContext，工具会直接说明，而不是靠猜——要开标签页请用 openBrowserPage。

安装插件

这个插件是 DSH 的普通配置档依赖，本仓库直接从 GitHub 安装——没有 npm 包：

install (or reinstall at the latest commit)
dsh plugin --profile web add github:iimaguest/dsh-browser-annotate

update to the newest pushed commit
dsh plugin --profile web update dsh-browser-annotate

remove — dependency and bundle layer together; the profile's own cordis.patch.yml is never touched
dsh plugin --profile web remove dsh-browser-annotate

每条命令都在 DSH 下次启动时生效。
这条命令装的是什么：一个包，它的 package.json 声明自己是 DSH 插件 —— dsh.bundle.patch 指向 cordis.patch.yml（一行 insert，承载宿主那一半：服务、HTTP 路由、工具），dsh.client.inject 把浏览器侧边栏挂进 web 客户端。host/ 是 DSH 那一半，client/ 是 web 客户端那一半，extension/ 是可选的 Chrome MV3 扩展，可以充当第二个引擎。

如果你想在这个仓库的检出上开发，同一套接线可以指向工作树：把配置档里的 node_modules/dsh-browser-annotate 软链到你的检出（或者 dsh plugin --profile web add <path>），再在仓库里跑 npm run link-peers，万一某次安装把 @deepseek-ai/* 这些 peer 依赖清掉了就重新链上。之后每次 DSH 启动，改动都是即时生效的。

只有一半，没有另一半

两边都不假设对方存在：

- 有插件，没有应用 —— DSH 正常启动、正常工作；十二个工具照常注册，只是回答一句「桌面浏览器没有挂上」（Chrome 扩展那边同理），不会卡住也不会崩。启动应用，下一次调用就能用。
- 有应用，没有插件 —— 应用就是个普通双栏浏览器：标签页、地址栏、标注、队列、投递到会话的输入框。它从不调用 DSH，只在回环地址上应答 HTTP，所以哪怕哪里都没装插件，功能也不会退化。

实测验证过的内容

对着真实应用和真实 DSH 跑的，不是夹具：

- 十二个工具驱动真实页面，包括一次失败的 DNS 查询被 Chromium 自己的错误拒绝、限定范围的 readPage、真正会阻塞的对话框，以及一次靠落点效果验证的拖拽；
- 从可信右键快速标注：记录元素 → 输入框 → 评论 → 带截图、选择器、路径、角色、矩形、样式、HTML 的队列；
- 检查标注：悬停遍历，方向键移动选中项，Enter 给遍历到的节点加标注（是 h1，不是悬停的 p）；
- 两条标注以格式化文本加 blob 图片附件的形式投递进会话输入框，再通过它们真实的 chip 按钮移除；
- annotations 工具对着真实会话里填满的队列：list 把截图附在结果上，inject 投递上下文块，队列保持不变。

局限，直说

- 关闭标签页是给人用的操作（⌘W、标签栏），目前还没有工具动词能关。
- Electron 的 CDP 端点没有实现 Target.createTarget / Target.createBrowserContext。
- Chrome 扩展引擎无法提供 runPlaywrightCode；只有应用可以。