前言¶
DeepSeek Harness（DSH）的生態理念是「一切皆插件」。在開發或使用 DSH Agent 時，常遇到資料讀後即忘、筆記難以檢索、文檔風格難以統一的問題。dsh-study-buddy 是一個針對這一痛點的插件與 Agent 預設組合，旨在將零散的資料轉化爲結構化、可交互、可歸檔的 Markdown 筆記。
核心功能¶
這個插件通過一套固定的流程，把一份資料講完、問透，並寫成文檔。
-
四步閉環
流程包含：讀取資料 → 講解 → 問答反詰 → 歸檔成文檔。 -
結構化筆記
筆記按資料 / 章 / 節 / 塊的層級成篇。每層都有對應的微目錄作爲導航。文件名不加序號前綴，閱讀順序由文件內的順序鍵與微目錄共同承擔。 -
寫法由你決定
插件不會自動生成統一的模板。它強制要求在 vault 根目錄存在一個筆記期望.md文件。筆記的格式、結構、詳略程度都由這個文件決定。 -
安全歸檔機制
在正式寫入 vault 之前，插件會先列出文件夾規劃供確認。只有確認後纔會落盤。如果路徑不在規劃內或重複消費，寫入操作會被拒絕。 -
純 Markdown 數據
所有筆記都是 vault 裏的普通 Markdown 文件。這意味着你可以直接用 Obsidian 打開編輯，也可以用 Git 進行版本控制。舊筆記在重寫前會自動備份到.study/archive/目錄，支持回退。
安裝與啓用¶
在安裝前，請確保環境滿足以下條件：
* 一份能跑的 DSH 部署（web profile）。
* Node.js 版本 >= 22。
* pnpm 已安裝。
* DSH 版本要求 >=0.1.7-rc.1 <0.3.0-0。
1. 安裝插件¶
使用官方命令將插件添加到 profile 中：
dsh plugin --profile web add dsh-study-buddy
2. 配置 Vault 路徑¶
插件不包含機器路徑，需要你在部署側指定。推薦使用環境變量：
$env:DSH_STUDY_VAULT = 'D:\你的vault絕對路徑'
重啓 DSH 後生效。也可以通過 <DSH_HOME>/study-buddy.json 或覆蓋預設配置中的 vaultRoot 來指定。
3. 配置筆記期望¶
這是插件工作的核心依據。必須複製默認模板到 vault 根目錄：
Copy-Item presets/study/assets/筆記期望.md "D:\你的vault絕對路徑\筆記期望.md"
如果未找到此文件，插件將拒絕寫入筆記。
典型用法¶
安裝並選擇「學習夥伴」預設後，可以通過對話指令控制流程。
-
只讀不講解
如果只想看提取的內容，輸入文件路徑或“讀取X”，插件只會輸出讀取報告，不會自動開始講解。 -
逐步講解
輸入“講解”或“講講”。插件會一次講解一個原子知識點，並在每個點結束後詢問：“清晰？細化 / 跳過？” -
深度問答
遇到不懂的點直接提問。插件會採用“三明治回答”：先給直擊核心的 ≤3 句話，再解釋底層邏輯，最後進行反詰追問，確保理解到位。 -
歸檔與整理
輸入“整理筆記”或“歸檔”，觸發十步歸檔流程。這包括檢查未答追問、讀取期望、生成目錄規劃、等待確認、逐塊寫入、更新微目錄和覆蓋度。 -
繼續學習
如果會話中斷，輸入“接着講”，插件會從上次斷點繼續。 -
修改舊筆記
對舊筆記進行修改時，插件會先展示“舊 vs 新”的對比，確認無誤後才執行寫入。
適用場景與注意事項¶
此插件適合需要將外部文檔（PDF、PPTX等）轉化爲內部知識庫的用戶。它不聯網，但會將其讀取的內容（標題、正文、路徑）發送給模型服務商處理，請勿將敏感數據放入同一個 vault。
升級注意：升級插件後，如果 DSH 沒有自動加載新代碼，需要刪除 profile 目錄下的 node_modules\dsh-study-buddy，然後重新運行 pnpm install。
總結¶
dsh-study-buddy 是一個將資料消化、內化、歸檔的完整工作流工具。它通過嚴格的文件夾規劃、可定製的 Markdown 寫法以及純文本的數據格式，確保了知識沉澱的可控性與可追溯性。
