# dsh-browser

> 在 dsh web 配置中挂载 token 认证的 WebSocket 桥，让 Chrome 扩展读取并操作用户真实浏览器内的页面，保留登录态。

## 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-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
这个插件是 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 的 `web` profile；插件在 `webServer` 上注册 `/ext/bridge` WebSocket 升级路由与 `/ext/bridge-config` HTTP 端点，并通过 `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 版本 |

本插件未声明额外的原生模块依赖。

## 安装方式
```bash
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 工具管线尚未把同一策略开放给其它客户端

---

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/packages/browser/bridge-browser)
Wiki generated by AI (model: `MiniMax-M3`)