cashbook

Local-first personal bookkeeping Skill (SQLite). Supports natural language and screenshot-based expense recording, account management, budget tracking, weekl...

Security Scan

The skill's code and instructions mostly match a local SQLite bookkeeping tool, but there are inconsistencies (missing export script and a claim of “zero cloud dependency” while instructions call an image/OCR tool) that you should review before installing.

Purpose & Capability

Name/description (local-first personal bookkeeping) align with the included Python scripts (accounts, transactions, budgets, CSV import, reports). The only capability that looks out-of-place is the SKILL/README claim of “zero cloud dependency” while the runtime instructions rely on an 'image' tool for screenshot OCR — that can involve external processing depending on the platform.

Instruction Scope

SKILL.md instructs the agent to call a platform 'image' tool to parse screenshots (expected for OCR) but that may send receipt images off-device depending on the platform/tool implementation, which contradicts the README's '100% local storage / zero cloud dependency' claim. Also multiple docs and the SKILL.md reference a scripts/export.py command for data export, but no export.py file is present in the provided files — an inconsistency that could break functionality or indicate incomplete packaging.

Install Mechanism

No install spec (instruction-only) and only bundled Python scripts. No external downloads, package installs, or archive extraction. Risk from install mechanism is low.

Credentials

No required environment variables or credentials. The only env var read is CASHBOOK_DB (optional override for DB path) which is proportional and expected.

Persistence & Privilege

Skill does not request always:true and is user-invocable; scripts run on-demand. No evidence the skill attempts to modify other skills or system-wide configs.

What to consider before installing

What to consider before installing/using: - Functionality: The Python scripts implement a local SQLite bookkeeping app and appear coherent for the stated purpose (add/query/delete transactions, budgets, CSV import). Most behavior is local and readable in the provided source. - Missing file: The documentation and SKILL.md mention scripts/export.py for exporting CSVs, but that file is not present in the supplied package. Expect export commands to fail unless the missing script is provided. Ask the publisher for the missing file or a corrected README/SKILL.md. - Image/OCR privacy: The SKILL.md instructs the agent to call an 'image' tool to parse screenshots. Depending on your platform, that tool may send image data to external services for OCR (i.e., receipts could leave your device). If you require strict local-only processing, confirm whether the platform's image tool processes images locally or externally; disable/avoid screenshot OCR if you don't want images sent off-device. - Data location & permissions: By default the DB is stored at ~/.local/share/cashbook/cashbook.db and can be overridden via CASHBOOK_DB. Verify filesystem permissions for that path if other users share the machine. - CSV import behavior: import_csv.py auto-creates categories and updates balances; test with --dry-run first to avoid accidental imports. It attempts multiple encodings when reading files. - Audit & testing: If you plan to use this for real finances, run the scripts in a safe environment, test create/delete flows, and inspect/backup the DB file. Ask the author for the missing export script and clarification about OCR/image handling to resolve the documented contradictions.

面向中文用户的本地记账 Skill。数据存储在本地 SQLite，用户拥有完整数据主权。

开箱即用

首次使用时数据库自动创建（建表 + 预置分类），无需手动初始化。

用户第一次记账时，若还没有账户，先引导创建一个默认账户：

python3 scripts/account.py add --nickname "默认钱包" --type wallet
python3 scripts/account.py default --id 1

数据库路径：~/.local/share/cashbook/cashbook.db（可通过 CASHBOOK_DB 环境变量覆盖）
如需重置：python3 scripts/init.py --force

---

核心工作流

1. 自然语言记账

从用户输入提取结构化字段，调用 scripts/add_tx.py：

python3 scripts/add_tx.py \
  --amount 38 --type expense --category 餐饮 \
  --account "招行信用卡" --date today --note "星巴克"

解析字段： 金额、收/支类型、分类、账户（可选）、日期、备注/商户
时间表达： 支持"今天/昨天/上周三/3月10日"等，统一转为 YYYY-MM-DD
确认流程： 解析后先展示给用户确认，确认后再写入

多语言支持： 用户可用中文、英文或日文描述交易，分类传参支持英文别名（如 food→餐饮、transport→交通、shopping→购物）。无论用户用什么语言，--category 传中文分类名或英文别名均可。

2. 截图记账

用户上传图片时，使用 image tool 分析截图，提取关键字段后走确认流程入库。

支持类型： 微信支付截图、支付宝截图、POS 小票、外卖/电商订单截图

工作流：

1. 调用 image tool，prompt 示例：

   这是一张支付截图。请提取以下字段（JSON 格式返回）：amount（金额，数字）、merchant（商户名）、date（日期，YYYY-MM-DD，无法确定则用今天）、pay_method（支付方式，如微信/支付宝/银行卡）、type（expense/income）

2. 展示解析结果，请用户确认或修改：

   解析结果：支出 ¥38.00 / 星巴克 / 2026-03-16 / 微信支付
   分类建议：餐饮。确认入账？（可修改分类/金额/日期）

3. 用户确认后调用 add_tx.py 写入，--source screenshot
4. 多张截图： 逐张解析，全部展示后统一确认批量入库

解析失败处理： 图片模糊或字段缺失时，告知用户并请求补充信息，不强行入库。

3. 删除记录

python3 scripts/delete_tx.py --id 5          # 按 ID 删除
python3 scripts/delete_tx.py --last 1 --yes  # 删最新一条（跳过确认）

删除会自动回滚账户余额。先用 query.py --last 10 确认 ID 再删。

4. 账户管理

详见 references/account.md

python3 scripts/account.py add --nickname "招行储蓄卡" --type debit --last4 1234
python3 scripts/account.py list
python3 scripts/account.py default --id 1
python3 scripts/account.py edit --id 1 --nickname "新名字"
python3 scripts/account.py delete --id 2

5. 预算管理

详见 references/budget.md

python3 scripts/budget.py set --category 餐饮 --amount 2000          # 月度分类预算
python3 scripts/budget.py set --amount 8000                          # 月度总预算
python3 scripts/budget.py query --all                                 # 查所有分类进度
python3 scripts/budget.py query --category 餐饮                       # 查单个分类
python3 scripts/budget.py list
python3 scripts/budget.py delete --category 餐饮

6. 查询流水

python3 scripts/query.py --last 10                          # 最近10条明细
python3 scripts/query.py --period month                     # 本月汇总
python3 scripts/query.py --period week --category 餐饮      # 本周餐饮
python3 scripts/query.py --from 2026-03-01 --to 2026-03-15

7. 周报 / 月报

python3 scripts/report.py --period week
python3 scripts/report.py --period month
python3 scripts/report.py --period month --year 2026 --month 2   # 指定月份

报告含：收支汇总、分类分布 + ASCII 进度条、预算执行情况（月报）、最高单笔。

8. CSV 导入（支付宝 / 微信）

python3 scripts/import_csv.py --file ~/Downloads/alipay_record.csv --account "支付宝"
python3 scripts/import_csv.py --file ~/Downloads/wechat_record.csv --account "微信钱包"
python3 scripts/import_csv.py --file xx.csv --dry-run   # 预览不写入

自动检测格式、分类映射、重复跳过。

9. 数据导出

python3 scripts/export.py --format csv
python3 scripts/export.py --format csv --from 2026-01-01 --to 2026-03-31

默认输出到 ~/Downloads/cashbook-YYYY-MM.csv

---

分类

支出预置：餐饮、交通、购物、娱乐、医疗、住房、教育、旅行、其他
收入预置：工资、奖金、副业、其他
自定义：python3 scripts/category.py add --name 宠物 --type expense

不存储的敏感信息

完整卡号、CVV、密码、银行登录凭证。只存：昵称、卡类型、尾号（可选）。

数据模型

见 references/schema.md