前言¶
DeepSeek Harness (DSH) 的理念是「一切皆插件」。在智能體開發中，筆記與規則的定義是核心環節。dsh-notes 插件旨在提供一個本地化的 Markdown 筆記存儲方案，通過目錄分組來管理內容，並提供 Web 界面進行交互。它不僅能存儲筆記，還能讀取根目錄或分組下的 AGENTS 等規則文件作爲寫作上下文，幫助模型遵循特定規範進行文件寫入。
安裝與啓用¶
安裝該插件需要執行以下命令：
dsh plugin --profile web add ./dsh-notes
安裝完成後，需要重啓 Web 側欄（profile）才能生效：
pnpm dsh web
重啓後，左側側欄會出現「筆記」入口。
核心功能¶
目錄與筆記結構¶
插件採用本地目錄模型：
- 根目錄：你選擇的本地路徑（默認爲 <DSH_HOME>/dsh-notes）。
- 分組：根目錄下的直接子目錄（二級目錄）即爲分組。
- 筆記：分組目錄下的 .md 文件即爲筆記。
當你寫入筆記時，如果對應的分組目錄不存在，插件會自動創建該目錄。
規則上下文¶
爲了規範寫作，插件支持讀取規則文件。根目錄或分組下匹配（不區分大小寫）以下命名的文件會被識別爲規則文件：
- AGENTS.md
- AGENTS.local.md
- CLAUDE.md
- *.rules.md
- *規則.md / *規則.md
在寫作前，模型可以通過工具讀取這些規則文件，瞭解約定後再執行文件寫入。
Web 界面與工具¶
- 側欄頁面：點擊「筆記」進入管理頁面，可查看分組列表、規則預覽、創建/編輯/重命名/刪除筆記，以及切換根目錄。
- 根目錄切換：支持在頁面內切換根目錄，支持
~符號，留空則恢復默認路徑。切換操作會立即生效並持久化。 - Agent 工具：插件向 DSH 註冊了以下工具：
note_root：查看或切換根目錄。note_list：查看分組概覽，或查看分組下的筆記列表。note_rules：讀取根規則或指定分組規則作爲上下文。note_create：創建或更新筆記（自動創建分組）。note_read：讀取筆記全文。note_delete：刪除筆記。
使用方式¶
默認路徑與切換¶
默認根目錄爲 <DSH_HOME>/dsh-notes。在 Web 頁面中，使用「switch directory」功能指向任何絕對本地路徑（支持 ~）。
規則與筆記的命名¶
- 規則文件和筆記文件共享同一命名空間。
- 如果文件名匹配規則命名規則（如
AGENTS.md），則該文件被視爲規則，無法作爲筆記創建。 - 粘貼完整的 Markdown 文件（包含 Front Matter）會原樣存儲，不會重複包裝。
技術細節與限制¶
- 安全邊界：瀏覽器僅通過受保護的路由訪問數據，不直接接觸磁盤。所有文件操作都經過嚴格的路徑遍歷字符過濾和存在性檢查。
- 數據寫入：Markdown 寫入採用「臨時文件 + 原子性重命名」機制，配合單寫隊列防止併發損壞。
- 大小限制：規則和筆記的讀取有字節限制，超過限制會返回 413 狀態碼。
- 依賴項：
@deepseek-ai/dsh-tools和@deepseek-ai/schemastery爲可選的 peer dependencies，用於擴展功能。
總結¶
dsh-notes 提供了一套完整的本地 Markdown 筆記管理方案，結合 Web UI 與 Agent 工具，使得筆記的創建、管理與上下文讀取變得標準化。它遵循 MIT 協議，適合需要在 DSH 環境中進行本地化知識管理的開發者。
