mcpField
R
receipt-compiler

receipt-compiler

github.com/moonlight-lupin文档处理11373 次安装1 天前更新
代码仓库

关于 receipt-compiler

Receipt Compiler 将手机拍摄的收据照片整理为 A4 报销 PDF，支持图像校正、OCR、排版和可选封面。适用于汇总报销收据；生成 PDF 前必须审核并确认数据，确认后会校验数据是否被修改。

主要功能

  1. 01校正收据照片并生成扫描效果
  2. 02通过 OCR 提取费用数据
  3. 03审核并确认提取的数据
  4. 04在 A4 页面排列收据并可编号
  5. 05生成可选的汇总封面

适用场景

  1. 01将收据照片整理成报销文件
  2. 02核对 OCR 提取的日期、商户和金额
  3. 03制作分页的 A4 收据材料

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/moonlight-lupin/agent-skills --skill receipt-compiler

安装后在 Claude Code 中输入/receipt-compiler确认已加载。

附带文件scripts/receipt_compiler.pytests/receipt_compiler_selftest.py

详细介绍

Receipt Compiler

概述

Receipt Compiler 可将一个文件夹中的手机拍摄收据照片转换为一份 A4 PDF，效果类似复印的报销材料：每张收据都会校正（透视变换、倾斜校正），转换为黑白“扫描件”效果，以统一的视觉比例排布在 A4 页面上并编号，还可选择在封面页汇总信息。

包含四个子命令，并强制执行确认关卡：

  1. scan — 校正每张照片、转换为扫描件效果并进行 OCR → manifest.json
  2. review — 打印提取出的费用表格
  3. confirm — 标记用户已批准，并绑定已审核的数据（摘要）
  4. pack — 生成 A4 PDF（运行前必须先执行 confirm）

适用场景

  • “把我的收据整理成一份报销用 PDF”
  • “用这些收据照片制作一份报销材料”
  • “校正这些收据并转成黑白，然后排在 A4 页面上”
  • 不适用于：使用平板扫描仪扫描，或处理发票 PDF（请使用 pdf 技能）。

前置条件

pip install opencv-python-headless pillow pillow-heif pytesseract reportlab numpy
# PyMuPDF is needed only to run the self-test (tests/), not the script itself

还需确保系统已安装 tesseract-ocr，且位于 PATH 中。使用 tesseract --version 检查。

工作流（Agent 必须遵守确认关卡）

步骤 1 — scan
python3 ~/.hermes/skills/productivity/receipt-compiler/scripts/receipt_compiler.py \
    scan <photos_dir> -o <workdir> [--mode bw|photo]

默认的 --mode bw 会生成用户要求的复印件效果。使用 --mode photo 可转换为灰度图。完成标准：清单文件已生成，且每张照片对应一个条目； 已设置 ocr_confidence 和 needs_review 标记。

步骤 2 — review + confirm（必须执行，用户参与）
python3 .../receipt_compiler.py review <workdir>
# ... apply any corrections to manifest.json, THEN re-run review so the user
# ... sees the corrected table ...
python3 .../receipt_compiler.py review <workdir>
# ... after the user approves the corrected table ...
python3 .../receipt_compiler.py confirm <workdir>

在聊天中向用户展示打印出的表格。询问：

  1. 提取出的日期、商家和金额是否正确？请修正 manifest.json 中的字段。
  2. 可选要求——每次都要询问，不要自行假设：
    • 是否需要封面页（包含报销人、报销期间和备注）
    • 是否需要为每张收据添加编号徽标
    • 是否需要为每张收据添加说明文字（日期 · 商家 · 金额）
    • 合计金额是否需要显示货币符号
  3. 排除项——是否需要移除任何收据（"include": false）？
  4. 封面上的用途／备注文本。

只有在用户批准后，才能运行 confirm <workdir>。该命令会设置 confirmed: true，并绑定批准时所审核字段的 review_digest。 在运行 confirm 后进行任何编辑（日期、金额、货币、是否纳入）都会导致 pack 拒绝运行，直到重新运行 confirm——这意味着要再次向用户展示修改后的表格。没有绕过标记。运行 confirm 之前，先将用户的修正应用到 manifest.json。

步骤 3 — pack
python3 .../receipt_compiler.py pack <workdir> -o claim.pdf \
    [--cover --number --captions] \
    --title "Expense Claim — <purpose>" --claimant "MH" --period "..." --notes "..."

完成标准：PDF 已生成，并在 JSON 输出中报告页数。 然后通过当前活动渠道将 PDF 作为文档／文件发送给用户。

排版规则（收据的排列方式）

  • A4 纵向，边距 15 mm，间距 5 mm。
  • 特别长的收据（宽高比 ≥ 2.2）每行排 3 张并占满行高； 普通收据每行排 2 张，高度上限为内容区高度的 52%（约占整页的 47%）。 按单元格进行缩放 （每张收据填满其单元格）；收据较少的行会使用更宽的单元格。
  • 每张图片都会按比例缩放——不变形、不裁切。
  • 收据会依次排到后续页面；30 张以上也能正常排版。
  • 长收据先于普通收据打印；如有需要，可通过清单调整顺序。

常见问题

  1. 跳过确认关卡 — 如果 confirmed: false、确认值不是布尔值，或确认后又进行了编辑（摘要校验），pack 会直接失败。 没有绕过标志；必须先向用户展示表格。
  2. 照片昏暗或有阴影 — 2/98 百分位拉伸可以处理大多数情况；如果 OCR 置信度低于 55，或未提取到金额，该条目会被标记为 needs_review；请将这些条目展示给用户。
  3. 透视校正失败 — 光面或起皱的收据可能无法生成干净的四边形；脚本会退回到对整个画面进行小角度倾斜校正。检查清单中的 method；如果收据明显需要裁剪，但方法为 deskew，请使用 PIL 手动修正裁剪，或接受当前取景。
  4. HEIC 照片 — iPhone 照片格式为 .heic；如果已安装 pillow-heif，它可以处理这些照片。如果未安装，请向用户索要 JPG 文件，或安装 pillow-heif。
  5. 多种货币 — 总额按货币分组（审核输出和封面页会为每种货币单独打印一行，不会计算合计）。为使报销申请更清晰，每个包只使用一种货币；切勿将有效金额归零或编辑有效金额来强行合并计算总额。
  6. 封面表格中的长描述 — 描述会在 70 个字符处截断；请保持封面备注简短，或将详细信息放入 notes。

验证清单

  • scan 已生成 manifest.json，且每张照片对应一个条目
  • 已向用户展示 review 表格；已将更正应用到清单
  • 每次都询问可选要求（封面／编号／说明文字）
  • 仅在用户批准后运行 confirm（绝不手动编辑 confirmed）
  • PDF 输出文件已生成，页数符合预期
  • 已将 PDF 发送给用户，并附上正确的输出路径

评论

支持 Markdown