tonyd2wild/DeepSeek-Harness-Browser

DeepSeek Harness 浏览器

⚠️ 非官方社区项目

与 DeepSeek AI 无关联，未获其认可，亦非由其维护。 这是为其开源 harness 开发的
第三方插件。官方项目请见
deepseek-ai/deepseek-harness。
请勿将与本仓库相关的问题报告给 DeepSeek。

harness 内的浏览器窗格，就在聊天旁边。 一个真实的 Chrome，人类可以观看并输入，还能渲染预览本地文件——以及三个让模型可以驱动它并读取屏幕上内容的工具。

该窗格是一个真正的布局列：对话会让出空间，而不是被覆盖。实测打开时从 907px → 447px，关闭时恢复。

它能做什么

网页在真实的 Chrome 中打开，通过 Chrome DevTools Protocol 驱动，并使用其自己的持久化配置文件。你可以登录。你可以输入。那些拒绝被嵌入框架的网站也能正常工作，因为没有任何内容被嵌入框架。

本地文件会被渲染，而不是以链接形式呈现：

| 类型 | 显示为 |
|---|---|
| .md | 格式化文档——标题、表格、代码、任务列表、引用 |
| .html | 真实页面，其相对图片和样式可正常解析 |
| 图片 | 以应用背景为衬底的画框式展示 |
| PDF | 页面图像，服务端渲染——无需浏览器 PDF 查看器 |
| 代码 / 文本 / 配置 | 带语言和行数信息的语法高亮框 |

点击聊天中的链接或文件路径会在窗格中打开它。

将文件保存到你自己的机器。 只要窗格正在显示文件，工具栏中就会出现一个 ↓ 按钮。它会以 Content-Disposition: attachment 提供真实字节，而不是你正在查看的渲染页面。当 harness 位于另一台机器上时，这一点最为重要——文件在那边，而在此之前，窗格只能向你展示它的图片。

该按钮对网页刻意不显示：“下载”对实时页面并不是一个有意义的操作，而一个什么都不做的按钮比没有按钮更糟。

三个面向模型的工具

- open_preview(url, label?) —— 一个网页或本地文件。接受裸域名（cnn.com）、http(s) URL、localhost:PORT 以及文件路径（C:\path\file.md、/abs/path、file: URL）。
- read_preview(start?, count?) —— 屏幕上的内容，以文本形式返回。当 end  的窗口中加载这同一个 UI，插件会进行特性检测：窗格变成一个真正的嵌入式浏览上下文，具有原生输入和滚动，并且完全不启动第二个 Chrome。它严格是增量式的——在普通浏览器标签页中什么都不变，删除 shell 文件夹即可还原，无需撤销任何东西。

参见 docs/DESKTOP-SHELL.md；源代码在 shell/。

帧是被推送的，而不是轮询的

Page.startScreencast 只在页面重绘时发出帧；主机通过 Server-Sent Events 转发每一帧。实测约 22fps，首帧 59ms——相比之下，它所取代的轮询版本约为 2fps，且最多有 450ms 的陈旧像素。

两个发现使这成为可能，两者都不显而易见：

Chrome 不会绘制一个它认为没人能看到的窗口。 窗口在屏幕外启动，因此它保持在桌面之外——而仅这一点就产生了零个 screencast 帧，这迫使采用截图轮询，并让窗格感觉像远程桌面。四个标志修复了它，而窗口保持隐藏：

--disable-backgrounding-occluded-windows
--disable-renderer-backgrounding
--disable-background-timer-throttling
--disable-features=CalculateNativeWinOcclusion

实测：0 帧 → 176。
不设上限时，Chrome 会跑到约 100fps（每帧 46KB，约 4.5 MB/s）——远超阅读窗格所需，足以拖垮客户端。宿主会合并到约 25fps，将其维持在接近 1 MB/s。

要求

- 已安装 dsh（npm i -g @deepseek-ai/dsh）——基于 0.1.0-rc.6 构建
- Node ^22.19.0 || >=24.0.0（需要全局 fetch 和 WebSocket）
- Chrome 或 Edge——用于实时浏览器
- pnpm——dsh plugin 会调用它
- 可选： Python + PyMuPDF（pip install pymupdf）用于 PDF 渲染。
没有它时，PDF 会回退到浏览器自带的查看器。

安装

dsh plugin --profile web add /absolute/path/to/DeepSeek-Harness-Browser/plugin

然后将 examples/cordis.patch.yml 复制到
$DSH_HOME/profiles/web/cordis.patch.yml（$DSH_HOME 默认为 ~/.dsh），并用
dsh web 重启。

插件从 profile 目录解析。把插件放进 dsh 安装目录的
node_modules 会导致每个 profile 在启动时因 ERR_MODULE_NOT_FOUND 崩溃。

各部分如何组合在一起

dsh 宿主进程                          :3080 上的 Web GUI
┌──────────────────────────────┐        ┌──────────────────────────────┐
│ index.js                     │        │ client.js                    │
│  · open/read/close_preview   │        │  · 窗格，位于真实的          │
│  · /api/preview/* bridge     │◀──────▶│    布局列中                  │
│                              │        │  · 推送帧的             │
│ cdpbrowser.js ──CDP──▶ Chrome│        │  · 转发点击 + 按键           │
│ filerender.js  md/html/img   │        │  · 在  中渲染        │
│ pdfrender.js   PDF→img+text  │        │    本地文件                  │
│ webproxy.js    fallback      │        └──────────────────────────────┘
└──────────────────────────────┘

index.js 是宿主那一半；client.js 会被提供给页面，因为
package.json 声明了 dsh.client.platform: "web"。一个插件入口，两个
部分。

耗费了大量实际调试时间的问题

记录下来，因为它们都不是能猜出来的。

一个读取即排空的命令队列在打开两个窗格时会出问题。 命令原本是用
splice 从队列中取出的，所以哪个窗格先轮询就会吞掉它们，其他每个窗格都会
完全错过导航——这看起来和“open_preview 坏了”一模一样。现在命令会携带
序列号并被短暂保留；每个窗格会跟踪它最后看到的那一个。

以 / 结尾的前缀路由永远不会匹配。 dsh 的匹配器会测试
pathname === prefix || pathname.startsWith(prefix + '/')，所以注册的前缀
/api/preview/asset/ 实际上是在寻找双斜杠。注册时不要带末尾斜杠。

file: URL 无法在 http 页面内被框入。 Chrome 会拒绝，框架什么也
渲染不出来。本地文件必须由宿主提供——这也使它们成为同源，因此可读。

本地 HTML 文件需要  标签，否则它的相对  会解析
针对 harness 源和 404 —— 页面渲染时所有图像都是空白的。

以原始字节提供资源。 将图像通过渲染器处理会把它包装在一个带样式的 HTML 页面中；把那个喂给  标签什么也显示不出来。

已发布的 dsh 子包可能是不同的代次。
npm 上的 @deepseek-ai/dsh-tools 是 0.0.1-rc.1，而 harness 是
0.1.0-rc.6，并且 dsh-web-search-exa@0.0.1-rc.1 导入了一个从未发布过的包 —— 安装它会把整个 profile 拖垮。链接 harness 自带的副本。

不要让读取回退到之前的页面。 早期版本在发现活动标签页尚未渲染时，会返回最后一个已经渲染过的标签页。一个标记为 Google 的标签页返回了 CNN 的文本，而 agent 将其报告为当前内容。给那个答案加上警告是错误的修复方式；不产生它才是正确的。如果页面尚未渲染，答案就是“仍在加载”。

安全

该窗格可以承载真实的已登录会话。 它由 agent 驱动。如果该 agent 在没有审批提示的情况下运行，它可以在持有用户账户的浏览器中导航、点击和输入。告诉它不要登录或登出、发布、购买或未经要求发送任何内容，并且永远不要解决 CAPTCHA —— 并理解这只是指导，而非强制执行。

代理页面在没有 allow-same-origin 的情况下被沙箱化。 窗格显示的所有内容都从 harness 自己的源提供，因此 allow-scripts + allow-same-origin 一起使用会让任意站点的 JavaScript 触及 parent 并读取其周围的应用。本地文件不被沙箱化（自有内容，且 PDF 查看器需要）；外部页面被赋予不透明源。

资源路由拒绝逃逸其目录。 令牌指定一个目录，相对部分中的 ../ 会被拒绝 —— 否则页面内容可能驱动任意文件读取。

许可证

MIT —— 见 LICENSE。