| name | record-ai-bookkeeping |
| description | 用自然语言录入和维护个人账目。当用户说“记一笔”“今天花了”“买了什么”“收到工资”“退款了”“报销垫付”“报销到账”“转账”“改一下刚才那笔”“撤销上一笔”或“恢复流水”时触发。负责分类、预览、去重、提交、修改和可恢复撤销。 |
Record AI Bookkeeping
把用户的一句话拆成一条或多条可核对流水，写入统一账本。
何时触发
- “记一笔：今天午饭 46，支付宝”
- “早上咖啡 18，中午面 32，晚上打车 56，都走支付宝”
- “今天和小王吃饭我付了 260，其中 130 公司报销”
- “从招行转 3000 到支付宝”
- “大阪晚饭 4200 日元，汇率 0.049，Visa”
- “这单退了 80 / 报销到账 130”
- “刚才金额写错了 / 撤销上一笔 / 恢复那笔”
共用入口
所有操作都通过共享脚本，配置路径在本次会话中保持一致：
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
--config "/absolute/path/to/config.json" record "用户原话"
新增流水
-
保留用户原话、消息来源和稳定的消息 ID。消息 ID 用于防止重试时重复写入。
-
先运行不带 --commit 的命令，读取预览中的金额、币种、类型、分类、账户、日期、账本、置信度和追问。
-
逐项检查：
- 金额必须大于 0。
- 外币必须有该笔确认汇率。
- 退款必须关联原支出。
- 报销到账必须关联原垫付。
- 转账必须有付款账户和收款账户。
- 累计退款、累计报销到账都不能超过原流水上限。
-
用户已经明确说“记账/录入/帮我记”，只有一条小额人民币流水，置信度至少 0.85，且没有追问时，可以直接提交。
-
以下情况先展示预览并等待确认：
- 多笔批量流水。
- 金额达到配置中的大额线。
- 外币、退款、报销、转账、借款或还款。
- 日期、账户、金额、汇率或关联流水不完整。
- 分类可能有两种合理解释。
-
确认后用完全相同的输入和消息 ID 提交：
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
--config "/absolute/path/to/config.json" \
record "用户原话" \
--source-message-id "稳定消息 ID" \
--commit
-
提交后核对返回的 created_count、duplicate_count 和流水 ID，再用一句话回执。
开放式表达
内置解析器覆盖 examples/natural-language.md 中的高频句式。遇到更自由的表达时，先整理为结构化 JSON，字段参照 schema/transactions.schema.json，然后预览：
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
--config "/absolute/path/to/config.json" record-json input.json
用户确认后追加 --commit。不要补造金额、日期、汇率、账户或关联 ID。
修改、撤销和恢复
修改基础字段：
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
--config "/absolute/path/to/config.json" \
update "BK-..." '{"amount":"38"}' --reason "用户纠正金额"
金额、类型、币种、汇率、可报销金额变更后，系统会重算本位币金额、现金流和个人消费。派生金额不能直接改。
撤销与恢复：
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" --config "/absolute/path/to/config.json" undo "BK-..."
python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" --config "/absolute/path/to/config.json" restore "BK-..."
没有流水 ID 的“撤销上一笔”会撤销最近一条有效流水。回复时必须带回被操作的流水 ID、金额和状态。
分类原则
- 优先使用现有二级分类和用户历史习惯。
- 旅行费用写入具体项目账本，同时保留餐饮、交通、住宿等消费分类。
- 房租、水电、保险、订阅等标为固定或弹性，再标必要性。
- 退款沿用原消费的分类、账本和消费属性。
- 报销垫付的个人消费只保留用户最终承担的部分。
边界与异常
- 同一个来源消息重复提交时，把它当作同一笔，回报“已存在”。
- 找不到唯一的退款或报销原流水时，只问一个最小问题。
- 用户说“改刚才那笔”时，先展示最近一笔的关键信息再修改。
- 撤销保留历史，禁止物理删除。
- 报销到账撤销或恢复后，要再次核对原垫付的报销状态。
- 用户手工锁定的分类，后续自动分类不能覆盖。
回执格式
已记 1 笔：7 月 1 日午饭 46.00 元，餐饮 / 午餐，支付宝。
流水 ID：BK-...
批量录入时先给总笔数和合计，再列出需要关注的异常。
