前言¶
在 DSH 里让模型改「网页上这一块」，通常要同时解决两件事：页面能看见，且能精确指向是哪个元素或区域。侧栏自带浏览器若直接嵌远程 URL，常被 X-Frame-Options 或 CSP 的 frame-ancestors 挡住；即便能显示，跨源也无法稳定读取 DOM，对话里往往只能贴截图或口头描述，模型还要猜布局。
dsh-annotated-browser 面向上述场景：在宿主机用 headless Chromium 渲染页面，再从 DSH 同源代理出 HTML，使侧栏与页面同源，从而点击元素或框选区域，把选择器、可见文本、矩形与备注一并送入会话。
这是什么¶
- 名称：
dsh-annotated-browser（DeepSeek Harness 客户端插件） - 维护者：KirinKylin-1
- 分类：客户端（
platform: web，注入右侧栏与会话相关 UI） - 许可证：MIT
插件在 DSH 侧栏浏览器中提供标注能力：通过同源主机代理渲染页面后，点击元素或拖拽区域，将备注写入对话。模型收到的是选择器、可见文本与矩形信息，而非需要猜测含义的截图。
核心功能¶
同源代理，提高可嵌入与可标注性¶
部分站点禁止被 iframe 直接加载远程地址。本插件不在侧栏里直连远端 URL，而是在宿主机用 headless Chromium 执行页面，再把结果从 DSH 源站提供，从而避开典型的嵌入限制，页面更易正常显示。
渲染结果与 DSH 面板同源后，才能满足 DOM 标注前提，支持：
- 点击元素并生成 选择器（
#id、data-testid，或沿祖先链行走的 CSS 路径）； - 拖拽区域时收集 区域内所有元素，而不只是最外层节点；
- 一并记录可见文本、元素位置与备注；
- 连续选取，最终按选取顺序 合并为一条消息 发送。
与现有浏览器标签的协作方式¶
配置项 takeover 默认为 true 时，插件直接提供 browser 标签类型，打开的页面默认可标注。设为 false 时不替换原有 browser 标签：快捷键、在系统浏览器中打开、历史记录及其他依赖 browser 的插件行为保持不变，并额外提供标注标签与标签条上的切换入口。
整页评审少占轮次¶
添加备注后仍留在选取模式，可按 Esc 结束。备注会进入列表，通过「发送到对话」一次性发出，整页走查不必每条备注占一轮。
已是同源时的直连¶
若页面本就由当前 DSH 提供（例如另一插件的页面），则直接 iframe 加载，保留 cookie，不再多跑一遍 Chromium。
无法标注时的明确降级¶
仅在本机可达的地址（例如映射到本地的端口）等情况下，面板可回退为 直接加载（只读）：页面仍可见，并明确提示无法标注，而不是空白 iframe。
界面语言¶
面板跟随 GUI 语言（Settings → General），可随设置切换；内置英文与中文，字符串集中在 i18n.js。
安装与启用¶
官方推荐从 GitHub Releases 安装预构建包（README 记载在干净 profile 上验证约 9.4 s，包约 273 KB）：
dsh plugin --profile web add https://github.com/KirinKylin-1/dsh-annotated-browser/releases/download/v1.2.2/dsh-annotated-browser-1.2.2.tgz
安装后需 重启一次 dsh web（宿主机侧需加载），并刷新 GUI。
另有两种 README 记载的替代方式（按需选用）：
# 直接从 git（下载更大，从源码运行）
dsh plugin --profile web add github:KirinKylin-1/dsh-annotated-browser
# 自 npm 发布后即可（README 中称「once published」）
dsh plugin --profile web add dsh-annotated-browser
环境要求（来自 package.json 与 README）：
- Node
>=22 - DSH
>=0.2.1-rc.1 <0.3.0 - 宿主机需有基于 Chromium 的浏览器（Chrome、Chromium 或 Edge）；自动探测常见路径，或通过
CHROME_PATH/PUPPETEER_EXECUTABLE_PATH指定。探测失败时可在 profile 补丁中写明路径：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-annotated-browser
config:
browserExecutable: /usr/bin/google-chrome
配置项¶
| 字段 | 默认值 | 含义 |
|---|---|---|
browserExecutable |
自动探测 | Chrome/Chromium 可执行文件绝对路径 |
proxyServer |
空 | 渲染页面时使用的 HTTP 代理，例如 http://127.0.0.1:7890 |
timeoutMs |
30000 |
页面加载超时（毫秒） |
allowRemote |
false |
是否接受非环回地址的代理请求（仅当 DSH 直接暴露在局域网时考虑） |
takeover |
true |
是否接管 browser 标签类型；false 保留原版浏览器并增加标注入口 |
典型用法¶
README 记载的操作顺序如下：
- 右侧栏 → Browser → 输入 URL。
- 工具栏 → Annotate（按 Esc 可退出标注模式）：单击元素，或按住拖拽框选区域。
- 填写备注 → Add to list；添加后自动继续选取。
- Send to conversation 将所有备注按添加顺序作为 一条消息 发到当前会话。
备注列表在刷新后仍保留：按 Session 存在 localStorage 中，直到清空或发送。
适用场景与注意¶
适合：需要在真实页面布局上与模型对齐修改意见的前端或 UI 相关工作流；需要把「改这里」落实为可机器读取的选择器与文本，而不是截图猜测的场景。
局限（README「Limits」）：
- 页面由 headless Chromium 渲染后回源提供；登录态、重度交互应用可能与日常浏览器表现不一致。
- 代理页面视为「较可信」内容，只浏览你本会在 GUI 中打开的站点。
- 不会共享你本机浏览器里的 cookie。
安全与权限：插件以当前 dsh 进程权限在宿主机启动 Chromium 并代理请求。安装前宜阅读源码与 MIT 许可证，确认可接受其网络与本地浏览器调用行为。社区目录 skillhub.cn 为独立收录站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」的扩展方式。
结尾¶
dsh-annotated-browser 把「看见页面」和「指名部位」合成侧栏里的标注流程，并以结构化信息进入对话，适合整页走查类任务。进一步了解可访问社区目录页与项目仓库：
- 目录页：https://www.skillhub.cn/plugins/KirinKylin-1/dsh-annotated-browser
- GitHub：https://github.com/KirinKylin-1/dsh-annotated-browser
