DSH Preview Plugin：在 iframe 中嵌入开发服务器并透明代理 SPA 流量

前言¶

DeepSeek Harness (DSH) 的设计理念是“一切皆插件”。在开发智能体或 Web 应用时，在 DSH 中直接预览本地开发服务器的页面是一个常见需求。传统的预览方式往往难以处理单页应用（SPA）的路由跳转、静态资源加载以及后端 API 代理。dsh-preview-plugin 插件通过在 iframe 中嵌入开发服务器并提供透明的 SPA 代理，解决了这些问题。

是什么¶

这是一个为 DSH 提供的实时预览标签页组件，由 RaulLazaro 维护。它允许将任意开发服务器嵌入到 DSH Web GUI 的预览标签页中，并支持单页应用的路径代理和多应用 monorepo 场景。

安装与启用¶

启用该插件需要修改 DSH Web 配置的 package.json。

添加为依赖项
在 package.json 的 dependencies 字段中添加：

    {
      "dependencies": {
        "dsh-preview-plugin": "file:~/workspace/dsh-preview-plugin"
      }
    }

添加到 bundles
在 package.json 的 dsh.profile.bundles 数组中添加 dsh-preview-plugin：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "...",
            "dsh-preview-plugin"
          ]
        }
      }
    }

重启 DSH
执行重启命令以加载插件：

    systemctl restart dsh

典型用法¶

基础预览¶

在 VPS 上启动开发服务器（例如 npm run dev -- --host 0.0.0.0 --port 3000）。
打开 DSH Web GUI 的 Preview 标签页。
在 URL 字段输入端口号（如 3000）并点击 Go。
字段会自动切换到当前页面路径（例如 /preview/3000/laptops?page=2#specs），支持随时编辑并按回车跳转。

多应用 Monorepo¶

如果前端和后端运行在不同端口（例如前端 4321，后端 Payload CMS 3001），可以配置多端口代理：
1. 启动两个服务器。
2. 打开 Preview 标签页。
3. 在 URL 字段输入前端端口（如 4321），在 Backend 字段输入后端端口（如 3001，多个端口用逗号分隔）。
4. 点击 Go。此时 API 请求（如 http://localhost:3001/api/...）会自动通过 /preview/3001/api/... 代理到 iframe 内。

Agent 工具¶

Agent 可以使用 set_preview_port 工具编程式配置端口：

set_preview_port(port: 4321, backendPorts: [3001])

工作原理与特性¶

SPA 代理：插件注册了 /preview/:port/* 路由。对于静态资源直接代理；对于 SPA 导航，返回根 HTML 由客户端路由处理。
智能路由：支持片段链接（#section）跳转，支持根相对资源（如 /assets/photo.png）和 srcset 的自动重写。
真实流量：支持 fetch、XMLHttpRequest 以及表单提交，保持 Method、Body、Cookie 和 Set-Cookie 头，实现完整的登录和写操作。
持久化：预览配置（前端端口 + 后端端口）存储在 ${DSH_HOME:-~/.dsh}/preview-plugin.json，重启后自动恢复。
安全性：代理仅针对 127.0.0.1，iframe 沙箱属性为 allow-scripts allow-same-origin allow-forms allow-popups。

注意事项¶

非配置 URL 跳转：浏览器原生的 location.href、location.assign 和 location.replace 无法被脚本拦截。插件会检测到这些跳转并尝试将路径重载回代理规则下，但应用内部应使用相对路径或 import.meta.env.BASE_URL 来构建 URL。
端口限制：端口验证仅允许 1 到 5 位数字。
权限：插件以 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。

结尾¶

该插件为 DSH 提供了便捷的开发预览能力，相关资源可在 GitHub 上查看：https://github.com/RaulLazaro/dsh-preview-plugin