前言¶
在 DSH 裏跑 agent 時，常見需求是把決策、摘錄或模板寫進工作區文件，並在後續回合裏繼續讀改。若只靠通用寫文件工具，缺少「讀—改—寫」之間的版本校驗，併發或重複編輯容易互相覆蓋。下面介紹社區插件 dsh-notes（維護者 LIghtJUNction，目錄分類爲「記憶」）：它在工作區 .dsh-notes/ 下提供平面 Markdown 筆記與模板，更新和刪除必須攜帶上次讀取返回的 revision（內容爲 UTF-8 的 SHA-256）。插件不提供自動會話召回、後臺記憶，也不是 DSH session-search 的替代實現。
這是什麼¶
dsh-notes 是面向 DSH 0.2.1-rc.2 的 Markdown 筆記工具，npm 包名 @lightjunction/dsh-notes，當前資料中的版本爲 0.1.0，許可證 MIT。筆記保存在 .dsh-notes/notes，模板保存在 .dsh-notes/templates。所有文件操作走 DSH 進程所在主機的 Node 本地文件系統，不是遠程 world 或 sandbox；僅在 host-local 工作區啓用。
核心功能¶
插件通過 Cordis 註冊工具 id dsh-notes，向 agent 暴露五類操作：
| 工具 | 主要參數 | 行爲 |
|---|---|---|
notes_list |
collection? |
按名稱列出筆記或模板，最多 1000 項，超出時返回 limited: true |
notes_read |
path, collection? |
返回 { path, content, revision } |
notes_create |
path, content, template?, collection? |
新建文件，拒絕覆蓋；可選模板原文加在 content 前（不自動加換行） |
notes_update |
path, content, revision, collection? |
revision 匹配後整文件替換 |
notes_delete |
path, revision, collection? |
revision 匹配後永久刪除 |
collection 只能是 notes（默認）或 templates。模板與筆記共用同一套讀寫刪工具。
約束要點（與 README 一致）：
- 文件名：平面 ASCII，首字符爲字母或數字，其餘爲字母、數字、點、下劃線或連字符，以
.md結尾，最長 123 字符；不支持子目錄、絕對路徑、重命名或 Pi TUI。 - 單文件上限 256 KiB；拒絕符號鏈接目錄/文件，拒絕讀取硬鏈接文件。
- revision 相同內容相同，不是遞增序號，無法檢測「改回原內容」的 ABA 情況。
- 多進程寫同一 store 時用
.dsh-notes/.write-lock協調；鎖忙需重試，崩潰遺留鎖需確認無寫入者後手動刪除。
安裝與啓用¶
面向 Node 24+（README 寫明本地驗收爲 Node 26）。GitHub Release 發佈 v0.1.0 後，可按 tarball 安裝；README 註明該說明不表示版本一定已發佈：
dsh plugin --profile tui add https://github.com/LIghtJUNction/dsh-notes/releases/download/v0.1.0/lightjunction-dsh-notes-0.1.0.tgz
包內自帶 cordis.patch.yml。在 profile 的 cordis.patch.yml 或 --patch overlay 中配置：
- id: dsh-notes
config:
root: /absolute/path/to/project
不設置 root 時，使用調用 agent 的 workingDirectory 服務；沒有 agent 的直接工具調用必須提供 root。
典型用法¶
1、創建模板與基於模板的筆記
先建模板，再創建引用該模板的筆記：
{"tool":"notes_create","arguments":{"collection":"templates","path":"decision.md","content":"# Decision\n\n"}}
{"tool":"notes_create","arguments":{"path":"cache.md","template":"decision.md","content":"Use a bounded local cache."}}
{"tool":"notes_read","arguments":{"path":"cache.md"}}
2、帶 revision 的更新
將 notes_read 返回的完整 revision 填入下一次更新：
{"tool":"notes_update","arguments":{"path":"cache.md","revision":"<revision returned by notes_read>","content":"# Decision\n\nUse a 256-entry local cache."}}
3、用自然語言驅動 agent
也可以直接要求 agent：「把我明確選擇的這段對話摘錄保存到 decision.md。」agent 通過 notes_create 保存你給出的文本；插件不會自動讀取或導出整段會話。
適用場景與注意¶
適合誰： 需要在當前 DSH 工作區裏維護少量結構化 Markdown（決策記錄、緩存策略說明、可複用模板），並希望通過 revision 降低併發覆蓋風險的開發者。
務必知曉：
- 筆記內容會進入模型上下文與正常工具記錄，不要把密鑰等祕密寫進筆記。
- 工具在 DSH 進程權限下運行，安裝前請自行查看源碼與 MIT 許可證。
- 不要在插件寫入期間用外部編輯器改同一文件；插件不是 OS 級權限隔離。
- 社區目錄頁 skillhub.cn 上的 dsh-notes 與 GitHub 倉庫由社區維護，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，目錄站是獨立站點。
結尾¶
dsh-notes 把「列表 / 讀 / 建 / 改 / 刪」收斂到 revision 校驗的 Markdown 文件上，適合作爲 agent 可調用、可審計的本地筆記層，而不是全自動記憶系統。進一步細節見 GitHub：LIghtJUNction/dsh-notes。
