前言¶
DeepSeek Harness (DSH) Web 是一個基於插件的架構，官方界面提供了基礎的文件瀏覽能力。dsh-v-explorer 是一個官方右側欄擴展插件，由用戶 victor10035445 維護。它通過插件機制接管官方的 files 頁型，提供增強的文件樹體驗，並新增了 bookmarks 頁型與行區間引用摘錄功能。該插件採用純增量模式，卸載或降級即可恢復官方行爲。
核心功能¶
1. Files Tab 接管¶
插件接管了官方的文件樹頁面，提供了目錄懶加載、右鍵菜單和文件預覽功能。
- 操作邏輯：點擊文件會觸發官方預覽，點擊目錄僅展開摺疊狀態。
- 右鍵菜單：支持打開所在目錄、複製路徑、插入到會話、加書籤（★）、默認瀏覽器打開 HTML。
- 文件顯示：. 開頭的隱藏文件照常顯示（不提供書籤功能）。
2. Bookmarks Tab 書籤頁¶
新增了一個書籤頁型，用於管理當前會話的文件引用。
- 會話作用域：書籤與當前會話綁定，刷新或切換會話會重置書籤狀態。
- 持久化與同步：書籤數據持久化存儲在 <cwd>/.dsh-v-explorer/bookmarks.json，多標籤頁間通過 SSE 協議實時同步變更。
- 失效標記：當源文件被刪除時，書籤會保留並顯示刪除線。
- 限制：書籤上限爲 100 條，支持冪等去重。
3. 變更流自動刷新¶
插件利用官方的 ChangeFeed 機制構建了變更流，用於維護文件樹和書籤的同步狀態。
- 重拉策略：目錄展開時觸發 500ms 去抖靜默重拉。
- 摘除策略：當文件從目錄中消失時，會即時摘除對應的書籤或樹節點。
4. 自動展開與佈局¶
每次進入會話時，插件會自動展開官方右側欄，並默認打開 files 和 bookmarks 兩個頁型。
- 寬度控制：默認寬度固定爲 300px（此前官方視口 45% 過寬，插件通過接口做了契約修正）。
5. 行區間引用摘錄¶
提供了一種引用文件特定區間的語法，方便將代碼片段直接索引進提示詞。
- 語法：<路徑>#起-止。
- 機制：通過 agent/pre-step 捕獲，發送時會生成對應的 composer chip。
6. 預覽渲染器¶
接管了官方預覽的渲染邏輯。
- 支持主題：Markdown Reader Pro 主題。
- 支持格式：JSON 美化渲染。
安裝與啓用¶
使用 DSH 命令行工具進行安裝，需確保環境滿足最低版本要求。
最低 DSH 版本：0.1.5-rc.2
# 安裝插件
dsh plugin --profile web add "github:victor10035445/dsh-v-explorer"
數據目錄說明：
插件會在工作區根目錄創建 .dsh-v-explorer/ 目錄，該目錄被 .git/info/exclude 隱身，因此對 Git 工作區完全無感（冪等、零工作區改動）。
典型用法¶
安裝後，在 Web 界面右側欄即可看到新增的 bookmarks 頁。
- 使用引用語法：在輸入框中使用
<路徑>#起-止語法，可以將文件中的特定行區間內容直接作爲上下文發送。 - 管理書籤：在
files樹身或bookmarks子樹上點擊右鍵，選擇“加書籤 ★”或“切換展開狀態”。失效的書籤在書籤頁會顯示刪除線。 - 查看變更：文件樹會自動跟隨變更流刷新，消失的節點會即時摘除。
適用場景與注意¶
- 適用對象：DSH Web 用戶，特別是需要頻繁引用文件片段或管理本地代碼書籤的開發者。
- 權限與安全：插件運行在當前 DSH 進程的權限上下文中。讀取文件路徑時會經過詞法 + realpath 雙重校驗，越界訪問會被攔截（403），且文件讀取上限爲 10MB，包含二進制檢測。
- SSE 說明：SSE 通信僅廣播書籤變更事件，不攜帶文件路徑等會話敏感信息。
短結尾¶
dsh-v-explorer 通過插件形式補全了 DSH Web 在文件瀏覽、書籤管理和代碼片段引用上的短板。它通過接管官方組件而非重寫界面，保持了與 DeepSeek Harness 生態的兼容性。更多細節與源碼，可查閱插件目錄或 GitHub 倉庫。
