在 dsh web 配置中挂载 token 认证的 WebSocket 桥，让 Chrome 扩展读取并操作用户真实浏览器内的页面，保留登录态。
ⓘ 此插件是大仓库 Lum1104/dsh-browser 的子包，星数与活跃度统计的是整个仓库。
- 语言
- TypeScript
- License
- MIT
- 分支
- main
安装
$ dsh plugin --profile web add github:Lum1104/dsh-browser/packages/browser/bridge-browser在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
对话式安装
帮我安装 DeepSeek Harness 插件 Lum1104/dsh-browser/packages/browser/bridge-browser：先查看仓库 https://github.com/Lum1104/dsh-browser.git 确认安全性，然后执行安装命令并验证插件加载成功。
把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。
一句话定位
这个插件是 dsh web profile 的浏览器操作桥：在宿主 webserver 上挂载一个 token 认证的 WebSocket 通道，让 Chrome 扩展连进来读取并操作你正在浏览的页面，登录态与会话全程保留。
核心能力
- 读取当前标签页的结构化文本快照（标题、URL、正文、编号交互清单与脱敏表单字段）
- 按编号点击元素、在输入框里追加或替换文本、发送键盘按键（Enter/Tab/Escape/方向键等）
- 上下滚动视口、跳到顶部或底部、按像素滚动
- 在当前标签页内导航到任意 HTTP(S) 地址，以及前进、后退、刷新
- 读取页面任意区域或选择器对应的纯文本
- 等待页面加载与 DOM 变化稳定，可附加额外延迟
技术实现
- 语言: TypeScript
- 关键依赖:
@deepseek-ai/schemastery（配置 schema）、ws（WebSocket 服务端）、@deepseek-ai/dsh-tools（工具注册）、@deepseek-ai/dsh-host-webserver（挂载升级路由） - 架构模式: Cordis 插件，通过
dsh.bundle.patch注入 dsh 的webprofile；插件在webServer上注册/ext/bridgeWebSocket 升级路由与/ext/bridge-configHTTP 端点，并通过ctx.apiProxy.events.mux按连接泵送会话事件；browser_*工具在ctx.tools上注册，每次执行都通过 WebSocket 向扩展派发tool.call帧 - 入口文件:
packages/browser/bridge-browser/src/index.ts
适用场景
适合在 dsh 里直接操作已经登录的网页（比如后台管理系统、SaaS 控制台、需要保留 Cookie 的多步流程）。DSH 模型没有视觉能力，本插件提供一套纯文本的"读页面 + 按编号点击/填表"工具链，让模型在用户自己的 Chrome 里完成任务，而不是开一个无头浏览器。日常隐私敏感用户也能用它做表单填写、内容提取与跨页跳转。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | ^0.1.0-rc.6 | 通过 peerDependencies 锁定 dsh-* 系列包；根工作区实际固定在 0.1.0-rc.8 |
| Node.js | ^22.19 或 >=24 | 仓库根 README 强制要求 |
| 包管理器 | pnpm 11.x | 仓库使用 pnpm workspace，lockfile 在根目录 |
| 浏览器 | Google Chrome | 需配合 Chrome MV3 扩展一起安装，扩展从 ~/.dsh/browser-extension 加载 |
| 平台 | 跨平台 | 不限定操作系统，但需要本地有 Chrome 与上述 Node 版本 |
本插件未声明额外的原生模块依赖。
安装方式
dsh plugin --profile web add github:Lum1104/dsh-browser/packages/browser/bridge-browser
完整安装（含 Chrome 扩展构建与加载）请使用仓库自带的安装脚本：
curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash。本命令单独执行只注册桥插件，扩展需另行构建并加载到 Chrome。
配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
token | 字符串 | 固定 bearer token，用于 WebSocket 握手；缺省时首次启动自动生成并写入 ~/.dsh/ext-bridge-token（权限 0600），启动日志同步打印 | 自动生成 |
toolTimeoutMs | 数字 | 单次工具调用的最长等待时间（毫秒），给扩展 60 秒审批窗口预留时间 | 90000 |
snapshotMaxChars | 数字 | 单次页面快照最多允许的字符数，同时通过 hello 协商下发给扩展 | 32000（最低 500） |
maxInteractiveItems | 数字 | 单次快照里编号交互元素的最大条数 | 60 |
sessionWorkspacePath | 字符串 | 扩展创建的会话所归属的工作区目录，GUI 会把它单独分组 | ~/.dsh/browser-sessions（设为空串则不分组） |
deferSessionCreate | 布尔 | 打开侧边栏但不发消息时，是否跳过真正的会话创建 | true |
环境变量 DSH_EXT_TOKEN 可用来注入 token，DSH_BROWSER_SESSION_WORKSPACE 可用来覆盖会话工作区路径（与上述字段同名，等价）。
常见问题
Q: 为什么安装后侧边栏一直显示「未连接」？
A: dsh plugin 命令只把桥 bundle 注册到本机的 web profile；如果安装前 dsh 已经在运行，它不会自动加载新插件。把当前 dsh 进程停掉，重新执行 pnpm start 或 npx @deepseek-ai/dsh web，扩展会自动通过 /ext/bridge-config 探测桥地址并重连，不需要重新配置。
Q: 需要手动复制粘贴 Token 吗？
A: 本机（127.0.0.1）回环连接不需要 Token，扩展直接通过 /ext/bridge-config 拿到 WebSocket 地址并连上去。只有当你用 --host 0.0.0.0 让 dsh 监听非回环地址时，才需要在侧边栏设置里填 Token。
Q: 哪些网页无法被读取和操作？
A: 受保护的浏览器内置页（如 chrome://、chrome-extension://、Chrome Web Store）无法注入内容脚本，因此本插件不支持；只有普通的 http:// 或 https:// 页面可用。已打开的页面不需要刷新，扩展会在第一次操作时自动注入脚本。
Q: 密码或银行卡号会不会发给模型？
A: 不会。页面快照在渲染时把敏感字段（type=password 与支付卡号）一律显示为 ••••，值不离开页面；表单填写结果只回送脱敏后的纯文本。
Q: 切换标签页会不会被模型跟着切？
A: 不会。助手开始工作时会把上下文绑定到当前活动标签页；用户手动切走后会暂停后续浏览器操作，由侧边栏询问是「继续原页面」还是「跟随新页面」。选择原页面允许后台操作，但绝不会改你正在看的标签页。
Q: 和 dsh 官方的浏览器能力是什么关系？
A: 这就是 dsh web profile 的浏览器能力实现：插件注册 browser_* 工具集 + WebSocket 通道，模型按编号寻址在用户自己的 Chrome 里执行动作，所有登录态与会话全程保留。
Q: 怎么卸载？
A: dsh 侧执行 dsh plugin --profile web remove @yuxianglin/dsh-bridge-browser 移除桥插件；Chrome 侧到 chrome://extensions 找到「dsh 浏览器助手」点「移除」即可。本机副本在 ~/.dsh/dsh-browser（托管安装）与 ~/.dsh/browser-extension（扩展目录），可按需清理。
上手难度
入门 — 用户基本无需手动配置：装上桥 + Chrome 扩展后打开侧边栏就能用；要调试或自定义 Token、超时、快照上限时再回头看配置项即可。
已知问题与限制
- 同时只允许一个扩展连接；新打开的窗口会顶替旧的，旧窗口里的待处理工具调用会以
bridge-closed失败结算 - 受保护或已销毁的跨源 iframe 在快照里会被标为「不可用」，不会让整页快照失败
- Token 没有自动过期机制，需要手动改
~/.dsh/ext-bridge-token或在配置里改token才能轮换 /ext/bridge-config仅返回ws://127.0.0.1地址；非回环部署需要在侧边栏设置里手工填地址与 Token- 仓库自带的 Playwright e2e 在缺少可用 Chromium 或未构建扩展时会自动跳过，不影响桥本身工作
- 审批逻辑强制在扩展 service worker 里执行，不依赖模型自觉；DSH 工具管线尚未把同一策略开放给其它客户端
English | 中文
Connect DeepSeek Harness to the Chrome tab you are already using. The model can read page content, click controls, fill forms, scroll, and navigate while preserving your login state, session, and cookies. A side panel provides the conversation UI.
dsh is DeepSeek AI's open-source, plugin-based agent harness. This repository provides a companion browser bridge plugin and Chrome MV3 extension as one standalone pnpm workspace.
The integration is text-only: pages become structured text with a numbered inventory of interactive elements, and the model addresses those elements by number. Screenshots never enter the model-facing pipeline.
Quick install
The standard dsh plugin command alone cannot install this project. The integration contains both a dsh bridge plugin and a Chrome MV3 extension, and the extension must also be built and installed in Chrome. Use the repository's one-line installer to set up both parts:
curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash
When the installer opens chrome://extensions, follow its instructions to load or reload dsh Browser Assistant. If dsh is already running, restart it after installation. See Detailed installation and usage for prerequisites, startup commands, updates, and developer installation.
[!IMPORTANT] The unscoped
dsh-browserpackage on npm belongs to a different project and is not affiliated with this repository. This project is not currently published as an npm package; use the installer above.
Performance
In a paired 60-run end-to-end benchmark on August 18, 2026, both backends completed all 30 assigned runs successfully, while dsh Browser Control required fewer model/tool round trips and finished faster:
| Backend | Success | Mean end-to-end latency | Mean browser tool calls |
|---|---|---|---|
| dsh Browser Control | 30/30 | 5.32 s | 3.4 |
| Matched Playwright baseline | 30/30 | 6.67 s | 4.7 |
The paired Playwright / extension duration ratio was 1.24 (95% CI 1.16–1.34): Playwright took about 24% longer, or equivalently, dsh Browser Control reduced latency by about 20% and saved 1.35 seconds per task on average. The suite used six browser tasks, five deterministic seeds, the same DSH profile and model (deepseek-v4-flash), and independently validated page state. See the benchmark methodology and reproduction guide.
Core capabilities
| Capability | Tool | Notes |
|---|---|---|
| Read page | browser_snapshot | Structured text snapshot: title, URL, main text, numbered controls, and masked form fields; delta: true returns only changes |
| Click element | browser_click | Click links, buttons, checkboxes, and other controls by inventory number |
| Fill forms | browser_type | React/Vue-compatible input; replace clears the field first |
| Press keys | browser_press | Keyboard events such as Enter, Tab, Escape, and arrow keys |
| Scroll | browser_scroll | Viewport scrolling: up, down, top, and bottom |
| Navigate | browser_navigate / browser_back / browser_forward / browser_reload | Navigation inside the controlled tab, with login state preserved |
| Read region | browser_get_text | Lazy-loaded or partial page text |
| Wait for stability | browser_wait | Page-load and render-settle detection |
Repository layout
packages/browser/bridge-browser/
cordis.patch.yml
extensions/dsh-browser/
scripts/install.sh
Why this design
- Your real browser, not a headless copy: the model works in the page you already have open, retaining logins, sessions, and cookies.
- A text-first model interface: numbered controls, stable IDs across snapshots, delta updates, and masked sensitive values make pages operable without vision.
- A narrow privacy boundary: passwords and payment-card values are always rendered as
••••and never leave the page. - A guarded bridge: authenticated handshakes protect remote connections, privileged gateway methods reject non-loopback callers, and the extension binds tools to one user-controlled tab.
Detailed installation and usage
Requirements: Node.js ^22.19 or >=24, Corepack/pnpm, and Google Chrome.
Install or update
For a managed installation, run:
curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash
The installer downloads main, builds and registers the bridge plugin, builds the Chrome extension into ~/.dsh/browser-extension, and opens chrome://extensions. On the first install, load that directory as an unpacked extension; on updates, click Reload. Restart dsh if it is already running.
To install the current branch from a source checkout instead:
git clone https://github.com/Lum1104/dsh-browser.git
cd dsh-browser
./scripts/install.sh
After pulling or switching revisions, rerun ./scripts/install.sh and reload the extension.
Start and use
Start the managed installation with:
cd ~/.dsh/dsh-browser && pnpm start
From a source checkout, run pnpm start in the repository root. To use the latest public dsh release instead:
npx @deepseek-ai/dsh web
Local use requires no configuration. Open an http:// or https:// page, click the DeepSeek whale icon, and wait for Connected. Existing tabs are instrumented on the first action; protected pages such as chrome:// and the Chrome Web Store are not supported.
Troubleshooting
Side panel stays "Not connected"
- Make sure dsh web is running locally (default
http://127.0.0.1:3080). - Verify the bridge is loaded: open
http://127.0.0.1:3080/ext/bridge-config. It should return JSON such as{"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}. If it returns a web page instead of JSON, the running dsh predates the bridge registration — restart dsh and refresh the page; the extension reconnects on its own. - The extension probes ports 3080, 3081, and 3090 automatically. If dsh runs on another port — or you use a remote
--host 0.0.0.0deployment — set the address (and bridge token) in the side panel settings.
Development
The bridge plugin and Chrome extension are both members of this repository's workspace. Run all commands from the repository root. For the first development installation, run pnpm install.
pnpm run build
pnpm run typecheck
pnpm run test
pnpm --filter @yuxianglin/dsh-bridge-browser run build
pnpm --filter @yuxianglin/dsh-bridge-browser run typecheck
pnpm --filter @yuxianglin/dsh-bridge-browser run test
pnpm --filter dsh-browser-extension run build
pnpm --filter dsh-browser-extension run test
Notes:
- The bridge plugin must have a built
lib/before startup because the loader consumes it; bothscripts/install.shand the rootpnpm run buildbuild the plugin before the extension. - The dependencies of
@deepseek-ai/dshand the bridge plugin are pinned to the same tested public release line. An upgrade must update the manifests and lockfile together and rerun the root checks.
Security
- The bridge path sits outside the
/apitrust boundary and performs its own bearer-token authentication. - Privileged gateway methods such as
settings.*,credentials.*, andhost.open*reject non-loopback sources. - The model-facing pipeline is text-only; passwords and payment-card values never leave the page.
- When work begins, the assistant binds to the active tab (at prompt submission, or at the first direct browser-tool call). If you switch tabs manually, later browser actions pause and the side panel asks whether the assistant should continue on the original tab or follow the new one. Choosing the original tab permits background operation; the extension never silently retargets or changes your visible tab. Closing the controlled tab also pauses tools until you explicitly select the current page.
- Page-authored text is wrapped as untrusted input. The default
automode reads only the controlled tab without an extra prompt; privacy-sensitive users can selectaskfor per-read confirmation oroffto block reads entirely. Inaskmode, the read dialog can allow one read or persistently switch back toauto; this can be reversed in Settings. Read page text is sent to the selected model. - Click, type, keypress, navigation, history, and reload calls fail closed until the user approves them. An origin may be trusted for the current side-panel session (cleared when the last panel closes or the service worker restarts), while permanent trust is managed explicitly in Settings. Explicit cross-origin
browser_navigatecalls and unknown history destinations always prompt again.
收录徽章
[](https://deepseek-plugin.org/plugins/Lum1104/dsh-browser/packages/browser/bridge-browser)把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。