dsh-personal-ledger
Verifieddsh-personal-ledger · v1.5.1 · MIT · Web UI
Installment ledger: record and edit installment / one-time bills, import JD Baitiao / credit card / Alipay bills, track monthly repayments with one-click payment, and export text / CSV / PNG.
Install
dsh plugin add dsh-personal-ledger Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Published to npm without a public repository. Inspect the package contents before installing.
Tags
Creators
Readme
分期记账(Installment Ledger)
npm 包名:
dsh-personal-ledger· 版本1.5.1
DeepSeek Harness Web UI 插件:在左侧栏提供「分期记账」入口,打开一个记账面板,用来记录 / 编辑分期账单和不分期(一次性)账单,从京东白条 / 信用卡 / 支付宝备用金 / 支付宝花呗等平台导入账单,按还款月份统计应还金额并一键还清当月,还可将账单导出为文本 / 表格(CSV)/ 图片(PNG)。
功能
- 添加账单:对话框顶部选择「分期 / 不分期」。
- 分期账单:名称、总金额、期数(3/6/12/24 快捷或 1–120)、首期还款日期、备注;自动生成每期计划。
- 不分期账单:名称、总金额、还款日期、备注;只有一笔到期记录。
- 编辑账单(本次新增):每张卡片都有「编辑」按钮,可修改类型、名称、总额、期数、首期还款日期与备注。保存时按「期号顺序」保留已还状态:仍存在的期保留原已还时间;改期数 / 改类型时,能对应上的期保留已还,新增的期从未还开始。
- 金额自动计算(本次新增):编辑账单时,「总金额」输入框支持算式与相对加减,保存时自动计算并重算总额与每期金额:
- 直接输入算式:
3994.28+100.00→ 保存为 ¥4,094.28;3994.28-100.00、1000+200-50等多段加减也可; - 或只写调整量:
+300/-200(全角 +/-/− 也可),表示在当前总额上加减,例如当前 ¥1,000.00 输入+300保存为 ¥1,300.00; - 支持千分位与空格(
3,994.28 + 100);预览区实时显示计算结果:900+50 = ¥950.00或调整后总额:¥1,000.00 + ¥300.00 = ¥1,300.00,每期金额同步变化; - 已还状态按期号保留;结果 ≤ 0、超过上限、低于「每期 0.01 元」或算式格式错误时会提示且不保存。新增账单同样支持算式输入;
+500/-500在新增时分别等价于 500 / 无效。
- 直接输入算式:
- 调整记录(本次新增):每当编辑保存导致账单总额变化,自动记录一条调整记录:
- 记录内容:精确到秒的时间(本地时区
YYYY-MM-DD HH:mm:ss)、变动金额(+ / -)、调整前 / 调整后总额,以及编辑对话框里的「调整备注(可选)」; - 账单卡片会出现「调整记录(n)」按钮,展开后按新→旧列出全部记录(时间 / 变动 / 调整后总额 / 备注);
- 仅总额变化才会记录:只改名称、期数、还款日等不会产生记录;记录保存在本地账本
localStorage中,刷新 / 重启不丢; - 编辑 / 删除记录(本次新增):调整记录面板每行有「编辑」「删除」:
- 编辑:可修改该条记录的时间(
datetime-local,精确到秒)与备注;变动金额与调整后总额保持原样(不能篡改历史金额); - 删除:行内二次确认后移除该条记录(只删除记录、不会回滚账单金额,如需恢复金额请再次编辑账单金额)。
- 编辑:可修改该条记录的时间(
- 记录内容:精确到秒的时间(本地时区
- 按月份分类与一键还款(本次新增):工具栏可切换「账单列表 / 按月份」。
- 按到期月份分组,显示每月应还 / 已还 / 待还金额与逾期笔数;当前月份高亮。
- 每个月份卡片可展开逐笔查看(账单名、第几期、到期日、金额、状态),也可单独「标记已还」。
- 点「一键还清本月」会把该月份内所有未还款项一次性标记为已还,并提示笔数与金额。
- 导出账单(本次新增):页面右上角「导出」。
- 格式:文本(.txt)、表格(.csv,Excel 可直接打开,带 BOM)、图片(.png,按当前主题绘制的账单汇总图)。
- 可勾选是否包含已还清账单;导出内容包含账单明细(类型、名称、总额、期数、已还、剩余、到期日、来源、备注)与按月份汇总。
- 账单导入:右上角「导入账单」,平台预设 京东白条 / 信用卡 / 支付宝备用金 / 支付宝花呗 / 通用 CSV;粘贴文本或读取
.csv/.tsv/.txt(UTF-8,自动尝试 GBK);点「解析账单」后逐条勾选,点「导入 N 笔」批量导入,自动去重并标记来源平台。本插件导出的 CSV 可直接回灌(见下)。 - 逐期 / 逐笔标记已还:分期账单展开「还款计划」逐期操作;不分期账单直接在卡片上操作;逾期用警示色提示。
- 汇总与筛选:剩余待还、本月已还、最近一期;全部 / 进行中 / 已还清筛选;有逾期或待还的账单排在前面。
- 删除:行内二次确认。本地持久化:
localStorage键dsh.installment-ledger.v1,多标签页通过storage事件同步。 - 中英文文案跟随 Harness 语言;颜色、边框、弹层使用 Harness 主题 token,浅色 / 深色 / 第三方皮肤下均可读。
导入格式说明
| 平台 | 识别方式 |
|---|---|
| 京东白条 / 支付宝花呗 | 标签文字:商品名称 / 分期总额(或总金额)/ 分期期数 / 每期应还 / 下期还款日;有「每期金额 + 期数」时生成分期账单,否则按「本期应还 + 还款日」生成一次性账单;也支持多行分期明细(名称 12期 每期 100.00)与 CSV。 |
| 信用卡 | 逐行交易明细:2026-01-10 京东商城 123.45(日期 商户 金额),或带表头的 CSV(日期 / 商户 / 金额…),每行生成一笔一次性账单;也识别「本期应还 + 到期还款日」汇总。 |
| 支付宝备用金 | 标签文字:取用金额 / 借款金额 / 还款金额、到期日(或应还日期),生成一次性账单。 |
| 通用 / CSV | 表头列名支持:名称 / 描述 / 商户、金额 / 总金额、日期 / 到期日、期数 / 分期期数、类型(分期 / 不分期)、备注;分隔符支持 , / \t / ; / ` |
示例(通用 / CSV,可直接粘贴到「通用 / CSV」平台解析):
名称,金额,日期,期数,类型
手机分期,12000,2026-11-10,12,分期
年度保险,3600,2026-12-01,1,不分期
- 文件读取支持
.csv/.tsv/.txt文件,UTF-8 编码;检测到乱码时自动尝试 GBK。 - 导入前会按「类型 + 名称 + 总额 + 首期/到期日」去重,重复候选会被跳过并提示数量。
导出后回灌(导出 CSV 再导入)
「导出」得到的账单 CSV 可以直接粘回「导入账单 → 通用 / CSV」恢复数据,支持的表头为:
类型,名称,总额(元),期数,已还期数,剩余(元),首期/到期日,下次到期日,来源,备注
- 名称按原样保留(带英文逗号的名称会自动按 CSV 引号规则处理);名称列为空白的行会用当前平台默认名回填,不会生成无名账单;
- 已还期数会还原为对应期数的已还状态(已还时间记为导入时刻);「剩余(元)」「下次到期日」是导出时的派生列,导入时按总额与期数重新计算,不参与导入;
- 来源列的中英文平台名会映射回平台标记(空值表示无来源);
- 文件末尾的「还款月份 / 应还 / 已还 / 待还」汇总表会被自动忽略,不会被当成账单导入;英文界面导出的
Month / Due (CNY) / Paid (CNY) / Unpaid (CNY)汇总表同样会被忽略; - 缺少可识别表头的多列表格会提示「缺少可识别表头」而不会猜测金额、生成错误账单。
导出格式说明
| 格式 | 文件 | 内容 |
|---|---|---|
| 文本 | installment-ledger-YYYY-MM-DD.txt |
标题、生成时间、账单总数与剩余待还、逐笔账单明细、按月份应还 / 已还 / 待还汇总。 |
| 表格 | installment-ledger-YYYY-MM-DD.csv |
第一段:类型 / 名称 / 总额(元) / 期数 / 已还期数 / 剩余(元) / 首期或到期日 / 下次到期日 / 来源 / 备注;第二段:还款月份 / 应还(元) / 已还(元) / 待还(元)。UTF-8 BOM,逗号分隔,含引号转义。 |
| 图片 | installment-ledger-YYYY-MM-DD.png |
按当前主题配色绘制的账单汇总图:标题、汇总、账单明细表、按月份汇总,2 倍像素密度。 |
三种格式均在浏览器本地生成并触发下载,不上传任何数据。
界面位置
- 左侧栏新增账本图标(
sidebar.panellist,id 为installment-ledger);点击后在中栏打开记账页(main槽位),无需选中会话。 - 右上角按钮:导出、导入账单、添加账单。
- 工具栏:账单列表 / 按月份视图切换;列表中另有 全部 / 进行中 / 已还清 筛选。
- 添加 / 编辑 / 导入 / 导出均为页面内对话框:Esc 关闭、点击遮罩关闭、Tab 焦点循环,关闭后焦点回到触发按钮。
数据格式
{
"version": 2,
"bills": [
{
"id": "bill-…",
"kind": "installment",
"name": "手机分期",
"totalCents": 1200000,
"periods": 12,
"firstDue": "2026-11-10",
"note": "免息",
"source": "generic",
"createdAt": "2026-11-03T13:00:00.000Z",
"payments": [
{ "index": 0, "dueDate": "2026-11-10", "amountCents": 100000, "paidAt": null }
],
"adjustments": [
{
"id": "adj-…",
"at": "2026-11-06T06:35:12.000Z",
"deltaCents": 10000,
"beforeCents": 1200000,
"afterCents": 1210000,
"note": "加购配件"
},
{
"id": "adj-…",
"at": "2026-11-08T09:12:40.000Z",
"deltaCents": -10000,
"beforeCents": 1210000,
"afterCents": 1200000,
"note": "退款修正"
}
]
},
{
"id": "bill-…",
"kind": "single",
"name": "年度保险",
"totalCents": 360000,
"periods": 1,
"firstDue": "2026-12-01",
"note": "",
"source": "",
"createdAt": "2026-11-03T13:05:00.000Z",
"payments": [
{ "index": 0, "dueDate": "2026-12-01", "amountCents": 360000, "paidAt": null }
]
}
]
}
kind为"installment"(分期)或"single"(不分期);旧版本数据没有kind时按「分期」读取,兼容已有账本。source为可选来源平台 id:jd-baitiao/credit-card/alipay-reserve/huabei/generic;手动添加的账单为空。- 两种类型共用
payments结构:不分期就是只有 1 期的账单;编辑账单时按index保留已还时间戳。 - 金额一律以「分」为整数存储;读取时做防御性归一化(非法账单丢弃、缺失的期数 / 金额 / 到期日重新推导,已还时间戳保留)。
adjustments为账单的调整记录(可选,旧账本没有该字段时按[]读取):每条含id、at(ISO 时间)、deltaCents(有符号变动,非 0)、beforeCents/afterCents(调整前 / 后总额,需满足after = before + delta)、note(≤120 字)。读取时会丢弃非法记录,每张账单最多保留最近 200 条。
文件结构
package.json:bundle 清单(dsh.bundle.patch+dsh.client)。cordis.patch.yml:向当前 profile 插入installment-ledger行。index.js:Host 半边(无 Host 逻辑,UI 与数据均在浏览器端)。client.js:面板页面、添加 / 编辑 / 导入 / 导出对话框、月度统计与还款、localStorage 存取与槽位注册。locale/en.json、locale/zh.json:插件管理器中显示的标题与描述。icon.svg:原创图标(账本 + 金币)。LICENSE:MIT 许可证。
安装与验证
从 npm 安装:在 Harness 左侧栏「插件 / Plugins」页点「Add plugin」,输入包名
dsh-personal-ledger(可带版本号,如[email protected])。node --check index.js、node --check client.js通过;package.json、locale/*.json为合法 JSON;icon.svg为合法 SVG。安装后经
cordis_inspect_query的 ClientSlots.listSubTree确认:sidebar.panellist出现installment-ledger占用项,main出现installment-ledger键。离线单元 + 渲染烟雾测试:
node test/run-tests.mjs(198 个用例,覆盖金额 / 日期 / 分期拆分、类型切换、旧数据兼容、五种导入解析、账单编辑(已还状态保留)、算式与相对金额调整、调整记录(生成 / 时间与备注编辑 / 删除 / 上限 / 兼容旧数据)、按月分组与一键还款、文本 / CSV / 图片导出、导出 CSV 回灌、词典与占位符一致性、槽位注册与组件渲染)。真实浏览器端到端测试:
node e2e/run-e2e.mjs(headless Chrome + CDP 驱动真实 Web UI:打开面板、添加账单、标记已还 + 刷新持久化、按月份 + 一键还清、CSV 导入 / 去重、CSV / TXT / PNG 导出下载、算式金额调整、调整记录(时间 + 备注)与刷新持久化、调整记录的编辑 / 删除(含两步确认与金额不变校验)、重置空态)。开发方式与本地 link 安装流程见同目录
DEV.md。
已知限制
- 不包含分类统计、多币种、按平台筛选;编辑只维护「当前计划」,不会还原历史已还时间(已还状态按期号保留)。
- 图片导出是绘制好的静态 PNG(不可再编辑文本);文本 / 表格 / 图片均在浏览器生成并触发下载,若运行环境禁止下载只提示不支持。
- 导入解析基于常见文案 / 表头的启发式规则:不同银行或平台的导出格式可能不同,请先在「识别结果」里核对候选账单再导入。
- 调整记录仅保存在浏览器本地账本中,不包含在导出的文本 / CSV / 图片里;删除账单会同时删除其调整记录。删除单条调整记录只删除记录、不会回滚账单金额;编辑记录只能改时间与备注,不能改变动金额。
- 数据存于当前浏览器,不跨浏览器 / 设备同步,也不写入 Session 日志或 Host 存储;清除站点数据会清空账本。
- 本插件未注册模型可调用的工具,模型无法直接读写账本。
- 当前安装环境没有交互式浏览器控制,核心交互已由 headless Chrome 端到端测试覆盖;像素级外观仍建议在 Web UI 中人工确认。