Skip to content

dsh-personal-ledger

Verified

dsh-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 的 Client Slots.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 中人工确认。