tuojc/dsh-browser-firefox

dsh-browser-firefox

Firefox 版的 DeepSeek Harness 浏览器操作插件，让模型直接读取并操作你正在使用的 Firefox 标签页，登录态、会话与 Cookie 全程保留。

- 后台静默操作：导航与点击链接一律新建标签页（不覆盖当前页、不抢焦点），Agent 在后台完成操作。
- 常驻运行：扩展加载后即常驻并保持桥接连接，无需先点开侧边栏。
- 会话级分组：每个 dsh 对话固定一个带颜色的标签页组，组名取自目标域名（如 bilibili.com）。

本项目从 Lum1104/dsh-browser（MIT 许可）移植为 Firefox 版，保留原作者版权（见 LICENSE）。

这是什么

dsh（DeepSeek Harness）是 DeepSeek 的开源插件式 Agent 框架。本仓库提供配套的两个组件：

| 组件 | 位置 | 作用 |
|---|---|---|
| bridge 插件 | plugin/ | 装在 dsh web 里的本地服务端（WebSocket 桥） |
| Firefox 扩展 | extension/ | 装在 Firefox 里，实际操作浏览器标签页 |

页面被转成带编号交互元素清单的结构化文本，模型按编号操作元素；遇到文本无法表达的内容（图片、图表、验证码）时，browser_screenshot 把截图作为原生图像块直接送入对话上下文，模型直接看图。

快速开始

第 1 步：安装 bridge 插件

前置要求：dsh 版本需 ≥ 0.1.2-alpha.2（0.1.2 线的 Typert Remote 网关）。npm latest 标签目前的 0.1.1-rc.x 不受支持——其网关没有流式接口，会报 ctx.typertGateway.stream is not a function。升级宿主请用 npm install -g @deepseek-ai/dsh@next。

dsh plugin --profile web add dsh-browser-firefox@latest

安装后重启 dsh web 生效。

第 2 步：安装 Firefox 扩展

扩展已上架 Firefox 扩展商店，直接安装👉 DSH 浏览器助手 - addons.mozilla.org（也可在 AMO 搜索「dsh 浏览器助手」）。

第 3 步：填写 token（仅首次）

cat ~/.dsh/ext-bridge-token   # 复制输出

打开扩展侧边栏 → 右上角 ⚙️ 设置 → 把复制的内容粘贴到 Token 一栏 → 保存并连接。（桥地址留空即可，自动探测本机 3080/3081/3090 端口。）

为什么 Firefox 必须填 token（0.3.1 起，与上游同步的安全收紧）：Firefox 扩展的 moz-extension:// Origin 是每次安装随机生成的 UUID，无法据此辨认扩展身份，所以 bridge 要求 Firefox 客户端一律出示 token。没填或填错时，面板会显示「需要 Token」横幅引导你完成这一步。

验证

bridge 发现端点应返回 WS 地址
curl -s http://127.0.0.1:3080/ext/bridge-config
=> {"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}

更新组件

插件与扩展必须同版本，更新时两端一起换：

- 插件：npm i -g dsh-browser-firefox（或按你当时的安装方式重装），然后重启 dsh web
- 扩展：在 Firefox 附加组件站更新，或 about:debugging 重新载入新的构建

版本不一致时，侧边栏顶部会出现黄色横幅提示（两端握手时会互相核对版本号）。

功能

| 能力 | 工具 | 说明 |
|---|---|---|
| 读取页面 | browser_snapshot | 结构化文本快照：标题/URL/正文/编号控件/表单字段（敏感值掩码）；delta: true 只返回变化 |
| 点击元素 | browser_click | 按编号点击；若是 http/https 链接则后台新开标签页，否则普通点击 |
| 填写表单 | browser_type | 输入文本；replace 先清空再输入 |
| 按键 | browser_press | Enter / Tab / Escape / 方向键等 |
| 滚动 | browser_scroll | 视口滚动（up/down/top/bottom） |
| 导航 | browser_navigate | 后台静默新建标签页打开 URL，不覆盖当前页 |
| 历史 | browser_back / browser_forward | 当前标签页内后退/前进 |
| 刷新 | browser_reload | 重新加载当前标签页 |
| 读区域 | browser_get_text | 懒加载内容 / 局部文本 |
| 等待 | browser_wait | 页面加载与渲染稳定检测 |
| 截图 | browser_screenshot | 按需截图（视觉兜底），图像作为原生图像块直接进模型上下文 |
| 执行 JS | browser_evaluate | 页面上下文执行任意 JS（支持 async/await），snapshot/click 覆盖不到时的逃逸舱 |
| 列出标签页 | browser_list_tabs | 列出当前会话分组内的所有标签页（ 标记工作标签页） |
| 打开标签页 | browser_open_tab | 后台开新页（归组），返回标签页 id |
| 切换工作页 | browser_follow_tab | 后续操作作用于指定标签页 |
| 关闭标签页 | browser_close_tab | 只能关闭本会话打开/归入本组的标签页 |

模型选择
会话栏的模型芯片显示当前模型，点开为按提供商分组的目录（含推理强度选择）；选择按会话生效，新会话在发送首条消息后自动应用。

问答卡片

助手经 ask_user_question 提问时，问题卡片直接出现在侧边栏底部——在浏览器里选择/填写/放弃即可，不必切到 dsh web；桥断开时自动回落给 dsh web 回答。

权限级别

输入区盾牌按钮选择权限级别——锁定（不碰页面）/ 只读（默认，可读不可动）/ 读写（全自动）；按钮按当前级别着色（锁定=红、读写=黄），被拒绝的调用会告诉模型当前级别与切换方法。

附件

输入区回形针按钮添加图片（走宿主多模态通道，张数/尺寸等限制跟随宿主投影）或文本文件（fenced 拼入消息），也可直接粘贴；消息历史中的图片经 session/attachment 回读渲染，点击可放大。

后台静默操作

browser_navigate 与点击链接都用 active:false 新建标签页——浏览器停留当前页、不切走。扩展内部维护「工作标签页」，后续 browser_snapshot/点击等操作静默作用在这个后台标签页上。

常驻运行

Firefox MV3 的 background 默认是 event page，空闲 45-90 秒会休眠。本扩展用 3 个错峰的 alarm（每 20 秒）持续保活，使 background 常驻、WebSocket 桥常连——Agent 随时能操作浏览器，无需先点侧边栏。

截图（视觉兜底）

当页面内容是图片/公式/验证码等无法用文本表达时，模型可调 browser_screenshot 截图：图像存入宿主附件库并作为原生图像块直接返回给模型查看（支持视觉的 DeepSeek 路由原生读图；纯文本路由由宿主自动降级为占位符）。不再产生本地临时文件。

会话级标签页组

每个 dsh 会话固定一个 Firefox 标签页组：该会话内导航/点击链接新建的标签页都归入同一组，颜色自动分配（蓝/绿/红/紫…循环），组名取自目标域名（去 www. 前缀，如 bilibili.com）——不同会话不同颜色、不同域名，连续性工作聚在一起。

架构

sidebar panel (React) ◄─port─► background script ◄─WS─► dsh bridge 插件
│
tabs.sendMessage (DSH_ACTION / DSH_RESOLVE_ELEMENT)
▼
content script (快照 / 动作 / 元素解析 / 隐私)

- bridge 插件（plugin/）：token 认证的 WebSocket 服务端、工具分发、会话标识透传；挂载 /ext/bridge（WS）与 /ext/bridge-config（地址自动发现）。
- 扩展 background（extension/src/background/）：桥连接（指数退避重连 + alarm 保活）、工具分流（导航/链接在 background 新建标签页并分组，其余分发到 content script）、标签页组管理。
- content script（extension/src/content/）：纯文本快照、稳定编号、元素解析、动作执行、敏感字段掩码。
- panel（extension/src/panel/）：React 侧边栏对话界面，Markdown 渲染（已消毒）。
- 协议：plugin/src/protocol.ts 是两端共享的帧格式定义（tool.call 帧含 expiresAt/sessionId/title；超时或取消时服务端以 tool.cancel 撤回调用）。

从源码构建

前置要求：Node.js >=20、pnpm 11.x、Firefox >=140（标签页组需要）。

从源码 clone 后，先执行 cp extension/manifest.example.json extension/manifest.json，并把其中 gecko.id 改成你自己的唯一邮箱（提交 AMO 签名需要，仓库不含个人 manifest）。

pnpm install
pnpm build   # 依次构建 bridge 插件 + 扩展

构建产物：

| 组件 | 分发方式 | 本地产物 |
|---|---|---|
| 插件 | 发布到 npm（dsh-browser-firefox），用户一行命令安装 | plugin/lib/（构建输出） |
| 扩展 | 提交 AMO（Firefox 扩展商店） | extension/dsh-browser-firefox.zip（安装包）、extension/dsh-browser-firefox-extension-source.zip（AMO 审核用源码包） |

目录结构

plugin/                                 # dsh 侧 bridge 插件（npm 包 dsh-browser-firefox）
src/                                  # 源码（协议 / 服务端 / 工具）
lib/                                  # 构建产物
cordis.patch.yml                      # 插件注册配置
extension/                              # Firefox 扩展
src/background/                       # 桥连接 / 工具分流 / 分组管理
src/content/                          # 快照 / 动作 / 元素解析
src/panel/                            # React 侧边栏
src/browser.d.ts                      # browser. 类型声明
manifest.json                         # Firefox MV3 清单
dist/                                 # 构建产物
dsh-browser-firefox.zip               # 加载 / 提交包
dsh-browser-firefox-extension-source.zip  # 源码包
scripts/install-firefox.sh              # 一键安装（跨电脑）
README.md / PRIVACY.md / LICENSE
package.json / pnpm-workspace.yaml / pnpm-lock.yaml

安全

- bridge 路径自带 token 认证；非回环远程拒绝特权方法（settings/credentials/open-*）。
- Firefox 扩展一律要求 token：moz-extension:// Origin 是每次安装随机生成的 UUID，无法据此辨认扩展身份，不构成安全边界。
- 密码、支付卡号等敏感字段在快照中一律掩码为 ••••。
- 导航/点击链接只在后台新建标签页，不覆盖、不抢用户当前页面。
- 仅限本机回环使用：桥地址是 ws:// 明文，token 与页面内容在传输中不加密。如需远程部署（dsh web --host 0.0.0.0），请在前面自建 wss/TLS 反向代理，不要在不可信网络直接暴露 3080 端口。

许可

MIT © 2026 Yuxiang Lin（原 Lum1104/dsh-browser 作者）；Firefox port modifications © 2026 tuojc。保留原版权声明与 MIT 协议。