dsh-file-explorer

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

✨ 功能特性

• 懒加载目录树：按需展开工作区目录，目录在前、文件带大小；默认隐藏 node_modules、.git 等（可切换显示）
• 树内搜索过滤（v1.9.0）：Ctrl+F / ⌘F 呼出搜索条，即时过滤已加载节点（保留目录层级）；命中子串高亮、↑↓ 键盘导航、Enter 打开、匹配计数与空状态；跟随「显示隐藏」开关
• Markdown 渲染预览（v1.9.0）：.md 文件默认富文本渲染（GFM 表格 / 任务列表 / 删除线、代码块语法高亮 + 一键复制、可折叠标题目录、限宽居中阅读）；渲染 / 源码 / 编辑 三态切换（Ctrl+[ / Ctrl+]），按文件类型记忆上次模式
• IDE 式代码查看（v1.9.0）：代码文件默认高亮 + 行号（服务端 marked + highlight.js 渲染）；自动换行（行号按逻辑行对齐）；单行超长（>2000 字符）截断并标记；≤2000 行高亮、2000~10000 行纯文本行号 + 虚拟化渲染、>4MB 分段「继续加载」不粗暴截断；深浅主题自动切换高亮配色
• 编辑增强（v1.9.0）：编辑视图带行号（与输入同步滚动）、Tab 插入 2 空格缩进、Esc 退出编辑
• 在资源管理器中显示（v1.9.0）：文件 / 目录右键菜单一键在系统文件管理器中定位（Windows 选中 / macOS Finder 显示 / Linux 打开目录）
• 快捷键帮助：按 ? 或点击面板头部 ? 按钮弹出快捷键清单
• 预览 + 内联编辑：点击文件即预览（二进制自动识别）；文本文件可编辑（Ctrl+S 保存、磁盘冲突检测）
• IDE 式右键菜单：新建文件 / 文件夹、重命名、复制粘贴（同名自动加后缀）、复制绝对 / 相对路径、删除到回收站
• 拖放移动：拖到目标目录行或树空白区即移动；跨设备自动「复制 + 删除」回退
• 实时刷新：新建 / 重命名 / 粘贴 / 保存 / 删除 / 移动后树即时更新
• 跨平台回收站：Windows / macOS / Linux 系统回收站，带内置兜底（~/.dsh-file-explorer-trash/）
• 工作区自动跟随：切换会话 / 工作区后约 1 秒内自动切换目录
• 停靠与浮动：右侧 / 中间 / 浮动三种形态（可拖宽、四边四角缩放）——仅独立模式；装有 ui-beautify 时由插件面板统一管理
• ui-beautify 插件面板适配：检测到 ui-beautify 时自动加入「插件面板」（卡片 / 经典模式统一管理，名称「文件浏览器」）；未安装时回退自带按钮 + 面板
• 偏好记忆：位置 / 尺寸 / 停靠模式 / 预览高度 / 预览模式本地记忆
• HIG 风格界面（v1.9.0）：Apple HIG 规范统一（系统字体栈与字号阶梯、8pt 圆角间距网格、深浅色材质、SF Symbols 风格 SVG 图标、150–200ms 动效）

⌨️ 快捷键（按 ? 查看）

安装

前置要求

• DSH 0.1.1-rc.2（或兼容的 0.1.x 系列）；Windows / macOS / Linux 均支持（路径处理按平台自适应）
• 官方安装方式需要 pnpm（npm install -g pnpm）

官方方式（推荐）

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

• 装完重启 DSH，会话标题栏右侧会出现「📁 文件」按钮（安装 ui-beautify 后由「🧩 插件面板」统一管理）
• 升级 / 卸载：dsh plugin --profile web update/remove dsh-file-explorer

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

使用说明

打开方式

• 会话标题栏右侧「📁 文件」按钮（ui-beautify 安装时入口为「🧩 插件面板」）

面板操作

操作速览

• 预览与编辑：点文件预览；「编辑」进入编辑模式（仅文本文件，二进制 / 已截断不可编辑）；Ctrl+S 保存、Esc 退出；保存带版本检测，编辑期间被外部改动会拒绝保存
• 拖放移动：按住文件 / 文件夹行拖到目标目录行（或树空白区）松开即移动；拖到自身 / 子目录被拒绝
• 右键菜单：新建文件（内置 txt / md / py / js / json / ts / html / css 模板）、新建文件夹、重命名、复制、粘贴（同名自动加后缀）、复制绝对 / 相对路径、删除（确认后移入回收站）
• 提示：粘贴到「文件」= 粘贴到其所在目录；删除目录会连同全部内容移入回收站

卸载

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

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

常见问题（FAQ）

兼容性

• 目标版本：DSH 0.1.0-rc.7；Windows / macOS / Linux（路径分隔符、大小写敏感、回收站策略均按平台自适应）
• 部分 CSS 选择器（侧边栏宽度探测 .pI_x6G_frame 等）针对该版本的客户端产物编写，DSH 大版本升级后可能需要复核
• Host 半区依赖 dsh 自带的 @deepseek-ai/dsh-typert-protocol（peer 依赖）——不要单独安装该包的独立副本，否则 Remote 桥会失效
• 写操作边界（v1.8.1）：编辑保存 / 新建 / 重命名 / 复制 / 移动 / 删除由 Host 半区直接通过 Node fs/promises 执行，并限制在当前工作区根目录内——工作区外的写 / 删 / 改名 / 移动会被拒绝（只读的浏览与预览不受限）。这是刻意设计（用户手动操作的文件管理器），但仍不受 DSH 的 read-only / workspace-write 策略约束，请勿在不可信环境下使用
• 大目录（如 node_modules）整目录复制 / 跨设备移动会较慢，属正常现象

开发者

• Host 半区（lib/index.js）：FileExplorerService 注册 fileExplorer 远程服务（fsList / fsRead / fsWrite / fsCreate / fsRename / fsCopy / fsDelete / fsMove / wsRoot / wsList）；读操作走 DSH fs 服务，写操作 node:fs/promises 直连；删除按平台走 PowerShell / osascript / gio trash，失败落内置回收站（30 天 / 200 条自动清理）；fsMove 处理跨设备（EXDEV）复制 + 删除回退；agent/status + session/event 维护最近活跃工作区
• Client 半区（lib/client.js）：__ModuleLoader__.load 加载；ctx.remote.$mount 自挂载 fileExplorer 命名空间；零 React hooks（原生 DOM 渲染）；路径拼接 / 相对路径 / 大小写比较按 platform 自适应；检测到 ui-beautify 的 dock 服务时注册为插件面板
• 改代码后：Client 改动刷新页面即可生效，Host 改动需重启 DSH；无需构建
• 已安装用户升级：dsh plugin --profile web update dsh-file-explorer

版本历史

• v1.9.0：Markdown 预览 + IDE 式代码查看 + 树内搜索 + 资源管理器定位 + HIG 风格界面——
  • 服务端引入 marked + highlight.js（lib/render.js 独立渲染管线模块）：Markdown 白名单渲染（raw HTML 转义 / 链接协议校验 / 图片占位 / TOC / 代码块高亮）、代码逐行高亮（≤2000 行）、单行超长截断标记；
  • 新增 fsRender（类型判定 + 分层渲染 + offset 续读）与 fsReveal（系统文件管理器定位）远程方法；预览上限 2MB → 4MB，超限支持分段「继续加载」；
  • 客户端：行号视图（自动换行逻辑行对齐 / 虚拟化渲染 / 编辑同步滚动）、Markdown 富文本视图（折叠 TOC / 代码块复制 / 限宽居中）、三态视图切换（Ctrl+[/] 与记忆）、树内搜索（Ctrl+F 过滤 / 子串高亮 / 键盘导航 / 计数 / 空状态）、右键「在资源管理器中显示」、? 快捷键帮助浮层；
  • HIG 风格界面：系统字体栈、8pt 圆角间距、深浅色材质（hljs 双主题跟随）、SF Symbols 风格 SVG 图标（替换 emoji）、动效规范。
• v1.8.1：安全加固——破坏性文件操作（写 / 建 / 改名 / 复制 / 移动 / 删除）限制在工作区根目录内，越界拒绝（只读不受限）；修复内置回收站清理策略反转（原按时间升序导致保留最旧 200 条、删除最新）；工作区跟随被用户拒绝后不再每轮重复弹确认。
• v1.8.0：重构——颜色值规范化、去重与 token 化（行为不变）。
• v1.7.3：移除悬浮球功能（侧边可拖动入口、工具栏开关按钮及相关偏好记忆全部删除；旧 localStorage 残留数据不再读取，无影响）。装有 ui-beautify 时本由插件面板浮动替代，现独立模式也不再提供。
• v1.7.2：健壮性与内存优化（行为不变）——
  • 目录缓存加上限（300 条 FIFO 淘汰，同步清理请求序号表；被淘汰目录再次展开时重新加载，短暂"加载中"；文件内容从不缓存不受影响）；
  • 修复行内输入框 blur 定时器竞态（不会误关新打开的输入框）；卸载时关闭残留的右键菜单/输入浮层；
  • 面板重建时清理 grip/停靠按钮注册表（overlay 槽重挂载不再累积陈旧引用）；工作区跟随探测加防叠加标志。
• v1.7.1：拖动跟手性——ui-beautify 拖动中（frame 带 data-vsc-dragging）暂停工作区跟随与目录树重建，避免拖动面板/停靠卡时树重渲染造成偶发卡顿。
• v1.7.0：接入 ui-beautify 统一插件面板——
  • 面板名称改为「文件浏览器」（列表项 / 标签页显示名，带 📁 图标）；
  • ui-beautify 的 dock 存在时，标题栏不再注册「📁 文件」按钮（入口统一为「🧩 插件面板」，会话日志按钮旁），面板在两种模式下都由插件面板宿主渲染（卡片模式停靠卡 / 经典模式右侧停靠与浮动）；自带的经典三档面板退役（仅 ui-beautify 缺失时启用）；
  • 悬浮球在宿主模式下隐藏；无 ui-beautify 时行为与 v1.6.0 完全一致。
• v1.6.0：适配 ui-beautify 卡片模式——
  • 检测到 ui-beautify 的 dock 面板宿主（卡片模式生效时）自动注册为停靠卡标签面板：点「📁 文件」在停靠卡中打开，支持 ⧉ 浮动 / 回停靠 / × 关闭，按钮高亮与面板开关实时同步；
  • 宿主面板内隐藏与卡片体系冲突的自带元素（右侧/中间/浮动停靠按钮、四边缩放 grip、悬浮球开关），样式由卡片宿主统一（毛玻璃 / border-l2 / 12px 圆角）；
  • 经典（webUI）模式保持原三档停靠面板，外观按卡片语言微调（12px 圆角、token 边框）；
  • 经典 ↔ 卡片切换时开关状态双向同步；ui-beautify 未安装 / 引擎未生效时自动回退经典面板，行为与旧版一致。
• 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