文件工作台侧栏 ssjob123/dsh-file-panel-left

dsh-file-panel-left

DSH Web 的「纯文件工作台」侧边栏插件 —— 文件资源管理器、编辑器与预览器一体，左树右内容，文件浏览、编辑、引用与对话联动在一个面板里完成。

基于社区插件 dsh-better-sidebar（作者 omdsh-dev，仓库，MIT 许可）精简定制，只保留文件相关能力（文件树 / 编辑器 / 预览 / @引用 / 聊天文件打开），删除了终端、浏览器、Git、任务管理等与文件无关的功能。原名 dsh_left_bar，2026 年改名并独立发布。

功能特性

纯文件工作台定位

- 左树右内容分栏：文件树常驻左侧（搜索 / 刷新），右侧内容区展示打开的文件；未打开文件时显示占位提示
- 已删除终端、浏览器、Git、任务管理、标签栏、下载与插件市场等非文件功能，聚焦文件浏览与编辑

文件树

- 懒加载目录（逐层读取），大目录不卡顿
- 软链接支持：识别链接目标类型，失效链接明确标记为「失效的软链接」
- 支持 UNC 网络路径
- 按文件名全局搜索（300ms 防抖，可中止），结果过多时提示截断
- 刷新按钮；树头「+」与文件夹行尾 hover「+」新建文件（内联输入，Enter 创建 / Esc 取消，创建后不自动打开）
- 单击打开文件；树内空白处点选可选中目录（作为新建文件的目标），选中态高亮
- 右键复制相对 / 绝对路径

CodeMirror 6 编辑器

- 20+ 种语言语法高亮：JS/TS/JSX、JSON、Python、HTML、CSS、Markdown、XML、YAML、SQL、Java、C/C++、C#、Kotlin、Swift、Rust、Go、PHP、Shell、TOML、INI、nginx、Dockerfile、properties 等（含自定义 INI 高亮）
- Ctrl/Cmd+F 搜索面板、括号配对高亮、代码折叠、自动缩进、活动行高亮、Alt+拖拽列选
- JSON/JSONC 一键格式化（Ctrl/Cmd+Shift+F）
- Ctrl/Cmd+S 手动保存；同时内置每秒轮询的自动保存（有未保存修改才写盘）

内置 6 种文件查看器

- 图片 / PDF / Markdown / HTML / 代码（兜底）/ 二进制提示
- Markdown 预览 / 编辑双模式，预览支持 Mermaid 图表渲染
- HTML 预览在沙箱 iframe 中渲染（无法读取界面数据与本地文件），提供「刷新预览」按钮
- 超大文件截断显示（仅展示前 512KB）；不支持的二进制类型给出明确提示

@引用（自研「添加到对话」+ 官方源并存）

- 在编辑器选中代码、松开鼠标，弹出「添加到对话」浮窗，向草稿插入 @相对路径 L12-L25 纯引用（真实行号、不携带选中文本，省 token；单行选区为 @路径 L12，反查失败回退为裸 @路径）
- 行号真实可靠：编辑模式直接取 CodeMirror 行号；预览模式经两级反查保证准确，宁可回退为裸引用也不给错行号
- 草稿中以蓝色胶囊展示；hover 胶囊左缘出现 ×，点击即可删除；点击胶囊在侧边栏打开该文件
- DSH 官方 @ 源（0.1.1-rc.2+，无行号文件胶囊）与自研源同菜单并存；插件绝不触碰官方胶囊（不挂叉号、不拦截）
- 随插件分发 file-line-reading skill，指导 AI 按引用行号只读必要内容

右键菜单

- 复制相对地址 / 复制绝对地址 / 重命名 / 删除
- 重命名带同名预检与非法字符校验；删除弹窗确认后移入系统回收站（Windows / macOS），会话根目录不可删除

智能布局

- 折叠 / 展开按钮：任何展开动作（按钮、聊天打开文件、打开文件）都恢复为视口 65% 的可读宽度
- 内容区「关闭」按钮（X）：收起展示页并把面板宽度收窄到只剩目录树，再次点选文件即恢复 65% 宽度
- 面板宽度与树列宽度均可拖拽（树列 240–480px，默认 280px），会话内持久化

聊天联动

- 聊天中的文件链接（工具行、官方「本次产出」行、文件提及）一律在侧边栏打开，不再调用系统默认应用
- 「本次产出」行由 DSH 官方 ui-deliverables 原生渲染（0.1.1-rc.2+）；本插件拦截其打开动作，使产物文件与内联码提及都开进侧边栏——这是插件保留的核心差异化

扩展与本地化

- 通过 ctx.betterSidebar 服务，外部插件可注册侧边栏标签页与文件查看器
- 界面文案中英双语，跟随 DSH 语言设置实时切换
- 会话隔离：每个会话独立的工作目录与面板状态；布局偏好持久化

平台适配

- Windows 标题栏兼容模式（为无边框窗口右上角的原生标题栏预留空间）
- 无 settings 服务的部署自动降级：偏好设置写入 ~/.dsh/dsh-file-panel-left-prefs.json

安装

环境要求：Node.js ≥ 20、DSH Web（含 dsh 命令行）。peer 依赖（React 18、Cordis 与 @deepseek-ai/dsh-* 系列）由 DSH 运行时提供，无需手动安装。

正式发布版（npm）

dsh plugin --profile web add dsh-file-panel-left

- 一条命令完成安装与挂载：包内声明的 bundle patch（cordis.patch.yml）会让 CLI 自动把插件加入 profile 的 bundle 栈，无需手改任何配置文件
- 安装完成后重启 DSH 并硬刷新浏览器（Ctrl+Shift+R / Cmd+Shift+R）即可看到侧边栏
- 指定版本：dsh plugin --profile web add dsh-file-panel-left@
- 卸载：dsh plugin --profile web remove dsh-file-panel-left
- 若 profile 里之前手动挂载过本插件（cordis.patch.yml 中的挂载行），改用 CLI 安装前请先移除旧行，避免双挂载（出现两个侧边栏）

本地开发安装（file: 依赖）

在 profile 目录（如 ~/.dsh/profiles/web）的 package.json 中添加本地依赖：

"dependencies": {
"dsh-file-panel-left": "file:/dsh-file-panel-left"
}

在 profile 的 cordis.patch.yml 中手动挂载（与 CLI 自动挂载二选一，不要重复）：

- insert:
- id: dsh-file-panel-left
name: 'dsh-file-panel-left'

然后安装：

cd ~/.dsh/profiles/web
pnpm install

注意：pnpm 的 file: 依赖是拷贝而非软链。每次修改插件源码后，需要删除 profile 中 node_modules/dsh-file-panel-left 的旧拷贝再重新安装，否则加载的仍是旧版本：

Remove-Item -LiteralPath "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-file-panel-left" -Recurse -Force
cd $env:USERPROFILE\.dsh\profiles\web; pnpm install

使用说明

- 文件树：单击文件打开；树头或文件夹行尾的「+」新建文件（Enter 创建 / Esc 取消）；顶部搜索框按文件名过滤；右键行可复制路径 / 重命名 / 删除
- 编辑器：打开代码或配置文件即进入 CodeMirror 编辑器；Ctrl/Cmd+S 保存，修改后每秒自动保存；Ctrl/Cmd+F 搜索；代码 / 配置文件带折叠、括号配对、列选等 IDE 能力；JSON 文件有格式化按钮（Ctrl/Cmd+Shift+F）
- 预览：Markdown 文件可在「预览 / 编辑」间切换，预览渲染 Mermaid 图；HTML 文件默认在沙箱 iframe 中渲染，工具条可刷新；图片 / PDF 直接预览；不支持的二进制类型显示提示
- 右键菜单：复制相对地址、复制绝对地址、重命名（重名会提示）、删除（确认后移入系统回收站）
- @引用：在编辑器选中代码、松开鼠标 → 点击浮窗「添加到对话」，草稿插入蓝色 @相对路径 L12-L25 胶囊（hover 左缘 × 删除）；官方 @ 源（无行号）也在同一菜单可用

配置

插件没有设置页面，行为全部为内置默认值，刻意保持简单：

- 展开面板 = 视口宽度的 65%（可拖拽微调，会话内记住）
- 自动保存：每 1 秒轮询，有未保存修改才写盘，不可关闭
- 聊天文件打开拦截：恒开启（工具行 / 本次产出 / 文件提及都会在侧边栏打开），不提供开关
- 删除：确认后移入系统回收站（Windows 10/11 与 macOS）
- HTML 预览：默认启用沙箱（不读取界面数据与本地文件）
- 偏好设置（标题栏兼容等）通过 settings 服务持久化；无 settings 服务的部署自动降级为本地文件

平台支持

| 平台 | 支持情况 |
| Windows 10 / 11 | 完整支持：删除移入系统回收站（基于 PowerShell 的 Microsoft.VisualBasic.FileIO，零额外依赖）；标题栏兼容模式可用 |
| macOS | 完整支持：删除移入废纸篓（基于 osascript 调用 Finder，零额外依赖）；标题栏兼容模式不适用 |
| Linux | 浏览 / 编辑 / 预览等全部文件功能可用（@引用由 DSH 官方提供）；删除为永久删除（Linux 无系统回收站，删除前需二次确认，删除后无法恢复） |

已知限制

- 文件按扩展名 + 首部 NUL 字节探测分类：UTF-16 / UTF-32 编码的文本会被判定为二进制（首部含 0x00 字节），显示二进制提示而非编辑器——如需查看请转存为 UTF-8。按编码探测需要先读完整文件，得不偿失。

开发

pnpm install
pnpm build # tsc 类型检查产物 + tsdown 打包，输出 lib/
pnpm typecheck # 仅类型检查（tsc --noEmit）

迭代流程：pnpm build → 强制同步到 profile（见「本地开发安装」）→ host 端改动重启 DSH、client 端改动硬刷新浏览器 → 浏览器中验证。

技术栈与架构

- Host（Node）：Cordis 插件，提供文件树 / 读取 / 写入 / 搜索 / 回收站删除 / 重命名等 API 路由；偏好持久化（settings 服务或本地文件降级）
- Client（浏览器）：React 18 + CSS Modules；文件树、左树右内容分栏、查看器注册表
- 编辑器：CodeMirror 6，语言包与扩展按需加载
- 按需分块：Mermaid、编辑器等重模块以懒加载 chunk 提供，首次打开对应文件时才加载
- 服务化基座：ctx.betterSidebar 服务供外部插件注册标签页与文件查看器
- i18n：接入 DSH 语言服务，中英双语、实时切换
- 会话隔离：每个会话独立工作目录与面板状态，偏好持久化到 localStorage（键 dsh_left_bar:v1）

许可

MIT

致谢

本项目由社区插件 dsh-better-sidebar（作者 omdsh-dev，DSH-better-sidebar，MIT 许可）精简定制而来（原项目名 dsh_left_bar，2026 年更名），感谢上游的设计与实现；上游版权声明保留于 LICENSE。