dsh-file-explorer

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

它做什么

浏览与搜索：目录树按需展开（目录排在前、文件带大小），默认隐藏 node_modules、.git 这类条目，需要时用工具栏的「👁 隐藏」开关显示；按 Ctrl+F 会在树内呼出搜索条，实时过滤已加载的节点并保留目录层级，命中内容高亮，↑ / ↓ 导航、Enter 打开、→ / ← 展开或收起，搜索条会显示匹配数量与空状态。

预览与编辑：点开文件即进入预览——Markdown 默认富文本渲染（GFM 表格 / 任务列表 / 删除线、代码块语法高亮并支持一键复制、可折叠标题目录），代码与文本文件则直接进入带语法高亮的编辑视图，输入即所见，行号随输入同步、滚动精确对齐，长行横向滚动不软换行；Ctrl+S 保存、Esc 退出，Ctrl+[ / Ctrl+] 在 Markdown 的「渲染 / 编辑」之间切换，插件会按文件类型记住你上次用的模式。超过 4MB 的文件会分段加载，点「继续加载」逐段读取。预览显示在独立的浮动卡片里，卡片可以拖动、四边四角缩放、双击最大化 / 还原，Esc 或 × 关闭。

文件操作：文件与目录行支持拖放移动，右键菜单提供新建文件（内置 txt / md / py / js / json / ts / html / css 模板）、新建文件夹、重命名、复制、粘贴（同名自动加后缀）、复制绝对或相对路径，以及删除到回收站；删除会按平台走系统回收站（Windows PowerShell / macOS Finder / Linux gio trash），系统回收站不可用时落到内置回收站 ~/.dsh-file-explorer-trash/（保留 30 天、最多 200 条，自动清理）。工作区会自动跟随当前会话切换，面板本身支持「右侧 / 中间 / 浮动」三种停靠方式并记住你的偏好。

界面：整体按 Apple HIG 规范统一——系统字体栈、8pt 圆角与间距、深浅色材质、SF Symbols 风格图标、150–200ms 动效，预览卡片与面板在深浅主题间自动切换配色。

快捷键（按 ? 查看帮助）

键	动作
Ctrl+F / ⌘F	搜索 / 过滤文件名
Esc	关闭搜索 · 退出编辑 · 关闭浮层
↑ / ↓	在搜索结果中导航
Enter	打开选中文件（目录则展开）
→ / ←	展开 / 收起目录
Ctrl+[ / Ctrl+]	切换渲染 / 编辑视图（仅 Markdown）
Tab（编辑中）	插入 2 空格缩进
Ctrl+S（编辑中）	保存
?	快捷键帮助（也可点工具栏「帮助」按钮）

安装

前置要求是 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 plugin --profile web update dsh-file-explorer
dsh plugin --profile web remove dsh-file-explorer

装完重启 DSH，会话标题栏右侧会出现「📁 文件」按钮；如果同时装了 ui-beautify，入口会统一收进 DSH 官方右侧栏的一个标签页（右侧栏「开始」页上的入口胶囊，或标签条的 +），本插件不再占用标题栏位置。

使用说明

面板里可以做的操作：

控件 / 操作	作用
右侧 / 中间 / 浮动	切换停靠方式；「右侧 / 中间」模式下拖边缘调整宽度
标题栏拖动	浮动模式下拖动面板位置
面板四边 / 四角	浮动模式下自由调整大小
↻ 刷新	重新加载当前目录
👁 隐藏	显示 / 隐藏 node_modules、.git 等条目
点目录 / 点文件 / ✕	展开目录 / 打开文件预览 / 关闭预览

几个容易忽略的细节：保存带版本检测，如果文件在你编辑期间被其它程序改动，保存会被拒绝并提示重新载入；粘贴到某个「文件」上等于粘贴到它所在的目录；删除目录会把里面的内容一起移入回收站。

安全边界（重要）

编辑保存、新建、重命名、复制、移动、删除这些写操作由 Host 半区直接通过 Node 的 fs/promises 执行，并且限制在当前工作区根目录内——工作区之外的写、删、改名、移动都会被拒绝（只读的浏览与预览不受这个限制），工作区根目录本身也禁止删除、重命名和移动。这是刻意的设计（这是一个由用户手动操作的文件管理器），但它不受 DSH 的 read-only / workspace-write 策略约束，请不要在不可信环境下使用。

常见问题

问题	原因与解决
点「📁 文件」没有出现面板	多为页面缓存或渲染异常：先硬刷新（Ctrl+F5），仍不行则重启 DSH
树里显示红色错误行	该路径当前不可读（权限或已删除），点「↻ 刷新」重试
保存文件提示「文件已改变」	该文件在编辑期间被其它程序修改，重新载入后再保存
删除的文件去哪了	系统回收站；不可用时落到内置回收站 ~/.dsh-file-explorer-trash/（保留 30 天、最多 200 条）
复制到剪贴板失败	浏览器在非安全上下文禁用剪贴板 API（本机 localhost 通常可用），可改用右键菜单里的内部剪贴板
面板位置跑到屏幕外	清除该站点的 dsh-file-explorer:* localStorage 键后重新打开
与旧版 / 临时版插件冲突	v1.2.0 起通过官方 bundle 只安装一个实例即可，移除其它副本

兼容性

目标版本是 DSH 0.1.0-rc.7 及兼容的 0.1.x 系列；部分 CSS 选择器（例如侧边栏宽度探测用的 .pI_x6G_frame）针对该版本的客户端产物编写，DSH 大版本升级后可能需要复核。Host 半区依赖 dsh 自带的 @deepseek-ai/dsh-typert-protocol（peer 依赖），不要单独安装该包的独立副本，否则 Remote 桥会失效。大目录（例如 node_modules）整目录复制或跨设备移动会明显变慢，这属于正常现象。

开发者

Host 半区（lib/index.js）：FileExplorerService 注册 fileExplorer 远程服务（fsList / fsRead / fsWrite / fsCreate / fsRename / fsCopy / fsDelete / fsMove / wsRoot / wsList），读操作走 DSH 的 fs 服务、写操作直连 node:fs/promises，删除按平台调用系统回收站并在失败时落到内置回收站，fsMove 处理跨设备（EXDEV）的复制加删除回退，另通过 agent/status 与 session/event 维护最近活跃的工作区。

Client 半区（lib/client.js）：__ModuleLoader__.load 加载，用 ctx.remote.$mount 自挂载 fileExplorer 命名空间，全部界面用原生 DOM 渲染（零 React hooks），路径拼接、相对路径与大小写比较按 platform 自适应；检测到 ui-beautify 的 dock 服务时注册为插件面板，用的是规范写法 ctx.inject(['dock'], (c) => …)（规范见 dsh-ui-beautify/docs/plugin-panel-integration.md）。

改代码后：Client 改动刷新页面即可生效，Host 改动需要重启 DSH，全程无需构建。

更新日志

v1.11.0

• 变更：集成契约从 ui-beautify 的 dock（v2）改为 sidebarPanel（v1）。 ui-beautify 3.0.0 移除了自研「插件面板」宿主——它拖动卡片时要改写官方 AppFrame 的 grid-template-columns，而那正是官方右侧栏通过 ctx.layout.openRightbar() 申领的同一份资源，两边互相覆盖就是"面板与侧边栏冲突"的根因。现在本插件注册成 DSH 官方右侧栏的一个标签页：标签条、浮动、分屏、每会话独立状态全部由官方负责，引导页上多一个「文件浏览器」入口胶囊。
• 适配：面板正文在右侧栏里按面板自身宽度响应式（不再按窗口宽度）。宿主在面板小于 420px 时加 data-dsh-narrow，工具栏的文本标签在窄宽度下收起只留图标（title 仍提供 tooltip），树行文件名走省略号截断而不是换行，行内文件大小在窄宽度下隐藏。
• 变更：subscribe 被移除（官方右侧栏没有对应接口，也不需要——标签条与引导页本身就是入口）；注册期间标题栏按钮保持隐藏。
• 说明：未安装 ui-beautify 或 ui-beautify < 3.0.0 时，本插件退回自带的独立浮动面板与标题栏入口，行为不变。

v1.10.2

• 变更：接入 ui-beautify 的 dock API v2 规范写法（ctx.inject），宿主热重载或卸载时自动重注册，并保留守护 ctx 的幂等退化绑定器。

v1.10.1

• 修复：保存的版本校验改为原子写入，外部改动不再被静默覆盖；新建文件走原子创建。
• 修复：工作区包含性检查升级为词法加真实路径双层校验，封堵符号链接与 Windows junction 逃逸。
• 修复：「继续加载」在文件恰好等于窗口长度时误报截断；剪贴板清空后「粘贴」仍可点却无操作；重命名后编辑 / 预览 / 剪贴板路径不跟随迁移。
• 修复：保存飞行中关闭或切换预览时旧回调复活、停靠面板顶部偏移硬编码、工作区跟随抖动等十余项健壮性问题。

v1.10.0

• 变更：适配 DSH 0.1.2-rc.1 —— 封堵目录穿越、统一版本令牌族、修正工作区字段漂移、侧栏定位改用稳定契约、活动工作区探针取正确分组。

v1.9.20

• 修复：深色主题检测改以 body[data-ds-dark-theme] 为准，手动切深色时不再套用浅色配色；浅色配色换成 VS Code Light+。

v1.9.19

• 修复：深色配色换成 VS Code Dark+；预览卡片创建时即打主题标记；编辑器行号条的层级修正，文字不再压在行号上。

v1.9.18

• 新增：编辑器撤销 / 重做（VS Code 语义，保存视为检查点，跨保存可撤），配工具栏按钮与 Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y。

v1.9.17

• 修复：光标与选区在中文、全角、emoji 行内的横向错位（改为按字符实际宽度计算几何）。

v1.9.16

• 变更：预览卡片与独立面板的缩放把手改为独立浮层，不再遮挡滚动条与关闭按钮。

v1.9.15

• 变更：编辑器底层重构为单一滚动容器，行号列与正文解耦，光标 / 选区 / 点击 / 输入法的位置由同一套几何计算。

v1.9.11

• 修复：编辑器光标错位（行号列宽被重复计入导致文字整体右偏）。

v1.9.7

• 修复：「继续加载」偏移跳段导致内容静默丢失、工作区拒绝跟随失效后每 800ms 重复弹窗、Markdown 渲染的两处 XSS、工作区根目录可被删除或改名、浮层盖住设置弹窗。
• 变更：编辑器重做为输入即实时语法高亮。

v1.9.x

• 新增：Markdown 渲染预览、IDE 式实时高亮编辑、预览独立浮动卡片、树内搜索、快捷键帮助浮层、HIG 风格界面。

v1.8.x

• 变更：破坏性写操作限制在工作区根目录内；颜色值 token 化。

v1.7.x

• 新增：接入 ui-beautify 的统一插件面板；移除悬浮球。

v1.6.x

• 新增：适配 ui-beautify 卡片模式（停靠卡标签面板、浮动、双向状态同步、经典模式回退）。

v1.5.x

• 新增：跨平台回收站、拖放移动，修复大文件预览、二进制识别与浮动面板打不开等问题。

v1.4.x

• 新增：删除到回收站与实时刷新。

v1.3.x

• 新增：文件内联编辑与 IDE 式右键菜单（新建 / 重命名 / 复制 / 粘贴 / 复制路径，含磁盘冲突检测）。

v1.2.x

• 变更：支持 dsh 官方 bundle 安装；typert-protocol 改为 peerDependency，保证与 gateway 共享模块实例。

v1.1.x

• 变更：v2 架构重写（Client 用 $mount 自挂载命名空间、Host 用 TypertRemoteService 自动注册）。

v1.0.x

• 初版，已被 v1.1 取代。

License

MIT