Dawn388887/dsh-fileview

dsh-fileview

⚠️ 已弃用（2026-09-13）：DSH 0.1.5 起在 Web 侧边栏内置了远程文件预览（Markdown、代码、HTML、PDF、图片），并可直接预览模型交付的文件，本插件的核心场景已被官方内置功能取代，不再维护。最后适配版本：DSH 0.1.2。本仓库已归档，仅供历史参考。

DeepSeek Harness（DSH）插件：让远程浏览器（通过 LAN 或 VPN 访问 DSH Web 的设备）直接在 GUI 中查看、编辑和浏览工作区文件。

为什么需要它

DSH 将原生工作区文件打开器保留为仅回环可用的特权操作。DSH 0.1.2 的文件链接调用 ctx.remote.session.openWorkspacePath({ path })；远程页面无法借此在远程设备上启动宿主机桌面程序。本插件在非回环页面包装这个 Remote 方法，通过带路径白名单的 HTTP 端点，在浏览器浮层中打开目标路径；回环页面仍调用原生系统打开器。

功能

- 远程页面点击文件链接 → 打开 GUI 内浮层查看器（全文本、可滚动、可选中、可编辑、可保存，触摸友好）
- 左缘「文件」把手 → 目录浏览（多根切换、面包屑、上一级）
- 回环页面（本机）保持系统默认程序打开，行为不变
- 编码阶梯：BOM（UTF-8 / UTF-16LE / UTF-16BE）→ UTF-8 → GB18030；保存时保留原编码、BOM 与换行符（CRLF/LF）
- 二进制文件：图片（PNG/JPG/GIF/WebP/BMP）直接显示，其余给出提示
- 大文件（> 2 MB）分页只读浏览
- 原子保存（临时文件 + rename）

客户端接管原理

DSH 0.1.2 将 remote.session.openWorkspacePath 安装为一个可配置、仅 getter 的自有属性，普通赋值不能替换它。因此客户端先保存完整属性描述符，再通过 Object.defineProperty 安装包装函数。

- 远程页面收到合法的 { path } 请求时，在 GUI 查看器中打开文件，并返回成功的 Remote 结果。
- 回环页面把原始请求和 AbortSignal 原样转交给原生方法。
- Cordis 停止或更新插件时，清理函数恢复完全相同的原始描述符。

用于获得这些 API 的客户端依赖已在 package.json 中声明为 @deepseek-ai/dsh-api-session-controller 和 @deepseek-ai/dsh-client-connection。

安装与配置

config.roots 是必填的读写路径白名单（绝对目录；子路径放行，其余返回 403）。config.writeRoots 可选，用于把保存权限收窄到部分根目录。未配置 root 时，Host 插件安全地不注册任何文件路由；不会回退到机器专属目录，也不会开放整块磁盘。

- insert:
- id: fileview
name: dsh-fileview
inject: [webServer]   # 等待 webServer 就绪后再注册路由
config:
roots:
- 'D:\workspace'
- 'C:\Users\me\projects'
writeRoots:          # 可选：仅允许保存到 D:\workspace
- 'D:\workspace'

修改 composition 或 Host 代码后需要重启 dsh web。只修改 client.js 时，根据你的 DSH 安装方式重新构建或重新加载客户端插件，然后刷新页面即可。

安全设计

- 同源守卫：浏览器请求带 Origin 时必须与请求到达的 Host 一致（比较 hostname，容忍反向代理改写端口）；无 Origin 调用遵循与 DSH API 层一致的姿势
- 路径白名单：绝对路径 + 大小写不敏感的包含检查；越权和遍历请求返回 403
- 安全的未配置状态：没有 config.roots 就不注册文件路由
- 保存限制：内容上限 6 MB；GBK/GB18030 文件无法无损回写，因此拒绝在线保存并以只读方式打开

兼容性

- v1.1.0 面向 DSH 0.1.2 及其 ctx.remote.session.openWorkspacePath 契约
- DSH 0.1.2 不再使用 v1.0.0 的 workspaces.openPath 接管方式
- 路径语义面向 Windows；编码阶梯依赖 Node.js ICU 的 GB18030 解码能力

测试

node test/fileview-smoke.mjs
node test/fileview-client-test.mjs

- fileview-smoke.mjs：34 项可移植离线 Host 回归（mock req/res、临时夹具、无需服务器），覆盖 meta/file/dir 端点、分页、CRLF 保持、二进制嗅探、白名单/遍历拒绝、同源处理、UTF-8 边界、GB18030 拒存、UTF-16LE/BE 往返、大文件和路由形状。
- fileview-client-test.mjs：可移植离线客户端回归，覆盖 DSH 0.1.2 Remote 描述符包装、远程接管、回环委托和原始描述符精确恢复。

赞助

如果这个插件帮你省了时间或麻烦，欢迎请我喝杯咖啡：

- PayPal：paypal.me/dawn388887

许可

MIT © 2026 Dawn388887