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

---

name: billclaw

description: Drives the BillClaw local bookkeeping CLI against SQLite (db/expenses.db) via scripts/main.py JSON subcommands—add/query transactions, delete and category-merge with preview+confirm, user-defined categories, reports with chart PNGs, CSV export, and a local Flask dashboard. Use when the user tracks 记账/收支/账本, manages 分类, asks for 报表 or charts, wants to open the Web 看板, exports CSV, or mentions BillClaw or running main.py (root shim) / scripts/main.py.

---

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

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

---

1. 功能概览

**环境变量**：`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 '{...}'`

常用字段：

将 `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"}'`

---

Intent G：打开 Web 看板

`python scripts/main.py serve --json-string '{"host":"127.0.0.1","port":8000}'`

（进程会占用终端，需告知用户浏览器访问 `http://127.0.0.1:8000`。）

页面含：日期范围筛选与快捷预设（全部/本年至今/近三月/近一月）、总收支 KPI、**支出与收入分类**环形图、每日折线（滚轮缩放/拖拽平移，可重置）、按月收支柱状图、可排序分页交易表（可选仅收入/仅支出）。前端为 `scripts/dashboard.html`，JS 库在 `scripts/static/vendor/`（离线可用，见该目录 `README.md`）；中文字体使用系统字体栈。

---

Intent H：导出 CSV（可选）

`python scripts/main.py export-csv --json-string '{"path":"./bills.csv","date_from":"2026-01-01"}'`

---

3. 子命令一览

| 子命令 | 作用 |

|--------|------|

| `add` | 插入一条交易 |

| `query` | 条件查询 |

| `delete-preview` / `delete-confirm` | 删除预览 / 执行删除 |

| `merge-preview` / `merge-confirm` | 改类预览 / 执行批量更新 category |

| `category-add` / `category-list` | 自定义分类 |

| `report` | 统计 + 出图 |

| `export-csv` | 导出 |

| `parse` | 从文本抽取时间/金额/类型/分类提示 |

| `serve` | 启动 Flask 看板 |

---

4. 输入 / 输出约定

---

5. 示例对话（覆盖常见场景）

5.1 正常记账

5.2 模糊时间

5.3 金额异常

5.4 新增分类

5.5 删除记录

5.6 报表

5.7 Web 看板

---

6. 异常与用户确认策略（必须遵守）

1. **删除、批量改分类**：必须 preview → 用户明确确认 → confirm。

2. **时间不确定**：追问具体日期。

3. **金额与场景明显不符**：追问是否输错。

4. **类型不明**：问清收入还是支出。

5. **输出风格**：简洁、有温度；避免生硬系统提示腔。

---

7. 文件与依赖

若 `serve` 或 `report` 报错缺依赖，提示用户执行 `pip install -r requirements.txt`。

---

8. output 目录与定时清理