dsh-browser-tool：DSH 浏览器工具

DSH（DeepSeek Harness）采用“一切皆插件”的架构。在需要让 Agent 在会话中驱动 Chromium、打开标签页、执行脚本或观察页面时，dsh-browser-tool 是核心组件。该工具移植自 oh-my-pi 的 browser 工具，保持了 open / run / close 的三段式语义，并提供了 Browser Relay 模式以接管用户本地的真实 Chrome。

目前该仓库已归档，开发工作已迁移至 mtaech/melon 仓库。

安装与启用¶

安装前必须先停止正在运行的 dsh 进程。在服务运行期间修改依赖树会导致运行中的进程读到残缺的模块。

安装插件：

    dsh plugin --profile <你的 profile> add dsh-browser-tool

或者通过 npm 直接添加：

    cd ~/.dsh/profiles/<你的 profile>
    pnpm add github:mtaech/dsh-browser-tool

注册到 Profile：
在该 profile 的 package.json 中，将插件添加到 dsh.profile.bundles 数组（建议放最后）：

    {
      "dsh": {
        "profile": {
          "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-browser-tool"]
        }
      }
    }

配置 Sharp：
截图功能依赖 sharp 的原生模块，pnpm 默认会跳过其构建脚本。需在 profile 的 pnpm-workspace.yaml 中放行：

    allowBuilds:
      sharp: true

验证：
重启 dsh 后，检查配置是否生效：

    dsh --profile <你的 profile> --dump-config | grep dsh-browser-tool

核心功能¶

open：浏览器来源¶

支持四种浏览器来源，通过 action:"open" 启动：

headless：进程内启动无头 Chromium，使用 puppeteer-core + @puppeteer/browsers 自动下载，支持 stealth 注入。
spawned：detached 启动指定可执行文件（桌面应用或自研 App），通过空闲 CDP 端口 attach，关闭时随进程回收。
connected：连接已有 CDP 端点（通过环境变量 DSH_BROWSER_CDP_URL），不拥有浏览器，释放时只 disconnect。
relay：通过本地 Browser Relay 接管用户正在使用的 Chrome，支持标签页分组排队和 debugger ban 恢复。

run：脚本执行¶

在标签页中运行 JS 单元，提供丰富的 API：

作用域：page、browser、tab（支持 goto/observe/ariaSnapshot/screenshot/extract/click/type/fill/press/scroll/drag/waitFor*/evaluate/select/uploadFile/ref 等）。
输出：支持文本流输出、自动 resize 至模型像素预算的截图、以及 JSON 返回值。
辅助函数：display、print、console、assert、wait、sleep。
错误处理：如果调用了 omp 专属 helper（如 read/write/env/tree/agent/parallel/pipeline/phase/log/budget），会明确报错。

close：生命周期¶

关闭标签页，并可配置是否同时 kill 浏览器进程。

relay CLI¶

提供本地服务端命令：
* serve：启动 HTTP+WS 服务，伪装 Chrome CDP discovery 接口。
* install：把扩展装入 ~/.dsh/browser-relay/extension。
* status：查看服务状态。

配置与环境变量¶

通过环境变量 DSH_BROWSER_* 控制行为（均为可选）：

DSH_BROWSER_ENABLED：0 时禁用工具。
DSH_BROWSER_HEADLESS：1 时默认使用 headless 模式。
DSH_BROWSER_RELAY / DSH_BROWSER_RELAY_URL：1 时走 relay 模式（默认 http://127.0.0.1:9224）。
DSH_BROWSER_CDP_URL：默认 connected 目标。
DSH_BROWSER_SCREENSHOT_DIR：截图落盘目录。
DSH_BROWSER_NO_WEBP：1 时模型副本使用 PNG。
DSH_BROWSER_INSTALL_CHROME：0 不自动下载 Chromium。
DSH_BROWSER_DONOR_CACHE：额外的 Chromium 复用来源（如 oh-my-pi 的缓存）。
PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE：指定 Chromium 可执行文件。

依赖项说明¶

该插件声明 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 为 peerDependencies。DSH 通过符号链接农场将宿主运行时暴露给插件。若将其写入 dependencies，pnpm 会安装副本，导致跨实例读取模块实例为 undefined，引发调度错误。安装时请勿将其写入 dependencies。

Chromium 复用策略¶

启动 headless Chromium 时，按以下顺序解析可执行文件：
1. 环境变量 PUPPETEER_EXECUTABLE_PATH / DSH_BROWSER_EXECUTABLE。
2. 系统已安装的 Chrome/Chromium。
3. 本包缓存里已有的 Chrome for Testing。
4. 其他工具缓存：直接复制 DSH_BROWSER_DONOR_CACHE、~/.omp/puppeteer、PUPPETEER_CACHE_DIR 等，不重新下载。
5. 以上均无，才从 Chrome for Testing 下载。

典型用法¶

# 1. 打开一个非 headless 的标签页
browser action:"open" name:"wiki" url:"https://en.wikipedia.org" headless:false

# 2. 在标签页内运行脚本，观察并点击登录
browser action:"run" name:"wiki" code:"await tab.observe(); await tab.click('text/Log in');"

# 3. 关闭标签页
browser action:"close" name:"wiki"

# 4. 启动 Browser Relay 服务
dsh-browser-relay serve

注意事项¶

归档状态：本仓库已归档，Issue 与 PR 请在 mtaech/melon 仓库处理。
权限：插件以当前 dsh 进程的权限运行，请检查源码与许可证。
结构：核心逻辑移植自 oh-my-pi，包括 open、run、close 三段式流程以及 tab API 实现。

GitHub 仓库