前言¶
給 DSH Web UI 寫插件時，常見的需求是把一套固定的記錄表單掛進側欄，讓用戶每月填一次、自動算好。已有的做法要麼是讓模型每次重新生成一份清單，數據散落在對話裏；要麼是單獨起一個 Web 應用，脫離 Harness 的窗口。下面介紹的 skyline66/dsh-family-budget 走的是插件這條路：側欄多一個入口，點進去是一張月度家庭預算表。
它是個人維護的客戶端插件，只做記賬，不做投資建議。事實依據來自插件的 GitHub README 與 package.json，未在資料中出現的行爲不做推測。
這是什麼¶
一句話：在 DSH Web UI 的側欄里加一個「家庭財務」頁面，按月記錄收入、固定支出、可變支出、儲蓄、應急金、債務，並給出復盤和目標進度。
誰維護：skyline66，MIT 許可證，package.json 裏 version 爲 1.0.2。
解決什麼問題：家庭每月的錢分散在工資、房貸、日常開銷和儲蓄目標裏，缺少一張能持續更新、自動算差額的表。這個插件把這張表放進 Harness 窗口，數據落在本地磁盤，不需要外部服務。
它明確不是理財工具。README 裏寫明不做市場數據、不推產品、不做預測、不給投資建議，頁面本身也標註了這一點。
核心功能¶
側欄入口是「家庭財務 / Family budget」，點開後一個月一張表。表內分七個區塊，每個區塊寫什麼、算什麼如下。
| 區塊 | 你錄入 | 頁面計算 |
|---|---|---|
| 收入 Income | 工資、獎金、其他進項 | 收入合計，佔各比例的基數 |
| 固定支出 Fixed | 房貸／房租、水電燃氣、通訊、保險、教育 | 固定支出合計，佔收入比例 |
| 可變支出 Variable | 每項的預算與實際 | 預算合計、實際合計、逐項差額、超支項 |
| 儲蓄 Savings | 計劃儲蓄、已累計儲蓄 | 本月可存（結餘）、距計劃差額、一鍵記入累計 |
| 應急金 Emergency fund | 現有應急金、目標月數（3/6/12） | 目標金額 = 固定支出 × 月數，覆蓋率與缺口 |
| 債務 Debt | 每筆餘額、月供、本月已還 | 餘額合計、月供合計、已還合計 |
| 復盤 Review | 做得好的／超支原因／下月調整 | 自動覈對：儲蓄率、超支項、固定支出佔比、應急金覆蓋 |
另有一行目標條，可以在儲蓄、還債、買房之間切換，跟蹤一個目標及你錄入的累計金額。
輸出能力：可導出 CSV 給電子表格使用，可導出 / 導入 JSON 做備份。導入時頁面會先確認，再替換文檔。
安裝與啓用¶
在 DSH 的 Settings → Plugins → Add 中填入倉庫 spec：
github:skyline66/dsh-family-budget
也可以從 releases 頁面取預構建的 dsh-family-budget.tgz：
https://github.com/skyline66/dsh-family-budget/releases/latest
無論哪種方式，裝完都要重載窗口，然後在側欄打開「家庭財務 / Family budget」。
注意：這個包沒有發佈到 npm，所以只寫 dsh-family-budget 名字是解析不到的。
數據落在哪裏¶
所有數據放在一個文檔裏：<dsh home>/family-budget/budget.json。
寫入由 Host 端校驗，規則是：
- 未知鍵直接丟棄。
- 金額被約束爲非負數，四捨五入到分。
- 月份鍵必須是
YYYY-MM。 - 復盤文字有長度上限。
- 文件損壞或不可讀時，先把它挪到一旁，而不是直接覆蓋。
頁面不往外發數據，只跟自己的插件路由通信。顯示金額用的 ¥ 前綴只是格式化約定，插件不做貨幣換算。
用法示例¶
裝好之後的日常流程是：每個月新建一月，填收入和固定支出，可變支出逐項填預算與實際，然後看頁面給出的差額和超支項。
儲蓄區塊有個一鍵動作：把「本月可存」記入累計儲蓄。應急金區塊填現有金額和目標月數（3、6 或 12），頁面按固定支出乘月數算出目標金額和缺口。債務區塊逐筆錄入餘額、月供和本月已還，頁面給出合計。
復盤區塊填三項自由文本，頁面隨後自動覈對儲蓄率、超支項、固定支出佔比和應急金覆蓋率。
代碼結構¶
插件分 Host 端和 Client 端兩部分，主要文件：
index.js Host half: /family-budget/api/{doc,health}, validation, atomic write
client.js Client half: sidebar entry + budget page (plain JS, React from the host)
locale/{en,zh}.json plugin title and description for the plugin list
cordis.patch.yml the bundle row and its storage root
test/ arithmetic, wiring and live-API tests
本地驗證命令：
npm test # arithmetic + module wiring (no browser needed)
npm run test:api -- http://127.0.0.1:57253 # live Host round-trip against a running Harness
npm test 跑的是 test/calc.test.mjs（直接取 client.js 裏的算術塊求值）和 test/wiring.test.mjs（加載 client.js，套到 stub 上下文，檢查兩個 slot 註冊以及中英文案字典的一致性），不需要瀏覽器。npm run test:api 則向 running 的 Harness 發一輪真實 Host 往返，test/api.test.mjs 會往線上路由 POST 一份惡意文檔，檢查清洗後的結果，再把原文檔恢復。
適用場景與注意¶
適合想在 DSH 窗口裏長期維護一份家庭月度賬、且不想依賴外部工具的用戶，或者想在 DSH Web UI 上學習 Host / Client 兩段式插件寫法的開發者——這個插件的結構足夠小，index.js 負責校驗和落盤，client.js 負責渲染，可作爲參考。
安裝前注意幾點：
- 插件以當前 dsh 進程的權限運行，安裝前應先讀一遍源碼（
index.js、client.js、cordis.patch.yml）和 LICENSE，確認寫入路徑和路由行爲符合預期。 - 數據目錄是
<dsh home>/family-budget/，備份靠 CSV / JSON 導出，不是自動同步。 - 它不做貨幣換算，也不提供任何投資判斷，遇到這類需求要另找工具。
- 目錄頁把分類標爲「客戶端」，星標數爲 0，說明使用者還很少，遇到問題主要靠自己讀代碼或提 issue 到倉庫。
結尾¶
這個插件的價值在於把月度家庭賬收斂成一張表，輸入由你控制，算術由插件保證，數據留在本地。對於想在自己的 DSH 實例里加一套家庭記賬入口的人來說，它是目前比較直接的選擇。
目錄頁：https://www.skillhub.cn/plugins/skyline66/dsh-family-budget
