前言¶
在使用 DeepSeek Harness（DSH）時，對話內容很容易在會話結束後散落。如果不做記錄，後續查找和整理會很麻煩。現有的做法通常是手動複製粘貼到文檔，既耗時又容易遺漏。
dsh-study-note 是一個 DeepSeek Harness 插件，它讓對話按需自動生成結構化的 Markdown 筆記，並維護一個根目錄索引。每個對話在開始時默認關閉記錄，你需要顯式啓用，這樣不會影響其他對話。
是什麼¶
dsh-study-note 是 WaterFountain-Jack 維護的 DeepSeek Harness 插件。它將顯式開啓的對話轉化爲 Markdown 學習筆記，併爲每個筆記創建單獨的文件，同時維護一個根目錄的 README.md 索引。
插件通過 /note 命令集控制記錄開關、同步、狀態查看和主題管理。筆記內容包含問題、結論、解釋、公式/代碼/示例、AI 起草的理解、未解問題和源輪次編號等區域。後續相關追問會更新同一區域，不相關追問則新增區域。
安裝與啓用¶
安裝前請確保已安裝 Node.js 22.19+，並有一個提供 commands、sessions 和 llm 的 DSH 配置文件。插件依賴 DSH 0.1.0-rc.8、0.1.1-rc.2 或 0.2.0-rc.2。
- 克隆插件倉庫，安裝依賴，打包成安裝包：
git clone https://github.com/WaterFountain-Jack/dsh-study-note.git
cd dsh-study-note
npm install
npm pack
- 將打包後的
.tgz文件安裝到你指定的 DSH 配置文件中。示例中假設配置文件名爲desktop：
dsh plugin --profile desktop add "$PWD/dsh-study-note-0.1.1.tgz"
dsh --profile desktop --dump-config
-
如果 DSH 沒有熱加載插件，請重啓該配置文件。
-
在對話中依次發送以下命令，然後提出學習問題並等待回答：
/note on Cordis
/note status
- 錄製會在回答結束後在後臺運行。使用以下命令檢查和同步：
/note sync
/note status
查看生成的文檔和根目錄索引。完成後使用 /note off 關閉當前對話的記錄。
卸載時保留筆記和本地狀態：
dsh plugin --profile desktop remove dsh-study-note
命令參考¶
| 命令 | 行爲 |
|---|---|
/note on [topic] |
開啓當前對話的記錄，僅處理開啓後開始的完整輪次。重複使用不會重置檢查點。 |
/note off |
取消並等待後臺工作完成，保留已有文件。成功後不再對新輪次寫入。 |
/note status |
顯示開關狀態、目錄、主題、文件、待處理工作和最新錯誤。 |
/note sync |
立即處理所有符合條件的已完成輪次。需要在開啓狀態下運行，不會回填關閉期間的輪次。 |
/note topic <topic> |
固定主題並移動當前對話的筆記，重建索引。 |
/note reindex |
重建插件擁有的根索引，無需模型調用。可在關閉時使用。 |
/note new |
清除關聯，需在舊筆記刪除或移出根目錄後使用。會自動關閉記錄。 |
主題命名規則：1–64 個字符，允許字母、數字、下劃線、連字符或中文字符，必須以字母或數字開頭。固定主題可以創建目錄，自動主題選擇僅使用現有目錄，否則使用 inbox。子代理對話無法開啓記錄。
筆記與索引結構¶
筆記保存在配置的 notesDir 目錄下，結構如下：
~/.dsh/study-notes/
├── README.md
├── Cordis/
│ └── 2026-10-15-Cordis-學習-<session-hash>.md
├── inbox/
└── .study-note/
├── state.json
├── writer.lock
└── requests/
每個文檔對應一個對話。相關問題時一個包含問題、結論、解釋、公式/代碼/示例、AI 起草理解、未解問題和源輪次編號的區域。後續相關追問會更新同一區域，不相關追問則新增區域。手寫區域不會被替換，相關追問會追加補充區域。索引只維護 README.md 中 <!-- dsh-study-note:index:start --> 和 <!-- dsh-study-note:index:end --> 之間的內容，外部手寫條目保持不變。插件僅索引自己的文檔，不會自動整理無關筆記。
配置說明¶
插件條目 ID 爲 study-note，可選通過覆蓋層指定不同的根目錄：
- id: study-note
config:
notesDir: '~/study-notes'
保存覆蓋層並在啓動時傳入 --patch <絕對覆蓋路徑>，或者將條目合併到你的配置覆蓋中。項目不會修改活動配置或現有知識庫。
| 字段 | 默認值 | 含義 |
|---|---|---|
notesDir |
~/.dsh/study-notes |
絕對路徑或 ~/ 路徑，每個同時運行的 DSH 進程建議使用獨立目錄。 |
debounceMs |
1500 |
完成輪次後延遲多少毫秒開始後臺處理。 |
timeoutMs |
60000 |
輔助請求截止時間，包括審計寫入。 |
provider、model |
缺失 | 同時提供非空字符串以覆蓋，否則複用已完成回答的路徑。 |
maxInputBytes |
98304 |
整個分幀輔助請求的 UTF-8 限制，超大會導致明顯失敗。 |
maxOutputBytes |
65536 |
序列化流塊的限制，不僅包括最終文本。 |
maxOutputTokens |
4000 |
輔助輸出 token 上限。 |
recentSections |
6 |
作爲後續上下文提供的最近筆記區域數量。 |
maxMessageChars |
12000 |
每個問題、回答或區域文本的限制，截斷會明確標記。 |
隱私、成本與故障處理¶
從未開啓的對話不會產生記錄文件或輔助模型調用。錄製只選擇人類源文本和未來已完成輪次的最後一個完整助手文本，排除推理塊、工具結果、圖像、注入用戶消息和中斷輸出。本地過濾掉確切確認消息和進度問題，其他無關輪次仍可能需要模型調用以決定是否跳過。
每個符合條件的輪次可能觸發對配置提供者的額外付費請求，包括被跳過的內容。同一對話同一時間只運行一個請求，不同對話可併發運行。先前的筆記區域，包括你在這些區域中的編輯，可以進入這些請求。插件不會讀取 API 密鑰或環境值，但對對話文本中輸入的密鑰不會進行脫敏。
請求分派前，系統提示、消息路由、token 限制和源事件編號會寫入 .study-note/requests/。這些本地審計文件會保留選定的對話文本，即使模型跳過該輪次或隨後關閉記錄。新文件所有者權限，未加密，現有父目錄權限不會收緊。關閉或卸載不會刪除文件，沒有自動保留清理。
輔助請求不會插入到主模型歷史或 DSH 會話日誌中。測試過的宿主無法安全註冊外部信息會話事件，因此重放需要將插件審計目錄與 DSH 對話日誌放在一起。錄製期間沒有 shell 命令或模型工具執行。
模型錯誤、無效 JSON、截斷完成、文件缺失、標記損壞和權限錯誤通過 /note status 和運行時日誌報告。修復原因後使用 /note sync，失敗模型工作重試時可能會再次計費。狀態、索引和筆記是獨立的原子文件替換，不是一次性事務；索引失敗可能留下已保存筆記，同步重建不會重新生成已提交輪次。崩潰可能導致重複模型計費，但筆記元數據會在恢復時防止重複提交區域。
適用場景與注意事項¶
適合需要長期保存對話內容、按主題組織學習筆記、希望自動維護索引的開發者和學習者。插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證。
敏感對話請謹慎開啓記錄，除非你對提供者的本地保留策略可以接受。插件不會自動清理歷史數據，卸載不會刪除已生成的筆記和審計文件。建議定期手動整理和備份筆記目錄。
