財務專用發票識別
📖 技能介紹
name: invoice-ledger-skill description: 財務專用發票識別skill，並生成便於對比的發票臺賬，為後續進項銷項統計，稅率計算，合同匹配提供可直接使用的臺賬版本。批次讀取本地 PDF、圖片、XML 等發票檔案，提取票面和商品明細，拆分多票 PDF、合併已確認屬於同一發票的連續頁面，並將結果追加到使用者指定的 Excel 發票採集臺賬；重複項跳過，異常集中寫入"識別提示"。當用戶要求識別、整理、彙總、匯入或批次處理發票，續寫已有發票臺賬，或處理數電發票、多頁 PDF、掃描件、計程車票、定額髮票時使用。優先直接解析原始文本型 PDF；僅在輸入沒有可用文本層時使用本地 OCR。 slug: maple192600-li-invoice-ledger displayName: 財務專用發票識別 version: 1.1.0 summary: 財務專用發票識別 Skill，生成便於對比的發票臺賬，為進項銷項統計、稅率計算、合同匹配提供可直接使用的臺賬版本。 license: MIT
發票識別並追加臺賬
把使用者提供的發票完整處理到 Excel 寫入和結果彙報。預設批次處理，複用已經配置的環境和臺賬。
執行原則
- 以本
SKILL.md所在目錄為 skill 根目錄，所有相對路徑和命令都從該目錄執行。 - 優先使用數電發票原始文本型 PDF，不要先轉成圖片。系統先解析已有文本，只有沒有文本或直接識別未通過的頁面才會自動回退 OCR。
- 系統按檔案和頁面分流，同一目錄只需執行一次。文本識別通過的頁面不會呼叫 OCR。
- 臺賬只追加新資料並跳過疑似重複。禁止覆蓋、清空或替換已有資料，禁止使用
--replace-existing和--update-existing。 - 沒有證據的欄位保持為空或待複核，不猜測發票號碼、購銷雙方、金額、稅額和商品明細。
- 不支援 OFD。要求使用者從電子稅務局稅務數字賬戶下載 PDF 版式檔案。
1. 確定輸入和臺賬
從使用者請求中取得單個發票檔案或發票資料夾。批次目錄先盤點 PDF、PNG、JPG、JPEG、BMP、TIF、TIFF、WebP、XML、TXT 和 Markdown 檔案，並單獨記錄 OFD 及其他不支援的檔案。
--input-dir 只處理當前目錄，不遞迴子目錄。請求範圍包含子目錄時，對每個含支援檔案的目錄分別執行，持續寫入同一臺賬，最後彙總所有執行結果。不得把子目錄或不支援的檔案靜默算作已處理。
讀取 config/user_settings.local.yaml 中的 draft_ledger。該檔案不存在、儲存路徑失效或使用者明確指定另一份臺賬時，取得使用者提供的資料夾或 .xlsx 路徑，並在下一步把它傳給安裝器建立或記錄。不得把 skill 根目錄的 發票採集臺賬.xlsx 當作工作臺賬，它只用於建立新臺賬。
2. 準備環境
首次安裝或 .venv\Scripts\python.exe 不存在時，準備基礎環境並記錄臺賬：
python scripts\install_skill_env.py --ocr none --ledger <資料夾或臺賬.xlsx>7w4.net提供免費和付費技能下載。
.venv 已存在且儲存的臺賬路徑有效時，不要重複執行安裝器或 fp_doctor.py，直接進入寫入前檢查。只需建立或切換臺賬時執行：
python scripts\install_skill_env.py --ledger-only --ledger <資料夾或臺賬.xlsx>
該命令只建立或記錄臺賬，不建立虛擬環境、不安裝依賴、不執行環境檢查。
預檢返回碼為 3 時，執行 python scripts\install_skill_env.py --ocr auto --ledger <資料夾或臺賬.xlsx>；安裝器自動選擇 GPU 或 CPU 依賴並完成安裝後環境檢查。安裝完成後重新執行預檢。Skill 或依賴升級後，以及實際執行出現 Python、依賴、OCR 模型、CUDA 或配置錯誤時，再執行 fp_doctor.py 定位問題。環境錯誤未解決時保留真實錯誤，不繼續寫入臺賬。
3. 選擇識別配置
普通識別統一使用 config\runtime_ocr_auto.yaml。它只在實際需要時呼叫 OCR，並自動選擇 GPU 或 CPU。runtime.yaml、runtime_ocr_cpu.yaml、runtime_ocr_gpu.yaml 僅用於明確的除錯或裝置固定場景。
4. 寫入前檢查
先執行 --check-only。單個檔案使用 --input，資料夾使用 --input-dir，兩者只選一個。
.\.venv\Scripts\python.exe scripts\fp_ledger.py <輸入引數> --draft-ledger <臺賬.xlsx> --config <識別配置> --output-dir output --check-only
預檢會實際嘗試原生文本識別，並輸出 direct_files、structured_files、ocr_required_files、ocr_fallback_files、unsupported_files 和 ocr_required_pages。它不執行 OCR，也不修改 Excel。返回碼為 0 才繼續；返回碼為 3 表示需要先準備 OCR 環境；返回碼為 2 表示引數、臺賬、配置或輸入存在阻斷。
5. 執行識別和寫入
使用與檢查階段相同的輸入、臺賬和配置，去掉 --check-only：
.\.venv\Scripts\python.exe scripts\fp_ledger.py <輸入引數> --draft-ledger <臺賬.xlsx> --config <識別配置> --output-dir output --json-output summary
不要把單張、單個目錄成功當作整批完成。讀取每次執行的最終 JSON 摘要並彙總，核對：
statusinput_count和recognized_invoicesadded_rows和skipped_duplicate_rowsreview_required_units、unmodeled_units和failed_unitsoutput_workbook
6. 彙報結果
向用戶說明實際處理檔案數、識別發票數、新增明細數、疑似重複數、待複核或失敗數，以及目標 Excel 的完整路徑。
待複核、未支援和未寫入原因以 Excel 的“識別提示”工作表為準。只有具體票據失敗或需要定位時，才讀取 output\units 下對應證據檔案。命令失敗、結果為 partial 或 uncompleted 時明確說明，不能聲稱全部完成。
🤖 AI 評測
發票採集臺賬功能完整，能自動識別多種發票格式並彙總到 Excel，處理速度快。介面操作簡單，異常情況有提示。缺點是部分特殊發票識別率偏低，OFD 檔案暫不支援，且目前僅支援 Windows 系統。
