前言¶
做智能體應用時，待辦工具回答的是「還有什麼沒做」。用戶真正關心的往往是另一個問題：這條待辦從建到完花了多久。dsh-todo-time-log 做的是把待辦和耗時合併成一件事：管理待辦的同時自動記錄創建時間與完成時間，再用表格、看板、甘特圖、日曆四種視圖呈現真實耗時。
下面介紹這個插件。它是 FantasyStarry 維護的 DeepSeek Harness（DSH）插件，分類是工作流，許可證爲 MIT，npm 包名 dsh-todo-time-log。已有的待辦方案多停留在清單層面，要麼只有時間字段卻缺少視圖組織，要麼視圖齊全但不記錄完成時刻。它把「記賬」和「看賬」接在一起，數據存在本地 JSON 文件，不聯網、不上傳。
一、核心能力¶
時間記錄是默認行爲，不是配置項。每條待辦寫入創建時刻（本地時間 YYYY-MM-DD HH:mm:ss），完成時自動寫入完成時刻，未經完成就顯示 -。重複完成、重複取消會給出明確提示。表格的「完成時間」列直接給出「用時 / 進行中」兩行，未完成的條目同時顯示已耗時與「進行中」標記。
四種視圖共用同一份數據卡片，切換視圖保留當前篩選與排序，排序統一走表頭：
- 表格：創建時間、完成時間兩列是主角。
- 看板：按狀態分列，卡片帶優先級、類型與用時；支持按狀態、分類或狀態×分類泳道分組，泳道可摺疊、可在裏面新建。
- 甘特圖：一根條 = 創建 → 完成，未完成的條目延伸到「現在」；支持按分類分組，可切換全部 / 近 7 天 / 近 30 天。甘特圖是純前端計算，不新增接口。
- 日曆：按創建或完成時間落格，點某天處理當天全部條目。
每條待辦還可以帶分類、優先級（高 / 中 / 低）、類型（缺陷 / 新功能 / 改進 / 疑問 / 雜項 / 其他）；用 @工作區文件 關聯代碼文件時，如果沒有顯式分類，會自動取文件所在目錄作爲分類。
二、四種錄入入口¶
面板表單、對話式一句話、/todo 斜槓命令、智能體工具 todo_time_log 四個入口共用同一套解析規則（lib/parse.js 的 parseQuickAdd()），不存在兩邊規則漂移。
標記語法三處通用：
新任務 寫週報 #工作 @src/auth/login.ts
修復登錄缺陷 #工作 !high ^bug
買牛奶 @生活；回郵件 [工作]
項目：學習 整理筆記，讀完第三章
- 分類：
#工作/@生活/[工作]/項目：工作/分類：工作，取最左的非空值，並從標題裏剝離。 - 優先級：
!high/!medium/!low，也接受!h!m!l與中文!高!中!低；未寫則回退到表單選擇器。 - 類型：
^bug/^feature/^improvement/^question/^chore/^other，也支持中文與類型：bug/type:bug；未知值保留原文。 - 文件：
@路徑/文件、@"docs/My File.md"，記爲工作區相對路徑。 - 多條：換行、
；、;分隔；只有填充詞的行會被跳過，不會創建空待辦。
智能體工具掛在 todo_time_log 上，支持 list / get / create / complete / uncomplete / update / delete / health，與 UI 共用同一實現：
todo_time_log { "action": "create", "title": "修復登錄", "priority": "high", "type": "bug" }
todo_time_log { "action": "list", "filter": "pending", "sortBy": "priority", "direction": "asc" }
todo_time_log { "action": "complete", "id": "ttl_…" }
數據文件路徑爲 <DSH_PROFILE_DIR 或 ~/.dsh>/todo-time-log/todos.json，用臨時文件 + rename 原子替換、寫入串行化、跨進程文件鎖保護；文件損壞時自動備份並重建。頁頭「數據」菜單提供 JSON 無損備份與 CSV 導出（給 Excel 統計）；導入先預覽再寫入，支持合併 / 僅新增 / 覆蓋全部，自動備份並可直接撤銷。面板快捷鍵：/ 聚焦搜索、n 聚焦新建、f 循環切換篩選。
三、安裝與啓用¶
要求：DeepSeek Harness >= 0.2.0-rc.2 < 0.2.3-0（engines.dsh 聲明，已在 0.2.2-rc.1 真機驗證），Node.js ≥ 20。
在插件管理器（Plugin Manager）裏安裝 bundle，包名填 dsh-todo-time-log。也可以讓當前會話的智能體執行安裝：
plugin_manager action=install_bundle target=dsh-todo-time-log
安裝會執行包安裝（pnpm）、寫入 dsh.bundle.patch 聲明的 Host 行並啓用 bundle。只有返回 application: "applied" 纔算真正生效。Host 半改動需要關閉再開啓插件（或重啓桌面端）纔會加載新模塊；Client 半（dsh.client.immediately）隨下一次頁面刷新加載。安裝成功後，左側導航出現「待辦時間日誌」入口，Plugin Manager 中能看到中文名稱、描述與圖標。
本地開發用 link 方式安裝，target 換成本地倉庫絕對路徑；修改 lib/*.js 後同樣需要關閉再開啓插件（或重啓桌面端）加載新的 Host 模塊，UI 改動刷新頁面即可。卸載：
plugin_manager action=remove_bundle target=dsh-todo-time-log
卸載後數據文件保留，手動刪除 todos.json 即可清空。
配置數據文件路徑有兩條外部途徑，當前構建未導出 Config schema，插件詳情頁沒有配置表單，所以只能走這兩種方式：
# cordis.patch.yml 行配置（優先級最高），寫入 plugin 的 config
config: { dataFile: 'D:/data/todos.json' }
# 環境變量 DSH_TODO_TIME_LOG_DATA（優先級次之）
export DSH_TODO_TIME_LOG_DATA=D:\data\todos.json
兩者都不設時使用默認路徑。相對路徑解析到配置目錄下。具體限制原因見倉庫 docs/limitations.md。
四、典型用法¶
- 在面板頂部輸入框寫標題，順手打
#工作指定分類、@lib/store.js引用工作區文件；分類、優先級、類型可直接點選。按 Enter 或點「添加」，帶標記時由 Host 統一解析，標題裏不會殘留#分類/@文件。 - 點行首的勾選圈（看板裏是卡片上的勾選框）完成待辦，完成時刻自動寫入，底部浮出 toast；「撤銷」可以一鍵退回未完成狀態，「完成時間」列立即出現時間。
- 需要一次記多條時，點新建框右側的「批量」進入對話式錄入，先確認工作區（
@文件補全按工作區隔離），一句話寫多條，發送後逐條回執，不滿意可整批撤銷。 - 不想離開對話流時用斜槓命令，在 Harness 主輸入框寫：
/todo 寫週報 #工作 lib/store.js
- 想讓模型代記、代查時調用智能體工具
todo_time_log，參數與面板表單同源，action 覆蓋增刪改查與健康檢查。
五、適用場景與注意事項¶
適合把 DSH 當工作臺、希望待辦清單同時是一份時間記錄的人，尤其是需要讓智能體按規則代記待辦、再回頭用甘特圖或日曆復盤耗時的場景。
需要注意幾點。安裝前應檢查源碼與許可證（倉庫爲 MIT，LICENSE 在根目錄），並以當前 DSH 進程權限運行插件。它不是獨立應用，必須先有可用的 DeepSeek Harness，版本需滿足 engines.dsh 約束。插件詳情頁目前沒有配置表單，數據文件路徑要用 cordis.patch.yml 或環境變量指定。所有數據都在本地，不聯網、不上傳。
六、小結¶
這個插件的價值在於把「待辦清單」和「時間賬本」合成一個界面：錄入入口多但不分裂，四種視圖共享一份解析和數據，完成動作即記賬，撤銷和導入導出都帶上了。如果你是 DSH 用戶，待辦又恰好需要回答「做了多久」，可以從這裏入手。
- 目錄頁：https://www.skillhub.cn/plugins/FantasyStarry/dsh-todo-time-log
- GitHub：https://github.com/FantasyStarry/dsh-todo-time-log
- npm：https://www.npmjs.com/package/dsh-todo-time-log
