dsh-preview-plugin
DSH 的实时预览标签页 — 将任意开发服务器嵌入 iframe，并支持 SPA 代理和多应用 monorepo
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:RaulLazaro/dsh-preview-plugin#4c0e42dab69dc18d0ee798f42df9bac6171d8c0dPreview Plugin 以 dsh-preview-plugin 发布，当前版本为 1.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Live preview tab for DeepSeek Harness — embed any dev server in an iframe with transparent SPA proxying.
/preview/:port/* rewrites all routes so the embedded app works as if served from the DSH host#section links jump inside the page instead of reloading the site root, and anchors rendered after load are still reached/assets/photo.png, srcset and poster are rewritten too, so images and lazy-loaded stylesheets load instead of 404ing against the DSH hostfetch() and XMLHttpRequest.open() to rewrite both relative and absolute URLs (e.g. http://localhost:3001/api/... → /preview/3001/api/...)Set-Cookie are forwarded, so the embedded app can log in, submit forms and use PUT/PATCH/DELETE — not just serve pageshistory.pushState, window.open and links that open a new tab keep the proxy prefix; an app that assigns location.href (which no script can intercept) is brought back instead of leaving you on the DSH app$DSH_HOME/preview-plugin.json and restored when DSH starts againset_preview_port tool lets the agent configure ports programmatically when starting dev serversallow-scripts allow-same-origin allow-forms allow-popups for secure embeddingIn your DSH web profile's package.json:
{
"dependencies": {
"dsh-preview-plugin": "file:~/workspace/dsh-preview-plugin"
}
}
In your profile's package.json, add dsh-preview-plugin to the dsh.profile.bundles array:
{
"dsh": {
"profile": {
"bundles": [
"...",
"dsh-preview-plugin"
]
}
}
}
systemctl restart dsh
npm run dev -- --host 0.0.0.0 --port 3000)3000) in the URL field and click GoThe field then switches to the page being shown (e.g. /preview/3000/laptops?page=2#specs),
so you can edit it at any time and press Enter to load something else.
The URL field accepts all of these:
| You type | It loads |
|---|---|
4321 | port 4321, root page |
4321/laptops | port 4321, /laptops |
/laptops?page=2 | that path on the port already in use |
laptops | same as /laptops |
?page=2 / #specs | the current page with that query/fragment |
/preview/4321/laptops | a proxy path, as-is |
http://localhost:4321/laptops | the dev-server URL |
Non-local URLs are rejected (the proxy only reaches 127.0.0.1). ↻ reloads the
page currently shown, ↗ opens it in a browser tab of its own.
Start both servers:
# Backend (e.g. Payload CMS)
cd apps/backend && pnpm dev # port 3001
# Frontend (e.g. Astro)
cd apps/web && pnpm dev # port 4321
Open the Preview tab
Type 4321 in URL and 3001 in Backend (comma-separated for multiple)
Click Go — API calls to http://localhost:3001/api/... are automatically proxied through /preview/3001/api/...
The agent can configure ports programmatically using the set_preview_port tool:
set_preview_port(port: 4321, backendPorts: [3001])
This updates the interceptor script and client UI automatically.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/preview-port | Get the current global port and backend ports |
GET | /api/preview-port?sessionId=<id> | Get ports for a session (falls back to global) |
POST | /api/preview-port | Set global ports ({ "port": 4321, "backendPorts": [3001] }) |
POST | /api/preview-port?sessionId=<id> | Set ports for a session |
/api/preview-port — port management/preview/:port/* — transparent proxy.js, .css, .png) are proxied directly from the requested path<base href="/preview/:port/"> for relative URL resolution#section) itself: with a <base> tag they would otherwise
resolve to /preview/:port/#section, a different path, and reload the site root
instead of jumping inside the page. Targets that appear later (SPA sections) are
retried for a few seconds.fetch() and XMLHttpRequest.open() URLs (relative, absolute frontend, and absolute backend)src, srcset, poster, data-src, and
resource <link href>) on nodes added by JS — a <base> tag only affects truly
relative URLs, so "/assets/x.png" would otherwise be fetched from the DSH hostSet-Cookie comes back, so
sessions and writes work inside the previewThe preview config (frontend port + backend ports) is stored in
${DSH_HOME:-~/.dsh}/preview-plugin.json, so it survives a DSH restart and is shared by
every session. Deleting the file simply resets it; a corrupt file is ignored.
location.href = "/…", location.assign() and location.replace() cannot be
intercepted: browsers install them as non-configurable own properties of the location
object ([LegacyUnforgeable]). The preview tab notices the escape and reloads that path
under the proxy, but an app that wants a clean URL should build it from its own base
(e.g. Astro's import.meta.env.BASE_URL) or use a relative path.
pnpm install
pnpm test
node --test runs three suites:
| Suite | What it covers |
|---|---|
test/client-helpers.test.mjs | URL/port parsing (resolveTarget) and proxy-path helpers |
test/preview-view.test.mjs | The Preview tab component with real React and happy-dom |
test/preview-proxy.test.mjs | The proxy end-to-end against a fixture site with Playwright (skipped when Chromium is unavailable) |
127.0.0.1 — no external SSRF possibleallow-scripts allow-same-origin allow-forms allow-popupsMIT