前言¶
在 DeepSeek Harness (DSH) 的對話過程中，想法、決策、實施細節和後續任務會不斷湧現。這些內容如果僅停留在聊天記錄中，容易淹沒或丟失。同時，在 DSH 和其他編輯器之間頻繁切換會打斷工作流。
dsh-notes-markdown 插件旨在 DSH 的側邊欄提供一個輕量級、持久化的 Markdown 筆記空間。它允許你在保持當前對話可見的同時，直接記錄決策、計劃、API 和任務，且無需切換窗口。
定位¶
該插件由維護者 Tieboyh 開發，核心定位是：
* 持久化筆記：側邊欄內的 Markdown Notes 頁面，長期駐留。
* 真實文件：每個筆記都是本地 .md 文件，默認存儲在 ~/.dsh/docs，可直接被編輯器、Git、腳本和智能體訪問。
* 工作流整合：通過一鍵創建、自動保存、實時預覽和源碼模式，將文檔管理融入 DSH 流程。
核心功能¶
該插件提供以下具體能力：
- 文檔創建與管理：支持一鍵創建筆記（使用當前工作區名稱和自動編號），支持打開、搜索、重命名和刪除。筆記列表可摺疊，並會記住用戶的展開/收起狀態。
- 雙模式編輯：支持 Typora 風格的實時預覽（Live edit）模式和精確的源碼模式（Source mode）。源碼模式適用於需要精確控制 Markdown 或使用不支持的擴展時。
- GFM 渲染與支持：支持 GitHub Flavored Markdown (GFM) 的實時渲染，包括標題、鏈接、列表、任務列表、引用、表格和圍欄代碼塊。
- 自動保存與狀態反饋：輸入停止約 700 毫秒後觸發自動保存，界面會有保存狀態提示。切換或重命名文檔前會先刷新未保存內容。
- 內容與路徑操作：支持複製當前 Markdown 內容，或複製文檔的絕對文件路徑（便於與智能體協作）。
- 衝突檢測與安全：包含版本檢查機制，當另一個 DSH 窗口修改了文件時，會報告衝突而不是覆蓋新內容。支持原子保存、重複名稱保護、路徑遍歷保護和符號鏈接拒絕。
安裝與啓用¶
- 安裝本插件：
dsh plugin --profile web add github:Tieboyh/dsh-notes-markdown
- 安裝、升級或移除插件後，需重啓 DSH Web 才能生效。
- 在 Better Sidebar 的
+菜單中找到並打開 Markdown Notes。
典型用法¶
- 邊聊邊記：在 DSH 對話窗口中記錄技術設計、API 調試計劃或實施檢查清單。
- 保持文件流：將對話中產生的想法保存爲本地
.md文件，確保數據不丟失且可被後續處理。 - 智能體協作：複製筆記的絕對文件路徑，直接交給同一環境下的智能體使用。
- 常見場景：技術設計文檔、API 記錄、會議結論、可複用提示詞、代碼片段及 Mermaid 流程圖源碼。
注意事項¶
- 存儲位置：筆記默認存儲在
~/.dsh/docs目錄，目錄會自動創建。若需使用不同目錄，可在啓動 DSH Web 前設置環境變量DSH_NOTES_MARKDOWN_DIR。 - 文件名限制：當前版本筆記存儲在單層目錄中，文件名不能包含
/、\、隱藏文件前綴（如.）或路徑遍歷段。 - 版本機制：編輯停止約 700 毫秒後觸發保存。若檢測到文件在他處被修改，會提示衝突。
結語¶
dsh-notes-markdown 通過文件級持久化和側邊欄集成，解決了 DSH 用戶在對話過程中記錄和保存關鍵信息的痛點。它讓筆記管理變得輕量且透明，適合需要頻繁記錄和查閱技術文檔的開發者。
