前言¶

在 DSH「一切皆插件」的生态中，很多扩展能力由社区插件独立提供。DSH Web GUI 处理工作区文件时，经常需要在界面里直接看目录、预览文件、修改内容，并在提交前检查 Git 状态。

folder-tree-sh 是 DSH Web GUI 的工作区文件树插件（dsh-ftree），提供文件浏览、多格式预览、内联编辑、Git 变更面板与完整文件操作。它采用零核心修改、热插拔（profile bundle）的方式接入 DSH Web。

这是什么¶

资料中给出的 package name 为 folder-tree-sh，package.json 版本为 0.3.0，并声明 private: true。许可证为 MIT，dsh.client.platform 为 web。

仓库地址为：

https://github.com/Nothree-code/folder-tree-sh

它的定位是 DSH Web GUI 的工作区文件树插件：在网页侧提供文件树、预览、编辑、Git 变更和文件操作能力。

核心功能¶

文件树¶

文件树侧边栏支持：

1. 目录展开 / 折叠。
2. 5 秒自动刷新，同时支持手动刷新。
3. 过滤框：按文件名实时过滤。
4. 排序：名称 / 大小 / 修改时间，目录始终置顶。
5. 隐藏文件开关：默认隐藏 .git / node_modules / .DS_Store。
6. 宽度拖拽调整，面板开关状态持久化到 localStorage。

多标签预览¶

插件支持多标签同时打开多个文件，切换即时。预览能力包括：

• Markdown：渲染 + 编辑双模式，支持工具栏、实时预览、自动保存、Ctrl+S。
• 工作区相对路径图片：例如 ![](assets/a.png)，经 host raw 路由渲染。
• 代码：30+ 语言轻量高亮。
• CSV：自动分隔符检测（, ; Tab），并以表格渲染。
• 图片：支持缩放（Ctrl+滚轮），双击复位。
• PDF：浏览器原生渲染，使用 no-cache 字节流。
• DOCX：依赖 mammoth 转为 HTML 真渲染，含图片；无 mammoth 时自动降级为 PowerShell 提取纯文本。
• 文本：分块加载，1MB/块，100MB 上限；GBK 编码自动检测回退。

Markdown 内联编辑¶

Markdown 文件支持内联编辑：

• 自动保存：800ms 防抖。
• 手动保存：Ctrl+S。
• 保存前滚动备份：.dshbak.1 到 .dshbak.3。

Git 变更面板¶

Git 变更面板提供：

• 分支显示。
• 变更列表：未跟踪 / 已暂存 / 已修改。
• 操作：
• 暂存：add
• 取消暂存：restore --staged
• 丢弃更改：checkout --；未跟踪文件走回收站删除
• 查看差异：diff / diff --cached

文件操作¶

右键菜单支持以下文件操作：

1. 刷新。
2. 新建文件。
3. 新建文件夹。
4. 重命名。
5. 删除，进入回收站，不永久删除。
6. 复制 / 剪切 / 粘贴。
7. 原地复制。
8. 打开源文件夹，即在资源管理器中定位。
9. 复制路径。
10. 添加到聊天，适用于图片。

安全模型¶

插件在 host 侧提供多道边界限制：

1. Origin 白名单：从 webStartup 动态派生，例如 127.0.0.1、localhost、[::1]、配置的 host、trustedHosts。跨站请求一律 403。监听 0.0.0.0（LAN）时，退化为仅靠 CSRF token。
2. 每进程 anti-CSRF token：所有变更路由（op / write / git-op）必须携带 /dsh-ftree-token 颁发的 token。
3. 工作区白名单：所有路径必须位于已注册 workspace 根，deny by default。
4. 删除进回收站：不永久删除。
5. 写入前滚动备份：.dshbak.1 到 .dshbak.3。
6. Shell 注入防护：所有 PowerShell 命令经单引号转义，' 变为 ''。
7. realpath 路径守卫：所有路径经 realpath 规范化，跟随符号链接与 NTFS junction，然后再做工作区前缀校验。.. 穿越、junction 与 symlink 逃逸均无法绕过白名单；不存在的写入目标自动回溯最近存在祖先（realpathLenient）。
8. 预览缓存：按文件 size 校验自动失效，写入后主动清除。

安装与启用¶

当前资料没有提供面向使用者的官方安装命令。README 给出的是开发 / 本地包安装场景下的步骤。

先同步修改到 node_modules 实体拷贝：

powershell -ExecutionPolicy Bypass -File sync.ps1

如果 package.json 有改动，例如名称、版本、dsh.client，再执行本地包安装 / 更新：

cd ..\.. && pnpm add "file:./packages/dsh-ftree"

经过上面的步骤后，重启 dsh web 生效。

典型路由¶

host 侧暴露的路由如下：

• GET /dsh-ftree-meta：获取版本信息。
• GET /dsh-ftree-token：获取 CSRF token。
• GET /dsh-ftree-list：列目录，withMtime=1 时附修改时间。
• GET /dsh-ftree-read：分块读文件，支持 text/image/pdf/docx。
• POST /dsh-ftree-op：执行 rename / delete / paste / open / mkdir / newfile。
• POST /dsh-ftree-write：保存文本，带 .dshbak 备份。
• GET /dsh-ftree-pdf：获取 PDF 字节流。
• GET /dsh-ftree-raw：获取工作区原始字节，用于 Markdown 图片等场景。
• GET /dsh-ftree-git：获取 git status，包括 branch 和变更。
• POST /dsh-ftree-git-op：执行 stage / unstage / discard / diff。

调用变更类路由前，需要先获取 /dsh-ftree-token 颁发的 token。

适用场景与注意¶

适合这些场景：

1. 在 DSH Web GUI 中浏览工作区目录。
2. 快速预览 Markdown、代码、CSV、图片、PDF、DOCX、文本等文件。
3. 直接编辑 Markdown 文件，并查看保存前备份。
4. 在提交前查看 Git 分支、变更列表，并执行 stage / unstage / discard / diff。
5. 执行新建、重命名、删除、复制、移动等文件操作。

使用前需要注意：

1. 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
2. 当前资料没有提供面向使用者的官方安装命令，不能仅凭仓库名拼接安装命令。
3. 插件路径能力受工作区白名单限制，路径必须位于已注册 workspace 根。
4. DOCX 真渲染依赖 mammoth，缺少时会降级为 PowerShell 提取纯文本。

链接¶

• 目录页：当前资料未包含可核实的目录页地址。
• GitHub：https://github.com/Nothree-code/folder-tree-sh
• 许可证：MIT