流水分好类

---
name: statement-sorter
description: 给自由职业者和小店主，把贴过来的银行流水或 CSV 分好类，变成一份会自动更新的 Excel：每行有下拉可以改分类，有分类汇总和月度汇总，第一张表写明要你决定什么。每一行都标明“待你决定”“你说的”或“我们的猜测，没核对”，并写清原因。私人开支、大额购置、自己账户之间的转账单独放，没定的钱一直显示，所以没分完的表不会看起来像分完了。脚本会和流水核对，对不上就直接报错。支持中文和英文，在本机运行，不上传任何内容。支付宝和微信的列名来自公开样本文件，不是官方规格，也没有用真实导出试过。不提供税务建议。当有人想整理或分类银行流水、交易 CSV、支付宝或微信账单时使用。
version: 1.1.0
---

# 流水分好类

对方给一份流水，拿回一份可以自己定完的工作簿。他看到的内容除了“Excel 文件”，不提脚本和公式。安装和运行都由你来做。

## 先说隐私

流水很敏感。脚本都在这台电脑上运行，不上传任何内容。唯一的下载是 XlsxWriter 这个库，只下一次，不带任何流水内容。

但如果他把流水贴进对话，运行你的 AI 服务就会收到它。贴之前先告诉他，并提供更私密的做法：

1. 他把流水存成文件，把路径给你。
2. 你用路径运行 `make.py`，不打开文件。它只输出行数和行号。
3. 你运行 `check.mjs`，它不会输出流水里的任何一行。
4. 你不看工作簿、`overview.html` 和 `overview.png`，直接交付，并告诉他你没有看过。

不要把真实流水放进代码库、共享文件夹或示例。用完删掉临时副本。真实结果文件的权限只有当前用户能读。

## 要问的信息

必须有：
1. 流水：文件路径（最好），或贴过来的文字。银行流水、CSV，或支付宝、微信账单导出都可以。

接着问，一次问几个，可以回答“不知道”：
2. 商家名称和语言（中文或英文）。默认用他写字用的语言。
3. 币种。一份工作簿只放一种币种。
4. 他自己的其他账户，用流水上出现的文字（比如“储蓄账户6621”）。只有这些才算确认过的转账。
5. 已经知道的收付款方，写成规则：“云岫民宿是客户”“某某是软件订阅”。
6. 多大金额要问一声是不是大额购置。这个数只决定什么时候问，别的都不决定。它不是税务规定，不能说成税务规定。不知道就不填：默认 ¥5,000 或 A$1,000，工作簿会把它列为假设。
7. 期初和期末余额，如果流水上没有。
8. 日期写法，只在 03/04/2026 这种有两种读法时才问。

## 规则

- 绝不悄悄猜。每一行只有这几种状态：
  - **待你决定**：在等他，并写清要问什么。这笔钱算在“还没决定”里，不进任何合计。
  - **你说的**：他确认过，通过规则、他的账户或单行决定。
  - **我们的猜测，没核对**：只凭一个很少是私人用途的词（发票款、手续费、代账）猜的，没人确认。第一张表会请他看一遍；这些行打勾或改掉之前，不会出现“都答过了”那句话。
- 一个词绝不能决定可能是私人或借款的行。房租、话费、保险、电费、加油、订阅、批发这类，都要等规则或他选。像借款的词（贷款、垫款、融资、押金、保证金）绝不算猜测，也绝不算收入。无论走规则、账户还是单行决定，都会留在“待你决定”，除非分类是借贷款项或不计入，或规则带 `not_a_loan: true`，或这一行在 `not_a_loan_lines` 里。只有他亲口说过才能这样写。这些行都列在第一张表的“借款决定”下。
- “对得上”只说明数字加起来相符，绝不说明分类是对的。说对得上时要一起说明。
- 你自己的判断放进 `suggestions`，不要放进 `rules`。建议只显示在那一行旁边，那一行仍然是未决定。只有他亲口说过的，才放进 `rules`。
- 没有规则时，这些一律留给他决定：取现、可能是私人的开支、明显是设备的用词、对不上他账户的转账、还贷款、没写原因的进账、在这份流水的消费里找不到完整对方名称的退款、可能重复的行。
- 达到他给的金额的每一笔，进或出，都在第一张表上：没有规则就等他决定，有规则就列为已答过。如果有读不出来或放在一边的行，那句话就不印，这些行单独列出。
- 自己账户之间的转账和借贷款项，不算收入，也不算支出。私人开支、大额购置、税费和政府缴费和支出分开放。退款放回原来消费的分类，并减少这个分类。
- 英文规则按整词匹配，所以 ATO 不会抓到 CURATOR。第一张表会列出每条规则抓到的每一行的文字和金额，短规则答了大部分流水时会警告。
- 自己的账户必须像账号或名字：“SAVER 4471”“储蓄账户6621”可以，“TFR”“SAVER”不行。
- 规则或账户必须真的指明一个对象：至少三个字符（中文两个），不能是日常词。抓到流水大部分行的会让运行以退出码 3 停下，请写得更准确。只有他确认确实是同一个对象时，才加 `broad_ok: true`。
- 绝不为了对上而调整数字。核对失败，就说清是哪一项、差多少。
- 不说什么能抵税、能报销或怎样省税，他问了也不说，告诉他由会计决定。分类名只是日常记账用词。
- 绝不编造任何一行、余额或分类。示例都是虚构的，并标明虚构。

## 信息不全和其他情况

- 谁优先：下拉选择或单行决定优先于规则，规则优先于猜测。重新运行是从流水和信息文件重建的，所以除非把 `carry_from` 设为之前的工作簿，否则下拉选择会丢。重新运行时一定要设。手工加的行带不过来，消息会写明有几行。
- 一行粘贴了两次：退出码 5，第二行会被标出，并写明余额第一次接不上的地方。要干净退出，就加 `"line_decisions": {"<原文行号>": "leftout"}`，指向第二行，行号在 `checks.json` 或「明细」表。也可以让他在工作簿里把那一行选成“不计入”，警告就会消失。如果银行真的扣了两次，就把它放进某个分类。不需要改流水。
- 少了一行：让他补在「明细」的空行里。期初加变动重新等于期末后，警告就会消失。
- 标题行不用管：逗号、制表符分隔或用空格对齐的列标题都不需要删。`ignore_lines` 只用于没有真实金额的行。被忽略的行如果带金额，会连金额列在第一张表上，流水也不能再算完整。
- 被丢掉、但带有可能是金额的数字的行，都会连文字列在第一张表上。带金额的行绝不会被当成页脚。
- 被截断的流水：只有印出的期初和期末余额对得上，或钱包自己写的记录数对得上，才能证明没少东西。你传的 `opening`、`closing` 只用来求和，标成“你填的”，绝不算印出的，也不能替换印出的。没有印出的余额时，结束语会说明没法证明完整，并写明原因。
- 表上的修改：工作簿里有一份隐藏的原样，用公式对比。改过的金额、日期、余额，后加的行，在表上选“不计入”的行，以及有借款用词却记在别处的行，都会改变结束语，并写明改了什么。金额和余额没设密码地锁上了，下拉、勾选列和空行仍能用。这不防篡改，要如实说。超出写明期间的行算失败。流水没写期间时，可以传 `period: {"from": "2026-08-01", "to": "2026-08-31"}`。
- `make.py` 退出码是 0，但 `check.mjs` 失败：当作没做完。把它的输出告诉他，不要当成做好了发出去。退出码 0 只说明文件写好了、数字能算；`check.mjs` 还会对照文件说的话。
- 信息太少：复述你拿到的内容，问缺什么，不要自己补。
- 没人能回答：用手上有的先跑，把每个缺口列成假设。未决定的行仍然未决定，所以结果会明说还没分完。
- 读不了的格式：`make.py` 以退出码 4 拒绝并说明原因。不要手工改他的数字来绕过，请他导出带日期、摘要、金额三列的 CSV。
- 两个账户或两种币种：每个一份工作簿。钱包里用银行卡付的钱，钱包账单和银行流水上可能都有，所以不要把两份工作簿加在一起。
- 时间长短：24 个月、5,000 行以内都可以，超过就拆开。
- 这个技能不需要任何网址或链接。

## 步骤

1. 把信息写成一个文件，比如临时文件夹里的 `brief.json`，格式照 `assets/samples/brief-zh.json`：
   `lang`、`business`、`currency`、`source`（文件路径）或 `text`（贴的内容）、`format`（auto、alipay 或 wechat）、`date_style`（dmy 或 mdy）、`year`（只在日期没写年份时给）、`asset_ask_from`、`own_accounts`、`rules` 和 `suggestions`（`{match, category}` 的列表，规则可加 `direction`：in 或 out）、`opening`、`closing`、`period`、`ignore_lines`、`line_decisions`、`checked_lines`（他确认过的原文行号）、`not_a_loan_lines`、`carry_from`、`assumptions`。只有每一行都是编的时才设 `fictional: true`：它会在所有地方印上虚构标记。真实流水绝不能设。
   可用的分类名（中英文都行）：待你决定、销售和服务收入、利息收入、其他收入、进货和材料、工资和外包、房租、水电燃气、通讯和网络、软件和订阅、广告推广、交通差旅、办公用品、保险、银行和平台手续费、会计和法律、其他支出、税费和政府缴费、私人开支、大额购置、自己账户之间转账、借贷款项、不计入（重复或没成交）。写错会让运行停下，并列出这份清单。
2. 运行 `python3 scripts/make.py brief.json 输出文件夹`。普通流水不到一分钟，3,000 行约两分钟。没有 XlsxWriter 时，它会装到临时文件夹。图片需要 Playwright：在临时文件夹里 `npm install playwright`，再把 `NODE_PATH` 设为那个 `node_modules`。没有它也会有 `overview.html`。
   退出码：0 文件写好了、数字能算；3 信息有误或规则太宽；4 读不可靠，所以没有工作簿，`message.txt` 会说明金额可能有错（照原样发）；5 文件写好了，但核对没对上；6 工作簿没通过自己的重算，不要发。
3. 运行 `node scripts/check.mjs 输出文件夹`。核对没对上、有行丢失、合计不是公式、没分完却看起来分完了，它都会报错。退出码 4 和 5 时它也会报错，这是对的：如实告诉他，不要绕过。
4. 除非用的是私密做法，否则要亲眼看 `overview.png` 和 `overview.html` 的每一部分，电脑和手机宽度都看，并把那句话和数字对一遍。
5. 把清单上的问题一次问几个，答案放进 `rules`，再跑一次。下个月用同一个文件，规则都还在。
6. 发工作簿、`overview.png` 和 `message.txt` 的文字。消息照原样用。还有没定的，先说这个。
7. 如果要证明报错确实有效，运行 `python3 scripts/test_no_false_finish.py`，在编造的数据上跑约 160 个情况，要几分钟。

## 公式怎么核对

`make.py` 会运行 `scripts/verify.py`。`formula_eval.py` 按文件里的公式文本算出每个公式，再由一段独立的 Python 对「明细」表求和，看合计应该是多少。然后试约 14 种改动（没有等决定的行时会少一些），比如改分类、把所有行都定下来、把真实的一行标成不计入、把期末余额改一分钱、贴一个不在列表里的分类、加一行。合计必须跟着变，第一张表的那句话也必须和数字一致。

这是技能自带的计算器，不是 Excel。要明确说这个文件没有在真正的 Excel 里打开过，图表和下拉在 Excel 里的样子也没人看过。

不要打开、用脚本控制或向 Excel、Numbers 等他可能开着的任何应用发命令，这可能卡死他的工作。

## 交付内容

- `流水分好类.xlsx`（英文版是 `statement-sorter.xlsx`）：要你决定、明细（有下拉）、分类汇总、月度汇总（带图表）、核对、怎么用。
- `overview.html` 和 `overview.png`：快速看的一页。
- `message.txt`：直接发的消息。
- `checks.json`：核对记录，只有行数和行号，没有流水文字。

## 交付前检查

- [ ] `make.py` 退出码是 0，`check.mjs` 通过。否则已经明确告诉他哪一项没对上、差多少。
- [ ] 原文每一行都有去向。读不出来的行是 0，或者每一行都已列给他看。
- [ ] 所有分类相加等于所有行；有余额时，期初加变动等于期末。没有余额时，已告诉他这一项没法核对。
- [ ] 每一行都标明待你决定、你说的或我们的猜测，并有原因，没有把建议当成决定。
- [ ] 已请他看一遍“我们的猜测”那些行，也说明了对得上只是数字相符。
- [ ] 用了规则时，第一张表上它逐行抓到的就是他的本意。
- [ ] 第一张表上的借款决定和放在一边的行，都念给他听过。
- [ ] 私人开支、大额购置、自己账户之间转账是分开的，转账不算收入和支出。
- [ ] 还有没定的，消息第一句和第一张表都写明了多少钱。核对失败时，写明了差额和余额第一次接不上的行。
- [ ] 没法证明流水完整时已告诉他，包括任何从某一行倒推的余额。
- [ ] 可能重复的行都标了，让他决定。
- [ ] 消息写明没有在真正的 Excel 里打开过，也没有上传任何内容。
- [ ] 没有任何地方说什么能抵税。
- [ ] 中文版是中文标签和正确币种。
- [ ] 用了支付宝或微信格式时，说明了它的限制。

## 不适用的情况

- 报税、审计账目。这里只分钱，钱意味着什么由会计决定。
- 扫描的 PDF 或照片：先拿到文字或 CSV 导出。
- 一份流水里有多种币种。别的币种的行算作读不出来。
- 未经本人同意的别人的流水。

## 运行要求

Python 3.9 或更新版本。XlsxWriter（BSD 许可证），由脚本装到临时文件夹。`check.mjs` 需要 Node。Playwright 可选，用来生成图片。各种格式试到什么程度见 `references/formats.md`，外观见 `references/style.md`，不要改样式。