BillClaw 记账 Skill（OpenClaw / Agent 使用说明）

本 Skill 通过本地 Python CLI 操作 SQLite 账本（db/expenses.db），实现记账、分类管理、报表图表与 Web 看板。Agent 负责自然语言理解与二次确认；脚本负责结构化读写与一致性。

1. 功能概览

• 记账（结构化字段；可选 parse_text 辅助从片段补全字段）
• 条件查询（日期范围、类型、分类、备注关键词等）
• 删除（先 preview 列候选，用户确认后再 confirm）
• 分类归并（先 preview，用户确认后再批量改 category）
• 用户自定义分类（user_categories 表；记账时 category 可直接用自定义名）
• 报表：深色主题多图 PNG（合图 report_dashboard.png：KPI + 支出/收入环形图 + 每日趋势 + 按月柱图；另有单图 expense_by_category.png、income_by_category.png、daily_trend.png、monthly_bar.png）+ 结构化 highlights（供你生成有温度的中文总结）；data.agent_json 中含 primary_chart 指向合图路径
• Web 看板：本地 Flask + scripts/dashboard.html + scripts/static/vendor 内 Chart.js，支持时间筛选、按月柱状图、分页明细与图表交互（缩放/平移等），离线可开页
• 导出 CSV（可选）

环境变量：BILLCLAW_DB_PATH 可覆盖默认数据库路径。

调用方式：在项目根目录执行 python scripts/main.py <子命令> --json-string '<JSON>' 或 --json 文件.json；亦可使用根目录 python main.py ...（转发到同一入口）。标准输出为一行 JSON：{"ok": bool, "error": str|null, "data": {...}}。

2. 用户意图（Intent）与处理流程

Intent A：记一笔账

1. 从用户话中提取：date（YYYY-MM-DD）、type（收入|支出）、category、amount（元）、note。
2. 若字段不全，可调用 parse 子命令辅助：
   python scripts/main.py parse --json-string '{"text":"<用户原句或片段>"}'
   使用返回的 time.date、amount.value、type_hint、category_hint 补全（仍需你判断是否ambiguous）。
3. 时间模糊：若 parse 或你的理解中 ambiguous: true，先问用户确认日期/时刻，再 add。
4. 金额异常：若 add 的 data 中含 suspicious: true，先向用户确认是否输错，再决定是否重新 add 或取消。
5. 写入：
   python scripts/main.py add --json-string '{"date":"...","type":"支出","category":"正餐","amount":35,"note":"..."}'
   可选："parse_text":"昨天午饭38" 与上述字段合并（缺省字段由解析补全）。

默认支出分类：正餐、零食饮料、出行、购物、日常开销、娱乐、居住、医疗健康、家人、社交、其他。
默认收入分类：工资、奖金、投资、家人、其他收入。
用户自定义分类可先走 Intent D，之后记账 category 填该名称即可。

Intent B：查账 / 列表

python scripts/main.py query --json-string '{...}'

常用字段：

• date_from, date_to（含边界，格式建议 YYYY-MM-DD）
• type：收入 / 支出
• category：精确匹配
• category_like：SQL LIKE 子串
• note_like：备注 LIKE
• keyword_in_note：备注或分类中包含关键词
• limit：默认 500

将 data.rows 用简洁表格或列表回复用户。

Intent C：删除记录

禁止直接删除。 必须两步：

1. delete-preview：与 query 相同过滤字段，返回 data.preview_rows 与 data.ids。
2. 向用户展示将删除的记录，得到明确确认后：
   delete-confirm：{"ids":[...]}

Intent D：新增自定义分类

python scripts/main.py category-add --json-string '{"name":"恋爱","kind":"支出"}'
kind 只能是 收入 或 支出。
可用 category-list 查看已有用户分类。

Intent E：分类归并（把一批记录改到新类）

1. merge-preview：用 keyword_in_note、old_category、old_category_like、date_from/date_to、type（默认可筛支出）等缩小范围。
2. 展示 preview_rows，用户确认后：
   merge-confirm：{"ids":[...],"new_category":"恋爱"}

Intent F：报表（图表 + 口语化总结）

python scripts/main.py report --json-string '{"date_from":"2026-03-01","date_to":"2026-03-31","output_dir":"./billclaw_output"}'