mcpField
R
receipt-ocr-sorter

receipt-ocr-sorter

github.com/aktsmm文档处理2654 次安装1 天前更新
代码仓库

关于 receipt-ocr-sorter

使用 Surya OCR 处理收据的技能，可提取信息、重命名文件、按项目归档并生成 Markdown 汇总，适用于整理费用凭证。支持 dry-run 和 CSV 日志。

主要功能

  1. 01识别图片、PDF、ZIP 和视频帧
  2. 02提取日期、金额、国家、卡片和分类
  3. 03规范文件名并按项目归档
  4. 04dry-run 模式与 CSV 日志
  5. 05生成金额及明细 Markdown 汇总

适用场景

  1. 01按项目整理文件夹中的收据
  2. 02根据提取的信息重命名差旅收据
  3. 03移动收据前预览文件变更
  4. 04按日期和国家汇总项目费用

安装

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

$npx skills add https://github.com/aktsmm/agent-skills --skill receipt-ocr-sorter

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE.txt
references/
d365-expense-guide.md
receipt_sorter.py
setup-guide.md

详细介绍

来自项目 README

Receipt OCR Sorter

OCR（Surya）を使った領収書の自動仕分け・リネーム・集計ツール。

When to Use

  • 領収書を仕分けて, レシートを整理して, receipt sorting
  • フォルダ内の領収書画像をプロジェクト単位で自動整理したい
  • 大量のレシート写真に日付・金額・用途でファイル名を付けたい
  • 出張経費の領収書を一括でリネーム＆集計したい

Core Workflow

  1. 入力フォルダの画像 / PDF / ZIP / 動画を受け取る
  2. OCR で日付・金額・国・カード・用途を抽出する
  3. 品質補正をかけて標準ファイル名へ正規化する
  4. プロジェクト単位で仕分ける
  5. Markdown サマリーを出す

Architecture

入力フォルダ（incoming/unassigned 等）
  │
  ├─ JPEG/PNG/PDF/ZIP → OCR → 抽出 → リネーム → PJフォルダへ移動
  ├─ MP4/MOV → ffmpeg → JPG → OCR → ...
  │
  ├─ カード不明 or テキスト不可 → 未分類フォルダ → 再仕分け可能
  │
  └─ 個人経費（D365対象外） → PJフォルダ/private/

private/ フォルダ: D365 に申請しない個人経費レシートを格納する。OCR後にユーザーが「個人経費」と判断した場合に移動する。

Naming Convention

YYYY-MM-DD-国コード-金額[-カード]-分類.ext

例:
  2026-02-09-jpn-14320-amex-shinkansen.jpeg
  2026-02-11-us-272-amex-hotel.jpeg
  2026-02-12-us-190.38-meal.jpeg        ← カードなし
  2026-02-09-us-6.80-amex-meal-starbucks.jpeg

国コード一覧、分類一覧、D365 カテゴリ対応、添付手順は references/d365-expense-guide.md を参照。

CLI Usage

# Dry-run（確認のみ、ファイル移動なし）
python receipt_sorter.py --project "202602_Domestic_Trip" --dry-run

# 本実行
python receipt_sorter.py --project "202602_Domestic_Trip" --input "incoming\unassigned"

# ログ指定
python receipt_sorter.py --project "202602_Domestic_Trip" --input "incoming\unassigned" --log "result.csv"
Options
オプション説明デフォルト
--project出力PJフォルダ名（必須）-
--input入力フォルダincoming/unassigned/
--dry-runファイル移動せず結果のみ表示false
--log結果CSVパス<PJフォルダ>/csv/<PJ名>_dryrun.csv or _result.csv

Markdown Summary Output

本実行後、PJフォルダに <PJ名>_summary.md が自動生成される。

含む内容:

  • プロジェクト合計（通貨混在・参考値）
  • 国コード別合計テーブル
  • 日付×国コード別合計テーブル
  • 全明細テーブル（日付・国・金額・カード・分類・日本語概要・ファイル名）

Intake Pattern

  • 未分類の生ファイルは、workspace root ではなく専用の intake folder に集約する
  • 例: incoming/unassigned/
  • 案件が確定しているファイルは、intake folder を経由せず project folder へ直接入れてよい
  • dry-run 用のコピーや検証入力は一時フォルダで扱い、完了後に削除する

Setup

→ references/setup-guide.md

Script Reference

→ references/receipt_sorter.py

D365 Expense Integration

OCR 後のファイルを D365 Expense に添付する運用はこの skill の重要ユースケースだが、カテゴリ表と添付手順は本体から分離する。

  • カテゴリ対応表
  • 添付 / 差し替え手順
  • 添付時の照合ルール
  • ブラウザ操作の注意

詳細は references/d365-expense-guide.md を参照。

Known Limitations

  • OCRの精度はSuryaモデルに依存（手書きや歪みが大きい領収書は誤読あり）
  • 金額は最大候補を採用するが、複数明細のあるレシートでは個別明細は取れない
  • 金額連結誤読: OCRが改行をまたいで数字を結合し巨大整数を返すことがある（例: 14520 + 300 → 14520300）。上限チェック（500万超は除外）で防御しているが、完全ではない
  • 動画は中間フレーム1枚のみ抽出（最適フレーム選択は未実装）
  • 日本語の漢字店名はスラッグ化時にASCII変換で落ちる（カタカナはローマ字化される）
  • Windows PIL ファイルロック: Image.open() がハンドルを保持し shutil.move() が WinError 32 で失敗する。with + img.copy() + リトライで対応済み

Done Criteria

  • OCR 抽出からリネームまで一貫して処理できる
  • 標準ファイル名でプロジェクト単位に仕分けできる
  • 未分類と private の扱いを説明できる
  • Markdown サマリーが出力される
  • D365 へ載せる場合は reference の照合ルールに従って添付できる

评论

支持 Markdown