前言¶

在 DeepSeek Harness（DSH）裏，一個工作區對應「一個項目目錄 + 跑在該目錄下的會話」。實際開發時，這些目錄常常成批落在同一個父路徑下：十幾個插件倉庫、demo、沙箱項目並排註冊，側邊欄默認「按工作區」平鋪一長列，切換和定位成本很高。

官方側邊欄已經提供 「按工作區樹」 視圖（groupBy = "workspace-tree"），會把每個工作區掛到最近的已註冊祖先工作區下面。難點在於：樹要有「父節點」，而你往往只註冊了葉子項目目錄，沒有爲共同的上級目錄單獨建工作區。

社區插件 dsh-plugin-better-folders（維護者 huguangyu666，分類：客戶端）做的是：按規則把共同上級目錄註冊成文件夾節點，讓內置樹視圖自動把同級工作區收進去，而不是重寫側邊欄 UI。

這是什麼¶

更好的 DSH 文件夾 是 DSH 客戶端側插件：自動整理工作區列表，把同一上級目錄下滿足條件的多個工作區匯合成一個可摺疊的文件夾節點。視覺上的摺疊與層級由 @deepseek-ai/dsh-client-ui-workspace 提供的「按工作區樹」完成；插件側主要是註冊上級目錄爲工作區，並可選切換分組方式。

它解決什麼問題¶

README 中的典型佈局如下：多個項目都在 MyProjects 或 code 下，平鋪時每一行都是一個工作區。整理後，共同父目錄會變成文件夾節點，子工作區嵌在其下；只有一個工作區的路徑仍保持原樣。

工作原理可以概括爲：

把相同上一級目錄的工作區匯合在一起，等價於把那個共同的上級目錄本身註冊成一個工作區（文件夾節點）。

因此插件不覆蓋官方 UI，依賴已有樹視圖渲染，避免「插件一掛、側邊欄白屏」類問題。

核心功能¶

按上級目錄自動 / 手動整理¶

整理規則可在設置中調整（默認值來自 README）：

插件對自己創建的文件夾節點做了級聯防護；用戶手動註冊的父級工作區不受此限制；根目錄（C:\、/）永遠不建節點。

「表」：自定義工作區集合¶

除磁盤層級決定的匯合外，插件支持 表：自定義名稱下的工作區 id 集合，不創建目錄、不改 cwd、不碰會話歷史。同一工作區可屬於多張表；刪表不刪工作區或會話。入口在側邊欄「工作區」標題行旁的 📋（與 📁 整理按鈕同排；定位失敗時會退回底部「整理文件夾」按鈕）。

斜槓指令示例：

/folders tables                        # 列出所有表
/folders tables new 性能對比            # 建表
/folders tables add 性能對比 titan      # 把工作區加進去（按路徑片段匹配）
/folders tables remove 性能對比 titan   # 移出
/folders tables rename 性能對比 A/B     # 改名
/folders tables delete 性能對比         # 刪表（不刪任何東西）

模型側可用工具 manage_workspace_tables。

安全邊界（使用前建議通讀）¶

• 只增不刪：整理只調用 workspaceRegistry.create()，不刪除工作區、目錄或會話歷史。
• 還原：unmerge 僅刪除本插件創建且沒有任何會話的文件夾節點；狀態記錄在 ~/.dsh/better-folders/state.json。
• 還原會關閉 autoOrganize，避免刪節點後又被自動整理重建。
• 刪除工作區註冊不等於刪除磁盤數據；重複整理冪等。

HTTP API（同源）¶

Host 通過 ctx.webServer 註冊前綴路由，例如：GET /better-folders/api/status、POST /better-folders/api/preview、POST /better-folders/api/apply、POST /better-folders/api/unmerge 等（完整列表見倉庫 README）。

安裝與啓用¶

插件以源碼構建後寫入 DSH profile，README 未提供 dsh plugin add 一類的一行命令。當前 package 版本爲 0.5.2（MIT），要求 Node >= 22.5，peer 依賴 @deepseek-ai/dsh（>=0.1.2-rc.1）等。

下面步驟來自倉庫 README：先構建，可選 dry-run，再安裝到 profile（示例爲 web；桌面版常用 desktop，需與當前正在使用的 profile 一致）。

npm install
npm run build
npm test
node tools/install-into-profile.mjs --profile web --dry-run
node tools/install-into-profile.mjs --profile web

從 GitHub 獲取源碼後，在同一目錄內執行：

git clone https://github.com/huguangyu666/dsh-plugin-better-folders.git
cd dsh-plugin-better-folders
npm install && npm run build
node tools/install-into-profile.mjs --profile web

裝完後重啓 DSH；桌面版還需刷新頁面以加載客戶端半。卸載：

node tools/install-into-profile.mjs --profile web --uninstall

DSH 社區插件目錄 SkillHub 條目 可查閱簡介與分類；目錄站爲社區生態，與 DeepSeek / 幻方無官方從屬關係。安裝前請自行閱讀源碼與許可證；插件在當前 DSH 進程權限下運行。

典型用法¶

裝上並重啓後，多數情況下無需額外操作：

1. 自動整理在啓動約 4 秒後運行一次，將合格的上級目錄註冊爲文件夾節點。
2. 若 autoTreeView 爲 true 且存在可匯合目錄，客戶端會嘗試把側邊欄切到「按工作區樹」。不切到該視圖時，列表可能只多出幾個條目，看不出摺疊效果。

手動流程：

1. 打開 設置 → 插件 → 更好的 DSH 文件夾。
2. 點 預覽 查看將新建的文件夾節點。
3. 點 一鍵整理；必要時在 視圖選項 → 分組方式 → 按工作區樹 手動切換，或刷新頁面。
4. 不滿意則 還原（會關閉自動整理；需在面板中重新打開 autoOrganize 若仍要自動匯合）。

對話中可執行：

/folders            # 查看現狀
/folders plan       # 預覽
/folders organize   # 執行整理
/folders unmerge    # 還原

沒看到效果時，README 建議覈對：profile 是否對應當前進程、客戶端半是否加載、分組是否爲「按工作區樹」。排查信息可寫在 ~/.dsh/better-folders/diag.json（接口 /better-folders/api/diag）。

適用場景與注意¶

• 適合：同一父目錄下注冊了多個 DSH 工作區（多插件倉、多 demo、多沙箱），希望側邊欄按文件夾摺疊，又願意使用官方「按工作區樹」而非第三方改 DOM 的方案。
• 適合：需要把分散路徑上的工作區收進自定義「表」，在側邊欄按集合瀏覽，甚至下鑽到會話級跳轉。
• 注意：匯合依賴「註冊上級目錄爲工作區」；minChildren、maxDepth 會改變哪些目錄會變成節點。還原僅針對插件創建且無會話的節點。
• 注意：安裝涉及本地構建與 install-into-profile.mjs，請只在信任的來源（上述 GitHub 倉庫）操作，並確認 target profile。

結尾¶

更好的 DSH 文件夾把「同級目錄太多、側邊欄平鋪難找」的問題，收斂成可配置的註冊與視圖切換：算法在 Host 端規劃與創建節點，展示交給 DSH 內置工作區樹；並附帶表、斜槓指令、Agent 工具與 HTTP API，便於人工和自動化共用同一套整理邏輯。

• 社區目錄：https://www.skillhub.cn/plugins/huguangyu666/dsh-plugin-better-folders
• 源碼與完整說明：https://github.com/huguangyu666/dsh-plugin-better-folders