dsh-browser-firefox

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

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

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

这是什么

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

集成是纯文本的：页面被转成带编号交互元素清单的结构化文本，模型按编号操作元素。截图只是视觉兜底——保存为 PNG 文件交给视觉工具分析，不以图片形式进入对话上下文。

快速开始

第 1 步：安装 bridge 插件

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"}

功能

后台静默操作

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

常驻运行

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

配合视觉工具（截图）

当页面内容是图片/公式/验证码等无法用文本表达时，模型可调 browser_screenshot 截图，得到 PNG 绝对路径后交给任意视觉工具（如 vision_glance）分析。截图保存在 session workspace 的 .dsh-browser-tmp/ 目录，多张并存、最多 20 张（超出自动删最旧）；看完后调 browser_clear_screenshots 清理。

会话级标签页组

每个 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 插件 + 扩展

构建产物：

目录结构

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，无法据此辨认扩展身份，不构成安全边界。
• 密码、支付卡号等敏感字段在快照中一律掩码为 ••••。
• 导航/点击链接只在后台新建标签页，不覆盖、不抢用户当前页面。

许可

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