前言¶
在 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 變更和文件操作能力。
核心功能¶
文件樹¶
文件樹側邊欄支持：
- 目錄展開 / 摺疊。
- 5 秒自動刷新，同時支持手動刷新。
- 過濾框：按文件名即時過濾。
- 排序：名稱 / 大小 / 修改時間，目錄始終置頂。
- 隱藏文件開關：默認隱藏
.git/node_modules/.DS_Store。 - 寬度拖拽調整，面板開關狀態持久化到
localStorage。
多標籤預覽¶
插件支持多標籤同時打開多個文件，切換即時。預覽能力包括：
- Markdown：渲染 + 編輯雙模式，支持工具欄、即時預覽、自動保存、
Ctrl+S。 - 工作區相對路徑圖片：例如
，經 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
文件操作¶
右鍵菜單支持以下文件操作：
- 刷新。
- 新建文件。
- 新建文件夾。
- 重命名。
- 刪除，進入回收站，不永久刪除。
- 複製 / 剪切 / 粘貼。
- 原地複製。
- 打開源文件夾，即在資源管理器中定位。
- 複製路徑。
- 添加到聊天，適用於圖片。
安全模型¶
插件在 host 側提供多道邊界限制：
- Origin 白名單：從
webStartup動態派生，例如127.0.0.1、localhost、[::1]、配置的 host、trustedHosts。跨站請求一律403。監聽0.0.0.0（LAN）時，退化爲僅靠 CSRF token。 - 每進程 anti-CSRF token：所有變更路由（
op/write/git-op）必須攜帶/dsh-ftree-token頒發的 token。 - 工作區白名單：所有路徑必須位於已註冊 workspace 根，deny by default。
- 刪除進回收站：不永久刪除。
- 寫入前滾動備份：
.dshbak.1到.dshbak.3。 - Shell 注入防護：所有 PowerShell 命令經單引號轉義，
'變爲''。 realpath路徑守衛：所有路徑經realpath規範化，跟隨符號鏈接與 NTFS junction，然後再做工作區前綴校驗。..穿越、junction 與 symlink 逃逸均無法繞過白名單；不存在的寫入目標自動回溯最近存在祖先（realpathLenient）。- 預覽緩存：按文件 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。
適用場景與注意¶
適合這些場景：
- 在 DSH Web GUI 中瀏覽工作區目錄。
- 快速預覽 Markdown、代碼、CSV、圖片、PDF、DOCX、文本等文件。
- 直接編輯 Markdown 文件，並查看保存前備份。
- 在提交前查看 Git 分支、變更列表，並執行 stage / unstage / discard / diff。
- 執行新建、重命名、刪除、複製、移動等文件操作。
使用前需要注意：
- 插件以當前
dsh進程權限運行，安裝前應檢查源碼與許可證。 - 當前資料沒有提供面向使用者的官方安裝命令，不能僅憑倉庫名拼接安裝命令。
- 插件路徑能力受工作區白名單限制，路徑必須位於已註冊 workspace 根。
- DOCX 真渲染依賴
mammoth，缺少時會降級爲 PowerShell 提取純文本。
鏈接¶
- 目錄頁：當前資料未包含可覈實的目錄頁地址。
- GitHub：https://github.com/Nothree-code/folder-tree-sh
- 許可證：MIT
