# dsh-browser

> Use DeepSeek Harness to read and interact with web pages directly through a Chrome extension. Capture plain text snapshots, click elements, fill forms, scroll, and navigate—all while preserving your login session.

## Metadata

- Author: [@Lum1104](https://github.com/Lum1104)
- Repo: <https://github.com/Lum1104/dsh-browser.git>
- GitHub: [Lum1104/dsh-browser](https://github.com/Lum1104/dsh-browser)
- Stars: 347
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `browser-automation`, `chrome-extension`, `coding-agent`, `cordis`, `deepseek`, `deepseek-harness`, `dsh`, `dsh-plugin`
- Forks: 17
- Open Issues: 3
- Last push: 2026-08-19T16:27:55.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

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

## Wiki

## One-Line Description
dsh-browser connects DeepSeek Harness to your active Chrome tab: the model reads the page in plain text, clicks controls, fills forms, scrolls and navigates, while preserving login state and cookies; the sidebar provides a conversation interface, and operations require your confirmation step by step.

## Core Features
- **Read Page**: Renders the current tab as structured text (including title, URL, numbered interaction list, form fields), with sensitive values displayed as `••••`
- **Click Elements**: Click links, buttons, checkboxes and other controls by number, compatible with React/Vue controlled components
- **Fill Forms**: Input text into form fields by number, supports `replace=true` to clear first then fill
- **Send Keystrokes**: Synthesize keyboard events like Enter, Tab, Escape, Arrow keys, Backspace, Delete, etc.
- **Scroll and Navigation**: Scroll up/down or jump to top/bottom; open new URLs within the tab, go back, go forward, refresh
- **Wait for Stability**: Detect page load and DOM rendering completion, with optional additional wait time
- **Partial Reading**: Read local text by CSS selector, useful for lazy-loaded or partial area content

## Technical Implementation
- **Language**: TypeScript (both server and extension use TS, extension side includes React)
- **Key Dependencies**: `ws` (WebSocket bridge transport), `@deepseek-ai/dsh-host-apiproxy` (DSH gateway RPC reuse), `@deepseek-ai/schemastery` (Config schema), `react` + `marked` + `dompurify` (sidebar UI)
- **Architecture Pattern**: Cordis plugin `bridge-browser`, mounts `/ext/bridge` WebSocket upgrade route on the host webserver (located outside `/api` trust fence, with bearer token authentication); same-named Chrome MV3 extension as client, bridges panel messages to WebSocket via `chrome.runtime.connect`; extension content script executes `browser_*` tools in the controlled tab
- **Entry Files**: `packages/browser/bridge-browser/src/index.ts` (bridge plugin), `extensions/dsh-browser/src/background/index.ts` (extension background), `extensions/dsh-browser/src/panel/main.tsx` (sidebar entry)

## Use Cases
Suitable for users who want to integrate DeepSeek model into a "real browser" instead of a headless copy: when the target site is sensitive to login state, cookies, device fingerprints (like admin panels, e-commerce backends, social platforms), or when you need to preserve the current multiple tabs open by the user, the model can continue operating directly in the existing page. DSH's `web` profile thus gains an additional set of browser tools.

## Prerequisites and Compatibility

| Dependency | Minimum Version | Description |
|---|---|---|
| DeepSeek Harness | `0.1.0-rc.6` | Bridge plugin locks `@deepseek-ai/dsh-*` 0.1.0-rc.6 via `peerDependencies`; can only be installed on `dsh web` |
| Node.js | `^22.19` or `>=24` | Root `package.json` doesn't declare `engines`, README specifies this range; installer validates `node` command exists |
| Package Manager | Corepack + pnpm | Installation script and build script (`scripts/install.sh`, root `pnpm run build`) both depend on pnpm |
| Chrome | >= 116 | Extension `minimum_chrome_version: 116` in manifest.json (MV3 + sidebar API requirement) |
| Platform | Cross-platform | Bridge plugin only depends on Node and `ws`, no native modules; extension is Chrome MV3, theoretically cross-platform; install script's `pbcopy` and `open` work best on macOS |
| Native Modules | None | Bridge plugin doesn't introduce native modules; workspace only allows (doesn't force) build scripts from upstream dependencies like `node-pty / koffi / esbuild` |

## Installation

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

## Configuration
This plugin declares 6 adjustable fields via `cordis.patch.yml` (located in `packages/browser/bridge-browser/cordis.patch.yml`). Except for token, all have default values, so regular users don't need to modify them.

| Config | Type | Description | Default |
|---|---|---|---|
| `token` | string | Bearer token for bridge connection; when missing, auto-generated and written to `~/.dsh/ext-bridge-token` (permissions 0600). No token needed for local loopback connections, only needed for remote deployment | Auto-generated |
| `toolTimeoutMs` | integer (ms) | Timeout for single browser tool call, after which the bridge will revoke the instruction sent to the extension | `90000` |
| `snapshotMaxChars` | integer (chars) | Maximum characters for a single page snapshot render; content beyond this is truncated; minimum 500 | `32000` |
| `maxInteractiveItems` | integer | Maximum number of numbered interactive elements in a single snapshot; elements exceeding this are discarded | `60` |
| `sessionWorkspacePath` | path string | Default workspace directory for sessions created by the browser extension; empty string means no grouping | `~/.dsh/browser-sessions` |
| `deferSessionCreate` | boolean | Whether to defer session creation (return temporary ID first, persist to storage on user's first message) | `true` |

Two additional environment variables are supported: `DSH_EXT_TOKEN` (overrides `token` field, for fixed remote deployment token) and `DSH_BROWSER_SESSION_WORKSPACE` (overrides `sessionWorkspacePath`).

## FAQ

**Q: dsh is running after installation, but the sidebar shows "Not Connected" - what should I do?**

A: The installer only registers the bridge bundle with the local `web` profile when dsh starts; already running processes don't automatically load new plugins. Stop that dsh process and re-run `pnpm start` (or `npx @deepseek-ai/dsh web`), the extension will automatically reconnect without needing reconfiguration.

**Q: Do I need to copy-paste the Token?**

A: Local loopback (127.0.0.1) connections don't require a token; the extension auto-detects and connects via `/ext/bridge-config`; only remote deployment with `--host 0.0.0.0` requires filling in address and token in the sidebar settings. Tokens don't auto-rotate.

**Q: Which pages cannot be read or operated on?**

A: Built-in or protected browser pages (like `chrome://` pages, Chrome Web Store) cannot have content scripts injected, so they don't support reading or operating; only normal `http://` and `https://` pages are supported. Pages already open before installation don't need manual refresh; the extension will auto-inject on first operation.

**Q: Will passwords or bank card numbers be sent to the model?**

A: No. Sensitive fields (`type=password` and payment card numbers) are always displayed as `••••` in snapshots, field values don't leave the page; the sidebar also receives desensitized plain text.

**Q: Will there be a popup confirmation before the model operates?**

A: Most actions default to "auto-share" without popup; clicking, input, keystrokes, navigation, refresh, cross-origin `browser_navigate` will popup by origin (once/session/permanent trust). Privacy-sensitive users can switch "Share page content" to "Ask every time" or "Off" in the sidebar settings.

**Q: How to troubleshoot "Sidebar consistently shows not connected"?**

A: First confirm dsh is running (default `http://127.0.0.1:3080`), access `http://127.0.0.1:3080/ext/bridge-config` in browser, should return JSON like `{"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}`; if it returns a webpage, dsh started before the bridge was registered - restart dsh and refresh the page. Extension auto-detects ports 3080/3081/3090; if dsh runs on another port or is deployed remotely, fill in address and token in sidebar settings.

**Q: Can the model see screenshots?**

A: No screenshots are sent. The entire pipeline uses plain text: page is converted to structured text + numbered interaction list, and the model operates precisely via numbers. The advantage is stable numbering that doesn't change across snapshots, narrower privacy boundary; the disadvantage is that captchas, pure image buttons and other elements without accessible names will have the tool result note "elements without text accessible names exist", requiring manual completion.

**Q: How to uninstall?**

A: On the bridge plugin side, use `dsh plugin --profile web remove @yuxianglin/dsh-bridge-browser`; on Chrome side, go to `chrome://extensions`, find "dsh Browser Assistant", click "Remove". Deleting `~/.dsh/dsh-browser` (hosted installation) and `~/.dsh/browser-extension` (extension directory) will clear local copies.

## Learning Curve
Entry Level — users only need to run the installation script once, load the extension, and click the whale icon; configuration only needs to be touched when upgrading DSH or deploying remotely.

## Known Issues and Limitations
- **Only one extension connection at a time**: Later-connected extensions will replace earlier ones, and in-flight tool calls from the earlier extension will be settled with `bridge-closed`.
- **Token doesn't auto-rotate**: After generation, it's persisted in `~/.dsh/ext-bridge-token` and doesn't expire; if reset is needed, manually delete that file.
- **`browser_press` doesn't trigger browser native default behaviors**: Synthesized Tab focus movement, arrow keys, Enter activation, etc. don't trigger, only serve as in-framework keyboard events; for scenarios depending on native behavior, manual operation is recommended.
- **`browser_wait` doesn't observe continuous DOM updates**: Based on load completion + fixed silent window, continuously refreshing SPAs may be misjudged as stable.
- **Captcha / pure image buttons cannot be handled**: Tool results will note "elements without text accessible names exist", requiring manual user completion.
- **Cannot operate protected pages**: Browser-built-in or extension pages like `chrome://`, Chrome Web Store cannot have content scripts injected.
- **Depends on same DSH version line**: Bridge plugin pins all `@deepseek-ai/dsh-*` dependencies to 0.1.0-rc.6; when DSH upgrades, manifest and lock files need to be synced and root directory tests re-run.
- **Tab binding granularity is per extension connection**: Within one extension connection, a single controlled tab is shared, not split by conversation sessions.

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-browser](https://deepseek-plugin.org/plugins/Lum1104/dsh-browser)
Wiki generated by AI (model: `MiniMax-M2.5`)