statement-bookkeeping

把微信 / 支付宝 / 京东金融 / 银行对账单合并成一本账的 AI 记账工作流（Agent Skill）。

由用户提供多平台账单文件，Agent 负责：合并 → 去重 → 区分转账与收支 → 分类，产出复核稿，用户确认后写入 ezBookkeeping（自托管记账应用）。

定位：Agent 是记账员（bookkeeper），不是收银员。未确认前绝不写入。

特性

• 确定性解析器：scripts/parse_statements.py 本地解析微信/支付宝/京东/银行 CSV（处理 GBK/GB18030、表头广告、列名漂移、银行收支分列、金额千分位），并支持按 mapping 分类 + 跨平台去重
• 多平台合并：微信支付 / 支付宝 App / 支付宝 Web / 京东金融 / 银行 CSV / OFX 等
• 跨平台去重：同一笔消费同时出现在钱包和银行卡时，保留支付渠道行（信息更全），丢弃银行行
• 转账识别：充值 / 提现 / 信用卡还款 / 花呗还款 / 零钱通互转等计为转账，不计入盈亏
• 强制复核：入账前生成复核稿（汇总 / 账户净变动 / review 行 / transfer 行），等用户明确确认
• 双写入通道：≤40 行走 ezBookkeeping MCP add_transaction；量大改出 CSV 走官方导入
• 隐私保护：解析优先本地完成，确需云端读账单时脱敏（账号 / 身份证 / 手机号剥离，卡号只留后 4 位）

工作流

阶段	内容
Phase 0 准备	识别平台 → 拉取 ezBookkeeping 账户/分类/标签/同期交易 → 加载用户映射
Phase 1 解析	按统一 schema 规范化每行（处理表头广告、GBK 编码、列名漂移）
Phase 2 分类	支出 / 收入 / 转账 / 忽略 / 待查
Phase 3 去重	同文件 → 跨平台同消费 → 内部流转配对 → 对已有账本去重
Phase 4 复核	强制停点：生成复核稿，等用户确认或指正
Phase 5 入账	MCP dry_run 先行 → 确认后写入；或生成导入 CSV；入账后对账校验

安装

git clone https://github.com/<you>/statement-bookkeeping.git
cp -r statement-bookkeeping ~/.hermes/skills/productivity/

（Claude Code / 其他支持 SKILL.md 的 Agent 同理，放入其 skills 目录。）

使用

把账单文件丢给 Agent，说「记账」或「合并对账」即可。Agent 会按 Phase 0→4 走完并给出复核稿，你说「确认入账」后才写入。

首次使用建议复制 assets/mapping.example.yaml 为 mapping.yaml，把账户名 / 分类名改成与你的 ezBookkeeping 完全一致，并按需调整商户规则。

依赖

• ezBookkeeping 实例（自托管，mayswind/ezbookkeeping）
• MCP 连接：ezBookkeeping 开启 enable_mcp，Agent 配置好 MCP 服务器（端点 /mcp + Bearer token）
  • 用到的工具：query_all_accounts query_all_transaction_categories query_all_transaction_tags query_transactions add_transaction（及对账用的 query_all_accounts_balance）
• 没有 MCP 时：工作流止步于复核稿 + 导入 CSV（可用官方导入 UI）

目录结构

statement-bookkeeping/
├── SKILL.md                     # 主工作流（硬规则 + 6 阶段）
├── scripts/
│   └── parse_statements.py      # 本地解析/分类/去重脚本（确定性）
├── references/
│   ├── platforms.md             # 各平台账单格式与坑
│   └── ezbookkeeping.md         # MCP 入账 / CSV 导入细节
└── assets/
    ├── mapping.example.yaml     # 账户/分类映射 + 退款策略 + 商户规则模板
    ├── review-schema.json       # 规范化行 schema（status/type 解耦、条件必填）
    └── review-template.md       # 复核稿模板

本地解析器

python3 scripts/parse_statements.py parse 微信账单.csv 支付宝流水.csv 银行对账单.csv \
  --mapping mapping.yaml --out normalized.jsonl     # 解析(+分类)
python3 scripts/parse_statements.py dedup normalized.jsonl --mapping mapping.yaml \
  --out ready.jsonl                                  # 跨平台去重

支持：GBK/GB18030/UTF-8 自动探测、表头广告跳过、列名漂移容错、银行收入/支出分列、1,299.00 千分位、交易日期/时间分列合并、parse/classify/dedup 三子命令。

Known limitations / 设计取舍

• 跨平台去重只处理「支付 App vs 银行」；微信 vs 支付宝同消费不自动去重（避免误杀真实重复消费），由复核阶段人工看
• 退款默认 review（mapping refund_policy 可改为 income/pair），避免虚增盈亏
• 商户规则为子串匹配，短词（如"京东"）可能误伤"京东支付"通道行——mapping 里用 exclude_patterns 先行过滤，或改用更长关键词
• 解析脚本是尽力而为的确定性工具；遇到新格式/解析告警时，模型仍可按 SKILL.md 手工规范化兜底

License

MIT