dsh-ledger

dsh-ledger — 只读记账仪表盘插件

在 dsh web 会话页的 「记账」Tab（与「梦境」并排）展示 beancount 账本的月度快照： 本月收支总览、资产结构、支出分类占比、最近交易。只读——不在插件里记账，Fava 保留做深度分析。

dsh 版本兼容性

要求 dsh ≥ 0.1.7-rc.1（已在 0.1.7-rc.1 实测通过）。

• ctx.settings.register() 已移除（2026-09-24）：原 ledger settings namespace 并入插件 Config，可热改字段标 .volatile()；inject 去掉 settings。
• Typert strict codec 必须带 create() 工厂（0.1.7 客户端校验）：client.js 与 index.js 的 result / payload codec 均已补 create()。

工作原理

进入「记账」Tab / 点「刷新」
  → RPC /dsh-ledger/dashboard
  → LedgerEngine：
      1. 解析当月账本文件 Beancount/<year>/<month>.bean（交易/分类/收支）
      2. exec ledger.py balance（全部账户余额）
  → 输出统一 JSON → Tab 渲染

数据源复用现有 ledger.py（skill 自带），脚本零改动；当月交易直接从按月分文件的 .bean 解析，不调账本写入。

展示内容

• 本月收支总览卡：本月支出（含笔数）/ 本月收入 / 本月结余 / 活期余额 / 总资产
• 资产结构：动态分组——按账本 Assets:<类别> 自动发现（任意 beancount 结构自适应），活期 = 数字尾号卡账户（如 Assets:CMB:1234 形态）
• 本月支出分类：Top 5 分类 + 占比进度条 + 其余合计
• 最近交易：最近 15 条（日期 / 一级分类 / 描述 / 金额，支出红收入绿），右侧独立栏可滚动

目录

dsh-ledger/
├── index.js              # host 插件：settings + connection.rpc（/dsh-ledger）
├── client.js             # 浏览器 bundle：conversation.view "记账" Tab
├── lib/ledger-engine.mjs # 解析 .bean + exec ledger.py balance → 仪表盘 JSON
├── cordis.patch.yml
└── package.json

技术要点（踩过的坑）

• 依赖软链必须建：node_modules/@deepseek-ai → /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai，否则 ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/schemastery' 导致整个 profile 起不来
• inject 必须包含用到的服务：index.js 用了 ctx.typert，inject 列表需含 "typert"（曾漏掉）
• inject 需含 "webServer"（dsh 0.1.5 起严格检查）：漏了报 cannot get property "webServer" without inject，整个 profile 起不来（2026-09-10 踩过）
• 中文账户名：账本里有 Assets:TimeDeposit:享定存70007 等中文账户，正则需允许 \u4e00-\u9fff，否则几十万资产解析不到
• 挂载：~/.dsh/profiles/web/package.json 的 dependencies（link）+ dsh.profile.bundles 两处

验证

# 引擎单测（真实账本）
node -e "import('./lib/ledger-engine.mjs').then(async m => { const e = new m.LedgerEngine(); console.log(JSON.stringify(await e.buildDashboard(), null, 1).slice(0, 800)); })"

# RPC 实测
curl -s -X POST "http://127.0.0.1:3080/dsh-ledger/dashboard" \
  -H "Content-Type: application/json" \
  -d '{"type":"client-request","rpcId":"v1","method":"dashboard","payload":{}}'

改代码后重启 web 生效：launchctl kickstart -k system/com.dsh.web