DeepSeek Harness 對話式記賬插件：bookkeeping

前言¶

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         # 可選，單筆最大金額（單位）

典型用法¶

對話模式
在 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 倉庫。

GitHub 倉庫
插件目錄頁