dsh-bookkeeping

English · 简体中文

A conversational bookkeeping plugin for DeepSeek Harness (dsh). Record expenses and income by chatting — "记一笔 午饭 35" — then query, report, export, and budget against a local SQLite ledger.

The plugin is a self-contained dsh bundle: an npm package whose package.json declares the dsh.bundle manifest, ships a cordis.patch.yml layer, and exports a standard plugin entry (name / inject / Config / apply). It works both as model-callable tools inside dsh and as a standalone CLI.

Features

• Conversational bookkeeping — the model records entries through bookkeeping_add; amounts are validated strictly, dates are normalized from natural language, categories are auto-detected.
• SQLite ledger — local persistence with amount / category / tags / date / currency fields (amounts stored as exact integer minor units).
• Category system — built-in categories (餐饮 / 交通 / 购物 / 居住 / 娱乐 / 医疗 / 学习 / 收入 / 其他), keyword auto-classification, and custom keyword→category rules.
• Reports — daily / monthly / category summaries and monthly trends, filterable by month, range, category, type and tag.
• Exports — CSV (RFC 4180 quoting) and self-contained HTML reports.
• Budgets — optional monthly budgets (overall or per category) with near-limit (≥80%) and over-budget warnings returned right when an entry is recorded.
• Dual entry — nine model-callable tools (ctx.tools) plus a standalone CLI with identical behavior.

Requirements

• Node.js ^22.19.0 || >=24.0.0 (same range as dsh itself)
• A running dsh installation (npx @deepseek-ai/dsh), with pnpm on PATH for plugin installation

Install into dsh

From the repository root, build the package first:

npm install
npm run build
npm pack          # optional: produces dsh-bookkeeping-1.0.0.tgz

Install the bundle into a dsh profile (any pnpm spec works: directory, tarball, github:..., or an npm package name):

dsh plugin --profile bookkeeping add <path/to/dsh-bookkeeping>
# or: dsh plugin --profile bookkeeping add ./dsh-bookkeeping-1.0.0.tgz

Verify the layer is composed, then boot:

dsh --profile bookkeeping --dump-config   # expect a "# == dsh-bookkeeping" layer
dsh --profile bookkeeping

pnpm may print Ignored build scripts: [email protected] during install. That warning is benign: better-sqlite3 v13 ships prebuilt binaries inside the package, so no build step is required.

Once running, the model can use the tools directly in chat:

用户: 记一笔 午饭 35
用户: 昨天打车花了 28
用户: 花了多少钱在餐饮上？
用户: 这个月一共花了多少？
用户: 给我看下最近 10 条记录
用户: 导出 csv
用户: 设置本月预算 5000

Configuration

Plugin configuration is declared with a Schemastery schema (export const Config) and supplied through the profile's cordis.patch.yml:

- insert:
    - id: bookkeeping
      name: dsh-bookkeeping
      config:
        dataDir: /var/data/bookkeeping   # optional, default ~/.dsh-bookkeeping
        currency: CNY                    # optional, default CNY
        maxAmount: 1000000000000         # optional, max single amount in units

…