前言¶
在 DSH Web UI 里修改代码时，经常需要同时看项目运行结果和工作区文件。@dsh-external/dsh-web-preview-float 提供两个独立悬浮窗：预览 iframe 与代码文件树。它通过官方扩展点挂载，不改 DSH 核心。
这是什么¶
@dsh-external/dsh-web-preview-float 是 DeepSeek Harness（DSH）Web UI 的悬浮预览插件，由 WJNCT55555 维护。当前版本为 0.1.0，许可证为 MIT。GitHub 仓库为 https://github.com/WJNCT55555/dsh-web-preview-float。
它提供两个可拖拽、可拉伸、可缩小的独立悬浮窗：
- 预览窗：使用
iframe直连项目 dev server。 - 代码窗：提供工作区文件树和代码内容查看/编辑。
插件依赖官方扩展点 ctx.webServer、ctx.fs、ctx.sandboxPolicy 和自包含 DOM portal，不改 DSH 核心。
核心功能¶
预览窗¶
预览窗使用 iframe 加载项目 dev server。URL 会自动从项目 package.json 脚本探测，常见映射如下：
Vite→5173
Next/CRA→3000
Astro→4321
如果探测结果不适合当前项目，可以手动修改 URL。
窗口控制支持：
- 常用宽高比预设：
16:9 / 4:3 / 3:2 / 21:9 / 9:16 / 9:18 / 9:19.5 - 锁定比例，使手动拉伸时保持比例
- 直接输入
宽×高自定义尺寸 - 常用分辨率预设：
1920×1080 / 1366×768 / 390×844等 - 放大/还原，超出屏幕时自动缩放适配
代码窗¶
代码窗提供工作区文件树，支持懒加载目录，点击文件查看内容。也可以直接编辑：点击「编辑」进入编辑态，修改后点击「保存」或按 Ctrl+S 确认写入。
保存时会弹出确认，确认后写入文件，并记录 web-preview/code-edit 会话事件到 DSH 日志。当前代码窗为纯文本显示，语法高亮未做。
对于二进制或超大文件（>256KB），会提示文件过大；写操作限制在 1MB 内。
窗口状态¶
两个悬浮窗标题栏都有放大/还原按钮，可一键放大到贴合屏幕。最小化成胶囊后也可以直接拖动。悬浮窗位置/大小状态保存在内存中，刷新后回到默认位置。
安装与启用¶
README 给出的启用方式是作为 profile 的 patch 层安装。插件自带的 cordis.patch.yml 会插入以下配置：
- id: dsh-web-preview-float
name: '@dsh-external/dsh-web-preview-float'
安装后重启 DSH Web：
dsh web
浏览器里会出现两个悬浮窗。
本地开发¶
如果需要本地开发，先执行：
pnpm install
pnpm run typecheck
pnpm run test
pnpm run build
构建会产出 lib/index.js（node 半）和 lib/client.js（浏览器半）。
本地开发依赖 @deepseek-ai/cordis。它是 vendored 包，不在 npm 上；package.json 的 devDependencies 使用 link: 指向 harness checkout 的 vendor/cordis。
peerDependencies 声明如下：
{
"@deepseek-ai/cordis": "^4.0.1-rc.1",
"react": "^18.2.0",
"react-dom": "^18.2.0"
}
典型用法¶
1、安装后重启 dsh web，浏览器里会出现两个悬浮窗。
2、在预览窗中确认 URL。URL 会自动从项目 package.json 脚本探测（Vite→5173、Next/CRA→3000、Astro→4321），也可以手改。
3、在代码窗中点击文件查看内容；点击「编辑」进入编辑态，修改后点击「保存」或按 Ctrl+S 确认写入。
4、需要调整视图时，使用标题栏的放大/还原按钮，或把窗口最小化成胶囊后拖动。
5、预览窗可选择宽高比预设（如 16:9、9:16）或分辨率预设（如 1920×1080、390×844），也可以直接输入宽×高。
适用场景与注意¶
适合在 DSH Web UI 里边改代码边看 dev server 页面效果，同时快速浏览工作区文件的场景。
插件会用到 ctx.webServer、ctx.fs、ctx.sandboxPolicy 等官方扩展点，并且代码窗保存会写入项目文件。因此安装前应检查源码和许可证，并确认你信任当前项目与当前 DSH 进程权限。
当前版本为 0.1.0，语法高亮未做，悬浮窗位置/大小状态不会跨刷新保留。
