dsh-browser

一句话定位

dsh-browser 把 DeepSeek Harness 接到你正在浏览的 Chrome 标签页：模型用纯文本方式读取页面、点击控件、填写表单、滚动和导航，登录态和 Cookie 一并保留；侧边栏提供对话界面，操作需要你逐次确认。

核心能力

• 读取页面：以结构化文本（含标题、URL、编号交互清单、表单字段）渲染当前标签页，敏感值显示为 ••••
• 点击元素：按编号点击链接、按钮、复选框等控件，兼容 React/Vue 受控组件
• 填写表单：按编号向表单字段输入文本，支持 replace=true 先清空再填写
• 发送按键：合成 Enter、Tab、Escape、方向键、Backspace、Delete 等键盘事件
• 滚动与导航：上下滚动或跳到顶/底；在标签页内打开新 URL、后退、前进、刷新
• 等待稳定：检测页面加载与 DOM 渲染完成，可叠加额外等待时间
• 局部读取：按 CSS 选择器读取局部文本，用于懒加载或部分区域内容

技术实现

• 语言: TypeScript（服务端与扩展均用 TS，扩展侧含 React）
• 关键依赖: ws（WebSocket 桥传输）、@deepseek-ai/dsh-host-apiproxy（DSH 网关 RPC 复用）、@deepseek-ai/schemastery（Config schema）、react + marked + dompurify（侧边栏 UI）
• 架构模式: Cordis 插件 bridge-browser，在 host webserver 上挂载 /ext/bridge WebSocket 升级路由（位于 /api 信任栅栏之外，自带 bearer token 认证）；同名 Chrome MV3 扩展作为客户端，通过 chrome.runtime.connect 把面板消息桥到 WebSocket；扩展 content script 在受控标签页执行 browser_* 工具
• 入口文件: packages/browser/bridge-browser/src/index.ts（桥插件）、extensions/dsh-browser/src/background/index.ts（扩展后台）、extensions/dsh-browser/src/panel/main.tsx（侧边栏入口）

适用场景

适合想把 DeepSeek 模型接入到「真实浏览器」而非无头副本的用户：当目标站点对登录态、Cookie、设备指纹敏感（如后台管理系统、电商后台、社交平台），或者需要保留用户当前打开的多个标签页现场时，模型可以直接在已有页面里继续操作，DSH 的 web profile 也能因此多出一组浏览器工具。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Lum1104/dsh-browser

配置项

本插件通过 cordis.patch.yml 声明 6 个可调字段（位于 packages/browser/bridge-browser/cordis.patch.yml）。除 token 外，其余均有默认值，普通用户无需改动。

另外支持两个环境变量：DSH_EXT_TOKEN（覆盖 token 字段，固定远程部署 Token）和 DSH_BROWSER_SESSION_WORKSPACE（覆盖 sessionWorkspacePath）。

常见问题

Q: 安装后 dsh 已经在跑、侧边栏却显示「未连接」怎么办？

A: 安装器只在 dsh 启动时把桥 bundle 注册进本机的 web profile，已经在跑的进程不会自动加载新插件。把那个 dsh 进程停掉，重新执行 pnpm start（或 npx @deepseek-ai/dsh web）即可，扩展会自动重连，无需重新配置。

Q: 需要复制粘贴 Token 吗？

A: 本机（127.0.0.1）回环连接不需要 Token，扩展通过 /ext/bridge-config 自动探测并连接；只有 --host 0.0.0.0 远程部署时才需要在侧边栏设置里填地址和 Token。Token 无自动轮换能力。

Q: 哪些网页不能被读取和操作？

A: 浏览器内置或受保护页面（如 chrome:// 页面、Chrome Web Store）无法注入内容脚本，因此不支持读取和操作；只有普通 http:// 和 https:// 页面支持。安装前就已打开的页面无需手动刷新，扩展会在第一次操作时自动补注入。

Q: 密码或银行卡号会发给模型吗？

A: 不会。敏感字段（type=password 和支付卡号）在快照里一律显示为 ••••，字段值不离开页面；侧边栏收到的也是脱敏后的纯文本。

Q: 模型操作前会弹窗确认吗？

A: 多数动作默认走「自动共享」不弹窗；点击、输入、按键、导航、刷新、跨域 browser_navigate 会按 origin 弹窗（一次/会话/永久可信任）。隐私敏感用户可以在侧栏设置里把「分享页面内容」切换到「每次询问」或「关闭」。

Q: 怎么排查「侧边栏一直未连接」？

A: 先确认 dsh 在跑（默认 http://127.0.0.1:3080），浏览器访问 http://127.0.0.1:3080/ext/bridge-config，应返回类似 {"wsUrl":"ws://127.0.0.1:3080/ext/bridge"} 的 JSON；返回网页说明当前 dsh 早于桥注册——重启 dsh 并刷新页面。扩展自动探测 3080/3081/3090 端口，若 dsh 跑在别的端口或远程部署，要在侧栏设置里填地址和 Token。

Q: 模型能看到截图吗？

A: 不发截图。整套管线采用纯文本：页面转成结构化文本 + 编号交互清单，模型通过编号精确操作。优点是稳定编号跨快照不变、隐私边界更窄；缺点是验证码、纯图片按钮等没有可访问名的元素，工具结果会标注「存在无文本可访问名的元素」，需要手动完成。

Q: 怎么卸载？

A: 桥插件侧用 dsh plugin --profile web remove @yuxianglin/dsh-bridge-browser；Chrome 侧到 chrome://extensions 找到「dsh 浏览器助手」点「移除」。删除 ~/.dsh/dsh-browser（托管安装）和 ~/.dsh/browser-extension（扩展目录）会把本地副本清空。

上手难度

入门 — 用户只需跑一次安装脚本、加载扩展、点鲸鱼图标即可；DSH 升级或远程部署时才需要碰配置。

已知问题与限制

• 同时只有一个扩展连接：后连的扩展会顶替先连的扩展，先连扩展在飞的工具调用会被 bridge-closed 结算。
• Token 无自动轮换：生成后持久化在 ~/.dsh/ext-bridge-token，不会到期；如需重置需手动删除该文件。
• browser_press 不触发浏览器原生默认行为：合成的 Tab 焦点移动、方向键、Enter 激活等不会触发，仅作框架内键盘事件；依赖原生行为的场景建议手动操作。
• browser_wait 不观察持续 DOM 更新：以加载完成 + 固定静默窗口为准，连续刷新的 SPA 可能被误判为稳定。
• 验证码 / 纯图片按钮无法处理：工具结果会标注「存在无文本可访问名的元素」，需用户手动完成。
• 不能操作受保护页面：chrome://、Chrome Web Store 等浏览器内置或扩展页面无法注入内容脚本。
• 依赖 dsh 同版本线：桥插件把所有 @deepseek-ai/dsh-* 依赖固定在 0.1.0-rc.6；DSH 升级时需同步更新 manifest 与锁文件并重跑根目录测试。
• 标签页绑定粒度到扩展连接：一次扩展连接内共用一个受控标签页，不按对话会话分裂。

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.

The workspace uses a pinned, publicly available @deepseek-ai/dsh release for reproducible installation. It requires neither a DeepSeek Harness source checkout, dependencies from a parent directory, nor npm credentials. DeepSeek Harness is currently a developer preview, so upgrades may require coordinated dependency and API updates.

[!IMPORTANT] The unscoped dsh-browser package 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 installation method below.

Core capabilities

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.

Zero-configuration install and use

Prerequisites: Node.js ^22.19 or >=24, Corepack/pnpm, and Google Chrome. All required @deepseek-ai packages are available from the public npm registry; installation does not require an npm token.

Step 1 — install the bridge and extension. The recommended command does not require Git or a local clone:

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash

The remote installer downloads main into the installer-managed directory ~/.dsh/dsh-browser, then installs the pinned public npm dependencies from the lockfile, builds the bridge plugin, registers its official bundle in dsh's local web profile, builds the extension, copies it to ~/.dsh/browser-extension, and opens chrome://extensions. Enable Developer mode and load the extension directory when prompted. Running the same command again updates the managed installation; keep source edits in a clone instead.

Already running dsh? Restart it after installing. The installer registers the bridge bundle in dsh's local web profile, and dsh loads its profile only at startup. An instance started before the install keeps running without the bridge, so the side panel reports "Not connected" even though the extension loaded correctly. Stop that instance and start it again (Step 2); the extension then discovers the bridge automatically and needs no reconfiguration.

Developers can clone the repository and run the same installer from any checkout. This mode uses the current branch without downloading or overwriting source files:

git clone https://github.com/Lum1104/dsh-browser.git
cd dsh-browser
./scripts/install.sh

Step 2 — start dsh. For a managed installation, use its pinned version:

cd ~/.dsh/dsh-browser && pnpm start

From a clone, run pnpm start in the repository root instead.

Or run the latest public release directly from npm:

npx @deepseek-ai/dsh web

Both commands load the same browser bundle from the local web profile. Port 3080 is used by default; if it is occupied, run pnpm start -- --port <port> or npx @deepseek-ai/dsh web --port <port>. When the DeepSeek whale icon appears in the toolbar, click it to open the side panel.

For subsequent use, the extension does not need to be installed again. Run either startup command above.

No configuration is required for local use: the extension discovers dsh through /ext/bridge-config, and loopback connections do not require a bridge token. This runtime security token is unrelated to npm authentication; an address and bridge token are only needed for remote deployment with --host 0.0.0.0.

Step 3 — use it: open any normal http:// or https:// page and click the DeepSeek whale icon. When the side panel reports "Connected", chat normally or click "Read page" first. A page that was already open before the extension was installed or reloaded is instrumented automatically on the first action; no page refresh is needed. Browser-internal and protected pages such as chrome:// and the Chrome Web Store cannot be read or operated.

To update a managed installation, run the same curl | bash command again. To update a clone, pull or switch to the desired revision and run ./scripts/install.sh. Then click Reload for "dsh Browser Assistant" in chrome://extensions and reopen the side panel. Chrome should load ~/.dsh/browser-extension; do not load the source directory extensions/dsh-browser/. If dsh web is already running, restart it too so it reloads the updated web profile (see Troubleshooting).

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.0 deployment — 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; both scripts/install.sh and the root pnpm run build build the plugin before the extension.
• The dependencies of @deepseek-ai/dsh and 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 /api trust boundary and performs its own bearer-token authentication.
• Privileged gateway methods such as settings.*, credentials.*, and host.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 auto mode reads only the controlled tab without an extra prompt; privacy-sensitive users can select ask for per-read confirmation or off to block reads entirely. In ask mode, the read dialog can allow one read or persistently switch back to auto; 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_navigate calls and unknown history destinations always prompt again.