pocketbook

# Pocketbook ## Overview Use this skill to operate a personal ledger in a low-friction conversational flow. Prefer fast capture, local persistence, and safe correction over perfect upfront completeness. Keep the ledger append-only. Persist the source utterance, support incomplete entries, and recover a current view by replaying events. ## Trigger Discipline Trigger this skill only when the user is acting on a personal ledger. Trigger immediately for: - Explicit ledger verbs such as `记账`, `记一笔`, `入账`, `查账`, `汇总`, `统计`, `补全上一笔`, `改上一笔`, `撤销上一笔` - Short transaction utterances with a clear money movement, such as `午饭28`, `地铁4元`, `工资到账12000`, `退款80`, `招行转支付宝500` - Ledger queries such as `今天花了多少`, `本月餐饮多少`, `最近三笔`, `按类别统计`, `Top 支出` Ask one brief confirmation before triggering when confidence is only medium, for example: - bare amounts such as `28块` - a category plus amount without an obvious ledger action and without prior ledger context Do not trigger for: - generic note-taking such as `记一下明天开会` - system or product design such as `帮我做个记账系统` - budgeting, investment, tax, accounting, reimbursement, OCR, or price lookup requests unless the user is explicitly operating the ledger If the user is designing or debugging bookkeeping software instead of using the ledger, stay in normal coding or discussion mode and do not use this skill. When trigger confidence is unclear, read [references/intent-examples.md](references/intent-examples.md). ## Operating Model Treat the ledger as an event stream, not as mutable rows. Use these event types: - `create` for new entries - `update` for corrections or completion - `revert` for undo Persist all facts in `ledger.jsonl`. Treat `personal_finance.md` as a derived human-readable view that can be regenerated at any time. ## Data Root Pick a stable local directory on persistent storage. If the user does not provide one, default to `~/.openclaw/pocketbook/default`. Keep these files in the same data root: - `ledger.jsonl` - `personal_finance.md` - `profile.json` for user defaults and aliases Use the same `--data-dir` for every script invocation in the session. ## Workflow ### 1. Capture Quickly Extract as many of these fields as possible from the user utterance: - `entry_type`: `expense`, `income`, `refund`, or `transfer` - `amount` - `occurred_at` - `category` - `payment_method` - `account` - `merchant` - `note` Require `amount`. If it is missing, ask for it. Default the date or time to now in `Asia/Shanghai` when the user does not specify it, and add the inferred field name to `inferred_fields`. If `profile.json` exists, use its defaults and aliases before falling back to `unknown`. This is the preferred place for normalizing terms such as `微信 -> wechat` or `招行 -> cmb`. Allow `category`, `payment_method`, and `account` to be missing. Persist them as `unknown`, mark the entry `incomplete`, and continue without extra questions unless the user explicitly wants a precise record right now. Set `needs_review` when: - the category is only a guess - the user wording is ambiguous - duplicate risk is non-trivial After capture, reply briefly with what was stored and what remains to be completed. ### 2. Query and Summarize Use the query script to answer questions like: - current day, week, or month spending - recent entries - pending completion items - category and payment method breakdowns Apply these semantics consistently: - `花了多少` means expense total only - `净流出` means `expense - refund` - `transfer` does not count as spending unless the user explicitly asks for transfers ### 3. Complete Later When the user asks to fill in missing details, list pending entries first if needed, then update the target entry. Prefer `上一笔` or `最近 N 笔` resolution over guessing. Treat an entry as pending when any of these are true: - `status` is `incomplete` - `needs_review` is `true` - `category`, `payment_method`, or `account` is `unknown` ### 4. Correct or Undo Safely Never rewrite or delete existing lines in `ledger.jsonl`. Use `update` events to modify the current state of an entry. Use `revert` events to undo an entry. If `上一笔` could refer to more than one plausible entry, show the recent candidates and ask the user to choose. Do not silently edit the wrong entry. ## Scripts Read [references/schema.md](references/schema.md) before changing the JSON payload shape. Use these scripts: - `python scripts/append_ledger.py create --data-dir <dir> --payload <json-file-or->` - `python scripts/append_ledger.py update --data-dir <dir> --payload <json-file-or->` - `python scripts/append_ledger.py revert --data-dir <dir> --payload <json-file-or->` - `python scripts/query_ledger.py recent --data-dir <dir> --limit 5` - `python scripts/query_ledger.py summary --data-dir <dir> --period today` - `python scripts/query_ledger.py pending --data-dir <dir> --limit 10` - `python scripts/edit_recent.py update-last --data-dir <dir> --payload <json-file-or->` - `python scripts/edit_recent.py revert-last --data-dir <dir> --payload <json-file-or->` - `python scripts/render_finance_md.py --data-dir <dir>` - `python scripts/profile_manager.py show --data-dir <dir>` - `python scripts/profile_manager.py set-default --data-dir <dir> --field payment_method --value wechat` - `python scripts/profile_manager.py set-alias --data-dir <dir> --field account --alias 招行 --value cmb` Pass structured payloads to scripts. Do not ask the scripts to interpret free-form language. ## Response Style Keep replies short and ledger-oriented. Good confirmation style: - `已记：今天午饭 28.00 元，分类餐饮，支付方式待补充。` - `已撤销最近一笔：地铁 4.00 元。` - `今天支出 86.00 元，其中餐饮 58.00 元。` If the scripts surface duplicate candidates, warn briefly and let the user decide whether this is a second entry or a duplicate.