前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，任務往往會落在三個時間尺度上：跨項目的長期跟進、當前倉庫裏的開發事項、以及這一次會話裏要立刻做完的幾步。如果把它們都寫進對話或零散備忘錄，切換工作區或新開會話後很難對齊上下文；讓智能體改待辦，又需要明確邊界，避免誤改你手寫的內容。
TODO 便籤（dsh-todo-notes）是社區維護者 BlazeNebula 發佈的 DSH 插件（package 版本 1.0.1，MIT）。它在客戶端提供用戶級、工作區級、會話級三組待辦，數據全部落在本機 $DSH_HOME/todo-notes/，並通過一組 Agent 工具在 DSH 審批下讀寫條目。下面介紹安裝方式、界面用法、設置項與智能體側能力。
插件定位與數據模型¶
插件在 DSH 裏註冊 Web 客戶端與宿主側 HTTP 路由 /dsh-todo-notes/api，面板通過該路由讀寫本地文件；插件自述不發起外網請求。每條 TODO 存爲一個 Markdown 文件，frontmatter 含 id、title、status（todo / partial / done）、created、updated、source、priority、primaryFolder 等字段。
三個層級互不混用：
- 用戶級：跨項目長期事項，任意工作區可見。
- 工作區級：按工作區目錄分開存放。
- 會話級：僅屬當前會話；切換會話時，會話組自動換成對應內容。當前工作區與會話的組標題爲斜體，懸停可見工作區路徑或會話 ID。
浮動面板與右側欄「TODO 便籤」頁籤展示同一份數據，任一側修改會即時同步。
安裝與生效¶
官方 README 給出的安裝方式如下，未提供 dsh plugin add github:... 一類命令，安裝時請按文檔操作：
- 在 DSH 插件市場搜索「TODO 便籤」安裝。
- 若市場尚未收錄，在插件頁填寫倉庫地址
https://github.com/BlazeNebula/dsh-todo-notes，或選擇本地目錄安裝。 - 安裝完成後，右上角會出現浮動面板，右側欄頁籤中也會出現「TODO 便籤」。
生效規則需要區分兩類改動：
- 僅客戶端改動：按
Ctrl+R刷新即可。 - 新增插件或設置頁等宿主側改動：需完全退出 DSH（含托盤圖標）後重新啓動。
插件以當前 DSH 進程權限運行；安裝前建議在 GitHub 查看源碼與 LICENSE（MIT）。社區目錄頁：skillhub.cn 上的 dsh-todo-notes。該目錄爲社區獨立站點，與 DeepSeek / 幻方無官方從屬關係。
快速上手¶
- 在浮動面板中點擊組標題右側的「+」，創建第一條 TODO。
- 單擊條目打開 Markdown 預覽；在預覽右上角點編輯，可改標題與正文。
- 拖動面板標題欄移動位置，拖右下角調整大小；位置與尺寸會記住。
- 勾選表示完成；智能體勾選的條目會先進入半完成，待你確認。
組織、預覽與批量¶
文件夾與優先級：可建嵌套文件夾；一條 TODO 有主歸屬，也可被多個文件夾收錄。優先級爲 T0～T9（T0 最高）。拖動可排序；拖到另一文件夾會移動主歸屬；按住 Ctrl 拖動僅增加收錄。支持框選、Shift 連續選擇及批量移動、收錄、改優先級、重命名或刪除。
預覽窗口：單擊打開臨時預覽；拖預覽標題欄可保留爲獨立窗口，可多開，刷新或重啓後恢復位置與內容。同一條目只保留一個預覽窗口，再次打開會置頂已有窗口。編輯時標題爲輸入框，正文編輯 frontmatter 之後部分；停止輸入後自動保存（間隔可在設置中配置）。
勾選三態：未完成、半完成（智能體勾選待確認）、已完成（人工確認）。單擊勾選框切換；雙擊勾選區域可直接完成。
設置與 Config 默認值¶
路徑：設置 → 左側「TODO 便籤」，或從插件列表進入，爲同一設置頁。
- 狀態外觀：未完成 / 半完成 / 已完成行透明度（默認已完成 35%、半完成 67%）。
- 優先級顏色：T0～T9 十檔，支持取色器或十六進制輸入。
- 編輯與保存：「允許智能體修改你手寫的條目」默認關閉，開啓後每次寫入仍須 DSH 審批；正文與標題停止輸入後的保存間隔（秒，默認 5）；標題最大長度（默認 30 字，超長時面板截斷並提示，智能體工具會拒絕並返回當前字數）。
設置保存在本機 ui-settings.json；點「保存」後立即作用於所有面板。插件 Config 中的 agentWriteUserTodos 與 bodyAutosaveMs 在未改過設置頁時作爲默認值，改過以後以設置頁爲準。
智能體工具¶
智能體通過以下工具操作便籤（列表類不返回正文）：
| 工具 | 作用 |
|---|---|
todo_notes_list |
按範圍列摘要 |
todo_notes_read |
按 id 讀正文與屬性 |
todo_notes_create |
新建條目 |
todo_notes_update |
改標題、優先級、狀態或文件夾 |
todo_notes_toggle |
勾選或取消勾選 |
todo_notes_delete |
刪除條目 |
智能體勾選最多爲半完成，最終完成須由你確認。修改手寫條目需先在設置中開啓許可，且每次寫入經過 DSH 審批；拒絕或無法審批時不寫入。
本機目錄結構¶
$DSH_HOME/todo-notes/
windows.json # 保留窗口的位置、尺寸與內容
ui-settings.json # 外觀、自動保存、標題長度、智能體權限
user/ # 用戶級
workspaces/<工作區 slug>/
sessions/<會話 id>/
適用場景與注意¶
適合需要在 DSH 內長期維護待辦、並希望智能體在明確審批與半完成機制下協助增刪改的場景。不適合依賴雲端同步或多設備共享的需求——數據僅本機存儲。
開發側：lib/ 爲宿主邏輯，client/src/ 構建爲單文件 client/client.js；改客戶端後執行 node scripts/build-client.mjs 或 npm run build:client，npm run check 做語法檢查。
結尾¶
TODO 便籤把用戶 / 工作區 / 會話三層待辦、文件夾與優先級整理、以及審批下的 Agent 工具收進同一套本地面板。安裝與細節以倉庫 README 爲準：GitHub：BlazeNebula/dsh-todo-notes，目錄頁：skillhub.cn/plugins/BlazeNebula/dsh-todo-notes。
