DSH Web Client 的 VSCode 風格文件樹側欄插件：dsh-ymc-sidebar

前言¶

DeepSeek Harness (DSH) Web Client 原生的文件瀏覽通常依賴於 details 面板。這種方式在空白會話或需要獨立佈局時存在侷限。dsh-ymc-sidebar 插件通過掛載在 document.body 上的方式，爲 Web Client 提供了一個獨立的右側文件樹側欄。它不佔用 DSH 原生的 details slot，因此即使是在無上下文的 blank 會話中也能正常工作，並實現了類似 VSCode 的佈局體驗。

核心功能¶

該插件主要包含三個核心視圖和一個文件樹系統。

視圖與佈局¶

Activity Bar 圖標欄：側欄最右側提供常駐的 VSCode 風格 Activity Bar，包含“文件資源管理器”、“Git 追蹤”和“瀏覽器”三個視圖。點擊當前視圖圖標可收起/展開側欄。
拖拽調整寬度：側欄左側邊緣支持拖拽調整寬度，最小寬度爲 280px，且狀態會持久化存儲。
佈局 push：插件通過 --dsh-sidebar-width 屬性讓原生的 #root 元素讓出右側空間，形成“真佔位”效果，而非覆蓋。

文件資源管理器¶

虛擬化懶加載：以當前會話的工作區目錄（cwd）爲根展示文件樹。目錄和樹結構均採用虛擬化懶加載，防止大目錄導致性能問題。
文件預覽：點擊文件後，在右欄下方預覽內容。支持文本/代碼（帶行號與語法高亮）、Markdown 渲染/源碼切換，以及常見圖片格式預覽。二進制文件會顯示爲二進制提示。
多標籤頁：支持同時打開多個文件，具備橫向滾動和關閉功能。

Git 追蹤視圖¶

功能子頁：提供“改動”、“歷史”和“分支”三個子頁。
- 改動：查看當前分支、暫存區、工作區未暫存改動及未跟蹤文件，支持行級高亮的 diff 預覽。
- 歷史：查看提交記錄、提交信息及單次提交 diff。
- 分支：管理本地/遠端分支列表，支持切換分支或檢出遠端分支。
操作與刷新：面板頭部提供 Pull 和 Push 操作（帶確認框）。所有狀態、diff、歷史和分支會隨文件變化和 Git 元數據變化自動刷新。

瀏覽器視圖¶

Loopback 路由：支持在文件樹中選擇 .html / .htm 文件，自動切換到瀏覽器視圖並打開。插件提供自身的 Loopback HTTP 路由，使得本地 HTML 引用的相對資源（CSS / JS / 圖片等）能正確加載。
網頁瀏覽：提供自繪搜索首頁（默認爲必應搜索）和地址欄。支持多標籤頁瀏覽，標籤頁保留各自的導航歷史。
HTML 快捷菜單：瀏覽器面板頭部提供當前工作區 HTML 文件的快捷菜單，可快速跳轉打開本地文件。

安裝與啓用¶

環境要求¶

DeepSeek Harness (DSH): 0.1.2-alpha.2 或更新版本。
Node.js: 20+
pnpm: 10+
Git: 本地 git 命令（用於 Git 追蹤功能）。

安裝命令¶

插件已發佈至 npm，可直接通過 DSH 插件命令安裝：

dsh plugin --profile web add @kaijia/dsh-sidebar

安裝完成後，重啓 dsh web 即可看到右側的側欄。確認配置生效可執行：

dsh --profile web --dump-config

輸出中應包含 # == @kaijia/dsh-sidebar 層。

配置¶

安裝後，可以在 cordis.yml 配置文件中通過 insert 配置項調整插件行爲。默認配置如下：

- insert:
    - id: dsh-sidebar
      name: '@kaijia/dsh-sidebar'
      config:
        maxTextBytes: 2097152
        maxImageBytes: 8388608
        maxEntriesPerDirectory: 2000
        maxTreeRows: 100000
        watchEnabled: true
        watchDebounceMs: 200
        watchIgnored:
          - '**/node_modules/**'
          - '**/.git/**'

配置項	默認值	說明
`maxTextBytes`	`2097152`	單次文本預覽上限（UTF-8 字節）。
`maxImageBytes`	`8388608`	單張圖片預覽上限（字節）。
`maxEntriesPerDirectory`	`2000`	單目錄最多返回的條目數，超出時截斷。
`maxTreeRows`	`100000`	客戶端展開後可扁平化的最大樹行數。
`watchEnabled`	`true`	是否開啓文件監聽實時刷新（依賴 chokidar）。
`watchDebounceMs`	`200`	觸發通知的等待時間（毫秒）。
`watchIgnored`	`['/node_modules/', '/.git/']`	文件監聽忽略的 glob 路徑列表。

使用示例¶

調整側欄：在側欄展開狀態下，拖拽左側邊緣調整寬度；點擊最右側的 Activity Bar 圖標收起側欄。
瀏覽文件：在文件樹中選擇文件查看預覽；在“瀏覽器”視圖輸入網址或使用搜索框。
本地 HTML：在文件樹中點擊 .html 文件，側欄會自動切換至“瀏覽器”視圖並打開該文件。
Git 操作：在“Git 追蹤”視圖頭部點擊 Pull 或 Push，或在“分支”頁面切換分支。

依賴與注意事項¶

Blank 會話：插件不依賴 DSH 原生的 details slot，因此可以在無上下文的 blank 會話中打開。
工作區依賴：文件樹內容依賴於當前會話的工作區目錄（cwd）。如果當前會話沒有 cwd，右欄會顯示提示信息。
Git 依賴：Git 追蹤功能依賴本機已安裝的 git 命令，且當前工作區目錄必須是 Git 倉庫。
圖片支持：僅支持 png / jpg / jpeg / gif / webp / bmp / ico / avif 格式。

開發與維護¶

插件採用 Host/Browser 分離架構。源碼位於 src/index.ts（Host 入口，負責 RPC、文件系統、Git）和 src/client.tsx（Browser 入口，負責 React 組件與樣式）。

本地開發：克隆倉庫後，執行 pnpm install 和 pnpm build，再使用 dsh plugin --profile web add . 安裝。
樣式：使用 Tailwind CSS，直接消費 DSH 的主題 alias token（--dsw-alias-*），支持明暗主題切換。

結尾¶

dsh-ymc-sidebar 爲 DSH Web Client 提供了一套完整的文件管理、代碼預覽和 Git 追蹤方案，且不侵入原生界面。適合需要在 Web 端獲得類似 VSCode 開發體驗的用戶。

目錄頁: kaijia323/dsh-ymc-sidebar
GitHub: kaijia323/dsh-ymc-sidebar