把分散的账单整理清楚，逐步看清自己真正花了多少钱。
FlowLens 是一款在本机运行的多平台账单整理与收支分析工具。将微信、支付宝和银行账单放进同一本账本，你可以查看来源流水，对照原始字段或截图核验疑点，并持续追加、保存和导出。
项目希望解决的不只是“把金额加起来”：同一笔消费可能同时出现在银行卡和支付平台账单中，本人转账、退款、AA 回款和报销也会影响对个人支出的理解。整体设计是先提供有依据、可解释的结果，再让用户补充个人事实和调整分析口径。
当前版本：第二阶段首轮实现，已接入去重配对与真实流水页面。 本地规则整理有依据的重复记录，保留来源字段，支持纠正和撤销；仍不等同于个人生活支出。AI 调用路径已接入并通过模拟验证，真实服务与独立人工标注验收尚待完成。
当前已知局限：导入层和配对层仍依赖与特定银行／平台格式绑定的硬规则，鲁棒性较差。 现阶段对微信、支付宝、建行、中行及少数已知版式的支持，不能推导为对任意银行和任意账单格式的通用兼容；当表头、摘要、渠道词、时间精度或字段组合变化时，可能漏读、漏配或产生错误候选。项目正在审计并替换这套规则，方向是以格式指纹、字段语义、证据分组和必要的用户确认取代来源名称与单一样本假设。新体系尚未替换生产逻辑，因此当前结果仍需结合来源详情复核。
| 能力 | 状态 | 使用说明 |
|---|---|---|
| 多来源文件导入 | 已实现 | CSV、XLS/XLSX、文本 PDF、扫描 PDF、PNG/JPEG；兼容性取决于具体格式 |
| 本地 OCR | 已实现 | 扫描页和图片在本机识别，保留原始证据，疑点进入核验 |
| 账本与批次管理 | 已实现 | 新建、重命名、切换、逐批追加，删除至回收站后可恢复 |
| 导入进度与引导 | 已实现 | 展示处理阶段、文件计数和等待时间，首次使用引导可跳过 |
| 来源流水概览 | 已实现 | 日期范围、读取覆盖情况，按来源和币种分别汇总 |
| 明细查询 | 已实现 | 搜索、日期／来源／状态筛选和分页 |
| 读取核验 | 已实现 | 疑点字段高亮、保存后进入下一条、补录、排除、整页笔数检查 |
| 历史与撤销 | 已实现 | 原始底稿保留，人工修改追加保存，可撤销最近一次修改 |
| 本地持久化 | 已实现 | 重启后继续使用，追加导入不覆盖旧批次 |
| 有效流水导出 | 已实现 | JSON，区分完整导出与用户明确选择的部分导出 |
| 跨来源／跨批交易去重 | 首轮已实现 | 明确付款、合付关系，逐字段保留来源与备选值 |
| 退款关联 | 首轮已实现 | 保留两笔收付，明确退款可标为原付款未关联 |
| AI 辅助配对 | 已接通，待真实服务验收 | DeepSeek V4.1 Flash，受保护候选预览，用户点击开始 |
| 本人转账与费用回收归因 | 规划中 | 个人收支性质与实际承担留到后续 |
| AI 支出分类与趋势 | 规划中 | 理解商户、商品和上下文，支持用户纠正 |
| AA、代付、报销及个人生活费口径 | 规划中 | 根据用户补充的事实形成个性化分析 |
银行卡和微信记录同次付款时，来源明细仍保留两条底稿；真实流水页面在证据充分时只计一次。相同日期和金额本身不足以自动合并。
- Windows 64 位；本机验证环境为 Windows、Python 3.12 64 位及 Edge。
- 安装 Python 3.12 64 位，确认 Python Launcher（
py）可用。 - 使用支持现代 JavaScript 的浏览器。
- 首次安装依赖和准备 OCR 模型需要联网；账单导入与识别在本机进行。
默认使用 CPU，不要求配置 GPU。应用本身不需要 Node.js、单独安装数据库、云服务账号或外部 AI API Key。
GitHub 提供源码，不包含 Python 运行环境、已下载的 OCR 模型或任何个人账单。
使用 Git 下载，或在仓库页面选择 Code → Download ZIP 并解压。以下命令在 PowerShell 中执行：
git clone https://github.com/Tony-Liu217/FlowLens.git
cd FlowLens
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe scripts\prepare_ocr.py
.\.venv\Scripts\python.exe scripts\check_runtime.py使用 ZIP 时，先进入解压后包含 README.md、backend/ 和 start_flowlens.bat 的目录，再从创建虚拟环境开始执行。
这些命令直接使用虚拟环境中的 Python，无需激活环境或修改 PowerShell 执行策略。没有 py 命令时，可使用已安装的 Python 3.12 完整路径创建环境。
prepare_ocr.py 只初始化 OCR 模型，首次运行可能从 RapidOCR 配置的模型来源下载文件，不读取账单。模型保存在所选 Python 环境的 RapidOCR 模型目录中；更换或重建环境后，应重新执行这一步。
安装完成后，双击根目录的 start_flowlens.bat。启动器检查依赖并打开浏览器；使用期间请保留启动窗口。
也可以在 PowerShell 中启动：
.\.venv\Scripts\python.exe -B -X utf8 backend\run_app.py --open-browser应用只监听 127.0.0.1，默认选择可用端口。浏览器未自动打开时，复制启动窗口中的完整链接；链接带有本次启动的临时访问凭证，请勿分享。
关闭启动窗口，或在终端按 Ctrl+C，即可停止服务。下次启动后账本和核验历史仍保留。
启动器依次查找随附的 runtime/python.exe、项目 .venv/Scripts/python.exe、系统 python。从 GitHub 下载源码后应配置 .venv，不依赖旧版工程或开发者电脑上的环境。
- 新建账本：例如“年度日常收支”。同一期间的不同平台账单可以放在同一本账本中。
- 导入账单：选择或拖入文件。每批最多 20 个文件，合计不超过 50 MiB，后续可以继续追加批次。
- 查看概览：先了解哪些内容已读取、哪些记录或页面需要核验。可用部分可以先查看，失败和缺口单独保留。
- 核验疑点：点击“去读取核验”。荧光标记定位需要核对的原始字段和编辑项；标记不代表一定读错。整页截图默认收起，按需打开。
- 确认或修正：普通确认无需填写理由，默认保存后进入本批下一条，也可取消自动继续。补录、排除和整页核验需要依据；“修改历史与撤销”可撤销最近一次操作。
- 继续使用或导出：关闭后可继续追加与核验。所有读取缺口解决后才能完整导出；也可以明确选择仅导出可用部分，文件会保留缺口说明。
侧栏“删除”将整本及其批次移入回收站，可从“回收站”恢复。当前界面不永久清理数据，因此这一操作不会释放原账单数据占用的磁盘空间。
- 可用记录：关键字段已通过当前读取规则或人工核验，可供后续处理；不是“已经认定为消费”。
- 待核验记录／页面：存在关键字段、识别一致性或完整性疑点，可用部分仍可展示。
- 来源流水汇总：按来源、币种分别统计方向金额，保留交易状态。多来源可能重复记录同一事件，不能直接相加作为个人支出。
- 个人基础支出：尚未计算：这是尚未接入的分析能力，不是零支出。
- 余额仅供参考：余额单独存在 OCR 疑点时，不再强制逐条确认；关键金额、方向、日期和页面完整性仍需可靠证据。
当前规则对缺失或无法识别的币种仍默认人民币并显示提示；已识别外币分别保留、汇总，不自动换汇。导入外币账单时，请特别核对币种。
当前采用“通用文件读取 + 字段别名 + 部分来源结构规则 + 本地 OCR”。列顺序调整和已知别名通常可适应，但不是任意银行、任意排版都能自动理解。
导入层目前包含微信、支付宝、建行表格、中行表格和建行特定 PDF 等已知格式适配；配对层仍使用银行／平台渠道词、商户文本、时间窗口和一对一唯一性等首轮规则。这些规则可以支撑已覆盖样本，但对新银行、改版账单、字段缺失和一笔多来源记录的鲁棒性不足。相关规则正在重构，现有页面和统计不应被解释为通用准确率证明。
- 陌生表头、合并单元格、特殊收支编码或银行改版可能需要核验或新增映射。
- 未知格式中的无符号正金额不会无条件当作收入；已知来源可以使用明确的方向约定。
- 金额支持常见符号、全半角、合法千分位等表达，但不会猜测所有地区的数字写法。
- OCR 可能读错或漏行；识别分数和多图一致性不是准确率保证。没有荧光标记也不等于逐字段已人工确认。
- 当前尚无普适的账单总收入、总支出和笔数自动对账。“文件成功导入”不能代替与原账单核对。
- 不能读取的文件或页面会保留问题，不作为“零笔交易”正常结束。
详见 导入与核验边界。提交格式问题时，优先提供脱敏表头和最小示例，不要在公开 Issue 中上传完整真实账单。
默认数据目录为项目根目录下的 .local-data/workspace/，包含账本目录、各批次底稿、证据文件和核验历史。数据库使用 SQLite，不需要另行搭建服务。
备份时先关闭应用，再复制整个 .local-data/workspace/ 目录。仅复制某个 SQLite 文件，或仅导出有效流水 JSON，都不能完整恢复全部来源证据和历史。
可以指定独立的数据目录和固定端口：
.\.venv\Scripts\python.exe -B -X utf8 backend\run_app.py --data-dir "D:\FlowLensData" --port 8765 --open-browser同一数据目录不能同时启动多个服务。更新源码时保留数据目录；恢复时使用完整备份，不要把不同备份中的数据库和证据拼在一起。
应用保存原始字段和生成的证据，但目前不永久归档每一个上传原文件，请自行保留原始账单。导入和规则分析在本机运行。可选 AI 配对仅在点击开始后向 DeepSeek 发送预览中的受保护候选；密钥可在本机页面填写，仅存本次服务会话，也支持环境变量 DEEPSEEK_API_KEY。不设置总调用上限，支持取消。原文件和截图不外发。此版本面向本机使用，不适合直接暴露为公网服务。
双击后提示缺少运行环境或依赖？
确认 .venv 建在项目根目录，用该环境的 Python 安装 requirements.txt，再运行 scripts/check_runtime.py。不要只安装在另一个全局 Python 中。
CSV / Excel 可以读取，但扫描 PDF 或图片失败？
先在同一环境运行 scripts/prepare_ocr.py。OCR 工作进程禁止联网，不会在处理私人账单时临时下载模型；模型未准备好时会保留读取问题。
暂时不使用 OCR，可以只装基础依赖吗？
可以。创建 .venv 后安装 backend/requirements.txt，然后直接运行以下命令。扫描页和图片会保留为未解决的读取任务；默认双击启动器仍检查完整 OCR 环境。
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
.\.venv\Scripts\python.exe -B -X utf8 backend\run_app.py --no-ocr --open-browser为何导入完成了，但完整导出不可用？
任务完成表示已处理并保存这批文件，不表示所有内容都可靠读取。请检查记录、整页笔数及文件级异常，或明确选择部分导出。
重新读取同一个文件会替换原记录吗？
不会。默认拦截已导入的重复文件；启用“允许重新读取”后新增批次，两批都参与来源汇总。
能在 macOS / Linux 上运行吗？
Python 服务可从命令行启动，但当前完整启动器、浏览器交互和 OCR 组合主要在 Windows 上验证，尚未完成其他操作系统的完整验收。
| 阶段 | 交付目标 | 状态 |
|---|---|---|
| 第一阶段：可靠输入 | 导入、OCR、持久账本、读取核验、来源概览与导出 | 已实现，继续完善格式适配和体验 |
| 第二阶段：去重配对与真实流水 | 跨来源／跨批去重、退款配对、字段互补保留、隐私保护的 AI 辅助，支持纠正与撤销 | 首轮已实现，真实 AI 与独立标注验收待完成 |
| 第三阶段：AI 分类与生活收支透视 | 商户／商品理解、生活支出与借贷等特殊资金流区分、分类与趋势 | 规划中 |
| 第四阶段：个性化分析 | AA、代付、报销、专项资金和用户定义的生活费范围 | 规划中 |
后续会先让系统处理证据充分的情况，提供可用结果，再让用户处理真正需要个人背景的问题。规则负责精确计算和一致性约束，AI 负责语义理解与解释，用户保留纠正与定制权。
详细设计原则见 项目设计与路线图。
第二阶段按 2026-10-08 确认的范围推进，实施步骤、字段合并规则、AI 隐私机制及五来源验收基线见 第二阶段实施规划。
已实现范围、规则参数、实测结果及剩余限制见 首轮交付与验收。导入后进入侧栏“去重后流水”，可查看整理结果；配对核对和 AI 操作按需展开。
2026-10-09 更新：AI 输出截断修复与配对规则调整。AI 增加“先试 4 项”，明确关闭思考模式并在截断时拆小批次；本地规则支持金额日期相容、双向支付渠道明确且双方唯一的普通付款，不要求商户字面完全一致。该轮真实 AI 判断质量仍待本机密钥配置后的实测。
FlowLens/
├─ frontend/ 页面、样式、交互与品牌资源
├─ backend/
│ ├─ app/ 本机服务与接口
│ ├─ jiaowopay_ingest/ 读取、标准化和不可变底稿
│ ├─ jiaowopay_ocr/ 本地 OCR 与证据检查
│ ├─ jiaowopay_review/ 账本、修订、核验与有效记录
│ └─ tests/ 合成数据回归测试
├─ scripts/ 环境准备与验收脚本
├─ docs/ 产品路线、兼容性和接口说明
├─ requirements.txt 完整依赖入口
├─ start_flowlens.bat Windows 双击启动
└─ .local-data/ 私有运行数据，不纳入版本控制
前端为原生 HTML、CSS、JavaScript，由同一个 Python 服务提供，不需要执行前端构建。运行后端回归测试：
.\.venv\Scripts\python.exe -B -X utf8 -m unittest discover -s backend\tests -q合成浏览器验收、环境验证范围和贡献说明见 开发与验证；接口与数据语义见 接口约定。测试通过说明已覆盖的行为符合预期，不构成对所有银行账单的识别准确率承诺。
关于银行表头差异、附言补充、未知列提示和适用边界，见 来源字段完整性说明。
当前规则的适用边界、40 个规则族的审计和新证据／组级提案原型，见 规则鲁棒性全面审计与新体系。新原型尚未替换生产配对和统计。
项目沿用 MIT License。第三方依赖和模型遵循各自许可证；微信、支付宝等名称与标识仅用于来源识别，不代表官方关联或授权背书。