前言¶
DeepSeek Harness (DSH) 采用了插件化架构。在开发智能体或管理会话时，开发者经常需要查看项目结构、编辑配置文件或直接打开本地资源。原生环境往往缺乏健壮的文件浏览界面。devacc8/dsh-file-explorer 旨在解决这一需求，它是一个经过加固的文件管理工具，为 DSH 提供了安全、可控的文件访问能力。
插件定位¶
该插件是 joejojoking-cloud/dsh-file-explorer 的 vendored（打包）和 hardened（加固）fork。上游代码已冻结，该版本在此基础上增加了安全修复、全英文 UI 以及与 Harness 主题匹配的面板背景。它作为 DSH 的全局文件管理器工作，在每一个会话中为用户提供一个位于页面右侧的文件树面板。
布局与交互¶
插件在页面右侧打开一个名为 shell.overlay 的面板。
- 尺寸调整：面板宽度可通过拖动左侧边缘调整，范围在 260px 至 900px 之间。
- 独立折叠：文件树和预览区域拥有独立的折叠手柄（位于各自左侧边缘）。
- 折叠树形视图会保持预览区域并将其吸附到右侧边缘。
- 折叠预览区域会保持所有标签页，重新打开时会恢复。
- 双击聊天区域：双击聊天区域可以同时折叠左右两侧的面板，并应用“项目筛选”功能。此时，标签页中仅保留位于当前项目文件夹内的文件，其余标签页会被关闭；重新展开面板后，筛选状态依然保留。
预览与编辑¶
- 标签式预览：支持浏览器风格的标签页，切换时不重新加载文件内容。点击背景标签会滚动标签栏，点击当前标签则切换内容。
- 语法高亮：支持 Markdown、JSON、YAML、JS、TS、Python、C、C++、Java、Go、Rust、Shell、SQL、TOML、INI、CSS、HTML 等多种语法的文件预览。
- 面板内编辑：点击编辑图标可将预览切换为可编辑文本框，保存操作会将内容写入磁盘。再次点击预览文件可关闭对应标签页。
- 限制：文件大小超过 1 MB 时，预览功能不支持。
功能细节¶
- 头部工具栏：包含“Files”标签及多个功能图标：
- VS Code：点击可打开当前整个工作区。
- 系统文件管理器：根据当前选中状态操作。选中目录则直接打开，选中文件则高亮显示并定位到所在文件夹，未选中则打开项目根目录。
- 展开/折叠全部：控制文件树的显示状态。
- 刷新：更新文件列表。
- 折叠树形视图：仅折叠左侧树形，保留右侧预览。
- 搜索功能：搜索框支持对工作区进行递归扫描，自动排除
.git和node_modules目录。搜索结果上限为 300 个匹配项。 - 文件树：默认展开根目录，支持懒加载（点击展开目录），支持点击切换展开/折叠状态。
安装与启用¶
安装插件需使用官方命令。安装完成后需要重启 Harness。
dsh plugin --profile web add <path-to-this-package-or-npm-name>
安装生效后，插件会挂载到 /plugins/file-explorer/* 路径下，并在会话头部提供文件切换开关。
开发与维护¶
- 构建说明：客户端捆绑包 (
lib/client.js) 是手工修补的，因为上游的构建工具链无法独立安装（其声明的 peer 依赖包含未发布的包）。主机端则通过tsc机械生成。 - 代码规范：
lib/目录下的产物为生成文件，请勿直接编辑。所有逻辑和样式修改应在src/目录中进行。历史经验表明，直接编辑lib/下的文件会导致构建覆盖修改，并可能引发语法错误（如 CSS 模板字符串中的反引号问题）。 - 补丁机制：使用
cordis.patch.yml文件将插件注入到宿主配置中。
适用场景与注意事项¶
- 该插件以当前 DSH 进程的权限运行，请确保安装来源可信，并检查许可证。
- 由于是上游冻结的 fork，若遇到上游修复的问题，需等待维护者自行合并或提交 PR。
