前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在构建智能体应用时，开发者常需要为模型提供数据处理能力。对于财务记录类任务，手动编写数据库交互逻辑既繁琐又容易出错。bookkeeping 是一个专为 DSH 设计的插件，它允许用户通过自然语言对话完成记账、查询账目、生成报表和导出数据，同时支持本地持久化存储。
核心功能¶
对话式记账
插件支持通过自然语言输入金额、日期和备注。模型会自动解析日期（支持相对时间如“昨天”、“上周”）并尝试匹配默认分类（如“午饭”、“打车”）。金额输入支持多种格式（如 35、¥35、35元）。
本地数据持久化
数据存储在本地 SQLite 数据库中。金额以整数分的形式存储，确保精度。所有数据默认保存在 ~/.dsh-bookkeeping 目录下（可通过环境变量覆盖）。
分类与规则
内置了标准的分类系统（餐饮、交通、购物等）。支持通过关键词自动分类，并允许用户自定义规则（如将“咖啡豆”自动归类为“购物”）。
报表与导出
支持按日、月、分类查看收支汇总。支持导出为 CSV（遵循 RFC 4180 标准）和自包含的 HTML 报表。
月度预算
可以设置月度预算（全局或分类）。当支出达到预算的 80% 时会发出警告，超过预算时也会提示。
双模式运行
插件既可作为模型可调用的工具（Tool）集成在 DSH 进程中，也可作为独立的命令行工具（CLI）运行。
安装与配置¶
环境要求
- Node.js ^22.19.0 || >=24.0.0
- 已安装 DeepSeek Harness (dsh)
- pnpm 需在系统 PATH 中可用
安装步骤
1. 克隆或下载插件源码。
2. 进入目录并构建：npm install && npm run build。
3. 安装插件到指定 Profile：dsh plugin --profile bookkeeping add <path/to/dsh-bookkeeping>。
4. 启动 DSH 并验证配置：dsh --profile bookkeeping --dump-config。
配置示例
配置通过 Profile 的 cordis.patch.yml 文件提供，以下为示例：
- insert:
- id: bookkeeping
name: dsh-bookkeeping
config:
dataDir: /var/data/bookkeeping # 可选，默认 ~/.dsh-bookkeeping
currency: CNY # 可选，默认 CNY
maxAmount: 1000000000000 # 可选，单笔最大金额（单位）
| Key | Type | Default | Meaning |
|---|---|---|---|
dataDir |
string | ~/.dsh-bookkeeping |
数据库和导出目录。也可通过环境变量 DSH_BOOKKEEPING_DATA_DIR 覆盖。 |
currency |
string | CNY |
当金额不带货币符号时的默认货币。 |
maxAmount |
number | 1_000_000_000_000 |
单笔金额的上限（单位）。 |
典型用法¶
对话模式
在 DSH 聊天窗口中，模型可以直接调用工具：
用户：记一笔 午饭 35
用户：昨天打车花了 28
用户：花了多少钱在餐饮上？
用户：导出 csv
用户：设置本月预算 5000
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
数据与限制¶
数据存储
数据库文件为 ledger.db。主要表包括 entries（记录明细）、category_rules（自定义规则）、budgets（预算）和 meta（元数据）。
金额限制
- 金额必须为正数，零和负数会被拒绝。
- 支持的货币符号映射：¥/￥->CNY，$->USD，€->EUR，£->GBP，₩->KRW。
- 金额需为整数分（小数位不超过货币支持范围，如 CNY/USD 为 2 位，JPY/KRW 为 0 位）。
日期范围
支持的日期解析范围：1900-2100。支持相对时间（今天、昨天、前天、N天前等）和中文/英文相对词。
退出码
CLI 工具的退出码：0（成功），1（域错误，如金额无效），2（用法错误）。
适用场景与注意¶
适用场景
- 需要智能体处理个人财务记录的开发者。
- 需要轻量级本地记账方案，且希望利用 DSH 生态的开发者。
注意事项
- 插件以当前 DSH 进程的权限运行，请确保安装的源码安全。
- 金额和日期解析有严格限制，超出范围的输入会被拒绝。
- 数据存储在本地，请注意备份 ledger.db 文件。
生态与链接¶
该插件属于 DSH 生态，与 DeepSeek 或幻方官方无从属关系。更多细节和源码，请参考插件目录页或 GitHub 仓库。
