前言¶

在 DSH 的插件方式下，浏览器能力可以作为原生工具接入 Agent 的工具管道。dsh-cloak-browser 解决的是：Agent 需要打开页面、完成交互、读取渲染结果时，浏览器会话状态保留在 DSH 的工具调用中，并为每个 Agent 维护隔离的 BrowserContext。页面状态以受限快照和短引用返回，Agent 可以继续基于这些引用执行下一步操作。

这是什么¶

maxiaovivi/dsh-cloak-browser 是一个由 maxiaovivi 维护的 DSH 插件包，定位是：

Native CloakBrowser tools for DeepSeek Harness with per-agent browser sessions and snapshot references.

它把 DSH 与 CloakBrowser 接入到一起：DSH 侧负责 Agent、工具调用和附件能力，CloakBrowser 侧负责浏览器启动、输入和浏览器二进制分发。已核实资料明确说明：该仓库不是 DeepSeek 或 CloakHQ 官方项目，也不代表这两个组织背书。

核心能力¶

下面是已核实资料中列出的主要能力：

• Native DSH tools：提供 schema、canonical JSON results、UI presentation 和 Code Mode compatibility。
• Lazy browser startup：Chromium 只在 Agent 调用浏览器工具时启动。
• One isolated BrowserContext per Agent：Agent 结束或插件卸载时自动关闭对应上下文。
• Automatic bounded page snapshots：导航和交互后返回限定范围的页面快照，并附带短生命周期元素引用，例如 p1:s3:e8。
• 浏览器工具覆盖 navigation、click、fill、select、keyboard、wait、extraction、screenshot、tab 和 lifecycle。
• Durable DSH image attachments：面向支持图像的模型保存图像附件；文本路由使用文本快照回退。
• Optional humanized mouse、typing 和 scrolling，通过 CloakBrowser 提供。
• Automatic license-plan detection：已验证的 Free key 可不经用户确认直接启动；同一 DSH 进程内的本地 Free-session 并发启动会被串行化。
• Proxy-aware GeoIP consistency：当代理环境变量存在时自动启用；其运行时依赖已打包。
• Domain allow/deny rules、explicit local/private-address blocking、page and output limits、cooperative cancellation 和 browser cleanup。
• A resident routing prompt：让浏览器用于 rendered 或 interactive 任务；简单公开文本查找继续走更轻量的 web search/fetch tools。

安装与启用¶

前置条件¶

已核实资料给出的要求包括：

• Node.js 20 or newer
• DeepSeek Harness (DSH) 0.1.0-rc.6
• 已抓取资料中的 package.json 显示版本为 0.3.0
• peerDependencies 为 @deepseek-ai/dsh-llm ^0.1.0-rc.6 和 @deepseek-ai/dsh-tools ^0.1.0-rc.6

从 GitHub 安装¶

先添加插件：

dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

然后确认插件已组合进 profile：

dsh --profile web --dump-config | grep -A24 cloak-browser

重启 DSH 使插件生效：

dsh --profile web

上面的命令沿用已核实资料中的示例 profile web。如果当前 DSH 环境使用其他 profile，请按实际环境调整命令中的 profile 名称。

可选环境变量¶

许可证 key 和代理地址不应写入 cordis.patch.yml 或工具参数中。资料要求把它们导出到启动 DSH 的环境中：

export CLOAKBROWSER_LICENSE_KEY='your-license-key'       # optional
export CLOAKBROWSER_PROXY_URL='http://user:pass@host:port' # optional
dsh --profile web

Free key 与无 key 路径¶

如果没有 license key，CloakBrowser 会选择其可用的 free build。首次浏览器使用时会下载并校验大约 200 MB 的 Chromium archive。解压后的缓存可能在 ~/.cloakbrowser 下占用明显更大的磁盘空间。资料明确说明不需要执行 playwright install chromium。

已验证的 Free key 会直接启动，不要求用户确认。同一 DSH 进程内的并发本地 Free-session 启动会被串行化。该插件不能撤销属于其他机器或异常遗留进程的会话。

代理与 GeoIP¶

当代理 URL 存在时，插件会自动启用 CloakBrowser 的 GeoIP matching。首次使用时可能会下载约 70 MB 的 GeoLite database，并放入同一个缓存目录。

旧版本迁移¶

已核实资料说明：0.1.1 及之后的版本会复用 profile 中已有的 dsh-tools 和 dsh-llm runtime instances。如果之前安装过 0.1.0，重新安装前需要先卸载一次：

dsh plugin --profile web remove -w dsh-cloak-browser
dsh plugin --profile web add -w github:maxiaovivi/dsh-cloak-browser

完成后重启 DSH。

卸载¶

执行：

dsh plugin --profile web remove -w dsh-cloak-browser

然后重启 DSH。资料说明，~/.cloakbrowser 下缓存的浏览器二进制由 CloakBrowser CLI 单独管理。

典型用法¶

已核实资料给出的推荐流程如下：

browser_open(url)
  → Free, paid, or keyless: launches directly without asking
  → occupied Free seat: returns not_started without retrying in a loop
  → returns snapshot + refs
  → browser_click / browser_type / browser_select → returns next snapshot + refs
  → browser_close when the browser task is complete

也就是说，Agent 先打开目标页面，插件返回页面快照和短引用；随后 Agent 基于这些引用执行点击、输入或选择；每次交互后再返回下一轮快照和引用；任务完成后调用 browser_close 结束浏览器任务。

对于支持图像的模型，插件使用 Durable DSH image attachments；对于文本路由，使用文本快照作为回退。

适用场景与注意¶

适合的场景¶

• Agent 需要打开已渲染页面并完成交互。
• 需要点击、填写、选择、键盘输入、等待、提取、截图、标签页管理和浏览器生命周期管理。
• 希望在 DSH 内部隔离多个 Agent 的浏览器状态，避免跨 Agent 泄露。
• 希望浏览器工具返回结构化快照和短引用，而不是让 Agent 自己维护大量页面 DOM。
• 希望通过路由提示，把简单公开文本查找留给更轻量的 web search/fetch tools。

使用前注意¶

1、该插件运行在启动 DSH 的环境中，并使用当前 DSH 进程可获得的权限。安装前应检查源码、策略、工具边界和许可证。

2、许可证类型方面，已核实资料只说明 package.json 的 files 列出了 LICENSE 文件名，但没有给出具体许可证类型。不要把它当作已确认的 MIT、Apache 或其他许可证。

3、凭据不应放在 cordis.patch.yml 或工具参数中，应导出到启动 DSH 的环境中。

4、首次使用可能产生明显磁盘占用：无 key 路径首次会下载约 200 MB Chromium archive；代理路径首次可能下载约 70 MB GeoLite database。

5、Free-session 的占用状态只适用于本地并发场景。无法撤销其他机器或异常遗留进程持有的会话。

6、该仓库是社区维护项目，不是 DeepSeek 或 CloakHQ 官方项目，也不代表这两个组织背书。

结尾¶

dsh-cloak-browser 的核心是把 CloakBrowser 的浏览器能力做成 DSH 原生工具：按 Agent 隔离浏览器上下文，返回受限快照和短引用，并保留导航、交互、截图、附件、代理 GeoIP、Free-session 串行化和安全边界等能力。

GitHub 仓库地址：

https://github.com/maxiaovivi/dsh-cloak-browser