前言¶
给 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
