前言¶
在 DeepSeek Harness（DSH）裏做助手開發，常見需求之一是「記一筆、查本月花了多少」——若每次都手寫腳本或臨時 JSON，口徑容易和麪板不一致，也不方便做預算與趨勢。社區插件 dsh-ledger（維護者 laomaogu，SkillHub 分類：記憶）面向 DSH Web 場景：在側邊欄提供記賬本面板，同時向 Agent 註冊記賬與報表工具，統計與提示由 Host 統一計算，數據只落在本機一個 JSON 文件裏。
下面介紹它是什麼、能做什麼、如何安裝啓用，以及使用時需要注意的限制。
這是什麼¶
dsh-ledger 是 DeepSeek Harness 的個人記賬插件：記錄每一筆收支，按時間、分類、支付方式、星期、月度五個維度做分析，給出預算相關提示，並用內聯 SVG 圖表展示。不上傳雲端；HTTP 請求先經過 DSH 的 connection 信任檢查。
- 目錄頁：https://www.skillhub.cn/plugins/laomaogu/dsh-ledger
- 源碼與文檔：https://github.com/laomaogu/dsh-ledger
- 許可證：MIT（
package.json版本 1.0.0） - 插件行 id 爲
personal-ledger，啓用 bundle 名爲dsh-ledger
SkillHub 爲社區插件目錄，與 DeepSeek / 幻方無官方從屬關係；安裝前建議自行查看源碼與 LICENSE。
核心功能¶
面板與記賬¶
- 快速記賬：支出 / 收入、金額、14 個固定分類、日期、5 種支付方式、備註；點按記錄編輯，懸停刪除（二次確認）。
- 三個頁籤：概覽（KPI、圖表、本月小結、最近記錄）、明細（搜索與分類篩選）、設置（月度預算、數據文件路徑、導出當前月 CSV / JSON）。
- 概覽 KPI：本月支出、收入、結餘、日均支出、預算剩餘（含進度條）。
五種圖表（純 SVG / CSS，無第三方圖表庫，跟隨亮暗主題）¶
- 每日支出趨勢（面積 + 折線，標出今天）
- 支出構成環形圖（分類佔比 + 圖例）
- 支付方式橫向條形圖
- 星期分佈柱狀圖（區分工作日 / 週末）
- 近六個月支出與收入對比柱狀圖
消費分析與自動提示¶
概覽會彙總本月支出 / 收入 / 結餘 / 日均 / 預算剩餘，並按剩餘預算折算每日額度、按當前速度預測月末支出。根據數據最多生成 6 條建議（預算超支、分類上漲、環比變化、週末偏高、大額支出、重複消費、儲蓄率等），按 warn → tip → ok → info 排序，警告優先。規則爲啓發式，不構成財務建議；閾值可在 Host 的 buildInsights() 中調整（見 README 表格）。
對話記賬（Agent 工具）¶
裝上並啓用插件後，可對助手用自然語言記賬或查賬。註冊三個工具：
| 工具 | 作用 |
|---|---|
ledger_add |
記一筆：amount（必填）、type、category、date、method、note |
ledger_report |
某月彙總：總額、分類、支付方式、星期、環比、提示、最近 10 條（含 id） |
ledger_delete |
按 id 刪除一條 |
示例說法（來自 README）：
記一筆：午飯 25 元
昨天打車 38，用支付寶
這個月花了多少？幫我看看哪裏可以省
刪掉剛纔那筆咖啡
說明：Agent 工具返回的報告文本目前固定中文；面板文案支持中英雙語（zh / en）。
數據與隱私¶
- 存儲路徑：
~/.dsh/personal-ledger/ledger.json（目錄權限700、文件600，UTF-8，原子寫入）。 - 無法解析的 JSON 會改名爲
ledger.json.corrupt-<時間戳>，從空賬本繼續。 - 無遙測；刪除無回收站，需留檔請先導出。
Host 在 buildSnapshot() 中統一算統計與提示，面板與 Agent 共用同一口徑。
安裝與啓用¶
插件以當前 DSH 進程權限運行，安裝前應確認信任維護者與代碼。
方式一：插件管理器（推薦）¶
- 打開 DSH Web 的「插件」頁（左欄風車圖標）。
- 安裝：選擇本地目錄，或填寫本倉庫地址 / npm 包名。
- 在插件列表裏啓用
dsh-ledgerbundle。 - 左欄底部出現錢包圖標 記賬本 即表示成功。
方式二：命令行¶
本地目錄（會創建 link 依賴）：
dsh plugin --profile <profile> add /path/to/dsh-ledger
或從 GitHub 安裝：
dsh plugin --profile <profile> add github:laomaogu/dsh-ledger
隨後在「插件」頁啓用 dsh-ledger bundle（或讓助手通過插件管理器完成啓用）。
兼容性（README 寫明）：開發與驗證環境爲 DSH 0.2.1-rc.5、Node 22.23.4；package.json 要求 node >= 22.19.0、dsh ^0.2.1-alpha.2。僅使用 Node 內置模塊，無第三方運行時依賴。
典型用法¶
- 記一筆：面板右上角按鈕 → 選類型、金額、分類、日期、支付方式、備註 → 保存；錄入後自動跳到該筆所在月份。
- 看分析：在概覽頁閱讀圖表與「本月小結」。
- 找記錄：明細頁搜索備註 / 分類 / 金額，按分類過濾；點記錄編輯，懸停刪除。
- 設預算：設置頁填寫月度預算（0 或留空表示不設），提示邏輯會隨之變化。
- 導出：設置頁導出當前月份的 CSV 或 JSON。
Host 就緒時日誌會打印 [dsh-ledger] host ready: <數據文件>，便於確認加載的數據路徑。修改 client.js 後刷新頁面即可；改 Host 需重啓 DSH 進程。面板約每 25 秒或窗口重新聚焦時刷新，非實時推送。
適用場景與注意¶
適合：已在用 DSH Web、希望本機記賬並在同一環境裏讓 Agent 記一筆 / 查報表的開發者或個人用戶；需要預算提示和多維度 SVG 概覽、且接受固定分類集合的場景。
已知限制（README）：
- 單幣種（人民幣
¥），金額上限 10 億、備註 120 字、最多 5 萬條記錄。 - 分類爲內置集合，UI 暫不支持自定義。
- 無賬單導入、無多賬戶 / 多人共享。
Roadmap 包括自定義分類與多幣種、支付寶 / 微信 CSV 導入、提示閾值可配置等，以倉庫 CHANGELOG / Issue 爲準。
結尾¶
dsh-ledger 把「錄入—統計—圖表—預算提示—Agent 工具」收進一個 DSH 插件，數據留在 ~/.dsh/personal-ledger/ledger.json，適合作爲 Harness 生態裏本機個人財務記憶的起點。
- SkillHub：https://www.skillhub.cn/plugins/laomaogu/dsh-ledger
- GitHub：https://github.com/laomaogu/dsh-ledger
