bookkeeping - SKILL.md Agent Skill

name: bookkeeping description: 記帳系統。解析自然語言記帳指令，寫入 SQLite 資料庫並同步 Beancount 帳本。Use when user wants to record expenses, check spending, query transaction history, or manage accounts. Triggers on keywords like "記帳", "記賬", "花了", "買了", "支出", "收入", amount+category patterns (e.g. "40 飲料", "午餐 200").

Bookkeeping Skill

解析自然語言記帳 → SQLite（source of truth）→ 同步 Beancount。

檔案結構

bookkeeping/
├── SKILL.md
├── scripts/
│   ├── init_db.py          # 初始化 SQLite
│   ├── add_transaction.py  # 新增交易
│   └── sync_beancount.py   # SQLite → Beancount 全量同步
└── references/
    └── accounts.md         # 帳戶對照表

資料路徑

SQLite: ~/.openclaw/workspace/ledger/bookkeeping.db
Beancount: ~/.openclaw/workspace/ledger/main.beancount

核心流程：記帳

收到記帳訊息（如 "40 飲料"、"午餐便當80 飲料40"）
解析出交易列表：每筆含 date, payee, narration, account, amount
執行 scripts/add_transaction.py，傳入原始訊息 + 解析結果（如有提到店家，加 shop 欄位）
腳本自動：寫入 SQLite + append Beancount
回覆確認

解析規則

金額 + 類別：「40 飲料」→ amount=40, narration=飲料
類別 + 金額：「午餐 200」→ amount=200, narration=午餐
多筆合一：「午餐80 飲料40」→ 兩筆交易，共用同一 message
日期預設今天，可指定：「昨天午餐 150」「2/20 加油 1500」
帳戶映射見 references/accounts.md
店家（shop）：用戶有提到才記錄，沒提不強制（如「麥當勞晚餐169」→ shop=麥當勞）

付款方式

預設：Assets:Cash
可指定：「刷卡午餐 300」→ Liabilities:CreditCard
關鍵字：刷卡/信用卡 → CreditCard，轉帳 → Bank:Checking

查詢

「今天花了多少」→ 查 SQLite 當日 SUM
「這個月飲料花了多少」→ 按 account + 月份查詢
「最近的記帳」→ 最近 N 筆

add_transaction.py 用法

# 無店家
python3 scripts/add_transaction.py \
  --db ~/.openclaw/workspace/ledger/bookkeeping.db \
  --beancount ~/.openclaw/workspace/ledger/main.beancount \
  --message "40 飲料" \
  --sender "2078364301" \
  --transactions '[{"date":"2026-02-24","payee":"飲料店","narration":"飲料","account":"Expenses:Food:Drinks","amount":40,"currency":"TWD"}]'

# 有店家
python3 scripts/add_transaction.py \
  --db ~/.openclaw/workspace/ledger/bookkeeping.db \
  --beancount ~/.openclaw/workspace/ledger/main.beancount \
  --message "麥當勞 晚餐169" \
  --sender "2078364301" \
  --transactions '[{"date":"2026-02-24","payee":"麥當勞","narration":"晚餐","account":"Expenses:Food:DiningOut","amount":169,"currency":"TWD","shop":"麥當勞"}]'

注意事項

SQLite 是 source of truth，Beancount 可由 SQLite 重新生成
重複記帳檢查：同一 message 不重複寫入
Beancount payee 欄位必填（格式："payee" "narration"）
相對日期（昨天、上禮拜五）先用 date 命令確認再計算