JohnXu22786/bookkeeping

dsh-bookkeeping

English · 简体中文

面向 DeepSeek Harness（dsh）的对话式记账插件。聊天即可记一笔——「记一笔 午饭 35」——随后可查询、报表、导出，并基于本地 SQLite 账本做月度预算。

本插件是一个自包含的 dsh bundle：npm 包，package.json 声明 dsh.bundle 清单，附带 cordis.patch.yml 补丁层，并导出标准插件入口（name / inject / Config / apply）。它既可作为 dsh 中供模型调用的工具，也可作为独立 CLI 使用。

功能

- 对话式记账 —— 模型通过 bookkeeping_add 入账；金额严格校验，日期支持自然语言归一化，分类自动识别。
- SQLite 账本 —— 本地持久化，字段包含金额 / 分类 / 标签 / 日期 / 币种（金额以整数最小货币单位精确存储）。
- 分类体系 —— 内置分类（餐饮 / 交通 / 购物 / 居住 / 娱乐 / 医疗 / 学习 / 收入 / 其他）、关键词自动归类、自定义关键词→分类规则。
- 报表 —— 按日 / 月 / 分类汇总与月度趋势，支持月份、区间、分类、类型、标签过滤。
- 导出 —— CSV（RFC 4180 转义）与自包含 HTML 报表。
- 预算提醒 —— 可选月度预算（总预算或按分类），入账时即时提示接近限额（≥80%）与超支（≥100%）。
- 双入口 —— 九个可供模型调用的工具（ctx.tools），外加行为一致的独立 CLI。

环境要求

- Node.js ^22.19.0 || >=24.0.0（与 dsh 本身要求一致）
- 已安装 dsh（npx @deepseek-ai/dsh），且 PATH 中有 pnpm（用于安装插件）

接入 dsh

在仓库根目录先构建：

npm install
npm run build
npm pack          # 可选：生成 dsh-bookkeeping-1.0.0.tgz

将 bundle 安装进某个 dsh profile（目录、tgz、github:...、npm 包名均可）：

dsh plugin --profile bookkeeping add
或：dsh plugin --profile bookkeeping add ./dsh-bookkeeping-1.0.0.tgz

验证补丁层已生效，然后启动：

dsh --profile bookkeeping --dump-config   # 应出现 "# == dsh-bookkeeping" 层
dsh --profile bookkeeping

安装时 pnpm 可能提示 Ignored build scripts: better-sqlite3@13.0.3。
该提示可忽略：better-sqlite3 v13 已随包附带预编译二进制，无需构建。

启动后即可在对话中直接使用：

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

配置

插件配置通过 Schemastery schema（export const Config）声明，在 profile 的 cordis.patch.yml 中覆盖：

- insert:
- id: bookkeeping
name: dsh-bookkeeping
config:
dataDir: /var/data/bookkeeping   # 可选，默认 ~/.dsh-bookkeeping
currency: CNY                    # 可选，默认 CNY
maxAmount: 1000000000000         # 可选，单笔金额上限（单位）

| 键          | 类型   | 默认值                | 含义                                                          |
| ----------- | ------ | --------------------- | ------------------------------------------------------------ |
| dataDir   | string | ~/.dsh-bookkeeping  | ledger.db 与 exports/ 目录所在位置。也支持 DSH_BOOKKEEPING_DATA_DIR 环境变量（显式配置优先）。 |
| currency  | string | CNY                 | 金额未带符号时的默认币种。                                     |
| maxAmount | number | 1_000_000_000_000   | 单笔金额上限（单位）。                                         |

工具

所有工具返回 { summary, data }；summary 是面向模型的文本，data 是结构化 JSON。

| 工具 | 用途 |
| ---- | ---- |
| bookkeeping_add | 记一笔。amount 必填；category 省略时自动归类；type（expense/income）、currency、remark、tags、date（自然语言）可选。 |
| bookkeeping_list | 列出记录（最新在前），支持 month / start / end / category / type / tag / limit 过滤。 |
| bookkeeping_categorize | 用内置关键词与自定义规则预测文本所属分类。 |
| bookkeeping_categories | 列出全部已知分类（内置 + 自定义规则引入）及其类型。 |
| bookkeeping_report | 汇总：daily、monthly、category、trend（+months）。过滤：month / start / end / category / type。 |
| bookkeeping_export | 将匹配的记录导出为 CSV 或 HTML 文件（写入 /exports/，导出完整匹配集合），返回绝对路径。 |
| bookkeeping_budget | 月度预算 set / list / check。set 传 "0" 删除预算。 |
| bookkeeping_rules | 自定义关键词→分类规则：add / list / remove。 |
| bookkeeping_remove | 按 id 删除记录（列表中显示为 #12）。 |

CLI

同一账本也提供独立 CLI（无需 dsh）：

node dist/src/cli.js add 35 午饭                 # 记一笔
node dist/src/cli.js add "¥500" 工资 --type income --date 昨天
node dist/src/cli.js list --month 2026-08        # 查询
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             # 本月总预算
node dist/src/cli.js budget set 1500 --category 餐饮
node dist/src/cli.js rules add 咖啡豆 购物
node dist/src/cli.js remove 12

node dist/src/cli.js --help 查看完整参考。退出码：0 成功，1 领域错误（金额/日期非法等），2 用法错误。数据位于 ~/.dsh-bookkeeping（可用 --data-dir 或 DSH_BOOKKEEPING_DATA_DIR 覆盖）。

数据存储

数据目录下单个 SQLite 数据库（ledger.db），WAL 模式。表：

- entries —— id、amount_cents（整数最小单位，恒 > 0）、currency、type（expense/income）、category、remark、tags（JSON 数组）、date（YYYY-MM-DD）、created_at
- category_rules —— 自定义 keyword → category 规则（优先于内置关键词）
- budgets —— (month, category) 限额；category '*' 表示总预算
- meta —— 预留的元数据表

导出文件写入 /exports/ledger-.csv|html。

金额与日期

金额。 支持 35、35.5、¥35、35元、$35.99、1,234.56 等写法。符号决定币种（¥/￥→CNY，$→USD，€→EUR，£→GBP，₩→KRW；后缀 元/块→CNY，円→JPY）。显式 currency 参数可覆盖默认币种，但不得与符号冲突。以下输入会被拒绝：零、负数、非数字文本、千分位格式错误、超出币种小数位精度（CNY/USD 等 2 位，JPY/KRW 0 位）、超过 maxAmount 的金额。

日期。 支持 YYYY-MM-DD、2026/8/17、2026.8.17、2026年8月17日、8/17、8月17日、3月；相对词 今天/今日/昨天/昨日/前天/明天/明日/后天 与 today/yesterday/tomorrow；星期 周X/星期X/礼拜X（映射到当前周一起始的自然周内）、上周X、下周X、裸 上周/下周；偏移 N天前/N天后、N周前/后、N个月前/后；月份 上个月/本月/这个月/下个月（日期按目标月天数截断）。无法解析的日期会报错并列出支持格式。年份范围 1900–2100。

分类

内置分类与关键词自动归类：餐饮、交通、购物、居住、娱乐、医疗、学习、收入、其他（兜底）。匹配为不区分大小写的子串匹配；最长关键词优先，同长时自定义规则优先，均不匹配时归入其他。自定义规则持久化在数据库中，例如 rules add 咖啡豆 购物 之后，任何包含「咖啡豆」的备注都会归为购物。

报表与预算

- daily —— 每日收支；monthly —— 每月收支与净额（收入 − 支出）；category —— 分类汇总（含占比，按金额降序）；trend —— 最近 N 个月月度趋势（空月补零）。
- 起止边界支持 YYYY-MM 或 YYYY-MM-DD（月份边界自动展开为该月首日/末日）。type 默认两者（all），可传 expense/income 收窄。
- 预算按月（YYYY-MM），可设总预算或分类预算。记录支出时立即检查：≥80% 提示接近限额，≥100% 提示超支。收入不消耗预算。budget set … 0 删除预算。总览式 budget check 会报告当月全部预算（总预算与各分类预算）。

开发

npm install
npm run build     # tsc -> dist/
npm test          # tsc + node --test

结构：src/money.ts（金额解析/格式化）、src/dateutil.ts（自然语言日期）、src/categories.ts（内置分类与自动归类）、src/store.ts（SQLite）、src/ledger.ts（领域服务）、src/report.ts / src/budget.ts / src/export.ts（汇总、预算、导出）、src/format.ts（共享文本）、src/tools.ts（dsh 工具）、src/cli.ts（CLI）、src/index.ts（bundle 入口）。测试位于 test/，与模块一一对应。

Bundle 结构

package.json        dsh: { bundle: { patch: "./cordis.patch.yml" } }，type: module，exports，bin
cordis.patch.yml    插入插件行的补丁层（id: bookkeeping, name: dsh-bookkeeping）
dist/src/index.js   入口：export const name / inject / Config / apply(ctx, config)
dist/src/cli.js     独立 CLI（bin: dsh-bookkeeping）

限制

- 不做汇率换算——每条记录保留自己的币种；汇总假设单一币种（混币时按最小单位数值相加，预算按默认币种显示支出合计）。
- bookkeeping_list 的合计仅覆盖当前页；完整合计请用 bookkeeping_report。
- 周X 固定解析到当前周一起始的自然周内（含未来的星期几），此为约定行为。
- 预算以账本默认币种计。
- 数据按设计仅本地存储，不是多用户服务。

License

MIT