record-ai-bookkeeping

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 "用户原话"

新增流水

1. 保留用户原话、消息来源和稳定的消息 ID。消息 ID 用于防止重试时重复写入。

2. 先运行不带 --commit 的命令，读取预览中的金额、币种、类型、分类、账户、日期、账本、置信度和追问。

3. 逐项检查：

   • 金额必须大于 0。
   • 外币必须有该笔确认汇率。
   • 退款必须关联原支出。
   • 报销到账必须关联原垫付。
   • 转账必须有付款账户和收款账户。
   • 累计退款、累计报销到账都不能超过原流水上限。

4. 用户已经明确说“记账/录入/帮我记”，只有一条小额人民币流水，置信度至少 0.85，且没有追问时，可以直接提交。

5. 以下情况先展示预览并等待确认：

   • 多笔批量流水。
   • 金额达到配置中的大额线。
   • 外币、退款、报销、转账、借款或还款。
   • 日期、账户、金额、汇率或关联流水不完整。
   • 分类可能有两种合理解释。

6. 确认后用完全相同的输入和消息 ID 提交：

   python3 "$AI_BOOKKEEPING_HOME/scripts/bookkeeping.py" \
     --config "/absolute/path/to/config.json" \
     record "用户原话" \
     --source-message-id "稳定消息 ID" \
     --commit
   

7. 提交后核对返回的 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-...

批量录入时先给总笔数和合计，再列出需要关注的异常。