dsh-file-explorer

DeepSeek Harness（DSH）Web UI 的侧边文件浏览器：不离开聊天界面就能浏览工作区文件、预览内容，面板可停靠、可浮动。

✨ 功能特性

• 懒加载目录树：按需展开工作区目录，目录在前、文件带大小；默认隐藏 node_modules、.git 等（可切换显示）
• 文件预览 + 内联编辑：点击文件在面板内预览；文本文件可进入编辑模式（Ctrl+S 保存，带磁盘冲突检测）；超大文件自动截断、二进制文件自动识别；预览区高度可拖动
• IDE 式右键菜单：树中右键即可——新建文件（txt / py / md / json / js / ts / html / css 等模板）、新建文件夹、重命名、复制、粘贴（同名自动加 (1) 后缀）、复制绝对路径 / 相对路径、删除（移入系统回收站）
• 拖放移动：直接把文件 / 文件夹拖到其它目录行（或树空白区）即可移动，跨设备自动复制+删除回退；目标行高亮提示
• 实时刷新：新建 / 重命名 / 粘贴 / 保存 / 删除 / 移动后树即时更新，无需手动刷新
• 跨平台回收站：Windows 系统回收站 / macOS 废纸篓 / Linux XDG 回收站，均带内置回收站兜底（~/.dsh-file-explorer-trash/）
• 工作区自动跟随：切换会话/工作区后约 1 秒内自动切换到对应目录
• 三种停靠模式：右侧（挤压对话栏，不遮挡）/ 中间 / 浮动（自由拖动 + 四边四角缩放）
• 悬浮球：侧边可拖动入口，可随时开关
• 偏好记忆：面板位置/尺寸/停靠模式/预览高度/悬浮球开关全部本地记忆

安装

前置要求

• DSH 0.1.0-rc.6，Windows（路径处理按 Windows 习惯）
• 官方安装方式需要 pnpm（npm install -g pnpm）

官方方式（推荐）

dsh plugin --profile web add github:Zalpha263/dsh-file-explorer

• 发布到 npm 后可直接：dsh plugin --profile web add dsh-file-explorer
• 装完重启 DSH，会话标题栏右侧会出现「📁 文件」按钮
• 升级 / 卸载：dsh plugin --profile web update/remove dsh-file-explorer

- insert:
    - id: file-explorer
      name: dsh-file-explorer

使用说明

打开方式

• 会话标题栏右侧「📁 文件」按钮
• 侧边悬浮球「📁」（点击开关面板；拖动改变位置）

面板操作

预览与编辑

• 点文件 → 预览；预览头部点「编辑」进入编辑模式（仅限文本文件；二进制 / 已截断文件不可编辑）
• 编辑时 Ctrl+S（或「💾 保存」）写盘；「取消」丢弃改动；Esc 退出编辑
• 保存带版本检测：文件在打开期间被外部改动会拒绝保存并提示（避免覆盖他人修改）

拖放移动

• 按住任意文件 / 文件夹行，拖动到目标目录行（或树空白区）松开即移动
• 目标目录高亮提示；拖到自身或子目录会被拒绝；拖回原目录无操作
• 跨设备（不同盘 / 挂载点）移动自动转「复制 + 删除」完成

右键菜单

提示：粘贴到「文件」上 = 粘贴到该文件所在目录；粘贴到目录 / 树空白区 = 粘贴到该目录。 删除后文件可在系统回收站中恢复；删除目录会连同其全部内容一起移入回收站。

卸载

dsh plugin --profile web remove dsh-file-explorer

重启 DSH 后插件不再加载，面板与悬浮球消失，无残留。

常见问题（FAQ）

兼容性

• 目标版本：DSH 0.1.0-rc.6；Windows / macOS / Linux（路径分隔符、大小写敏感、回收站策略均按平台自适应）
• 部分 CSS 选择器（侧边栏宽度探测 .pI_x6G_frame 等）针对该版本的客户端产物编写，DSH 大版本升级后可能需要复核
• Host 半区依赖 dsh 自带的 @deepseek-ai/dsh-typert-protocol（peer 依赖，由 dsh 提供）——不要单独安装该包的独立副本，否则 Remote 桥会失效
• 写操作说明：编辑保存 / 新建 / 重命名 / 复制 / 移动 / 删除由 Host 半区直接通过 Node fs/promises 执行。这是刻意设计——本插件是用户手动操作的文件管理器，与读任意路径的行为对称；但请注意它不受 DSH 的 read-only / workspace-write 策略约束，请勿在不可信环境下使用
• 删除的回收站策略：Windows 用系统回收站（PowerShell）；macOS 用系统废纸篓（Finder / osascript）；Linux 用 gio trash（XDG）；以上不可用时统一回退到插件内置回收站 ~/.dsh-file-explorer-trash/（时间戳命名，防同名覆盖）
• 大目录（如 node_modules）整目录复制 / 跨设备移动会较慢，属正常现象

开发者

• Host 半区（lib/index.js）：FileExplorerService extends TypertRemoteService 注册 fileExplorer 远程服务（fsList / fsRead / fsWrite / fsCreate / fsRename / fsCopy / fsDelete / fsMove / wsRoot / wsList）；Remote 标记通过 markRemote 手动应用（不依赖 Node 装饰器语法）；写操作直接使用 node:fs/promises；删除按平台走 PowerShell / osascript / gio trash，失败落内置回收站；fsMove 处理跨设备（EXDEV）复制+删除回退；assertNoSelfNesting 防目录复制/移动进自身；agent/status + session/event 维护最近活跃工作区
• Client 半区（lib/client.js）：__ModuleLoader__.load 加载；ctx.remote.$mount 自挂载 fileExplorer 命名空间，用 ctx.get("remote.fileExplorer") 调用（返回 {ok, value} 信封统一解包）；零 React hooks（原生 DOM 渲染）；路径拼接 / 相对路径 / 大小写比较按 wsRoot 返回的 platform 自适应
• 改代码后：Client 改动刷新页面即可生效，Host 改动需重启 DSH；无需构建
• 已安装用户升级：dsh plugin --profile web update dsh-file-explorer

版本历史

• v1.5.6：修复浮动面板"打不开"——
  • 根因：浮动模式打开时直接使用保存的位置坐标，未按当前视口夹紧；若保存的位置超出当前窗口（换过窗口尺寸/显示器），面板会在屏幕外打开，表现为"点击无反应"；
  • 修复：applyDock 打开时对保存坐标做视口夹紧（复用拖拽时的 clampFloatPos），窗口 resize 时也自动重新夹紧；
  • 应急恢复（旧数据）：控制台执行 localStorage.removeItem('dsh-file-explorer:pos') 后刷新。
• v1.5.5：面板布局修复——
  • 浮动模式可拖到屏幕最右侧：边界按面板实际宽度计算（原写死 400px，面板拖窄/拖宽后右侧留白或超出屏幕）；
  • 「右侧 / 中间」吸附模式顶部下移（约 76px，避开会话标题栏的「对话 / 轨迹」按钮），不再遮挡顶部 UI。
• v1.5.4：源码复查修复——
  • 修复大文件预览必败：fsRead 改用流式读取（streamText），按字符数截断，>512KB 文件正确显示「已截断」；
  • 修复二进制识别失效：二进制检测统一为底层 FS_NOT_TEXT 信号（原 includes('\0') 是死代码），二进制文件显示「无法预览」而非报错；
  • 切换工作区时若有未保存编辑先弹确认（避免跟随循环静默丢弃编辑）；
  • 复制副本名从 (1) 开始（与文档一致）；重命名/缓存清理大小写比较按平台自适应；toAbsolute 支持 UNC 网络路径；保存后预览 size 即时更新；拖拽增加 document 级兜底清理；移除子菜单死代码，回收站命令统一 runShell 执行器。
• v1.5.3：修复拖放无法落下——onDrop 中先清空了 dragSrcPath 再调用依赖它的合法性校验，导致 drop 永远被拒绝；校验改为接收显式源路径参数。
• v1.5.2：修复拖放高亮判定——高亮改由持续触发的 dragover 维护（不再因行内子元素 enter/leave 抖动而闪烁或难触发），dragleave 只在真正离开行时取消；拖到自身 / 子目录 / 原目录时保持系统禁止光标且不高亮——高亮 = 可以放下，识别一目了然。
• v1.5.1：内置回收站自动清理——条目保留 30 天、最多 200 条（启动时与每次放入后触发），防止垃圾文件长期堆积。
• v1.5.0：跨平台健壮性修复 + 拖放移动——
  • 新增拖放移动：文件/文件夹直接拖入其它目录（含树空白区），目标行高亮；跨设备自动「复制+删除」回退；防拖入自身/子目录；
  • 删除跨平台化：macOS 走系统废纸篓（Finder）、Linux 走 gio trash（XDG），均带内置回收站兜底 ~/.dsh-file-explorer-trash/；
  • 修复 Linux/macOS 路径 bug：客户端路径拼接/相对路径/大小写比较按平台自适应（原硬编码 \ 导致非 Windows 新建、重命名、粘贴、删除全部失效）；
  • 修复 fsCopy 目录复制进自身会无限递归、点文件（.env）复制后丢点前缀；fsRename 增加自嵌套防护；
  • fetchDir 加请求序号防乱序覆盖；删除清理缓存加分隔符边界；菜单禁用项正常渲染文字。
• v1.4.0：删除到回收站 + 实时刷新——
  • 右键菜单新增「删除」（文件 / 目录，确认后 Windows 移入系统回收站，可恢复）；
  • 修复新建 / 重命名 / 粘贴 / 保存后树不实时更新的问题（目录刷新语义修正 + 强制绕过 in-flight 防重入；新建文件夹自动展开）。
• v1.3.0：文件编辑与 IDE 式右键菜单——
  • 预览支持内联编辑（Ctrl+S 保存、磁盘冲突检测、二进制/截断文件不可编辑）；
  • 右键菜单：新建文件（txt/py/md/json/js/ts/html/css 模板）/ 新建文件夹 / 重命名 / 复制 / 粘贴（同名自动加 (1) 后缀）/ 复制绝对与相对路径；
  • Host 新增 fsWrite / fsCreate / fsRename / fsCopy（node:fs/promises 直连，不走沙箱围栏——见「兼容性」）。
• v1.2.0：支持 dsh 官方 bundle 安装（dsh.bundle.patch + 自带 cordis.patch.yml）；@deepseek-ai/dsh-typert-protocol 改为 peerDependency——与 gateway 共享同一模块实例（Remote 标记的 WeakMap 按模块实例隔离，独立副本会导致桥接失效）。
• v1.1.0：v2 架构重写，修复 v1 的加载失败——
  • Client 半区 $mount 自挂载 fileExplorer 命名空间（v1 因 inject: ["remote.fileExplorer"] 等待一个无人挂载的服务而永远 pending）；
  • 命名空间改用 ctx.get("remote.fileExplorer") 访问（属性访问在自挂载场景会抛错并导致面板条目崩溃退役）；
  • Host 半区改用 TypertRemoteService 自动注册（服务 + typertRemote 绑定一步完成）；
  • 补丁注册行重写（此前曾被意外清空导致 Host 半区未加载）。
• v1.0.0：v1 初版（TypertRemote 桥实现）——存在 Client 等待不存在的 remote.fileExplorer 而加载失败的问题，已被 v1.1.0 取代。

License

MIT