实时预览 RaulLazaro/dsh-preview-plugin

DSH 预览插件

DeepSeek Harness 的实时预览标签页——通过透明 SPA 代理将任意开发服务器嵌入 iframe。

功能特性

- 基于路径的 SPA 代理：/preview/:port/ 重写所有路由，使嵌入的应用如同从 DSH 主机提供服务一样正常工作
- 可编辑的 URL 栏：输入端口、路径、代理路径或开发服务器 URL，即可将预览移动到任意位置；该栏会跟随页面内点击的链接
- 多应用 monorepo 支持：配置后端端口，通过同一 iframe 代理 API 调用（例如 Astro 前端 + Payload CMS 后端）
- 智能路由：静态资源（JS、CSS、图片）直接代理；SPA 导航提供根 HTML，由客户端路由器处理路由
- 片段链接安全：#section 链接在页面内跳转，而不是重新加载站点根路径，且加载后渲染的锚点仍可到达
- 根相对资源可用：/assets/photo.png、srcset 和 poster 也会被重写，因此图片和懒加载样式表能够加载，而不会针对 DSH 主机返回 404
- 绝对 URL 重写：拦截 fetch() 和 XMLHttpRequest.open()，重写相对和绝对 URL（例如 http://localhost:3001/api/... → /preview/3001/api/...）
- 真实 API 流量：方法、请求体、cookie 和 Set-Cookie 均被转发，因此嵌入的应用可以登录、提交表单并使用 PUT/PATCH/DELETE——而不仅仅是提供页面
- Agent 工具：set_preview_port 工具让 agent 在启动开发服务器时以编程方式配置端口
- 全局或按会话端口：通过 API 全局设置端口，或按对话会话设置端口
- 自动同步：预览标签页轮询主机以获取 agent 设置的端口变更
- 沙箱化 iframe：allow-scripts allow-same-origin allow-forms allow-popups，实现安全嵌入

安装

1. 添加为依赖项

在 DSH Web 配置文件的 package.json 中：

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

2. 添加到 bundles

在配置文件的 package.json 中，将 dsh-preview-plugin 添加到 dsh.profile.bundles 数组：

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

3. 重启 DSH

systemctl restart dsh

使用方法

基本用法（单服务器）

1. 在 VPS 上启动开发服务器（例如 npm run dev -- --host 0.0.0.0 --port 3000）
2. 在 DSH Web GUI 中打开 Preview 标签页
3. 在 URL 字段中输入端口（例如 3000），然后点击 Go

该字段随后会切换为正在显示的页面（例如 /preview/3000/laptops?page=2#specs），因此你可以随时编辑它并按 Enter 加载其他内容。

导航

URL 字段接受以下所有形式：

| 你输入的内容 | 加载的内容 |
| 4321 | 端口 4321，根页面 |
| 4321/laptops | 端口 4321，/laptops |
| /laptops?page=2 | 当前所用端口上的该路径 |
| laptops | 与 /laptops 相同 |
| ?page=2 / #specs | 带该查询/片段的当前页面 |
| /preview/4321/laptops | 一个代理路径，原样使用 |
| http://localhost:4321/laptops | 开发服务器 URL |

非本地 URL 会被拒绝（代理只能访问 127.0.0.1）。↻ 重新加载当前显示的页面，↗ 在独立的浏览器标签页中打开它。

多应用 monorepo

1. 启动两个服务器：后端（例如 Payload CMS）
cd apps/backend && pnpm dev # 端口 3001

前端（例如 Astro）
cd apps/web && pnpm dev # 端口 4321

2. 打开 Preview 标签页
3. 在 URL 中输入 4321，在 Backend 中输入 3001（多个用逗号分隔）
4. 点击 Go —— 对 http://localhost:3001/api/... 的 API 调用会自动通过 /preview/3001/api/... 代理

Agent 工具

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

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

这会自动更新拦截器脚本和客户端 UI。

API

| 方法 | 端点 | 描述 |
| GET | /api/preview-port | 获取当前的全局端口和后端端口 |
| GET | /api/preview-port?sessionId= | 获取某个会话的端口（回退到全局） |
| POST | /api/preview-port | 设置全局端口（{ "port": 4321, "backendPorts": [3001] }） |
| POST | /api/preview-port?sessionId= | 为某个会话设置端口 |

工作原理

1. 宿主在 DSH Web 服务器上注册三个路由：
- /api/preview-port —— 端口管理
- /preview/:port/ —— 透明代理
2. 静态资源（带 .js、.css、.png 等扩展名的文件）直接从请求的路径代理
3. SPA 导航（所有其他路径）从开发服务器提供根 HTML，因此由客户端路由器处理路由
4. 对于 HTML 响应，它会注入：
- 用于相对 URL 解析
- 一个拦截器脚本，它会：
- 自行处理片段链接（#section）：有了 标签，它们否则会解析为 /preview/:port/#section，这是一个不同的路径，会重新加载站点根而不是在页面内跳转。稍后出现的锚点目标（SPA 区块）会重试几秒钟。
- 重写 fetch() 和 XMLHttpRequest.open() URL（相对、绝对前端和绝对后端）
- 重写由 JS 添加的节点上的根相对资源 URL（src、srcset、poster、data-src 以及资源 ）—— 标签只影响真正相对的 URL，因此 "/assets/x.png" 否则会从 DSH 宿主获取
5. 初始 HTML 中的资源 URL 在页面发送前会在服务器端重写
6. 请求保留其方法、标头和正文，并且 Set-Cookie 会返回，因此会话和写入在预览内可以正常工作
7. 对于非 HTML 响应，它会直接流式传输响应

测试

pnpm install
pnpm test
node --test 运行三个测试套件：

| 套件 | 覆盖内容 |
| test/client-helpers.test.mjs | URL/端口解析（resolveTarget）和代理路径辅助函数 |
| test/preview-view.test.mjs | 使用真实 React 和 happy-dom 的预览标签页组件 |
| test/preview-proxy.test.mjs | 使用 Playwright 针对固定站点进行的端到端代理测试（当 Chromium 不可用时跳过） |

安全说明

- 代理仅针对 127.0.0.1 —— 不可能发生外部 SSRF
- iframe 使用 allow-scripts allow-same-origin allow-forms allow-popups 进行沙箱隔离
- 端口验证仅允许 1–5 位数字
- 后端端口经过验证并按前端端口存储
- 为方便本地开发设置了 CORS 头

许可证

MIT