前言¶
在 DeepSeek Harness（DSH）里做前端或本地 Web 应用联调时，常见做法是在对话界面里嵌一个 iframe，指向 http://127.0.0.1:5173/ 这类地址。DSH 的 Web GUI 往往通过反向代理以 https 对外暴露；远程浏览器打开时，127.0.0.1 会解析到浏览器所在机器，而不是跑 DSH 的那台主机；同时 https 页面加载 http 资源还会触发混合内容拦截。结果是 iframe 里看不到本机 dev server，或页面一片空白。
dsh-web-preview（仓库 qoqpqpq/dsh-web-preview）把 DSH 主机上的 loopback 服务经 DSH 同源路径转发出去，预览仍走 https 且与 GUI 同源，从而规避上述问题。下面介绍它是什么、能做什么、如何安装与配置。
这是什么¶
维护者为 qoqpqpq，在插件目录中归类为客户端（面向 DSH Web 端注入 UI 与路由）。一句话：在 DeepSeek Harness GUI 内预览任意本机端口上的 Web 服务，并提供嵌入标签页、浮动窗口，以及 Console / Network / Errors 诊断面板。
官方简介：Preview any local web server inside the DeepSeek Harness GUI — remote-browser-safe same-origin proxy with embed tab, floating window and Console/Network/Errors toolbox.
核心功能¶
以下能力均来自项目 README 与 package.json 说明。
远程浏览器可用
- 不经由裸
localhostiframe，避免 mixed content、错误 localhost、以及 DSH 侧不必要的 X-Frame-Options 问题（README 表述为 remote-browser-safe）。
两种 UI 入口
- Embedded tab：对话窗口中的「Web Preview」标签（React slot 组件）。
- Floating window：
PREVIEW按钮 + 可拖拽浮动窗，适合侧栏式预览。
诊断工具箱
- 可折叠的 Console / Network / Errors 面板；插件向被代理的 HTML 注入捕获脚本，将控制台输出、fetch/XHR 与运行时错误 beacon 回主机缓冲，客户端轮询展示。
任意本地端口
- 工具栏可输入
localhost:5173、127.0.0.1:8080等；客户端将 origin 编码为/web-preview/__proxy/<origin>/<path>，主机再转发到对应 loopback 服务，无硬编码端口。
配置默认值
- 可通过 profile 预填工具栏 URL、固定默认 upstream，以及为硬编码根路径（例如
/cesium/）配置 extra same-origin 别名。
实现分层（便于理解行为）
| 层 | 作用 |
|---|---|
Client（client.js） |
注册 conversation.view 标签与 shell.overlay 浮动窗；将 loopback URL 改写为同源 /web-preview/__proxy/...；轮询 /web-preview/__events 获取诊断。 |
Host（index.js） |
在 DSH webServer 上注册代理与诊断路由；转发到 http://<origin>/<path>，向 HTML 注入捕获脚本并缓冲诊断事件。 |
当前 package 版本为 1.1.2，许可证 MIT。Node 引擎要求：^22.19.0 || >=24.0.0；peer 依赖含 @deepseek-ai/cordis（>=4.0.0）与 react（^18.2.0）。
安装与启用¶
从 DSH Plugin Market（或任意 curated registry 源）安装，命令以 README 为准：
dsh plugin --profile web add dsh-web-preview
安装后重启 dsh web。README 说明：启动时无需额外审批——该插件为 bundle，而非动态 Cordis 插件。
配置¶
所有配置项可选，写在 profile patch 中该插件的 config: 下（loader 仅将 config: 传给插件）。示例路径与字段来自 README：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-web-preview
config:
# Prefill the toolbar with this URL (client-side convenience).
defaultUrl: "http://127.0.0.1:4173/"
# Optional fixed upstream for the bare /web-preview/<path> form.
defaultUpstream: "http://127.0.0.1:4173"
# Extra DSH-origin prefixes forwarded to a local service. Needed when the
# previewed app makes root-absolute requests that must stay on the same
# origin but are NOT under /web-preview (e.g. Cesium's hardcoded /cesium/).
extraAliases:
- prefix: "/cesium"
origin: "127.0.0.1:4173"
path: "/cesium"
# Optional override for the browser-error log (defaults to the OS temp dir).
logPath: "/tmp/dsh-web-preview-errors.log"
若 defaultUpstream 为空，只能通过工具栏输入 URL 选择目标；动态路径 /web-preview/__proxy/<origin>/<path> 仍可在零配置下指向任意 localhost origin。
典型用法¶
- 按上一节安装并重启
dsh web。 - 在本机启动 dev server（例如 Vite 默认
5173或 README 示例中的4173）。 - 打开 DSH Web GUI：使用对话区的 Web Preview 标签，或点击 PREVIEW 打开浮动窗。
- 在工具栏输入目标，例如
http://127.0.0.1:4173/或localhost:5173；客户端会自动改写为 DSH 同源代理 URL 并在 iframe 中加载。 - 需要排查页面行为时，展开 Console / Network / Errors 面板；必要时可对
/web-preview/__clear重置诊断缓冲（由插件 UI 或路由能力支持，缓冲上限 2000 条事件）。
路由均挂在 DSH 同源下，常见条目包括：
| 路由 | 方法 | 用途 |
|---|---|---|
/web-preview/__proxy/<origin>/<path> |
any | 动态转发到 http://<origin>/<path> |
/web-preview/<path> |
any | 转发到 defaultUpstream（需已配置） |
<alias.prefix>/<path> |
any | 按 extraAliases 转发 |
/web-preview/__events |
GET | 拉取缓冲诊断（支持 ?since=<id>） |
/web-preview/__config |
GET | 解析后的插件配置（Client 读取默认值） |
适用场景与注意¶
适合谁
- 通过远程浏览器访问 DSH（反向代理 +
https），又需要在 GUI 里看本机 dev server 的前端或智能体界面开发者。 - 需要在 iframe 内快速看控制台与网络请求、而不必单独开浏览器 DevTools 的场景（能力以插件注入的捕获脚本为准）。
安全与权限
- README 说明：主机仅转发客户端编码后的 loopback 目标，不会代理任意远程 URL；loopback 在编码前由客户端校验。
- 捕获脚本运行在 iframe 内，受 iframe
sandbox约束，仅向 DSH 同源 beacon。 - 插件以当前 DSH 进程权限运行；安装前请自行审阅 GitHub 源码 与 MIT 许可证。社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
DSH 生态强调「一切皆插件」；dsh-web-preview 解决的是 GUI 预览本机 Web 服务时的同源与 mixed content 问题，并附带基础诊断面板。更多细节见目录页与仓库 README。
