maxiaovivi/dsh-cloak-browser

dsh-cloak-browser

安装

环境要求

- Node.js 20 或更高版本
- DeepSeek Harness（DSH） 0.1.0-rc.6
- CloakBrowser 支持的 Linux、macOS 或 Windows 平台

直接从 GitHub 安装

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

确认 Bundle 已进入 profile 的最终配置。
dsh --profile web --dump-config | grep -A24 cloak-browser

安装后重启 DSH：

dsh --profile web

DSH profile 是 pnpm workspace root，所以需要 -w。如果其他 profile 同时提供 DSH
tools 和 attachments 服务，也可以把 web 换成对应的 profile 名称。

从 0.1.1 开始，插件会复用 profile 已有的 dsh-tools 和 dsh-llm 运行时实例，避免重复
运行时引发 Cannot read properties of undefined (reading 'prepare')。

如果之前安装过 0.1.0，请先移除一次再重新安装：

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

从本地克隆安装

开发或审计插件时使用这种方式：

git clone https://github.com/maxiaovivi/dsh-cloak-browser.git
cd dsh-cloak-browser
npm ci
plugin_tarball=$(npm pack --silent)

仅 Ubuntu/Debian；这一步可能请求 sudo 权限。
npx playwright-core install-deps chromium

dsh plugin --profile web add -w "$PWD/$plugin_tarball"
dsh --profile web --dump-config | grep -A24 cloak-browser
dsh --profile web

GitHub 安装会由 pnpm 安装运行依赖。本地流程安装打包产物而不是链接开发目录，避免开发专用
的 DSH 宿主包副本进入 profile。

License 和代理环境变量

不要把凭据写进 cordis.patch.yml 或 Tool 参数；应在启动 DSH 的环境中导出：

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

没有 License key 时，CloakBrowser 会选择可用的免费版本。首次真正使用浏览器时会下载并校验
约 200MB 的 Chromium 压缩包，解压后的 ~/.cloakbrowser 缓存会占用更多磁盘空间。不需要执行
playwright install chromium。

当环境变量或本地保存的 License 被验证为 Free plan 时，插件默认席位无人使用，直接启动，
不会询问用户。插件会串行化同一 DSH 进程内的 Free 会话并发启动，并在本地或 License Server
已占用时返回明确状态，不再循环重试。插件无法撤销另一台机器或异常退出旧进程持有的服务器端
租约；这类租约仍需由上游关闭或等待过期。

存在代理 URL 时，插件会自动启用 CloakBrowser GeoIP 匹配。第一次使用可能还会把约 70MB 的
GeoLite 数据库下载到同一缓存；mmdb-lib 已随插件安装，不需要再执行安装命令。

卸载

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

卸载后重启 DSH。~/.cloakbrowser 下的浏览器缓存由 CloakBrowser CLI 单独管理。

DSH 实际演示

这条真实 DSH 会话打开 Wikipedia，通过有界 Snapshot 找到搜索框，提交 CloakBrowser，
确认结果页、完成截图并关闭浏览器。Agent 的完整运行耗时 15 秒。

Agent 端到端工作流

DSH Agent 使用 CloakBrowser 从打开页面到关闭会话的完整工作流

结果页结构化状态与稳定元素 ref

browser_snapshot 返回 Wikipedia 结果页和有界元素 ref

公开反自动化检测演示

另一条真实 DSH 会话由 Agent 打开 Rebrowser 公开 Bot Detector，等待检测、确认渲染结果并关闭
浏览器。独立的可复现 Pro 150 Runner 同时保存了检测页面，结果为 5 项通过、3 项未触发、0 项
失败。这只能证明该次公开 Detector 没有检出，不能表述为所有生产反爬和风控系统都能绕过。

CloakBrowser Pro 150 在 Rebrowser 上取得 0 项失败

项目来源

dsh-cloak-browser 是社区维护的独立 DeepSeek Harness 原生浏览器 Tool Bundle，连接了两个
上游产品：

- DeepSeek Harness 提供 Cordis 插件运行时、
Agent Loop、Tool 执行管线、模型路由和持久附件存储。
- CloakBrowser 提供兼容 Playwright 的 Chromium
启动器、源码级指纹补丁、可选的人类化输入、代理/GeoIP 集成和浏览器二进制分发。

本仓库不是 DeepSeek 或 CloakHQ 官方项目，也未获得这两个组织的附属或背书关系。

插件采用薄集成：

DSH 原生 Tool → per-Agent BrowserContext Map → CloakBrowser → Playwright

没有 MCP Server、独立中间件进程、远程浏览器服务或模型提供的任意 JavaScript 执行器。仅保留
很小的 Session Map，因为浏览器状态需要跨 Tool 调用保持，同时不能在不同 Agent 之间泄漏。

产品功能

- 原生 DSH Tool：支持 schema、规范 JSON 返回、UI 展示和 Code Mode。
- 延迟启动：只有 Agent 第一次调用浏览器 Tool 时才启动 Chromium。
- 每个 Agent 拥有隔离的 BrowserContext；agent/disposed 或插件卸载时自动关闭。
- 导航和交互后自动返回有界页面快照与短期元素 ref（例如 p1:s3:e8），Agent 无需额外调用
一次观察 Tool 即可继续。
- 自动识别 iframe 内的控件，并返回 selected、expanded、required、invalid、read-only 等表单状态。
- 支持导航、点击、填写、选择、按键、等待、内容提取、截图、标签页和生命周期管理。
- 视觉模型获得 DSH 持久图片附件；纯文本模型自动回退到页面文本快照。
- 通过 CloakBrowser 提供可选的人类化鼠标、输入和滚动。
- CloakBrowser 人类化点击/填写出现特定的 covered by  执行前误报时自动重试一次；
其他错误仍安全失败。
- 未显式配置 seed 时，自动为每个 Agent 派生稳定且哈希化的 fingerprint seed。
- 自动识别 License 套餐：验证为 Free 的 Key 无需询问用户即可启动；同一 DSH 进程内的 Free
会话并发启动会被串行化。
- 检测到代理环境变量时自动启用 GeoIP 一致性，所需运行依赖随插件安装。
- 默认使用临时 Context；显式配置后可使用按 Agent 隔离的持久 profile。
- 支持域名允许/拒绝规则、显式私网地址拦截、页面/输出限制、协作取消和浏览器清理。
- 常驻路由提示让交互或真实渲染任务选择浏览器，而简单公开文本查询继续使用更轻量的 Web Tool。

Tool 与 Agent 工作流

推荐流程：

browser_open(url)
→ Free、付费套餐或无 Key 本地构建：无需询问，直接启动
→ Free 席位已占用：返回 not_started，不循环重试
→ 返回 snapshot + refs
→ browser_click / browser_type / browser_select → 返回下一份 snapshot + refs
→ 浏览器任务完成后 browser_close

默认流程不需要在每次操作之间手工调用 browser_snapshot。页面自行变化或 Agent 需要刷新视图时，
仍可使用显式 Snapshot Tool。

| Tool | 功能 |
|---|---|
| browser_open | 无需用户确认，延迟打开会话；传入 URL 时同时返回 Snapshot |
| browser_navigate | 导航并返回含 ref 的新 Snapshot |
| browser_snapshot | 显式刷新有上限的页面/iframe 文本和 ref |
| browser_click | 点击 ref 并返回下一份 Snapshot |
| browser_type | 填写文本、可选提交并返回下一份 Snapshot |
| browser_select | 选择选项并返回下一份 Snapshot |
| browser_press | 按下限定导航键并返回下一份 Snapshot |
| browser_wait | 等待文本或时间并返回结果 Snapshot |
| browser_extract | 提取有上限的文本、HTML 或属性，不执行任意 JS |
| browser_screenshot | 视觉路由返回图片附件，文本路由返回元数据 |
| browser_tabs | 列出、选择或关闭标签页 |
| browser_close | 关闭并清除当前 Agent 的浏览器会话 |

常驻提示会把“打开、浏览、点击、填写、提交、登录、检查渲染状态、网页截图”等请求路由到
browser_。简单公开文本调研仍优先使用 Web Search/Fetch，需要真实渲染或交互时才升级。

示例请求：

使用浏览器打开 https://example.com，检查渲染后的页面，列出可交互元素，完成后关闭浏览器。

配置

Bundle 默认配置位于 cordis.patch.yml。

| 配置项 | 默认值 | 说明 |
|---|---:|---|
| headless | true | 无可见窗口运行 Chromium |
| humanize | true | 启用 CloakBrowser 人类化交互 |
| humanPreset | default | default 或 careful 行为预设 |
| geoip | auto | proxyEnv 存在时自动按代理 IP 推导语言和时区，也可显式设为 true 或 false |
| proxyEnv | CLOAKBROWSER_PROXY_URL | 保存代理 URL 的环境变量名 |
| persistentProfileRoot | 空 | 按 Agent 哈希创建持久 profile 的根目录 |
| fingerprintSeed | 空 | 留空时自动派生稳定且哈希化的 per-Agent seed；显式 seed 会覆盖自动值 |
| fingerprintNoise | false | 关闭 canvas/WebGL/audio/client-rect 注入噪声；实测消除了 5 个 CreepJS lies |
| fingerprintWindowsFontMetrics | false | Chromium 148+ Windows 字体指标；Linux 必须有真实 Windows 字体集 |
| allowThirdPartyCookies | false | Chromium 148+ 的内嵌 reCAPTCHA/SSO/支付流程兼容开关 |
| fingerprintStorageQuotaMb | 0 | 可选 storage quota；0 保留上游自动值 |
| viewportWidth、viewportHeight | 0、0 | 可选匹配 viewport/指纹屏幕尺寸；0 使用更安全的自动管理 |
| allowedDomains | [] | 空数组允许公网；支持精确域名和 .example.com |
| blockedDomains | [] | 在 allowlist 前检查的拒绝域名 |
| blockPrivateNetworks | true | 阻止显式 localhost、私网、link-local 和保留 IP URL |
| maxPages | 5 | 单个 Agent 会话的最大标签页数 |
| actionTimeoutMs | 15000 | 普通 Playwright 操作超时 |
| typingTimeoutMs | 90000 | 为刻意放慢的人类化输入提供更长超时 |
| navigationTimeoutMs | 30000 | 导航超时 |
| maxSnapshotElements | 100 | 单次快照返回的最大 ref 数 |
| maxTextChars | 12000 | 页面和提取文本最大长度 |
| autoSnapshot | true | 在导航和交互结果中自动包含一份新的有界 Snapshot |
| screenshotFormat | jpeg | jpeg 或 png |
| screenshotQuality | 80 | JPEG 质量 |
| routePrompt | true | 向 system prompt 注入浏览器选择规则 |

生产环境建议在 profile override 中限制导航域名：

- id: cloak-browser
config:
allowedDomains:
- 'example.com'
- '*.example.com'
blockedDomains:
- 'admin.example.com'
persistentProfileRoot: '/var/lib/dsh/cloak-profiles'

同一个站点身份应保持 profile、fingerprint、代理、timezone 和 locale 一致。不要把日常 Chrome
profile 交给 Agent。

安全边界

- browser_type.text 会进入 DSH Tool 日志，不能传递密码、API key、Cookie 或 Token。当前版本
有意不包含凭据存储驱动的输入 Tool。
- 页面内容属于不可信输入；插件会明确告诉 Agent，网页内容不能覆盖系统或用户指令。
- allowedDomains 用于顶层导航，是应用层护栏而不是完整网络沙箱。高安全环境仍需用容器/防火墙
防止 DNS rebinding 和网页子资源访问私网。
- 插件不允许模型提供任意 JavaScript 执行代码。
- 仅在你有权自动化的系统和网站上使用，并遵守法律与站点条款。

上游许可

本仓库代码使用 MIT License。

CloakBrowser wrapper 源码使用 MIT，但其下载的 Chromium 二进制由 CloakHQ 单独的
Binary License 管理。
在重分发、逆向、修改二进制，或对外提供客户可控 Browser-as-a-Service 前必须审阅该许可。

兼容性与验证

当前版本锁定：

| 组件 | 版本 |
|---|---|
| dsh-cloak-browser | 0.3.0 |
| DeepSeek Harness packages | 0.1.0-rc.6 |
| CloakBrowser wrapper | 0.5.7 |
| Playwright Core | 1.62.0 |
| Node.js | >=20 |

当前版本执行过：

- 域名策略、私网拒绝、自动及 iframe snapshot ref、过期 ref、安全 actionability 重试、稳定
per-Agent seed、Agent 隔离、图片附件和清理单元测试。
- 在干净的临时 DSH Web profile 中安装并完整启动 Cordis/Web。
- Linux x64 免费版 CloakBrowser Chromium 真实启动、本地页面导航、iframe 发现、ref 验证和截图。
- 通过插件路径和 CloakBrowser direct 对照运行上游同口径的本地及公开隐身 detector；完整报告见下文。
- npm audit、语法检查和 npm package dry-run。

本地验证命令：

npm run check
npm test
npm audit --omit=dev
npm pack --dry-run

单元测试使用假的 BrowserContext，不会下载 Chromium。

隐身测试结果

在本文档所列 Linux 主机上，使用免费 Chromium 146、headless、无代理且无 Windows 字体时，插件
通过 5/6 个核心公开 detector。直接调用 CloakBrowser launchContext 的对照结果完全相同；两者都只在
Device & Browser Info 的 hasInconsistentTimingResolution 失败。关闭 fingerprint noise 后，CreepJS
从 5 lies 改进为 0，因此它已成为插件默认值。FingerprintJS demo 仍会拦截这个旧二进制/环境；
reCAPTCHA v3 一次得到 0.9，重复运行则没有得到 score。

双语测试方法、命令、严格判定规则、完整结果和升级路径见
docs/STEALTH.zh-CN.md。公开 detector 会随环境和时间变化，不能保证
无关站点一定放行。

性能

在文档所列 Linux 测试机上，缓存后的首次延迟启动约 635ms，后续约 183ms；100-ref 快照 P50
为 29ms，提取 12,000 字符为 1.2ms，视口截图为 51ms。关闭 humanize 时“快照→点击→快照”
为 161ms；默认的人类化工作流会有意放慢到 6.27 秒。自动观察把“导航→观察”从两次 Tool
调用降为一次，把“操作→观察”工作流从三次降为两次，且浏览器执行时间没有实测回退。双语
方法、内存数据、对比表和原始 JSON 见
docs/PERFORMANCE.zh-CN.md。