dsh-bookkeeping
适用于 DeepSeek Harness 的对话式记账插件：通过聊天记录支出和收入、查询账本、生成报告、导出 CSV/HTML，并跟踪每月预算。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-bookkeeping@1.0.0Bookkeeping 以 dsh-bookkeeping 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
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.
bookkeeping_add; amounts are validated strictly, dates are normalized from natural language, categories are auto-detected.ctx.tools) plus a standalone CLI with identical behavior.^22.19.0 || >=24.0.0 (same range as dsh itself)npx @deepseek-ai/dsh), with pnpm on PATH for plugin installationFrom 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: better-sqlite3@13.0.3during 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
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
| Key | Type | Default | Meaning |
|---|---|---|---|
dataDir | string | ~/.dsh-bookkeeping | Where ledger.db and the exports/ directory live. Also honored via the DSH_BOOKKEEPING_DATA_DIR environment variable (explicit config wins). |
currency | string | CNY | Default currency when an amount carries no symbol. |
maxAmount | number | 1_000_000_000_000 | Upper bound for a single amount, in units. |
All tools return { summary, data }; summary is model-facing text, data is structured JSON.
| Tool | Purpose |
|---|---|
bookkeeping_add | Record one entry. amount required; category auto-detected when omitted; type (expense/income), currency, remark, tags, date (natural language) optional. |
bookkeeping_list | List entries, newest first, with filters month / start / end / category / type / tag / limit. |
bookkeeping_categorize | Predict the category of free text using built-in keywords and custom rules. |
bookkeeping_categories | List all known categories (built-in plus custom-rule categories) with their kind. |
bookkeeping_report | Aggregations: daily, monthly, category, trend (+ months). Filters: month / start / end / category / type. |
bookkeeping_export | Write a CSV or HTML file under <dataDir>/exports/; exports the full matching set and returns the absolute file path. |
bookkeeping_budget | set / list / check monthly budgets. set with amount "0" removes the budget. |
bookkeeping_rules | Manage custom keyword→category rules: add / list / remove. |
bookkeeping_remove | Delete an entry by id (shown as #12 in listings). |
The same ledger is available as a standalone CLI (no dsh required):
node dist/src/cli.js add 35 午饭 # record
node dist/src/cli.js add "¥500" 工资 --type income --date 昨天
node dist/src/cli.js list --month 2026-08 # list
node dist/src/cli.js report category --month 2026-08
node dist/src/cli.js report trend --months 6
node dist/src/cli.js export csv --out ./out
node dist/src/cli.js budget set 5000 # overall monthly budget
node dist/src/cli.js budget set 1500 --category 餐饮
node dist/src/cli.js rules add 咖啡豆 购物
node dist/src/cli.js remove 12
Run node dist/src/cli.js --help for the full reference. Exit codes: 0 ok, 1 domain error (invalid amount/date/…), 2 usage error. Data lives in ~/.dsh-bookkeeping (override with --data-dir or DSH_BOOKKEEPING_DATA_DIR).
A single SQLite database (ledger.db) in the data directory, WAL mode. Tables:
entries — id, amount_cents (integer minor units, always > 0), currency, type (expense/income), category, remark, tags (JSON array), date (YYYY-MM-DD), created_atcategory_rules — custom keyword → category rules (checked before built-in keywords)budgets — (month, category) limits; category '*' is the overall budgetmeta — reserved for schema metadataExports are written to <dataDir>/exports/ledger-<timestamp>.csv|html.
Amounts. Text like 35, 35.5, ¥35, 35元, $35.99, 1,234.56. Symbols select the currency (¥/￥→CNY, $→USD, €→EUR, £→GBP, ₩→KRW; suffixes 元/块→CNY, 円→JPY). An explicit currency argument overrides the default but must not conflict with a symbol. Rejected: zero, negatives, non-numeric text, malformed thousands separators, more decimal digits than the currency supports (2 for CNY/USD/…, 0 for JPY/KRW), amounts above maxAmount.
Dates. YYYY-MM-DD, 2026/8/17, 2026.8.17, 2026年8月17日, 8/17, 8月17日, 3月; relative words 今天/今日/昨天/昨日/前天/明天/明日/后天 and today/yesterday/tomorrow; weekdays 周X/星期X/礼拜X (mapped into the current Monday-based week), 上周X, 下周X, bare 上周/下周; offsets N天前/N天后, N周前/后, N个月前/后; months 上个月/本月/这个月/下个月 (day-of-month clamped to the target month's length). Unparseable dates are rejected with the supported formats listed. Year range: 1900–2100.
Built-in categories with keyword auto-classification: 餐饮, 交通, 购物, 居住, 娱乐, 医疗, 学习, 收入, 其他 (fallback). Matching is case-insensitive substring matching; the longest matching keyword wins, ties prefer custom rules, and anything unmatched falls to 其他. Custom rules persist in the database, e.g. rules add 咖啡豆 购物 makes any remark containing "咖啡豆" classify as 购物.
daily — per-day expense/income totals; monthly — per-month totals with net (income − expense); category — per-category totals with share, sorted by amount; trend — monthly totals for the last N months (zero-filled).YYYY-MM or YYYY-MM-DD bounds (month bounds expand to the month's first/last day). type defaults to both (all); pass expense/income to narrow.YYYY-MM), overall or per category. When recording an expense, matching budgets are checked immediately: ≥80% produces a near-limit notice, ≥100% an over-budget warning. Income never consumes a budget. budget set … 0 removes a budget. An overall budget check reports every budget of the month (overall plus each category).ledger.db under the
configured dataDir (default ~/.dsh-bookkeeping), with exports in
<dataDir>/exports/. Override via DSH_BOOKKEEPING_DATA_DIR or the
--data-dir CLI flag (an explicit config value wins).¥→CNY, $→USD, €→EUR, £→GBP, ₩→KRW, 円→JPY,
元/块→CNY). Set currency to change the default. There is no currency
conversion; aggregates assume a single currency.bookkeeping_rules add 关键词 分类 (or rules add 咖啡豆 购物 in the CLI).
Custom rules are checked before built-in keywords.YYYY-MM month string and that the entry's default currency matches.npm install
npm run build # tsc -> dist/
npm test # tsc + node --test
Layout: src/money.ts (amount parsing/formatting), src/dateutil.ts (natural-language dates), src/categories.ts (built-ins + autoclassify), src/store.ts (SQLite), src/ledger.ts (domain service), src/report.ts / src/budget.ts / src/export.ts (aggregation, budgets, exports), src/format.ts (shared text), src/tools.ts (dsh tools), src/cli.ts (CLI), src/index.ts (bundle entry). Tests mirror this structure under test/.
package.json dsh: { bundle: { patch: "./cordis.patch.yml" } }, type: module, exports, bin
cordis.patch.yml layer that inserts the plugin row (id: bookkeeping, name: dsh-bookkeeping)
dist/src/index.js entry: export const name / inject / Config / apply(ctx, config)
dist/src/cli.js standalone CLI (bin: dsh-bookkeeping)
bookkeeping_list totals cover the shown page only; use bookkeeping_report for full sums.周X always resolves inside the current Monday-based week (documented convention), including upcoming weekdays.