前言¶
在 DeepSeek Harness（DSH）里做智能体或插件开发时，模型和工具往往只能间接接触工作区里的路径：对话里引用文件、预览内容、整理目录，常常要来回切终端或外部编辑器。DSH 社区把能力拆成插件；dsh-folderead 由维护者 nipheryang 发布，归类为客户端插件，在 Web 界面右侧栏提供树形文件管理，并支持把工作区外的目录附加进来，让模型与你都能直接读写原文件（不复制）。社区目录页见 skillhub.cn/plugins/nipheryang/dsh-folderead，源码与说明在 GitHub。需说明：这是 DSH 插件，不是独立 npm 库；须通过 DSH 插件装载机制运行，脱离 DSH 无法启动。
这是什么¶
dsh-folderead（npm 包名 dsh-folderead，当前资料中版本 0.2.0）是 DeepSeek Harness 的右侧栏文件管理插件。它依赖宿主提供的 webServer、workspaceRegistry、fs、sandboxPolicy、systemPrompt 五项服务，在浏览器侧注入 React UI（经 @deepseek-ai/dsh-client-ui-sidebar-right 等插槽挂载）。
一句话定位：在工作区里浏览、预览、编辑、整理文件，也可附加工作区外目录，并把文件或文件夹引用进对话输入框。
核心功能¶
下面介绍 README 中已列出的能力，均可在仓库说明中核对。
浏览与切换¶
- 树形浏览：目录就地展开，懒加载并按层缓存；悬停与按下时预热下一层。
- 多位置切换：位置胶囊在工作区与已附加目录之间切换，重名目录以父级消歧。
工作区外目录¶
- 附加目录：由你在原生目录选择器里亲手选定；其中文件保持原位，插件直接操作原文件，不复制。
- 附加即授权：附加一个目录，等于同时把该目录的读写权限交给模型；界面上会如实标注；沙箱换根由插件拦截层接管
tools/execute上的write/edit/bash/pwsh（逻辑移植自dsh-multi-folder@0.3.3，见包内LICENSE.dsh-multi-folder.txt）。
对话与面板¶
- 引用到对话：把文件或文件夹作为引用放进对话输入框。
- 面板内预览：Markdown（含 GFM 表格）、代码、图片、PDF。PDF 由随包自带的
pdfjs-dist（vendor/pdfjs/，版本6.3.289）渲染，不依赖宿主内置阅读器。 - 面板内编辑：带 mtime/size 冲突检查；文件在外部被截断时不给编辑入口，避免保存把内容写短。
整理与系统集成¶
- 整理：新建、移动、重命名、导入、导出、删除。删除移入废纸篓，不永久删除（macOS 上依赖
osascript驱动访达；非 macOS 删除返回trash-unsupported，同样不退回rm）。 - 在访达中显示：优先走宿主官方通道，不可用时退回
open -R（主要面向 macOS）。
权限与安全边界¶
这个插件能写文件，安装前建议读完 README 中的边界说明。
- 两类可写位置：已注册的工作区根，以及该工作区已附加的目录；除此之外一律拒绝。
- 路径校验：读写目标先做词法包含检查，再用
realpath解析最近的已存在祖先，避免软链接逃出所在位置。 - HTTP 路由：只服务本机，通过 socket 地址、
Host头、同源标记三重校验，只接受本机回环请求。 - 导出：目标目录须由原生选择器选定，且请求带
confirmOutside: true。 - 删除：唯一删除路径是移入废纸篓，逐项执行，任一项失败立刻中止；没有永久删除分支。
安装与启用¶
需要 DSH 0.2.0-rc.2 或更新，Node.js 20+。
先做 CLI 或 Desktop 二选一安装，再重启 Web 或应用。
从 npm 安装：
dsh plugin add dsh-folderead
或从 GitHub 安装：
dsh plugin add github:nipheryang/dsh-folderead
DSH Desktop 也可在应用内 Settings → Plugins 安装（该 profile 归应用插件管理器所有，CLI 在应用运行时不会改动它）。装完后重启 dsh web 或应用。
典型用法¶
资料中没有单独的「教程脚本」，用法即右侧栏内的操作流程，与 README 能力一一对应：
- 打开 DSH Web 或 Desktop，确认插件已加载，在右侧栏看到文件树。
- 展开工作区根目录，点击文件进行预览；可编辑的类型在面板内修改并保存（注意外部修改时的冲突提示）。
- 需要模型读写项目外目录时，用界面附加目录（原生选择器），确认权限提示后再让模型通过工具访问该路径下的原文件。
- 将文件或文件夹拖入/引用到对话输入框，作为上下文引用。
- 需要整理时，在树内新建、移动、重命名；导出时在原生选择器里指定目标并确认；在 macOS 上删除会进废纸篓。
非 macOS 平台可浏览、预览、编辑、引用，但删除不可用。
适用场景与注意¶
适合谁：经常在 DSH 里改工作区文件、希望少切窗口的开发者；需要把仓库外配置或数据目录「挂」进同一工作区、且接受模型对该目录读写授权的场景。
运行与信任：插件以当前 DSH 进程权限运行，安装前应查看 源码仓库 与 MIT 许可证。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系，不宜当作官方应用商店。
平台：主要面向 macOS（废纸篓、访达集成）；其他系统仍可使用除删除以外的大部分能力。
开发与许可¶
源码为纯 JavaScript，无构建步骤，运行时依赖 Node 内置模块。维护者提供多条 selftest-*.mjs 自测入口（见仓库 README「开发」一节）。第三方 PDF 渲染与多目录拦截逻辑的来源与许可证在 README「第三方」中列出。
经过上面的步骤，若你已安装 DSH 并需要右侧栏统一管理文件与附加目录，可按本文安装命令启用 dsh-folderead，并在使用前理解其写文件边界与附加目录的授权含义。
