README
dsh-browser-bridge
DSH 0.2.1-rc.2 开发与验证
本次 0.1.1 适配要求 DSH 0.2.1-rc.2;尚未发布 npm。运行包与开发工作区分开。
开发验证直接使用同版已安装的官方 npm SDK,客户端引擎测试另需官方源码 tag
dsh-v0.2.1-rc.2(commit 687f282e8625c6b8d11ff58211a90524be2e4317)。
setup 校验版本、生成忽略的本机路径映射,不修改上游源码。Node 与 pnpm 版本见 package.json。
# runtime-prefix 下须有 node_modules/@deepseek-ai/dsh@0.2.1-rc.2。
# 另外需要同版 client-store、client-ui-slots、client-ui-primitives,
# 以及 client-store 使用的 zustand@5 / immer@10;若另装到一个 prefix,作为第三个参数传入。
node scripts/setup-dsh.mjs /path/to/runtime-prefix /path/to/deepseek-harness-at-tag /path/to/extra-sdk-prefix
pnpm install --frozen-lockfile
pnpm check
不需要第三个 SDK prefix 时可省略。SDK 使用外部已有安装,仓库不复制核心实现; 三个输入目录可以放在任意持久位置,提交的默认配置不依赖临时目录或个人绝对路径。
效果展示

在完整 DSH Web 对话中通过 @当前标签页 附加左侧开发页面,DSH 可以沿用已有的代码上下文继续观察、操作和验证页面。
核心特色
- 侧边栏里就是 DSH Web 本身,不是另一个聊天客户端。 你在侧边栏看到的正是平时使用的完整 DSH Web,可以打开原有开发对话并延续其上下文;bridge 无需再实现和维护一套独立的对话界面。
- 延续原来的开发对话,而不是另起炉灶。 不用开新对话,也不必把问题重新描述一遍——在正在进行的开发对话中,通过
@当前标签页按钮(或@引用源browser-tabs)把当前页面显式授权给这一条 prompt,DSH 就能在同一个上下文里继续检查、交互、定位问题、修改代码并验证。 - 页面按 prompt 显式授权。 授权只对当前这一条 prompt 生效:turn 结束、取消或从队列移除、标签页关闭、桥接断开时自动失效,下一条 prompt 必须重新附加。弹窗、新开的标签页、发送后切换的活动标签页都不会被隐式授权。
- 结构化、有据可查的浏览器证据。 不是把整个浏览器交给模型,而是通过一组稳定的结构化工具返回证据:DOM 状态、计算样式、几何信息、精确 URL、console 错误、失败的网络请求,以及截图。
- 权限按需且临时的。 CDP 会话在第一次工具调用时才懒附加,turn 结束时自动断开;没有任何访问会隐式延续到未来的 prompt。
一个典型的开发闭环
这是本项目的首要使用场景——开发反馈回路:
- DSH 修改源码。 在开发对话中让 DSH 用现有的文件与 Shell 工具改代码,例如调整样式或修复逻辑。
- HMR 更新页面。 开发服务器热更新已经开在 Chrome 里的页面,浏览器立即呈现新版本。
@当前标签页授权。 在同一个对话的输入框上方点击@当前标签页,把正在显示的页面授权给当前 prompt,然后发送。- 同一对话中观察、操作、诊断。 DSH 读取真实页面的 DOM、计算样式与几何信息,必要时点击、输入、滚动,并查看 console 错误和失败请求来定位问题。
- 继续改代码并复验。 根据浏览器证据再次修改源码,HMR 又一次刷新页面,DSH 继续观察验证,直到结果符合要求。
整个过程中只有一个对话:上下文不丢失,页面只是被显式授权的“证据与操作对象”。例如可以直接接着刚才的开发过程说:
刚才改的按钮 hover 还是不对。
@当前标签页请在当前页面悬停检查;如果有问题,继续修改源码并复验。
同样的原语也适用于问题复现、信息提取、表单操作等轻量浏览器自动化场景——它不只是一个验收工具,也不是全局的 Computer Use。
工作方式(架构)
Chrome side panel
└─ embedded DSH Web (iframe)
└─ DSH client plugin
├─ @ tab references and shortcut
└─ origin-checked postMessage
↕
Chrome extension service worker
├─ prompt grant vault
├─ CDP session manager (chrome.debugger)
└─ authenticated WebSocket
↕
DSH host plugin (pairing, grants, tools)
↕
DSH agent runtime
三个组成部分共享同一个与传输无关的协议包(packages/protocol):
extension/—— Manifest V3 侧边栏扩展(React + shadcn 壳),负责标签页发现、prompt 授权(grant)与chrome.debugger会话;它不实现聊天界面。packages/dsh-plugin/—— 一个可安装的外部 DSH 插件,包含客户端一半(composer 集成)与宿主一半(配对、授权、工具)。packages/protocol/—— 双方共享的带版本号线上协议 schema(配对、授权、桥接请求、工具结果、错误、版本协商)。
把标签页授权给 prompt
- 输入框上方的
@当前标签页按钮一键附加当前 Chrome 标签页到 prompt。按钮通过 DSH 官方conversation.input.dockslot(注册序 30)显示在输入框正上方:排在 Todo(0)、Goal(10)、Queue(20) 等输入 dock 条目之后、最靠近输入框,左边缘与输入卡片对齐、垂直间距 6px;空白首页(hero)下宿主间距为 12px,由插件 CSS 补偿为同样的 6px,因此空白首页与已有对话中位置一致。 @引用源(browser-tabs)列出可附加的标签页,可以一次附加多个;每个附加页面获得稳定别名(如page_1、page_2),并在 prompt 中附带净化后的标题/URL 元数据。- 授权是按 prompt 生效的:turn 的 durable
turn/end(包括完成、错误、取消与 dispose)、引用标签页关闭或终态桥接断开都会立即撤销。Chrome 扩展授权另有 10 分钟滑动空闲超时:新的、已通过校验的浏览器工具调用在执行期间不计 idle,最后一个调用结束后重新开始 10 分钟倒计时,但整条 prompt 最长不超过 6 小时。相同 request 的并发、失败或延迟重传只重放原结果,不执行、不续租;短暂断线期间产生的撤销会在同一 logical session 重连时优先送达。下一条 prompt 仍需重新附加。 - 弹窗或新打开的标签页永远不会被隐式授权;发送消息后切换活动标签页也不会把授权重定向到新页面。
浏览器工具
当一个 prompt 拥有至少一个有效授权时,以下工具仅在该 turn 内存在:browser_observe、browser_inspect、browser_screenshot、browser_act、browser_navigate、browser_wait、browser_console、browser_network。Host 在 DSH claim 消息后、组装首个模型请求前只读校验 marker 并暴露工具 schema;真正的页面访问权仍要到 agent/pre-step 原子消费 grant 后才激活。这样首个请求就能看到浏览器工具;被拦截、删去 marker 或校验失败的 step 会被拒绝并撤销本次 pending grant,不能借“提前注册”获得页面权限或跨 turn 重放。
| 工具 | 作用 |
|---|---|
browser_observe |
返回页面身份、生命周期状态、语义化 DOM/无障碍内容,以及短生命周期的元素引用;默认不含整段文本(text: true 显式请求),过滤 InlineTextBox 与重复 StaticText |
browser_inspect |
查询指定元素(引用/选择器/批量 targets)的表单状态(value/checked/selected 等)、属性、文本、几何与可见性;计算样式仅在显式请求 properties 时返回;密码/secret 字段不泄漏明文 |
browser_screenshot |
截取当前视口或指定元素,并返回图片附件证据;仅当前模型明确支持图片输入时执行 |
browser_act |
点击、输入(type 追加/replace: true 覆盖)、fill(原生 setter 可靠覆盖 input/textarea/select/datetime-local)、选择、悬停、聚焦、按键、滚动;可用 actions 批量顺序执行并附带 expect 后置条件 |
browser_navigate |
打开 HTTP(S) 地址、后退/前进、刷新 |
browser_wait |
等待元素、文本、URL、生命周期状态,或一段有界的页面稳定窗口 |
browser_console |
返回标签页被附加以来观察到的 console 错误与相关日志 |
browser_network |
返回标签页被附加以来失败的请求与加载错误(不含请求头与请求体) |
browser_screenshot 会在访问浏览器前检查当前 DSH provider/model 的图片输入能力。DeepSeek chat-completions 等纯文本模型会收到可恢复的文本工具错误,并可继续改用 browser_observe / browser_inspect;截图不会写入会话历史,也不会导致后续轮次持续失败。
元素引用是短生命周期的:页面导航会使全部引用失效,DOM 替换可能使个别引用失效,工具此时返回 stale_element 而不是猜测其他目标。
console 与 network 证据有界:从 debugger 附加时开始记录,随授权一起删除;任何情况下都不会返回请求头、请求体、cookie 或密码值。
权限与安全边界
debugger—— CDP 会话:首次工具调用时懒附加,授权结束时断开。打开 DevTools 会分离会话,并返回可恢复的debugger_detached错误。tabs—— 仅用于读取标签页标题/URL 供@引用使用,不记录任何常驻浏览历史。storage—— 本地设置,以及chrome.storage.session中用于 service worker 启动对账的非机密归属台账。- 只有 HTTP(S) 标签页可附加。
- 首个版本支持本地 DSH Web 来源(
localhost、127.0.0.1)与 Chrome 118+。 - 原始 CDP 透传默认关闭;不支持无痕窗口标签页;默认无遥测;任何访问都不会隐式延续到后续 prompt。
- 如果 DSH Web 无法被嵌入侧边栏,面板会显示可操作的嵌入诊断。
- 意外的跨域跳转会暂停进一步的写入(
navigation_requires_confirmation),读取仍然可用,直到新的 prompt 显式附加新页面。 - 附加的页面内容只作为外部证据注入模型,并被明确标注为证据而非指令。
通过 npm 安装
npm 上已发布的 @ycp424c/dsh-browser-bridge@0.1.0 属于旧版 DSH;以下命令仅供旧版使用。DSH 0.2.1-rc.2 请使用本仓库 0.1.1 源码构建,尚未发布新版 npm:
# 1. 安装依赖(等价于在 profile 目录执行 pnpm add)
dsh plugin add --profile web @ycp424c/dsh-browser-bridge
# 2. 挂载插件:把包名追加到 ~/.dsh/profiles/web/package.json 的 bundles
# "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@ycp424c/dsh-browser-bridge"] } }
# 3. 重启
dsh web
更多「网页与浏览器」插件
anysearch-dsh
作者 anysearch-team
为 DeepSeek Harness 提供的 AnySearch 网页搜索提供方与高级搜索工具。
dsh-find-plugin
作者 awesome-dsh-plugin
Find DSH plugins inside the agent — live GitHub dsh-plugin topic search, star-ranked / 会话内搜索发现 DSH 插件
fnos-dsh
作者 fnosp
DeepSeek Harness应用与harness插件 monorepo
modsearch
作者 liustack
🥇 The strongest free web search plugin for DeepSeek Harness, and the search bridge for every model without native web access. Free, no signup, no API key. Ask the web or X, get structured JSON evidence. | 🥇 全网最强的 DeepSeek Harness 免费联网搜索插件,免费免注册免 API key。为不能联网的模型补上搜索,问网页或 X,拿回结构化 JSON 证据(搜索、抓取、引用)。
