前言¶
DSH（DeepSeek Harness）採用插件化架構。在會話中預覽 Markdown 報告或文檔時，若切換到外部編輯器會打斷上下文，直接在對話中展示又缺乏良好的排版與交互。dsh-md-overlay 插件通過引入一個可懸浮/可停靠的 Markdown 預覽面板，以及一個 md_preview 模型工具，解決了這一痛點，實現了會話內的一鍵預覽。
插件定位¶
這是一個 DSH Web 客戶端插件，由 2017java 維護，採用 MIT 許可證。
插件提供兩個核心能力：
1. md_preview 模型工具：讀取 workspace 內的 .md 文件並觸發面板預覽。
2. 預覽面板：支持浮層/停靠雙模式、多標籤頁管理、寬度拖拽調整，以及代碼塊語法高亮。
核心功能¶
- md_preview 模型工具：該工具註冊爲全局工具，所有會話可見。當調用該工具時，插件會讀取 workspace 內的 Markdown 文件，並在對話中展示預覽卡片，同時打開右側預覽面板。
- 浮層 / 停靠雙模式：默認狀態下，面板懸浮在內容之上。點擊面板頭部的 📌 圖標可將其停靠，推擠頁面佈局融入；再次點擊可恢復懸浮。
- 多標籤與拖拽：支持一次打開多個文檔，點擊標籤切換，逐個關閉。面板寬度可通過左緣拖拽調整，範圍在 320px 到 75% 屏寬之間。
- 代碼塊渲染：支持 JS/TS/Python/Bash/YAML/HTML/CSS 語法高亮，顯示行號、語言徽標，並提供一鍵複製功能。
- 目錄與列表：自動收集文檔標題生成目錄（TOC），點擊可平滑滾動至對應章節。支持任務清單（
- [x]）和嵌套列表。 - HTML 處理：自動剝離 HTML 註釋，進行實體反轉義，確保渲染安全。
- 安全邊界：插件僅讀取 workspace 內的文件，文件大小超過 1MB 時會被拒絕加載。
安裝與啓用¶
前置條件：確保 DSH（dsh web）可正常運行。
dsh plugin --profile web add dsh-md-overlay@latest
安裝完成後，請硬刷新瀏覽器（Cmd/Ctrl + Shift + R）以加載新插件。
典型用法¶
- 指令觸發：在對話中輸入“預覽一下 report.md”，Agent 調用
md_preview工具，右側面板會自動打開並渲染該文檔。 - 產物點擊：對話中如果出現“產出文件”等 .md 產物，直接點擊該文件名，面板會自動打開並展示內容。
注意事項¶
- 相對路徑圖片：暫不支持解析 Markdown 中的相對路徑圖片。
- 特殊語法：暫不支持 LaTeX 和 Mermaid（這些是 better-sidebar 的強項，本插件規劃中未包含）。
- 觸發機制：預覽卡片和麪板只在
md_preview工具被調用，或者點擊 .md 產物後纔出現，其他類型文件會交給系統默認應用或側邊欄處理。
總結¶
dsh-md-overlay 適合需要在 DSH 會話中頻繁查看 Markdown 文檔、代碼報告的用戶。它通過提供一個懸浮且可嵌入佈局的預覽窗口，減少了應用切換成本。
