pocketbook

Record, query, complete, correct, and undo personal bookkeeping entries through short natural-language conversation, with local JSONL and Markdown persistenc...

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.

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 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.