前言¶
在 DSH 裏幹活的人大多會遇到這類問題：想在對話間隙記點什麼，AI 聊天框的輸入體驗卻很彆扭；筆記存在別的應用裏，思路和維護的成本又上去了。dsh-notes 是維護者 tyouter 給自己寫的插件，定位是 DSH 內部的一個筆記本：一個輸入框，一個實時排版的預覽，只在需要判斷時才調用模型。
下面介紹它的定位、安裝方式和典型用法。
這是什麼¶
tyouter/dsh-notes 是一個 DSH 插件，npm 包名 @tyouter/dsh-notes，當前版本 1.1.2。它以三個頁籤的形式工作：Capture、History、Board。它是客戶端分類下的插件，屬於 npm 上的 bundle，一個安裝裏同時包含宿主半部分、web panel 和 agent presets。
解決的問題可以歸納成三項：
- 打開工具時還想得起要寫什麼——需要一個啓動即寫、不需要點工具欄的界面；
- AI 聊天框的輸入難受，複雜筆記應用又不斷打擾——需要一個”紙”而不是一個”編輯器”；
- 寫完的筆記沒人看、沒人理——需要 AI 在頁面邊緣等着，而不是插在正文裏。
核心功能¶
一張”紙”。 Capture 頁只有一個輸入框和一張預覽頁。排版規則很簡單：輸入的格式只有空格和換行，兩個空格生成一個列表項，四個空格生成下一級，手不需要離開鍵盤。保存時寫入的是排版後的文本，預覽不是提示而是承諾。
本地排版。 Format 動作是確定性的本地函數 formatLocally，不發請求也沒有按鈕。它做的工作是規範化分隔符、編號、空行和散落的星號，不動措辭，並且冪等。
AI 在邊緣。 Structure 調用模型對當前筆記（或選中的範圍）做改寫，生成一份草稿，可以選擇 Apply、Save 或 Translate；Translate 改變語言，Apply 只替換對應範圍。狀態欄裏等待，你需要時纔回答。
歷史與看板。 History 把筆記分組成卡片，可以篩選、搜索、打標籤；編輯歷史條目時會把 Capture 的輸入框掛上去，源碼在左、排版結果在右，是一個編輯器而不是兩個。Board 頁是統計信息加上一個真正的 agent session，跑 notes-board 預設，用的是宿主自帶的對話組件。
文件即真相。 筆記以普通 JSON 文件存放，數據庫是可以刪掉重建的投影。README 上的路徑結構如下，完整路徑取決於工作區。
notes-vault/
notes.json live notes (source of truth)
trash.json deleted notes, kept as a safety net
links.json which session belongs to the notebook
events.jsonl append-only instrumentation: AI calls, UI actions, charts
dashboard.json charts pinned to the dashboard
index.db SQLite projection of the above, for the query tools
不上傳。 模型調用走宿主自身的 llm 服務，用 DSH 已配置的 provider 和 key。看板的 assistant 是一個真實的 agent session，工具只有 notes_query（對 index.db 的只讀單條 SELECT）、notes_analyze、dashboard_chart 和讀寫筆記的 notes 工具。
三種 AI 面，三種機制。 這一點在 README 裏被單獨強調：早期版本曾把截斷的文本塞進 prompt，就是因爲把三種機制混在了一起。
- Structuring 是一次流式模型調用，沒有 session 也沒有工具，推理 effort 設爲
off； - Completion 只在停止輸入一秒後請求下一句，否則用筆記裏重複出現的措辭回答，不發請求；
- Board 聊天是建好的 agent session，面板只負責創建和渲染，投遞、流式、工具卡片和審批全部由框架負責。
輸入框之外也能用。 Alt+N 或輸入組件行上的筆記本圖標會打開一個浮動卡片；/note 內容 可以直接從聊天框保存一條筆記。
安裝與啓用¶
包在 npm 上，官方安裝命令只有一條，從 DSH 裏帶 profile 執行：
dsh plugin --profile <name> add @tyouter/dsh-notes
安裝後如果安裝程序沒有自動處理，需要在 profile 的 package.json 裏把 @tyouter/dsh-notes 加到 dsh.profile.bundles，然後重啓。插件會出現在側邊欄和插件清單裏，名字叫 Notebook。
從源碼構建的話，README 給出的路徑是 clone 下來跑構建，再把目錄通過 Plugin Manager / install_bundle 裝進去：
git clone https://github.com/tyouter/dsh-notes.git
cd dsh-notes
npm run build # writes client.js from src/
# then install the directory through Plugin Manager / install_bundle
要求：DSH 構建需要帶 node:sqlite（Node 24 自帶），lib/ 下都是第一方代碼，沒有其他運行時依賴。若 node:sqlite 缺失，查詢工具會自行禁用並說明，筆記本其他功能照常可用。
配置方面，cordis.patch.yml 裏的 notesPath 可以改筆記目錄；相對路徑錨定的是註冊表裏的默認工作區，不是第一個調用它的 session。
典型用法¶
- 裝好後打開側邊欄的 Notebook，停在 Capture 頁；
- 直接在一個框裏輸入，兩個空格做列表，四個空格做下一級，右邊頁面逐鍵排版；
- 想讓 AI 整理結構時，點工具欄的 Structure，右側出現草稿，可以 Apply、Save 或 Translate；
- 選中編輯器裏的文字再翻譯，作用範圍就是那一段；
- 到 History 頁翻歷史筆記，搜索或按標籤過濾；需要改某條時，點 Edit 掛載輸入框，左右兩個視圖共用一份源碼；
- 在 Board 頁跟
notes-board對話，讓它統計筆記的by_tag、by_day、長度分佈等，或用dashboard_chart在看板上釘一張圖。
適用場景與注意¶
適合寫筆記頻繁、又不想讓筆記應用打斷思路的人。它把”寫作”和”AI 輔助”分開：排版不發請求，AI 只在需要判斷時出現。對 DSH 使用者來說，它的價值在於筆記和宿主共用一個模型配置。
兩點需要留意。第一，插件以當前 dsh 進程的權限運行，安裝前應先檢查源碼與許可證；本插件許可證爲 MIT，作者 tyouter，倉庫 https://github.com/tyouter/dsh-notes 。第二，它的 agent 會話帶有讀寫筆記的工具，別把它當成一個只讀的展示面板。
結尾¶
dsh-notes 的取捨很明確：把存儲做簡單（JSON 文件），把排版做成確定性的本地步驟，把 AI 留在邊緣。這樣一個插件的安裝是一個 profile 綁定，代價不大。目錄頁在 https://www.skillhub.cn/plugins/tyouter/dsh-notes ，源碼與 README 在 https://github.com/tyouter/dsh-notes 。
