reading-receipt

レシート・領収書・ふるさと納税受領証明書 画像読み取り

レシート・領収書・ふるさと納税受領証明書の画像を読み取り、構造化データとして返すスキル。

PDF ファイルの場合

ファイルが PDF（.pdf）の場合、画像 OCR の前にテキスト抽出を試みる。

1. shinkoku pdf extract-text --file-path <path> を実行する
2. 抽出テキストに必要な情報（金額・日付・店舗名等）が含まれていれば、テキストから構造化データを生成する
3. テキストが不十分（スキャン PDF 等）の場合は shinkoku pdf to-image --file-path <path> --output-dir <dir> で PNG に変換し、以下の画像読み取りフローに進む

画像読み取り方法

推奨: デュアル検証（並列2コンテキスト）

精度を高めるため、同じ画像を2つの独立したコンテキストで並列に読み取り、結果を照合する。

1. 2つの独立した読み取りを実行する: サブエージェントが使える環境では、2つのサブエージェントを並列で起動し、それぞれ独立に画像を読み取る。 各サブエージェントには以下の「基本ルール」と「出力フォーマット」をプロンプトとして渡し、画像ファイルパスを指定する。

2. 結果照合: 両方の読み取り結果から主要フィールド（金額等）を比較する。

3. 一致の場合: そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告する。

4. 不一致の場合: ユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:

   • 差異のあるフィールドを明示する
   • A を採用 / B を採用 / 手動入力 の3択を提示する

フォールバック（サブエージェント非対応の場合）

サブエージェントが利用できない環境では、以下の手順で読み取る:

1. 画像ファイルを直接 Read ツールで読み取る
2. 以下の「基本ルール」と「出力フォーマット」に従ってデータを抽出する
3. 抽出結果をユーザーに提示し、必ず目視確認を依頼する

⚠ デュアル検証が利用できないため、必ずユーザーに目視確認を依頼してください。

基本ルール

• 画像ファイルは Read ツールで読み取る（Claude Vision が自動的に画像を認識する）
• 金額は必ず int（円単位の整数）で返す。カンマや「円」は除去する
• 日付は YYYY-MM-DD 形式で返す
• 和暦は西暦に変換する（令和7年 → 2025、令和6年 → 2024、平成31年 → 2019）
• 読み取れないフィールドは UNKNOWN（文字列）または 0（金額）とする
• 複数ファイルを渡された場合は全て順に処理してまとめて返す

出力フォーマット

レシート・領収書の場合

画像を読み取り、以下の形式で返す:

---RECEIPT_DATA---
date: YYYY-MM-DD
vendor: 店舗名
total_amount: 金額（int）
tax_included: true/false
items:
  - name: 品目名
    amount: 金額（int）
    quantity: 数量（int）
---END---

ふるさと納税受領証明書の場合

画像を読み取り、以下の形式で返す:

---FURUSATO_RECEIPT_DATA---
municipality_name: 自治体名（市区町村名）
prefecture: 都道府県名
amount: 寄附金額（int）
date: YYYY-MM-DD
receipt_number: 受領証明書番号（記載がなければ UNKNOWN）
---END---

抽出のポイント

レシート・領収書

• 合計金額（税込）を最優先で抽出する
• 内税・外税の区別を確認する（「税込」「税抜」の記載）
• 品目は読み取れる範囲で抽出する（不明な場合は items を空にする）
• 店舗名はレシート上部のロゴや名称から抽出する
• 日付はレシート上の取引日を使用する（発行日ではなく）

ふるさと納税受領証明書

• 「寄附金受領証明書」というタイトルを確認する
• 自治体名は「○○市」「○○町」「○○村」等の正式名称を抽出する
• 都道府県名は自治体名の前に記載されていることが多い
• 寄附金額は「金額」「寄附金額」欄から抽出する
• 日付は寄附を受領した日（受領日）を使用する
• 受領証明書番号は「第○○号」等の記載から抽出する