前言¶

DeepSeek Harness（DSH）Web 右侧预览已经能看文本、代码、图片、PDF 以及部分 Office 格式，但会话工作区之外的文件、大体积二进制、以及「下载到本机」「上传」「打包」等操作，在默认产品里要么没有入口，要么受 /api/file 内联与字节上限约束。做智能体或本地开发时，经常需要在同一套已登录的 Web 界面里直接浏览宿主机目录、改个小配置、拖文件进去，而不是再开一套 FTP 或远程桌面。

下面介绍社区插件 dsh-local-files（维护者 DeveloperYe），它通过 ctx.webServer 在同源、同一 Web 端口上注册路由，复用 dsh-access-gate 的认证模型，不另开端口、不新起独立服务，零第三方运行时依赖。

这是什么¶

dsh-local-files 是 DSH 的客户端类插件：在浏览器里完成本机文件的浏览、预览、下载、上传、复制粘贴、在线编辑（文本类）、新建、重命名与删除。分类上属于「客户端」——除独立文件管理页 /-/files 外，还会在 DSH 右侧文档预览、工作区文件树等位置注入「下载」「文件管理器」等入口。

插件在 SkillHub 目录 与 GitHub 仓库 发布；仓库代码为 MIT 许可，内置 mammoth、SheetJS 等浏览器库的许可见仓库内 THIRD-PARTY-NOTICES.md 与 lib/vendor/NOTICE.md。

相对默认 DSH 补了哪些洞¶

资料里归纳的缺口与对应能力如下：

1. 产品侧没有通用的「下载到本机」；本插件提供单文件下载、目录 Zip、勾选打包下载，ZIP 在 Host 侧流式生成。
2. 文件树与预览默认只认会话工作区（workspaceFiles.list 限定 workspace root）；本插件支持按配置的根目录白名单整盘浏览（未配置根时自动枚举盘符）。
3. zip 等无预览渲染器的类型原先只能看到「不支持预览」；本插件对不可预览类型提供明显下载入口，并在 client 半边给空态加「下载到本机 / 文件管理器」。
4. 没有上传、复制粘贴、打包下载入口；本插件支持拖拽上传、工具栏上传、跨目录复制粘贴（Ctrl+C / Ctrl+V），以及 xlsx 单元格编辑后另存为副本等。

0.2.0 还修复了聊天消息里带 .. 的相对路径链接无法被右侧栏认领的问题：在打开资源前归一化路径，仍在工作区内则用工作区相对路径，否则用绝对路径，避免 sidebarRight: no registered tab type claims 类错误。

核心功能¶

文件管理页与导航¶

访问 http://<你的 DSH 入口>/-/files（须在 dsh-access-gate 密码门内，或从右侧预览/文件树按钮跳转）。默认首页取配置项 home，未配置时落到第一个盘符；界面提供首页、盘符切换、面包屑与绝对路径跳转。

预览（右侧面板）¶

常见类型行为包括：图片内联；PDF 内嵌阅读器；音视频 <video> / <audio> 且支持 Range；文本/代码等宽预览（默认 512 KiB 上限，可配 maxTextBytes）；Markdown 客户端安全渲染；JSON 美化；CSV/TSV 表格；HTML 在禁用脚本的 sandbox iframe 中渲染并可切源码。

Office 与表格：

• docx：客户端懒加载 mammoth 快速预览，并可选用 Host officeToPdf 做「LibreOffice 精排」转 PDF；不支持在线改 docx 正文（版式会丢）。
• xlsx / xls / xlsm / ods：懒加载 SheetJS，多工作表与行列上限保护；可「编辑单元格」后另存为新 xlsx（公式/合并单元格等部分保留，图表、透视表、条件格式、VBA 等会丢失，界面有提示）。
• doc / ppt / pptx：走 Host officeToPdf 转 PDF 预览；宿主未挂载服务时 501 并提示下载。

超过内联预览默认 64 MiB（maxPreviewBytes）时，不走客户端解析，提示下载。其它二进制（zip、7z、exe 等）提供「下载到本机」。

下载、上传与目录操作¶

• 下载：行级「下载」、目录行「Zip」、工具栏对勾选项或当前目录「打包下载」。
• 上传：工具栏选择或拖入列表，流式落盘（.part 后原子 rename），同名自动 name (2).ext，默认单文件上限 4 GiB。
• 复制/粘贴：勾选后复制，到目标目录粘贴；目录递归复制，默认不覆盖同名，禁止复制到自身子目录。
• 新建 / 重命名 / 删除：单段文件名，含 \ / 拒绝；删除默认移入 trashDir（默认 ~/.dsh-local-files-trash/<时间戳>/），根目录不可删。

在线编辑（文本类）¶

预览工具条「编辑」→ 保存走 POST /-/files/api/write，带读取时 mtimeMs + size 的冲突检测（409 不覆盖）、同目录临时文件再 rename 的原子写；默认单次保存上限 5 MiB（maxWriteBytes）。

与 DSH 主界面集成（client 半边）¶

• 右侧文档预览头部增加「下载」。
• 不可预览空态增加「下载到本机」「文件管理器」。
• 工作区文件树头部增加「文件管理器」，打开 /-/files?path=<当前目录>。

Host 侧主要路由前缀为 /-/files 与 /-/files/api/*（列表、文本、raw、download、zip、office、upload、copy、write、create、rename、delete 等），详见仓库 README 路由表。

安装与启用¶

需要 Node.js ≥ 22，peer 依赖 @deepseek-ai/cordis ^4.0.1。在已安装 DSH CLI 的机器上，按资料原文任选一种方式：

# 从 npm 安装（发布产物已预置：dsh-local-files@0.1.0）
dsh plugin --profile web add dsh-local-files

# 从 GitHub 安装（DSH ≥ 0.2.0-rc.2）
dsh plugin --profile web add github:DeveloperYe/dsh-local-files

# 从本地目录安装（开发用）
dsh plugin --profile web add link:C:/path/to/dsh-local-files

卸载：

dsh plugin --profile web remove dsh-local-files

安装后浏览器打开 /-/files，或从右侧预览/文件树入口进入。npm 包与 git 安装内容一致（含 cordis.patch.yml 与 vendored 渲染器）。

配置¶

在 cordis.patch.yml 中可调整插件 local-files 的 config，例如：

- id: local-files
  config:
    home: 'D:\workspace'      # 打开时的默认目录（留空 = 第一个盘符）
    roots: []                 # 留空 = 自动枚举所有盘符；也可写 ['C:\\', 'D:\\data']
    maxTextBytes: 524288      # 文本预览上限（512 KiB）
    maxPreviewBytes: 67108864 # 内联预览上限（64 MiB）
    maxUploadBytes: 4294967296 # 单文件上传上限（4 GiB）
    maxCopyEntries: 20000     # 一次复制/移动的条目上限
    maxWriteBytes: 5242880    # 在线保存内容上限（5 MiB）
    trashDir: 'C:\Users\<you>\.dsh-local-files-trash'  # 删除回收目录

典型用法¶

1. 安装插件并确保 Web 配置启用了 dsh-access-gate 访问密码。
2. 登录 DSH Web 后打开 /-/files，用盘符与面包屑进入目标目录。
3. 需要把本地文件放进某目录：拖入列表或使用工具栏「上传」。
4. 需要改 json / md / 代码：选中文件预览 →「编辑」→ Ctrl+S 保存；若他人已改过文件，按提示重新加载后再写。
5. 在聊天里点击工作区相对路径或略超出工作区的链接时，由 client 归一化后仍可打开预览或文件管理器，而不是标签注册失败。
6. 在 DSH 自带预览里看 docx/xlsx：用插件增强的预览；大文件或密码保护工作簿按界面提示下载处理。

仓库提供冒烟测试（需在插件目录执行）：

node test\smoke.mjs         # Host 路由
node test\client-smoke.mjs  # Client 半边

适用场景与注意¶

适合：已在用 DSH Web、希望在同一认证边界内管理本机目录的开发者；需要补下载/上传/打包、工作区外路径浏览、Office 与表格浏览器预览的场景。

安全与权限（务必阅读 README 安全节）：

• 插件逻辑以当前 dsh 进程权限访问文件系统；安装前应自行审阅 源码 与许可证。
• 信任模型与官方 /api 一致：依赖 dsh-access-gate 在认证通过后将 Host 改写为 127.0.0.1；未认证远程请求 403。未启用门禁时，写操作对能访问端口的人相当于整盘暴露，部署时必须同时启用访问密码。
• 路径经 realpath 与白名单根校验，.. 穿越无效；写操作有冲突检测、回收站删除与单段文件名限制。

SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件星标与热度以各站点当时数据为准（目录线索为 0 star）。

结尾¶

dsh-local-files 把 DSH Web 补成「同源、已认证环境下的本机文件管理器」：不额外开端口，用白名单根与门禁模型约束暴露面，并和右侧预览、文件树打通。进一步了解与提 issue 可访问 SkillHub 插件页 与 GitHub：DeveloperYe/dsh-local-files。