English | 简体中文

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 行号；预览模式经两级反查保证准确，宁可回退为裸引用也不给错行号
• 草稿中以蓝色胶囊展示，完整引用文本保留在剪贴板与草稿中，模型仍能读到 @路径 Lxx
• 随插件分发 file-line-reading skill，指导 AI 按引用行号只读必要内容

右键菜单

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

智能布局

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

聊天联动

• 聊天中的文件链接（工具行、本次产出列表、文件提及）一律在侧边栏打开，不再调用系统默认应用
• 「本次产出」行拦截：工具产生的文件以卡片形式展示，点击即在侧边栏打开

扩展与本地化

• 通过 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@<version>
• 卸载：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 蓝色胶囊；或使用树上的「@文件」按钮快速引用整个文件

配置

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

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

平台支持

已知限制

• 文件按扩展名 + 首部 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](./LICENSE)

致谢

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